@ultimat3/ui 22.14.0 → 23.0.0

package/src/components/Pagination.tsx

@@ -1,32 +1,63 @@
 // 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.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
 import { Button } from './Button';
+import { Link } from './Link';
 import styles from './Pagination.module.scss';
 
-export interface PaginationProps {
+type PageDirection = 'next' | 'prev';
+
+interface PaginationBaseProps {
   /** Opaque cursor for the following page; absent disables "next". */
   nextCursor?: string | undefined;
   prevCursor?: string | undefined;
+  /** Already-translated; falls back to the ui.* catalog keys. */
+  labelPrevious?: string | undefined;
+  labelNext?: string | undefined;
+  class?: string | undefined;
+}
+
+/** Callback mode: the page is an island and pages itself. */
+export interface PaginationCallbackProps extends PaginationBaseProps {
+  /** Callback mode. Never beside `hrefFor` — the type refuses the pair. */
   onCursor?: ((cursor: string, direction: 'next' | 'prev') => void) | undefined;
   /** Numbered mode: 1-based page and total. Ignored when cursors are present. */
   page?: number | undefined;
   totalPages?: number | undefined;
   onPage?: ((page: number) => void) | undefined;
-  /** Already-translated; falls back to the ui.* catalog keys. */
-  labelPrevious?: string | undefined;
-  labelNext?: string | undefined;
-  class?: string | undefined;
+  hrefFor?: undefined;
 }
 
+/** Link mode: each cursor is a URL, so the pager works with scripting off. */
+export interface PaginationLinkProps extends PaginationBaseProps {
+  /**
+   * Link mode: the URL of the page a cursor names. Renders `<a rel="next|prev">` and attaches no
+   * handler, so it needs no island. Cursor paging only — never beside `onCursor`, `onPage`,
+   * `page` or `totalPages`.
+   */
+  hrefFor: (cursor: string, direction: 'next' | 'prev') => string;
+  onCursor?: undefined;
+  page?: undefined;
+  totalPages?: undefined;
+  onPage?: undefined;
+}
+
+export type PaginationProps = PaginationCallbackProps | PaginationLinkProps;
+
 export function Pagination(props: PaginationProps): JSX.Element {
   const ui = useUi();
-  const previous = (): string => props.labelPrevious ?? ui.t(UI_KEYS.previous);
-  const next = (): string => props.labelNext ?? ui.t(UI_KEYS.next);
+  const label = (direction: PageDirection): string =>
+    direction === 'prev'
+      ? (props.labelPrevious ?? ui.t(UI_KEYS.previous))
+      : (props.labelNext ?? ui.t(UI_KEYS.next));
+  const cursor = (direction: PageDirection): string | undefined =>
+    direction === 'prev' ? props.prevCursor : props.nextCursor;
   // 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.
@@ -36,23 +67,62 @@ export function Pagination(props: PaginationProps): JSX.Element {
     props.page === undefined ||
     props.totalPages === undefined;
 
-  return (
-    <nav class={cx(styles['pagination'], props.class)} aria-label={ui.t(UI_KEYS.page)}>
+  const exhausted = (direction: PageDirection): boolean => {
+    if (cursorMode()) return cursor(direction) === undefined;
+    return direction === 'prev'
+      ? (props.page ?? 1) <= 1
+      : (props.page ?? 1) >= (props.totalPages ?? 1);
+  };
+
+  const go = (direction: PageDirection): void => {
+    const to = cursor(direction);
+    if (cursorMode()) {
+      if (to !== undefined) props.onCursor?.(to, direction);
+    } else if (direction === 'prev') {
+      props.onPage?.(Math.max(1, (props.page ?? 1) - 1));
+    } else {
+      props.onPage?.(Math.min(props.totalPages ?? 1, (props.page ?? 1) + 1));
+    }
+  };
+
+  /**
+   * 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.
+   */
+  const side = (direction: PageDirection): JSX.Element => {
+    const to = cursor(direction);
+    if (props.hrefFor !== undefined && to !== undefined) {
+      return (
+        <Link
+          appearance="button"
+          variant="secondary"
+          size="sm"
+          tone="neutral"
+          rel={direction}
+          href={props.hrefFor(to, direction)}
+        >
+          {label(direction)}
+        </Link>
+      );
+    }
+    return (
       <Button
         variant="secondary"
         size="sm"
         tone="neutral"
-        disabled={cursorMode() ? props.prevCursor === undefined : (props.page ?? 1) <= 1}
-        onClick={() => {
-          if (cursorMode()) {
-            if (props.prevCursor !== undefined) props.onCursor?.(props.prevCursor, 'prev');
-          } else {
-            props.onPage?.(Math.max(1, (props.page ?? 1) - 1));
-          }
-        }}
+        disabled={exhausted(direction)}
+        onClick={props.hrefFor === undefined ? () => go(direction) : undefined}
       >
-        {previous()}
+        {label(direction)}
       </Button>
+    );
+  };
+
+  return (
+    <nav class={cx(styles['pagination'], props.class)} aria-label={ui.t(UI_KEYS.page)}>
+      {side('prev')}
 
       {cursorMode() ? null : (
         <span class={styles['status']} aria-live="polite">
@@ -60,25 +130,7 @@ export function Pagination(props: PaginationProps): JSX.Element {
         </span>
       )}
 
-      <Button
-        variant="secondary"
-        size="sm"
-        tone="neutral"
-        disabled={
-          cursorMode()
-            ? props.nextCursor === undefined
-            : (props.page ?? 1) >= (props.totalPages ?? 1)
-        }
-        onClick={() => {
-          if (cursorMode()) {
-            if (props.nextCursor !== undefined) props.onCursor?.(props.nextCursor, 'next');
-          } else {
-            props.onPage?.(Math.min(props.totalPages ?? 1, (props.page ?? 1) + 1));
-          }
-        }}
-      >
-        {next()}
-      </Button>
+      {side('next')}
     </nav>
   );
 }

package/src/components/Radio.module.scss

@@ -67,8 +67,8 @@
 }
 
 .input:focus-visible + .dot {
-  outline: 2px solid t.role('accent');
-  outline-offset: 2px;
+  outline: t.stroke(thick) solid t.role('accent');
+  outline-offset: t.stroke(thick);
 }
 
 .text {

package/src/components/Select.module.scss

@@ -30,9 +30,9 @@
   inset-inline-end: t.space(3);
   inline-size: 0.4rem;
   block-size: 0.4rem;
-  border-inline-end: 2px solid t.role('fg-muted');
-  border-block-end: 2px solid t.role('fg-muted');
-  transform: translateY(-2px) rotate(45deg);
+  border-inline-end: t.stroke(thick) solid t.role('fg-muted');
+  border-block-end: t.stroke(thick) solid t.role('fg-muted');
+  transform: translateY(t.rem(-2px)) rotate(45deg);
   pointer-events: none;
 }
 

package/src/components/Skeleton.module.scss

@@ -24,7 +24,7 @@
       t.role('bg-soft') 63%
     )
     0 0 / 200% 100%;
-  animation: ultimate-shimmer 1.4s linear infinite;
+  animation: ultimate-shimmer calc(#{t.duration(slower)} * 2) linear infinite;
 }
 
 .shape-text {

package/src/components/Spinner.module.scss

@@ -8,10 +8,10 @@
 
 .spinner {
   display: inline-block;
-  border: 2px solid t.role('line');
+  border: t.stroke(thick) solid t.role('line');
   border-block-start-color: t.role('accent');
   border-radius: t.radius(full);
-  animation: ultimate-spin 700ms linear infinite;
+  animation: ultimate-spin t.duration(slower) linear infinite;
   // Reduced motion is handled globally in reset.scss; the ring still reads as
   // a distinct shape when the animation is neutralised.
 }
@@ -29,5 +29,5 @@
 .size-lg {
   inline-size: 2rem;
   block-size: 2rem;
-  border-width: 3px;
+  border-width: t.stroke(heavy);
 }

package/src/components/Switch.module.scss

@@ -57,8 +57,8 @@
 }
 
 .input:focus-visible + .track {
-  outline: 2px solid t.role('accent');
-  outline-offset: 2px;
+  outline: t.stroke(thick) solid t.role('accent');
+  outline-offset: t.stroke(thick);
 }
 
 .text {

package/src/components/Table.module.scss

@@ -10,8 +10,8 @@
   background: t.role('surface');
 
   &:focus-visible {
-    outline: 2px solid t.role('accent');
-    outline-offset: -2px;
+    outline: t.stroke(thick) solid t.role('accent');
+    outline-offset: calc(-1 * #{t.stroke(thick)});
   }
 }
 

package/src/components/Tabs.module.scss

@@ -19,7 +19,7 @@
   }
 
   .tab[aria-selected='true'] {
-    box-shadow: inset -2px 0 0 0 t.role('accent');
+    box-shadow: inset calc(-1 * #{t.stroke(thick)}) 0 0 0 t.role('accent');
   }
 }
 
@@ -32,7 +32,7 @@
 }
 
 .tab {
-  @include t.focus-ring(('accent'), 2px, -2px);
+  @include t.focus-ring('accent', t.stroke(thick), calc(-1 * #{t.stroke(thick)}));
   @include t.transition(color, box-shadow, background);
   padding-block: t.space(2);
   padding-inline: t.space(3);
@@ -54,7 +54,7 @@
   &[aria-selected='true'] {
     color: t.role('accent');
     // Inset shadow instead of a border, so the tab does not shift on select.
-    box-shadow: inset 0 -2px 0 0 t.role('accent');
+    box-shadow: inset 0 calc(-1 * #{t.stroke(thick)}) 0 0 t.role('accent');
   }
 }
 
@@ -62,7 +62,7 @@
   min-inline-size: 0;
 
   &:focus-visible {
-    outline: 2px solid t.role('accent');
-    outline-offset: 2px;
+    outline: t.stroke(thick) solid t.role('accent');
+    outline-offset: t.stroke(thick);
   }
 }

package/src/components/ThemeToggle.module.scss

@@ -18,6 +18,6 @@
 
   &[data-theme-glyph='dark'] {
     background: transparent;
-    box-shadow: inset -0.28rem -0.18rem 0 0 currentcolor;
+    box-shadow: inset t.rem(-4.5px) t.rem(-3px) 0 0 currentcolor;
   }
 }

package/src/components/Toast.module.scss

@@ -38,7 +38,7 @@
   align-items: flex-start;
   gap: t.space(3);
   padding: t.space(4);
-  border-inline-start: 3px solid var(--toast-accent);
+  border-inline-start: t.stroke(heavy) solid var(--toast-accent);
   color: t.role('fg');
   pointer-events: auto;
 
@@ -56,7 +56,7 @@
 
   @starting-style {
     opacity: 0;
-    translate: 0 12px;
+    translate: 0 t.space(3);
   }
 }
 

package/src/components/Tooltip.module.scss

@@ -10,7 +10,7 @@
   position: absolute;
   z-index: t.z(tooltip);
   inset-inline-start: 50%;
-  translate: -50% 4px;
+  translate: -50% t.space(1);
   max-inline-size: 18rem;
   padding-block: t.space(1);
   padding-inline: t.space(2);

package/src/components/bar-chart-view.ts

@@ -5,6 +5,11 @@ export interface ChartPoint {
   /** The bar's name — a day, a bucket, a label. Read by `<title>` and the axis. */
   readonly key: string;
   readonly value: number;
+  /**
+   * A second series, stacked on `value` — failed on top of done. Absent or 0 draws nothing, so a
+   * one-series chart is exactly the chart it was.
+   */
+  readonly secondary?: number;
 }
 
 export interface BarRect {
@@ -24,11 +29,16 @@ export const BAR_CHART = { width: 600, top: 12, plot: 104, height: 128, gap: 3 }
 /** Quarter lines. Four is what a reader can use to judge a bar's height without a y-axis. */
 export const GRID_STEPS = [0.25, 0.5, 0.75, 1] as const;
 
-/** The busiest point, and never below 1, so an all-zero series still divides. */
+const finite = (value: number | undefined): number =>
+  value !== undefined && Number.isFinite(value) ? Math.max(0, value) : 0;
+
+/** The busiest point — its whole stack — and never below 1, so an all-zero series still divides. */
 export function maxOf(points: readonly ChartPoint[]): number {
   let max = 1;
-  for (const point of points)
-    if (Number.isFinite(point.value) && point.value > max) max = point.value;
+  for (const point of points) {
+    const total = finite(point.value) + finite(point.secondary);
+    if (total > max) max = total;
+  }
   return max;
 }
 
@@ -53,3 +63,19 @@ export function barRects(points: readonly ChartPoint[]): readonly BarRect[] {
     };
   });
 }
