@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/checkbox/checkbox.stories.js

@@ -2,29 +2,57 @@ import { html } from 'lit';
 import './checkbox.js';
 
 export default {
-  title     : 'Components/Checkbox',
+  title     : 'Atoms/Checkbox',
   tags      : ['autodocs'],
   parameters: {
     docs: {
       description: {
         component: `
-**BdCheckbox** is a fully accessible Lit checkbox component.
+**BdCheckbox** is a three-state checkbox: unchecked, checked and
+indeterminate.
 
 ### Usage
 \`\`\`html
-<bd-checkbox label="Accept terms" name="terms" value="accepted"></bd-checkbox>
-<bd-checkbox label="Disabled" disabled></bd-checkbox>
+<bd-checkbox label="Accept terms"></bd-checkbox>
 <bd-checkbox label="Pre-checked" checked></bd-checkbox>
+<bd-checkbox label="Select all" indeterminate></bd-checkbox>
+<bd-checkbox label="Unavailable" disabled></bd-checkbox>
+
+<!-- the label is slotted, so it can carry markup -->
+<bd-checkbox>I agree to the <a href="/terms">Terms of Use</a></bd-checkbox>
 \`\`\`
 
+### States
+| State | |
+|---|---|
+| \`checked\` | Draws a tick. |
+| \`indeterminate\` | Draws a dash and announces \`aria-checked="mixed"\`. Takes precedence over \`checked\`, and clicking it resolves to checked, as a native checkbox does. |
+| \`disabled\` | Greys the box and the label, and drops the row out of the tab order. Exempt from contrast under WCAG 1.4.3. |
+
+Both marks are drawn in \`currentColor\` with flat caps and a mitred join, so
+they read sharp against the square corners of the box.
+
 ### Accessibility
-- Uses \`role="checkbox"\` with \`aria-checked\` and \`aria-disabled\`
-- Keyboard support: Space and Enter toggle the checkbox
-- Focus ring appears only on keyboard navigation (Tab), not on mouse click
-- \`tabindex="-1"\` when disabled
+- The **whole row is the control**, not just the box. Clicking the label
+  toggles, and the target measures 25px tall against the 24px WCAG 2.5.8 asks
+  for — a 20px box on its own cannot reach it.
+- \`role="checkbox"\` with \`aria-checked\` reporting \`true\`, \`false\` or
+  \`mixed\`, plus \`aria-disabled\`.
+- Space toggles. Enter also toggles as a convenience: this control is not
+  form-associated, so Enter has nothing else to do here.
+- The focus ring appears on keyboard navigation only, via \`:focus-visible\`,
+  and is inset evenly on all four sides.
+- \`tabindex="-1"\` when disabled.
+
+### Not form-associated
+\`name\` and \`value\` are carried on the \`change\` event, but this element does
+**not** participate in form submission — a \`<form>\` containing it yields no
+\`FormData\` entry, because there is no native input behind it. Read the state
+from the event or the \`checked\` property instead.
 
 ### Events
-- \`change\` — fires with \`detail: { value }\` where value is the checkbox's \`value\` prop when checked, or \`null\` when unchecked
+- \`change\` — \`detail: { checked, value }\`, where \`value\` is the \`value\` prop
+  when checked and \`null\` when not.
         `
       }
     }
@@ -32,28 +60,33 @@ export default {
   argTypes: {
     label: {
       control    : 'text',
-      description: 'Visible text label rendered next to the checkbox',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
-    },
-    name: {
-      control    : 'text',
-      description: 'Form field name',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Form' }
-    },
-    value: {
-      control    : 'text',
-      description: 'Value emitted in the `change` event detail when checked',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Form' }
+      description: 'Label text. Fallback for the default slot, so slotted content wins over it.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Content' }
     },
     checked: {
       control    : 'boolean',
-      description: 'Whether the checkbox is checked',
+      description: 'Draws a tick. Ignored while `indeterminate` is set.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    indeterminate: {
+      control    : 'boolean',
+      description: 'The mixed state. Draws a dash, announces `aria-checked="mixed"`, and takes precedence over `checked`.',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
     },
     disabled: {
       control    : 'boolean',
-      description: 'Disables interaction and applies disabled styles',
+      description: 'Blocks interaction, greys the box and label, and sets `tabindex="-1"`.',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    name: {
+      control    : 'text',
+      description: 'Carried on the `change` event only — this element does not participate in form submission.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Data' }
+    },
+    value: {
+      control    : 'text',
+      description: 'Emitted in the `change` event detail when checked, `null` when not.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Data' }
     }
   }
 };
