@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/switch/switch.stories.js

@@ -0,0 +1,86 @@
+import { html } from 'lit';
+import './switch.js';
+
+export default {
+  title     : 'Atoms/Switch',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdSwitch** turns something on or off, taking effect immediately. If the
+change only applies once a form is submitted, use \`<bd-checkbox>\` instead —
+that difference is the whole reason both exist.
+
+### Usage
+\`\`\`html
+<bd-switch label="Autopilot"></bd-switch>
+<bd-switch label="Scam alerts" checked></bd-switch>
+<bd-switch label="Unavailable" disabled></bd-switch>
+
+<bd-switch @bd-change=\${e => console.log(e.detail)}>Autopilot</bd-switch>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`checked\` | boolean, on or off | \`false\` |
+| \`disabled\` | boolean | \`false\` |
+| \`label\` | label text | \`''\` |
+| \`name\` | carried for your own use | \`''\` |
+
+Content can also come from the default slot, which renders after \`label\` — so
+set one or the other, not both.
+
+### Events
+\`bd-change\` — fires on toggle with \`detail\` set to the new boolean.
+
+### Accessibility
+It is a real \`<input type="checkbox">\` with \`role="switch"\`, inside a
+\`<label>\`, so it is keyboard-operable and announced as a switch with an on/off
+state rather than checked/unchecked.
+
+### Not form-associated
+The input lives in this element's shadow root, and a native input inside a
+shadow root does not participate in an outer \`<form>\`. **\`name\` is carried but
+nothing is submitted** — read the state from \`bd-change\` or the \`checked\`
+property.
+        `
+      }
+    }
+  },
+  argTypes: {
+    checked: {
+      control    : 'boolean',
+      description: 'On or off. Takes effect immediately, which is what separates a switch from a checkbox.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: "false" }, category: 'State' }
+    },
+    disabled: {
+      control    : 'boolean',
+      description: 'Blocks interaction.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: "false" }, category: 'State' }
+    },
+    label: {
+      control    : 'text',
+      description: 'Label text, rendered before any slotted content.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    },
+    name: {
+      control    : 'text',
+      description: 'Carried for your own use. NOT submitted with a form — see the notes.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Data' }
+    }
+  }
+};
+
+export const Default = () => html`
+    <bd-switch label="Automatic updates"></bd-switch>
+  `;
+
+export const Checked = () => html`
+    <bd-switch checked label="Real-time protection"></bd-switch>
+  `;
+
+export const Disabled = () => html`
+    <bd-switch disabled label="Unavailable on this plan"></bd-switch>
+  `;

package/src/components/tab-list/content-switcher.stories.js

