@ultimat3/ui 24.0.0 → 25.1.0

package/src/components/Gauge.tsx

@@ -0,0 +1,67 @@
+// One value against its maximum as a 270° dial — CPU, a quota, a queue's fill — with the reading
+// in its centre and its label under it. A `meter` role carries the value for assistive tech, the
+// way `Meter` does; the readout is HTML over the svg so it keeps its size on a phone.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import { ChartFrame } from './ChartFrame';
+import { chartPercentFormat, cssPercent } from './chart-frame-view';
+import styles from './Gauge.module.scss';
+import { GAUGE, gaugeArcs } from './gauge-view';
+import { meterAria, meterShare } from './meter-view';
+import type { Tone } from './variants';
+
+export interface GaugeProps {
+  /** What is measured, already translated: shown under the dial, and the meter's name. */
+  label: string;
+  value: number;
+  max: number;
+  /** The fill's colour role. Default `accent`; a caller picks `warning`/`danger` by threshold. */
+  tone?: Tone | undefined;
+  /** The readout, from the value and max. Default: the share as a percentage in the page's locale. */
+  format?: ((value: number, max: number) => string) | undefined;
+  /** Lands on the root `<figure>`. */
+  class?: string | undefined;
+}
+
+export function Gauge(props: GaugeProps): JSX.Element {
+  const ui = useUi();
+  const share = (): number => meterShare(props.value, props.max);
+  const readout = (): string =>
+    props.format === undefined
+      ? chartPercentFormat(ui.locale)(share())
+      : props.format(props.value, props.max);
+  const arcs = () => gaugeArcs(share());
+  return (
+    <ChartFrame label={props.label} showCaption class={cx(styles['gauge'], props.class)}>
+      <div class={cx(styles['dial'], styles[`tone-${props.tone ?? 'accent'}`])}>
+        {/* A native <meter> paints through per-browser pseudo-elements, so it cannot be drawn
+            from tokens; the role goes on the svg that draws it, as in `Meter`. */}
+        {/* biome-ignore lint/a11y/useSemanticElements: <meter> cannot be styled from tokens */}
+        <svg
+          class={styles['plot']}
+          viewBox={`0 0 ${GAUGE.width} ${GAUGE.height}`}
+          role="meter"
+          aria-label={props.label}
+          aria-valuemin={0}
+          aria-valuemax={meterAria(props.value, props.max).max}
+          aria-valuenow={meterAria(props.value, props.max).now}
+          aria-valuetext={readout()}
+        >
+          <path class={styles['track']} d={arcs().track} />
+          {arcs().fill === '' ? null : <path class={styles['fill']} d={arcs().fill} />}
+        </svg>
+        {/* aria-hidden: the meter already speaks this as its value text. */}
+        <span
+          class={styles['readout']}
+          aria-hidden="true"
+          data-readout="true"
+          style={{ '--centre': cssPercent(GAUGE.centre, GAUGE.height) }}
+        >
+          {readout()}
+        </span>
+      </div>
+    </ChartFrame>
+  );
+}

package/src/components/Grid.tsx

@@ -19,22 +19,43 @@ export interface GridProps {
 }
 
 export function Grid(props: GridProps): JSX.Element {
-  const Tag = props.as ?? 'div';
   const tracks = (): string =>
     props.columns === undefined
       ? `repeat(auto-fit, minmax(${props.minColumn ?? '16rem'}, 1fr))`
       : `repeat(${props.columns}, minmax(0, 1fr))`;
+  const cls = (): string => cx(styles['grid'], props.class);
+  const style = (): JSX.CSSProperties => ({
+    '--grid-tracks': tracks(),
+    '--grid-gap': `var(--space-${props.gap ?? 4})`,
+    '--grid-row-gap': `var(--space-${props.rowGap ?? props.gap ?? 4})`,
+  });
 
-  return (
-    <Tag
-      class={cx(styles['grid'], props.class)}
-      style={{
-        '--grid-tracks': tracks(),
-        '--grid-gap': `var(--space-${props.gap ?? 4})`,
-        '--grid-row-gap': `var(--space-${props.rowGap ?? props.gap ?? 4})`,
-      }}
-    >
-      {props.children}
-    </Tag>
-  );
+  // 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 'section':
+      return (
+        <section class={cls()} style={style()}>
+          {props.children}
+        </section>
+      );
+    case 'div':
+      return (
+        <div class={cls()} style={style()}>
+          {props.children}
+        </div>
+      );
+  }
 }

