@ultimat3/ui 1.0.0

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,93 @@
+// Theme control. `toggle` flips light/dark; `select` also offers "system", which
+// clears the stored choice so the OS takes over again. All strings come from the
+// catalog, and the DOM work happens in theme.ts, never here.
+
+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 {
+  browserThemeEnv,
+  clearTheme,
+  resolveTheme,
+  setTheme,
+  storedTheme,
+  type Theme,
+  type ThemeEnv,
+  toggleTheme,
+  watchOsTheme,
+} from '../theme/theme';
+import { IconButton } from './IconButton';
+import { Select } from './Select';
+import styles from './ThemeToggle.module.scss';
+
+export type ThemeChoice = Theme | 'system';
+
+export interface ThemeToggleProps {
+  mode?: 'toggle' | 'select' | undefined;
+  /** Server-render value; the effect corrects it on the client before paint. */
+  initial?: Theme | undefined;
+  /** Injectable for tests and for non-DOM hosts. */
+  env?: ThemeEnv | undefined;
+  class?: string | undefined;
+}
+
+export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const [choice, setChoice] = rt.createSignal<ThemeChoice>(props.initial ?? 'system');
+  const [resolved, setResolved] = rt.createSignal<Theme>(props.initial ?? 'light');
+
+  const env = (): ThemeEnv => props.env ?? browserThemeEnv();
+
+  const sync = (): void => {
+    const current = env();
+    setChoice(storedTheme(current) ?? 'system');
+    setResolved(resolveTheme(current));
+  };
+
+  rt.createEffect(() => {
+    if (props.env === undefined && typeof window === 'undefined') return;
+    sync();
+    const stop = watchOsTheme(env());
+    rt.onCleanup(stop);
+  });
+
+  const apply = (next: ThemeChoice): void => {
+    if (next === 'system') clearTheme(env());
+    else setTheme(next, env());
+    sync();
+  };
+
+  if (props.mode === 'select') {
+    return (
+      <Select
+        class={cx(styles['select'], props.class)}
+        aria-label={ui.t(UI_KEYS.theme)}
+        value={choice()}
+        options={[
+          { value: 'system', label: ui.t(UI_KEYS.themeSystem) },
+          { value: 'light', label: ui.t(UI_KEYS.themeLight) },
+          { value: 'dark', label: ui.t(UI_KEYS.themeDark) },
+        ]}
+        onChange={(event) => apply(event.currentTarget.value as ThemeChoice)}
+      />
+    );
+  }
+
+  return (
+    <IconButton
+      class={cx(styles['toggle'], props.class)}
+      label={resolved() === 'dark' ? ui.t(UI_KEYS.themeLight) : ui.t(UI_KEYS.themeDark)}
+      aria-pressed={resolved() === 'dark'}
+      round
+      onClick={() => {
+        toggleTheme(env());
+        sync();
+      }}
+    >
+      <span class={styles['glyph']} data-theme-glyph={resolved()} />
+    </IconButton>
+  );
+}

package/src/components/Toast.module.scss

