@ultimat3/ui 1.0.0

package/src/components/Container.module.scss

@@ -0,0 +1,31 @@
+@use '../tokens' as t;
+
+.container {
+  --container-gutter: #{t.space(4)};
+  inline-size: min(100% - (var(--container-gutter) * 2), var(--container-max));
+  margin-inline: auto;
+}
+
+.size-prose {
+  --container-max: 68ch;
+}
+
+.size-sm {
+  --container-max: 40rem;
+}
+
+.size-md {
+  --container-max: 52rem;
+}
+
+.size-lg {
+  --container-max: 72rem;
+}
+
+.size-xl {
+  --container-max: 90rem;
+}
+
+.size-full {
+  --container-max: 100%;
+}

package/src/components/Container.tsx

@@ -0,0 +1,29 @@
+// Centred measure with a gutter. `margin-inline: auto` and `min()` mean one
+// declaration covers every viewport and both writing directions.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Container.module.scss';
+import type { SpaceStep } from './variants';
+
+export type ContainerSize = 'prose' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+export interface ContainerProps {
+  children: JSX.Element;
+  size?: ContainerSize | undefined;
+  gutter?: SpaceStep | undefined;
+  as?: 'div' | 'main' | 'section' | 'article' | 'header' | 'footer' | undefined;
+  class?: string | undefined;
+}
+
+export function Container(props: ContainerProps): JSX.Element {
+  const Tag = props.as ?? 'div';
+  return (
+    <Tag
+      class={cx(styles['container'], styles[`size-${props.size ?? 'lg'}`], props.class)}
+      style={{ '--container-gutter': `var(--space-${props.gutter ?? 4})` }}
+    >
+      {props.children}
+    </Tag>
+  );
+}

package/src/components/DataTable.module.scss

@@ -0,0 +1,33 @@
+@use '../tokens' as t;
+
+.wrap {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(3);
+}
+
+// Numbers align to the trailing edge in both writing directions.
+.numeric {
+  text-align: end;
+  font-variant-numeric: tabular-nums;
+}
+
+.sortButton {
+  @include t.focus-ring;
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(1);
+  border-radius: t.radius(sm);
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+
+  &:hover {
+    color: t.role('accent');
+  }
+}
+
+.indicator {
+  color: t.role('fg-muted');
+  font-size: 0.75em;
+}

package/src/components/DataTable.tsx