package/src/components/Image.tsx

@@ -20,7 +20,7 @@ import {
   loadingHints,
   reservedRatio,
   sourceSetsFor,
-  srcsetFor,
+  variantSrcset,
 } from './image-source';
 
 /**
@@ -77,7 +77,7 @@ export function Image(props: ImageBaseProps & ImageDimensions): JSX.Element {
       style={{ '--image-ratio': ratio() }}
       src={src()}
       alt={props.alt}
-      srcset={srcsetFor(props.variants)}
+      srcset={variantSrcset(props.variants)}
       sizes={props.sizes}
       width={box()?.width}
       height={box()?.height}

package/src/components/InlineBar.module.scss

@@ -0,0 +1,23 @@
+@use '../tokens' as t;
+
+// The figure first, the bar filling what is left: in a numeric column the figures align at the
+// trailing edge and the bars start where the figures end, so the column reads as one chart.
+.inlineBar {
+  display: inline-grid;
+  grid-template-columns: auto minmax(t.space(12), 1fr);
+  align-items: center;
+  gap: t.space(2);
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+
+.value {
+  @include t.data-text;
+  text-align: end;
+}
+
+// `Meter` draws in an SVG, whose x axis is physical: mirrored here so the bar grows from the
+// inline start in a right-to-left document too.
+.bar:dir(rtl) {
+  scale: -1 1;
+}

package/src/components/InlineBar.tsx

@@ -0,0 +1,31 @@
+// A figure with a bar drawn to its share of a maximum — the in-cell bar a dashboard table uses to
+// make a column of numbers scannable. The text is the fact and is what assistive tech reads; the
+// bar is `Meter`'s decorative form, so the share rule and its clamping are written once.
+// The figure arrives formatted, as `StatTile`'s does: this component never guesses a locale.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './InlineBar.module.scss';
+import { Meter } from './Meter';
+import type { Tone } from './variants';
+
+export interface InlineBarProps {
+  value: number;
+  /** The whole the bar is a share of — usually the largest value in the column. */
+  max: number;
+  /** The figure as the cell shows it, already formatted (`Intl.NumberFormat`, `formatMoney`). */
+  text: string;
+  tone?: Tone | undefined;
+  class?: string | undefined;
+}
+
+export function InlineBar(props: InlineBarProps): JSX.Element {
+  return (
+    <span class={cx(styles['inlineBar'], props.class)}>
+      <span class={styles['value']} data-inline-bar-value="">
+        {props.text}
+      </span>
+      <Meter class={styles['bar']} value={props.value} max={props.max} tone={props.tone} />
+    </span>
+  );
+}

package/src/components/LineChart.module.scss

