@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/tokens/story-chrome.js

@@ -0,0 +1,503 @@
+/**
+ * Shared chrome for the Design Tokens stories.
+ *
+ * Every page in that section uses this module so they stay consistent by
+ * construction rather than by five copies of the same CSS. It also carries the
+ * token-discovery and contrast helpers, so a docs page never hardcodes a scale
+ * that could drift from the tokens themselves.
+ *
+ * Not a story file: Storybook only globs *.stories.js.
+ */
+import { html } from 'lit';
+
+/* ============================================================
+   Token discovery — read the real values out of the loaded CSS
+   ============================================================ */
+
+/** Concatenated text of every readable stylesheet in the document. */
+export function readAllCssText() {
+  let text = '';
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue; // cross-origin sheet, skip
+    }
+    for (const rule of Array.from(rules)) text += `${rule.cssText}\n`;
+  }
+  return text;
+}
+
+/** Resolves a custom property to its computed value on :root. */
+export function resolve(token) {
+  return getComputedStyle(document.documentElement).getPropertyValue(token)
+    .trim();
+}
+
+/**
+ * Finds every custom property whose name matches `pattern`, in declaration
+ * order, de-duplicated. `pattern` must have the token name as group 1.
+ */
+export function discoverTokens(cssText, pattern) {
+  const seen = new Set();
+  const found = [];
+  for (const match of cssText.matchAll(pattern)) {
+    const token = match[1];
+    if (seen.has(token)) continue;
+    seen.add(token);
+    found.push(match);
+  }
+  return found;
+}
+
+/** Maps each palette/primitive token to the tokens that reference it. */
+export function discoverConsumers(cssText) {
+  const consumers = new Map();
+  const pattern = /(--[A-Za-z0-9-]+)\s*:\s*var\(\s*(--[A-Za-z0-9-]+)\s*\)/g;
+  for (const [, token, referenced] of cssText.matchAll(pattern)) {
+    if (!consumers.has(referenced)) consumers.set(referenced, new Set());
+    consumers.get(referenced).add(token);
+  }
+  return consumers;
+}
+
+/* ============================================================
+   Colour maths — WCAG 2.1 relative luminance and contrast
+   ============================================================ */
+
+export const INK = '#151719'; // --color-neutral-900
+export const PAPER = '#ffffff'; // --color-neutral-0
+
+/** Resolves any CSS colour notation to [r, g, b] via the browser. */
+export function toRgb(value) {
+  const probe = document.createElement('span');
+  probe.style.cssText = 'position:absolute;visibility:hidden';
+  probe.style.color = value;
+  document.body.appendChild(probe);
+  const computed = getComputedStyle(probe).color;
+  probe.remove();
+  const parts = computed.match(/-?[\d.]+/g);
+  return parts ? parts.slice(0, 3).map(Number) : [0, 0, 0];
+}
+
+function luminance([r, g, b]) {
+  const [lr, lg, lb] = [r, g, b]
+    .map(channel => channel / 255)
+    .map(channel => (channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+}
+
+export function contrast(a, b) {
+  const [hi, lo] = [luminance(toRgb(a)), luminance(toRgb(b))].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export function toHex(value) {
+  return `#${toRgb(value)
+    .map(channel => Math.round(channel).toString(16)
+      .padStart(2, '0'))
+    .join('')}`;
+}
+
+/** WCAG level reached by a contrast ratio for normal-size body text. */
+export function wcagLevel(ratio) {
+  if (ratio >= 7) return { label: 'AAA', pass: true };
+  if (ratio >= 4.5) return { label: 'AA', pass: true };
+  if (ratio >= 3) return { label: '18pt', pass: true }; // large text / UI edges only
+  return { label: 'fail', pass: false };
+}
+
+export function levelBadge(ratio) {
+  const { label, pass } = wcagLevel(ratio);
+  return html`<span class="level" data-pass=${pass}>${label}</span>`;
+}
+
+/* ============================================================
+   Shared styles
+   ============================================================ */
+
+export const chromeStyles = html`
+  <style>
+    /* The Storybook canvas is transparent, so it inherits the OS colour
+       scheme. Paint an explicit surface: there are no dark-mode tokens yet. */
+    .docs {
+      font-family: var(--typography-fontFamily-sans);
+      color: var(--color-neutral-900);
+      background: var(--color-neutral-0);
+      padding: var(--spacing-24);
+      box-sizing: border-box;
+    }
+
+    .docs-inner {
+      max-width: 1180px;
+    }
+
+    .docs h1 {
+      font-size: var(--typography-fontSize-2xl);
+      font-weight: var(--typography-fontWeight-semibold);
+      margin: 0 0 var(--spacing-8);
+    }
+
+    .docs-lede {
+      font-size: var(--typography-fontSize-sm);
+      line-height: var(--typography-lineHeight-normal);
+      color: var(--color-neutral-600);
+      margin: 0 0 var(--spacing-16);
+      max-width: 68ch;
+    }
+
+    .docs-note {
+      font-size: var(--typography-fontSize-xs);
+      line-height: var(--typography-lineHeight-normal);
+      color: var(--color-neutral-700);
+      background: var(--color-neutral-50);
+      border-radius: var(--radius-md);
+      padding: var(--spacing-12) var(--spacing-16);
+      margin-bottom: var(--spacing-32);
+    }
+
+    .docs-note b {
+      font-weight: var(--typography-fontWeight-semibold);
+      color: var(--color-neutral-900);
+    }
+
+    .docs-note code,
+    .docs-lede code {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-code-inline-fontSize);
+    }
+
+    /* --- sections --- */
+    .section {
+      margin-bottom: var(--spacing-40);
+    }
+
+    .section-head {
+      display: flex;
+      align-items: baseline;
+      gap: var(--spacing-8);
+      margin-bottom: var(--spacing-12);
+    }
+
+    .section-name {
+      font-size: var(--typography-fontSize-lg);
+      font-weight: var(--typography-fontWeight-semibold);
+      margin: 0;
+    }
+
+    .section-meta {
+      font-size: var(--typography-fontSize-xs);
+      font-family: var(--typography-fontFamily-mono);
+      color: var(--color-neutral-500);
+    }
+
+    /* --- reference tables --- */
+    /* Wide content scrolls inside its own container, never the page. */
+    .table-scroll {
+      overflow-x: auto;
+    }
+
+    .docs table {
+      border-collapse: collapse;
+      width: 100%;
+      font-size: var(--typography-fontSize-xs);
+    }
+
+    .docs caption {
+      /* the visible heading is .section-head; this is for screen readers */
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip-path: inset(50%);
+    }
+
+    .docs th {
+      text-align: left;
+      font-weight: var(--typography-fontWeight-semibold);
+      color: var(--color-neutral-600);
+      font-size: var(--typography-fontSize-xxs);
+      text-transform: uppercase;
+      letter-spacing: var(--typography-letterSpacing-wide);
+      padding: 0 var(--spacing-12) var(--spacing-8);
+      border-bottom: var(--border-width-1) solid var(--color-neutral-200);
+      white-space: nowrap;
+    }
+
+    .docs td {
+      padding: var(--spacing-8) var(--spacing-12);
+      border-bottom: var(--border-width-1) solid var(--color-neutral-100);
+      vertical-align: middle;
+    }
+
+    .docs tbody tr:last-child td {
+      border-bottom: 0;
+    }
+
+    /* --- cell primitives --- */
+    .mono {
+      font-family: var(--typography-fontFamily-mono);
+      white-space: nowrap;
+    }
+
+    .num {
+      font-family: var(--typography-fontFamily-mono);
+      font-variant-numeric: tabular-nums;
+      white-space: nowrap;
+      color: var(--color-neutral-700);
+    }
+
+    /* the rendered pixel value beside a rem one, so a step is recognisable
+       without doing the arithmetic */
+    .px-hint {
+      margin-left: var(--spacing-8);
+      color: var(--color-neutral-500);
+      font-size: var(--typography-fontSize-xxs);
+    }
+
+    .muted {
+      color: var(--color-neutral-500);
+    }
+
+    .unused {
+      color: var(--color-neutral-400);
+    }
+
+    .token-copy {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xs);
+      color: var(--color-neutral-900);
+      background: none;
+      border: 0;
+      padding: 0;
+      cursor: copy;
+      text-align: left;
+      white-space: nowrap;
+    }
+
+    .token-copy:hover {
+      color: var(--color-blue-600);
+      text-decoration: underline;
+    }
+
+    .token-copy:focus-visible {
+      outline: var(--focus-outline-traditional);
+      outline-offset: var(--focus-outline-offset);
+      border-radius: var(--radius-sm);
+    }
+
+    .copied {
+      color: var(--color-green-700);
+      font-weight: var(--typography-fontWeight-semibold);
+    }
+
+    /* --- WCAG level badge --- */
+    .level {
+      display: inline-block;
+      min-width: 3.2em;
+      margin-left: var(--spacing-6);
+      padding: 1px var(--spacing-6);
+      border-radius: var(--radius-sm);
+      font-family: var(--typography-fontFamily-sans);
+      font-size: var(--typography-fontSize-xxs);
+      font-weight: var(--typography-fontWeight-semibold);
+      text-align: center;
+    }
+
+    .level[data-pass='true'] {
+      color: var(--color-green-800);
+      background: var(--color-green-50);
+    }
+
+    .level[data-pass='false'] {
+      color: var(--color-red-800);
+      background: var(--color-red-50);
+    }
+
+    /* --- usage disclosure --- */
+    details.usage summary {
+      cursor: pointer;
+      white-space: nowrap;
+    }
+
+    details.usage summary:focus-visible {
+      outline: var(--focus-outline-traditional);
+      outline-offset: var(--focus-outline-offset);
+      border-radius: var(--radius-sm);
+    }
+
+    details.usage ul {
+      margin: var(--spacing-6) 0 0;
+      padding-left: var(--spacing-16);
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+      line-height: var(--typography-lineHeight-normal);
+    }
+
+    .usage-count {
+      font-weight: var(--typography-fontWeight-semibold);
+      color: var(--color-blue-700);
+    }
+
+    /* --- specimen frame, for stories that show rendered output --- */
+    .specimen {
+      background: var(--color-neutral-25);
+      border: var(--border-width-1) solid var(--color-neutral-100);
+      border-radius: var(--radius-md);
+      padding: var(--spacing-16);
+    }
+  </style>
+`;
+
+/* ============================================================
+   Page and section shells
+   ============================================================ */
+
+export function docsPage({ title, lede, note, children }) {
+  return html`
+    ${chromeStyles}
+    <div class="docs">
+      <div class="docs-inner">
+        <h1>${title}</h1>
+        ${lede ? html`<p class="docs-lede">${lede}</p>` : ''}
+        ${note ? html`<div class="docs-note">${note}</div>` : ''}
+        ${children}
+      </div>
+    </div>
+  `;
+}
+
+export function refSection({ name, meta, children }) {
+  return html`
+    <section class="section">
+      <div class="section-head">
+        <h2 class="section-name">${name}</h2>
+        ${meta ? html`<span class="section-meta">${meta}</span>` : ''}
+      </div>
+      ${children}
+    </section>
+  `;
+}
+
+/** A token name that copies its var() reference when clicked. */
+export function copyToken(token) {
+  const copy = async event => {
+    const button = event.currentTarget;
+    const original = button.textContent;
+    try {
+      // Rejects in an insecure context, on denied permission, or when the
+      // document is not focused.
+      await navigator.clipboard.writeText(`var(${token})`);
+      button.innerHTML = '<span class="copied">copied</span>';
+    } catch {
+      button.innerHTML = '<span class="copied">copy blocked</span>';
+    }
+    setTimeout(() => {
+      button.textContent = original;
+    }, 1200);
+  };
+
+  return html`
+    <button class="token-copy" @click=${copy} title="Copy var(${token})">${token}</button>
+  `;
+}
+
+/** Lists the tokens that consume a given token, behind a disclosure. */
+export function usageCell(consumerSet) {
+  if (!consumerSet || !consumerSet.size) return html`<span class="unused">unused</span>`;
+  const names = [...consumerSet].sort();
+  return html`
+    <details class="usage">
+      <summary>
+        <span class="usage-count">${names.length}</span> token${names.length === 1 ? '' : 's'}
+      </summary>
+      <ul>
+        ${names.map(name => html`<li>${name}</li>`)}
+      </ul>
+    </details>
+  `;
+}
+
+/**
+ * Standard caveat for the "Referenced by" column.
+ *
+ * This page can only see stylesheets in the document. Component CSS lives
+ * inside shadow roots and is unreachable, so the column counts token-to-token
+ * references only — a primitive with no listed references may still be used
+ * directly by components.
+ */
+export const referenceNote = html`<b>Referenced by</b> counts other
+  <em>tokens</em> that point at this one. Component CSS lives inside shadow
+  roots and cannot be read from this page, so a token listed as unreferenced
+  may still be used directly in a component.`;
+
+/**
+ * Token / value / optional visual / references table, shared by the primitive
+ * pages. `visual` receives (token, value) and returns the cell contents.
+ */
+export function primitiveTable({ caption, tokens, consumers, visual, visualHeader = 'Preview', valueClass = 'num' }) {
+  const rows = tokens
+    .map(token => {
+      const value = resolve(token);
+      return { token, value, px: toPx(value) };
+    })
+    .filter(row => row.value);
+
+  return html`
+    <div class="table-scroll">
+      <table>
+        <caption>${caption}</caption>
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">Value</th>
+            ${visual ? html`<th scope="col">${visualHeader}</th>` : ''}
+            <th scope="col">Referenced by</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${rows.map(
+            ({ token, value, px }) => html`
+              <tr>
+                <td>${copyToken(token)}</td>
+                <td class=${valueClass}>
+                  ${value}${px ? html`<span class="px-hint">${px}</span>` : ''}
+                </td>
+                ${visual ? html`<td>${visual(token, value)}</td>` : ''}
+                <td>${usageCell(consumers.get(token))}</td>
+              </tr>
+            `
+          )}
+        </tbody>
+      </table>
+    </div>
+  `;
+}
+
+/**
+ * The rendered pixel value of a rem length, measured rather than assumed, so a
+ * browser at a non-default root font size reports its own truth.
+ *
+ * rem only. An em value is relative to the element's own font size, so there
+ * is no single pixel equivalent to state — quoting one would be wrong rather
+ * than merely imprecise. px values, 0, unitless numbers, keywords and colours
+ * are left alone too.
+ */
+export function toPx(value) {
+  const v = String(value ?? '').trim();
+  if (!/^[\d.]+rem$/.test(v)) return '';
+  const probe = document.createElement('div');
+  probe.style.cssText = `position:absolute;visibility:hidden;height:0;width:${v}`;
+  document.body.appendChild(probe);
+  const px = getComputedStyle(probe).width;
+  probe.remove();
+  return px === v ? '' : px;
+}
+
+/** Tokens matching a prefix, in declaration order, read from the loaded CSS. */
+export function tokensFor(cssText, prefix) {
+  const pattern = new RegExp(`(--${prefix}[A-Za-z0-9-]*)\\s*:`, 'g');
+  return discoverTokens(cssText, pattern).map(match => match[1]);
+}