+
+/**
+ * The second series' rect per point, stacked on that point's primary bar; `null` where it is 0.
+ * Same scale as `barRects`, so a stack is read against the same grid lines.
+ */
+export function secondaryRects(points: readonly ChartPoint[]): readonly (BarRect | null)[] {
+  const primary = barRects(points);
+  const max = maxOf(points);
+  return points.map((point, index) => {
+    const value = finite(point.secondary);
+    const below = primary[index];
+    if (value === 0 || below === undefined) return null;
+    const height = (value / max) * BAR_CHART.plot;
+    return { x: below.x, y: below.y - height, width: below.width, height };
+  });
+}

package/src/components/button-classes.ts

@@ -0,0 +1,25 @@
+// The classes a button's look is made of — asked by `<Button>` and by `<Link appearance="button">`,
+// so a control that submits and a control that navigates cannot drift into two looks. Keys into
+// `Button.module.scss`, never class names: the scoped name is the stylesheet's to give.
+
+import type { ButtonVariant, Size, Tone } from './variants';
+
+export interface ButtonLook {
+  variant?: ButtonVariant | undefined;
+  tone?: Tone | undefined;
+  size?: Size | undefined;
+  fullWidth?: boolean | undefined;
+}
+
+/** The classes of the element's CONTENT, which both elements wrap their label in. */
+export const BUTTON_CONTENT_KEYS = ['label', 'spinner'] as const;
+
+export function buttonClassKeys(look: ButtonLook): readonly string[] {
+  return [
+    'button',
+    `variant-${look.variant ?? 'primary'}`,
+    `tone-${look.tone ?? 'accent'}`,
+    `size-${look.size ?? 'md'}`,
+    ...(look.fullWidth === true ? ['full'] : []),
+  ];
+}

