@ultimat3/ui 29.4.0 → 30.1.0

package/src/components/SortableList.module.scss

@@ -0,0 +1,72 @@
+@use '../tokens' as t;
+
+// Shared by `SortableList` and `Board` (`sort-surface.tsx`): one gesture, one sheet.
+
+.root {
+  position: relative;
+}
+
+.list {
+  @include t.column(t.space(2));
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  min-block-size: t.touch(target);
+}
+
+.row {
+  @include t.row(t.space(2), center);
+  @include t.transition(box-shadow);
+  position: relative;
+
+  &[data-lifted='true'] {
+    z-index: t.z(raised);
+    box-shadow: t.shadow(lg);
+    // The pointer's offset, written per move: input, not animation, so reduced motion keeps it.
+    transform: translate(var(--drag-x, 0), var(--drag-y, 0));
+  }
+}
+
+.body {
+  flex: 1;
+  min-inline-size: 0;
+}
+
+// The handle is the ONLY place a drag starts, so the row body still scrolls a phone's page.
+.handle {
+  @include t.touch-target;
+  @include t.focus-ring;
+  display: inline-grid;
+  place-items: center;
+  border: 0;
+  border-radius: t.radius(md);
+  background: transparent;
+  color: t.role('fg-muted');
+  cursor: grab;
+  touch-action: none;
+
+  &[aria-pressed='true'] {
+    background: t.role('bg-soft');
+    color: t.role('accent');
+    cursor: grabbing;
+  }
+}
+
+// Without script the handle cannot do anything, so it is not there; the form is.
+.root:not([data-enhanced='true']) .handle {
+  display: none;
+}
+
+.root[data-enhanced='true'] .fallback {
+  display: none;
+}
+
+.fallback {
+  @include t.row(t.space(1), center);
+  flex-wrap: wrap;
+
+  button,
+  select {
+    min-block-size: t.touch(target);
+  }
+}

package/src/components/SortableList.tsx

@@ -0,0 +1,42 @@
+// A list a person reorders by hand: a handle per row that lifts by pointer, touch or keyboard, and
+// a drop that REQUESTS a move through `onMove` — the caller's action decides. With scripting off
+// each row carries Move up and Move down as real form buttons posting to `action`.
+
+import type { JSX } from 'solid-js';
+import type { CanDrop, SortMove } from '../drag/sort-view';
+import { type SortFields, sortSurface } from './sort-surface';
+
+export interface SortableListProps<T> {
+  items: readonly T[];
+  /** Unique per item; the row keeps its node under it across live updates. */
+  itemKey: (item: T) => string;
+  /** The row's look is the caller's: a `Card`, a line of text. */
+  renderItem: (item: T) => JSX.Element;
+  /** Already-translated name of the list, read with every announcement. */
+  label: string;
+  /** Called once per drop that moves something. A rejection puts the row back and says so. */
+  onMove: (move: SortMove) => unknown;
+  canDrop?: CanDrop<T> | undefined;
+  /** The action URL the no-script Up and Down buttons post to. Without it, no fallback renders. */
+  action?: string | undefined;
+  /** The field names those buttons post: `id`, `fromGroup`, `toGroup`, `toIndex` by default. */
+  fields?: SortFields | undefined;
+  /** The id `onMove` names as `fromGroup` and `toGroup`. Defaults to `list`. */
+  group?: string | undefined;
+  class?: string | undefined;
+}
+
+export function SortableList<T>(props: SortableListProps<T>): JSX.Element {
+  return sortSurface<T>({
+    groups: () => [{ id: props.group ?? 'list', label: props.label, items: props.items }],
+    itemKey: (item) => props.itemKey(item),
+    renderItem: (item) => props.renderItem(item),
+    onMove: (move) => props.onMove(move),
+    canDrop: props.canDrop,
+    action: props.action,
+    fields: props.fields,
+    layout: 'list',
+    label: props.label,
+    class: props.class,
+  });
+}

package/src/components/Sparkline.module.scss

@@ -1,5 +1,7 @@
 @use '../tokens' as t;
 
+@include t.tone-classes;
+
 .sparkline {
   display: block;
   inline-size: 100%;
@@ -7,7 +9,7 @@
 }
 
 .line {
-  stroke: t.role('accent');
+  stroke: var(--tone);
   stroke-width: 2;
   // The box scales with its column; the line must not (it rendered ~7px thick at full width).
   vector-effect: non-scaling-stroke;
@@ -15,6 +17,12 @@
   stroke-linecap: round;
 }
 
