@ultimat3/ui 29.3.2 → 30.0.0

package/src/components/LogViewer.tsx

@@ -0,0 +1,123 @@
+// Structured log rows on `VirtualList`: a 100,000-line run mounts a screenful, follows the end
+// while the reader is there, and keeps only the newest `cap` lines. With script, a text filter, a
+// level floor and a follow toggle; without it, every line given is in the document.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import { DateTime } from './DateTime';
+import { Link } from './Link';
+import styles from './LogViewer.module.scss';
+import { LOG_VIEWER_LEVELS, type LogLine, type LogViewerLevel, logWindow } from './log-viewer-view';
+import { VirtualList } from './VirtualList';
+
+export interface LogViewerProps {
+  lines: readonly LogLine[];
+  /** Already-translated name of the log; defaults to `ui.log.region`. */
+  label?: string | undefined;
+  /** Start following the end. Defaults to true; the reader can turn it off. */
+  follow?: boolean | undefined;
+  /** The newest lines kept. Defaults to 10,000. */
+  cap?: number | undefined;
+  class?: string | undefined;
+}
+
+const isLevel = (value: string): value is LogViewerLevel =>
+  (LOG_VIEWER_LEVELS as readonly string[]).includes(value);
+
+export function LogViewer(props: LogViewerProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const [enhanced, setEnhanced] = rt.createSignal(false);
+  rt.createEffect(() => setEnhanced(true));
+  const [query, setQuery] = rt.createSignal('');
+  const [minimum, setMinimum] = rt.createSignal<LogViewerLevel | undefined>(undefined);
+  const [follow, setFollow] = rt.createSignal(props.follow !== false);
+  const shown = rt.createMemo(() =>
+    logWindow(props.lines, {
+      query: query(),
+      minimum: minimum(),
+      cap: props.cap,
+      locale: ui.locale,
+    }),
+  );
+  const label = (): string => props.label ?? ui.t(UI_KEYS.logRegion);
+
+  const row = (line: LogLine): JSX.Element => (
+    <div class={styles['line']} data-level={line.level}>
+      {line.at === undefined ? (
+        <span />
+      ) : (
+        <DateTime
+          value={line.at}
+          timeZone={ui.timeZone}
+          timeStyle="medium"
+          class={styles['time']}
+        />
+      )}
+      <span class={styles['level']}>{line.level ?? ''}</span>
+      <span class={styles['text']}>
+        {line.href === undefined ? line.text : <Link href={line.href}>{line.text}</Link>}
+      </span>
+    </div>
+  );
+
+  return (
+    <section
+      class={cx(styles['log'], props.class)}
+      aria-label={label()}
+      data-enhanced={enhanced() ? 'true' : undefined}
+    >
+      <div class={styles['bar']}>
+        <input
+          type="search"
+          class={styles['filter']}
+          aria-label={ui.t(UI_KEYS.logFilter)}
+          placeholder={ui.t(UI_KEYS.logFilter)}
+          value={query()}
+          onInput={(event: InputEvent) => setQuery((event.currentTarget as HTMLInputElement).value)}
+        />
+        <select
+          class={styles['levels']}
+          aria-label={ui.t(UI_KEYS.logLevel)}
+          onChange={(event: Event) => {
+            const value = (event.currentTarget as HTMLSelectElement).value;
+            setMinimum(isLevel(value) ? value : undefined);
+          }}
+        >
+          <option value="" selected={minimum() === undefined}>
+            {ui.t(UI_KEYS.logAll)}
+          </option>
+          {LOG_VIEWER_LEVELS.map((level) => (
+            <option value={level} selected={minimum() === level}>
+              {level}
+            </option>
+          ))}
+        </select>
+        <button
+          type="button"
+          class={styles['follow']}
+          aria-pressed={follow() ? 'true' : 'false'}
+          onClick={() => setFollow(!follow())}
+        >
+          {ui.t(UI_KEYS.logFollow)}
+        </button>
+      </div>
+      {shown().dropped > 0 ? (
+        <p class={styles['capped']}>{ui.t(UI_KEYS.logCapped, { count: shown().lines.length })}</p>
+      ) : null}
+      {/* The box is this component's: its height is fixed here, whatever order the sheets load in. */}
+      <div class={styles['box']}>
+        <VirtualList
+          items={shown().lines}
+          itemKey={(line: LogLine) => line.id}
+          renderItem={row}
+          follow={follow()}
+          label={label()}
+        />
+      </div>
+    </section>
+  );
+}