@@ -0,0 +1,92 @@
+@use '../tokens' as t;
+
+@keyframes ultimate-toast-in {
+  from {
+    opacity: 0;
+    translate: 0 12px;
+  }
+}
+
+.region {
+  position: fixed;
+  z-index: t.z(toast);
+  padding: t.space(4);
+  pointer-events: none;
+}
+
+.placement-block-end-inline-end {
+  inset-block-end: 0;
+  inset-inline-end: 0;
+}
+
+.placement-block-start-inline-end {
+  inset-block-start: 0;
+  inset-inline-end: 0;
+}
+
+.placement-block-end-center {
+  inset-block-end: 0;
+  inset-inline: 0;
+  display: flex;
+  justify-content: center;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(2);
+  inline-size: min(24rem, calc(100vw - #{t.space(8)}));
+  list-style: none;
+}
+
+.toast {
+  @include t.surface('surface-raised', 'lg');
+  display: flex;
+  align-items: flex-start;
+  gap: t.space(3);
+  padding: t.space(4);
+  border-inline-start: 3px solid var(--toast-accent);
+  color: t.role('fg');
+  animation: ultimate-toast-in t.duration(base) t.easing(out);
+  pointer-events: auto;
+}
+
+.content {
+  flex: 1;
+  min-inline-size: 0;
+}
+
+.title {
+  color: t.role('fg-strong');
+  font-weight: t.weight(semibold);
+  font-size: t.text(sm);
+}
+
+.body {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+}
+
+.tone-neutral {
+  --toast-accent: #{t.role('line')};
+}
+
+.tone-accent {
+  --toast-accent: #{t.role('accent')};
+}
+
+.tone-success {
+  --toast-accent: #{t.role('success')};
+}
+
+.tone-warning {
+  --toast-accent: #{t.role('warning')};
+}
+
+.tone-danger {
+  --toast-accent: #{t.role('danger')};
+}
+
+.tone-info {
+  --toast-accent: #{t.role('info')};
+}

package/src/components/Toast.tsx

@@ -0,0 +1,74 @@
+// Transient notification. ToastRegion is the single live region for the app;
+// individual Toasts are its children, so announcements are not duplicated and
+// the region exists before the first message (screen readers require that).
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { IconButton } from './IconButton';
+import styles from './Toast.module.scss';
+import type { Tone } from './variants';
+
+export interface ToastRegionProps {
+  children: JSX.Element;
+  /** Already-translated landmark name, e.g. "Notifications". */
+  label: string;
+  placement?: 'block-end-inline-end' | 'block-start-inline-end' | 'block-end-center' | undefined;
+  class?: string | undefined;
+}
+
+export function ToastRegion(props: ToastRegionProps): JSX.Element {
+  return (
+    <section
+      class={cx(
+        styles['region'],
+        styles[`placement-${props.placement ?? 'block-end-inline-end'}`],
+        props.class,
+      )}
+      aria-label={props.label}
+    >
+      <ol class={styles['list']}>{props.children}</ol>
+    </section>
+  );
+}
+
+export interface ToastProps {
+  /** Already-translated message. */
+  children: JSX.Element;
+  title?: string | undefined;
+  tone?: Tone | undefined;
+  action?: JSX.Element | undefined;
+  onDismiss?: (() => void) | undefined;
+  dismissLabel?: string | undefined;
+  class?: string | undefined;
+}
+
+export function Toast(props: ToastProps): JSX.Element {
+  const ui = useUi();
+  const tone = (): Tone => props.tone ?? 'neutral';
+  const assertive = (): boolean => tone() === 'danger';
+
+  return (
+    <li
+      class={cx(styles['toast'], styles[`tone-${tone()}`], props.class)}
+      role={assertive() ? 'alert' : 'status'}
+      aria-live={assertive() ? 'assertive' : 'polite'}
+    >
+      <div class={styles['content']}>
+        {props.title === undefined ? null : <p class={styles['title']}>{props.title}</p>}
+        <div class={styles['body']}>{props.children}</div>
+      </div>
+      {props.action}
+      {props.onDismiss === undefined ? null : (
+        <IconButton
+          label={props.dismissLabel ?? ui.t(UI_KEYS.dismiss)}
+          size="sm"
+          onClick={() => props.onDismiss?.()}
+        >
+          <span aria-hidden="true">×</span>
+        </IconButton>
+      )}
+    </li>
+  );
+}

package/src/components/Tooltip.module.scss

@@ -0,0 +1,41 @@
+@use '../tokens' as t;
+
+.wrap {
+  position: relative;
+  display: inline-flex;
+}
+
+.bubble {
+  @include t.transition(opacity, translate);
+  position: absolute;
+  z-index: t.z(tooltip);
+  inset-inline-start: 50%;
+  translate: -50% 4px;
+  max-inline-size: 18rem;
+  padding-block: t.space(1);
+  padding-inline: t.space(2);
+  border-radius: t.radius(sm);
+  background: t.role('fg-strong');
+  color: t.role('bg');
+  font-size: t.text(xs);
+  line-height: t.leading(snug);
+  text-align: center;
+  white-space: normal;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.placement-block-start {
+  inset-block-end: calc(100% + #{t.space(1)});
+}
+
+.placement-block-end {
+  inset-block-start: calc(100% + #{t.space(1)});
+}
+
+// Hover and keyboard focus both reveal it — a hover-only tooltip is inaccessible.
+.wrap:hover .bubble,
+.wrap:focus-within .bubble {
+  translate: -50% 0;
+  opacity: 1;
+}

package/src/components/Tooltip.tsx

@@ -0,0 +1,32 @@
+// Supplementary hint, shown on hover AND on keyboard focus. CSS-only, so it
+// costs no JS; the content is wired with `aria-describedby`, never `title`,
+// because `title` is unreachable by keyboard and untranslatable by the platform.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import styles from './Tooltip.module.scss';
+
+export interface TooltipProps {
+  /** Already-translated hint text. Never the element's only accessible name. */
+  content: string;
+  children: (control: { 'aria-describedby': string }) => JSX.Element;
+  placement?: 'block-start' | 'block-end' | undefined;
+  class?: string | undefined;
+}
+
+export function Tooltip(props: TooltipProps): JSX.Element {
+  const id = useId('tooltip');
+  return (
+    <span class={cx(styles['wrap'], props.class)}>
+      {props.children({ 'aria-describedby': id })}
+      <span
+        id={id}
+        role="tooltip"
+        class={cx(styles['bubble'], styles[`placement-${props.placement ?? 'block-start'}`])}
+      >
+        {props.content}
+      </span>
+    </span>
+  );
+}

package/src/components/date-time-view.ts

@@ -0,0 +1,68 @@
+// Pure formatting core behind <DateTime>. Produces both halves the component
+// needs: the machine-readable ISO instant for `<time datetime>` and the human
+// string formatted in the injected zone + locale.
+
+import {
+  type DateTimeStyle,
+  type FormatDateTimeOptions,
+  formatDateTime,
+  type Instant,
+  instant,
+  type TimeZone,
+} from '@ultimat3/time';
+import { invalidValueError } from '../errors';
+
+/** What a component may be handed for a point in time. */
+export type TimeInput = Date | string | number | Instant;
+
+export type DateStyle = DateTimeStyle;
+
+export type DateTimeFormatter = (at: Instant, options: FormatDateTimeOptions) => string;
+
+export interface DateTimeViewOptions {
+  value: TimeInput;
+  /** Required: there is no ambient locale in this package. */
+  locale: string;
+  /** Required: a date is never formatted without an explicit IANA zone. */
+  timeZone: TimeZone;
+  dateStyle?: DateStyle | undefined;
+  timeStyle?: DateStyle | undefined;
+  /** Override for tests or a custom calendar. */
+  format?: DateTimeFormatter | undefined;
+}
+
+export interface DateTimeView {
+  /** UTC ISO-8601 — the value that goes in the `datetime` attribute. */
+  readonly dateTime: string;
+  /** Localised, zoned text — the value a human reads. */
+  readonly text: string;
+}
+
+export function toDate(value: TimeInput): Date {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw invalidValueError('DateTime', value, 'a valid Date, ISO string, or epoch millis');
+  }
+  return date;
+}
+
+export function toInstant(value: TimeInput): Instant {
+  return instant(toDate(value));
+}
+
+/** Always UTC, so the attribute is comparable across zones and machines. */
+export function toIsoInstant(value: TimeInput): string {
+  return toDate(value).toISOString();
+}
+
+export function dateTimeView(view: DateTimeViewOptions): DateTimeView {
+  const at = toInstant(view.value);
+  const format = view.format ?? formatDateTime;
+  const options: FormatDateTimeOptions = {
+    locale: view.locale,
+    zone: view.timeZone,
+    ...(view.dateStyle === undefined ? {} : { dateStyle: view.dateStyle }),
+    ...(view.timeStyle === undefined ? {} : { timeStyle: view.timeStyle }),
+  };
+  return { dateTime: at.toISOString(), text: format(at, options) };
+}

package/src/components/image-source.ts

@@ -0,0 +1,150 @@
+// Pure srcset core behind <Image>. Split out so the descriptor rules — one kind
+// per set, ascending, no duplicates — are testable without a renderer, and so a
+// malformed variant list fails where it is written instead of shipping a srcset
+// the browser silently ignores.
+
+import { invalidValueError } from '../errors';
+
+/**
+ * One rendition of an image. Exactly one of `width` (emits a `w` descriptor) or
+ * `density` (an `x` descriptor): HTML forbids mixing the two in one srcset.
+ */
+export interface ImageVariant {
+  src: string;
+  /** Intrinsic width in CSS pixels. Pairs with `sizes`. */
+  width?: number | undefined;
+  /** Device pixel ratio this rendition targets. Use when the box is fixed. */
+  density?: number | undefined;
+}
+
+/** What `priority` resolves to on the element — never decided at the call site. */
+export interface ImageLoadingHints {
+  loading: 'eager' | 'lazy';
+  fetchpriority: 'high' | 'auto';
+  decoding: 'async';
+}
+
+/** Intrinsic dimensions to inline. Both, or the browser has no ratio to reserve. */
+export interface ImageBox {
+  width: number;
+  height: number;
+}
+
+interface Candidate {
+  src: string;
+  kind: 'w' | 'x';
+  value: number;
+}
+
+/**
+ * The `srcset` attribute for a variant list, ordered ascending so the markup is
+ * byte-stable whatever order the caller built the list in. `undefined` for an
+ * empty list — the component omits the attribute rather than emitting an empty one.
+ */
+export function srcsetFor(variants: readonly ImageVariant[] | undefined): string | undefined {
+  if (variants === undefined || variants.length === 0) return undefined;
+
+  const candidates = variants.map(toCandidate);
+  if (new Set(candidates.map((candidate) => candidate.kind)).size > 1) {
+    throw invalidValueError(
+      'Image',
+      variants,
+      'a variant list of one descriptor kind — every variant with width, or every variant with density',
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    const descriptor = descriptorOf(candidate);
+    if (seen.has(descriptor)) {
+      throw invalidValueError(
+        'Image',
+        variants,
+        `a variant list with distinct descriptors — ${descriptor} appears twice`,
+      );
+    }
+    seen.add(descriptor);
+  }
+
+  return [...candidates]
+    .sort((a, b) => a.value - b.value)
+    .map((candidate) => `${candidate.src} ${descriptorOf(candidate)}`)
+    .join(', ');
+}
+
+/**
+ * `priority` is the only knob: eager + high priority for the LCP image, lazy +
+ * auto for every other one. Decoding is always async — a sync decode blocks paint.
+ */
+export function loadingHints(priority: boolean | undefined): ImageLoadingHints {
+  return priority === true
+    ? { loading: 'eager', fetchpriority: 'high', decoding: 'async' }
+    : { loading: 'lazy', fetchpriority: 'auto', decoding: 'async' };
+}
+
+/**
+ * Both dimensions or neither: one alone gives the browser no aspect ratio to
+ * reserve, which is the layout shift <Image> exists to prevent.
+ */
+export function boxFor(
+  width: number | undefined,
+  height: number | undefined,
+): ImageBox | undefined {
+  if (width === undefined && height === undefined) return undefined;
+  if (width === undefined || height === undefined) {
+    throw invalidValueError(
+      'Image',
+      { width, height },
+      'both width and height, or neither — one alone reserves no aspect ratio',
+    );
+  }
+  assertPixels(width);
+  assertPixels(height);
+  return { width, height };
+}
+
+/**
+ * A `src` with real content once whitespace is trimmed. Shared by the primary `src` prop and
+ * every variant `src`: an empty or blank one emits a broken `<img>` or a srcset entry the
+ * browser silently drops, so both paths reject it the same way instead of one staying permissive.
+ */
+export function assertNonEmptySrc(kind: string, value: unknown, src: string): string {
+  const trimmed = src.trim();
+  if (trimmed === '') {
+    throw invalidValueError(kind, value, 'a non-empty src');
+  }
+  return trimmed;
+}
+
+function toCandidate(variant: ImageVariant): Candidate {
+  const src = assertNonEmptySrc('Image', variant, variant.src);
+
+  const width = variant.width;
+  const density = variant.density;
+  if ((width === undefined) === (density === undefined)) {
+    throw invalidValueError(
+      'Image',
+      variant,
+      'a variant with exactly one of width (a w descriptor) or density (an x descriptor)',
+    );
+  }
+
+  if (width !== undefined) {
+    assertPixels(width);
+    return { src, kind: 'w', value: width };
+  }
+  if (density === undefined || !Number.isFinite(density) || density <= 0) {
+    throw invalidValueError('Image', variant, 'a positive density, such as 1, 1.5 or 2');
+  }
+  return { src, kind: 'x', value: density };
+}
+
+function descriptorOf(candidate: Candidate): string {
+  return `${candidate.value}${candidate.kind}`;
+}
+
+function assertPixels(value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw invalidValueError('Image', value, 'a positive whole number of CSS pixels');
+  }
+}

package/src/components/money-view.ts

@@ -0,0 +1,50 @@
+// Pure formatting core behind <Money>. Split out so the rule "format through the
+// injected locale, never an ambient default" is testable without a renderer.
+
+import {
+  type FormatMoneyOptions,
+  formatMoney,
+  type Money,
+  money as makeMoney,
+} from '@ultimat3/money';
+import { invalidValueError } from '../errors';
+
+/** A bare number is minor units in the context currency. */
+export type MoneyInput = Money | number;
+
+export type MoneyFormatter = (
+  amount: Money,
+  locale: string,
+  options?: FormatMoneyOptions,
+) => string;
+
+export interface MoneyViewOptions {
+  value: MoneyInput;
+  /** Required: there is no ambient locale in this package. */
+  locale: string;
+  /** Used only when `value` is a bare minor-unit number. */
+  currency: string;
+  /** Passed through to @ultimat3/money: display, accounting, grouping. */
+  options?: FormatMoneyOptions | undefined;
+  /** Override for tests, custom rounding, or a non-Intl renderer. */
+  format?: MoneyFormatter | undefined;
+}
+
+export function toMoney(value: MoneyInput, currency: string): Money {
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value)) {
+      throw invalidValueError('Money', value, 'an integer number of minor units');
+    }
+    // Delegated so the currency code is validated by the one authority on it.
+    return makeMoney(value, currency);
+  }
+  if (!Number.isInteger(value.minor)) {
+    throw invalidValueError('Money', value, 'an integer number of minor units');
+  }
+  return value;
+}
+
+export function moneyText(view: MoneyViewOptions): string {
+  const format = view.format ?? formatMoney;
+  return format(toMoney(view.value, view.currency), view.locale, view.options);
+}

package/src/components/relative-time-view.ts

@@ -0,0 +1,45 @@
+// Pure core behind <RelativeTime>. Uses Intl.RelativeTimeFormat against the
+// injected locale; the caller supplies `now` so output is deterministic in tests
+// and identical between the server render and the client hydrate.
+
+import { type TimeInput, toDate } from './date-time-view';
+
+export interface RelativeTimeOptions {
+  value: TimeInput;
+  locale: string;
+  /** Defaults to the current instant. Pass it explicitly for SSR parity. */
+  now?: TimeInput | undefined;
+  numeric?: 'always' | 'auto' | undefined;
+}
+
+interface Threshold {
+  readonly unit: Intl.RelativeTimeFormatUnit;
+  readonly ms: number;
+}
+
+const THRESHOLDS: readonly Threshold[] = [
+  { unit: 'year', ms: 365 * 24 * 60 * 60 * 1000 },
+  { unit: 'month', ms: 30 * 24 * 60 * 60 * 1000 },
+  { unit: 'week', ms: 7 * 24 * 60 * 60 * 1000 },
+  { unit: 'day', ms: 24 * 60 * 60 * 1000 },
+  { unit: 'hour', ms: 60 * 60 * 1000 },
+  { unit: 'minute', ms: 60 * 1000 },
+  { unit: 'second', ms: 1000 },
+];
+
+export function relativeTimeText(options: RelativeTimeOptions): string {
+  const target = toDate(options.value).getTime();
+  const base = options.now === undefined ? Date.now() : toDate(options.now).getTime();
+  const delta = target - base;
+  const magnitude = Math.abs(delta);
+
+  const threshold =
+    THRESHOLDS.find((candidate) => magnitude >= candidate.ms) ??
+    (THRESHOLDS[THRESHOLDS.length - 1] as Threshold);
+  const value = Math.round(delta / threshold.ms);
+
+  const formatter = new Intl.RelativeTimeFormat(options.locale, {
+    numeric: options.numeric ?? 'auto',
+  });
+  return formatter.format(magnitude < 1000 ? 0 : value, threshold.unit);
+}

package/src/components/sort-state.ts

@@ -0,0 +1,28 @@
+// Pure sort-state reducer shared by Table and DataTable. Kept out of the .tsx so
+// the ordering rules are testable without a renderer.
+
+export type SortDirection = 'asc' | 'desc';
+
+export interface SortState {
+  readonly key: string;
+  readonly direction: SortDirection;
+}
+
+/**
+ * Click cycle on a column header: unsorted -> asc -> desc -> unsorted.
+ * Clicking a different column always starts that column at `asc`.
+ */
+export function nextSortState(current: SortState | undefined, key: string): SortState | undefined {
+  if (current === undefined || current.key !== key) return { key, direction: 'asc' };
+  if (current.direction === 'asc') return { key, direction: 'desc' };
+  return undefined;
+}
+
+/** The value for `aria-sort` on a column header. */
+export function ariaSortFor(
+  current: SortState | undefined,
+  key: string,
+): 'ascending' | 'descending' | 'none' {
+  if (current === undefined || current.key !== key) return 'none';
+  return current.direction === 'asc' ? 'ascending' : 'descending';
+}

package/src/components/variants.ts

@@ -0,0 +1,17 @@
+// The shared vocabulary every component's props draw from. One size scale, one
+// tone scale — a component that needs a new rung adds it here, not locally.
+
+export const SIZES = ['sm', 'md', 'lg'] as const;
+export type Size = (typeof SIZES)[number];
+
+/** Maps 1:1 onto the status colour roles in `_colors.scss`. */
+export const TONES = ['neutral', 'accent', 'success', 'warning', 'danger', 'info'] as const;
+export type Tone = (typeof TONES)[number];
+
+export const BUTTON_VARIANTS = ['primary', 'secondary', 'ghost', 'link'] as const;
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+
+export type Align = 'start' | 'center' | 'end' | 'stretch' | 'between';
+
+/** Space token step, as used by the layout primitives. */
+export type SpaceStep = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16;