package/src/components/link-classes.ts

@@ -0,0 +1,38 @@
+// Which stylesheet a `<Link>` reads and which of its classes — the one decision `appearance`
+// makes. Pure, so it is testable with no renderer: the `.tsx` only maps the answer onto a sheet.
+
+import { type ButtonLook, buttonClassKeys } from './button-classes';
+import type { Tone } from './variants';
+
+export interface LinkLook extends Omit<ButtonLook, 'tone'> {
+  appearance?: 'link' | 'button' | undefined;
+  underline?: 'always' | 'hover' | 'none' | undefined;
+  /** A text link's own two tones, or — as a button — any `Tone`. */
+  tone?: Tone | 'inherit' | undefined;
+}
+
+export interface LinkClasses {
+  /** `button` is `Button.module.scss`: one set of button styles, whichever element wears them. */
+  readonly sheet: 'link' | 'button';
+  readonly keys: readonly string[];
+}
+
+export function linkClasses(look: LinkLook): LinkClasses {
+  if (look.appearance === 'button') {
+    return {
+      sheet: 'button',
+      // `inherit` is a text link's tone and no button has it; the type refuses the pairing, and a
+      // caller that got past the type gets the default tone rather than a class nothing declares.
+      keys: buttonClassKeys({
+        variant: look.variant,
+        tone: look.tone === 'inherit' ? undefined : look.tone,
+        size: look.size,
+        fullWidth: look.fullWidth,
+      }),
+    };
+  }
+  return {
+    sheet: 'link',
+    keys: ['link', `underline-${look.underline ?? 'hover'}`, `tone-${look.tone ?? 'accent'}`],
+  };
+}