@@ -0,0 +1,147 @@
+@use '../tokens' as t;
+
+// Value labels | plot, then the key labels under the plot. The grid is the container the label
+// density is decided against — the plot's own width, not the viewport's.
+.chart {
+  @include t.container(line-chart);
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  grid-template-areas:
+    'values box'
+    '. keys';
+  column-gap: t.space(2);
+  row-gap: t.space(1);
+  // The svg does not mirror in a right-to-left page, so the labels positioned over it must not
+  // either: inline-start IS the svg's x = 0 here.
+  direction: ltr;
+}
+
+.box {
+  grid-area: box;
+  position: relative;
+  min-inline-size: 0;
+}
+
+.plot {
+  display: block;
+  inline-size: 100%;
+  block-size: auto;
+  overflow: visible;
+}
+
+.grid {
+  stroke: t.role('line', 0.55);
+  stroke-width: 1;
+  stroke-dasharray: 2 4;
+  // Hairlines stay hairlines however wide the chart is stretched.
+  vector-effect: non-scaling-stroke;
+}
+
+.line {
+  fill: none;
+  stroke: var(--series);
+  stroke-width: 2;
+  stroke-linejoin: round;
+  stroke-linecap: round;
+  vector-effect: non-scaling-stroke;
+}
+
+.area {
+  fill: var(--series);
+  fill-opacity: 0.16;
+  stroke: none;
+}
+
+.marker {
+  fill: var(--series);
+  // A ring of the surface around each marker keeps it legible where two lines cross.
+  stroke: t.role('surface');
+  stroke-width: 1;
+  vector-effect: non-scaling-stroke;
+}
+
+// --- Labels: HTML text, so it keeps its type step at every chart width (issue 494) -----------
+
+.tick,
+.key {
+  @include t.data-text;
+  font-size: t.text(xs);
+  line-height: t.leading(tight);
+  color: t.role('fg-muted');
+  white-space: nowrap;
+}
+
+// Every value label in one cell, each offset to its grid line: the column is as wide as the
+// widest label and exactly as tall as the plot it stands beside.
+.values {
+  grid-area: values;
+  display: grid;
+}
+
+.tick {
+  grid-area: 1 / 1;
+  align-self: start;
+  justify-self: end;
+  position: relative;
+  inset-block-start: var(--at);
+  translate: 0 -50%;
+}
+
+.keys {
+  grid-area: keys;
+  display: grid;
+  min-inline-size: 0;
+}
+
+// Capped at a third of the axis: three labels on a stride of at least half the axis cannot meet.
+.key {
+  @include t.truncate;
+  grid-area: 1 / 1;
+  max-inline-size: calc(100% / 3);
+}
+
+.edge-start {
+  justify-self: start;
+  margin-inline-start: var(--at);
+}
+
+.edge-middle {
+  justify-self: start;
+  margin-inline-start: var(--at);
+  translate: -50% 0;
+}
+
+.edge-end {
+  justify-self: end;
+  margin-inline-end: calc(100% - var(--at));
+}
+
+// Narrow first — a 390px phone: three key labels, every other value label.
+.key[data-narrow='false'] {
+  display: none;
+}
+
+.tick[data-minor='true'] {
+  // `visibility`, never `display`: the column keeps the width of its widest label either way.
+  visibility: hidden;
+}
+
+// A plot this wide holds six key labels (each capped at 2/15 of the axis: ⅔ of a fifth) and
+// every value label.
+@include t.container-query(line-chart, 36rem) {
+  .key[data-narrow='false'] {
+    display: block;
+  }
+
+  .key[data-wide='false'] {
+    display: none;
+  }
+
+  .key {
+    max-inline-size: calc(100% * 2 / 15);
+  }
+
+  .tick[data-minor='true'] {
+    visibility: visible;
+  }
+}

package/src/components/LineChart.tsx

