@ultimat3/ui 29.4.0 → 30.0.0

package/src/components/Tree.module.scss

@@ -0,0 +1,98 @@
+@use '../tokens' as t;
+
+.tree {
+  font-size: t.text(sm);
+}
+
+.root,
+.group {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+// Indent caps at a few levels: past it, a deep path still fits a phone and stays readable.
+.group {
+  padding-inline-start: min(t.space(4), 4vw);
+}
+
+.item {
+  min-inline-size: 0;
+}
+
+.link,
+.summary,
+.row {
+  display: flex;
+  align-items: center;
+  gap: t.space(2);
+  min-block-size: t.touch(target);
+  @include t.padding-inline(t.space(2));
+  border-radius: t.radius(sm);
+  color: t.role('fg');
+  overflow-wrap: anywhere;
+  cursor: pointer;
+
+  &:hover {
+    background: t.role('bg-soft');
+  }
+}
+
+.link {
+  text-decoration: none;
+
+  &[aria-current='page'] {
+    color: t.role('accent-strong');
+    font-weight: t.weight(semibold);
+    background: t.role('accent', 0.12);
+  }
+}
+
+.link:focus-visible,
+.summary:focus-visible,
+.item[role='treeitem']:focus-visible > .row {
+  outline: t.stroke(thick) solid t.role('accent');
+  outline-offset: calc(-1 * #{t.stroke(thick)});
+}
+
+.item[role='treeitem'] {
+  outline: none;
+}
+
+.item[aria-selected='true'] > .row {
+  color: t.role('accent-strong');
+  background: t.role('accent', 0.12);
+}
+
+.item[aria-disabled='true'] > .row {
+  color: t.role('fg-muted');
+  cursor: not-allowed;
+}
+
+.twisty {
+  display: inline-block;
+  inline-size: t.space(3);
+  color: t.role('fg-muted');
+
+  &[data-open] {
+    transform: rotate(90deg);
+  }
+}
+
+// Under `dir="rtl"` the closed marker points inward from the other side.
+:global([dir='rtl']) .twisty:not([data-open]) {
+  transform: scaleX(-1);
+}
+
+.label {
+  min-inline-size: 0;
+}
+
+.loading {
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+}
+
+.branch {
+  margin: 0;
+}

package/src/components/Tree.tsx

@@ -0,0 +1,185 @@
+// Files, folders, org charts: one node list, two renderings. With `hrefFor` it is nested `<ul>` and
+// `<details>` with links — open and close are the platform's, 0 B of script. With `onSelect` it is
+// an APG `role="tree"` with one tab stop, arrows, type-ahead and lazy children: an island's.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { TREE_ITEM_SELECTOR } from '../roving';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import styles from './Tree.module.scss';
+import { type TreeItemState, TreeLinkNode, TreeSelectNode } from './tree-node';
+import {
+  flattenTree,
+  type TreeNode,
+  treeAncestors,
+  treeMove,
+  treeTypeahead,
+  visibleTreeIds,
+  withLoadedChildren,
+} from './tree-view';
+
+interface TreeBaseProps {
+  nodes: readonly TreeNode[];
+  /** Already-translated accessible name. */
+  label: string;
+  /** The current node: `aria-current="page"` in link mode, `aria-selected` in select mode. Its ancestors open. */
+  selected?: string | undefined;
+  /** Branches open on first render, beside the selected node's ancestors. */
+  open?: readonly string[] | undefined;
+  class?: string | undefined;
+}
+
+/** Link mode: every leaf is a link. Works with scripting off. */
+export interface TreeLinkProps extends TreeBaseProps {
+  hrefFor: (node: TreeNode) => string;
+  onSelect?: undefined;
+  onExpand?: undefined;
+}
+
+/** Select mode, in an island: `role="tree"`, and `onExpand` fetches a `lazy` node's children. */
+export interface TreeSelectProps extends TreeBaseProps {
+  onSelect: (id: string) => void;
+  onExpand?: ((id: string) => Promise<readonly TreeNode[]>) | undefined;
+  hrefFor?: undefined;
+}
+
+export type TreeProps = TreeLinkProps | TreeSelectProps;
+
+const MODIFIED = (event: KeyboardEvent): boolean => event.ctrlKey || event.metaKey || event.altKey;
+
+export function Tree(props: TreeProps): JSX.Element {
+  const rt = solid();
+  const ui = useUi();
+  const [loaded, setLoaded] = rt.createSignal<ReadonlyMap<string, readonly TreeNode[]>>(new Map());
+  const [loading, setLoading] = rt.createSignal<ReadonlySet<string>>(new Set());
+  const nodes = rt.createMemo(() => withLoadedChildren(props.nodes, loaded()));
+  const flat = rt.createMemo(() => flattenTree(nodes()));
+  const initialOpen = (): ReadonlySet<string> =>
+    new Set([...(props.open ?? []), ...treeAncestors(flat(), props.selected)]);
+  const [open, setOpen] = rt.createSignal<ReadonlySet<string>>(initialOpen());
+  const [active, setActive] = rt.createSignal<string | undefined>(undefined);
+  let root: HTMLUListElement | undefined;
+
+  const states = rt.createMemo(
+    () =>
+      new Map<string, TreeItemState>(
+        flat().map((entry) => [
+          entry.node.id,
+          {
+            level: entry.level,
+            setsize: entry.setsize,
+            posinset: entry.posinset,
+            branch: entry.branch,
+          },
+        ]),
+      ),
+  );
+
+  /** One tab stop: the node last moved to, else the selected one if reachable, else the first. */
+  const stop = (): string | undefined => {
+    const visible = visibleTreeIds(flat(), open());
+    const chosen = active() ?? props.selected;
+    return chosen !== undefined && visible.includes(chosen) ? chosen : visible[0];
+  };
+
+  const focusNode = (id: string): void => {
+    setActive(id);
+    const items =
+      root === undefined ? [] : [...root.querySelectorAll<HTMLElement>(TREE_ITEM_SELECTOR)];
+    items.find((item) => item.dataset['treeId'] === id)?.focus();
+  };
+
+  const setNodeOpen = (id: string, next: boolean): void => {
+    const copy = new Set(open());
+    if (next) copy.add(id);
+    else copy.delete(id);
+    setOpen(copy);
+    const node = flat().find((entry) => entry.node.id === id)?.node;
+    const onExpand = props.onExpand;
+    if (!next || onExpand === undefined || node?.lazy !== true || loaded().has(id)) return;
+    setLoading(new Set([...loading(), id]));
+    const settle = (): void => setLoading(new Set([...loading()].filter((each) => each !== id)));
+    void onExpand(id).then(
+      (children) => {
+        setLoaded(new Map([...loaded(), [id, children]]));
+        settle();
+      },
+      (error: unknown) => {
+        // Closed again, and the rejection kept: a fetch that failed is the caller's to report.
+        settle();
+        setOpen(new Set([...open()].filter((each) => each !== id)));
+        throw error;
+      },
+    );
+  };
+
+  const activate = (id: string): void => {
+    setActive(id);
+    props.onSelect?.(id);
+    if (states().get(id)?.branch === true) setNodeOpen(id, !open().has(id));
+  };
+
+  const onKeyDown = (event: KeyboardEvent): void => {
+    const item = (event.target as Element | null)?.closest?.('[role="treeitem"]');
+    const current = item instanceof HTMLElement ? item.dataset['treeId'] : undefined;
+    if (current === undefined) return;
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      activate(current);
+      return;
+    }
+    const move = treeMove(flat(), open(), current, event.key, ui.dir);
+    if (move !== undefined) {
+      event.preventDefault();
+      if (move.kind === 'focus') focusNode(move.id);
+      else setNodeOpen(move.id, move.kind === 'open');
+      return;
+    }
+    if (event.key.length === 1 && !MODIFIED(event)) {
+      const found = treeTypeahead(flat(), open(), current, event.key, ui.locale);
+      if (found !== undefined) focusNode(found);
+    }
+  };
+
+  return (
+    <div class={cx(styles['tree'], props.class)}>
+      {props.hrefFor !== undefined ? (
+        <ul class={styles['root']} aria-label={props.label}>
+          {nodes().map((node) => (
+            <TreeLinkNode
+              node={node}
+              hrefFor={props.hrefFor as (node: TreeNode) => string}
+              selected={props.selected}
+              open={initialOpen()}
+            />
+          ))}
+        </ul>
+      ) : (
+        <ul
+          class={styles['root']}
+          // biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: APG's tree is a list of items, one keydown on the root
+          role="tree"
+          aria-label={props.label}
+          onKeyDown={onKeyDown}
+          ref={(el: HTMLUListElement) => {
+            root = el;
+          }}
+        >
+          {nodes().map((node) => (
+            <TreeSelectNode
+              node={node}
+              state={(id) => states().get(id)}
+              isOpen={(id) => open().has(id)}
+              isLoading={(id) => loading().has(id)}
+              isStop={(id) => stop() === id}
+              selected={props.selected}
+              childrenOf={(each) => each.children ?? []}
+              onActivate={activate}
+            />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/components/VirtualList.module.scss

@@ -0,0 +1,60 @@
+@use '../tokens' as t;
+
+// One row that may SHRINK: an `auto` row grows to every row's height whenever the caller's size is
+// a cap (`max-block-size`) or a flex share rather than a fixed block size, and the list then
+// measures itself as tall as all its rows and draws each one (`ui-virtual-list.e2e.test.ts`).
+.wrap {
+  position: relative;
+  display: grid;
+  grid-template-rows: minmax(0, 1fr);
+  block-size: 100%;
+  min-block-size: 0;
+}
+
+// The caller's box sets the height; this one scrolls inside it. The platform's scroll anchoring
+// is off because the component keeps the reader's row itself, and two anchors fight.
+.box {
+  @include t.custom-scrollbar;
+  min-block-size: 0;
+  overflow-y: auto;
+  overflow-anchor: none;
+  overscroll-behavior: contain;
+  -webkit-overflow-scrolling: touch;
+
+  &:focus-visible {
+    outline: t.stroke(thick) solid t.role('accent');
+    outline-offset: calc(-1 * #{t.stroke(thick)});
+  }
+}
+
+// The padding stands in for the rows not drawn, so the scrollbar is the whole list's.
+.list {
+  margin: 0;
+  padding-block: var(--virtual-before, 0) var(--virtual-after, 0);
+  padding-inline: 0;
+  list-style: none;
+}
+
+.row {
+  display: block;
+}
+
+.toEnd {
+  @include t.touch-target;
+  @include t.padding-inline(t.space(4));
+  position: absolute;
+  inset-block-end: t.space(3);
+  inset-inline-end: t.space(3);
+  border: 1px solid t.role('line');
+  border-radius: t.radius(pill);
+  color: t.role('fg-strong');
+  background: t.role('surface-raised');
+  box-shadow: t.shadow(md);
+  font-size: t.text(sm);
+  cursor: pointer;
+
+  &:focus-visible {
+    outline: t.stroke(thick) solid t.role('accent');
+    outline-offset: t.stroke(thick);
+  }
+}

package/src/components/VirtualList.tsx

@@ -0,0 +1,251 @@
+// A long list that mounts only what is on screen: a real `<ul>` in a scroll box, padded above and
+// below by what is not drawn. Server-rendered, and with scripting off, every row renders — the
+// document carries the whole list. The arithmetic is `virtual-list-view.ts`; this file is wiring.
+
+import { finiteCount, finiteOption } from '@ultimat3/core';
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { invalidValueError } from '../errors';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import type { Accessor } from '../theme/solid-adapter';
+import { solid } from '../theme/solid-adapter';
+import { keyedRows } from './data-table-rows';
+import styles from './VirtualList.module.scss';
+import { domRowOffset, readDomAnchor } from './virtual-list-anchor';
+import { createVirtualListObserver, type VirtualListObserver } from './virtual-list-observer';
+import {
+  anchorAt,
+  anchorCorrection,
+  anchoredScrollTop,
+  assertUniqueKeys,
+  endDistance,
+  nextAtEnd,
+  pruneHeights,
+  rowOffsets,
+  type ScrollAnchor,
+  VIRTUAL_LIST_ESTIMATE,
+  VIRTUAL_LIST_OVERSCAN,
+  visibleRange,
+} from './virtual-list-view';
+
+export interface VirtualListProps<T> {
+  items: readonly T[];
+  /** Unique per item: a visible row keeps its node — and its focus — across a live prepend. */
+  itemKey: (item: T) => string;
+  renderItem: (item: T) => JSX.Element;
+  /** A row's block size in CSS px until it is measured. A right estimate IS fixed-height mode. */
+  estimate?: number | undefined;
+  /** Rows drawn beyond each edge of the box. */
+  overscan?: number | undefined;
+  /** Stay at the end as items arrive, while the reader is there; offer a way back when not. */
+  follow?: boolean | undefined;
+  /** Already-translated accessible name for the list. */
+  label: string;
+  /** Size the box here: the list scrolls inside the caller's height, and a box with none renders every row. */
+  class?: string | undefined;
+}
+
+const px = (value: number): string => `${String(Math.max(0, Math.round(value)))}px`;
+
+/** No smooth scroll by default, and none at all for a reader who asked the platform for less motion. */
+const scrollBehavior = (): ScrollBehavior =>
+  typeof matchMedia === 'function' && !matchMedia('(prefers-reduced-motion: reduce)').matches
+    ? 'smooth'
+    : 'auto';
+
+export function VirtualList<T>(props: VirtualListProps<T>): JSX.Element {
+  const rt = solid();
+  const ui = useUi();
+  const estimate = (): number => {
+    const value = finiteOption('VirtualList', 'estimate', props.estimate ?? VIRTUAL_LIST_ESTIMATE);
+    if (value <= 0) throw invalidValueError('VirtualList estimate', value, 'a block size above 0');
+    return value;
+  };
+  const overscan = (): number =>
+    finiteCount('VirtualList', 'overscan', props.overscan ?? VIRTUAL_LIST_OVERSCAN, 0);
+
+  const heights = new Map<string, number>();
+  const [measured, setMeasured] = rt.createSignal(0);
+  // `undefined` is a server render, which draws every row. In a browser the window stands in for
+  // the box until the box has been measured, so the first paint is a screenful, not the list.
+  const [viewport, setViewport] = rt.createSignal<number | undefined>(
+    typeof window === 'undefined' ? undefined : window.innerHeight,
+  );
+  const [scrollTop, setScrollTop] = rt.createSignal(0);
+  const [behind, setBehind] = rt.createSignal(false);
+  let box: HTMLDivElement | undefined;
+  let observer: VirtualListObserver | undefined;
+  const mounted = new Set<HTMLElement>();
+  let atEnd = true;
+  let anchor: ScrollAnchor | undefined;
+
+  interface Layout {
+    readonly keys: readonly string[];
+    readonly positions: ReadonlyMap<string, number>;
+    readonly offsets: readonly number[];
+  }
+  /** The layout the DOM is drawn from right now: the one a new layout's anchor is read against. */
+  let shown: Layout | undefined;
+
+  /**
+   * Where the reader is, read off the DOM before it changes. Called as a new layout is computed,
+   * so a scroll whose event has not fired yet — a `focus()` that scrolled a row into view, a fling
+   * in the same frame as a live update — is still where the anchor is taken. The DOM, not the
+   * layout: a row drawn but not yet measured sits where the browser put it, not where the estimate
+   * said, and the reader sees the browser's.
+   */
+  const capture = (): void => {
+    if (box === undefined) return;
+    // The DOM's own height, not the layout's, for the same reason.
+    atEnd = nextAtEnd(atEnd, endDistance(box.scrollTop, box.clientHeight, box.scrollHeight));
+    anchor =
+      readDomAnchor(box, mounted) ??
+      (shown === undefined ? undefined : anchorAt(shown.keys, shown.offsets, box.scrollTop));
+  };
+
+  const layout = rt.createMemo((): Layout => {
+    measured();
+    const keys = props.items.map((item) => props.itemKey(item));
+    assertUniqueKeys(keys);
+    const size = estimate();
+    capture();
+    const positions = new Map(keys.map((key, index) => [key, index]));
+    pruneHeights(heights, positions);
+    shown = {
+      keys,
+      positions,
+      offsets: rowOffsets(keys.map((key) => heights.get(key) ?? size)),
+    };
+    return shown;
+  });
+
+  /**
+   * Where the box WILL be scrolled under this layout: at the end for a following reader there,
+   * else wherever keeps the anchored row in place. The range is drawn for that position, not the
+   * stale one — drawn for the stale one, a prepend would unmount the very row being read (and the
+   * focus inside it) before the scroll correction put it back.
+   */
+  const targetTop = (keys: readonly string[], offsets: readonly number[], box: number): number => {
+    // Read before any branch: a memo tracks what its LAST run read, and a run that returned at the
+    // end without reading the scroll position would never hear the reader scroll away from it.
+    const scrolled = scrollTop();
+    const total = offsets[offsets.length - 1] ?? 0;
+    if (props.follow === true && atEnd) return Math.max(0, total - box);
+    const anchored = anchor === undefined ? undefined : anchoredScrollTop(anchor, keys, offsets);
+    return anchored ?? scrolled;
+  };
+
+  const range = rt.createMemo(() => {
+    const { keys, offsets } = layout();
+    const box = viewport();
+    if (box === undefined) return { start: 0, end: offsets.length - 1 };
+    return visibleRange(offsets, targetTop(keys, offsets, box), box, overscan());
+  });
+
+  const rowNode = (item: Accessor<T>, key: string): JSX.Element => (
+    <li
+      class={styles['row']}
+      data-key={key}
+      aria-setsize={layout().keys.length}
+      aria-posinset={(layout().positions.get(key) ?? 0) + 1}
+      ref={(el: HTMLLIElement) => {
+        mounted.add(el);
+        observer?.observe(el);
+        rt.onCleanup(() => {
+          mounted.delete(el);
+          observer?.unobserve(el);
+        });
+      }}
+    >
+      {props.renderItem(item())}
+    </li>
+  );
+  const rowNodes = keyedRows<T, JSX.Element>(rt, (item) => props.itemKey(item), rowNode);
+
+  /** Where the box is now, as the next layout change will need it. */
+  const settle = (): void => {
+    if (box === undefined) return;
+    layout();
+    capture();
+    setScrollTop(box.scrollTop);
+    setBehind(props.follow === true && !atEnd);
+  };
+
+  rt.createEffect(() => {
+    if (box === undefined) return;
+    const target = box;
+    observer = createVirtualListObserver(target, (sizes) => {
+      let changed = false;
+      for (const [key, size] of sizes.rows) {
+        if (heights.get(key) !== size) {
+          heights.set(key, size);
+          changed = true;
+        }
+      }
+      if (sizes.viewport !== undefined) setViewport(sizes.viewport);
+      if (changed) setMeasured(measured() + 1);
+    });
+    for (const element of mounted) observer?.observe(element);
+    setViewport(target.clientHeight);
+    rt.onCleanup(() => observer?.disconnect());
+  });
+
+  // After every layout change AND every move of the drawn range: follow the end if the reader is
+  // there, otherwise put the row they were reading back where it was. The range moves on its own
+  // (the box measured, a scroll settled), and each move swaps drawn rows for estimated padding:
+  // rows measured 31 px against a 48 px estimate left a follower 52 px short, which the hysteresis
+  // then read as scrolled away. The platform's `overflow-anchor` is off; this is the one rule.
+  rt.createEffect(() => {
+    const { keys, offsets } = layout();
+    range();
+    if (box === undefined) return;
+    if (props.follow === true && atEnd) {
+      box.scrollTop = box.scrollHeight;
+    } else if (anchor !== undefined) {
+      const drawn = domRowOffset(box, mounted, anchor.key);
+      const delta =
+        drawn === undefined
+          ? targetTop(keys, offsets, box.clientHeight) - box.scrollTop
+          : anchorCorrection(anchor, drawn);
+      if (Math.abs(delta) >= 1) box.scrollTop += delta;
+    }
+    settle();
+  });
+
+  const toEnd = (): void => {
+    box?.scrollTo({ top: box.scrollHeight, behavior: scrollBehavior() });
+  };
+
+  return (
+    <div class={cx(styles['wrap'], props.class)}>
+      <div
+        class={styles['box']}
+        ref={(el: HTMLDivElement) => {
+          box = el;
+        }}
+        onScroll={settle}
+      >
+        <ul
+          class={styles['list']}
+          // biome-ignore lint/a11y/noRedundantRoles: `list-style: none` drops the implicit role in WebKit
+          role="list"
+          aria-label={props.label}
+          style={{
+            '--virtual-before': px(layout().offsets[range().start] ?? 0),
+            '--virtual-after': px(
+              (layout().offsets[layout().keys.length] ?? 0) - (layout().offsets[range().end] ?? 0),
+            ),
+          }}
+        >
+          {rowNodes(props.items.slice(range().start, range().end))}
+        </ul>
+      </div>
+      {behind() ? (
+        <button type="button" class={styles['toEnd']} onClick={toEnd}>
+          {ui.t(UI_KEYS.listToEnd)}
+        </button>
+      ) : null}
+    </div>
+  );
+}

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

@@ -16,6 +16,8 @@ export interface ShellSlots {
   readonly header: boolean;
   readonly sidebar: boolean;
   readonly footer: boolean;
+  /** `AppShell bottomNav`: a second `navigation` landmark, after the footer in DOM order. */
+  readonly bottomNav?: boolean | undefined;
 }
 
 export function shellIds(base: string): ShellIds {
@@ -25,7 +27,7 @@ export function shellIds(base: string): ShellIds {
 
 /**
  * DOM order, which is also screen-reader order: banner, then navigation, then main, then
- * contentinfo. `main` is unconditional — a shell with no main region is not a page.
+ * contentinfo, then the bottom bar's navigation. `main` is unconditional — a shell with no main region is not a page.
  */
 export function shellLandmarks(slots: ShellSlots): readonly ShellLandmark[] {
   const out: ShellLandmark[] = [];
@@ -33,5 +35,6 @@ export function shellLandmarks(slots: ShellSlots): readonly ShellLandmark[] {
   if (slots.sidebar) out.push('navigation');
   out.push('main');
   if (slots.footer) out.push('contentinfo');
+  if (slots.bottomNav === true) out.push('navigation');
   return out;
 }