@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/header/header.js

@@ -1,23 +1,144 @@
 import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import "../button/button.js";
+import "../badge/badge.js";
+import "../icons/brand-signature-icon.js";
 import headerCSS from "../header/header.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 import "../heading/heading.js";
 import "../paragraph/paragraph.js";
 
 class Header extends LitElement {
   static properties = {
-    title         : { type: String },
-    subtitle      : { type: String },
-    description   : { type: String },
-    fullPrice     : { type: String },
-    discount      : { type: String },
-    finalPrice    : { type: String },
-    productId     : { type: String },
-    devices       : { type: String },
-    subscription  : { type: String },
-    shadow        : { type: Boolean, reflect: true },
-    dataLayerEvent: { type: String }
+    title            : { type: String },
+    subtitle         : { type: String },
+    description      : { type: String },
+    /* The outline level of the headline. `h1` by default, because that is what
+       a product hero is on the page it leads, and every current consumer wants
+       it -- so nothing has to change to keep the behaviour this component
+       already had.
+
+       It exists because the level is not this component's call. CLAUDE.md is
+       unambiguous: `as=` is the document outline and the composing page owns
+       it, `visual-level=` is the type role and the component owns that. This
+       component used to hardcode `as="h1"` and expose no way to say otherwise,
+       which took a page-level decision away from the page. Decided 2026-09-17:
+       the consuming dev team and the SEO team set the heading levels on this
+       section, so the component has to let them.
+
+       `visual-level="h1"` is PINNED in the template, deliberately, and that is
+       the half worth understanding. Passing a different level moves the
+       heading in the outline and changes nothing about how it looks: the hero
+       stays 48/700/1.25 at `heading-h1`, because the size is the design's and
+       only the level is the page's. Without the pin, `bd-h` follows `as` for
+       both, so `heading-level="h3"` would have quietly rendered the hero at
+       the h3 role instead -- measured 32px at 1024 and 24px at 320, against
+       48 and 30 -- an SEO decision repainting the design.
+
+       Anything that is not h1-h6 (or a bare 1-6) falls through bd-h's own
+       normalisation to h2 rather than h1: still a heading, never the page's.
+       That fallback is heading.js's, not repeated here. */
+    headingLevel     : { type: String, attribute: "heading-level" },
+    /* THE TWO CTA LABELS, and the secondary's destination. Props, not slots,
+       and they default to the strings this component has always rendered --
+       so no consumer changes and every consumer can now change them.
+
+       This is the half of the CTA question that was ours. The other half is
+       not: Header / v2 reads "Get Protection" and "Start your 30-day trial"
+       where these say "Buy now" and "View more plans", and which words sell a
+       subscription is purchase-funnel copy rather than a design-system value.
+       Until 2026-09-17 there was no way for the page to answer it even after
+       someone decided -- the strings were literals in this template. Now the
+       decision lands in markup, where copy belongs, and the default is only
+       what the component happened to ship.
+
+       PROPS RATHER THAN SLOTS, deliberately. A label is a plain string with no
+       markup in it, which is what `title` and `subtitle` already are; props
+       appear in schemas/component-manifest.json, which is the contract a page
+       generator is handed, and a slot does not. Adding both would give one
+       value two sources that can disagree -- the reason the three price props
+       were deleted rather than wired up.
+
+       THE SECONDARY CTA HAS NO DESTINATION UNTIL A PAGE GIVES IT ONE, and
+       that is not new: it never had one. bd-button-link drops the href
+       attribute entirely when href is empty, so the secondary has always
+       rendered an <a> with no href -- which is not focusable, is not a link in
+       the accessibility tree, and does nothing when clicked. The primary is
+       fine: `buyLink` makes the store inject the buy URL at runtime. So
+       cta-secondary-href is the fix for a dead control, not a nicety, and
+       there is no default because a URL is content this package cannot
+       invent. */
+    ctaLabel         : { type: String, attribute: "cta-label" },
+    ctaSecondaryLabel: { type: String, attribute: "cta-secondary-label" },
+    ctaSecondaryHref : { type: String, attribute: "cta-secondary-href" },
+    /* fullPrice, discount and finalPrice USED TO BE DECLARED HERE and are gone.
+       Nothing read them -- not this template, not this stylesheet, not the
+       store. The three price zones below are store-driven
+       (data-store-render with data-store-price / data-store-discount), and the
+       store computes the numbers from product-id, devices and subscription; it
+       never looks at a host property. So setting full-price="$159.99" did
+       exactly nothing, in every consumer, since the props were added.
+
+       Removed rather than wired up, and that is the decision worth recording.
+       Wiring them would give the same value two sources that can disagree --
+       the store's computed price and a hardcoded string -- with no answer to
+       which wins when both are present. The price belongs to the store; the
+       API for it is product-id plus devices plus subscription.
+
+       It matters more than a dead prop usually would because the manifest is
+       the contract a page generator is handed, and check-manifest.mjs's own
+       header says a stale entry is worse than a missing one: the model emits
+       props that do not exist. All three were listed there as if they worked.
+
+       The one consumer was packages/dex-system-design/index.html, Vite's dev
+       scratch page, which sets all three, loads no store, and has therefore
+       never displayed a price. It demonstrated the bug rather than a need, and
+       it is updated in the same commit. */
+    /* `product-id`, the spelling this component documents and the only one
+       anything writes. Lit derives an observed attribute by lowercasing the
+       property name rather than dash-casing it, so `productId` was listening
+       for `productid` while header.stories.js writes `product-id` in seven
+       places -- including its own usage example and its argTypes-driven
+       playground. The attribute was inert and the property stayed on its
+       "vsb" default: measured on Components/Header "Different Product IDs",
+       all three headers reported productId "vsb" while their markup asked for
+       "av", "ts" and "ps", so the same product was handed to <bd-product> for
+       every price lookup on the page.
+
+       Zero consumers of the working lowercase spelling: grepped `productid`
+       and `productId=` as an attribute across src, schemas and docs -- none,
+       and no `.productId=` property binding either. So naming the attribute
+       breaks nothing. Same root cause and same one-line repair as bd-grid's
+       cols-sm and bd-picture's fallback-src in P7H. */
+    productId        : { type: String, attribute: "product-id" },
+    devices          : { type: String },
+    subscription     : { type: String },
+    /* NOT styling, despite what this was documented as for a long time. It is
+       the store's opt-in for walking a shadow root.
+       @repobit/dex-store-elements' renders/index.ts selects shadow hosts with
+       SHADOW_HOST_SELECTOR = '[shadow], [data-bd-watch-shadow]', so an element
+       that does not reflect this attribute never has its shadow tree searched
+       for [data-store-render] or [data-store-hide] nodes -- and every price
+       zone in this component is inside the shadow root. Reflected and
+       defaulting to true for that reason, and load-bearing: drop it and the
+       prices silently stop rendering on a real page.
+
+       Nearly deleted as inert during the prop audit, because nothing in this
+       component or its stylesheet reads it. The consumer is another package. */
+    shadow           : { type: Boolean, reflect: true },
+    dataLayerEvent   : { type: String },
+    /* Whether the header-picture slot has anything in it. Internal state, not
+       an attribute: the consumer says this by slotting a picture or not, and a
+       second way to say it could only ever disagree with the first.
+
+       It exists because the scrim is only correct over an image. It is a
+       blue-950 band, and the NoImage story is a documented state -- rendering
+       the band there would paint a blue wash across the bottom of an empty
+       column, and the mark would sit on the page ground in text-inverse,
+       which is white on white. Nothing in CSS can ask whether a slot received
+       anything, so the slot is asked directly. */
+    _hasPicture      : { state: true }
   };
 
   constructor() {
@@ -25,17 +146,30 @@ class Header extends LitElement {
     this.title = "";
     this.subtitle = "";
     this.description = "";
+    this.headingLevel = "h1";
+    this.ctaLabel = "Buy now";
+    this.ctaSecondaryLabel = "View more plans";
+    this.ctaSecondaryHref = "";
     this.productId = "vsb";
     this.devices = "5";
     this.subscription = "1";
     this.shadow = true;
     this.dataLayerEvent = "info";
+    this._hasPicture = false;
   }
 
   // attributeChangedCallback(name, oldVal, newVal) {
   //   super.attributeChangedCallback(name, oldVal, newVal);
   // }
 
+  /* assignedElements rather than assignedNodes: a slot fed nothing but
+     whitespace from the consumer's markup still reports text nodes, and that
+     is not a picture. flatten so a picture arriving through another slot in a
+     composed tree still counts. */
+  _pictureSlotChanged(event) {
+    this._hasPicture = event.target.assignedElements({ flatten: true }).length > 0;
+  }
+
   render() {
     return html`
       <bd-context ignore-events-parent>
@@ -45,49 +179,141 @@ class Header extends LitElement {
           subscription="${this.subscription}" 
           data-layer-event="${this.dataLayerEvent}">
 
-        <div class="bd-container">
+        <div class="bd-ensemble bd-container">
           <div class="bd-header-left">
-            <bd-h as="h2" class="bd-product-name">${this.title}</bd-h>
-            <bd-h as="h4" class="bd-value-prop">${this.subtitle}</bd-h>
-            <bd-p kind="regular" class="bd-description">${this.description}</bd-p>
+            <!-- ONE HEADING HERE, AND THE EYEBROW IS NOT IT.
+
+                 What this replaces: the product name was as="h2" and the
+                 headline as="h4", so the outline ran h2 then h4 in that DOM
+                 order -- an eyebrow announced as a landmark, above the actual
+                 promise announced two levels below it. Every page rendering
+                 this header carried that.
+
+                 The headline is the page's main heading, so it is h1 --
+                 h1 by DEFAULT now rather than hardcoded, see headingLevel
+                 above. This component is the product hero and there is one per
+                 page, which is the condition an h1 needs, so h1 is the right
+                 default; the page can still say otherwise. bd-h's h1 role is
+                 5xl/bold/tight -- 48/700/1.25 -- which is Header / v2's
+                 value-prop exactly, which is why visual-level is pinned to h1
+                 and not left to follow as: the two agree at the default, and
+                 when a page separates them the design keeps the size.
+
+                 The product name is a kicker -- a label naming the product, and
+                 in Figma a plain text layer called product-name rather than a
+                 heading. So it is a <p>, out of the heading list entirely, and
+                 it resolves through the heading-h4 ROLE in header.css.js, which
+                 is where a role on a non-heading element belongs. A kicker in
+                 the outline is worse than no kicker in the outline: it adds a
+                 rung nobody navigates by and pushes the real heading down.
+
+                 THE ALTERNATIVE, and why not. The other accessible pattern is
+                 to put both inside the h1 -- <h1><span>Bitdefender Ultimate
+                 Security</span><span>Your Ultimate Digital Protection</span>
+                 </h1> -- which gives the heading an accessible name carrying
+                 the product as well as the promise. It was rejected on two
+                 counts: every heading list, skip link and rotor entry would
+                 then read the whole run, and it would mean rendering the h1
+                 here by hand instead of through bd-h, since the atom takes one
+                 slot. The product is named by the document title, the price
+                 block and the CTA; the heading does not have to carry it. -->
+            <p class="bd-product-name">${this.title}</p>
+            <bd-h
+              as="${this.headingLevel}"
+              visual-level="h1"
+              class="bd-value-prop">${this.subtitle}</bd-h>
+            <bd-p variant="regular" class="bd-description">${this.description}</bd-p>
 
             <div class="bd-price-zone-top" data-store-hide="!it.option.price.discounted">
-              <span class="bd-full-price" data-store-render data-store-price="full"></span>
-              <span class="bd-discount" data-store-render data-store-discount="percentage"></span>
+              <!-- font-weight="medium", the atom's own attribute rather than a
+                   declaration out in the stylesheet. Header / v2 sets the struck
+                   price at 16 Medium, and a weight on a bd-p HOST is inert --
+                   the atom sets all five type axes on its inner element -- so
+                   the only way in from outside is the attribute, which
+                   paragraph.js resolves through the weight scale and applies to
+                   that inner element. Measured before adding it: 400. -->
+              <bd-p variant="regular" font-weight="medium" class="original-price">
+                <s data-store-render data-store-price="full"></s>
+              </bd-p>
+              <!-- bd-badge, not the span this used to be. Header / v2 places the
+                   Badge component here at tone=success variant=fill size=lg, and
+                   the atom's own lg step is that spec exactly: 8/12 padding, the
+                   control-label size, a full radius. The span it replaces was a
+                   hand-rolled badge and a DIFFERENT one -- green-100 behind
+                   text/success, which is the atom's shade variant, at 16px
+                   semibold in a --radius-xl box. Its two "no role:" markers went
+                   with it: they existed to say "this should be a bd-badge", and
+                   the answer to that is a bd-badge. -->
+              <bd-badge
+                tone="success"
+                variant="fill"
+                size="lg"
+                class="bd-discount"
+                data-store-render
+                data-store-discount="percentage"
+              ></bd-badge>
             </div>
 
             <span class="bd-price-zone-final" data-store-render data-store-price="discounted||full"></span>
 
             <div class="bd-cta">
+              <!-- size="lg", and no font-size override. Header / v2 draws both
+                   CTAs at 16/32 padding with an 18px label in an 8px-radius box,
+                   and --button-large-* is that set exactly: spacing-16/32,
+                   fontSize-lg, radius-lg. These were size="md" (12/24, 16px,
+                   radius-md) with font-size="lg" bolted on top, so the label was
+                   the large step's and the box was the medium step's -- 18px type
+                   in a box padded for 16px type. Dropping the override puts the
+                   whole control back on one answer.
+
+                   THE LABELS come from cta-label and cta-secondary-label as of
+                   2026-09-17, defaulting to the strings this component always
+                   rendered. Which words sell a subscription is still not ours
+                   -- see the prop declarations above -- but the page can now
+                   act on the answer without editing this file.
+
+                   NO label ATTRIBUTE ON EITHER. On bd-button-link, label
+                   is the accessible name and the slot is the visible text, and
+                   these passed the same string to both -- so the anchor
+                   carried an aria-label duplicating its own content. Dropping
+                   it lets the accessible name come from the text, which is one
+                   source instead of two saying the same thing.
+
+                   The secondary's href is empty by default and the atom then
+                   renders an anchor with no href at all. Measured on
+                   Components/Header -> Design copy & a live secondary: it
+                   refuses focus and matches neither a[href] nor :enabled, so
+                   it is not focusable, not a link to a screen reader, and does
+                   nothing on click. It has been that way since it was written.
+                   Set cta-secondary-href.
+
+                   In Storybook the PRIMARY is inert too, for the same reason
+                   the price zones are empty there -- no store to inject an
+                   href. On a real page the store fills the primary in and
+                   never touches the secondary. -->
               <bd-button-link
-                label="Buy now"
-                kind="danger"
-                size="md"
+                variant="accent"
+                size="lg"
                 part="buy-button"
-                font-size="18px"
-                font-weight="600"
                 buyLink
-                >Buy now</bd-button-link
+                >${this.ctaLabel}</bd-button-link
               >
               <bd-button-link
-                label="View more plans"
-                kind="primary-outline"
-                size="md"
-                font-size="18px"
-                font-weight="600"
+                href="${this.ctaSecondaryHref}"
+                variant="tertiary"
+                size="lg"
+                >${this.ctaSecondaryLabel}</bd-button-link
               >
-                View more plans
-              </bd-button-link>
             </div>
 
-            <bd-p kind="small" class="bd-disclaimer-top">
+            <bd-p variant="xsmall" class="bd-disclaimer-top">
               <slot name="disclaimer-top">
                 Protection for 1 account & 5 PCs, Macs, tablets, or smartphones.
                 Windows® | macOS® | Android™ | iOS®
               </slot>
             </bd-p>
 
-            <bd-p kind="small" class="bd-disclaimer-bottom">
+            <bd-p variant="xsmall" class="bd-disclaimer-bottom">
               <slot name="disclaimer-bottom-text-start"></slot>
               <slot name="disclaimer-bottom-link"></slot>
               <slot name="disclaimer-bottom-text-end"></slot>
@@ -96,8 +322,15 @@ class Header extends LitElement {
 
           <div class="bd-header-right">
             <div class="bd-header-image-wrapper">
-              <slot name="header-picture"></slot>
-              <div class="bd-header-watermark"><span>Trusted. Always.</span></div>
+              <slot name="header-picture" @slotchange=${this._pictureSlotChanged}></slot>
+              ${this._hasPicture
+                ? html`
+                    <div class="bd-header-scrim" aria-hidden="true"></div>
+                    <bd-brand-signature-icon
+                      class="bd-header-signature"
+                    ></bd-brand-signature-icon>
+                  `
+                : null}
             </div>
           </div>
         </div>
@@ -108,6 +341,6 @@ class Header extends LitElement {
   }
 }
 
-Header.styles = [tokens, headerCSS];
+Header.styles = [ensembleCSS, headerCSS];
 
 customElements.define("bd-header", Header);