@@ -0,0 +1,189 @@
+import { html } from "lit";
+import "./tab-list.js";
+import { contentSwitcherCSS, tabListCSS } from "./tab-list.css.js";
+
+/**
+ * The Content Switcher is `bd-tab-list` wearing `appearance="switcher"`, so it
+ * renders into light DOM like the strip does and needs both sheets in scope —
+ * see the note in tab-list.js. Inside a real component you add them to that
+ * component's own `static styles` instead of doing this.
+ */
+const withStyles = template => html`
+  <style>${tabListCSS.cssText}${contentSwitcherCSS.cssText}</style>
+  <div style="font-family: var(--typography-fontFamily-sans);">${template}</div>
+`;
+
+export default {
+  title     : "Components/Content Switcher",
+  tags      : ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**The Content Switcher** is a pill track of mutually exclusive options with the
+selected one on a white pill. Designed in Figma as *Content switcher*
+(node \`311:931\`).
+
+### It is an appearance, not its own element
+
+It is \`<bd-tab-list appearance="switcher">\`. Everything underneath —
+\`role="tablist"\`, \`role="tab"\`, \`aria-selected\`, the roving \`tabindex\` and the
+Arrow/Home/End pattern with automatic activation — is the same control the
+underlined strip uses, so a second element would have meant a second copy of
+that keyboard pattern to keep in step. CLAUDE.md's own rule: *when two
+components implement the same visual role, prefer extracting the role over
+spelling it twice.*
+
+### Both options are as wide as the longer label
+
+This is the part the design is built around: a translation cannot make one
+option wider than the other, because every option is as wide as the **longest**
+label.
+
+**CSS alone cannot express that**, and the two obvious declarations were both
+tried and measured on the *Unequal labels* story below:
+
+| | result |
+|---|---|
+| \`grid-auto-columns: 1fr\` | 127.21px and 141.79px — unequal, and both narrower than their content, so the labels wrapped to four lines |
+| \`grid-auto-columns: minmax(max-content, 1fr)\` | 78.35px and 248.77px — no wrapping, still unequal |
+
+An \`fr\` track needs definite free space to equalise and a shrink-to-fit
+container has none; once the width *is* definite, \`fr\` splits it evenly rather
+than matching the widest. Hug, equal, and equal-to-the-widest cannot all come
+from one grid declaration.
+
+So the width is measured. \`_sizeSwitcherOptions\` in tab-list.js reads the
+widest option after each render and publishes it as
+\`--bd-switcher-option-width\`, which \`grid-auto-columns\` consumes; it clears
+the property before measuring, so the track can shrink again when labels get
+shorter, and it re-measures once \`document.fonts.ready\` settles, because a
+width measured on a fallback face does not match IBM Plex.
+
+Figma cannot express it either: in the file one option hugs and the other is
+fixed at the same width, which is equal at this text and stops being equal as
+soon as a label changes length. The code carries the rule; the file carries a
+snapshot of it.
+
+### Usage
+
+\`\`\`js
+import "@repobit/dex-system-design/tab-list";
+import { tabListCSS, contentSwitcherCSS } from "@repobit/dex-system-design/tab-list-css";
+
+static styles = [tabListCSS, contentSwitcherCSS, myComponentCSS];
+\`\`\`
+
+\`\`\`js
+html\`
+  <bd-tab-list
+    appearance="switcher"
+    label="Plan type"
+    .tabs=\${[{ label: "Individual" }, { label: "Family" }]}
+    .selected=\${0}
+    @bd-tab-select=\${e => (this.plan = e.detail.index)}
+  ></bd-tab-list>
+\`
+\`\`\`
+
+### Accessibility
+
+\`label\` becomes the \`aria-label\` on the \`tablist\` and is not optional in
+practice — without it a screen reader announces a tab list with no name. The
+selected option is the only one in the tab order; arrow keys move between them
+and select in one step.
+
+The unselected label is white on \`--color-action-primary\`, which measures
+**4.53:1** — it passes the 4.5:1 minimum for 16px/500 text with very little to
+spare. CLAUDE.md names blue-500 as the step with no headroom, so if this track
+ever needs to sit on a tint, re-measure before assuming it still passes.
+        `
+      }
+    }
+  }
+};
+
+const switcher = (tabs, selected = 0, label = "Plan type") => withStyles(html`
+  <bd-tab-list
+    appearance="switcher"
+    label=${label}
+    .tabs=${tabs}
+    .selected=${selected}
+  ></bd-tab-list>
+`);
+
+export const Default = {
+  name      : "Default",
+  render    : () => switcher([{ label: "Individual" }, { label: "Family" }], 0),
+  parameters: {
+    docs: { description: { story: "The design as drawn: the first option selected." } }
+  }
+};
+
+export const SecondSelected = {
+  name      : "Second selected",
+  render    : () => switcher([{ label: "Individual" }, { label: "Family" }], 1),
+  parameters: {
+    docs: {
+      description: {
+        story: "The other variant in the Figma set. Only the pill and the ink move — "
+          + "both labels stay at the action-label weight, so nothing reflows on switch."
+      }
+    }
+  }
+};
+
+export const UnequalLabels = {
+  name      : "Unequal labels",
+  render    : () => switcher([{ label: "One" }, { label: "A considerably longer label" }], 0),
+  parameters: {
+    docs: {
+      description: {
+        story: "The equal-width rule under load. \"One\" is far shorter than its "
+          + "sibling and still occupies exactly the same width, which is what makes "
+          + "the control safe to translate. Measure both options in this story rather "
+          + "than the one above — in Default the two labels are close enough that a "
+          + "plain flex row would look almost the same."
+      }
+    }
+  }
+};
+
+export const ThreeOptions = {
+  name      : "Three options",
+  render    : () => switcher([{ label: "Monthly" }, { label: "Yearly" }, { label: "Lifetime" }], 1),
+  parameters: {
+    docs: {
+      description: {
+        story: "Nothing in the control assumes two. The Figma component is drawn with "
+          + "two because that is what pricing needs; the grid adds a column per option "
+          + "and they all stay equal."
+      }
+    }
+  }
+};
+
+export const LongestLabelDrivesBoth = {
+  name  : "In a narrow container",
+  render: () => withStyles(html`
+    <div style="width: 320px; outline: 1px dashed var(--color-border-subtle); padding: var(--spacing-16);">
+      <bd-tab-list
+        appearance="switcher"
+        label="Plan type"
+        .tabs=${[{ label: "Individual" }, { label: "Family" }]}
+        .selected=${0}
+      ></bd-tab-list>
+    </div>
+  `),
+  parameters: {
+    docs: {
+      description: {
+        story: "The track hugs its content rather than filling its parent, so it does "
+          + "not stretch in a wide column. At 320px both options plus the track "
+          + "padding still fit — measured, the pair comes to 256px — which is why the "
+          + "switcher holds its 12/24 option padding below `sm` instead of taking the "
+          + "strip's narrower step."
+      }
+    }
+  }
+};

