@0001-labs/design-system-1 0.3.0-alpha.28 → 0.3.0

package/DS1/0-face/layout-inspector.ts

@@ -1,4 +1,8 @@
-/** Inspect named page areas without changing their size, opacity, or interaction. */
+/**
+ * Inspect a page's layout without changing its size, opacity, or interaction:
+ * named areas in dashed outlines with their name and size, text and fields in
+ * green boxes, and every component (a custom element) outlined with its tag name.
+ */
 export function createLayoutInspector() {
   const root = document.documentElement;
   const overlay = document.createElement('div');
@@ -17,116 +21,110 @@ export function createLayoutInspector() {
       color-scheme: inherit !important;
     }
     :host([hidden]) { display: none !important; }
-    .veil, .areas { position: absolute; inset: 0; overflow: hidden; }
-    .veil { background: color-mix(in srgb, var(--page-background, Canvas) 78%, transparent); }
-    .area {
+    .boxes { position: absolute; inset: 0; overflow: hidden; }
+    .box {
       position: absolute;
       box-sizing: border-box;
-      display: grid;
-      place-items: center;
-      background: color-mix(in srgb, var(--pastel) 40%, transparent);
-      border: 1px solid color-mix(in srgb, var(--pastel) 65%, #82718d);
+      border: 1px solid var(--tint);
     }
-    .name {
-      box-sizing: border-box;
-      max-width: 100%;
-      padding: 3px 8px;
-      background: var(--page-background, Canvas);
-      color: var(--base-slate, CanvasText);
-      font: 400 14px/20px var(--font-regular, var(--typeface-regular, sans-serif));
-      text-align: center;
-      overflow-wrap: anywhere;
-    }
-    .area[data-container] {
-      background: transparent;
-    }
-    .area[data-container] > .name {
-      position: absolute;
-      top: 0;
-      left: 0;
-    }
-    .area[data-compact] .name {
+    .area { --tint: #efc9dc; border-style: dashed; }
+    .text { --tint: #bfe0cd; background: color-mix(in srgb, var(--tint) 18%, transparent); }
+    .field { --tint: #bfe0cd; background: color-mix(in srgb, var(--tint) 45%, transparent); }
+    .component { --tint: #d5c9ef; }
+    .tag {
       position: absolute;
-      bottom: 100%;
-      left: 50%;
-      transform: translateX(-50%);
-      width: max-content;
-      max-width: none;
-      padding: 2px 4px;
-      font-size: 12px;
-      line-height: 16px;
-      white-space: nowrap;
-    }
-    .dimensions {
-      display: block;
-      font-size: 12px;
-      line-height: 16px;
+      box-sizing: border-box;
+      display: flex;
+      gap: 6px;
+      padding: 0 4px;
+      background: var(--tint);
+      color: #2a2530;
+      font: 400 12px/16px var(--font-regular, var(--typeface-regular, sans-serif));
       font-variant-numeric: tabular-nums;
       white-space: nowrap;
     }
+    .area > .tag { top: -1px; right: -1px; }
+    .component > .tag { bottom: 100%; left: -1px; }
+    .component[data-inside] > .tag { bottom: auto; top: -1px; }
+    .measure { opacity: 0.7; }
     @media print { :host { display: none !important; } }
-  </style><div class="veil"></div><div class="areas"></div>`;
+  </style><div class="boxes"></div>`;
   document.body.appendChild(overlay);
-  const layer = shadow.querySelector<HTMLDivElement>('.areas')!;
-  const colors = ['#efc9dc', '#d5c9ef', '#c2d9eb', '#bfe0cd', '#eee3b7', '#efcfb8'];
+  const layer = shadow.querySelector<HTMLDivElement>('.boxes')!;
+  type Kind = 'area' | 'text' | 'field' | 'component';
+  // A page of thousands of words draws its first boxes and stops.
+  const limit = 2000;
+  const fields = new Set(['input', 'textarea', 'select', 'img', 'picture', 'svg', 'video', 'canvas', 'iframe']);
+  const skipped = new Set(['script', 'style', 'template', 'noscript', 'link', 'meta', 'slot']);
+  // Primitives drawn as what they show rather than named: words, an icon,
+  // and a gap with nothing to see.
+  const primitives: Record<string, Kind | 'none'> = { 'ds-text': 'text', 'ds-icon': 'field', 'ds-gap': 'none' };
   let frame = 0;
   let visible = false;
   const observed = new Set<HTMLElement>();
   const observedRoots = new Set<ShadowRoot>();
-
-  const getAreas = () => {
-    const named: HTMLElement[] = [];
-    const collect = (scope: Document | ShadowRoot | HTMLElement) => {
-      named.push(...scope.querySelectorAll<HTMLElement>('[data-ds-area]'));
-      scope.querySelectorAll<HTMLElement>('[data-ds-layout-root]').forEach((host) => {
-        if (!host.shadowRoot) return;
-        if (!observedRoots.has(host.shadowRoot)) {
-          mutations.observe(host.shadowRoot, { subtree: true, childList: true, characterData: true });
-          observedRoots.add(host.shadowRoot);
+  const collect = () => {
+    const areas: HTMLElement[] = [];
+    const words: [HTMLElement, Kind][] = [];
+    const components: HTMLElement[] = [];
+    const visit = (parent: Element | ShadowRoot, inText: boolean) => {
+      for (const element of Array.from(parent.children) as HTMLElement[]) {
+        const name = element.localName;
+        if (skipped.has(name) || element.hasAttribute('data-ds-layout-overlay') || element.hasAttribute('data-ds-grid-overlay')) continue;
+        if (element.hasAttribute('data-ds-area')) areas.push(element);
+        const primitive = primitives[name];
+        if (primitive === 'none') continue;
+        const component = !primitive && name.includes('-');
+        if (component) components.push(element);
+        if (fields.has(name) || primitive === 'field') {
+          if (!inText) words.push([element, 'field']);
+          continue;
         }
-        collect(host.shadowRoot);
-      });
+        const text = !inText && !component && (primitive === 'text' || Array.from(element.childNodes).some((node) =>
+          node.nodeType === Node.TEXT_NODE && node.textContent!.trim() !== ''));
+        if (text) words.push([element, 'text']);
+        // A design system component is drawn whole; an app's own component is
+        // opened, so what it holds is drawn too.
+        const content = element.shadowRoot;
+        if (content && !primitive && (!name.startsWith('ds-') || element.hasAttribute('data-ds-layout-root'))) {
+          if (!observedRoots.has(content)) {
+            mutations.observe(content, { subtree: true, childList: true, characterData: true });
+            observedRoots.add(content);
+          }
+          visit(content, inText || text);
+        }
+        visit(element, inText || text);
+      }
     };
-    collect(document.querySelector<HTMLElement>('[data-ds-inspect-active]') ?? document);
-    if (named.length) return named;
+    visit(document.querySelector<HTMLElement>('[data-ds-inspect-active]') ?? document.body, false);
     // Semantic fallback for pages that have not supplied their own area names.
-    return Array.from(document.querySelectorAll<HTMLElement>('header, main, section, footer, one-footer'))
+    const named = areas.length ? areas : Array.from(document.querySelectorAll<HTMLElement>('header, main, section, footer, one-footer'))
       .filter((element) => !element.querySelector('section, header, footer, one-footer'));
+    return { areas: named, words, components };
   };
-  const render = () => {
-    frame = 0;
-    if (!visible) return;
-    const areas = getAreas();
-    const current = new Set(areas);
-    for (const element of observed) {
-      if (!current.has(element)) { resize.unobserve(element); observed.delete(element); }
+
+  const tag = (name: string, ...measures: string[]) => {
+    const label = document.createElement('span');
+    label.className = 'tag';
+    label.textContent = name;
+    for (const measure of measures) {
+      const part = document.createElement('span');
+      part.className = 'measure';
+      part.textContent = measure;
+      label.appendChild(part);
     }
-    const fragments = document.createDocumentFragment();
-    areas.forEach((element, index) => {
-      if (!observed.has(element)) { resize.observe(element); observed.add(element); }
-      const rect = element.getBoundingClientRect();
-      if (!rect.width || !rect.height || rect.bottom <= 0 || rect.top >= innerHeight || rect.right <= 0 || rect.left >= innerWidth) return;
-      if (getComputedStyle(element).visibility === 'hidden') return;
-      const panel = document.createElement('div');
-      panel.className = 'area';
-      panel.toggleAttribute('data-container', !!element.shadowRoot?.querySelector('[data-ds-area]'));
-      panel.toggleAttribute('data-compact', rect.width < 80 || rect.height < 24);
-      panel.style.left = `${rect.left}px`;
-      panel.style.top = `${rect.top}px`;
-      panel.style.width = `${rect.width}px`;
-      panel.style.height = `${rect.height}px`;
-      panel.style.setProperty('--pastel', colors[index % colors.length] ?? null);
-      const label = document.createElement('span');
-      label.className = 'name';
+    return label;
+  };
+  const box = (element: HTMLElement, kind: Kind, rect: DOMRect) => {
+    const panel = document.createElement('div');
+    panel.className = `box ${kind}`;
+    panel.style.left = `${rect.left}px`;
+    panel.style.top = `${rect.top}px`;
+    panel.style.width = `${rect.width}px`;
+    panel.style.height = `${rect.height}px`;
+    if (kind === 'area') {
       const areaName = element.dataset.dsArea || element.getAttribute('aria-label') ||
         (element.localName === 'one-footer' ? 'footer' : element.localName);
-      label.textContent = areaName.replace(/[-_]/g, ' ').replace(/^./, (letter) => letter.toUpperCase());
-      const dimensions = document.createElement('span');
-      dimensions.className = 'dimensions';
-      dimensions.textContent = `${Number(rect.width.toFixed(1))} × ${Number(rect.height.toFixed(1))} px`;
-      label.appendChild(dimensions);
-      const ratio = document.createElement('span');
-      ratio.className = 'dimensions';
       // Reduce dimensions measured to a tenth of a CSS pixel; use a decimal
       // for fluid shapes whose exact fraction would be too long to read.
       const width = Math.max(1, Math.round(rect.width * 10));
@@ -138,14 +136,42 @@ export function createLayoutInspector() {
       }
       const horizontal = width / divisor;
       const vertical = height / divisor;
-      ratio.textContent = horizontal <= 100 && vertical <= 100
-        ? `${horizontal}:${vertical}`
-        : `≈ ${Number((rect.width / rect.height).toFixed(2))}:1`;
-      label.appendChild(ratio);
-      panel.appendChild(label);
-      fragments.appendChild(panel);
-    });
-    layer.replaceChildren(fragments);
+      panel.appendChild(tag(
+        areaName.replace(/[-_]/g, ' ').replace(/^./, (letter) => letter.toUpperCase()),
+        `${Number(rect.width.toFixed(1))} × ${Number(rect.height.toFixed(1))}`,
+        horizontal <= 100 && vertical <= 100 ? `${horizontal}:${vertical}` : `≈ ${Number((rect.width / rect.height).toFixed(2))}:1`,
+      ));
+    } else if (kind === 'component') {
+      // A name with no room above the component stands inside it.
+      panel.toggleAttribute('data-inside', rect.top < 16);
+      panel.appendChild(tag(element.localName));
+    }
+    return panel;
+  };
+  const render = () => {
+    frame = 0;
+    if (!visible) return;
+    const { areas, words, components } = collect();
+    const watched = new Set([...areas, ...components]);
+    for (const element of observed) {
+      if (!watched.has(element)) { resize.unobserve(element); observed.delete(element); }
+    }
+    for (const element of watched) {
+      if (!observed.has(element)) { resize.observe(element); observed.add(element); }
+    }
+    // Areas first, then words, then components, so component names lie on top.
+    const drawn: HTMLElement[] = [];
+    const draw = (element: HTMLElement, kind: Kind) => {
+      if (drawn.length >= limit) return;
+      const rect = element.getBoundingClientRect();
+      if (!rect.width || !rect.height || rect.bottom <= 0 || rect.top >= innerHeight || rect.right <= 0 || rect.left >= innerWidth) return;
+      if (getComputedStyle(element).visibility === 'hidden') return;
+      drawn.push(box(element, kind, rect));
+    };
+    areas.forEach((element) => draw(element, 'area'));
+    words.forEach(([element, kind]) => draw(element, kind));
+    components.forEach((element) => draw(element, 'component'));
+    layer.replaceChildren(...drawn);
   };
   const schedule = () => { if (visible && !frame) frame = requestAnimationFrame(render); };
   const resize = new ResizeObserver(schedule);

package/DS1/0-face/preference-options.ts

@@ -22,6 +22,10 @@ export interface PreferenceOptions {
    * (`--background`) by default. `false` leaves both to the page.
    */
   themePaper?: { light: string; dark: string } | false;
+  /** Where the shape is stored: `"ds-one:shape"` by default. */
+  shapeStorageKey?: string;
+  /** The shape for a visitor who has chosen none; without it the components keep their own corners. */
+  shapeDefault?: "square" | "rounded" | "circular";
 }
 
 declare global {

package/DS1/0-face/scaling.ts

@@ -5,7 +5,8 @@
  * mobile browser, or a touch screen whose shorter side is at most 820px) is
  * drawn as if the screen were 280 units wide: the scale is the page's width
  * over 280, never under 0.75 or over 2, so a 375px phone draws everything a
- * third larger.
+ * third larger. The page's width is never taken as more than the screen's, so
+ * a page that a phone has widened and zoomed out never scales itself larger.
  *
  * `startScaling()` puts the scale on the page and keeps it there through
  * resizes and turns; `applyScaling()` does it once. Both set `--sf` and, on a
@@ -145,10 +146,27 @@ export function applyScaling(options: ScalingOptions = {}): number {
   return applyPage(root ?? document.documentElement, config);
 }
 
+/**
+ * The screen's own width as it is held, in CSS pixels: the widest a page on it
+ * is laid out at, or 0 when the browser does not say. iOS gives the screen's
+ * upright width whichever way it is turned, so the side is taken by the turn.
+ */
+export function screenWidth(): number {
+  const { width = 0, height = 0 } = window.screen ?? {};
+  if (!width || !height) return 0;
+  const turn = window.screen.orientation?.type;
+  const landscape = turn ? turn.startsWith("landscape") : window.matchMedia?.("(orientation: landscape)").matches ?? width > height;
+  return landscape ? Math.max(width, height) : Math.min(width, height);
+}
+
 function applyPage(root: HTMLElement, config: Partial<ScalingConfig>): number {
   const mobile = detectMobileDevice();
-  // The page's width without its scroll bar.
-  const width = document.documentElement.clientWidth || window.innerWidth || 0;
+  // The page's width without its scroll bar, never more than the screen's: when something reaches
+  // past the edge, a phone's browser widens the page and zooms out, and a scale read from that
+  // width would draw everything larger, which keeps the page too wide and zoomed out.
+  const page = document.documentElement.clientWidth || window.innerWidth || 0;
+  const held = mobile ? screenWidth() : 0;
+  const width = held ? Math.min(page, held) : page;
   const factor = mobile ? calculateScalingFactor(width, { ...defaultScalingConfig, ...config }, window.devicePixelRatio || 1) : 1;
   root.style.setProperty("--sf", String(factor));
   root.toggleAttribute("data-mobile", mobile);

package/DS1/0-face/shape.ts

@@ -0,0 +1,43 @@
+/**
+ * Square, rounded or circular: the corners every component draws, chosen once
+ * and remembered (Ezo's Shape setting, for every product).
+ *
+ * The runtime is the second part of `theme-bootstrap.js`, which a page inlines
+ * in its <head> so the first paint already has the shape; imported here, it
+ * installs itself when the page did not. It marks the root with
+ * `data-ds-shape`, which `1-root/component-appearance.css` reads: square
+ * corners, rounded ones (squircles where the browser draws them) or pills. A
+ * visitor who has chosen nothing sees `shapeDefault` from
+ * `window.DS_ONE_PREFERENCES`, or the components' own corners. Offer the
+ * choice with `<ds-cycle type="shape">`.
+ */
+import "./theme-bootstrap.js";
+
+export type Shape = "square" | "rounded" | "circular";
+export const SHAPES: readonly Shape[] = ["square", "rounded", "circular"];
+
+/** `window.DS_ONE_SHAPE`, installed by `theme-bootstrap.js`. */
+export interface ShapeRuntime {
+  /** The shape in effect, or null when none is chosen. */
+  shape(): Shape | null;
+  /** Choose and remember a shape, and put it on the page. */
+  set(shape: Shape): void;
+  /** Read the stored choice and the options again, and put them on the page. */
+  apply(): Shape | null;
+}
+
+declare global {
+  interface Window {
+    DS_ONE_SHAPE?: ShapeRuntime;
+  }
+}
+
+/** The shape in effect: the stored choice, else `shapeDefault`, else rounded (the components' own corners). */
+export function getShape(): Shape {
+  return window.DS_ONE_SHAPE?.shape() ?? "rounded";
+}
+
+/** Choose and remember a shape. */
+export function setShape(shape: Shape): void {
+  window.DS_ONE_SHAPE?.set(shape);
+}

package/DS1/0-face/text-contrast.ts

@@ -0,0 +1,164 @@
+// Rendered text, across slots and open shadow roots. Token pairs alone cannot
+// tell what ink a component actually draws on its own surface.
+export type RGBA = [number, number, number, number];
+const clear: RGBA = [0, 0, 0, 0];
+export const TEXT_CONTRAST_MINIMUM = 4.5;
+export const contrastRatio = (a: RGBA, b: RGBA) => {
+  const luminance = (c: RGBA) => c.slice(0, 3).map(v => v <= .04045 ? v / 12.92 : ((v + .055) / 1.055) ** 2.4)
+    .reduce((sum, v, i) => sum + v * [0.2126, 0.7152, 0.0722][i]!, 0);
+  const [high, low] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (high! + .05) / (low! + .05);
+};
+export function composite(top: RGBA, bottom: RGBA): RGBA {
+  const alpha = top[3] + bottom[3] * (1 - top[3]);
+  return alpha ? [...[0, 1, 2].map(i => (top[i]! * top[3] + bottom[i]! * bottom[3] * (1 - top[3])) / alpha), alpha] as RGBA : [...clear];
+}
+const styleOf = (e: Element, pseudo?: string) => e.ownerDocument.defaultView!.getComputedStyle(e, pseudo);
+/** The painted parent, including the slot's styles and the shadow host's surface. */
+export function paintedParent(e: Element): Element | null {
+  return e.assignedSlot ?? e.parentElement ?? (e.getRootNode() as ShadowRoot).host ?? null;
+}
+
+/** Computed RGB stays full precision; modern colour spaces use the browser's sRGB canvas conversion. */
+export function colorReader(document: Document) {
+  const cache = new Map<string, RGBA | null>();
+  let context: CanvasRenderingContext2D | null | undefined;
+  return (value: string): RGBA | null => {
+    if (cache.has(value)) return cache.get(value)!;
+    let color: RGBA | null = null;
+    if (value === 'transparent') color = [...clear];
+    const rgb = /^rgba?\(([^)]+)\)$/.exec(value);
+    if (rgb) {
+      const parts = rgb[1]!.split(/[\s,/]+/).filter(Boolean);
+      if (parts.length >= 3) color = [...parts.slice(0, 3).map(v => parseFloat(v) / (v.endsWith('%') ? 100 : 255)), parts[3] ? parseFloat(parts[3]) / (parts[3].endsWith('%') ? 100 : 1) : 1] as RGBA;
+    } else if (value && document.defaultView?.CSS.supports('color', value)) {
+      context ??= document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+      if (context) {
+        context.clearRect(0, 0, 1, 1);
+        context.fillStyle = value;
+        context.fillRect(0, 0, 1, 1);
+        color = Array.from(context.getImageData(0, 0, 1, 1).data, v => v / 255) as RGBA;
+      }
+    }
+    cache.set(value, color);
+    return color;
+  };
+}
+
+type TextSample = { element: Element; text: string; pseudo?: string; paintElement?: Element };
+function visible(e: Element) {
+  if (!e.getClientRects().length && styleOf(e).display !== 'contents') return false;
+  if (styleOf(e).visibility !== 'visible') return false;
+  for (let p: Element | null = e; p; p = paintedParent(p)) {
+    const s = styleOf(p);
+    if (s.display === 'none' || s.contentVisibility === 'hidden' || Number(s.opacity) === 0
+      || p.matches(':disabled, [aria-disabled="true"], [data-ds-constraint-panel]')) return false;
+  }
+  return true;
+}
+
+/** Text nodes are visited once in their composed position; hidden menus and inactive controls do not count. */
+function textSamples(root: ParentNode): TextSample[] {
+  const samples: TextSample[] = [];
+  const seen = new Set<Node>();
+  function visit(node: Node) {
+    if (seen.has(node)) return;
+    seen.add(node);
+    if (node.nodeType === 3) {
+      const text = node.textContent?.trim();
+      const element = node.parentElement;
+      const paintElement = (node as Text).assignedSlot ?? element;
+      if (text && element && paintElement && visible(paintElement)) {
+        const range = element.ownerDocument.createRange();
+        range.selectNodeContents(node);
+        if (Array.from(range.getClientRects()).some(r => r.width > 0 && r.height > 0)) samples.push({ element, text, paintElement });
+      }
+      return;
+    }
+    if (node.nodeType === 1) {
+      const e = node as Element;
+      if (e.matches('script, style, template, noscript, option, [data-ds-constraint-panel]')) return;
+      if (visible(e)) {
+        if (e.localName === 'input' || e.localName === 'textarea') {
+          const input = e as HTMLInputElement;
+          if (!['hidden', 'checkbox', 'radio', 'range', 'color', 'file', 'image'].includes(input.type)) {
+            if (input.value) samples.push({ element: e, text: input.type === 'password' ? 'Password value' : input.value });
+            else if (input.placeholder) samples.push({ element: e, text: input.placeholder, pseudo: '::placeholder' });
+          }
+        } else if (e.localName === 'select') {
+          const text = (e as unknown as HTMLSelectElement).selectedOptions[0]?.textContent?.trim();
+          if (text) samples.push({ element: e, text });
+        }
+        for (const pseudo of ['::before', '::after']) {
+          const s = styleOf(e, pseudo);
+          if (/^["'].*["']$/.test(s.content) && s.content.slice(1, -1).trim() && s.display !== 'none' && s.visibility === 'visible' && Number(s.opacity) !== 0) {
+            samples.push({ element: e, text: s.content.slice(1, -1), pseudo });
+          }
+        }
+      }
+      if (e.localName === 'slot') {
+        const assigned = (e as HTMLSlotElement).assignedNodes({ flatten: true });
+        (assigned.length ? assigned : Array.from(e.childNodes)).forEach(visit);
+        return;
+      }
+      if (e.shadowRoot) { visit(e.shadowRoot); return; }
+      // Values/placeholder above represent these controls, not their fallback children.
+      if (e.matches('input, textarea, select')) return;
+    }
+    node.childNodes.forEach(visit);
+  }
+  visit(root as Node);
+  return samples;
+}
+
+export type TextContrastResult = { element: Element; text: string; ratio?: number; reason?: string; foreground?: string; background?: string };
+const rgbLabel = (c: RGBA) => `rgb(${c.slice(0, 3).map(v => Math.round(v * 255)).join(', ')})`;
+
+export function measureTextContrast(root: ParentNode): TextContrastResult[] {
+  const document = (root as Node).ownerDocument ?? root as Document;
+  const read = colorReader(document);
+  const styles = new Map<Element, CSSStyleDeclaration>();
+  const style = (e: Element) => { if (!styles.has(e)) styles.set(e, styleOf(e)); return styles.get(e)!; };
+  return textSamples(root).map(({ element, text, pseudo, paintElement = element }) => {
+    const result: TextContrastResult = { element, text: text.replace(/\s+/g, ' ').slice(0, 60) };
+    const inkStyle = pseudo ? styleOf(element, pseudo) : style(paintElement);
+    let foreground = read(inkStyle.getPropertyValue('-webkit-text-fill-color') || inkStyle.color);
+    let background: RGBA = [...clear];
+    if (!foreground) return { ...result, reason: 'The rendered text colour could not be resolved.' };
+    const chain: CSSStyleDeclaration[] = [];
+    if (pseudo) chain.push(inkStyle);
+    for (let p: Element | null = paintElement; p; p = paintedParent(p)) chain.push(style(p));
+    for (const s of chain) {
+      if (s.mixBlendMode && s.mixBlendMode !== 'normal' || s.filter && s.filter !== 'none' || s.backdropFilter && s.backdropFilter !== 'none') {
+        return { ...result, reason: 'A blend or filter needs a visual contrast review.' };
+      }
+      if (background[3] < 1 && s.backgroundImage && s.backgroundImage !== 'none') {
+        return { ...result, reason: 'Text over an image or gradient needs a visual contrast review.' };
+      }
+      const fill = read(s.backgroundColor);
+      if (!fill) return { ...result, reason: 'The rendered background colour could not be resolved.' };
+      foreground = composite(foreground, fill);
+      background = composite(background, fill);
+      const opacity = Number(s.opacity);
+      foreground[3] *= opacity;
+      background[3] *= opacity;
+    }
+    // With no declared page background, compare both possible user-agent canvases.
+    // Usually the opaque html/body surface makes these identical.
+    const candidates: RGBA[] = [[1, 1, 1, 1], [0, 0, 0, 1]];
+    const pairs = candidates.map(canvas => ({ foreground: composite(foreground!, canvas), background: composite(background, canvas) }));
+    const values = pairs.map(pair => ({ ...pair, ratio: contrastRatio(pair.foreground, pair.background) })).sort((a, b) => a.ratio - b.ratio);
+    const worst = values[0]!;
+    if (background[3] < 1 && worst.ratio < TEXT_CONTRAST_MINIMUM) return { ...result, reason: 'Declare an opaque page background so text contrast can be verified.' };
+    return { ...result, ratio: worst.ratio, foreground: rgbLabel(worst.foreground), background: rgbLabel(worst.background) };
+  });
+}
+
+export function inspectTextContrast(root: ParentNode) {
+  return measureTextContrast(root).flatMap(result => {
+    const label = `“${result.text}”`;
+    // What cannot be measured is a review for a person, not a broken rule; a colour that could not be read is.
+    if (result.reason) return [{ element: result.element, message: `${label}: ${result.reason}`, review: /visual contrast review/.test(result.reason) }];
+    return result.ratio! < TEXT_CONTRAST_MINIMUM ? [{ element: result.element, message: `${label} has ${result.ratio!.toFixed(2)}:1 text contrast (${result.foreground} on ${result.background}); at least ${TEXT_CONTRAST_MINIMUM}:1 is required.` }] : [];
+  });
+}

package/DS1/0-face/theme-bootstrap.js

@@ -182,3 +182,46 @@
   window.addEventListener("storage", function (event) { if (event.key === null || event.key === key()) apply(); });
   window.addEventListener("pageshow", function () { apply(); });
 })();
+
+/**
+ * The shape, on before the first paint as well: square, rounded or circular,
+ * the corners every component draws (component-appearance.css keys on
+ * `data-ds-shape` on the root). Rounded draws squircles where the browser
+ * can. With nothing stored it is `shapeDefault` from
+ * `window.DS_ONE_PREFERENCES`, and without that the root carries no shape and
+ * the components keep their own corners. It is stored under `shapeStorageKey`
+ * (`"ds-one:shape"`), applied again when another tab stores one, and changed
+ * with `window.DS_ONE_SHAPE.set(shape)`, which dispatches `shape-changed` on
+ * window with `{ shape }`.
+ */
+(function () {
+  if (typeof window === "undefined" || typeof document === "undefined" || window.DS_ONE_SHAPE) return;
+  var root = document.documentElement;
+  var SHAPES = ["square", "rounded", "circular"];
+  var session = null;
+  function options() { return window.DS_ONE_PREFERENCES || {}; }
+  function key() { return options().shapeStorageKey || "ds-one:shape"; }
+  function stored() {
+    if (session) return session;
+    try {
+      var saved = window.localStorage.getItem(key());
+      if (SHAPES.indexOf(saved) >= 0) return saved;
+    } catch { /* Storage can be blocked. */ }
+    return SHAPES.indexOf(options().shapeDefault) >= 0 ? options().shapeDefault : null;
+  }
+  function apply() {
+    var shape = stored();
+    if (shape) root.setAttribute("data-ds-shape", shape);
+    else root.removeAttribute("data-ds-shape");
+    return shape;
+  }
+  function set(shape) {
+    if (SHAPES.indexOf(shape) < 0) return;
+    try { window.localStorage.setItem(key(), shape); session = null; } catch { session = shape; }
+    apply();
+    window.dispatchEvent(new CustomEvent("shape-changed", { detail: { shape: shape } }));
+  }
+  window.DS_ONE_SHAPE = { shape: stored, set: set, apply: apply };
+  apply();
+  window.addEventListener("storage", function (event) { if (event.key === null || event.key === key()) apply(); });
+})();

package/DS1/0-face/toast-queue.ts

@@ -21,6 +21,8 @@
  * says `important: false`.
  */
 
+import { reportFailure, type Failure } from "./failures";
+
 export type ToastId = string | number;
 export type ToastType = "default" | "success" | "info" | "warning" | "error" | "loading";
 export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
@@ -31,6 +33,9 @@ export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-le
  */
 export interface ToastButton { label: string; onClick?: (event: MouseEvent) => void; href?: string }
 export interface ToastOptions {
+  /** A real failed operation to report. Omit for validation and expected refusals.
+   * Authored code and summary only; the visible title/description are never reported. */
+  failure?: Failure;
   /** Reuse an id to update a toast in place, as Sonner does. */
   id?: ToastId;
   description?: string;
@@ -122,6 +127,7 @@ function show(title: string, type: ToastType, options: ToastOptions = {}): Toast
   const data: ToastData = { ...options, ...(important === undefined ? {} : { important }), id, title, type };
   // A copy: a listener may add or remove listeners while it hears the toast.
   for (const listener of Array.from(state.toasters.size ? state.toasters : state.fallbacks)) listener({ toast: data });
+  if (type === "error" && options.failure) reportFailure(options.failure);
   return id;
 }
 
@@ -142,7 +148,7 @@ export const toast = Object.assign(
       Promise.resolve(typeof promise === "function" ? promise() : promise)
         .then(
           value => { show(typeof success === "function" ? success(value) : success, "success", { ...options, id }); },
-          reason => { show(typeof error === "function" ? error(reason) : error, "error", { ...options, id }); },
+          reason => { show(typeof error === "function" ? error(reason) : error, "error", { ...options, id, ...(options.failure ? { failure: { ...options.failure, error: reason } } : {}) }); },
         )
         .finally(() => done?.());
       return id;

package/DS1/0-face/translations/da.json

@@ -30,6 +30,10 @@
     "Light": "Lys",
     "Dark": "Mørk",
     "System": "System",
+    "Shape": "Form",
+    "Square": "Firkantet",
+    "Rounded": "Afrundet",
+    "Circular": "Cirkulær",
     "Note": "Note",
     "Page": "Side",
     "Red": "Rød",
@@ -124,6 +128,11 @@
     "Total": "I alt",
     "End date": "Slutdato",
     "Include time": "Medtag klokkeslæt",
-    "Time": "Klokkeslæt"
+    "Time": "Klokkeslæt",
+    "Day": "Dag",
+    "Week": "Uge",
+    "Month": "Måned",
+    "Swimlane": "Baner",
+    "View": "Visning"
   }
 }

package/DS1/0-face/translations/de.json

@@ -30,6 +30,10 @@
     "Light": "Hell",
     "Dark": "Dunkel",
     "System": "System",
+    "Shape": "Form",
+    "Square": "Eckig",
+    "Rounded": "Abgerundet",
+    "Circular": "Rund",
     "Note": "Notiz",
     "Page": "Seite",
     "Red": "Rot",
@@ -124,6 +128,11 @@
     "Total": "Gesamt",
     "End date": "Enddatum",
     "Include time": "Uhrzeit hinzufügen",
-    "Time": "Uhrzeit"
+    "Time": "Uhrzeit",
+    "Day": "Tag",
+    "Week": "Woche",
+    "Month": "Monat",
+    "Swimlane": "Bahnen",
+    "View": "Ansicht"
   }
 }