@ultimat3/ui 1.0.0

package/src/components/Pagination.module.scss

@@ -0,0 +1,15 @@
+@use '../tokens' as t;
+
+.pagination {
+  display: flex;
+  align-items: center;
+  gap: t.space(2);
+  // Trailing edge in both writing directions.
+  justify-content: flex-end;
+}
+
+.status {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  font-variant-numeric: tabular-nums;
+}

package/src/components/Pagination.tsx

@@ -0,0 +1,77 @@
+// Cursor-first pagination — the only shape a Postgres-backed list should use.
+// Numbered mode exists for prerendered archives where the total is known.
+
+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 styles from './Pagination.module.scss';
+
+export interface PaginationProps {
+  /** Opaque cursor for the following page; absent disables "next". */
+  nextCursor?: string | undefined;
+  prevCursor?: string | undefined;
+  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;
+}
+
+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 cursorMode = (): boolean => props.page === undefined || props.totalPages === undefined;
+
+  return (
+    <nav class={cx(styles['pagination'], props.class)} aria-label={ui.t(UI_KEYS.page)}>
+      <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));
+          }
+        }}
+      >
+        {previous()}
+      </Button>
+
+      {cursorMode() ? null : (
+        <span class={styles['status']} aria-live="polite">
+          {`${props.page ?? 1} / ${props.totalPages ?? 1}`}
+        </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>
+    </nav>
+  );
+}

package/src/components/Popover.module.scss