package/src/components/link-target.ts

@@ -21,3 +21,16 @@ export function linkTarget(href: string, declaredExternal?: boolean | undefined)
   if (safe === null) return { href: undefined, external: false };
   return { href: safe, external: declaredExternal === true || /^https?:\/\//.test(safe) };
 }
+
+/**
+ * The `rel` an anchor carries. A relation is ADDED to the external hardening, never traded for
+ * it — which is why `<Link>` takes the relation as a closed pair and not a free `rel` string a
+ * caller could use to write the hardening away.
+ */
+export function linkRel(
+  external: boolean,
+  relation?: 'next' | 'prev' | undefined,
+): string | undefined {
+  if (!external) return relation;
+  return relation === undefined ? 'noopener noreferrer' : `${relation} noopener noreferrer`;
+}

package/src/index.ts

@@ -89,7 +89,12 @@ export {
   settleActive,
   stepActive,
 } from './components/command-palette-view';
-export type { Column, DataTableProps } from './components/DataTable';
+export type {
+  Column,
+  DataTableCallbackProps,
+  DataTableLinkProps,
+  DataTableProps,
+} from './components/DataTable';
 export { DataTable } from './components/DataTable';
 export type { DateTimeProps } from './components/DateTime';
 export { DateTime } from './components/DateTime';
@@ -160,7 +165,7 @@ export { boxFor, reservedRatio, sourceSetsFor, srcsetFor } from './components/im
 export type { LoadMoreInput, LoadMoreState } from './components/infinite-scroll-view';
 export type { KbdProps } from './components/Kbd';
 export { Kbd } from './components/Kbd';
