@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/button/button.js

@@ -1,166 +1,220 @@
-import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
-import "../icons/arrow-right-icon.js";
+import { LitElement, html, nothing } from "lit";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import buttonsCSS from "./button.css.js";
+import { fontSize, fontWeight } from "../shared/token-scales.js";
+// the trailing arrow on bd-contact-button; an atom now, not a local registry
+import "../icons/arrow-icon.js";
+
+// "white" and "outline-white" are ButtonLink-only presets (no bd-button
+// equivalent) used on a solid-colour banner (e.g. cta-banner) where a
+// surface="dark" primary/tertiary button would still be too close in tone —
+// they render a plain white fill / white 2px outline regardless of surface.
+const VARIANTS = ["primary", "secondary", "tertiary", "ghost", "accent", "white", "outline-white"];
+
+/**
+ * Pre-ds-button kind values, mapped onto the variant that reproduces them, so
+ * existing markup keeps rendering the same thing.
+ */
+const LEGACY_KINDS = {
+  "outline"        : "ghost",       // dark 2px outline
+  "primary-outline": "tertiary",    // blue 2px outline
+  // red is this system's conversion colour, not a danger signal, so both of
+  // these earlier names described the wrong thing
+  "danger"         : "accent",
+  "destructive"    : "accent"
+};
+
+const SIZE_CLASS = { sm: "button--small", md: "button--medium", lg: "button--large" };
+const SURFACES = ["light", "dark"];
+const SHAPES = ["default", "rounded"];
+
+/**
+ * Everything bd-button and bd-button-link share.
+ *
+ * They differ only in the element they render, and that difference is
+ * semantic rather than visual: <button> performs an action in place, <a href>
+ * navigates. No CSS substitutes for it — only the link appears in a screen
+ * reader's list of links and offers open-in-new-tab, and only the button
+ * responds to Space as well as Enter.
+ */
+class BdButtonBase extends LitElement {
+  static styles = [buttonsCSS];
 
-const arrowIcon = html`
-  <bd-arrow-right-icon class="button__arrow" width="100%" height="100%" aria-hidden="true"></bd-arrow-right-icon>
-`;
-
-class Button extends LitElement {
   static properties = {
-    label      : { type: String },
-    href       : { type: String },
-    size       : { type: String },
-    customClass: { type: String },
-    kind       : { type: String },
-    fullWidth  : { type: Boolean },
-    strong     : { type: Boolean },
-    fontSize   : { type: String, attribute: "font-size" },
-    fontWeight : { type: String, attribute: "font-weight" },
-    align      : { type: String },
-    noArrow    : { type: Boolean, attribute: "no-arrow" },
-    shape      : { type: String, reflect: true }
+    label     : { type: String },
+    size      : { type: String },
+    variant   : { type: String, reflect: true },
+    /** @deprecated pass `variant`. kind meant four different things across the
+        atoms; on this one it always meant appearance. */
+    kind      : { type: String },
+    fullWidth : { type: Boolean, attribute: "fullwidth" },
+    strong    : { type: Boolean },
+    disabled  : { type: Boolean, reflect: true },
+    loading   : { type: Boolean, reflect: true },
+    fontSize  : { type: String, attribute: "font-size" },
+    fontWeight: { type: String, attribute: "font-weight" },
+    align     : { type: String },
+    surface   : { type: String, reflect: true },
+    /** "rounded" takes the pill corner; see .button--rounded. */
+    shape     : { type: String, reflect: true },
+    /** The accent variant reveals a trailing arrow on hover; this opts out. */
+    noArrow   : { type: Boolean, attribute: "no-arrow" },
+    /* A circle holding one icon instead of a label: the homepage's audience
+       cards and the mobile menu toggle. A mode, not a variant, because every
+       variant, size, surface and state applies to it unchanged -- which is how
+       the Button icon sets in the foundation Figma file are drawn. With no
+       visible text there is nothing to name the control, so label becomes
+       required rather than optional. */
+    iconOnly  : { type: Boolean, attribute: "icon-only", reflect: true }
   };
 
   constructor() {
     super();
-    this.label = "Buy now";
-    this.href = "";
+    // label is only an accessible name, never the visible text: defaulting it
+    // to a word like "Buy now" would override whatever the caller slotted
+    this.label = "";
     this.size = "md";
+    this.variant = "primary";
+    this.kind = "";
+    this.fullWidth = false;
+    this.strong = false;
+    this.disabled = false;
+    this.loading = false;
     this.fontSize = "";
     this.fontWeight = "";
     this.align = "left";
-    this.noArrow = false;
+    // "dark" retunes every variant for a hero or panel with a full background
+    // colour; see the SURFACE block in button.css.js
+    this.surface = "light";
     this.shape = "default";
+    this.noArrow = false;
+    this.iconOnly = false;
   }
 
-  _onFocusin(e) {
-    const el = e.currentTarget;
-    requestAnimationFrame(() =>
-      requestAnimationFrame(() => {
-        if (el.matches(':focus-visible')) {
-          this.setAttribute('data-bd-button-focus', '');
-        }
-      })
-    );
-  }
-
-  _onFocusout() {
-    this.removeAttribute('data-bd-button-focus');
-  }
-
-  _handleClick() {
-    this.dispatchEvent(new Event("custom-click"));
+  willUpdate(changed) {
+    if (changed.has("kind") && this.kind) this.variant = this.kind;
+    if (changed.has("variant") || changed.has("kind")) {
+      if (LEGACY_KINDS[this.variant]) this.variant = LEGACY_KINDS[this.variant];
+      if (!VARIANTS.includes(this.variant)) this.variant = "primary";
+    }
+    if (changed.has("size") && !SIZE_CLASS[this.size]) this.size = "md";
+    if (changed.has("surface") && !SURFACES.includes(this.surface)) this.surface = "light";
+    if (changed.has("shape") && !SHAPES.includes(this.shape)) this.shape = "default";
   }
 
-  get sizeClass() {
-    switch (this.size) {
-      case "lg":
-        return "button--large";
-      case "md":
-        return "button--medium";
-      case "sm":
-        return "button--small";
-      default:
-        return "";
-    }
+  get _inert() {
+    return this.disabled || this.loading;
   }
 
-  get kindClass() {
-    switch (this.kind) {
-      case "primary-outline":
-        return "button--primary--outline";
-      case "outline":
-        return "button--outline";
-      case "secondary":
-        return "button--secondary";
-      case "primary":
-        return "button--primary";
-      case "danger":
-        return "button--danger";
-      case "white":
-        return "button--white";
-      case "outline-white":
-        return "button--outline-white";
-      default:
-        return "";
-    }
+  /* The hover arrow belongs to the conversion CTA -- what "danger" meant before
+     it became accent -- and never to a control that cannot be pressed. */
+  get _hasArrow() {
+    // an icon-only circle has no label to slide aside
+    return this.variant === "accent" && !this.noArrow && !this._inert && !this.iconOnly;
   }
 
-  get shapeClass() {
-    return this.shape === "rounded" ? "button--rounded" : "";
+  get _classes() {
+    return [
+      "button",
+      `button--${this.variant}`,
+      SIZE_CLASS[this.size],
+      this.iconOnly ? "button--icon-only" : "",
+      // a circle stretched to the container is a pill, not this control
+      this.fullWidth && !this.iconOnly ? "max--width" : "",
+      this.strong ? "button--bold" : "",
+      // the circle is already the roundest shape there is
+      this.shape === "rounded" && !this.iconOnly ? "button--rounded" : "",
+      this._hasArrow ? "button--with-arrow" : "",
+      this.loading ? "button--loading" : ""
+    ].filter(Boolean).join(" ");
   }
 
-  get fullWidthClass() {
-    return this.fullWidth ? "max--width" : "";
+  /**
+   * font-size and font-weight are step names resolved to token references by
+   * shared/token-scales.js; anything off-scale is dropped.
+   */
+  get _inlineStyle() {
+    return [
+      ["font-size",   fontSize(this.fontSize)],
+      ["font-weight", fontWeight(this.fontWeight)]
+    ].filter(([, v]) => v).map(([p, v]) => `${p}: ${v};`)
+      .join(" ");
   }
 
-  get strongClass() {
-    return this.strong ? "button--bold" : "";
+  /** The spinner is decorative — aria-busy on the control carries the state. */
+  get _content() {
+    if (this.iconOnly) return this._iconContent;
+    return html`${this.loading
+      ? html`<span class="spinner" aria-hidden="true"></span>`
+      : nothing}<span class="button__label"><slot>${this.label}</slot></span>${this._hasArrow
+      ? html`<bd-arrow-icon class="button__arrow" aria-hidden="true"></bd-arrow-icon>`
+      : nothing}`;
   }
 
-  get hasArrow() {
-    return this.kind === "danger" && !this.noArrow;
+  /**
+   * One glyph, never a glyph and a spinner side by side: the circle holds a
+   * single item, so loading replaces the icon rather than joining it.
+   *
+   * The icon is a slot so any bd-*-icon can go in; with nothing slotted it is
+   * the arrow, the system's only true shafted arrow and the default the Figma
+   * sets draw. The button and icon scales share step names -- sm 16, md 20,
+   * lg 24 against padding 8, 12 and 16 -- so the size passes straight through
+   * and the circle comes out 32, 44 and 56.
+   */
+  get _iconContent() {
+    if (this.loading) return html`<span class="spinner" aria-hidden="true"></span>`;
+    return html`<slot><bd-arrow-icon size="${this.size}" aria-hidden="true"></bd-arrow-icon></slot>`;
   }
 
-  get arrowClass() {
-    return this.hasArrow ? "button--with-arrow" : "";
+  _handleClick(e) {
+    if (this._inert) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+    this.dispatchEvent(new Event("custom-click"));
   }
+}
 
+/** Performs an action in place. */
+class Button extends BdButtonBase {
   render() {
     return html`
       <button
+        type="button"
+        class="${this._classes}"
+        aria-label="${this.label || nothing}"
+        aria-busy="${this.loading ? "true" : nothing}"
+        ?disabled="${this.disabled}"
+        style="${this._inlineStyle}"
         @click=${this._handleClick}
-        @focusin=${this._onFocusin}
-        @focusout=${this._onFocusout}
-        class="button ${this.kindClass} ${this.sizeClass} ${this.shapeClass} ${this.fullWidthClass} ${this.strongClass} ${this.arrowClass}"
-        aria-label="${this.label}"
-        style="
-          ${this.fontSize ? `font-size: ${this.fontSize};` : ""}
-          ${this.fontWeight ? `font-weight: ${this.fontWeight};` : ""}
-        "
-      >
-        <span class="button__label"><slot></slot></span>
-        ${this.hasArrow ? arrowIcon : ""}
-      </button>
+      >${this._content}</button>
     `;
   }
 }
 
-class ButtonLink extends LitElement {
+/** Navigates. Looks identical; is not the same control. */
+class ButtonLink extends BdButtonBase {
   static properties = {
-    label      : { type: String },
-    href       : { type: String },
-    size       : { type: String },
-    customClass: { type: String },
-    kind       : { type: String },
-    fullWidth  : { type: Boolean, attribute: "fullwidth" },
-    strong     : { type: Boolean },
-    fontSize   : { type: String, attribute: "font-size" },
-    fontWeight : { type: String, attribute: "font-weight" },
-    buyLink    : { type: Boolean },
-    shadow     : { type: Boolean, reflect: true },
-    align      : { type: String },
-    noArrow    : { type: Boolean, attribute: "no-arrow" },
-    shape      : { type: String, reflect: true }
+    href   : { type: String },
+    buyLink: { type: Boolean },
+    /* The base class comment calls <a href> the element that navigates and
+       "offers open-in-new-tab" -- and until now the atom could not express
+       that, so a consumer needing a new tab had to hand-roll the anchor and
+       lost the button's focus ring, disabled state and typography with it. */
+    target : { type: String },
+    rel    : { type: String }
   };
 
   constructor() {
     super();
-    this.label = "Buy now";
     this.href = "";
-    this.size = "md";
-    this.kind = "primary";
-    this.fullWidth = false;
-    this.strong = false;
-    this.fontSize = "";
-    this.fontWeight = "";
     this.buyLink = false;
     this.shadow = true;
     this.align = "left";
-    this.noArrow = false;
-    this.shape = "default";
+    this.target = "";
+    this.rel = "";
   }
 
   _onFocusin(e) {
@@ -178,44 +232,6 @@ class ButtonLink extends LitElement {
     this.removeAttribute('data-bd-button-focus');
   }
 
-  get sizeClass() {
-    switch (this.size) {
-      case "lg":
-        return "button--large";
-      case "md":
-        return "button--medium";
-      case "sm":
-        return "button--small";
-      default:
-        return "";
-    }
-  }
-
-  get kindClass() {
-    switch (this.kind) {
-      case "primary-outline":
-        return "button--primary--outline";
-      case "outline":
-        return "button--outline";
-      case "secondary":
-        return "button--secondary";
-      case "primary":
-        return "button--primary";
-      case "danger":
-        return "button--danger";
-      case "white":
-        return "button--white";
-      case "outline-white":
-        return "button--outline-white";
-      default:
-        return "";
-    }
-  }
-
-  get shapeClass() {
-    return this.shape === "rounded" ? "button--rounded" : "";
-  }
-
   get fullWidthClass() {
     return this.fullWidth ? "max--width" : "";
   }
@@ -224,42 +240,47 @@ class ButtonLink extends LitElement {
     return this.strong ? "button--bold" : "";
   }
 
-  get hasArrow() {
-    return this.kind === "danger" && !this.noArrow;
-  }
-
-  get arrowClass() {
-    return this.hasArrow ? "button--with-arrow" : "";
+  /* Reverse tabnabbing is the reason rather than convention: a new tab opened
+     from here keeps a window.opener handle back unless rel says otherwise. An
+     explicit rel always wins, so a consumer can still opt out deliberately. */
+  get _rel() {
+    if (this.rel) return this.rel;
+    return this.target === "_blank" ? "noopener noreferrer" : "";
   }
 
   render() {
+    // A link has no native disabled state. Dropping the href stops it being a
+    // link at all, so the state is announced with aria-disabled and the role
+    // is restored explicitly; tabindex keeps it out of the tab order.
+    const href = this._inert || !this.href ? nothing : this.href;
+
     return html`
       <a
-        href="${this.href}"
-        class="button ${this.kindClass} ${this.sizeClass} ${this.shapeClass} ${this.fullWidthClass} ${this.strongClass} ${this.arrowClass}"
-        aria-label="${this.label}"
+        href="${href}"
+        target="${this.target || nothing}"
+        rel="${this._rel || nothing}"
+        role="${this._inert ? "link" : nothing}"
+        tabindex="${this._inert ? "-1" : nothing}"
+        class="${this._classes}"
+        aria-label="${this.label || nothing}"
+        aria-busy="${this.loading ? "true" : nothing}"
+        aria-disabled="${this.disabled ? "true" : nothing}"
+        style="${this._inlineStyle}"
         @click=${this._handleClick}
-        @focusin=${this._onFocusin}
-        @focusout=${this._onFocusout}
-        style="
-          ${this.fontSize ? `font-size: ${this.fontSize};` : ""}
-          ${this.fontWeight ? `font-weight: ${this.fontWeight};` : ""}
-        "
         ?data-store-render="${this.buyLink}"
         ?data-store-buy-link="${this.buyLink}"
-      >
-        <span class="button__label"><slot>${this.label}</slot></span>
-        ${this.hasArrow ? arrowIcon : ""}
-      </a>
+      >${this._content}</a>
     `;
   }
-
-  _handleClick() {
-    this.dispatchEvent(new Event("custom-click"));
-  }
 }
 
+/**
+ * A fixed "Contact us" CTA — a preset rather than a variant, with no size or
+ * kind axis. Its trailing arrow is bd-arrow-icon, an atom.
+ */
 class ContactButton extends LitElement {
+  static styles = [buttonsCSS];
+
   static properties = {
     label: { type: String },
     href : { type: String },
@@ -270,59 +291,30 @@ class ContactButton extends LitElement {
   constructor() {
     super();
     this.label = "Contact us";
-    this.href = "https://www.google.com";
+    this.href = "";
     this.align = "left";
     this.shape = "default";
   }
 
-  _onFocusin(e) {
-    const el = e.currentTarget;
-    requestAnimationFrame(() =>
-      requestAnimationFrame(() => {
-        if (el.matches(':focus-visible')) {
-          this.setAttribute('data-bd-button-focus', '');
-        }
-      })
-    );
-  }
-
-  _onFocusout() {
-    this.removeAttribute('data-bd-button-focus');
-  }
-
-  get shapeClass() {
-    return this.shape === "rounded" ? "button--rounded" : "";
+  _handleClick() {
+    this.dispatchEvent(new Event("custom-click"));
   }
 
   render() {
     return html`
-      <a 
-        class="button bd-contact-btn ${this.shapeClass}" 
-        href="${this.href}" 
-        aria-label="${this.label}"
+      <a
+        class="button bd-contact-btn ${this.shape === "rounded" ? "button--rounded" : ""}"
+        href="${this.href || nothing}"
+        aria-label="${this.label || nothing}"
         @click=${this._handleClick}
-        @focusin=${this._onFocusin}
-        @focusout=${this._onFocusout}
-        style="
-          ${this.fontSize ? `font-size: ${this.fontSize};` : ""}
-          ${this.fontWeight ? `font-weight: ${this.fontWeight};` : ""}
-        "
       >
         ${this.label}
-        <arrow-icon aria-hidden="true"></arrow-icon>
+        <bd-arrow-icon aria-hidden="true"></bd-arrow-icon>
       </a>
     `;
   }
-
-  _handleClick() {
-    this.dispatchEvent(new Event("custom-click"));
-  }
 }
 
-Button.styles = [tokens, buttonsCSS];
-ButtonLink.styles = [tokens, buttonsCSS];
-ContactButton.styles = [tokens, buttonsCSS];
-
 customElements.define("bd-button", Button);
 customElements.define("bd-button-link", ButtonLink);
 customElements.define("bd-contact-button", ContactButton);