@ultimat3/ui 24.0.0 → 25.1.0

package/src/components/Section.tsx

@@ -6,6 +6,7 @@ import type { JSX } from 'solid-js';
 import { useId } from '../a11y';
 import { cx } from '../cx';
 import { type HeadingLevel, headingTag } from './heading-level';
+import { headingNode } from './heading-node';
 import styles from './Section.module.scss';
 
 export interface SectionProps {
@@ -23,33 +24,51 @@ export interface SectionProps {
 }
 
 export function Section(props: SectionProps): JSX.Element {
-  const Tag = props.as ?? 'section';
-  const Heading = headingTag(props.level ?? 2);
+  // Resolved once, so an off-scale level throws `X_UI_INVALID_VALUE` here as it always did.
+  const heading = headingTag(props.level ?? 2);
   const titleId = useId('section');
-
-  return (
-    <Tag
-      class={cx(styles['section'], props.class)}
-      aria-labelledby={props.title === undefined ? undefined : titleId}
-    >
-      {props.title === undefined && props.actions === undefined ? null : (
-        <div class={styles['head']}>
-          <div class={styles['text']}>
-            {props.title === undefined ? null : (
-              <Heading id={titleId} class={styles['title']}>
-                {props.title}
-              </Heading>
-            )}
-            {props.description === undefined ? null : (
-              <p class={styles['description']}>{props.description}</p>
-            )}
-          </div>
-          {props.actions === undefined ? null : (
-            <div class={styles['actions']}>{props.actions}</div>
+  const cls = (): string => cx(styles['section'], props.class);
+  const labelledBy = (): string | undefined => (props.title === undefined ? undefined : titleId);
+  const title = (): string | undefined => props.title;
+  const head = (): JSX.Element =>
+    props.title === undefined && props.actions === undefined ? null : (
+      <div class={styles['head']}>
+        <div class={styles['text']}>
+          {props.title === undefined
+            ? null
+            : headingNode(heading, { id: titleId, class: styles['title'] }, title)}
+          {props.description === undefined ? null : (
+            <p class={styles['description']}>{props.description}</p>
           )}
         </div>
-      )}
-      <div class={styles['body']}>{props.children}</div>
-    </Tag>
-  );
+        {props.actions === undefined ? null : <div class={styles['actions']}>{props.actions}</div>}
+      </div>
+    );
+  const body = (): JSX.Element => <div class={styles['body']}>{props.children}</div>;
+
+  // One intrinsic per case, never `const Tag = props.as; <Tag>`: the island build compiles a
+  // capitalised tag to `createComponent(Tag)` and calls the string (#488, `intrinsic-root.test.ts`).
+  switch (props.as ?? 'section') {
+    case 'article':
+      return (
+        <article class={cls()} aria-labelledby={labelledBy()}>
+          {head()}
+          {body()}
+        </article>
+      );
+    case 'aside':
+      return (
+        <aside class={cls()} aria-labelledby={labelledBy()}>
+          {head()}
+          {body()}
+        </aside>
+      );
+    case 'section':
+      return (
+        <section class={cls()} aria-labelledby={labelledBy()}>
+          {head()}
+          {body()}
+        </section>
+      );
+  }
 }

package/src/components/Stack.tsx

@@ -28,22 +28,63 @@ const ALIGN: Readonly<Record<Align, string>> = {
 };
 
 export function Stack(props: StackProps): JSX.Element {
-  const Tag = props.as ?? 'div';
-  return (
-    <Tag
-      class={cx(
-        styles['stack'],
-        styles[`direction-${props.direction ?? 'column'}`],
-        props.wrap === true && styles['wrap'],
-        props.class,
-      )}
-      style={{
-        '--stack-gap': `var(--space-${props.gap ?? 4})`,
-        '--stack-align': ALIGN[props.align ?? 'stretch'],
-        '--stack-justify': ALIGN[props.justify ?? 'start'],
-      }}
-    >
-      {props.children}
-    </Tag>
-  );
+  const cls = (): string =>
+    cx(
+      styles['stack'],
+      styles[`direction-${props.direction ?? 'column'}`],
+      props.wrap === true && styles['wrap'],
+      props.class,
+    );
+  const style = (): JSX.CSSProperties => ({
+    '--stack-gap': `var(--space-${props.gap ?? 4})`,
+    '--stack-align': ALIGN[props.align ?? 'stretch'],
+    '--stack-justify': ALIGN[props.justify ?? 'start'],
+  });
+
+  // One intrinsic per case, never `const Tag = props.as; <Tag>`: the island build compiles a
+  // capitalised tag to `createComponent(Tag)` and calls the string (#488, `intrinsic-root.test.ts`).
+  switch (props.as ?? 'div') {
+    case 'ul':
+      return (
+        <ul class={cls()} style={style()}>
+          {props.children}
+        </ul>
+      );
+    case 'ol':
+      return (
+        <ol class={cls()} style={style()}>
+          {props.children}
+        </ol>
+      );
+    case 'nav':
+      return (
+        <nav class={cls()} style={style()}>
+          {props.children}
+        </nav>
+      );
+    case 'section':
+      return (
+        <section class={cls()} style={style()}>
+          {props.children}
+        </section>
+      );
+    case 'header':
+      return (
+        <header class={cls()} style={style()}>
+          {props.children}
+        </header>
+      );
+    case 'footer':
+      return (
+        <footer class={cls()} style={style()}>
+          {props.children}
+        </footer>
+      );
+    case 'div':
+      return (
+        <div class={cls()} style={style()}>
+          {props.children}
+        </div>
+      );
+  }
 }

package/src/components/Table.module.scss

@@ -75,3 +75,33 @@
 .striped :global(tbody tr:nth-child(even) td) {
   background: t.role('bg-soft', 0.6);
 }
+
+// The first column stays at the inline start while the scroller moves the rest. A sticky cell
+// needs an opaque background or the scrolled cells show through it; the edge line is a border,
+// not an inset shadow, because a border is logical and mirrors under RTL by itself.
+.table[data-sticky-first] :global(:is(th, td):first-child) {
+  position: sticky;
+  inset-inline-start: 0;
+  z-index: t.z(raised);
+  background-color: t.role('surface');
+  border-inline-end: 1px solid t.role('line');
+}
+
+.table[data-sticky-first] :global(th:first-child) {
+  background-color: t.role('bg-soft');
+}
+
+// The corner cell is sticky on both axes, so it must sit above both the header row and the column.
+.sticky[data-sticky-first] :global(thead th:first-child) {
+  z-index: t.z(sticky);
+}
+
+.sticky[data-sticky-first] :global(thead th:not(:first-child)) {
+  z-index: t.z(raised);
+}
+
+// A striped row keeps its stripe on the pinned cell: the translucent stripe laid over the opaque
+// surface, so the stripe shows and the scrolled cells still do not.
+.striped[data-sticky-first] :global(tbody tr:nth-child(even) td:first-child) {
+  background: linear-gradient(t.role('bg-soft', 0.6), t.role('bg-soft', 0.6)), t.role('surface');
+}

package/src/components/Table.tsx

@@ -1,6 +1,6 @@
-// Presentational table. Owns two things every hand-rolled table gets wrong:
-// a sticky header, and horizontal overflow contained inside the table's own
-// scroll container so the page body never scrolls sideways.
+// Presentational table. Owns what every hand-rolled table gets wrong: a sticky header, a first
+// column that stays put while the rest scrolls, and horizontal overflow contained inside the
+// table's own scroll container so the page body never scrolls sideways.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
@@ -13,6 +13,14 @@ export interface TableProps {
   /** Hide the caption visually while keeping it for assistive tech. */
   hideCaption?: boolean | undefined;
   stickyHeader?: boolean | undefined;
+  /** Pins the first column at the inline start while the table scrolls sideways. Off by default. */
+  stickyFirstColumn?: boolean | undefined;
+  /**
+   * Declares `role="table"` on the element itself. For a caller that restyles the table's
+   * `display` (DataTable's card view): WebKit drops a table's semantics once `display` changes,
+   * and the explicit role is what keeps it a table. The rows and cells are the caller's to mark.
+   */
+  explicitRoles?: boolean | undefined;
   density?: 'comfortable' | 'compact' | undefined;
   /** Zebra striping. Off by default — a border is usually enough. */
   striped?: boolean | undefined;
@@ -27,6 +35,9 @@ export function Table(props: TableProps): JSX.Element {
     // inside it — and a <section> with no name is generic, so the table keeps its own caption.
     <section class={cx(styles['scroller'], props.class)} tabindex="0">
       <table
+        role={props.explicitRoles === true ? 'table' : undefined}
+        // An attribute, not a class: it is state the stylesheet and a test both read.
+        data-sticky-first={props.stickyFirstColumn === true ? '' : undefined}
         class={cx(
           styles['table'],
           styles[`density-${props.density ?? 'comfortable'}`],

package/src/components/Tabs.tsx

@@ -2,7 +2,7 @@
 // between them, Home/End jump to the ends, and arrow direction follows `dir`.
 
 import type { JSX } from 'solid-js';
-import { ariaBool, createRovingTabindex, useId } from '../a11y';
+import { ariaBool, rovingTabindex, useId } from '../a11y';
 import { cx } from '../cx';
 import { TAB_SELECTOR, tabStopIndex } from '../roving';
 import { useUi } from '../theme/context';
@@ -35,7 +35,7 @@ export function Tabs(props: TabsProps): JSX.Element {
   // A disabled tab is excluded from BOTH answers — the list arrows walk and the one tab that
   // carries the tab stop — because `focus()` on a disabled button silently does nothing, so a
   // disabled tab left in the list pins the reducer on its index and hides every tab after it.
-  const onKeyDown = createRovingTabindex(
+  const onKeyDown = rovingTabindex(
     () => (list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>(TAB_SELECTOR))),
     { orientation: props.orientation ?? 'horizontal', dir: ui.dir },
   );

package/src/components/Text.tsx

@@ -37,21 +37,47 @@ export interface TextProps {
 }
 
 export function Text(props: TextProps): JSX.Element {
-  const Tag = props.as ?? 'span';
-
+  const cls = (): string =>
+    cx(styles['text'], styles[`tone-${props.tone ?? 'default'}`], props.class);
   // Size and weight are set only when asked for: unset means inherit, so <Text>
   // inside a heading or a caption does not silently reset to the body scale.
-  return (
-    <Tag
-      class={cx(styles['text'], styles[`tone-${props.tone ?? 'default'}`], props.class)}
-      style={{
-        ...(props.size === undefined ? {} : { '--text-scale': `var(--text-${props.size})` }),
-        ...(props.weight === undefined
-          ? {}
-          : { '--text-strength': `var(--weight-${props.weight})` }),
-      }}
-    >
-      {props.children}
-    </Tag>
-  );
+  const style = (): JSX.CSSProperties => ({
+    ...(props.size === undefined ? {} : { '--text-scale': `var(--text-${props.size})` }),
+    ...(props.weight === undefined ? {} : { '--text-strength': `var(--weight-${props.weight})` }),
+  });
+
+  // One intrinsic per case, never `const Tag = props.as; <Tag>`: the island build compiles a
+  // capitalised tag to `createComponent(Tag)` and calls the string (#488, `intrinsic-root.test.ts`).
+  switch (props.as ?? 'span') {
+    case 'p':
+      return (
+        <p class={cls()} style={style()}>
+          {props.children}
+        </p>
+      );
+    case 'div':
+      return (
+        <div class={cls()} style={style()}>
+          {props.children}
+        </div>
+      );
+    case 'strong':
+      return (
+        <strong class={cls()} style={style()}>
+          {props.children}
+        </strong>
+      );
+    case 'em':
+      return (
+        <em class={cls()} style={style()}>
+          {props.children}
+        </em>
+      );
+    case 'span':
+      return (
+        <span class={cls()} style={style()}>
+          {props.children}
+        </span>
+      );
+  }
 }

package/src/components/Toaster.tsx

@@ -15,7 +15,7 @@ import { Button } from './Button';
 import { Toast, type ToastPlacement, ToastRegion } from './Toast';
 
 export interface ToasterProps {
-  /** The queue. One per app — `createToastStore()` in the island that mounts this. */
+  /** The queue. One per app — `toastStore()` in the island that mounts this. */
   store: ToastStore;
   /** Already-translated landmark name, e.g. "Notifications". */
   label: string;

package/src/components/Toolbar.tsx

@@ -5,7 +5,7 @@
 // own arrow keys, so making the strip a single stop would strand every control past it.
 
 import type { JSX } from 'solid-js';
-import { createRovingTabindex, focusableWithin } from '../a11y';
+import { focusableWithin, rovingTabindex } from '../a11y';
 import { cx } from '../cx';
 import { useUi } from '../theme/context';
 import styles from './Toolbar.module.scss';
@@ -27,12 +27,13 @@ export function Toolbar(props: ToolbarProps): JSX.Element {
   let strip: HTMLDivElement | undefined;
 
   // Arrows follow the writing direction; `focusableWithin` skips anything hidden or disabled, and
-  // `createRovingTabindex` declines outright while a control that answers arrows itself — the
+  // `rovingTabindex` declines outright while a control that answers arrows itself — the
   // search Input this strip exists to hold — has focus.
-  const onKeyDown = createRovingTabindex(
-    () => (strip === undefined ? [] : focusableWithin(strip)),
-    { orientation: 'horizontal', dir: ui.dir, loop: false },
-  );
+  const onKeyDown = rovingTabindex(() => (strip === undefined ? [] : focusableWithin(strip)), {
+    orientation: 'horizontal',
+    dir: ui.dir,
+    loop: false,
+  });
 
   return (
     <div

package/src/components/app-shell-view.ts

@@ -1,6 +1,6 @@
-// AppShell's two rules, kept away from the markup: the id the skip link points at is derived
-// from the same place the <main> gets it, and which landmarks the frame emits in which order.
-// Both are silent failures when wrong — a skip link to nowhere, or two <main> elements.
+// AppShell's rules, kept away from the markup: the ids the skip link and the menu button point at
+// are derived from the same place the <main> and the <nav> get them, and which landmarks the frame
+// emits in which order. All are silent failures when wrong — a skip link or a menu to nowhere.
 
 export type ShellLandmark = 'banner' | 'navigation' | 'main' | 'contentinfo';
 
@@ -8,6 +8,8 @@ export interface ShellIds {
   readonly mainId: string;
   /** Always `#` + `mainId`. One derivation, so the link and the target cannot drift. */
   readonly skipHref: string;
+  /** The sidebar `<nav>`, which the menu button's `popovertarget` names below `md`. */
+  readonly navId: string;
 }
 
 export interface ShellSlots {
@@ -18,7 +20,7 @@ export interface ShellSlots {
 
 export function shellIds(base: string): ShellIds {
   const mainId = `${base}-main`;
-  return { mainId, skipHref: `#${mainId}` };
+  return { mainId, skipHref: `#${mainId}`, navId: `${base}-nav` };
 }
 
 /**

package/src/components/bar-chart-view.ts

@@ -20,11 +20,12 @@ export interface BarRect {
 }
 
 /**
- * 600 × 128 at a 5:1-ish ratio, not 3:1: at dashboard width a taller box pushed the table — the
- * thing people came for — below the fold. `plot` is where bars live; the strip under it belongs
- * to the axis labels, which drawn ON the first and last bars were unreadable there.
+ * 600 × 108, nearly 6:1, not 3:1: at dashboard width a taller box pushed the table — the thing
+ * people came for — below the fold. `plot` is where bars live; `top` and the matching strip under
+ * it only keep the outer grid hairlines off the edge. The axis labels are HTML OUTSIDE the svg
+ * (issue 494) — inside a viewBox they scaled with it — so the box spends no strip on them.
  */
-export const BAR_CHART = { width: 600, top: 12, plot: 104, height: 128, gap: 3 } as const;
+export const BAR_CHART = { width: 600, top: 2, plot: 104, height: 108, gap: 3 } as const;
 
 /** Quarter lines. Four is what a reader can use to judge a bar's height without a y-axis. */
 export const GRID_STEPS = [0.25, 0.5, 0.75, 1] as const;

package/src/components/chart-frame-view.ts

@@ -0,0 +1,219 @@
+// What every chart shares apart from its geometry: which colour slot, dash and marker a series
+// gets (so no series is told apart by colour alone), the data table a screen reader and a
+// no-colour reader get instead of the picture, and how a number becomes text — always in a locale
+// the caller passed, never the runtime's default.
+
+/** The chart colour roles, `chart-1` … `chart-8` (`--color-chart-N`). */
+export const CHART_SERIES_SLOTS = 8;
+
+export type MarkerShape =
+  | 'circle'
+  | 'square'
+  | 'triangle'
+  | 'diamond'
+  | 'plus'
+  | 'triangle-down'
+  | 'cross'
+  | 'star';
+
+const MARKERS: readonly MarkerShape[] = [
+  'circle',
+  'square',
+  'triangle',
+  'diamond',
+  'plus',
+  'triangle-down',
+  'cross',
+  'star',
+];
+
+/**
+ * Five dash patterns against eight slots and markers: 5 and 8 share no factor, so the whole look
+ * of a series (slot, dash, marker) first repeats at the 41st — a ninth series reuses a colour,
+ * never a line. Units are screen px: every chart stroke is `non-scaling-stroke`.
+ */
+const DASHES: readonly (string | undefined)[] = [undefined, '6 4', '2 3', '10 3 2 3', '1 4'];
+
+export interface SeriesStyle {
+  /** 1-based: the `N` of `--color-chart-N`, and the `data-series` a sheet keys the colour on. */
+  readonly slot: number;
+  /** `stroke-dasharray`; `undefined` is a solid line. */
+  readonly dash: string | undefined;
+  readonly marker: MarkerShape;
+}
+
+const indexOf = (index: number): number =>
+  Number.isFinite(index) && index > 0 ? Math.floor(index) : 0;
+
+/** The look of the `index`th series (0-based). */
+export function seriesStyle(index: number): SeriesStyle {
+  const i = indexOf(index);
+  return {
+    slot: (i % CHART_SERIES_SLOTS) + 1,
+    dash: DASHES[i % DASHES.length],
+    marker: MARKERS[i % MARKERS.length] ?? 'circle',
+  };
+}
+
+/** A coordinate as SVG text: two decimals at most, no trailing zeros, never `-0`. */
+export function svgNumber(value: number): string {
+  const text = value.toFixed(2).replace(/\.?0+$/, '');
+  return text === '-0' ? '0' : text;
+}
+
+/** A closed polygon through `points` (unit offsets scaled by `r` around `x, y`). */
+function polygon(x: number, y: number, r: number, points: readonly (readonly [number, number])[]) {
+  const [head, ...rest] = points.map(
+    ([dx, dy]) => `${svgNumber(x + dx * r)},${svgNumber(y + dy * r)}`,
+  );
+  return `M${head} ${rest.map((p) => `L${p}`).join(' ')} Z`;
+}
+
+const ring = (count: number, radius: number, phase = 0): [number, number][] =>
+  Array.from({ length: count }, (_, i) => {
+    const angle = phase + (i * 2 * Math.PI) / count;
+    return [Math.sin(angle) * radius, -Math.cos(angle) * radius];
+  });
+
+/** Polygons only, so a marker is one path a sheet fills — a 12-gon IS a circle at 4px. */
+const SHAPES: Record<MarkerShape, readonly (readonly [number, number])[]> = {
+  circle: ring(12, 1),
+  square: [
+    [-0.85, -0.85],
+    [0.85, -0.85],
+    [0.85, 0.85],
+    [-0.85, 0.85],
+  ],
+  triangle: [
+    [0, -1],
+    [1, 0.85],
+    [-1, 0.85],
+  ],
+  diamond: [
+    [0, -1],
+    [1, 0],
+    [0, 1],
+    [-1, 0],
+  ],
+  plus: [
+    [-0.33, -1],
+    [0.33, -1],
+    [0.33, -0.33],
+    [1, -0.33],
+    [1, 0.33],
+    [0.33, 0.33],
+    [0.33, 1],
+    [-0.33, 1],
+    [-0.33, 0.33],
+    [-1, 0.33],
+    [-1, -0.33],
+    [-0.33, -0.33],
+  ],
+  'triangle-down': [
+    [-1, -0.85],
+    [1, -0.85],
+    [0, 1],
+  ],
+  cross: [
+    [-1, -0.6],
+    [-0.6, -1],
+    [0, -0.4],
+    [0.6, -1],
+    [1, -0.6],
+    [0.4, 0],
+    [1, 0.6],
+    [0.6, 1],
+    [0, 0.4],
+    [-0.6, 1],
+    [-1, 0.6],
+    [-0.4, 0],
+  ],
+  star: ring(10, 1).map(([dx, dy], i) => (i % 2 === 0 ? [dx, dy] : [dx * 0.45, dy * 0.45])),
+};
+
+/** The `d` of a marker of `shape` centred on `x, y`, inside a box of half-width `r`. */
+export function markerPath(shape: MarkerShape, x: number, y: number, r: number): string {
+  return polygon(x, y, r, SHAPES[shape]);
+}
+
+/** A value a chart can place, or `null` for a gap: missing, NaN and ±∞ are never drawn as 0. */
+export function finiteOrNull(value: number | null | undefined): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export interface ChartSeries {
+  /** The series' name, already translated: the legend entry and the table's column head. */
+  readonly label: string;
+  /** One value per key, in key order; `null` is a gap in the line and an empty table cell. */
+  readonly values: readonly (number | null)[];
+}
+
+export interface ChartTableRow {
+  readonly key: string;
+  readonly cells: readonly string[];
+}
+
+export interface ChartTable {
+  readonly caption: string;
+  /** The corner cell (the key column's head, `''` when unnamed), then one head per series. */
+  readonly head: readonly string[];
+  readonly rows: readonly ChartTableRow[];
+}
+
+export interface ChartTableInput {
+  readonly caption: string;
+  readonly keyLabel: string | undefined;
+  readonly keys: readonly string[];
+  readonly series: readonly ChartSeries[];
+  readonly format: (value: number) => string;
+}
+
+/** The same numbers the picture draws, as rows a screen reader walks cell by cell. */
+export function chartTable(input: ChartTableInput): ChartTable {
+  return {
+    caption: input.caption,
+    head: [input.keyLabel ?? '', ...input.series.map((series) => series.label)],
+    rows: input.keys.map((key, index) => ({
+      key,
+      cells: input.series.map((series) => {
+        const value = finiteOrNull(series.values[index]);
+        return value === null ? '' : input.format(value);
+      }),
+    })),
+  };
+}
+
+/** `Intl.NumberFormat` in the locale passed — the page's, read by the component from `useUi()`. */
+export function chartNumberFormat(
+  locale: string,
+  maxFractionDigits = 2,
+): (value: number) => string {
+  const format = new Intl.NumberFormat(locale, { maximumFractionDigits: maxFractionDigits });
+  return (value) => format.format(value);
+}
+
+/** A point's accessible name: key, series (when there is more than one thing to name), value. */
+export function pointLabel(key: string, series: string | undefined, value: string): string {
+  return series === undefined ? `${key}: ${value}` : `${key}, ${series}: ${value}`;
+}
+
+/** `part` of `whole` as a CSS percentage for a `--x`/`--y` custom property, clamped to the box. */
+export function cssPercent(part: number, whole: number): string {
+  if (!(whole > 0) || !Number.isFinite(part)) return '0%';
+  const share = Math.min(1, Math.max(0, part / whole));
+  return `${svgNumber(share * 100)}%`;
+}
+
+/** A share (0..1) as a percentage in the locale passed: a donut's legend, a gauge's readout. */
+export function chartPercentFormat(locale: string): (share: number) => string {
+  const format = new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 });
+  return (share) => format.format(share);
+}
+
+/** Which way a point's readout opens: inward from the outer fifth of the plot, centred elsewhere. */
+export function hitEdge(x: number, width: number): 'start' | 'middle' | 'end' {
+  const share = width > 0 ? x / width : 0.5;
+  if (share < 0.2) return 'start';
+  if (share > 0.8) return 'end';
+  return 'middle';
+}