package/src/components/Markdown.module.scss

@@ -0,0 +1,87 @@
+@use '../tokens' as t;
+
+// Body copy never below 16 px on a phone (`text(md)` floors at 1rem); a wide table scrolls in its
+// own box so the page never scrolls sideways.
+.markdown {
+  @include t.column(t.space(3));
+  font-size: t.text(md);
+  line-height: t.leading(normal);
+  color: t.role('fg');
+  overflow-wrap: anywhere;
+
+  p,
+  ul,
+  ol {
+    margin: 0;
+  }
+
+  ul,
+  ol {
+    padding-inline-start: t.space(6);
+  }
+
+  hr {
+    inline-size: 100%;
+    border: 0;
+    border-block-start: t.stroke(hairline) solid t.role('line');
+  }
+}
+
+.heading {
+  margin: 0;
+  color: t.role('fg-strong');
+  line-height: t.leading(tight);
+}
+
+.code {
+  padding-inline: t.space(1);
+  border-radius: t.radius(sm);
+  background: t.role('bg-soft');
+  font-family: var(--font-mono);
+  font-size: t.text(sm);
+}
+
+.quote {
+  @include t.column(t.space(2));
+  @include t.border-inline-start(t.stroke(heavy), 'line');
+  margin: 0;
+  padding-inline-start: t.space(3);
+  color: t.role('fg-muted');
+}
+
+.task {
+  list-style: none;
+
+  input {
+    margin-inline-end: t.space(2);
+  }
+}
+
+.table {
+  max-inline-size: 100%;
+  overflow-x: auto;
+
+  table {
+    border-collapse: collapse;
+  }
+
+  th,
+  td {
+    padding-block: t.space(1);
+    padding-inline: t.space(2);
+    border: t.stroke(hairline) solid t.role('line');
+    text-align: start;
+  }
+
+  [data-align='center'] {
+    text-align: center;
+  }
+
+  [data-align='end'] {
+    text-align: end;
+  }
+}
+
+.rest {
+  white-space: pre-wrap;
+}

package/src/components/Markdown.tsx