@@ -0,0 +1,59 @@
+@use '../tokens' as t;
+
+.anchor {
+  position: relative;
+  display: inline-block;
+}
+
+.panel {
+  @include t.surface('surface-raised', 'lg');
+  position: absolute;
+  z-index: t.z(popover);
+  min-inline-size: 12rem;
+  max-inline-size: min(24rem, 90vw);
+  padding: t.space(4);
+  color: t.role('fg');
+}
+
+.placement-block-end {
+  inset-block-start: calc(100% + #{t.space(2)});
+}
+
+.placement-block-start {
+  inset-block-end: calc(100% + #{t.space(2)});
+}
+
+.placement-inline-end {
+  inset-inline-start: calc(100% + #{t.space(2)});
+  inset-block-start: 0;
+}
+
+.placement-inline-start {
+  inset-inline-end: calc(100% + #{t.space(2)});
+  inset-block-start: 0;
+}
+
+.align-start {
+  inset-inline-start: 0;
+}
+
+.align-end {
+  inset-inline-end: 0;
+}
+
+.align-center {
+  inset-inline-start: 50%;
+  translate: -50% 0;
+}
+
+// Inline placements own their own inline axis; alignment must not fight them.
+.placement-inline-end,
+.placement-inline-start {
+  &.align-start,
+  &.align-center,
+  &.align-end {
+    inset-inline-start: auto;
+    inset-inline-end: auto;
+    translate: none;
+  }
+}

package/src/components/Popover.tsx

@@ -0,0 +1,76 @@
+// Non-modal anchored panel. Positioning is CSS-only (a relatively positioned
+// anchor plus logical insets), so there is no measure/reflow loop and the panel
+// flips sides automatically under `dir="rtl"`.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { solid } from '../theme/solid-adapter';
+import styles from './Popover.module.scss';
+
+export type Placement = 'block-end' | 'block-start' | 'inline-end' | 'inline-start';
+
+export interface PopoverProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The anchor. Wire its onClick to `onOpenChange` in the caller. */
+  trigger: (control: {
+    id: string;
+    'aria-expanded': boolean;
+    'aria-controls': string;
+  }) => JSX.Element;
+  children: JSX.Element;
+  /** Already-translated accessible name for the panel. */
+  label: string;
+  placement?: Placement | undefined;
+  align?: 'start' | 'center' | 'end' | undefined;
+  class?: string | undefined;
+}
+
+export function Popover(props: PopoverProps): JSX.Element {
+  const rt = solid();
+  const panelId = useId('popover');
+  const triggerId = `${panelId}-trigger`;
+  let root: HTMLDivElement | undefined;
+
+  rt.createEffect(() => {
+    if (!props.open || typeof document === 'undefined') return;
+    const onPointerDown = (event: Event): void => {
+      if (root !== undefined && !root.contains(event.target as Node)) props.onOpenChange(false);
+    };
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') props.onOpenChange(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown, true);
+    document.addEventListener('keydown', onKeyDown);
+    rt.onCleanup(() => {
+      document.removeEventListener('pointerdown', onPointerDown, true);
+      document.removeEventListener('keydown', onKeyDown);
+    });
+  });
+
+  return (
+    <div
+      class={cx(styles['anchor'], props.class)}
+      ref={(el: HTMLDivElement) => {
+        root = el;
+      }}
+    >
+      {props.trigger({ id: triggerId, 'aria-expanded': props.open, 'aria-controls': panelId })}
+      {props.open ? (
+        <div
+          id={panelId}
+          role="dialog"
+          aria-label={props.label}
+          class={cx(
+            styles['panel'],
+            styles[`placement-${props.placement ?? 'block-end'}`],
+            styles[`align-${props.align ?? 'start'}`],
+          )}
+        >
+          {props.children}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/Radio.module.scss

@@ -0,0 +1,87 @@
+@use '../tokens' as t;
+
+.group {
+  display: flex;
+  gap: t.space(3);
+  border: 0;
+}
+
+.direction-row {
+  flex-flow: row wrap;
+  align-items: flex-start;
+}
+
+.direction-column {
+  flex-direction: column;
+}
+
+.legend {
+  color: t.role('fg-strong');
+  font-size: t.text(sm);
+  font-weight: t.weight(medium);
+}
+
+.row {
+  display: inline-flex;
+  align-items: flex-start;
+  gap: t.space(2);
+  cursor: pointer;
+
+  &:has(:disabled) {
+    color: t.role('fg-muted');
+    cursor: not-allowed;
+  }
+}
+
+.input {
+  @include t.visually-hidden;
+}
+
+.dot {
+  @include t.transition(border-color, box-shadow);
+  position: relative;
+  flex: none;
+  inline-size: 1.05rem;
+  block-size: 1.05rem;
+  margin-block-start: 0.15rem;
+  border: 1px solid t.role('line');
+  border-radius: t.radius(full);
+  background: t.role('surface-raised');
+
+  &::after {
+    position: absolute;
+    inset: 0.24rem;
+    border-radius: t.radius(full);
+    background: t.role('accent');
+    transform: scale(0);
+    content: '';
+  }
+}
+
+.input:checked + .dot {
+  border-color: t.role('accent');
+
+  &::after {
+    transform: scale(1);
+  }
+}
+
+.input:focus-visible + .dot {
+  outline: 2px solid t.role('accent');
+  outline-offset: 2px;
+}
+
+.text {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1rem;
+}
+
+.label {
+  font-size: t.text(sm);
+}
+
+.description {
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+}

package/src/components/Radio.tsx

@@ -0,0 +1,64 @@
+// Radio group. Rendered as a <fieldset>/<legend> so the group has a name, and as
+// one native radio per option so arrow-key navigation is the platform's job.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import styles from './Radio.module.scss';
+
+export interface RadioOption {
+  value: string;
+  /** Already-translated. */
+  label: string;
+  description?: string | undefined;
+  disabled?: boolean | undefined;
+}
+
+export interface RadioProps {
+  /** Already-translated group label, rendered as the <legend>. */
+  legend: string;
+  name: string;
+  options: readonly RadioOption[];
+  value?: string | undefined;
+  disabled?: boolean | undefined;
+  required?: boolean | undefined;
+  direction?: 'row' | 'column' | undefined;
+  class?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  onChange?: JSX.EventHandlerUnion<HTMLInputElement, Event> | undefined;
+}
+
+export function Radio(props: RadioProps): JSX.Element {
+  const group = useId('radio');
+  return (
+    <fieldset
+      class={cx(styles['group'], styles[`direction-${props.direction ?? 'column'}`], props.class)}
+      disabled={props.disabled === true}
+      aria-describedby={props['aria-describedby']}
+    >
+      <legend class={styles['legend']}>{props.legend}</legend>
+      {props.options.map((option, index) => (
+        <label class={styles['row']} for={`${group}-${index}`}>
+          <input
+            class={styles['input']}
+            id={`${group}-${index}`}
+            type="radio"
+            name={props.name}
+            value={option.value}
+            checked={props.value === option.value}
+            disabled={option.disabled === true}
+            required={props.required === true}
+            onChange={props.onChange}
+          />
+          <span aria-hidden="true" class={styles['dot']} />
+          <span class={styles['text']}>
+            <span class={styles['label']}>{option.label}</span>
+            {option.description === undefined ? null : (
+              <span class={styles['description']}>{option.description}</span>
+            )}
+          </span>
+        </label>
+      ))}
+    </fieldset>
+  );
+}

package/src/components/RelativeTime.module.scss

@@ -0,0 +1,7 @@
+@use '../tokens' as t;
+
+.relative {
+  color: t.role('fg-muted');
+  text-decoration: none;
+  white-space: nowrap;
+}

package/src/components/RelativeTime.tsx

@@ -0,0 +1,49 @@
+// "3 minutes ago" with the absolute instant in both `datetime` and `title`, so
+// hovering (or reading the DOM) always recovers the exact time.
+
+import type { TimeZone } from '@ultimat3/time';
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import { type DateTimeFormatter, dateTimeView, type TimeInput } from './date-time-view';
+import styles from './RelativeTime.module.scss';
+import { relativeTimeText } from './relative-time-view';
+
+export interface RelativeTimeProps {
+  value: TimeInput;
+  /** Pass explicitly for SSR so server and client render the same string. */
+  now?: TimeInput | undefined;
+  locale?: string | undefined;
+  timeZone?: TimeZone | undefined;
+  numeric?: 'always' | 'auto' | undefined;
+  format?: DateTimeFormatter | undefined;
+  class?: string | undefined;
+}
+
+export function RelativeTime(props: RelativeTimeProps): JSX.Element {
+  const ui = useUi();
+  const absolute = (): { dateTime: string; text: string } =>
+    dateTimeView({
+      value: props.value,
+      locale: props.locale ?? ui.locale,
+      timeZone: props.timeZone ?? ui.timeZone,
+      dateStyle: 'medium',
+      timeStyle: 'short',
+      ...(props.format === undefined ? {} : { format: props.format }),
+    });
+
+  return (
+    <time
+      class={cx(styles['relative'], props.class)}
+      datetime={absolute().dateTime}
+      title={absolute().text}
+    >
+      {relativeTimeText({
+        value: props.value,
+        locale: props.locale ?? ui.locale,
+        ...(props.now === undefined ? {} : { now: props.now }),
+        ...(props.numeric === undefined ? {} : { numeric: props.numeric }),
+      })}
+    </time>
+  );
+}

package/src/components/Select.module.scss

@@ -0,0 +1,51 @@
+@use '../tokens' as t;
+
+.wrap {
+  @include t.control;
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+
+  &:focus-within {
+    border-color: t.role('accent');
+  }
+}
+
+.select {
+  flex: 1;
+  min-inline-size: 0;
+  // Room for the chevron on the trailing side, whichever side that is.
+  padding-inline-end: t.space(5);
+  border: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  outline: none;
+  appearance: none;
+}
+
+// A CSS chevron avoids shipping an icon font or an inline SVG per select.
+.chevron {
+  position: absolute;
+  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);
+  pointer-events: none;
+}
+
+.size-sm {
+  padding-block: t.space(1);
+  font-size: t.text(sm);
+}
+
+.size-md {
+  padding-block: t.space(2);
+}
+
+.size-lg {
+  padding-block: t.space(3);
+  font-size: t.text(lg);
+}

package/src/components/Select.tsx

@@ -0,0 +1,63 @@
+// Native <select>. Deliberately not a custom listbox: the platform control wins
+// on mobile, on keyboard, and with screen readers.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './Select.module.scss';
+import type { Size } from './variants';
+
+export interface SelectOption {
+  value: string;
+  /** Already-translated option text. */
+  label: string;
+  disabled?: boolean | undefined;
+}
+
+export interface SelectProps {
+  options: readonly SelectOption[];
+  id?: string | undefined;
+  name?: string | undefined;
+  value?: string | undefined;
+  /** Rendered as a disabled first option, so it is never a submittable value. */
+  placeholder?: string | undefined;
+  size?: Size | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  class?: string | undefined;
+  'aria-label'?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  'aria-invalid'?: boolean | undefined;
+  onChange?: JSX.EventHandlerUnion<HTMLSelectElement, Event> | undefined;
+}
+
+export function Select(props: SelectProps): JSX.Element {
+  return (
+    <span class={cx(styles['wrap'], styles[`size-${props.size ?? 'md'}`], props.class)}>
+      <select
+        class={styles['select']}
+        id={props.id}
+        name={props.name}
+        value={props.value ?? ''}
+        required={props.required === true}
+        disabled={props.disabled === true}
+        aria-label={props['aria-label']}
+        aria-describedby={props['aria-describedby']}
+        aria-invalid={ariaBool(props['aria-invalid'])}
+        onChange={props.onChange}
+      >
+        {props.placeholder === undefined ? null : (
+          <option value="" disabled>
+            {props.placeholder}
+          </option>
+        )}
+        {props.options.map((option) => (
+          <option value={option.value} disabled={option.disabled === true}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+      <span aria-hidden="true" class={styles['chevron']} />
+    </span>
+  );
+}

package/src/components/Skeleton.module.scss

@@ -0,0 +1,41 @@
+@use '../tokens' as t;
+
+@keyframes ultimate-shimmer {
+  to {
+    background-position: -200% 0;
+  }
+}
+
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(2);
+}
+
+.skeleton {
+  display: block;
+  inline-size: var(--skeleton-w, 100%);
+  block-size: var(--skeleton-h, 1em);
+  // The sweep is built from surface roles, so it is visible on both themes.
+  background: linear-gradient(
+      90deg,
+      t.role('bg-soft') 25%,
+      t.role('line') 37%,
+      t.role('bg-soft') 63%
+    )
+    0 0 / 200% 100%;
+  animation: ultimate-shimmer 1.4s linear infinite;
+}
+
+.shape-text {
+  border-radius: t.radius(sm);
+}
+
+.shape-block {
+  border-radius: t.radius(md);
+}
+
+.shape-circle {
+  border-radius: t.radius(full);
+  aspect-ratio: 1;
+}

package/src/components/Skeleton.tsx

@@ -0,0 +1,34 @@
+// Loading placeholder. Sized by the caller so the real content lands in the same
+// box — a skeleton that changes size on load is just a slower layout shift.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Skeleton.module.scss';
+
+export interface SkeletonProps {
+  /** CSS length; must match the real content's box to keep CLS at 0. */
+  width?: string | undefined;
+  height?: string | undefined;
+  shape?: 'text' | 'block' | 'circle' | undefined;
+  /** Repeat as stacked lines, e.g. a paragraph placeholder. */
+  lines?: number | undefined;
+  class?: string | undefined;
+}
+
+export function Skeleton(props: SkeletonProps): JSX.Element {
+  const one = (index: number): JSX.Element => (
+    <span
+      class={cx(styles['skeleton'], styles[`shape-${props.shape ?? 'text'}`])}
+      style={{
+        '--skeleton-w': index > 0 && props.shape !== 'circle' ? '70%' : (props.width ?? '100%'),
+        '--skeleton-h': props.height ?? '1em',
+      }}
+    />
+  );
+
+  return (
+    <span aria-hidden="true" class={cx(styles['group'], props.class)}>
+      {Array.from({ length: Math.max(1, props.lines ?? 1) }, (_unused, index) => one(index))}
+    </span>
+  );
+}

package/src/components/Spinner.module.scss

@@ -0,0 +1,33 @@
+@use '../tokens' as t;
+
+@keyframes ultimate-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.spinner {
+  display: inline-block;
+  border: 2px solid t.role('line');
+  border-block-start-color: t.role('accent');
+  border-radius: t.radius(full);
+  animation: ultimate-spin 700ms linear infinite;
+  // Reduced motion is handled globally in reset.scss; the ring still reads as
+  // a distinct shape when the animation is neutralised.
+}
+
+.size-sm {
+  inline-size: 0.875rem;
+  block-size: 0.875rem;
+}
+
+.size-md {
+  inline-size: 1.25rem;
+  block-size: 1.25rem;
+}
+
+.size-lg {
+  inline-size: 2rem;
+  block-size: 2rem;
+  border-width: 3px;
+}