@ultimat3/ui 29.4.0 → 30.1.0

package/src/components/DescriptionList.tsx

@@ -0,0 +1,38 @@
+// Terms and their details: `<dl>` with one `<div>` per group, so a pair stays together when the
+// list stacks. A `Table` of two columns is the wrong landmark for facts about one thing.
+// Server-only: no signal, no effect, 0 B of script on a static route.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './DescriptionList.module.scss';
+
+export interface DescriptionItem {
+  /** Already-translated term. */
+  term: string;
+  detail: JSX.Element;
+}
+
+export interface DescriptionListProps {
+  items: readonly DescriptionItem[];
+  /**
+   * `columns` puts each term beside its detail and stacks them when the list's OWN width falls
+   * below `sm` (a container query, never the viewport). `stacked` always stacks.
+   */
+  layout?: 'columns' | 'stacked' | undefined;
+  class?: string | undefined;
+}
+
+export function DescriptionList(props: DescriptionListProps): JSX.Element {
+  return (
+    <div class={cx(styles['wrap'], props.class)}>
+      <dl class={cx(styles['list'], styles[`layout-${props.layout ?? 'columns'}`])}>
+        {props.items.map((item) => (
+          <div class={styles['group']}>
+            <dt class={styles['term']}>{item.term}</dt>
+            <dd class={styles['detail']}>{item.detail}</dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}

package/src/components/DiffView.module.scss

@@ -0,0 +1,124 @@
+@use 'sass:map';
+@use '../tokens' as t;
+
+$md: map.get(t.$breakpoints, 'md');
+
+// Unified below `md` of the CONTAINER, side by side at and above it. Hue is never alone: the
+// `+`/`-` gutter and a spoken word carry the same fact, so the diff reads with colour off.
+.diff {
+  @include t.container(diff);
+  border: t.stroke(hairline) solid t.role('line');
+  border-radius: t.radius(md);
+  background: t.role('bg-soft');
+}
+
+.bar {
+  @include t.row(t.space(1), center, flex-end);
+  padding-block: t.space(1);
+  padding-inline: t.space(2);
+  border-block-end: t.stroke(hairline) solid t.role('line');
+}
+
+.diff:not([data-enhanced='true']) .bar {
+  display: none;
+}
+
+.next {
+  @include t.focus-ring;
+  border: 0;
+  background: transparent;
+  color: t.role('accent');
+  font-size: t.text(sm);
+  cursor: pointer;
+  min-block-size: t.touch(target);
+}
+
+.scroll {
+  @include t.focus-ring;
+  overflow-x: auto;
+  text-align: start;
+}
+
+.unified,
+.split {
+  inline-size: 100%;
+  border-collapse: collapse;
+  font-family: var(--font-mono);
+  font-size: t.text(sm);
+  color: t.role('fg');
+}
+
+.split {
+  display: none;
+  table-layout: fixed;
+}
+
+@include t.container-query(diff, $md) {
+  .unified {
+    display: none;
+  }
+
+  .split {
+    display: table;
+  }
+}
+
+.row td {
+  vertical-align: top;
+}
+
+.num {
+  inline-size: t.space(10);
+  padding-inline: t.space(2);
+  color: t.role('fg-muted');
+  text-align: end;
+  user-select: none;
+}
+
+.sign {
+  inline-size: t.space(4);
+  text-align: center;
+  user-select: none;
+}
+
+.text {
+  padding-inline-end: t.space(2);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.add {
+  background: t.role('success-soft');
+}
+
+.del {
+  background: t.role('danger-soft');
+}
+
+.context {
+  background: transparent;
+}
+
+// A changed word: weight and an underline as well as the tint, so it survives colour off.
+.word {
+  background: transparent;
+  color: inherit;
+  font-weight: t.weight(bold);
+  text-decoration: underline;
+}
+
+.spoken {
+  @include t.visually-hidden;
+}
+
+.hunk,
+.file,
+.fold {
+  background: t.role('surface');
+  color: t.role('fg-muted');
+
+  td {
+    padding-block: t.space(1);
+    padding-inline: t.space(2);
+  }
+}

package/src/components/DiffView.tsx

@@ -0,0 +1,169 @@
+// A diff a person can read with colour off: `+` and `-` gutters, a spoken word per changed row,
+// word marks inside a changed pair, line numbers on each side. Unified below `md`, side by side
+// from it, by `@container`. Two texts or a unified patch — one parser to rows.
+
+import type { JSX } from 'solid-js';
+import type { DiffRow } from '../content/line-diff';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import styles from './DiffView.module.scss';
+import {
+  diffViewRows,
+  markedSegments,
+  type SidePair,
+  sidePairs,
+  startsChange,
+} from './diff-view-view';
+
+interface DiffViewBase {
+  /** Already-translated name of the scroll region; defaults to `ui.diff.region`. */
+  label?: string | undefined;
+  /** Rows past this fold into one line saying how many. Defaults to 2,000. */
+  maxLines?: number | undefined;
+  class?: string | undefined;
+}
+
+export interface DiffViewTextProps extends DiffViewBase {
+  old: string;
+  new: string;
+  patch?: undefined;
+}
+
+export interface DiffViewPatchProps extends DiffViewBase {
+  /** A unified patch, as `git diff` writes it. */
+  patch: string;
+  old?: undefined;
+  new?: undefined;
+}
+
+export type DiffViewProps = DiffViewTextProps | DiffViewPatchProps;
+
+const sign = (row: DiffRow): string => (row.kind === 'add' ? '+' : row.kind === 'del' ? '-' : ' ');
+
+const isChange = (row: DiffRow | null): boolean => row?.kind === 'add' || row?.kind === 'del';
+
+const pairChanges = (pair: SidePair | undefined): boolean =>
+  pair?.kind === 'pair' && (isChange(pair.left) || isChange(pair.right));
+const changeStarts = (pairs: readonly SidePair[], index: number): boolean =>
+  pairChanges(pairs[index]) && !pairChanges(pairs[index - 1]);
+
+export function DiffView(props: DiffViewProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const [enhanced, setEnhanced] = rt.createSignal(false);
+  rt.createEffect(() => setEnhanced(true));
+  const rows = rt.createMemo(() =>
+    diffViewRows({ old: props.old, new: props.new, patch: props.patch, maxLines: props.maxLines }),
+  );
+  let box: HTMLDivElement | undefined;
+  let stop = -1;
+
+  const spoken = (row: DiffRow): JSX.Element =>
+    row.kind === 'add' || row.kind === 'del' ? (
+      <span class={styles['spoken']}>
+        {ui.t(row.kind === 'add' ? UI_KEYS.diffAdded : UI_KEYS.diffRemoved)}
+      </span>
+    ) : null;
+
+  const text = (row: DiffRow): JSX.Element =>
+    'text' in row
+      ? markedSegments(row.text, 'marks' in row ? row.marks : undefined).map(([segment, marked]) =>
+          marked ? <mark class={styles['word']}>{segment}</mark> : segment,
+        )
+      : null;
+
+  const whole = (row: DiffRow, span: number): JSX.Element => (
+    <tr class={styles[row.kind]}>
+      <td colspan={span}>
+        {row.kind === 'fold'
+          ? ui.t(UI_KEYS.diffFolded, { count: row.count })
+          : 'text' in row
+            ? row.text
+            : null}
+      </td>
+    </tr>
+  );
+
+  const half = (row: DiffRow | null, side: 'old' | 'new'): JSX.Element[] => [
+    <td class={styles['num']}>
+      {row !== null && (row.kind === 'add' || row.kind === 'del' || row.kind === 'context')
+        ? row[side]
+        : null}
+    </td>,
+    <td class={styles['sign']} aria-hidden="true">
+      {row === null ? '' : sign(row)}
+    </td>,
+    <td class={cx(styles['text'], row !== null && styles[row.kind])}>
+      {row === null ? null : spoken(row)}
+      {row === null ? null : text(row)}
+    </td>,
+  ];
+
+  const next = (): void => {
+    const table = [...(box?.querySelectorAll<HTMLElement>('table') ?? [])].find(
+      (el) => el.offsetParent !== null,
+    );
+    const starts = [...(table?.querySelectorAll<HTMLElement>('[data-change="start"]') ?? [])];
+    if (starts.length === 0) return;
+    stop = (stop + 1) % starts.length;
+    starts[stop]?.scrollIntoView({ block: 'center' });
+  };
+
+  return (
+    <div class={cx(styles['diff'], props.class)} data-enhanced={enhanced() ? 'true' : undefined}>
+      <div class={styles['bar']}>
+        <button type="button" class={styles['next']} onClick={next}>
+          {ui.t(UI_KEYS.diffNext)}
+        </button>
+      </div>
+      {/* biome-ignore lint/a11y/useSemanticElements: the scroll box holds two tables, one shown per width */}
+      <div
+        class={styles['scroll']}
+        tabindex="0"
+        role="region"
+        aria-label={props.label ?? ui.t(UI_KEYS.diffRegion)}
+        dir="ltr"
+        ref={(el: HTMLDivElement) => {
+          box = el;
+        }}
+      >
+        <table class={styles['unified']}>
+          <tbody>
+            {rows().map((row, index) =>
+              row.kind === 'add' || row.kind === 'del' || row.kind === 'context' ? (
+                <tr
+                  class={styles['row']}
+                  data-change={startsChange(rows(), index) ? 'start' : undefined}
+                >
+                  <td class={styles['num']}>{row.old}</td>
+                  {half(row, 'new')}
+                </tr>
+              ) : (
+                whole(row, 4)
+              ),
+            )}
+          </tbody>
+        </table>
+        <table class={styles['split']}>
+          <tbody>
+            {sidePairs(rows()).map((pair, index, pairs) =>
+              pair.kind === 'whole' ? (
+                whole(pair.row, 6)
+              ) : (
+                <tr
+                  class={styles['row']}
+                  data-change={changeStarts(pairs, index) ? 'start' : undefined}
+                >
+                  {half(pair.left, 'old')}
+                  {half(pair.right, 'new')}
+                </tr>
+              ),
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/src/components/DonutChart.tsx

@@ -4,9 +4,10 @@
 // the ring reads in greyscale. SVG geometry from `donut-chart-view.ts`; text is HTML.
 
 import type { JSX } from 'solid-js';
+import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
 import type { ChartHit } from './ChartFrame';
-import { ChartFrame, chartHits } from './ChartFrame';
+import { ChartFrame, ChartHits } from './ChartFrame';
 import type { MarkerShape } from './chart-frame-view';
 import {
   chartNumberFormat,
@@ -14,6 +15,7 @@ import {
   chartTable,
   cssPercent,
   hitEdge,
+  hitIds,
   markerPath,
   pointLabel,
   seriesStyle,
@@ -62,13 +64,18 @@ export function DonutChart(props: DonutChartProps): JSX.Element {
   const total = (): number => props.segments.reduce((sum, s) => sum + finitePositive(s.value), 0);
   const { size, centre, outer, inner, marker } = DONUT;
 
-  const hits = (): readonly ChartHit[] =>
-    props.segments.flatMap((segment, i) => {
+  const hits = (): readonly ChartHit[] => {
+    const ids = hitIds(
+      0,
+      props.segments.map((segment) => segment.label),
+    );
+    return props.segments.flatMap((segment, i) => {
       const anchor = arcs()[i]?.anchor;
       if (anchor === null || anchor === undefined) return [];
       const share = arcs()[i]?.share ?? 0;
       return [
         {
+          id: ids[i] ?? String(i),
           x: cssPercent(anchor.x, size),
           y: cssPercent(anchor.y, size),
           label: pointLabel(
@@ -80,6 +87,7 @@ export function DonutChart(props: DonutChartProps): JSX.Element {
         },
       ];
     });
+  };
 
   return (
     <ChartFrame
@@ -100,6 +108,7 @@ export function DonutChart(props: DonutChartProps): JSX.Element {
           { label: props.valueLabel ?? props.label, values: props.segments.map((s) => s.value) },
         ],
         format,
+        none: ui.t(UI_KEYS.chartNone),
       })}
     >
       <div class={styles['donut']}>
@@ -137,7 +146,7 @@ export function DonutChart(props: DonutChartProps): JSX.Element {
             <span class={styles['caption']}>{props.centreLabel}</span>
           )}
         </p>
-        {props.focusable === true ? chartHits(hits()) : null}
+        {props.focusable === true ? <ChartHits hits={hits()} /> : null}
       </div>
     </ChartFrame>
   );

package/src/components/Drawer.module.scss

@@ -51,6 +51,46 @@
   border-start-end-radius: t.radius(lg);
 }
 
+// The bottom sheet with a grabber: snapped to half or nearly all of the DYNAMIC viewport, so the
+// browser's own bars never push it off-screen, and clear of the home indicator.
+.side-block-end[data-snap] {
+  @include t.transition(translate, block-size);
+  block-size: 50dvh;
+  max-block-size: calc(100dvh - #{t.safe-area-inset(block-start)} - #{t.space(4)});
+  translate: 0 var(--drawer-drag, 0);
+
+  &[data-snap='full'] {
+    block-size: calc(100dvh - #{t.safe-area-inset(block-start)} - #{t.space(4)});
+  }
+
+  // Following the finger: no easing between moves.
+  &[data-dragging] {
+    transition: none;
+  }
+
+  .body,
+  .footer {
+    @include t.safe-area-padding(block-end, t.space(4));
+  }
+}
+
+.grabber {
+  display: flex;
+  justify-content: center;
+  padding-block: t.space(2);
+  cursor: grab;
+  // This box alone: the body keeps its own scroll.
+  touch-action: none;
+
+  &::before {
+    content: '';
+    inline-size: t.space(10);
+    block-size: t.space(1);
+    border-radius: t.radius(pill);
+    background: t.role('fg-muted');
+  }
+}
+
 .panel {
   display: flex;
   flex-direction: column;

package/src/components/Drawer.tsx

@@ -1,6 +1,9 @@
 // Edge-anchored panel, also a native <dialog> so it inherits the top layer and
 // inert background. `side` is logical (`inline-start`/`inline-end`), so a drawer
 // pinned to the start edge lands on the right in an RTL locale automatically.
+//
+// `side="block-end"` is the bottom sheet: with `grabber`, a drag from the grabber (only — the body
+// keeps its scroll) moves it between `half` and `full` or closes it (`drawer-gesture-view.ts`).
 
 import type { JSX } from 'solid-js';
 import { useId } from '../a11y';
@@ -9,6 +12,7 @@ import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
 import { solid } from '../theme/solid-adapter';
 import styles from './Drawer.module.scss';
+import { type DrawerSnap, dragOffset, releaseSnap } from './drawer-gesture-view';
 import { IconButton } from './IconButton';
 
 export type DrawerSide = 'inline-start' | 'inline-end' | 'block-start' | 'block-end';
@@ -22,6 +26,13 @@ export interface DrawerProps {
   side?: DrawerSide | undefined;
   size?: string | undefined;
   footer?: JSX.Element | undefined;
+  /**
+   * `block-end` only: a handle to drag the sheet by. The drag has no keyboard form, so the close
+   * button stays; Esc closes as ever.
+   */
+  grabber?: boolean | undefined;
+  /** The height a `grabber` sheet opens at: `half` (the default) or `full` of the viewport. */
+  snap?: DrawerSnap | undefined;
   class?: string | undefined;
 }
 
@@ -33,6 +44,22 @@ export function Drawer(props: DrawerProps): JSX.Element {
   // Where the press STARTED — the `Dialog` rule: a drag-select begun in the panel and released
   // over the backdrop fires `click` on the <dialog> itself, and closed the drawer mid-selection.
   let pressedBackdrop = false;
+  const sheet = (): boolean => props.grabber === true && props.side === 'block-end';
+  const [snap, setSnap] = rt.createSignal<DrawerSnap>(props.snap ?? 'half');
+  let drag: { readonly pointer: number; readonly y: number; readonly height: number } | undefined;
+
+  const endDrag = (event: PointerEvent, release: boolean): void => {
+    if (drag === undefined || event.pointerId !== drag.pointer || element === undefined) return;
+    const delta = event.clientY - drag.y;
+    const height = drag.height;
+    drag = undefined;
+    element.style.removeProperty('--drawer-drag');
+    element.removeAttribute('data-dragging');
+    if (!release) return;
+    const next = releaseSnap(delta, height, snap());
+    if (next === 'close') props.onClose();
+    else setSnap(next);
+  };
 
   rt.createEffect(() => {
     const dialog = element;
@@ -51,6 +78,7 @@ export function Drawer(props: DrawerProps): JSX.Element {
       }}
       class={cx(styles['drawer'], styles[`side-${props.side ?? 'inline-end'}`], props.class)}
       style={{ '--drawer-size': props.size ?? '22rem' }}
+      data-snap={sheet() ? snap() : undefined}
       aria-labelledby={titleId}
       onCancel={(event) => {
         event.preventDefault();
@@ -66,6 +94,34 @@ export function Drawer(props: DrawerProps): JSX.Element {
       }}
     >
       <div class={styles['panel']}>
+        {sheet() ? (
+          // Pointer events here and nowhere else, `touch-action: none` on this box only: a drag
+          // that began in the body would steal its scroll.
+          <div
+            class={styles['grabber']}
+            aria-hidden="true"
+            onPointerDown={(event) => {
+              if (element === undefined) return;
+              drag = {
+                pointer: event.pointerId,
+                y: event.clientY,
+                height: element.getBoundingClientRect().height,
+              };
+              // A touch is captured by its target already; a mouse that leaves the grabber is not.
+              if (event.pointerType === 'mouse') {
+                event.currentTarget.setPointerCapture(event.pointerId);
+              }
+              element.setAttribute('data-dragging', '');
+            }}
+            onPointerMove={(event) => {
+              if (drag === undefined || event.pointerId !== drag.pointer) return;
+              const offset = dragOffset(event.clientY - drag.y, snap());
+              element?.style.setProperty('--drawer-drag', `${offset}px`);
+            }}
+            onPointerUp={(event) => endDrag(event, true)}
+            onPointerCancel={(event) => endDrag(event, false)}
+          />
+        ) : null}
         <header class={styles['header']}>
           <h2 class={styles['title']} id={titleId}>
             {props.title}

package/src/components/Gauge.module.scss

@@ -33,6 +33,14 @@
   fill: var(--tone);
 }
 
+// The target: a stroke of the strongest text colour across the ring, in every tone.
+.target {
+  stroke: t.role('fg-strong');
+  stroke-width: 2;
+  stroke-linecap: round;
+  vector-effect: non-scaling-stroke;
+}
+
 // HTML over the dial's centre, so the figure keeps its type step at every gauge size. The ring's
 // centre is not the box's — the open quarter is cropped — so `--centre` carries where it is.
 .readout {

package/src/components/Gauge.tsx

@@ -1,24 +1,32 @@
 // 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.
+// in its centre and its label under it. `null` is unknown: the track alone and `ui.chart.none`,
+// never an empty dial that reads as zero. Thresholds pick the tone; a target is a tick.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
 import { ChartFrame } from './ChartFrame';
+import { checkThresholds } from './chart-checks';
 import { chartPercentFormat, cssPercent } from './chart-frame-view';
 import styles from './Gauge.module.scss';
-import { GAUGE, gaugeArcs } from './gauge-view';
+import type { GaugeThreshold } from './gauge-view';
+import { GAUGE, gaugeArcs, gaugeTick, thresholdTone } 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;
+  /** `null` is unknown: the track alone, and the readout says so. */
+  value: number | null;
   max: number;
-  /** The fill's colour role. Default `accent`; a caller picks `warning`/`danger` by threshold. */
+  /** The fill's colour role below every threshold. Default `accent`. */
   tone?: Tone | undefined;
+  /** Ascending by `at` (the value's unit): the highest one reached sets the fill's tone. */
+  thresholds?: readonly GaugeThreshold[] | undefined;
+  /** A tick across the ring at this value — the goal the fill is read against. */
+  target?: number | 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>`. */
@@ -27,15 +35,28 @@ export interface GaugeProps {
 
 export function Gauge(props: GaugeProps): JSX.Element {
   const ui = useUi();
-  const share = (): number => meterShare(props.value, props.max);
-  const readout = (): string =>
-    props.format === undefined
+  const known = (): number | null =>
+    props.value !== null && Number.isFinite(props.value) ? props.value : null;
+  const share = (): number => meterShare(known() ?? 0, props.max);
+  const readout = (): string => {
+    const value = known();
+    if (value === null) return ui.t(UI_KEYS.chartNone);
+    return props.format === undefined
       ? chartPercentFormat(ui.locale)(share())
-      : props.format(props.value, props.max);
+      : props.format(value, props.max);
+  };
   const arcs = () => gaugeArcs(share());
+  const tone = (): Tone => {
+    checkThresholds('Gauge', props.thresholds ?? []);
+    return thresholdTone(known(), props.thresholds, props.tone ?? 'accent');
+  };
+  const target = (): number | null =>
+    props.target !== undefined && Number.isFinite(props.target) && props.max > 0
+      ? meterShare(props.target, props.max)
+      : null;
   return (
     <ChartFrame label={props.label} showCaption class={cx(styles['gauge'], props.class)}>
-      <div class={cx(styles['dial'], styles[`tone-${props.tone ?? 'accent'}`])}>
+      <div class={cx(styles['dial'], styles[`tone-${tone()}`])} data-tone={tone()}>
         {/* 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 */}
@@ -45,12 +66,18 @@ export function Gauge(props: GaugeProps): JSX.Element {
           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-valuemax={meterAria(known() ?? 0, props.max).max}
+          // `meter` requires a now; for an unknown value the text below is what is spoken.
+          aria-valuenow={meterAria(known() ?? 0, props.max).now}
           aria-valuetext={readout()}
         >
           <path class={styles['track']} d={arcs().track} />
-          {arcs().fill === '' ? null : <path class={styles['fill']} d={arcs().fill} />}
+          {arcs().fill === '' || known() === null ? null : (
+            <path class={styles['fill']} d={arcs().fill} />
+          )}
+          {target() === null ? null : (
+            <path class={styles['target']} d={gaugeTick(target() ?? 0)} data-target="true" />
+          )}
         </svg>
         {/* aria-hidden: the meter already speaks this as its value text. */}
         <span