@repobit/dex-system-design 1.0.0 → 2.0.0

package/src/components/list/list-item/list-item.js

@@ -2,6 +2,7 @@ import { LitElement, html, nothing } from "lit";
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import "../../../tokens/tokens.js";
 import listItemCSS from "./list-item.css.js";
+import { color } from "../../shared/token-scales.js";
 import "../../icons/check-icon.js";
 
 // the size steps list-item.css.js actually implements
@@ -10,6 +11,11 @@ const SIZE_STEPS = ['sm', 'md', 'lg'];
 /** The markers this item can draw. */
 const MARKERS = ['bullet', 'number', 'check', 'none'];
 
+/* Whether a sibling is a numbered item, read so it also answers for one
+   that has not upgraded yet: its variant is still only an attribute. */
+const isNumbered = el => el.localName === 'bd-li'
+  && (el.variant || el.getAttribute('variant') || el.getAttribute('kind')) === 'number';
+
 export class BdListItem extends LitElement {
   static properties = {
     variant: { type: String, reflect: true },
@@ -17,7 +23,7 @@ export class BdListItem extends LitElement {
     kind   : { type: String },
     size   : { type: String }, // sm, md, lg
     icon   : { type: String }, // custom icon URL
-    color  : { type: String }  // optional
+    color  : { type: String }  // a text role -- see token-scales.js COLOR_ROLES
   };
 
   constructor() {
@@ -36,10 +42,52 @@ export class BdListItem extends LitElement {
     }
   }
 
+  /* WHY THE NUMBER IS WORKED OUT HERE.
+     The number used to be a CSS counter, incremented on the <li> inside this
+     element's shadow root. Every shadow root starts its own counter, so each
+     item counted only itself and every numbered list read 1. 1. 1. Now each
+     item counts the numbered bd-li before it among its siblings, starting at
+     the enclosing bd-list's start.
+
+     The count depends on the siblings, so an item joining, leaving or
+     changing variant asks the others to recount, and bd-list asks its items
+     when start changes. */
+  get _number() {
+    const parent = this.parentElement;
+    if (!parent) return 1;
+    const start = parent.localName === 'bd-list' && Number.isFinite(parent.start) ? parent.start : 1;
+    return start + [...parent.children].filter(isNumbered).indexOf(this);
+  }
+
+  _renumberPeers(parent = this.parentElement) {
+    if (!parent) return;
+    for (const el of parent.children) if (el !== this && el.localName === 'bd-li') el.requestUpdate?.();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._parent = this.parentElement;
+    this._renumberPeers();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._renumberPeers(this._parent);
+    this._parent = null;
+  }
+
+  updated(changed) {
+    if (changed.has("variant")) this._renumberPeers();
+  }
+
   render() {
-    const style = this.color
-      ? `color: ${this.color}; --bd-li-marker-color: ${this.color};`
-      : "";
+    /* color is a text role, resolved the way bd-h resolves it. It used to be
+       written into the style attribute as given, so any string at all -- a
+       hex, a raw palette var(), a value with a semicolon in it -- reached the
+       inline style unchecked, past every token rule. A name that is not a
+       role writes nothing, and the item keeps its own colours. */
+    const ink = color(this.color);
+    const style = ink ? `color: ${ink}; --bd-li-marker-color: ${ink};` : "";
 
     return html`
       <li class="bd-list-item ${this.variant} ${SIZE_STEPS.includes(this.size) ? this.size : 'md'}" style="${style}">
@@ -58,7 +106,7 @@ export class BdListItem extends LitElement {
       return html`<img src="${this.icon}" alt="" class="bd-list-item-custom-icon" />`;
     }
 
-    return html`<span class="bd-list-item-marker">${
+    return html`<span class="bd-list-item-marker" data-number="${this.variant === "number" ? `${this._number}.` : nothing}">${
       this.variant === "check"
         ? html`<bd-check-icon size="xs" aria-hidden="true"></bd-check-icon>`
         : nothing

package/src/components/list/list-item/list-item.stories.js

@@ -1,5 +1,6 @@
 import { html } from "lit";
 import "./list-item.js";
+import "../list.js";
 
 export default {
   title     : "Atoms/List item",
@@ -88,6 +89,27 @@ export const Number = {
   `
 };
 
+/**
+ * Each item counts the numbered bd-li before it, starting at the enclosing
+ * bd-list's start. The number was a CSS counter once, and a counter cannot
+ * count across shadow roots, so every item read "1." -- a single-item story
+ * could not show that, which is why this one has several.
+ */
+export const NumberedList = {
+  name  : "Number — a list of them",
+  render: () => html`
+    <bd-list type="ordered">
+      <bd-li variant="number" size="md">Download the installer</bd-li>
+      <bd-li variant="number" size="md">Run it and sign in</bd-li>
+      <bd-li variant="number" size="md">Start your first scan</bd-li>
+    </bd-list>
+    <bd-list type="ordered" start="4">
+      <bd-li variant="number" size="md">Continues from four</bd-li>
+      <bd-li variant="number" size="md">and five</bd-li>
+    </bd-list>
+  `
+};
+
 // ─── Check ────────────────────────────────────────────────────────────────────
 
 export const Check = {

package/src/components/list/list.js

@@ -3,6 +3,14 @@ import { LitElement, html } from "lit";
 import "../../tokens/tokens.js";
 import listCSS from "./list.css.js";
 
+/* The values list.css.js styles, each with the default it falls back to. */
+const ALLOWED = {
+  type       : [['ordered', 'unordered'], 'unordered'],
+  spacing    : [['sm', 'md', 'lg'], 'md'],
+  variant    : [['default', 'compact', 'spacious'], 'default'],
+  orientation: [['vertical', 'horizontal'], 'vertical']
+};
+
 export class BdList extends LitElement {
   static properties = {
     type       : { type: String, reflect: true }, // 'ordered', 'unordered'
@@ -21,6 +29,25 @@ export class BdList extends LitElement {
     this.orientation = "vertical";
   }
 
+  /* Each of these becomes a class and reflects, so an unknown value used to
+     land on the element and in the class list as a name nothing styles --
+     orientation="row" laid the list out as nothing in particular, and still
+     said "row". It now falls back to the default, and the attribute shows
+     what is applied. start that is not a number goes back to 1. */
+  willUpdate(changed) {
+    for (const [prop, [values, fallback]] of Object.entries(ALLOWED)) {
+      if (changed.has(prop) && !values.includes(this[prop])) this[prop] = fallback;
+    }
+    if (changed.has('start') && !Number.isFinite(this.start)) this.start = 1;
+  }
+
+  /* A numbered bd-li counts from start, so it has to recount when start does. */
+  updated(changed) {
+    if (changed.has("start")) {
+      for (const el of this.children) if (el.localName === "bd-li") el.requestUpdate?.();
+    }
+  }
+
   render() {
     const classes = `bd-list ${this.spacing} ${this.variant} ${this.orientation}`;
 

package/src/components/modal/modal.css.js

@@ -130,7 +130,12 @@ export default css`
 
   .bd-modal-content button:focus-visible {
     /* the one focus ring — see Foundations/Focus */
-    outline: none;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
   }
 

package/src/components/pagination-dots/pagination-dots.css.js

@@ -0,0 +1,161 @@
+import { css } from "lit";
+
+/**
+ * Styled entirely from src/tokens/tokens.js -- see CLAUDE.md, "The foundation
+ * rule".
+ *
+ * The geometry is dimension, not spacing, on purpose: a dot is a fixed mark
+ * and should not grow when a reader enlarges their text. The gap around each
+ * dot is spacing, because it is padding, and padding is allowed to grow. So a
+ * larger root font makes the targets wider and leaves the dots as drawn.
+ */
+export default css`
+  :host {
+    display: inline-flex;
+  }
+
+  .dots {
+    display: flex;
+    align-items: center;
+    /* Each button carries its own target, so the space between two dots comes
+       from the boxes. A gap on top would push them apart without making
+       either easier to hit. */
+  }
+
+  /* ---- dots ---------------------------------------------------------------
+     The target. 24px tall for WCAG 2.5.8, and the dot plus 8px either side
+     wide: 24 for a resting dot, 56 for the current pill. The dot is drawn
+     inside it rather than being it. */
+  .dot {
+    display: grid;
+    place-items: center;
+    height: var(--dimension-24);
+    margin: 0;
+    padding: 0 var(--spacing-8);
+    border: none;
+    background: transparent;
+    cursor: pointer;
+  }
+
+  /* The mark is a real element rather than a ::before, because the current
+     one holds the progress fill and a Web Animation needs an element to run
+     on. */
+  .mark {
+    position: relative;
+    display: block;
+    overflow: hidden;
+    width: var(--dimension-8);
+    height: var(--dimension-8);
+    border-radius: var(--radius-full);
+    /* no role: a resting slide mark. No semantic role names an inactive
+       indicator, and it has to clear the 3:1 WCAG 1.4.11 asks of a control's
+       only visual: neutral-500 measures 4.81 on the page and 4.46 on the
+       blue-50 info tint the homepage puts it on. The design's 30% neutral-900
+       measures 1.94 there; neutral-300, which bd-awards-flex used to draw,
+       2.10; and neutral-450 would clear it but exists for the dark theme only. */
+    background: var(--color-neutral-500);
+    transition: width var(--transition-duration-normal) var(--transition-easing-ease),
+      background var(--transition-duration-normal) var(--transition-easing-ease);
+  }
+
+  .dot:hover .mark {
+    /* no role: the same mark under the pointer, one step darker */
+    background: var(--color-neutral-600);
+  }
+
+  /* The progress. Scaled rather than sized, so the fill is drawn by the
+     compositor and never re-lays the row out. Without autoplay the current
+     fill is whole, which is the pill as it always was; with it, the atom's
+     Web Animation runs this from 0 to 1 over the delay and the end of the
+     animation is the change of slide. */
+  .fill {
+    position: absolute;
+    inset: 0;
+    background: var(--indicator-color);
+    transform: scaleX(0);
+    transform-origin: left center;
+  }
+
+  :host(:dir(rtl)) .fill {
+    transform-origin: right center;
+  }
+
+  /* The current slide. The pill is the design's shape. The colour is the
+     indicator role, the one every current-item mark in the package shares --
+     the tab and nav underlines -- so they cannot drift apart. The design draws
+     it neutral-900 as an unbound value; using that would make this the one
+     current mark in the system that is not the indicator. */
+  .dot[aria-current="true"] {
+    cursor: default;
+  }
+
+  /* The current pill is also the autoplay track: the indicator colour at a
+     fifth, laid over whatever surface the dots sit on, inside an indicator
+     edge. Translucent rather than a colour of its own, so it belongs to every
+     ground -- a white track read as a hole on the awards tint and on a band.
+     It was the resting grey before that, and the blue fill could not be seen
+     on it: blue-500 on neutral-500 is 1.06:1.
+     .
+     The edge is 2px, drawn as an outline pulled inside the box rather than as
+     a border. At 1px it was faint at 1x density, and that is the moment it
+     matters most: the start of each slide, when nothing has filled yet and
+     the edge alone marks the pill. A 2px border would have taken the 2px out
+     of the box and left the fill a 4px sliver; an outline takes no room, and
+     it paints above the fill in the fill's own colour, so the fill keeps the
+     full 8px and the two merge where they meet. Under a forced palette the
+     outline is repainted in a system colour and still draws.
+     .
+     Measured: the fill against the track is 3.10:1 or better on the page,
+     the container, the subtle band and the awards tint; the edge against the
+     ground 4.05:1 or better. When the fill is whole the edge and fill are one
+     colour, which is the solid pill a dots row without autoplay shows. */
+  .dot[aria-current="true"] .mark {
+    width: var(--dimension-40);
+    background: color-mix(in srgb, var(--indicator-color) 20%, transparent);
+    outline: var(--border-width-2) solid var(--indicator-color);
+    outline-offset: calc(-1 * var(--border-width-2));
+  }
+
+  .dot[aria-current="true"] .fill {
+    transform: scaleX(1);
+  }
+
+  /* ---- focus ------------------------------------------------------------
+     the one focus ring -- see Foundations/Focus. It follows the target, not
+     the mark, so keyboard focus shows the size the button really is. */
+  .dot:focus {
+    outline: none;
+  }
+
+  .dot:focus-visible {
+    box-shadow: var(--focus-outline-primary);
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
+    border-radius: var(--radius-full);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .mark {
+      transition: none;
+    }
+  }
+
+  /* A forced palette repaints backgrounds, which would erase every dot.
+     Borders survive it, so a resting dot is drawn as a ring, and the fill is
+     kept out of the repaint and drawn in the highlight colour -- so the
+     current pill still shows, and so does the time it has left. */
+  @media (forced-colors: active) {
+    .mark {
+      box-sizing: border-box;
+      border: var(--border-width-1) solid currentColor;
+    }
+    .fill {
+      forced-color-adjust: none;
+      background: Highlight;
+    }
+  }
+`;

package/src/components/pagination-dots/pagination-dots.js

@@ -0,0 +1,202 @@
+import { LitElement, html, nothing } from "lit";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
+import paginationDotsCSS from "./pagination-dots.css.js";
+
+/**
+ * Which of a run of slides is showing, and a way to go to another: the
+ * package's one set of slide dots. Drawn in the foundation Figma file as
+ * Pagination dot and Pagination dots.
+ *
+ * bd-awards-flex and bd-carousel-section each used to draw their own -- a dot
+ * row that claimed to be a tablist, and a pair of <img role="button"> arrows --
+ * and the two had drifted apart on contrast, semantics and names. The carousel
+ * that owns the slides stays the owner of the slides: it sets current, and
+ * listens for bd-change.
+ *
+ * SEMANTICS. A group of buttons, the current one marked aria-current. Not a
+ * tablist: a tab needs a tabpanel it controls, and this atom does not own or
+ * know the panels. Each button is named for what it does ("Go to slide 2"),
+ * and the group for what it moves through. Both names are attributes, so a
+ * page in another language can say them.
+ *
+ * TARGET SIZE. A dot is 8px and the design spaces them 8px apart. Clickable at
+ * that size they fail WCAG 2.5.8, so each button is a 24px target with the dot
+ * drawn inside it. The dots end up 16px apart instead of 8; the part you can
+ * hit grows and the dots do not.
+ *
+ * AUTOPLAY. With autoplay set, the atom advances itself every delay ms and the
+ * current pill fills as the time runs: the progress IS the clock, so the fill
+ * and the change of slide cannot drift apart. That is why the timer lives here
+ * and not in the carousel. Every advance fires bd-change, exactly as a click.
+ *
+ * Stopping it. WCAG 2.2.2 wants a way to stop anything that moves on its own,
+ * and there is no pause button, so the dots are the mechanism: picking one
+ * stops autoplay for good (paused), because a visitor who chose a slide has
+ * said which one they want to read. The clock also holds -- transiently --
+ * while the pointer or focus is on the dots, or while the owner sets held for
+ * its own slides. Under prefers-reduced-motion it never starts.
+ *
+ * count below 2 renders nothing: one page has nothing to move to.
+ */
+const MIN_DELAY = 1000;
+
+class BdPaginationDots extends LitElement {
+  static styles = [paginationDotsCSS];
+
+  static properties = {
+    count    : { type: Number },
+    current  : { type: Number, reflect: true },
+    label    : { type: String },
+    itemLabel: { type: String, attribute: "item-label" },
+    autoplay : { type: Boolean, reflect: true },
+    delay    : { type: Number },
+    paused   : { type: Boolean, reflect: true },
+    held     : { type: Boolean },
+    _selfHeld: { state: true }
+  };
+
+  constructor() {
+    super();
+    this.count = 0;
+    // 1-based, like the names the buttons announce
+    this.current = 1;
+    this.label = "Slides";
+    this.itemLabel = "Go to slide";
+    this.autoplay = false;
+    this.delay = 4000;
+    this.paused = false;
+    this.held = false;
+    this._selfHeld = false;
+    this._progress = null;
+    this._announced = undefined;
+    this._onMotionChange = () => { if (this._motionQuery.matches) this.paused = true; };
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Watched rather than read once, so turning the setting on mid-visit stops it.
+    if (typeof window !== "undefined" && window.matchMedia) {
+      this._motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+      if (this._motionQuery.matches) this.paused = true;
+      this._motionQuery.addEventListener("change", this._onMotionChange);
+    }
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._motionQuery?.removeEventListener("change", this._onMotionChange);
+    this._stopProgress();
+  }
+
+  /** count is a whole number of dots, and current always names one of them. */
+  willUpdate(changed) {
+    if (!changed.has("count") && !changed.has("current")) return;
+    const count = Math.max(0, Math.floor(Number(this.count) || 0));
+    if (count !== this.count) this.count = count;
+    const current = Math.min(Math.max(1, Math.floor(Number(this.current) || 1)), Math.max(1, count));
+    if (current !== this.current) this.current = current;
+  }
+
+  updated(changed) {
+    // A new slide, a new clock or autoplay switched: the fill starts again.
+    if (["count", "current", "autoplay", "delay"].some(k => changed.has(k))) this._startProgress();
+    this._syncProgress();
+    this._announcePlayState();
+  }
+
+  get _running() {
+    return this.autoplay && this.count > 1;
+  }
+
+  get _moving() {
+    return this._running && !this.paused && !this.held && !this._selfHeld;
+  }
+
+  /* One Web Animation per slide, on the current pill's fill. Its finish is the
+     advance; pausing it is pausing the clock, and the fill holds where it
+     stopped rather than snapping back. */
+  _startProgress() {
+    this._stopProgress();
+    if (!this._running) return;
+    const fill = this.renderRoot.querySelector('.dot[aria-current="true"] .fill');
+    if (!fill?.animate) return;
+    const delay = Math.max(MIN_DELAY, Number(this.delay) || 0);
+    const progress = fill.animate(
+      [{ transform: "scaleX(0)" }, { transform: "scaleX(1)" }],
+      { duration: delay, easing: "linear", fill: "forwards" }
+    );
+    this._progress = progress;
+    progress.finished.then(() => {
+      if (this._progress !== progress) return;
+      this._select(this.current >= this.count ? 1 : this.current + 1);
+    }, () => {});
+  }
+
+  _stopProgress() {
+    const progress = this._progress;
+    this._progress = null;
+    progress?.cancel();
+  }
+
+  _syncProgress() {
+    const progress = this._progress;
+    if (!progress) return;
+    if (this._moving && progress.playState === "paused") progress.play();
+    else if (!this._moving && progress.playState === "running") progress.pause();
+  }
+
+  /* bd-toggle whenever the slides start or stop moving, for whatever reason.
+     An owner needs it for its live region -- slides that change on their own
+     must not be announced, and slides that change because the visitor asked
+     must be -- and only this atom knows about the holds it places itself.
+     Fired once on first render too, so the owner starts in step. */
+  _announcePlayState() {
+    const state = `${this.paused}|${this._moving}`;
+    if (state === this._announced) return;
+    this._announced = state;
+    this.dispatchEvent(new CustomEvent("bd-toggle", {
+      detail  : { paused: this.paused, moving: this._moving },
+      bubbles : true,
+      composed: true
+    }));
+  }
+
+  _select(n) {
+    if (n === this.current) return;
+    this.current = n;
+    this.dispatchEvent(new CustomEvent("bd-change", {
+      detail  : { current: n },
+      bubbles : true,
+      composed: true
+    }));
+  }
+
+  // The visitor's pick: it moves, and it stops autoplay for good.
+  _pick(n) {
+    if (this._running) this.paused = true;
+    this._select(n);
+  }
+
+  render() {
+    if (this.count < 2) return nothing;
+    const pages = Array.from({ length: this.count }, (_, i) => i + 1);
+    return html`<div
+        class="dots"
+        role="group"
+        aria-label="${this.label}"
+        @pointerenter=${() => { this._selfHeld = true; }}
+        @pointerleave=${() => { this._selfHeld = this.renderRoot.contains(this.renderRoot.activeElement); }}
+        @focusin=${() => { this._selfHeld = true; }}
+        @focusout=${e => { this._selfHeld = this.renderRoot.contains(e.relatedTarget) || this.matches(":hover"); }}
+      >${pages.map(n => html`<button
+          type="button"
+          class="dot"
+          aria-label="${this.itemLabel} ${n}"
+          aria-current="${n === this.current ? "true" : nothing}"
+          @click=${() => this._pick(n)}
+        ><span class="mark"><span class="fill"></span></span></button>`)}</div>`;
+  }
+}
+
+customElements.define("bd-pagination-dots", BdPaginationDots);