+.area {
+  fill: var(--tone);
+  fill-opacity: 0.16;
+  stroke: none;
+}
+
 .last {
-  fill: t.role('accent');
+  fill: var(--tone);
 }

package/src/components/Sparkline.tsx

@@ -1,32 +1,49 @@
 // One series as a single line with no axes — the trend beside a figure, in a table cell, on a
-// detail page. Static SVG for `BarChart`'s reason: the framework's own docs use a sparkline
-// pulling in a chart library as the cautionary example, and this file IS that sparkline written
-// the way the docs say to. The path comes from `sparkline-view.ts`.
+// StatTile. Static SVG for `BarChart`'s reason: the framework's own docs use a sparkline pulling
+// in a chart library as the cautionary example, and this file IS that sparkline written the way
+// the docs say to. Signed through zero; the path and the area come from `sparkline-view.ts`.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
-import type { ChartPoint } from './bar-chart-view';
 import styles from './Sparkline.module.scss';
-import { SPARKLINE, sparklinePath, sparkPoints } from './sparkline-view';
+import {
+  SPARKLINE,
+  type SparklinePoint,
+  sparkAreaPath,
+  sparklinePath,
+  sparkPoints,
+} from './sparkline-view';
+import type { Tone } from './variants';
 
 export interface SparklineProps {
   /** The accessible name for the whole chart, already translated. */
   label: string;
-  /** Oldest first. Every point comes from exactly this array — the caller zero-fills gaps. */
-  points: readonly ChartPoint[];
+  /** Oldest first. `value: null` is unknown — a gap in the line, never a zero. */
+  points: readonly SparklinePoint[];
+  /** The line's colour role, in place of `accent`. */
+  tone?: Tone | undefined;
+  /** Fill under the line, down to zero — above it for a gain, below it for a loss. */
+  area?: boolean | undefined;
   class?: string | undefined;
 }
 
 export function Sparkline(props: SparklineProps): JSX.Element {
-  const last = (): ChartPoint | undefined => props.points.at(-1);
-  const lastPoint = () => sparkPoints(props.points).at(-1);
+  // The newest point is marked only when it is known: an unknown "now" has no place to sit.
+  const last = (): SparklinePoint | undefined => {
+    const newest = props.points.at(-1);
+    return newest?.value === null ? undefined : newest;
+  };
+  const lastPoint = () => sparkPoints(props.points).at(-1) ?? undefined;
   return (
     <svg
       role="img"
       aria-label={props.label}
       viewBox={`0 0 ${SPARKLINE.width} ${SPARKLINE.height}`}
-      class={cx(styles['sparkline'], props.class)}
+      class={cx(styles['sparkline'], styles[`tone-${props.tone ?? 'accent'}`], props.class)}
     >
+      {props.area === true ? (
+        <path class={styles['area']} d={sparkAreaPath(props.points)} data-area="true" />
+      ) : null}
       <path class={styles['line']} d={sparklinePath(props.points)} fill="none" />
       {last() === undefined ? null : (
         <circle class={styles['last']} cx={lastPoint()?.x} cy={lastPoint()?.y} r={2}>

package/src/components/SplitPane.module.scss

@@ -0,0 +1,39 @@
+@use '../tokens' as t;
+
+// One column on a phone; from `md` a grid whose first track is `--split`, written by the
+// component (scripting off: the `defaultValue` it rendered with).
+.split {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: t.space(4);
+
+  @include t.respond-to(md) {
+    grid-template-columns: minmax(0, var(--split, 50%)) auto minmax(0, 1fr);
+    gap: 0;
+  }
+}
+
+.pane {
+  min-inline-size: 0;
+  overflow: auto;
+}
+
+.separator {
+  display: none;
+
+  @include t.respond-to(md) {
+    @include t.focus-ring;
+    display: block;
+    inline-size: t.space(2);
+    margin-inline: t.space(1);
+    border-radius: t.radius(pill);
+    background: t.role('line');
+    cursor: col-resize;
+    touch-action: none;
+
+    &:hover,
+    &:focus-visible {
+      background: t.role('accent');
+    }
+  }
+}

package/src/components/SplitPane.tsx

@@ -0,0 +1,96 @@
+// Two panes and a `role="separator"` between them, its value a percentage of the start pane. Arrows
+// step it, Home and End go to the bounds, a pointer drags it, Esc mid-drag restores. Below `md` the
+// panes stack and the separator is gone: no gesture on a phone. Storage is the caller's.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { bindPointerDrag } from '../drag/pointer-drag';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import styles from './SplitPane.module.scss';
+import { paneBounds, paneKey, panePercentAt, paneValue } from './split-pane-view';
+
+export interface SplitPaneProps {
+  start: JSX.Element;
+  end: JSX.Element;
+  /** Controlled: the start pane's share in percent. Pair it with `onResize`. */
+  value?: number | undefined;
+  /** Where the split sits before any input, and with scripting off. */
+  defaultValue: number;
+  min?: number | undefined;
+  max?: number | undefined;
+  /** Each change, in percent. Persisting it is the caller's: storage is never ambient. */
+  onResize?: ((percent: number) => void) | undefined;
+  /** Already-translated name of the separator; defaults to `ui.pane.resize`. */
+  label?: string | undefined;
+  class?: string | undefined;
+}
+
+export function SplitPane(props: SplitPaneProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const bounds = (): ReturnType<typeof paneBounds> => paneBounds(props.min, props.max);
+  const [own, setOwn] = rt.createSignal(paneValue(props.defaultValue, bounds()));
+  const value = (): number =>
+    props.value === undefined ? own() : paneValue(props.value, bounds());
+  const set = (next: number): void => {
+    if (next === value()) return;
+    setOwn(next);
+    props.onResize?.(next);
+  };
+  let root: HTMLDivElement | undefined;
+
+  const bind = (separator: HTMLDivElement): void => {
+    if (typeof document === 'undefined' || typeof separator.setPointerCapture !== 'function')
+      return;
+    let before = value();
+    const at = (x: number): number => {
+      const rect = root?.getBoundingClientRect();
+      return rect === undefined
+        ? value()
+        : panePercentAt(x, { start: rect.left, size: rect.width }, bounds(), ui.dir);
+    };
+    rt.onCleanup(
+      bindPointerDrag(separator, {
+        start: () => {
+          before = value();
+        },
+        move: (point) => set(at(point.x)),
+        drop: (point) => set(at(point.x)),
+        cancel: () => set(before),
+      }),
+    );
+  };
+
+  return (
+    <div
+      class={cx(styles['split'], props.class)}
+      style={{ '--split': `${value()}%` }}
+      ref={(el: HTMLDivElement) => {
+        root = el;
+      }}
+    >
+      <div class={styles['pane']}>{props.start}</div>
+      {/* biome-ignore lint/a11y/useSemanticElements: a FOCUSABLE separator with a value; <hr> takes neither */}
+      <div
+        class={styles['separator']}
+        role="separator"
+        tabindex="0"
+        aria-orientation="vertical"
+        aria-label={props.label ?? ui.t(UI_KEYS.paneResize)}
+        aria-valuenow={value()}
+        aria-valuemin={bounds().min}
+        aria-valuemax={bounds().max}
+        ref={bind}
+        onKeyDown={(event: KeyboardEvent) => {
+          const next = paneKey(event.key, value(), bounds(), ui.dir);
+          if (next === null) return;
+          event.preventDefault();
+          set(next);
+        }}
+      />
+      <div class={styles['pane']}>{props.end}</div>
+    </div>
+  );
+}

package/src/components/StatTile.module.scss

@@ -64,21 +64,47 @@
   stroke-linejoin: round;
 }
 
-.trend-up {
+// The chip's colour is what the caller said a direction MEANS (`goodWhen`), never the direction:
+// an error rate rising is `bad`. The arrow carries the direction in every mood.
+.mood-good {
   background: t.role('success-soft');
   color: t.role('success');
 }
 
-.trend-down {
+.mood-bad {
   background: t.role('danger-soft');
   color: t.role('danger');
 }
 
-.trend-flat {
+.mood-neutral {
   background: t.role('surface-raised');
   color: t.role('fg-muted');
 }
 
+.of {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  font-weight: t.weight(normal);
+}
+
+.trend {
+  block-size: t.space(8);
+}
+
+// A whole-tile link: the tile's own hover, a focus ring, and no underline on the figure.
+.linked {
+  @include t.focus-ring;
+  color: inherit;
+  text-decoration: none;
+}
+
+// A status edge on the inline start, from the tone's custom property.
+@include t.tone-classes;
+
+.toned {
+  border-inline-start: t.stroke(thick) solid var(--tone);
+}
+
 .hint {
   margin: 0;
   color: t.role('fg-muted');

package/src/components/StatTile.tsx

@@ -1,16 +1,20 @@
-// One labelled figure with an optional trend chip and a line of context — the tile a dashboard's
-// top row is made of. The figure arrives formatted: number formatting is the caller's
-// (`Intl.NumberFormat` against the page locale), so the tile never guesses a locale.
+// One labelled figure with an optional trend chip, a sparkline and a line of context — the tile a
+// dashboard's top row is made of. The figure arrives formatted (the caller's `Intl.NumberFormat`),
+// and whether up is good is the caller's one prop (`goodWhen`): the arrow always shows the way,
+// the colour only what the caller said it means.
 //
 // Intrinsic tags only: a runtime-chosen root (`const Tag = props.as ?? 'div'`) is called as a
-// component by the island build, so a tile built on `Card` hydrated differently from how it was
-// served. A `<div>` renders identically on both sides.
+// component by the island build, so a linked tile is a second literal `<a>`, never a variable tag.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
+import { Skeleton } from './Skeleton';
+import { Sparkline } from './Sparkline';
 import styles from './StatTile.module.scss';
-import type { StatDelta } from './stat-delta';
-import { DELTA_ARROW_PATH } from './stat-delta';
+import type { SparklinePoint } from './sparkline-view';
+import type { StatDelta, StatGoodWhen } from './stat-delta';
+import { DELTA_ARROW_PATH, deltaMood } from './stat-delta';
+import type { Tone } from './variants';
 
 export interface StatTileProps {
   /** The tile's caption, already translated — "Total links", "Clicks today". */
@@ -21,21 +25,55 @@ export interface StatTileProps {
   stat: string;
   /** The trend chip; `deltaOf()` builds one from a current and a baseline. */
   delta?: StatDelta | undefined;
+  /** Which direction of `delta` is good news. Default `'up'`; `'none'` colours neither. */
+  goodWhen?: StatGoodWhen | undefined;
+  /** The denominator, formatted — "of 40" reads after the figure: "12 of 40". */
+  of?: string | undefined;
+  /** The recent series behind the figure, oldest first; `null` is a gap. */
+  trend?: readonly SparklinePoint[] | undefined;
+  /** A status edge on the tile — `danger` for a figure past its limit. */
+  tone?: Tone | undefined;
+  /** The page behind the figure: the whole tile becomes one link. */
+  href?: string | undefined;
+  /** The figure is on its way: a skeleton in its box, so the row does not shift when it lands. */
+  loading?: boolean | undefined;
   /** One short line of context under the figure: "vs yesterday", "849 clicks". */
   hint?: string | undefined;
   class?: string | undefined;
 }
 
 export function StatTile(props: StatTileProps): JSX.Element {
-  return (
-    <div class={cx(styles['tile'], props.class)}>
+  const classes = (): string =>
+    cx(
+      styles['tile'],
+      props.tone !== undefined && [styles['toned'], styles[`tone-${props.tone}`]],
+      props.href !== undefined && styles['linked'],
+      props.class,
+    );
+  const body = (): JSX.Element => (
+    <>
       <p class={styles['label']}>{props.label}</p>
-      <div class={styles['figure']}>
-        <p class={styles['value']} data-stat={props.stat}>
-          {props.value}
-        </p>
-        {props.delta === undefined ? null : (
-          <span class={cx(styles['delta'], styles[`trend-${props.delta.trend}`])}>
+      <div class={styles['figure']} aria-busy={props.loading === true ? 'true' : undefined}>
+        {props.loading === true ? (
+          <span class={styles['value']}>
+            <Skeleton width="6ch" height="1em" />
+          </span>
+        ) : (
+          <p class={styles['value']} data-stat={props.stat}>
+            {props.value}
+          </p>
+        )}
+        {/* Beside the figure, not in it: `data-stat` reads the number alone. */}
+        {props.of === undefined ? null : <span class={styles['of']}>{props.of}</span>}
+        {props.delta === undefined || props.loading === true ? null : (
+          <span
+            class={cx(
+              styles['delta'],
+              styles[`mood-${deltaMood(props.delta.trend, props.goodWhen ?? 'up')}`],
+            )}
+            data-trend={props.delta.trend}
+            data-mood={deltaMood(props.delta.trend, props.goodWhen ?? 'up')}
+          >
             <svg viewBox="0 0 10 10" aria-hidden="true" class={styles['arrow']}>
               <path d={DELTA_ARROW_PATH[props.delta.trend]} />
             </svg>
@@ -43,7 +81,28 @@ export function StatTile(props: StatTileProps): JSX.Element {
           </span>
         )}
       </div>
+      {props.trend === undefined ? null : (
+        <Sparkline
+          label={props.label}
+          points={props.trend}
+          tone={props.tone}
+          class={styles['trend']}
+        />
+      )}
       {props.hint === undefined ? null : <p class={styles['hint']}>{props.hint}</p>}
-    </div>
+    </>
+  );
+  // The branch inside the JSX: in an island the body runs once, and a branch decided there would
+  // keep the first answer for the island's life.
+  return (
+    <>
+      {props.href === undefined ? (
+        <div class={classes()}>{body()}</div>
+      ) : (
+        <a class={classes()} href={props.href}>
+          {body()}
+        </a>
+      )}
+    </>
   );
 }

package/src/components/Stepper.module.scss

@@ -0,0 +1,78 @@
+@use '../tokens' as t;
+
+.stepper {
+  min-inline-size: 0;
+}
+
+// The phone's form: one line. The list stays in the accessibility tree, visually hidden, so the
+// reader still hears every step; the line is the sighted summary and is hidden from the tree.
+.compact {
+  display: none;
+  color: t.role('fg');
+  font-weight: t.weight(medium);
+
+  @include t.respond-down(sm) {
+    display: block;
+  }
+}
+
+.list {
+  display: flex;
+  gap: t.space(4);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+
+  @include t.respond-down(sm) {
+    @include t.visually-hidden;
+  }
+}
+
+.item {
+  display: flex;
+  min-inline-size: 0;
+}
+
+.step {
+  @include t.focus-ring;
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(2);
+  border: 0;
+  background: none;
+  color: t.role('fg-muted');
+  font: inherit;
+  text-decoration: none;
+
+  &[aria-current='step'] {
+    color: t.role('fg-strong');
+    font-weight: t.weight(semibold);
+  }
+}
+
+a.step,
+button.step {
+  color: t.role('accent');
+  cursor: pointer;
+}
+
+.marker {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: t.space(6);
+  block-size: t.space(6);
+  border: 1px solid currentcolor;
+  border-radius: t.radius(full);
+  font-size: t.text(xs);
+}
+
+.item[data-state='current'] .marker {
+  border-color: t.role('accent');
+  background: t.role('accent');
+  color: t.role('accent-fg');
+}
+
+.label {
+  @include t.truncate;
+}

package/src/components/Stepper.tsx

@@ -0,0 +1,73 @@
+// Progress through a multi-step flow: an `<ol>`, the current step `aria-current="step"`, a passed
+// step a link (its `href`) or a button (`onSelect`) and an upcoming one plain text. Exactly one
+// current, by `stepperModel`. Below `sm` the list folds into one line, "Step {n} of {total}: Details".
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { linkTarget } from './link-target';
+import styles from './Stepper.module.scss';
+import { type StepperStep, stepperModel } from './stepper-view';
+
+export interface StepperProps {
+  steps: readonly StepperStep[];
+  /** Already-translated name of the list — "Checkout progress". */
+  label: string;
+  /** A passed step with no `href` becomes a button that calls this. */
+  onSelect?: ((id: string) => void) | undefined;
+  class?: string | undefined;
+}
+
+export function Stepper(props: StepperProps): JSX.Element {
+  const ui = useUi();
+  const model = stepperModel(props.steps);
+  const current = props.steps[model.current];
+
+  const body = (step: StepperStep, index: number): JSX.Element => {
+    const marker = <span class={styles['marker']}>{index + 1}</span>;
+    const text = <span class={styles['label']}>{step.label}</span>;
+    if (step.state === 'done' && step.href !== undefined) {
+      return (
+        <a class={styles['step']} href={linkTarget(step.href).href}>
+          {marker}
+          {text}
+        </a>
+      );
+    }
+    const onSelect = props.onSelect;
+    if (step.state === 'done' && onSelect !== undefined) {
+      return (
+        <button type="button" class={styles['step']} onClick={() => onSelect(step.id)}>
+          {marker}
+          {text}
+        </button>
+      );
+    }
+    return (
+      <span class={styles['step']} aria-current={step.state === 'current' ? 'step' : undefined}>
+        {marker}
+        {text}
+      </span>
+    );
+  };
+
+  return (
+    <div class={cx(styles['stepper'], props.class)}>
+      <p class={styles['compact']} aria-hidden="true">
+        {ui.t(UI_KEYS.step, {
+          current: model.current + 1,
+          total: model.total,
+          label: current?.label ?? '',
+        })}
+      </p>
+      <ol class={styles['list']} aria-label={props.label}>
+        {props.steps.map((step, index) => (
+          <li class={styles['item']} data-state={step.state}>
+            {body(step, index)}
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}