package/src/components/tab-list/tab-list.css.js

@@ -0,0 +1,250 @@
+import { css, unsafeCSS } from "lit";
+/* unsafeCSS is how a Lit css`` template accepts a computed string. The
+   value is not arbitrary: below() resolves a name from the closed
+   breakpoint set and throws on anything else, so the only strings that
+   reach here are the ones the scale produced. */
+import { below } from "../shared/token-scales.js";
+
+/**
+ * Base styling for <bd-tab-list>.
+ *
+ * The element renders into light DOM (see tab-list.js), so this sheet is not
+ * applied automatically — a consumer adds it to its own `static styles` ahead
+ * of its overrides:
+ *
+ *   static styles = [tabListCSS, myComponentCSS];
+ *
+ * Everything that varies between the sections that use a tab strip is a custom
+ * property, so an override is a token change rather than a re-declaration of
+ * the whole button.
+ */
+export const tabListCSS = css`
+  /* The element is a pass-through wrapper: the strip itself stays the flex/grid
+     item it was before the extraction, so surrounding layout is unaffected. */
+  bd-tab-list {
+    display: contents;
+  }
+
+  .bd-tabs-container {
+    display: inline-flex;
+    justify-content: center;
+    flex-wrap: wrap;
+    border-bottom: var(--border-width-1) solid var(--bd-tab-border-color, var(--color-border-container));
+  }
+
+  .bd-tab-button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--bd-tab-gap, var(--spacing-8));
+    background: none;
+    border: none;
+    padding: var(--bd-tab-padding, var(--spacing-10) var(--spacing-16));
+    cursor: pointer;
+    position: relative;
+    color: var(--bd-tab-color, var(--color-text-brand));
+    font-family: var(--typography-fontFamily-sans);
+    /* body-regular, the same role bd-anchor-nav's and bd-page-switcher's items
+       resolve through.
+
+       This was body-large at semibold -- 18px/600 -- with no leading declared
+       at all, on the argument that a tab's type is a control's rather than a
+       text role's. The wayfinding family review settled it the other way: all
+       three of these components are labels with an action attached, they mark
+       the current one the same way, and there was no reason for one of them to
+       be a size and a weight apart. At 16/1.5 the tab box is 10 + 24 + 10, so
+       all three now measure 44px.
+
+       The leading is declared either way, and that part was a defect on its
+       own. An 18px label sat on IBM Plex Sans's own metric while the nav bars
+       beside it sat on a declared 24px -- and a leading nobody declares is the
+       blind spot neither gate can see: lint:tokens needs a DECLARED value to
+       report, and verify:typography only fails on multi-line text, which a
+       single-line tab label never is. */
+    font-size: var(--bd-tab-font-size, var(--typography-body-regular-fontSize));
+    line-height: var(--bd-tab-line-height, var(--typography-body-regular-lineHeight));
+    font-weight: var(--bd-tab-font-weight, var(--typography-body-regular-fontWeight));
+    transition: color var(--transition-duration-fast) var(--transition-easing-smooth);
+  }
+
+  .bd-tab-button::after {
+    content: "";
+    height: var(--bd-tab-underline-height, var(--indicator-underline-height));
+    background: var(--bd-tab-underline-color, var(--indicator-color));
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    width: 0;
+    transition: width var(--bd-tab-underline-duration, var(--indicator-underline-duration))
+      var(--indicator-underline-easing);
+  }
+
+  /* The transition two rules up had nothing to animate on pointer: this sheet
+     declared a colour transition and then no :hover rule anywhere, so a tab
+     was the one control in the package that gave no feedback under the
+     cursor.
+
+     action/primary-active is the step this system already uses for an
+     interactive element under the pointer -- bd-link's :hover and the anchor
+     nav's engaged dropdown option both resolve to it -- and it is a step
+     darker than the resting --color-text-brand, so the change is visible
+     without becoming the selected ink. Excluding .bd-selected keeps the
+     selected tab's text/primary from moving under the cursor. */
+  .bd-tab-button:hover:not(.bd-selected) {
+    color: var(--color-action-primary-active);
+  }
+
+  .bd-tab-button.bd-selected::after {
+    width: 100%;
+  }
+
+  .bd-tab-button.bd-selected {
+    color: var(--bd-tab-color-selected, var(--color-text-primary));
+    /* no role: the weight that marks the current item -- a state or modifier
+       weight, not a text-content type. See button.css.js's .button--bold for
+       the argument, and bd-link's .bd-link--active, which is the same 700 on
+       the same job in the other two components of this family. The tab used to
+       carry semibold at rest AND selected, so its weight said nothing about
+       which item you were on -- colour and the indicator carried it alone. */
+    font-weight: var(--bd-tab-font-weight-selected, var(--typography-fontWeight-bold));
+  }
+
+  .bd-tab-button:focus-visible {
+    /* the one focus ring — see Foundations/Focus */
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
+  }
+
+  /* Icon sizing is deliberately not defaulted here: the two sections that use
+     icons size them differently and neither value has a dimension token, so
+     each keeps its own rule rather than this atom inventing a size. */
+
+  .bd-tab-label {
+    pointer-events: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .bd-tab-button,
+    .bd-tab-button::after {
+      transition: none;
+    }
+  }
+
+  /* Narrower than sm. A media condition cannot read a custom property, so
+     below() interpolates the value; 600px was on no scale at all, and the
+     576px that replaced it still matched at exactly 576px, where sm begins. */
+  @media ${unsafeCSS(below('sm'))} {
+    .bd-tabs-container {
+      gap: var(--spacing-4);
+    }
+
+    .bd-tab-button {
+      padding: var(--bd-tab-padding-mobile, var(--spacing-8) var(--spacing-12));
+    }
+  }
+`;
+
+
+/* ---- appearance="switcher": the Content Switcher --------------------------
+   Figma: Content switcher, node 311:931. Every value below is the one the
+   component carries there, and the geometry reconciles: label 24 tall + 12/24
+   padding = a 48px option, + 4px track padding top and bottom = 56, which is
+   the frame height. "Individual" at 16/500 measures 75, + 24 + 24 = the 123px
+   option, and 4 + 123 + 4 + 123 + 4 = the 258px track.
+
+   THE EQUAL-WIDTH RULE IS THE POINT, and CSS expresses it where Figma cannot.
+   The design asks for both options to be as wide as the LONGER label so a
+   translation cannot make one tab bigger than the other. In the file one
+   option HUGs and the other is FIXED at the same width, which is equal at this
+   text and stops being equal the moment a label changes length. An auto-sized
+   inline grid whose columns are 1fr sizes every column to the widest column's
+   max-content, so the track still hugs its content AND the two options stay
+   identical -- which is the stated intent rather than a snapshot of it.
+
+   The selected option is marked by the white pill alone. The base sheet moves
+   the selected tab to bold, and that is right for an underlined strip where
+   weight and the indicator carry the state together; here the fill carries it,
+   so both weights stay at the action-label step and the label does not reflow
+   when you switch. That is also why every override here goes through the
+   --bd-tab-* custom properties the base sheet exposes rather than
+   re-declaring the button. */
+export const contentSwitcherCSS = css`
+  .bd-tabs-container--switcher {
+    display: inline-grid;
+    grid-auto-flow: column;
+    /* minmax(max-content, 1fr), NOT 1fr. Measured on the Unequal labels story:
+       a bare 1fr gave 127.21px and 141.79px -- two unequal columns, both
+       narrower than their content, so the labels wrapped to four lines. An fr
+       track under a shrink-to-fit container does not equalise to the widest
+       sibling, which is the assumption that was wrong.
+       .
+       minmax(max-content, 1fr) was the next attempt and gave 78.35 and 248.77
+       -- each column at its own max-content, still unequal. Once the width IS
+       definite an fr track splits it evenly instead, which is a different
+       wrong answer. There is no grid declaration that gives all three of hug,
+       equal, and equal-to-the-widest.
+       .
+       So the width arrives measured: _sizeSwitcherOptions in tab-list.js
+       publishes the widest option's width and this reads it. max-content is
+       the fallback for the frame before the first measurement, which is also
+       what keeps the geometry right if the property is ever absent -- and it
+       is a component-local property, the one place CLAUDE.md allows a
+       fallback. */
+    grid-auto-columns: var(--bd-switcher-option-width, max-content);
+    gap: var(--spacing-4);
+    padding: var(--spacing-4);
+    border-bottom: none;
+    border-radius: var(--radius-full);
+    background: var(--color-action-primary);
+  }
+
+  .bd-tabs-container--switcher .bd-tab-button {
+    /* the action-label step, which is what a button's label carries */
+    --bd-tab-font-weight: var(--typography-control-label-large-fontWeight);
+    --bd-tab-font-weight-selected: var(--typography-control-label-large-fontWeight);
+    --bd-tab-color: var(--color-text-inverse);
+    --bd-tab-color-selected: var(--color-text-primary);
+    --bd-tab-padding: var(--spacing-12) var(--spacing-24);
+    /* held at the same padding below sm: the base sheet drops to 8/12 there,
+       which would take the pill off the 48px option the design specifies, and
+       two 123px options plus the track padding still fit a 375px viewport. */
+    --bd-tab-padding-mobile: var(--spacing-12) var(--spacing-24);
+    border-radius: var(--radius-full);
+    /* An option is a control label, so it is one line by definition. The base
+       sheet lets a tab wrap, which is right for a strip that reflows; here a
+       wrap would break the pill geometry the design specifies. */
+    white-space: nowrap;
+    transition: color var(--transition-duration-fast) var(--transition-easing-smooth),
+      background-color var(--transition-duration-fast) var(--transition-easing-smooth);
+  }
+
+  .bd-tabs-container--switcher .bd-tab-button.bd-selected {
+    background: var(--color-surface-default);
+  }
+
+  /* The underline belongs to the other appearance. Left as display:none rather
+     than content:none so the base rule's width transition has nothing to
+     animate either. */
+  .bd-tabs-container--switcher .bd-tab-button::after {
+    display: none;
+  }
+
+  /* The base hover goes to action/primary-active, a darker blue, which on this
+     blue track would be close to invisible and is the wrong direction anyway.
+     The unselected option is already white, so the pointer affordance is the
+     pill appearing under it -- white at 12%, which reads on blue-500 without
+     competing with the selected option's solid white. */
+  .bd-tabs-container--switcher .bd-tab-button:hover:not(.bd-selected) {
+    color: var(--color-text-inverse);
+    background: var(--color-border-container-inverse);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .bd-tabs-container--switcher .bd-tab-button {
+      transition: none;
+    }
+  }
+`;
+
+export default tabListCSS;