V23/heading template vars - #1138
Draft
stephaniehobson wants to merge 1 commit into
Draft
Conversation
#668) Documentation-site only -- these are Fractal demo templates in components/*.html, not shipped in the npm package (AGENTS.md: 'docs/ exist for the documentation site, not the shipped package'). Consumers hand-write their own markup using the compiled classes; they don't call these render() functions, so this has zero impact on downstream projects. That's also why it needs no migration.md entry, unlike C1's actual CSS class renames. title -> heading title_el -> heading_el title_class -> heading_class Affects: Billboard, Callout, Card, Card Layout, Menu, Picto, Section Heading, Sticky Promo, Zap. Found and fixed a real, pre-existing bug as a side effect: Picto's config.yml already used `heading:` as its context key (has for a long time -- confirmed via git log), but picto.html's template still consumed `title`/`title_el`, so the config's example heading text was silently ignored and the Fractal preview rendered an empty heading. Renaming the template to match fixes it -- verified in the built docs output. Also updated prose in two component readmes (menu-item, sticky-promo) and one demo (form-header.html's 'Form Title' -> 'Form Heading') that directly described their own just-renamed heading elements by the old name. Left generic English usage of "title" alone elsewhere (e.g. the heading/heading-sizes readmes' 'a heading acts as a title for...', sidebar-menu's placeholder link text) -- that's not describing a renamed API surface. Explicitly out of scope, left for a separate follow-up (user decision): MzpModal.createModal() and MzpNotification.init() both take a real, shipped JS API option called `title` (assets/js/protocol/modal.js, notification-bar.js) that renders as heading text. That's a breaking public JS API change with real consumer impact, not a docs-only rename, so it doesn't belong bundled into this low-risk commit -- left modal.html, notification-bar--scripted.html, and their readmes untouched. Stacked on #1136 (v23/heading-classes). Part of #1084. Verified: npm run lint, npm test (47 specs, Firefox + Chrome), and npm run build-docs (523 items, no errors) -- confirmed in the built output that Picto, Card, Callout, Billboard, Section Heading, Zap, Menu, and Card Layout all render their heading content correctly.
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved markup, migration, changelog, and portability findings require fixes before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR standardizes Protocol v23 terminology from “title” to “heading” across component APIs, CSS classes, Sass, templates, examples, and menu behavior.
Changes:
- Renames component variables and CSS classes.
- Updates Sass, templates, examples, tests, and menu selectors.
- Adds heading styles and migration guidance.
Outstanding follow-ups include the Zap closing-tag default, template-variable migration guidance, a changelog entry, portable migration commands, and Sass documentation/style nits.
File summaries
| File | Summary |
|---|---|
tests/unit/menu.js |
Updates menu selectors in tests. |
docs/02-usage/migration.md |
Documents component rename commands and migration guidance. |
components/sticky-promo/sticky-promo.html |
Renames heading data and classes. |
components/sticky-promo/sticky-promo.config.yml |
Updates sticky promo context. |
components/sticky-promo/readme.md |
Updates heading terminology. |
components/sidebar-menu/sidebar-menu.html |
Renames sidebar heading classes. |
components/section-heading/section-heading.html |
Renames heading context data. |
components/section-heading/section-heading.config.yml |
Updates section heading context. |
components/picto/picto.html |
Renames heading parameters. |
components/newsletter/newsletter.html |
Renames newsletter heading classes. |
components/newsletter/newsletter--success.html |
Renames success heading class. |
components/newsletter/newsletter--errors.html |
Renames error heading class. |
components/navigation/03-menu-item/readme.md |
Updates menu item terminology. |
components/navigation/03-menu-item/menu-item.html |
Renames menu item heading class. |
components/navigation/02-menu/menu.html |
Updates menu and card contexts. |
components/menu-list/menu-list.html |
Renames menu list heading selector. |
components/layout/03-card-layout/card-layout.html |
Updates card contexts. |
components/layout/03-card-layout/04-card-layout--hero.html |
Updates hero card context. |
components/layout/03-card-layout/03-card-layout--quarter.html |
Updates quarter card context. |
components/layout/03-card-layout/02-card-layout--third.html |
Updates third-layout card context. |
components/forms/example-form/example-form.html |
Renames form heading classes. |
components/forms/12-form-header/form-header.html |
Updates form header terminology. |
components/forms/07-titles/titles.html |
Removes the old titles example. |
components/forms/07-titles/readme.md |
Removes old titles documentation. |
components/forms/07-headings/readme.md |
Adds headings documentation. |
components/forms/07-headings/headings.html |
Adds the headings example. |
components/card/readme.md |
Updates card terminology. |
components/card/card.html |
Renames card heading parameters and class. |
components/card/card.config.yml |
Updates card context values. |
components/callout/callout.html |
Renames callout heading parameters and class. |
components/callout/callout.config.yml |
Updates callout context values. |
components/callout/callout--example.html |
Renames the callout heading class. |
components/branding/zap/zap.html |
Renames Zap heading parameters. |
components/branding/zap/zap.config.yml |
Updates Zap context values. |
components/branding/zap/zap--all-styles.html |
Updates Zap examples. |
components/billboard/billboard.html |
Renames billboard heading parameters and classes. |
components/billboard/billboard.config.yml |
Updates billboard context. |
components/article/article.html |
Renames the article heading class. |
assets/sass/protocol/protocol.scss |
Switches to heading utilities. |
assets/sass/protocol/components/forms/_form.scss |
Renames form selectors. |
assets/sass/protocol/components/_sticky-promo.scss |
Renames sticky promo selectors. |
assets/sass/protocol/components/_sidebar-menu.scss |
Renames sidebar selectors. |
assets/sass/protocol/components/_newsletter-form.scss |
Renames newsletter selectors. |
assets/sass/protocol/components/_menu.scss |
Renames menu selectors. |
assets/sass/protocol/components/_menu-list.scss |
Renames menu list selectors. |
assets/sass/protocol/components/_menu-item.scss |
Renames menu item selectors. |
assets/sass/protocol/components/_card.scss |
Renames card selectors. |
assets/sass/protocol/components/_callout.scss |
Renames callout selectors. |
assets/sass/protocol/components/_billboard.scss |
Renames billboard selectors. |
assets/sass/protocol/components/_article.scss |
Renames article selectors. |
assets/sass/protocol/base/utilities/_headings.scss |
Updates heading utility documentation. |
assets/sass/protocol/base/elements/_headings.scss |
Adds base heading styles. |
assets/sass/protocol/base/_elements.scss |
Imports heading element styles. |
assets/js/protocol/menu.js |
Updates menu heading selectors. |
Review details
Suppressed comments (1)
components/card/card.html:9
- This renames a published component context key and its CSS class, which is a user-facing breaking change, but there is no corresponding entry in
CHANGELOG.md. The repository contribution convention inAGENTS.md:71requires user-facing framework changes to be recorded there; add the v23 migration note.
# heading - string
# heading_el - HTML heading element (h1, h2, h3, h4, h5, h6)
- Files reviewed: 23/23 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # heading - string | ||
| #} | ||
| <{{ title_el | default('h1') }} class="mzp-has-zap-{{ zap_number | default('1') }}">{{ title | safe }}</{{ title_el }}> | ||
| <{{ heading_el | default('h1') }} class="mzp-has-zap-{{ zap_number | default('1') }}">{{ heading | safe }}</{{ heading_el }}> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Describe what this change does.
CHANGELOG.md.Issue
Add a link to a related GitHub issue if applicable.
Testing
Enter helpful notes for whoever code reviews this change.