-export type { LinkProps } from './components/Link';
+export type { ButtonLinkProps, LinkProps, TextLinkProps } from './components/Link';
 export { Link } from './components/Link';
 export type { LocaleSwitcherProps } from './components/LocaleSwitcher';
 export { LocaleSwitcher, localeLabel } from './components/LocaleSwitcher';
@@ -176,7 +181,11 @@ export type { MoneyFormatter, MoneyInput, MoneyViewOptions } from './components/
 export { moneyText, toMoney } from './components/money-view';
 export type { PageHeaderProps } from './components/PageHeader';
 export { PageHeader } from './components/PageHeader';
-export type { PaginationProps } from './components/Pagination';
+export type {
+  PaginationCallbackProps,
+  PaginationLinkProps,
+  PaginationProps,
+} from './components/Pagination';
 export { Pagination } from './components/Pagination';
 export type { Placement, PopoverProps } from './components/Popover';
 export { Popover } from './components/Popover';
@@ -378,5 +387,6 @@ export {
   radiusTokens,
   shadowTokens,
   spaceTokens,
+  strokeTokens,
   zTokens,
 } from './tokens/tokens';

package/src/sass-probe.ts

@@ -0,0 +1,55 @@
+// TEST-ONLY. Compiles a stylesheet with the compiler an app's build uses, so a test can read what
+// Sass EMITS — a media query, a `clamp()`, the class list a mixin generates, an `@error` — instead
+// of the source it was written as. Never exported from `index.ts`, like `jsx-probe.ts`.
+
+/** The two members of Sass's API this file calls; the package itself is not a dependency of `ui`. */
+interface SassApi {
+  compileString(source: string, options: { readonly url: URL }): { readonly css: string };
+}
+
+let loading: Promise<SassApi> | undefined;
+
+/**
+ * `sass` is `@ultimat3/render`'s dependency — the package that compiles an app's sheets — and `ui`
+ * may not import `render` (tier 4, both). Resolved FROM render's directory, so a test compiles with
+ * the one compiler at the one version the lockfile pins and `ui` declares no second copy. Only a
+ * specifier is read from render; no module of it loads. Lazy, so importing this file has no effect.
+ */
+function sassCompiler(): Promise<SassApi> {
+  loading ??= import(
+    Bun.resolveSync('sass', new URL('../../render', import.meta.url).pathname)
+  ) as Promise<SassApi>;
+  return loading;
+}
+
+/** Compile `source` as though it were the file at `path`, so its relative `@use`s resolve. */
+export async function compileScss(source: string, path: string): Promise<string> {
+  const sass = await sassCompiler();
+  return sass.compileString(source, { url: new URL(`file://${path}`) }).css;
+}
+
+/** Compile a stylesheet that exists on disk. */
+export async function compileScssFile(path: string): Promise<string> {
+  return compileScss(await Bun.file(path).text(), path);
+}
+
+/**
+ * The `@error` text Sass refused `source` with, or `undefined` when it compiled. A refusal that is
+ * not Sass's own — the compiler failing to load — is rethrown: it is not an answer about `source`.
+ */
+export async function scssRefusal(source: string, path: string): Promise<string | undefined> {
+  try {
+    await compileScss(source, path);
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'sassMessage' in error) {
+      return String(error.sassMessage);
+    }
+    throw error;
+  }
+  return undefined;
+}
+
+/** Every class a compiled stylesheet declares. */
+export function declaredClasses(css: string): ReadonlySet<string> {
+  return new Set([...css.matchAll(/\.([A-Za-z][\w-]*)/g)].map((match) => match[1] as string));
+}

package/src/tokens/_index.scss

@@ -1,5 +1,5 @@
 // Single entry point for authors: `@use '../tokens' as t;` then `t.role('bg')`,
-// `t.space(4)`, `@include t.focus-ring`. Forwards maps, functions, and mixins —
+// `t.space(4)`, `t.rem(24px)`, `@include t.focus-ring`. Forwards maps, functions, and mixins —
 // emits no CSS. Global custom properties come from `theme.scss`.
 
 @forward 'breakpoints';
@@ -8,6 +8,8 @@
 @forward 'radius' hide emit;
 @forward 'shadow' hide emit, levels;
 @forward 'space' hide emit;
+@forward 'stroke' hide emit;
 @forward 'typography' hide emit;
+@forward 'units';
 @forward 'z' hide emit;
 @forward 'mixins';