@@ -0,0 +1,84 @@
+// What a model or a person wrote, rendered: text → tree → elements, never HTML. Raw HTML, a
+// `javascript:` link and a remote image all print inert. Re-parsed per change and keyed by block
+// index, so a streaming body keeps every finished block's node and only the open one redraws.
+
+import { finiteCount } from '@ultimat3/core';
+import type { JSX } from 'solid-js';
+import { headingIds } from '../content/heading-slug';
+import type { Language } from '../content/highlight';
+import { parseMarkdown } from '../content/markdown-parse';
+import type { MarkdownBlock } from '../content/markdown-tree';
+import { cx } from '../cx';
+import { solid } from '../theme/solid-adapter';
+import { keyedRows } from './data-table-rows';
+import { type HeadingLevel, headingTag } from './heading-level';
+import styles from './Markdown.module.scss';
+import { blockNode, type ResolvedImage } from './markdown-nodes';
+
+export type { ResolvedImage };
+
+export interface MarkdownProps {
+  /** The body. Malformed markdown is never an error: what cannot parse prints as text. */
+  text: string;
+  /** The level a `#` renders at. Defaults to 2: a body never adds a second `h1` to a page. */
+  baseLevel?: 1 | 2 | 3 | 4 | 5 | 6 | undefined;
+  /** Vouch for an image: its served source and box, or `null` to print its alt as a link. */
+  resolveImage?: ((src: string) => ResolvedImage | null) | undefined;
+  /**
+   * Give each heading the id the GitHub wiki would (`headingSlug`), de-duplicated `-1`, `-2` in
+   * order, so a `#anchor` link scrolls. Off by default: two bodies on one page would collide.
+   */
+  headingIds?: boolean | undefined;
+  /** Languages fences may highlight with. Absent: fences are plain text, and an island pays 0 B. */
+  languages?: readonly Language[] | undefined;
+  class?: string | undefined;
+}
+
+export function Markdown(props: MarkdownProps): JSX.Element {
+  const rt = solid();
+  // A level off the 1–6 scale (NaN included) is `X_UI_INVALID_VALUE` from `headingTag`.
+  const base = (): number => {
+    const level = finiteCount('Markdown', 'baseLevel', props.baseLevel ?? 2, 1);
+    headingTag(level as HeadingLevel);
+    return level;
+  };
+  // A block equal to the last parse's block at its index is that same object, so its node and
+  // everything under it stay put while a later block grows.
+  let previous: readonly MarkdownBlock[] = [];
+  let previousJson: readonly string[] = [];
+  const blocks = rt.createMemo((): readonly MarkdownBlock[] => {
+    const parsed = parseMarkdown(props.text);
+    const json = parsed.map((block) => JSON.stringify(block));
+    const stable = parsed.map((block, index) =>
+      json[index] === previousJson[index] ? (previous[index] ?? block) : block,
+    );
+    previous = stable;
+    previousJson = json;
+    return stable;
+  });
+  const ids = rt.createMemo(() => headingIds(blocks()));
+  // Keyed by position: the block at an index is the same object until its content changes.
+  let position = new Map<MarkdownBlock, number>();
+  const nodes = keyedRows<MarkdownBlock, JSX.Element>(
+    rt,
+    (block) => String(position.get(block) ?? -1),
+    (block) => (
+      <>
+        {blockNode(block(), {
+          baseLevel: base(),
+          resolveImage: props.resolveImage,
+          languages: props.languages,
+          ids: props.headingIds === true ? ids() : undefined,
+        })}
+      </>
+    ),
+  );
+
+  const rendered = rt.createMemo(() => {
+    const current = blocks();
+    position = new Map(current.map((block, index) => [block, index]));
+    return nodes(current);
+  });
+
+  return <div class={cx(styles['markdown'], props.class)}>{rendered()}</div>;
+}

package/src/components/Meter.module.scss

@@ -16,3 +16,10 @@
 .fill {
   fill: var(--tone);
 }
+
+// The target tick stands proud of the bar both ways, in the strongest text colour, every tone.
+.target {
+  stroke: t.role('fg-strong');
+  stroke-width: 2;
+  vector-effect: non-scaling-stroke;
+}

package/src/components/Meter.tsx

@@ -18,6 +18,8 @@ export interface MeterProps {
   /** The accessible name. Omit for a purely decorative bar beside a visible number. */
   label?: string | undefined;
   tone?: Tone | undefined;
+  /** A tick at this value — a bullet bar: the fill read against its goal. */
+  target?: number | undefined;
   class?: string | undefined;
 }
 
