@repobit/dex-system-design 1.0.1 → 2.0.1

package/src/components/radio/radio.js

@@ -20,7 +20,11 @@ class BdRadio extends LitElement {
   static styles = [radioCSS];
 
   static properties = {
-    name    : { type: String },
+    /* Reflected because the group is found by it: _group selects same-name
+       radios by attribute, so a name set as a property -- radio.name = "plan",
+       which is what a framework binding does -- left the radio in no group at
+       all, with no exclusivity, no arrow keys and its own tab stop. */
+    name    : { type: String, reflect: true },
     value   : { type: String },
     checked : { type: Boolean, reflect: true },
     disabled: { type: Boolean, reflect: true },
@@ -43,7 +47,7 @@ class BdRadio extends LitElement {
     if (!this.name) return [this];
     const root = this.getRootNode();
     const scope = root instanceof Document || root instanceof ShadowRoot ? root : document;
-    return [...scope.querySelectorAll(`bd-radio[name="${this.name}"]`)];
+    return [...scope.querySelectorAll(`bd-radio[name="${CSS.escape(this.name)}"]`)];
   }
 
   /**
@@ -57,6 +61,45 @@ class BdRadio extends LitElement {
     return group.find(r => !r.disabled) === this;
   }
 
+  /* The tab stop is a group decision, but each radio renders only when its own
+     properties change. So when one radio's checked or disabled flips, or one
+     joins or leaves, the rest have to be told to re-render: clicking radio 3
+     in a group with nothing selected used to leave radio 1 at tabindex 0
+     beside it -- two tab stops in one group. The peers' own checked and
+     disabled do not change, so this does not cascade. */
+  _refreshPeers(group) {
+    for (const radio of group) {
+      if (radio !== this) radio.requestUpdate?.();
+    }
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._refreshPeers(this._group);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // detached, this radio can no longer find its root, so it asks the one it
+    // was connected in
+    const root = this._root;
+    if (this.name && root) {
+      this._refreshPeers(root.querySelectorAll(`bd-radio[name="${CSS.escape(this.name)}"]`));
+    }
+  }
+
+  updated(changed) {
+    this._root = this.isConnected ? this.getRootNode() : this._root;
+    if (changed.has("checked") || changed.has("disabled") || changed.has("name")) {
+      this._refreshPeers(this._group);
+    }
+    // a radio renamed out of a group leaves its old peers to re-decide too
+    const oldName = changed.get("name");
+    if (oldName && this._root) {
+      this._refreshPeers(this._root.querySelectorAll(`bd-radio[name="${CSS.escape(oldName)}"]`));
+    }
+  }
+
   _select() {
     if (this.disabled || this.checked) return;
 
@@ -153,8 +196,10 @@ class BdToggleRadio extends LitElement {
     this.checked = !this.checked;
 
     this.dispatchEvent(
+      // name was declared and read by nothing; it is carried here, as
+      // bd-radio carries it, so a handler can tell which control changed
       new CustomEvent("change", {
-        detail  : { checked: this.checked, value: this.checked ? this.value : null },
+        detail  : { checked: this.checked, value: this.checked ? this.value : null, name: this.name },
         bubbles : true,
         composed: true
       })

package/src/components/radio/radio.stories.js

@@ -69,7 +69,7 @@ Two deviations from the design, both deliberate:
 
 ### Events
 - \`change\` — \`detail: { name, value }\` on \`bd-radio\`;
-  \`detail: { checked, value }\` on \`bd-toggle-radio\`.
+  \`detail: { checked, value, name }\` on \`bd-toggle-radio\`.
         `
       }
     }

package/src/components/shared/form-field.css.js

@@ -106,12 +106,17 @@ export const formFieldCSS = css`
      shows the indicator for a pointer click there too, because typing is
      expected — but the select is a control you click and walk away from, and
      it was drawing the full ring on every mouse press where bd-button drew
-     nothing. .focused is the component's own prop, not a user interaction, so
-     it stays unconditional. */
-  .form-input-bd:focus-visible,
-  .form-input-bd.focused {
+     nothing. There is no .focused class any more: a field's focused prop now
+     moves real focus, so :focus-visible is the only thing that draws this. */
+  .form-input-bd:focus-visible {
     border-color: var(--form-input-focus-borderColor);
     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);
   }
 
   /* ---- sizes ------------------------------------------------------------
@@ -139,6 +144,27 @@ export const formFieldCSS = css`
     border-radius: var(--form-input-large-borderRadius);
   }
 
+  /* The text's own room. --form-input-*-height is padding plus the line box,
+     and the box is border-box, so the 1px border on each edge came out of the
+     content: the line box stood 2px taller than the space left for it. An
+     input centres its line and paints into the padding, so it never showed;
+     a select does neither -- it clips at the content box -- and at md the
+     descenders of "Italy gjpqy ș ț" lost their bottoms. Taking the border out
+     of the block padding instead gives the line all of its box and leaves
+     every height where it was, on its button. The textarea is left out: its
+     height comes from its rows, so this would only make it 2px shorter. */
+  .input-sm:not(textarea) {
+    padding-block: calc(var(--spacing-8) - var(--form-input-default-borderWidth));
+  }
+
+  .input-md:not(textarea) {
+    padding-block: calc(var(--spacing-12) - var(--form-input-default-borderWidth));
+  }
+
+  .input-lg:not(textarea) {
+    padding-block: calc(var(--spacing-16) - var(--form-input-default-borderWidth));
+  }
+
   ::placeholder {
     color: var(--color-text-subtle);
     opacity: 1;

package/src/components/shared/token-scales.js

@@ -141,6 +141,22 @@ export const fontFamily = onScale(FONT_FAMILY_STEPS, '--typography-fontFamily-')
 export const letterSpacing = onScale(LETTER_SPACING_STEPS, '--typography-letterSpacing-');
 export const radius     = onScale(RADIUS_STEPS, '--radius-');
 
+/* The border-width steps. A px spelling of a step -- "2px" -- is read as the
+   step, because that is what callers wrote before there was a scale here. */
+export const BORDER_WIDTH_STEPS = ['0', '1', '2', '3', '4', '8'];
+export const borderWidth = value => {
+  const step = String(value ?? '').replace(/px$/, '');
+  return BORDER_WIDTH_STEPS.includes(step) ? `var(--border-width-${step})` : '';
+};
+
+/* Not a scale: a fraction. An opacity given as a prop is kept only when it is
+   a number from 0 to 1, so a stray string never reaches an inline style. */
+export const opacity = value => {
+  if (value === '' || value == null) return '';
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? String(n) : '';
+};
+
 export const space = name =>
   (Object.hasOwn(SPACE_STEPS, name) ? `var(--spacing-${SPACE_STEPS[name]})` : '');
 

package/src/components/spinner/spinner.css.js

@@ -33,6 +33,19 @@ export const spinnerCSS = css`
     --bd-spinner-pulse-fill: color-mix(in srgb, var(--color-neutral-0) 30%, transparent);
   }
 
+  /* The status region: text for assistive technology, nothing on screen. */
+  .announce {
+    position: absolute;
+    /* no token: 1px is the clip idiom's own measure, not a border -- the same
+       sanctioned literal as visually-hidden.css.js. */
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
   .spinner {
     width: var(--dimension-24);
     height: var(--dimension-24);
@@ -47,13 +60,27 @@ export const spinnerCSS = css`
 
   @keyframes bd-spin { to { transform: rotate(360deg); } }
 
-  /* a spinner that cannot spin should still say something, so fall back to a
-     pulse rather than freezing solid */
+  /* A spinner that cannot spin should still say something, so it pulses
+     rather than freezing solid -- but only the disc inside it. This used to
+     repaint the arc in the track colour and pulse the whole ring, so what was
+     left was the track alone: 1.66:1 against the page, 1.21:1 at the pulse's
+     low point, under the 3:1 WCAG 1.4.11 asks of a graphic that conveys
+     state. The arc now stays, still and at full strength (4.53:1 on the page,
+     3.64:1 on the disc), and the disc behind it carries the motion. Pulsing
+     the whole spinner instead would take the arc to 1.79:1 at the bottom of
+     each pulse. */
   @media (prefers-reduced-motion: reduce) {
     .spinner {
-      animation: bd-pulse var(--transition-duration-slower) var(--transition-easing-smooth) infinite alternate;
-      border-top-color: var(--bd-spinner-track);
+      position: relative;
+      animation: none;
+    }
+    .spinner::before {
+      content: "";
+      position: absolute;
+      inset: var(--spacing-0);
+      border-radius: var(--radius-full);
       background: var(--bd-spinner-pulse-fill);
+      animation: bd-pulse var(--transition-duration-slower) var(--transition-easing-smooth) infinite alternate;
     }
     @keyframes bd-pulse { to { opacity: var(--opacity-pulse); } }
   }

package/src/components/spinner/spinner.js

@@ -8,12 +8,13 @@ export class BdSpinner extends LitElement {
   static styles = [spinnerCSS];
 
   static properties = {
-    size   : { type: String, reflect: true },
-    label  : { type: String },
+    size     : { type: String, reflect: true },
+    label    : { type: String },
     /* The surface the spinner sits on. Its default arc and track were both
        chosen against a white page, so on a filled panel it all but disappears.
        Same attribute, same meaning, as on bd-button. */
-    surface: { type: String, reflect: true }
+    surface  : { type: String, reflect: true },
+    _announce: { type: Boolean, state: true }
   };
 
   constructor() {
@@ -21,6 +22,26 @@ export class BdSpinner extends LitElement {
     this.size = 'md';
     this.label = 'Loading';
     this.surface = 'light';
+    this._announce = false;
+  }
+
+  /* WHY THE TEXT ARRIVES LATE.
+     This was an empty role="status" named by aria-label. A live region is
+     announced when its CONTENT changes, and a name is not content, so it
+     never had anything to say: nothing announced the wait at all.
+
+     The label is now text inside the region. It is rendered empty first and
+     filled a moment later, because the region has to be in the accessibility
+     tree before its text arrives -- a region inserted already holding its
+     text is, to many screen readers, not a change. A later label change is
+     a content change too, so it is announced as well. */
+  firstUpdated() {
+    this._announceTimer = setTimeout(() => { this._announce = true; }, 100);
+  }
+
+  disconnectedCallback() {
+    clearTimeout(this._announceTimer);
+    super.disconnectedCallback();
   }
 
   willUpdate(changed) {
@@ -30,7 +51,8 @@ export class BdSpinner extends LitElement {
 
   render() {
     return html`
-      <span class="spinner" role="status" aria-label=${this.label}></span>
+      <span class="spinner" aria-hidden="true"></span>
+      <span class="announce" role="status">${this._announce ? this.label : ''}</span>
     `;
   }
 }

package/src/components/spinner/spinner.stories.js

@@ -22,16 +22,19 @@ unknown. When you know the proportion done, use \`<bd-progress>\` instead.
 ### Props
 | Prop | Values | Default |
 |---|---|---|
-| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+| \`size\` | \`sm\`, \`md\`, \`lg\` — \`small\` / \`default\` / \`large\` still resolve | \`md\` |
 | \`label\` | the accessible name | \`Loading\` |
 
 ### Accessibility
-It carries \`role="status"\` with \`aria-label\` from \`label\`, so the wait is
-announced politely rather than interrupting. Give it a specific \`label\` where
+\`label\` is the text of a visually hidden \`role="status"\` region, so the wait
+is announced politely rather than interrupting. The text arrives just after
+the region does, which is what lets a screen reader treat it as news, and a
+later change to \`label\` is announced too. Give it a specific \`label\` where
 you can — "Checking your licence" is more use than the default "Loading".
 
-Under \`prefers-reduced-motion\` it stops spinning and pulses instead, so it
-still reads as active without rotating.
+Under \`prefers-reduced-motion\` it stops spinning: the arc stays, still and
+at full contrast, and the disc behind it pulses, so it still reads as active
+without rotating and never fades below 3:1.
 
 ### Note on colour
 The spinner's track and head are fixed at \`--color-neutral-200\` and
@@ -47,9 +50,9 @@ let the two converge.
   argTypes: {
     size: {
       control    : { type: 'select' },
-      options    : ['small', 'default', 'large'],
+      options    : ['sm', 'md', 'lg'],
       description: 'Diameter of the spinner.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     },
     label: {
       control    : 'text',

package/src/components/switch/switch.css.js

@@ -58,10 +58,22 @@ export const switchCSS = css`
     flex: none;
   }
 
+  /* The thumb's inset and travel are derived from the two boxes they sit
+     between, in px like those boxes. They were --spacing-2 and --spacing-16,
+     which are rem, inside a track that is --dimension-* and so is not: at a
+     24px root the thumb rode 3px in and travelled 24px, and finished at 47px
+     in a 40px track. A knob has to stay on the track it belongs to at any text
+     size, so all four lengths are now one unit. Inset is half the height left
+     over; travel is the width left over after both insets: 2px and 16px. */
+  .track {
+    --bd-switch-inset: calc((var(--dimension-24) - var(--dimension-20)) / 2);
+    --bd-switch-travel: calc(var(--dimension-40) - var(--dimension-20) - 2 * var(--bd-switch-inset));
+  }
+
   .thumb {
     position: absolute;
-    top: var(--spacing-2);
-    left: var(--spacing-2);
+    top: var(--bd-switch-inset);
+    left: var(--bd-switch-inset);
     width: var(--dimension-20);
     height: var(--dimension-20);
     /* the knob on the track, white on both tracks: --color-action-on-fill,
@@ -81,13 +93,19 @@ export const switchCSS = css`
      If a second component ever needs it, that is when it earns a name. */
   label:hover .track { background: var(--color-neutral-500); }
   :host([checked]) label:hover .track { background: var(--color-action-primary-hover); }
-  :host([checked]) .thumb { transform: translateX(var(--spacing-16)); }
+  :host([checked]) .thumb { transform: translateX(var(--bd-switch-travel)); }
 
   /* the one focus ring — see Foundations/Focus. On the row rather than the
      track, so the target and the indicator are the same shape here as on
      bd-checkbox and bd-radio. */
   label:has(input: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(--focus-outline-radius);
   }
 

package/src/components/switch/switch.js

@@ -31,7 +31,14 @@ export class BdSwitch extends LitElement {
           ?disabled=${this.disabled}
           @change=${e => {
             this.checked = e.target.checked;
-            this.dispatchEvent(new CustomEvent('bd-change', { detail: this.checked }));
+            // bubbles and composed, as every sibling form atom's event is: with
+            // neither, it reached a listener on the switch and nothing above
+            // it, so a form wrapper delegating bd-change heard nothing
+            this.dispatchEvent(new CustomEvent('bd-change', {
+              detail  : this.checked,
+              bubbles : true,
+              composed: true
+            }));
           }}
         />
         <span class="track"><span class="thumb"></span></span>

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

@@ -33,7 +33,8 @@ Content can also come from the default slot, which renders after \`label\` — s
 set one or the other, not both.
 
 ### Events
-\`bd-change\` — fires on toggle with \`detail\` set to the new boolean.
+\`bd-change\` — fires on toggle with \`detail\` set to the new boolean. It bubbles and
+is composed, so a form wrapper can listen for it on itself.
 
 ### Accessibility
 It is a real \`<input type="checkbox">\` with \`role="switch"\`, inside a

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

@@ -111,7 +111,12 @@ export const tabListCSS = css`
 
   .bd-tab-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);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/terminal/terminal-cursor.js

@@ -32,6 +32,17 @@ class TerminalCursor extends LitElement {
           opacity: 0;
         }
       }
+
+      /* A cursor that blinks for as long as the page is open is exactly the
+         motion the setting exists for, and this one had no guard: every
+         other animated element in the package stops or softens under
+         prefers-reduced-motion. Here it stops, and the cursor stays shown --
+         a steady block still says "this is where the terminal is". */
+      @media (prefers-reduced-motion: reduce) {
+        .bd-terminal-cursor {
+          animation: none;
+        }
+      }
     `
   ];
 

package/src/components/terminal/terminal-message.js

@@ -160,7 +160,7 @@ class TerminalMessage extends LitElement {
           ${this.items && this.items.length
             ? html`
                 <bd-list class="bd-terminalmsg-list">
-                  ${this.items.map((item) => html`<bd-li variant="bullet" size="sm" color="var(--color-neutral-0)">${item}</bd-li>`)}
+                  ${this.items.map((item) => html`<bd-li variant="bullet" size="sm" color="inverse">${item}</bd-li>`)}
                 </bd-list>
               `
             : nothing}

package/src/components/termsOfUse/terms.css.js

@@ -12,7 +12,12 @@ export default css`
 
   .bd-terms-text-a: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);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/textarea/textarea.stories.js

@@ -119,6 +119,11 @@ The vertical resize handle is left enabled, so a user can grow the field beyond
       control    : 'boolean',
       description: 'Blocks editing.',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    name: {
+      control    : 'text',
+      description: 'Carried on the bd-change detail as { value, name }, for your own submit handling. NOT submitted with a form — the <textarea> is in a shadow root.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Content' }
     }
   }
 };
@@ -127,6 +132,24 @@ export const Default = () => html`
   <bd-textarea label="What happened?" placeholder="Tell us what happened"></bd-textarea>
 `;
 
+/**
+ * `name` reaches no form -- the <textarea> is in this element's shadow root --
+ * so it is carried on the event instead. Type, then click away: the line
+ * below shows the bd-change detail as it arrives.
+ */
+export const NameOnTheEvent = {
+  name  : 'name on the event',
+  render: () => html`
+    <bd-textarea
+      label="What happened?"
+      name="incident"
+      rows="2"
+      @bd-change=${e => { e.currentTarget.nextElementSibling.textContent = `bd-change detail: ${JSON.stringify(e.detail)}`; }}
+    ></bd-textarea>
+    <p style="font-family: var(--typography-fontFamily-mono); font-size: var(--typography-fontSize-sm)">bd-change detail: (type, then click away)</p>
+  `
+};
+
 export const Sizes = {
   name  : 'All Sizes',
   render: () => html`

package/src/components/tooltip/tooltip.css.js

@@ -64,8 +64,31 @@ export const tooltipCSS = css`
     transition: opacity var(--transition-duration-fast) var(--transition-easing-smooth);
   }
 
+  /* Shown means reachable. WCAG 1.4.13 asks that the pointer can move onto
+     content that appeared on hover without it disappearing. With
+     pointer-events: none left on, the pointer passed through the bubble to
+     whatever lay beneath it, the host lost :hover, and the bubble hid. The
+     bubble is in this shadow tree, so hovering it keeps :host(:hover). */
   :host(:hover) .bubble,
-  :host(:focus-within) .bubble { opacity: 1; }
+  :host(:focus-within) .bubble { opacity: 1; pointer-events: auto; }
+
+  /* Escape hides it while the pointer or focus is still there; see the note
+     on _showing in tooltip.js. Same specificity as the rule above and later,
+     so it wins, and it takes pointer events away with the opacity. */
+  :host(:hover) .bubble--dismissed,
+  :host(:focus-within) .bubble--dismissed { opacity: 0; pointer-events: none; }
+
+  /* The bubble floats --spacing-8 above the trigger, and the pointer has to
+     cross that gap to reach it: this fills it, so the host stays hovered
+     across the way. It inherits pointer-events from the bubble, so it catches
+     nothing while the bubble is hidden. */
+  .bubble::after {
+    content: "";
+    position: absolute;
+    inset-inline: 0;
+    top: 100%;
+    bottom: calc(-1 * var(--spacing-8));
+  }
 
   @media (prefers-reduced-motion: reduce) {
     .bubble { transition: none; }