@@ -0,0 +1,149 @@
+// Data-driven table: sortable headers, cursor pagination, and the four states a
+// real list always has (loading, error, empty, data). The error state renders an
+// UltimateError with the same code/cause/fix strings the terminal prints.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './DataTable.module.scss';
+import { EmptyState } from './EmptyState';
+import { ErrorState } from './ErrorState';
+import { Pagination } from './Pagination';
+import { Skeleton } from './Skeleton';
+import { ariaSortFor, nextSortState, type SortState } from './sort-state';
+import { Table } from './Table';
+
+export interface Column<Row> {
+  /** Stable identifier; also the sort key sent to the query. */
+  key: string;
+  /** Already-translated header text. */
+  header: string;
+  cell: (row: Row) => JSX.Element;
+  sortable?: boolean | undefined;
+  /** Right-aligns in LTR and left-aligns in RTL via `text-align: end`. */
+  numeric?: boolean | undefined;
+  width?: string | undefined;
+}
+
+export interface DataTableProps<Row> {
+  caption: string;
+  columns: readonly Column<Row>[];
+  rows: readonly Row[];
+  rowKey: (row: Row) => string;
+  sort?: SortState | undefined;
+  onSortChange?: (sort: SortState | undefined) => void;
+  loading?: boolean | undefined;
+  /** An UltimateError (or anything shaped like one) from the query. */
+  error?: unknown | undefined;
+  onRetry?: (() => void) | undefined;
+  emptyTitle?: string | undefined;
+  emptyDescription?: string | undefined;
+  /** Opaque cursors from the query result; absent means no further page. */
+  nextCursor?: string | undefined;
+  prevCursor?: string | undefined;
+  onCursor?: ((cursor: string, direction: 'next' | 'prev') => void) | undefined;
+  stickyHeader?: boolean | undefined;
+  density?: 'comfortable' | 'compact' | undefined;
+  /** Placeholder row count while loading. Match the usual page size. */
+  skeletonRows?: number | undefined;
+  class?: string | undefined;
+}
+
+export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
+  const ui = useUi();
+
+  const sortLabel = (key: string): string =>
+    ariaSortFor(props.sort, key) === 'ascending'
+      ? ui.t(UI_KEYS.sortDescending)
+      : ui.t(UI_KEYS.sortAscending);
+
+  const body = (): JSX.Element => {
+    if (props.loading === true) {
+      return Array.from({ length: props.skeletonRows ?? 5 }, () => (
+        <tr>
+          {props.columns.map(() => (
+            <td>
+              <Skeleton height="1.1em" />
+            </td>
+          ))}
+        </tr>
+      ));
+    }
+    return props.rows.map((row) => (
+      <tr data-row={props.rowKey(row)}>
+        {props.columns.map((column) => (
+          <td class={column.numeric === true ? styles['numeric'] : undefined}>
+            {column.cell(row)}
+          </td>
+        ))}
+      </tr>
+    ));
+  };
+
+  if (props.error !== undefined && props.error !== null) {
+    return <ErrorState error={props.error} onRetry={props.onRetry} class={props.class} />;
+  }
+
+  if (props.loading !== true && props.rows.length === 0) {
+    return (
+      <EmptyState
+        title={props.emptyTitle}
+        description={props.emptyDescription}
+        class={props.class}
+      />
+    );
+  }
+
+  return (
+    <div class={cx(styles['wrap'], props.class)}>
+      <Table
+        caption={props.caption}
+        stickyHeader={props.stickyHeader !== false}
+        density={props.density ?? 'comfortable'}
+      >
+        <thead>
+          <tr>
+            {props.columns.map((column) => (
+              <th
+                scope="col"
+                style={column.width === undefined ? undefined : { 'inline-size': column.width }}
+                aria-sort={ariaSortFor(props.sort, column.key)}
+                class={column.numeric === true ? styles['numeric'] : undefined}
+              >
+                {column.sortable === true ? (
+                  <button
+                    type="button"
+                    class={styles['sortButton']}
+                    aria-label={`${column.header}: ${sortLabel(column.key)}`}
+                    onClick={() => props.onSortChange?.(nextSortState(props.sort, column.key))}
+                  >
+                    {column.header}
+                    <span aria-hidden="true" class={styles['indicator']}>
+                      {ariaSortFor(props.sort, column.key) === 'ascending'
+                        ? '▲'
+                        : ariaSortFor(props.sort, column.key) === 'descending'
+                          ? '▼'
+                          : '↕'}
+                    </span>
+                  </button>
+                ) : (
+                  column.header
+                )}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody aria-busy={ariaBool(props.loading === true)}>{body()}</tbody>
+      </Table>
+      {props.nextCursor === undefined && props.prevCursor === undefined ? null : (
+        <Pagination
+          nextCursor={props.nextCursor}
+          prevCursor={props.prevCursor}
+          onCursor={props.onCursor}
+        />
+      )}
+    </div>
+  );
+}

package/src/components/DateTime.module.scss

@@ -0,0 +1,9 @@
+@use '../tokens' as t;
+
+.dateTime {
+  color: inherit;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  // Underlining a <time> would imply a link; the value carries the meaning.
+  text-decoration: none;
+}

package/src/components/DateTime.tsx

@@ -0,0 +1,45 @@
+// Renders <time datetime="<ISO instant>"> with text formatted in the context
+// time zone. The attribute is always the UTC instant so crawlers, tests, and
+// other machines read the same value regardless of the viewer's zone.
+
+import type { TimeZone } from '@ultimat3/time';
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import styles from './DateTime.module.scss';
+import {
+  type DateStyle,
+  type DateTimeFormatter,
+  dateTimeView,
+  type TimeInput,
+} from './date-time-view';
+
+export interface DateTimeProps {
+  value: TimeInput;
+  /** Overrides the context zone. Use for "in the venue's local time" displays. */
+  timeZone?: TimeZone | undefined;
+  locale?: string | undefined;
+  dateStyle?: DateStyle | undefined;
+  timeStyle?: DateStyle | undefined;
+  format?: DateTimeFormatter | undefined;
+  class?: string | undefined;
+}
+
+export function DateTime(props: DateTimeProps): JSX.Element {
+  const ui = useUi();
+  const view = (): { dateTime: string; text: string } =>
+    dateTimeView({
+      value: props.value,
+      locale: props.locale ?? ui.locale,
+      timeZone: props.timeZone ?? ui.timeZone,
+      ...(props.dateStyle === undefined ? {} : { dateStyle: props.dateStyle }),
+      ...(props.timeStyle === undefined ? {} : { timeStyle: props.timeStyle }),
+      ...(props.format === undefined ? {} : { format: props.format }),
+    });
+
+  return (
+    <time class={cx(styles['dateTime'], props.class)} datetime={view().dateTime}>
+      {view().text}
+    </time>
+  );
+}

package/src/components/Dialog.module.scss

@@ -0,0 +1,83 @@
+@use '../tokens' as t;
+
+@keyframes ultimate-dialog-in {
+  from {
+    opacity: 0;
+    translate: 0 8px;
+  }
+}
+
+.dialog {
+  inline-size: min(100% - #{t.space(8)}, var(--dialog-max, 32rem));
+  max-block-size: min(88dvh, 60rem);
+  padding: 0;
+  border: 1px solid t.role('line');
+  border-radius: t.radius(lg);
+  background: t.role('surface-raised');
+  color: t.role('fg');
+  box-shadow: t.shadow(xl);
+  overflow: clip;
+
+  &[open] {
+    animation: ultimate-dialog-in t.duration(base) t.easing(out);
+  }
+
+  &::backdrop {
+    background: t.role('scrim', 0.45);
+    backdrop-filter: blur(2px);
+  }
+}
+
+.size-sm {
+  --dialog-max: 24rem;
+}
+
+.size-md {
+  --dialog-max: 32rem;
+}
+
+.size-lg {
+  --dialog-max: 48rem;
+}
+
+.size-full {
+  --dialog-max: 100rem;
+}
+
+.panel {
+  display: flex;
+  flex-direction: column;
+  max-block-size: inherit;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: t.space(3);
+  padding-block: t.space(3);
+  padding-inline: t.space(5);
+  border-block-end: 1px solid t.role('line');
+}
+
+.title {
+  flex: 1;
+  min-inline-size: 0;
+  font-size: t.text(lg);
+}
+
+.body {
+  @include t.custom-scrollbar;
+  padding: t.space(5);
+  overflow-y: auto;
+}
+
+.footer {
+  display: flex;
+  flex-wrap: wrap;
+  gap: t.space(3);
+  justify-content: flex-end;
+  padding-block: t.space(3);
+  padding-inline: t.space(5);
+  border-block-start: 1px solid t.role('line');
+  background: t.role('bg-soft');
+}

package/src/components/Dialog.tsx

@@ -0,0 +1,75 @@
+// Modal built on native <dialog>: the platform gives us the top layer, the
+// backdrop, inert background content, and Escape-to-close for free. We add the
+// labelled heading, the close affordance, and body scroll locking.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import styles from './Dialog.module.scss';
+import { IconButton } from './IconButton';
+
+export interface DialogProps {
+  open: boolean;
+  /** Already-translated title. Becomes the dialog's accessible name. */
+  title: string;
+  children: JSX.Element;
+  footer?: JSX.Element | undefined;
+  onClose: () => void;
+  size?: 'sm' | 'md' | 'lg' | 'full' | undefined;
+  /** Clicking the backdrop closes. Turn off for destructive confirmations. */
+  dismissOnBackdrop?: boolean | undefined;
+  class?: string | undefined;
+}
+
+export function Dialog(props: DialogProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const titleId = useId('dialog-title');
+  let element: HTMLDialogElement | undefined;
+
+  rt.createEffect(() => {
+    const dialog = element;
+    if (dialog === undefined) return;
+    if (props.open && !dialog.open) dialog.showModal();
+    if (!props.open && dialog.open) dialog.close();
+  });
+
+  return (
+    // The backdrop's keyboard equivalent is Esc, which <dialog> raises as `cancel`, and
+    // `onCancel` below closes on it.
+    // biome-ignore lint/a11y/useKeyWithClickEvents: Esc closes through onCancel
+    <dialog
+      ref={(el: HTMLDialogElement) => {
+        element = el;
+      }}
+      class={cx(styles['dialog'], styles[`size-${props.size ?? 'md'}`], props.class)}
+      aria-labelledby={titleId}
+      onCancel={(event) => {
+        event.preventDefault();
+        props.onClose();
+      }}
+      onClick={(event) => {
+        // A click on the backdrop lands on the <dialog> itself, never a child.
+        if (props.dismissOnBackdrop !== false && event.target === element) props.onClose();
+      }}
+    >
+      <div class={styles['panel']}>
+        <header class={styles['header']}>
+          <h2 class={styles['title']} id={titleId}>
+            {props.title}
+          </h2>
+          <IconButton label={ui.t(UI_KEYS.close)} size="sm" onClick={() => props.onClose()}>
+            <span aria-hidden="true">×</span>
+          </IconButton>
+        </header>
+        <div class={styles['body']}>{props.children}</div>
+        {props.footer === undefined ? null : (
+          <footer class={styles['footer']}>{props.footer}</footer>
+        )}
+      </div>
+    </dialog>
+  );
+}

package/src/components/Divider.module.scss

@@ -0,0 +1,39 @@
+@use '../tokens' as t;
+
+.divider {
+  border: 0;
+  background: t.role('line');
+}
+
+.horizontal {
+  inline-size: 100%;
+  block-size: 1px;
+}
+
+.vertical {
+  inline-size: 1px;
+  block-size: 100%;
+  align-self: stretch;
+}
+
+.labelled {
+  display: flex;
+  align-items: center;
+  gap: t.space(3);
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+  text-transform: uppercase;
+  letter-spacing: var(--tracking-wide);
+
+  &::before,
+  &::after {
+    flex: 1;
+    block-size: 1px;
+    background: t.role('line');
+    content: '';
+  }
+}
+
+.label {
+  @include t.truncate;
+}

package/src/components/Divider.tsx

@@ -0,0 +1,38 @@
+// A rule. Always an explicit `role="separator"` with an orientation; pass `label`
+// to render a captioned separator, which is what a settings group actually needs.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Divider.module.scss';
+
+export interface DividerProps {
+  orientation?: 'horizontal' | 'vertical' | undefined;
+  /** Visible, already-translated caption rendered inside the rule. */
+  label?: string | undefined;
+  class?: string | undefined;
+}
+
+export function Divider(props: DividerProps): JSX.Element {
+  const orientation = (): 'horizontal' | 'vertical' => props.orientation ?? 'horizontal';
+
+  return props.label === undefined ? (
+    <hr
+      aria-orientation={orientation()}
+      class={cx(styles['divider'], styles[orientation()], props.class)}
+    />
+  ) : (
+    // A captioned separator is the structural (non-focusable) flavour of the role, which
+    // ARIA does not give a value and does not put in the tab order. `<hr>` is void, so the
+    // caption has to live in a container that carries the role itself.
+    // biome-ignore lint/a11y/useSemanticElements: <hr> cannot hold the caption
+    // biome-ignore lint/a11y/useFocusableInteractive: a captioned rule is not a splitter
+    <div
+      // biome-ignore lint/a11y/useAriaPropsForRole: aria-valuenow is the splitter flavour's
+      role="separator"
+      aria-orientation={orientation()}
+      class={cx(styles['labelled'], props.class)}
+    >
+      <span class={styles['label']}>{props.label}</span>
+    </div>
+  );
+}

package/src/components/Drawer.module.scss

@@ -0,0 +1,89 @@
+@use '../tokens' as t;
+
+.drawer {
+  position: fixed;
+  max-inline-size: 100%;
+  max-block-size: 100%;
+  padding: 0;
+  border: 0;
+  background: t.role('surface-raised');
+  color: t.role('fg');
+  box-shadow: t.shadow(xl);
+
+  &::backdrop {
+    background: t.role('scrim', 0.45);
+  }
+}
+
+.side-inline-start {
+  inset-block: 0;
+  inset-inline-start: 0;
+  inset-inline-end: auto;
+  inline-size: var(--drawer-size, 22rem);
+  block-size: 100dvh;
+  border-inline-end: 1px solid t.role('line');
+}
+
+.side-inline-end {
+  inset-block: 0;
+  inset-inline-end: 0;
+  inset-inline-start: auto;
+  inline-size: var(--drawer-size, 22rem);
+  block-size: 100dvh;
+  border-inline-start: 1px solid t.role('line');
+}
+
+.side-block-start {
+  inset-inline: 0;
+  inset-block-start: 0;
+  inset-block-end: auto;
+  inline-size: 100vw;
+  block-size: var(--drawer-size, 22rem);
+  border-block-end: 1px solid t.role('line');
+}
+
+.side-block-end {
+  inset-inline: 0;
+  inset-block-end: 0;
+  inset-block-start: auto;
+  inline-size: 100vw;
+  block-size: var(--drawer-size, 22rem);
+  border-block-start: 1px solid t.role('line');
+  border-start-start-radius: t.radius(lg);
+  border-start-end-radius: t.radius(lg);
+}
+
+.panel {
+  display: flex;
+  flex-direction: column;
+  block-size: 100%;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: t.space(3);
+  padding-block: t.space(3);
+  padding-inline: t.space(4);
+  border-block-end: 1px solid t.role('line');
+}
+
+.title {
+  flex: 1;
+  min-inline-size: 0;
+  font-size: t.text(lg);
+}
+
+.body {
+  @include t.custom-scrollbar;
+  flex: 1;
+  padding: t.space(4);
+  overflow-y: auto;
+}
+
+.footer {
+  padding-block: t.space(3);
+  padding-inline: t.space(4);
+  border-block-start: 1px solid t.role('line');
+  background: t.role('bg-soft');
+}