@@ -25,9 +27,23 @@ export function Meter(props: MeterProps): JSX.Element {
   const share = (): number => meterShare(props.value, props.max);
   const classes = (): string =>
     cx(styles['meter'], styles[`tone-${props.tone ?? 'accent'}`], props.class);
+  const target = (): number | null =>
+    props.target !== undefined && Number.isFinite(props.target) && props.max > 0
+      ? meterShare(props.target, props.max)
+      : null;
   const bars = (): JSX.Element => [
     <rect class={styles['track']} width={100} height={4} rx={2} />,
     <rect class={styles['fill']} width={meterWidth(share())} height={4} rx={2} />,
+    target() === null ? null : (
+      <line
+        class={styles['target']}
+        data-target="true"
+        x1={meterWidth(target() ?? 0)}
+        x2={meterWidth(target() ?? 0)}
+        y1={-2}
+        y2={6}
+      />
+    ),
   ];
   // Two literal elements rather than one with conditional ARIA: the `meter` role's value
   // attributes are only valid ON that role, and a lint that reads roles statically has to see it.

package/src/components/NavList.module.scss

@@ -0,0 +1,66 @@
+@use '../tokens' as t;
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(1);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.group {
+  margin-block-start: t.space(3);
+}
+
+.heading {
+  @include t.focus-ring;
+  padding-block: t.space(1);
+  padding-inline: t.space(3);
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+  font-weight: t.weight(semibold);
+  cursor: default;
+}
+
+summary.heading {
+  cursor: pointer;
+}
+
+.link {
+  @include t.focus-ring;
+  @include t.touch-target;
+  @include t.transition(background, color);
+  display: flex;
+  align-items: center;
+  gap: t.space(2);
+  padding-inline: t.space(3);
+  border-radius: t.radius(md);
+  color: t.role('fg');
+  text-decoration: none;
+
+  &:hover {
+    background: t.role('surface');
+    color: t.role('fg-strong');
+  }
+
+  &[aria-current='page'] {
+    background: t.role('surface');
+    color: t.role('accent');
+    font-weight: t.weight(semibold);
+  }
+}
+
+.icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.label {
+  flex: 1;
+  min-inline-size: 0;
+}
+
+.badge {
+  flex: none;
+}

package/src/components/NavList.tsx

@@ -0,0 +1,95 @@
+// The ways around an app: links only (a command is `Menu`'s), in groups, one marked current by
+// `currentOf` — the longest href covering the page. Server-rendered and scriptless; a collapsible
+// group is a `<details>`, open when it holds the current page.
+//
+// Renders lists, not a `<nav>`: it sits in `AppShell`'s sidebar, which is already the navigation
+// landmark, and a second one inside it would announce the same region twice.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { linkTarget } from './link-target';
+import styles from './NavList.module.scss';
+import { currentOf } from './nav-list-view';
+
+export interface NavListLink {
+  /** Already translated. */
+  label: string;
+  href: string;
+  /** An `<Icon>`, decorative: the label is the name. */
+  icon?: JSX.Element | undefined;
+  /** A count or state beside the label — a `<Badge>`. */
+  badge?: JSX.Element | undefined;
+}
+
+export interface NavListGroup {
+  /** Already-translated group heading. */
+  label: string;
+  items: readonly NavListLink[];
+  /** A `<details>` the reader can fold; always open while it holds the current page. */
+  collapsible?: boolean | undefined;
+}
+
+export type NavListEntry = NavListLink | NavListGroup;
+
+export interface NavListProps {
+  items: readonly NavListEntry[];
+  /** The page's own path — `currentOf` decides which one link carries `aria-current="page"`. */
+  currentHref: string;
+  class?: string | undefined;
+}
+
+const isGroup = (entry: NavListEntry): entry is NavListGroup => 'items' in entry;
+
+export function NavList(props: NavListProps): JSX.Element {
+  const base = useId('nav-group');
+  const links = props.items.flatMap((entry) => (isGroup(entry) ? entry.items : [entry]));
+  const current = links[currentOf(links, props.currentHref)];
+
+  const link = (item: NavListLink): JSX.Element => (
+    <li>
+      <a
+        class={styles['link']}
+        href={linkTarget(item.href).href}
+        aria-current={item === current ? 'page' : undefined}
+      >
+        {item.icon === undefined ? null : <span class={styles['icon']}>{item.icon}</span>}
+        <span class={styles['label']}>{item.label}</span>
+        {item.badge === undefined ? null : <span class={styles['badge']}>{item.badge}</span>}
+      </a>
+    </li>
+  );
+
+  return (
+    <ul class={cx(styles['list'], props.class)}>
+      {props.items.map((entry, index) => {
+        if (!isGroup(entry)) return link(entry);
+        const headingId = `${base}-${index}`;
+        const list = (
+          <ul class={styles['list']} aria-labelledby={headingId}>
+            {entry.items.map(link)}
+          </ul>
+        );
+        return (
+          <li class={styles['group']}>
+            {entry.collapsible === true ? (
+              <details
+                open={current !== undefined && entry.items.includes(current) ? true : undefined}
+              >
+                <summary class={styles['heading']} id={headingId}>
+                  {entry.label}
+                </summary>
+                {list}
+              </details>
+            ) : (
+              <p class={styles['heading']} id={headingId}>
+                {entry.label}
+              </p>
+            )}
+            {entry.collapsible === true ? null : list}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/src/components/Pagination.module.scss

@@ -4,8 +4,12 @@
   display: flex;
   align-items: center;
   gap: t.space(2);
-  // Trailing edge in both writing directions.
-  justify-content: flex-end;
+}
+
+// Next holds the trailing edge in both writing directions, so it stays put whether Previous or
+// First is drawn beside it or not.
+.next {
+  margin-inline-start: auto;
 }
 
 .status {

package/src/components/Pagination.tsx

@@ -1,7 +1,7 @@
-// Cursor-first pagination — the only shape a Postgres-backed list should use.
-// Numbered mode exists for prerendered archives where the total is known.
-// One mode per use: callbacks (`onCursor` / `onPage`) for an island, or `hrefFor` for a
-// server-rendered list — anchors the browser follows, with no script on the page.
+// Cursor-first pagination — the only shape a Postgres-backed list should use; numbered mode is for
+// prerendered archives with a known total. One mode per use: callbacks for an island, or `hrefFor`
+// anchors with no script. Keyset paging has no way back, so Previous is drawn only when there is
+// one, and `firstHref`/`onFirst` restart the list.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
@@ -14,12 +14,17 @@ import styles from './Pagination.module.scss';
 type PageDirection = 'next' | 'prev';
 
 interface PaginationBaseProps {
-  /** Opaque cursor for the following page; absent disables "next". */
-  nextCursor?: string | undefined;
-  prevCursor?: string | undefined;
+  /**
+   * Opaque cursor for the following page; `null` or absent disables "next" — one state, so a
+   * framework `Page`'s `nextCursor` is handed straight through.
+   */
+  nextCursor?: string | null | undefined;
+  /** The cursor back. A keyset `Page` has none, and with none no Previous is drawn at all. */
+  prevCursor?: string | null | undefined;
   /** Already-translated; falls back to the ui.* catalog keys. */
   labelPrevious?: string | undefined;
   labelNext?: string | undefined;
+  labelFirst?: string | undefined;
   class?: string | undefined;
 }
 
@@ -31,7 +36,10 @@ export interface PaginationCallbackProps extends PaginationBaseProps {
   page?: number | undefined;
   totalPages?: number | undefined;
   onPage?: ((page: number) => void) | undefined;
+  /** Back to the start: a "First" button. Callback mode's `firstHref`. */
+  onFirst?: (() => void) | undefined;
   hrefFor?: undefined;
+  firstHref?: undefined;
 }
 
 /** Link mode: each cursor is a URL, so the pager works with scripting off. */
@@ -42,10 +50,13 @@ export interface PaginationLinkProps extends PaginationBaseProps {
    * `page` or `totalPages`.
    */
   hrefFor: (cursor: string, direction: 'next' | 'prev') => string;
+  /** The URL of the first page: a "First" anchor. Absent — already there — draws none. */
+  firstHref?: string | undefined;
   onCursor?: undefined;
   page?: undefined;
   totalPages?: undefined;
   onPage?: undefined;
+  onFirst?: undefined;
 }
 
 export type PaginationProps = PaginationCallbackProps | PaginationLinkProps;
@@ -56,14 +67,15 @@ export function Pagination(props: PaginationProps): JSX.Element {
     direction === 'prev'
       ? (props.labelPrevious ?? ui.t(UI_KEYS.previous))
       : (props.labelNext ?? ui.t(UI_KEYS.next));
+  // `null` and `undefined` are one state: a `Page` says "no next page" with `null`.
   const cursor = (direction: PageDirection): string | undefined =>
-    direction === 'prev' ? props.prevCursor : props.nextCursor;
+    (direction === 'prev' ? props.prevCursor : props.nextCursor) ?? undefined;
   // A cursor present means cursor mode, exactly as `page`'s own doc says. The inverted form —
   // "cursor mode when a number is MISSING" — silently dropped the cursor and paged by number the
   // moment a caller passed both, which is the shape a list that knows its total naturally has.
   const cursorMode = (): boolean =>
-    props.nextCursor !== undefined ||
-    props.prevCursor !== undefined ||
+    cursor('next') !== undefined ||
+    cursor('prev') !== undefined ||
     props.page === undefined ||
     props.totalPages === undefined;
 
@@ -88,11 +100,12 @@ export function Pagination(props: PaginationProps): JSX.Element {
   /**
    * One side of the pager. In link mode a side WITH a cursor is an anchor and a side without one
    * is the same disabled button callback mode shows: an anchor with nowhere to go is a dead
-   * control that still takes a tab stop, and dropping the side would move the other one between
-   * the first page and the second.
+   * control that still takes a tab stop. Next stays put whether or not Previous is drawn —
+   * `.next` pins it to the trailing edge, so it never moves between the first page and the second.
    */
   const side = (direction: PageDirection): JSX.Element => {
     const to = cursor(direction);
+    const place = direction === 'next' ? styles['next'] : undefined;
     if (props.hrefFor !== undefined && to !== undefined) {
       return (
         <Link
@@ -102,6 +115,7 @@ export function Pagination(props: PaginationProps): JSX.Element {
           tone="neutral"
           rel={direction}
           href={props.hrefFor(to, direction)}
+          class={place}
         >
           {label(direction)}
         </Link>
@@ -114,15 +128,45 @@ export function Pagination(props: PaginationProps): JSX.Element {
         tone="neutral"
         disabled={exhausted(direction)}
         onClick={props.hrefFor === undefined ? () => go(direction) : undefined}
+        class={place}
       >
         {label(direction)}
       </Button>
     );
   };
 
+  /** A keyset page has no previous cursor: a Previous for it would be disabled forever. */
+  const hasPrevious = (): boolean => !cursorMode() || cursor('prev') !== undefined;
+
+  /** Back to the start — the one way back a keyset list has. Drawn only when it is given. */
+  const first = (): JSX.Element => {
+    const text = props.labelFirst ?? ui.t(UI_KEYS.first);
+    if (props.firstHref !== undefined) {
+      return (
+        <Link
+          appearance="button"
+          variant="secondary"
+          size="sm"
+          tone="neutral"
+          href={props.firstHref}
+        >
+          {text}
+        </Link>
+      );
+    }
+    const onFirst = props.onFirst;
+    if (onFirst === undefined) return null;
+    return (
+      <Button variant="secondary" size="sm" tone="neutral" onClick={() => onFirst()}>
+        {text}
+      </Button>
+    );
+  };
+
   return (
     <nav class={cx(styles['pagination'], props.class)} aria-label={ui.t(UI_KEYS.page)}>
-      {side('prev')}
+      {first()}
+      {hasPrevious() ? side('prev') : null}
 
       {cursorMode() ? null : (
         <span class={styles['status']} aria-live="polite">

package/src/components/Popover.tsx

@@ -66,10 +66,20 @@ export function Popover(props: PopoverProps): JSX.Element {
         root = el;
       }}
     >
+      {/*
+        Getters, so the trigger is built ONCE: a snapshot of `props.open` read here made every open
+        and close rebuild the trigger, and the node the trap hands focus back to on close was the
+        one just thrown away — focus landed on <body>. Read inside the trigger's own attributes,
+        `open` updates those attributes and nothing else.
+      */}
       {props.trigger({
         id: triggerId,
-        'aria-expanded': props.open,
-        'aria-controls': props.open ? panelId : undefined,
+        get 'aria-expanded'() {
+          return props.open;
+        },
+        get 'aria-controls'() {
+          return props.open ? panelId : undefined;
+        },
       })}
       {props.open ? (
         <div