@@ -0,0 +1,169 @@
+// A line chart of one or more series over the same keys — signups per day, p95 per hour — and
+// `AreaChart`, the same chart with each series' area filled to the baseline. SVG lines on a nice
+// 1-2-5 value axis, HTML axis labels (text inside a viewBox scales to a speck on a phone), a
+// legend, and a hidden data table. Every series has its own dash and marker, never colour alone.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import type { ChartHit } from './ChartFrame';
+import { ChartFrame, chartHits, seriesSwatch } from './ChartFrame';
+import type { ChartSeries } from './chart-frame-view';
+import {
+  chartNumberFormat,
+  chartTable,
+  cssPercent,
+  hitEdge,
+  markerPath,
+  pointLabel,
+  seriesStyle,
+} from './chart-frame-view';
+import { categoryLabels, minorTicks, tickDecimals } from './chart-ticks-view';
+import styles from './LineChart.module.scss';
+import type { LineLayout } from './line-chart-view';
+import { LINE_CHART, lineLayout, markedPoints } from './line-chart-view';
+
+export interface LineChartProps {
+  /** The chart's name, already translated: the figure's caption and the svg's accessible name. */
+  label: string;
+  /** The x axis, oldest first, already formatted for display — "17 Sep", "14:00". */
+  keys: readonly string[];
+  /** One entry per line. `values[i]` belongs to `keys[i]`; `null` is a gap, never a zero. */
+  series: readonly ChartSeries[];
+  /** The key column's head in the data table, already translated — "Day". */
+  keyLabel?: string | undefined;
+  /** Formats every value and tick. Default: `Intl.NumberFormat` in the page's locale. */
+  format?: ((value: number) => string) | undefined;
+  /** Start the value axis at zero. Default on; off fits the axis to the data. */
+  zero?: boolean | undefined;
+  /** Give every point a tab stop and a hover/focus readout. Default off: no tab stops. */
+  focusable?: boolean | undefined;
+  /** Show the caption above the plot. Default off — it names the figure either way. */
+  showCaption?: boolean | undefined;
+  /** Lands on the root `<figure>`. */
+  class?: string | undefined;
+}
+
+/** The same props: an area chart is a line chart that fills. */
+export type AreaChartProps = LineChartProps;
+
+/** Up to six value labels: at 390px a seventh crowds the ones beside it. */
+const MAX_TICKS = 6;
+const MARKER_RADIUS = 4;
+
+export function LineChart(props: LineChartProps): JSX.Element {
+  return xyChart(props, false);
+}
+
+export function AreaChart(props: AreaChartProps): JSX.Element {
+  return xyChart(props, true);
+}
+
+function xyChart(props: LineChartProps, filled: boolean): JSX.Element {
+  const ui = useUi();
+  const layout = (): LineLayout =>
+    lineLayout({
+      keys: props.keys,
+      series: props.series,
+      zero: props.zero !== false,
+      maxTicks: MAX_TICKS,
+    });
+  const format = (value: number): string => (props.format ?? chartNumberFormat(ui.locale))(value);
+  const tickFormat = (value: number): string =>
+    (props.format ?? chartNumberFormat(ui.locale, tickDecimals(layout().scale.step)))(value);
+  const { width, height } = LINE_CHART;
+
+  const hits = (): readonly ChartHit[] =>
+    props.series.flatMap((series, s) =>
+      (layout().series[s]?.points ?? []).map((point) => ({
+        x: cssPercent(point.x, width),
+        y: cssPercent(point.y, height),
+        label: pointLabel(props.keys[point.index] ?? '', series.label, format(point.value)),
+        edge: hitEdge(point.x, width),
+      })),
+    );
+
+  return (
+    <ChartFrame
+      label={props.label}
+      showCaption={props.showCaption}
+      class={props.class}
+      legend={
+        props.series.length < 2
+          ? undefined
+          : props.series.map((series, s) => ({
+              label: series.label,
+              swatch: seriesSwatch(seriesStyle(s)),
+            }))
+      }
+      table={chartTable({
+        caption: props.label,
+        keyLabel: props.keyLabel,
+        keys: props.keys,
+        series: props.series,
+        format,
+      })}
+    >
+      <div class={styles['chart']}>
+        <div class={styles['values']} aria-hidden="true">
+          {layout().ticks.map((tick, i) => (
+            <span
+              class={styles['tick']}
+              data-tick="value"
+              data-minor={minorTicks(layout().ticks.length)[i] === true ? 'true' : 'false'}
+              style={{ '--at': cssPercent(tick.y, height) }}
+            >
+              {tickFormat(tick.value)}
+            </span>
+          ))}
+        </div>
+        <div class={styles['box']}>
+          <svg
+            role="img"
+            aria-label={props.label}
+            viewBox={`0 0 ${width} ${height}`}
+            class={styles['plot']}
+          >
+            {layout().ticks.map((tick) => (
+              <line class={styles['grid']} x1={0} x2={width} y1={tick.y} y2={tick.y} />
+            ))}
+            {props.series.map((_, s) => {
+              const style = seriesStyle(s);
+              const geometry = layout().series[s];
+              if (geometry === undefined) return null;
+              return (
+                <g data-series={style.slot} data-line={String(s)}>
+                  {filled && geometry.area !== '' ? (
+                    <path class={styles['area']} d={geometry.area} data-area="true" />
+                  ) : null}
+                  <path class={styles['line']} d={geometry.line} stroke-dasharray={style.dash} />
+                  {markedPoints(geometry.points, props.keys.length).map((point) => (
+                    <path
+                      class={styles['marker']}
+                      d={markerPath(style.marker, point.x, point.y, MARKER_RADIUS)}
+                      data-marker={style.marker}
+                    />
+                  ))}
+                </g>
+              );
+            })}
+          </svg>
+          {props.focusable === true ? chartHits(hits()) : null}
+        </div>
+        <div class={styles['keys']} aria-hidden="true">
+          {categoryLabels(props.keys.length).map((label) => (
+            <span
+              class={cx(styles['key'], styles[`edge-${label.edge}`])}
+              data-tick="key"
+              data-narrow={String(label.narrow)}
+              data-wide={String(label.wide)}
+              style={{ '--at': cssPercent(layout().keyX[label.index] ?? 0, width) }}
+            >
+              {props.keys[label.index]}
+            </span>
+          ))}
+        </div>
+      </div>
+    </ChartFrame>
+  );
+}

package/src/components/Menu.tsx

@@ -2,7 +2,7 @@
 // Distinct from Select — a menu runs commands, it does not hold a form value.
 
 import type { JSX } from 'solid-js';
-import { createFocusTrap, createRovingTabindex, useId } from '../a11y';
+import { focusTrap, rovingTabindex, useId } from '../a11y';
 import { cx } from '../cx';
 import { MENU_ITEM_SELECTOR, tabStopIndex } from '../roving';
 import { useUi } from '../theme/context';