@@ -64,11 +97,19 @@ const render = (args) => html`
     name="${args.name}"
     value="${args.value}"
     ?checked="${args.checked}"
+    ?indeterminate="${args.indeterminate}"
     ?disabled="${args.disabled}"
   ></bd-checkbox>
 `;
 
-const defaultArgs = { label: 'Accept terms and conditions', name: 'terms', value: 'accepted', checked: false, disabled: false };
+const defaultArgs = {
+  label        : 'Accept terms and conditions',
+  name         : 'terms',
+  value        : 'accepted',
+  checked      : false,
+  indeterminate: false,
+  disabled     : false
+};
 
 // ─── Stories ───────────────────────────────────────────────────────────────
 
@@ -106,13 +147,39 @@ export const AllStates = {
   name  : 'All States',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:12px;">
-      <bd-checkbox label="Unchecked"          name="s1" value="1"></bd-checkbox>
-      <bd-checkbox label="Checked"            name="s2" value="2" checked></bd-checkbox>
-      <bd-checkbox label="Disabled unchecked" name="s3" value="3" disabled></bd-checkbox>
-      <bd-checkbox label="Disabled checked"   name="s4" value="4" checked disabled></bd-checkbox>
+      <bd-checkbox label="Unchecked"              name="s1" value="1"></bd-checkbox>
+      <bd-checkbox label="Checked"                name="s2" value="2" checked></bd-checkbox>
+      <bd-checkbox label="Indeterminate"          name="s3" value="3" indeterminate></bd-checkbox>
+      <bd-checkbox label="Disabled unchecked"     name="s4" value="4" disabled></bd-checkbox>
+      <bd-checkbox label="Disabled checked"       name="s5" value="5" checked disabled></bd-checkbox>
+      <bd-checkbox label="Disabled indeterminate" name="s6" value="6" indeterminate disabled></bd-checkbox>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'Every state: the three check states across enabled and disabled. Checked draws a tick and indeterminate a dash, both in currentColor.' } } }
+};
+
+export const Indeterminate = {
+  name  : 'Indeterminate',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:var(--spacing-12);">
+      <bd-checkbox label="Select all" indeterminate></bd-checkbox>
+      <div style="margin-left:var(--spacing-24); display:flex; flex-direction:column; gap:var(--spacing-12);">
+        <bd-checkbox label="First" checked></bd-checkbox>
+        <bd-checkbox label="Second"></bd-checkbox>
+      </div>
     </div>
   `,
-  parameters: { docs: { description: { story: 'All four checkbox states side by side: unchecked, checked, disabled unchecked, disabled checked.' } } }
+  parameters: { docs: { description: { story: 'The mixed state, for a parent over a partially selected group. Announced as `aria-checked="mixed"`, and clicking it resolves to checked the way a native checkbox does.' } } }
+};
+
+export const SlottedLabel = {
+  name  : 'Slotted label',
+  render: () => html`
+    <bd-checkbox>
+      I agree to the <a href="#" @click=${(e) => e.preventDefault()}>Terms of Use</a>
+    </bd-checkbox>
+  `,
+  parameters: { docs: { description: { story: 'The label accepts markup through the default slot, so a link can sit inside it. The `label` prop still works as the fallback.' } } }
 };
 
 export const Group = {

package/src/components/code/code.css.js

@@ -0,0 +1,70 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const codeCSS = css`
+  :host { display: inline; }
+
+  /* Scoped to the inline case: block mode nests a <code> inside the <pre>,
+     and an unscoped code selector would give it the inline chrome too. */
+  :host(:not([block])) code {
+    font-family: var(--typography-code-inline-fontFamily);
+    font-size: var(--typography-code-inline-fontSize);
+    font-weight: var(--typography-code-inline-fontWeight);
+    line-height: var(--typography-code-inline-lineHeight);
+    letter-spacing: var(--typography-code-inline-letterSpacing);
+    /* an explicit colour, not an inherited one: the background is fixed, so
+       inheriting a light foreground from a dark section put white on
+       neutral-50 at 1.12:1 */
+    color: var(--color-text-primary);
+    background: var(--color-surface-subtle);
+    padding: 0 var(--spacing-4);
+    border-radius: var(--radius-sm);
+    /* a token name is one long unbreakable word, so let it break rather than
+       overflow a narrow column */
+    overflow-wrap: break-word;
+  }
+
+  :host([block]) { display: block; }
+
+  :host([block]) pre {
+    margin: 0;
+    font-family: var(--typography-code-block-fontFamily);
+    font-size: var(--typography-code-block-fontSize);
+    font-weight: var(--typography-code-block-fontWeight);
+    line-height: var(--typography-code-block-lineHeight);
+    letter-spacing: var(--typography-code-block-letterSpacing);
+    color: var(--color-text-primary);
+    background: var(--color-surface-subtle);
+    padding: var(--spacing-16);
+    /* --radius-xl, not --radius-3xl. 24px was the only use of the top step in
+       the whole atom layer — the Radius Census story labelled the row "code
+       block, and nothing else" — and because the focus ring is a box-shadow
+       that follows the element's own shape, it also made this the only atom
+       whose ring was a 24px rounded rectangle where every other one is 4-8px.
+       12px still reads softer than a control, which is the point of the
+       difference, without being the outlier. */
+    border-radius: var(--radius-xl);
+    overflow-x: auto;
+  }
+
+  /* the nested <code> carries the semantics only; the <pre> does the styling */
+  :host([block]) code {
+    font: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    background: none;
+    padding: 0;
+  }
+
+  /* the block is focusable so it can be scrolled from the keyboard, so it
+     needs a visible focus indicator of its own */
+  :host([block]) pre:focus-visible {
+    /* the one focus ring — see Foundations/Focus. A two-colour ring whose
+       white inner band keeps it visible on a coloured or dark surface, which a
+       single-colour outline cannot do. */
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+  }
+`;
+
+export default codeCSS;

package/src/components/code/code.js

@@ -0,0 +1,40 @@
+import { LitElement, html } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { codeCSS } from './code.css.js';
+
+export class BdCode extends LitElement {
+  static styles = [codeCSS];
+
+  static properties = {
+    block: { type: Boolean, reflect: true },
+    label: { type: String }
+  };
+
+  constructor() {
+    super();
+    this.block = false;
+    this.label = '';
+  }
+
+  render() {
+    // Block mode nests <code> inside <pre>: <pre> carries the preformatted
+    // whitespace, <code> carries "this is code". A bare <pre> is only
+    // preformatted text, so assistive tech got no signal it was code at all,
+    // even though the inline variant gave one.
+    //
+    // The <pre> scrolls horizontally, and a scrollable region that cannot be
+    // focused cannot be scrolled from the keyboard (WCAG 2.1.1). tabindex
+    // makes it reachable; role and label give it something to announce, since
+    // a focusable element with no accessible name says nothing.
+    return this.block
+      ? html`<pre
+          tabindex="0"
+          role="region"
+          aria-label="${this.label || 'Code'}"
+        ><code><slot></slot></code></pre>`
+      : html`<code><slot></slot></code>`;
+  }
+}
+
+customElements.define('bd-code', BdCode);

package/src/components/code/code.stories.js

@@ -0,0 +1,73 @@
+import { html } from 'lit';
+import './code.js';
+
+export default {
+  title     : 'Atoms/Code',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdCode** renders code, inline in prose or as a block.
+
+### Usage
+\`\`\`html
+Use <bd-code>var(--color-blue-500)</bd-code> rather than a hex value.
+
+<bd-code block>.button {
+  padding: var(--spacing-12) var(--spacing-24);
+}</bd-code>
+
+<bd-code block label="Button styles">…</bd-code>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`block\` | boolean — renders a \`<pre><code>\` block instead of inline \`<code>\` | \`false\` |
+| \`label\` | accessible name for the scrollable block. Block mode only. | \`Code\` |
+
+### Inline versus block
+Inline renders a single \`<code>\` with a tinted background. Block nests
+\`<code>\` inside \`<pre>\` — \`<pre>\` carries the preformatted whitespace and
+\`<code>\` carries "this is code", which is the spec's pairing for a code block.
+
+### The block is keyboard-scrollable
+A long line scrolls horizontally, and a scrollable region that cannot be
+focused cannot be scrolled from the keyboard. The block therefore takes
+\`tabindex="0"\` with \`role="region"\` and an accessible name from \`label\`,
+defaulting to "Code", and shows a focus ring when reached by Tab.
+
+### Notes
+The inline variant sets its colour explicitly rather than inheriting, so it
+stays legible inside a dark section — an inherited light foreground on the
+fixed tint measured 1.12:1.
+
+Long unbroken tokens in inline code wrap rather than overflow a narrow column.
+        `
+      }
+    }
+  },
+  argTypes: {
+    block: {
+      control    : 'boolean',
+      description: 'Render a pre/code block instead of inline code.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: "false" }, category: 'Structure' }
+    },
+    label: {
+      control    : 'text',
+      description: 'Accessible name for the scrollable block, announced on focus. Block mode only.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "Code" }, category: 'Accessibility' }
+    }
+  }
+};
+
+export const Inline = () => html`
+    Use <bd-code>var(--color-blue-500)</bd-code> rather than a hex value.
+  `;
+
+export const Block = () => html`
+    <bd-code block>.button {
+  padding: var(--spacing-12) var(--spacing-20);
+}</bd-code>
+  `;