@@ -24,11 +24,15 @@ export interface MenuProps {
   items: readonly MenuItem[];
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  /**
+   * The menu button. `aria-controls` is present only while the list is mounted: an IDREF to an
+   * element not in the document names nothing.
+   */
   trigger: (control: {
     id: string;
     'aria-haspopup': 'menu';
     'aria-expanded': boolean;
-    'aria-controls': string;
+    'aria-controls': string | undefined;
   }) => JSX.Element;
   /** Already-translated accessible name for the menu. */
   label: string;
@@ -45,7 +49,7 @@ export function Menu(props: MenuProps): JSX.Element {
 
   // Disabled items are excluded from BOTH answers — the list arrows walk and the one item that
   // carries the tab stop — because `focus()` on a disabled button silently does nothing.
-  const onKeyDown = createRovingTabindex(
+  const onKeyDown = rovingTabindex(
     () =>
       list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR)),
     { orientation: 'vertical', dir: ui.dir },
@@ -65,7 +69,7 @@ export function Menu(props: MenuProps): JSX.Element {
     // Closing unmounts the panel with focus inside it, which resets focus to <body> and makes the
     // next Tab restart at the top of the document. The trap moves focus in on open and hands it
     // back to the trigger on close, so Escape returns the user where they were.
-    const trap = list === undefined ? undefined : createFocusTrap(list);
+    const trap = list === undefined ? undefined : focusTrap(list);
     trap?.activate();
     rt.onCleanup(() => {
       document.removeEventListener('pointerdown', onPointerDown, true);
@@ -85,7 +89,7 @@ export function Menu(props: MenuProps): JSX.Element {
         id: `${menuId}-trigger`,
         'aria-haspopup': 'menu',
         'aria-expanded': props.open,
-        'aria-controls': menuId,
+        'aria-controls': props.open ? menuId : undefined,
       })}
       {props.open ? (
         <div

package/src/components/PageHeader.tsx

@@ -6,6 +6,7 @@ import type { JSX } from 'solid-js';
 import { cx } from '../cx';
 import { Breadcrumb, type BreadcrumbItem } from './Breadcrumb';
 import { type HeadingLevel, headingTag } from './heading-level';
+import { headingNode } from './heading-node';
 import styles from './PageHeader.module.scss';
 
 export interface PageHeaderProps {
@@ -24,7 +25,9 @@ export interface PageHeaderProps {
 }
 
 export function PageHeader(props: PageHeaderProps): JSX.Element {
-  const Heading = headingTag(props.level ?? 1);
+  // Resolved once, so an off-scale level throws `X_UI_INVALID_VALUE` here as it always did.
+  const heading = headingTag(props.level ?? 1);
+  const title = (): string => props.title;
 
   return (
     <header class={cx(styles['pageHeader'], props.class)}>
@@ -33,7 +36,7 @@ export function PageHeader(props: PageHeaderProps): JSX.Element {
         <div class={styles['titles']}>
           {props.media === undefined ? null : <div class={styles['media']}>{props.media}</div>}
           <div class={styles['text']}>
-            <Heading class={styles['title']}>{props.title}</Heading>
+            {headingNode(heading, { class: styles['title'] }, title)}
             {props.description === undefined ? null : (
               <p class={styles['description']}>{props.description}</p>
             )}

package/src/components/Popover.tsx

@@ -3,7 +3,7 @@
 // loop and the panel mirrors under `dir="rtl"` — `rtl-sheets.test.ts` holds that.
 
 import type { JSX } from 'solid-js';
-import { createFocusTrap, useId } from '../a11y';
+import { focusTrap, useId } from '../a11y';
 import { cx } from '../cx';
 import { solid } from '../theme/solid-adapter';
 import styles from './Popover.module.scss';
@@ -50,7 +50,7 @@ export function Popover(props: PopoverProps): JSX.Element {
     // Closing unmounts the panel with focus inside it, which drops focus to <body> and makes the
     // next Tab restart at the top of the document. The trap moves focus into the panel on open and
     // hands it back to the trigger on close.
-    const trap = panel === undefined ? undefined : createFocusTrap(panel);
+    const trap = panel === undefined ? undefined : focusTrap(panel);
     trap?.activate();
     rt.onCleanup(() => {
       document.removeEventListener('pointerdown', onPointerDown, true);