@ultimat3/ui 1.0.0

package/src/components/Spinner.tsx

@@ -0,0 +1,35 @@
+// Indeterminate progress. `role="status"` plus a translated name, because a
+// spinner with no accessible name is silence to a screen reader.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './Spinner.module.scss';
+import type { Size } from './variants';
+
+export interface SpinnerProps {
+  size?: Size | undefined;
+  /** Overrides the translated `ui.loading` default. */
+  label?: string | undefined;
+  /** Hide from assistive tech when a parent already announces the busy state. */
+  decorative?: boolean | undefined;
+  class?: string | undefined;
+}
+
+export function Spinner(props: SpinnerProps): JSX.Element {
+  const ui = useUi();
+  const className = (): string =>
+    cx(styles['spinner'], styles[`size-${props.size ?? 'md'}`], props.class);
+
+  return props.decorative === true ? (
+    <span aria-hidden="true" class={className()} />
+  ) : (
+    <span
+      role="status"
+      aria-live="polite"
+      aria-label={props.label ?? ui.t(UI_KEYS.loading)}
+      class={className()}
+    />
+  );
+}

package/src/components/Stack.module.scss

@@ -0,0 +1,21 @@
+@use '../tokens' as t;
+
+.stack {
+  display: flex;
+  gap: var(--stack-gap, #{t.space(4)});
+  align-items: var(--stack-align, stretch);
+  justify-content: var(--stack-justify, flex-start);
+  list-style: none;
+}
+
+.direction-row {
+  flex-direction: row;
+}
+
+.direction-column {
+  flex-direction: column;
+}
+
+.wrap {
+  flex-wrap: wrap;
+}

package/src/components/Stack.tsx

@@ -0,0 +1,49 @@
+// Flex layout primitive. Gap comes from the space scale as a custom property, so
+// there is no class per step, and `row` uses `flex-direction: row` — which the
+// browser already mirrors under `dir="rtl"`.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Stack.module.scss';
+import type { Align, SpaceStep } from './variants';
+
+export interface StackProps {
+  children: JSX.Element;
+  direction?: 'row' | 'column' | undefined;
+  gap?: SpaceStep | undefined;
+  align?: Align | undefined;
+  justify?: Align | undefined;
+  wrap?: boolean | undefined;
+  /** Renders a semantic element instead of a div. */
+  as?: 'div' | 'ul' | 'ol' | 'nav' | 'section' | 'header' | 'footer' | undefined;
+  class?: string | undefined;
+}
+
+const ALIGN: Readonly<Record<Align, string>> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+  between: 'space-between',
+};
+
+export function Stack(props: StackProps): JSX.Element {
+  const Tag = props.as ?? 'div';
+  return (
+    <Tag
+      class={cx(
+        styles['stack'],
+        styles[`direction-${props.direction ?? 'column'}`],
+        props.wrap === true && styles['wrap'],
+        props.class,
+      )}
+      style={{
+        '--stack-gap': `var(--space-${props.gap ?? 4})`,
+        '--stack-align': ALIGN[props.align ?? 'stretch'],
+        '--stack-justify': ALIGN[props.justify ?? 'start'],
+      }}
+    >
+      {props.children}
+    </Tag>
+  );
+}

package/src/components/Switch.module.scss

@@ -0,0 +1,66 @@
+@use '../tokens' as t;
+
+.row {
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(2);
+  cursor: pointer;
+
+  &:has(:disabled) {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+}
+
+// Order swaps with `order`, so RTL still mirrors correctly.
+.label-start .text {
+  order: -1;
+}
+
+.input {
+  @include t.visually-hidden;
+}
+
+.track {
+  @include t.transition(background);
+  position: relative;
+  flex: none;
+  inline-size: 2.25rem;
+  block-size: 1.25rem;
+  border-radius: t.radius(pill);
+  background: t.role('line');
+}
+
+.knob {
+  @include t.transition(translate);
+  position: absolute;
+  inset-block-start: 0.125rem;
+  inset-inline-start: 0.125rem;
+  inline-size: 1rem;
+  block-size: 1rem;
+  border-radius: t.radius(full);
+  background: t.role('surface-raised');
+  box-shadow: t.shadow(xs);
+}
+
+.input:checked + .track {
+  background: t.role('accent');
+}
+
+// `translate` with a logical sign flip: RTL mirrors via the `dir` attribute.
+.input:checked + .track .knob {
+  translate: 1rem 0;
+}
+
+[dir='rtl'] .input:checked + .track .knob {
+  translate: -1rem 0;
+}
+
+.input:focus-visible + .track {
+  outline: 2px solid t.role('accent');
+  outline-offset: 2px;
+}
+
+.text {
+  font-size: t.text(sm);
+}

package/src/components/Switch.tsx

@@ -0,0 +1,44 @@
+// Boolean toggle with immediate effect (as opposed to Checkbox, which is part of
+// a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './Switch.module.scss';
+
+export interface SwitchProps {
+  /** Already-translated label. Required — the state alone is not a name. */
+  label: string;
+  checked?: boolean | undefined;
+  id?: string | undefined;
+  name?: string | undefined;
+  disabled?: boolean | undefined;
+  /** Put the label before the track, e.g. in a settings row. */
+  labelPosition?: 'start' | 'end' | undefined;
+  class?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  onChange?: JSX.EventHandlerUnion<HTMLInputElement, Event> | undefined;
+}
+
+export function Switch(props: SwitchProps): JSX.Element {
+  return (
+    <label class={cx(styles['row'], styles[`label-${props.labelPosition ?? 'end'}`], props.class)}>
+      <input
+        class={styles['input']}
+        type="checkbox"
+        role="switch"
+        id={props.id}
+        name={props.name}
+        checked={props.checked === true}
+        disabled={props.disabled === true}
+        aria-checked={ariaBool(props.checked === true)}
+        aria-describedby={props['aria-describedby']}
+        onChange={props.onChange}
+      />
+      <span aria-hidden="true" class={styles['track']}>
+        <span class={styles['knob']} />
+      </span>
+      <span class={styles['text']}>{props.label}</span>
+    </label>
+  );
+}

package/src/components/Table.module.scss

@@ -0,0 +1,77 @@
+@use '../tokens' as t;
+
+// Overflow is contained here, never on <body>.
+.scroller {
+  @include t.custom-scrollbar;
+  max-inline-size: 100%;
+  overflow-x: auto;
+  border: 1px solid t.role('line');
+  border-radius: t.radius(lg);
+  background: t.role('surface');
+
+  &:focus-visible {
+    outline: 2px solid t.role('accent');
+    outline-offset: -2px;
+  }
+}
+
+.table {
+  inline-size: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  font-size: t.text(sm);
+  // Cells decide their own width; the scroller handles the excess.
+  white-space: nowrap;
+
+  :global(th),
+  :global(td) {
+    @include t.padding-inline(t.space(4));
+    // Logical alignment, so numbers stay trailing in both directions.
+    text-align: start;
+    border-block-end: 1px solid t.role('line');
+    vertical-align: middle;
+  }
+
+  :global(th) {
+    color: t.role('fg-strong');
+    font-weight: t.weight(semibold);
+    background: t.role('bg-soft');
+  }
+
+  :global(tbody tr:last-child td) {
+    border-block-end: 0;
+  }
+}
+
+.caption {
+  @include t.padding-inline(t.space(4));
+  padding-block: t.space(3);
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+  text-align: start;
+  caption-side: top;
+}
+
+.srOnly {
+  @include t.visually-hidden;
+}
+
+.density-comfortable :global(th),
+.density-comfortable :global(td) {
+  padding-block: t.space(3);
+}
+
+.density-compact :global(th),
+.density-compact :global(td) {
+  padding-block: t.space(1);
+}
+
+.sticky :global(thead th) {
+  position: sticky;
+  inset-block-start: 0;
+  z-index: t.z(sticky);
+}
+
+.striped :global(tbody tr:nth-child(even) td) {
+  background: t.role('bg-soft', 0.6);
+}

package/src/components/Table.tsx

@@ -0,0 +1,42 @@
+// Presentational table. Owns two things every hand-rolled table gets wrong:
+// a sticky header, and horizontal overflow contained inside the table's own
+// scroll container so the page body never scrolls sideways.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Table.module.scss';
+
+export interface TableProps {
+  /** Already-translated caption. Required: a table needs an accessible name. */
+  caption: string;
+  children: JSX.Element;
+  /** Hide the caption visually while keeping it for assistive tech. */
+  hideCaption?: boolean | undefined;
+  stickyHeader?: boolean | undefined;
+  density?: 'comfortable' | 'compact' | undefined;
+  /** Zebra striping. Off by default — a border is usually enough. */
+  striped?: boolean | undefined;
+  class?: string | undefined;
+}
+
+export function Table(props: TableProps): JSX.Element {
+  return (
+    // tabindex makes the scroll region keyboard-reachable, which is required
+    // whenever a scrollable element has no focusable children.
+    <section class={cx(styles['scroller'], props.class)} tabindex="0" aria-label={props.caption}>
+      <table
+        class={cx(
+          styles['table'],
+          styles[`density-${props.density ?? 'comfortable'}`],
+          props.stickyHeader !== false && styles['sticky'],
+          props.striped === true && styles['striped'],
+        )}
+      >
+        <caption class={props.hideCaption === true ? styles['srOnly'] : styles['caption']}>
+          {props.caption}
+        </caption>
+        {props.children}
+      </table>
+    </section>
+  );
+}

package/src/components/Tabs.module.scss

@@ -0,0 +1,71 @@
+@use '../tokens' as t;
+
+.tabs {
+  display: flex;
+  gap: t.space(4);
+}
+
+.orientation-horizontal {
+  flex-direction: column;
+}
+
+.orientation-vertical {
+  flex-direction: row;
+
+  .list {
+    flex-direction: column;
+    border-block-end: 0;
+    border-inline-end: 1px solid t.role('line');
+  }
+
+  .tab[aria-selected='true'] {
+    box-shadow: inset -2px 0 0 0 t.role('accent');
+  }
+}
+
+.list {
+  @include t.custom-scrollbar;
+  display: flex;
+  gap: t.space(1);
+  border-block-end: 1px solid t.role('line');
+  overflow-x: auto;
+}
+
+.tab {
+  @include t.focus-ring(('accent'), 2px, -2px);
+  @include t.transition(color, box-shadow, background);
+  padding-block: t.space(2);
+  padding-inline: t.space(3);
+  border-start-start-radius: t.radius(sm);
+  border-start-end-radius: t.radius(sm);
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  font-weight: t.weight(medium);
+  white-space: nowrap;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    color: t.role('fg-strong');
+    background: t.role('bg-soft');
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  &[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');
+  }
+}
+
+.panel {
+  min-inline-size: 0;
+
+  &:focus-visible {
+    outline: 2px solid t.role('accent');
+    outline-offset: 2px;
+  }
+}

package/src/components/Tabs.tsx

@@ -0,0 +1,88 @@
+// Tablist with roving tabindex: one Tab in the page tab order, arrows move
+// between them, Home/End jump to the ends, and arrow direction follows `dir`.
+
+import type { JSX } from 'solid-js';
+import { ariaBool, createRovingTabindex, useId } from '../a11y';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import styles from './Tabs.module.scss';
+
+export interface TabItem {
+  id: string;
+  /** Already-translated tab label. */
+  label: string;
+  panel: JSX.Element;
+  disabled?: boolean | undefined;
+}
+
+export interface TabsProps {
+  items: readonly TabItem[];
+  /** Selected tab id. Controlled — the caller owns the state. */
+  value: string;
+  onChange: (id: string) => void;
+  /** Already-translated accessible name for the tablist. */
+  label: string;
+  orientation?: 'horizontal' | 'vertical' | undefined;
+  class?: string | undefined;
+}
+
+export function Tabs(props: TabsProps): JSX.Element {
+  const ui = useUi();
+  const base = useId('tabs');
+  let list: HTMLDivElement | undefined;
+
+  const onKeyDown = createRovingTabindex(
+    () =>
+      list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>('[role="tab"]')),
+    { orientation: props.orientation ?? 'horizontal', dir: ui.dir },
+  );
+
+  return (
+    <div
+      class={cx(
+        styles['tabs'],
+        styles[`orientation-${props.orientation ?? 'horizontal'}`],
+        props.class,
+      )}
+    >
+      <div
+        ref={(el: HTMLDivElement) => {
+          list = el;
+        }}
+        class={styles['list']}
+        role="tablist"
+        aria-label={props.label}
+        aria-orientation={props.orientation ?? 'horizontal'}
+        onKeyDown={onKeyDown}
+      >
+        {props.items.map((item) => (
+          <button
+            type="button"
+            role="tab"
+            id={`${base}-tab-${item.id}`}
+            class={styles['tab']}
+            aria-selected={ariaBool(props.value === item.id)}
+            aria-controls={`${base}-panel-${item.id}`}
+            tabindex={props.value === item.id ? 0 : -1}
+            disabled={item.disabled === true}
+            onClick={() => props.onChange(item.id)}
+          >
+            {item.label}
+          </button>
+        ))}
+      </div>
+      {props.items.map((item) => (
+        <div
+          role="tabpanel"
+          id={`${base}-panel-${item.id}`}
+          class={styles['panel']}
+          aria-labelledby={`${base}-tab-${item.id}`}
+          tabindex={0}
+          hidden={props.value !== item.id}
+        >
+          {item.panel}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/Text.module.scss

@@ -0,0 +1,37 @@
+@use '../tokens' as t;
+
+.text {
+  // Unset size and weight inherit, so <Text> is transparent inside a heading,
+  // a caption, or a control that already set the scale.
+  font-size: var(--text-scale, inherit);
+  font-weight: var(--text-strength, inherit);
+  line-height: t.leading(normal);
+}
+
+.tone-default {
+  color: t.role('fg');
+}
+
+.tone-muted {
+  color: t.role('fg-muted');
+}
+
+.tone-accent {
+  color: t.role('accent');
+}
+
+.tone-success {
+  color: t.role('success');
+}
+
+.tone-warning {
+  color: t.role('warning');
+}
+
+.tone-danger {
+  color: t.role('danger');
+}
+
+.tone-info {
+  color: t.role('info');
+}

package/src/components/Text.tsx

@@ -0,0 +1,57 @@
+// Typography primitive. Tone is a foreground or status colour role, size and
+// weight are keys of the type scale — so body copy, captions and inline status
+// text come from one component and stay legible on both themes.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import type { fontSizeTokens, fontWeightTokens } from '../tokens/tokens';
+import styles from './Text.module.scss';
+
+/** Maps 1:1 onto the foreground and status colour roles in `_colors.scss`. */
+export const TEXT_TONES = [
+  'default',
+  'muted',
+  'accent',
+  'success',
+  'warning',
+  'danger',
+  'info',
+] as const;
+export type TextTone = (typeof TEXT_TONES)[number];
+
+/** Keyed off the token maps, so a new rung is added once, in `_typography.scss`. */
+export type TextSize = keyof typeof fontSizeTokens;
+export type TextWeight = keyof typeof fontWeightTokens;
+
+export interface TextProps {
+  children: JSX.Element;
+  tone?: TextTone | undefined;
+  size?: TextSize | undefined;
+  weight?: TextWeight | undefined;
+  /**
+   * Renders a semantic element instead of a span; `p` for flow text. `strong`
+   * and `em` carry meaning to assistive tech — `weight` and `tone` do not.
+   */
+  as?: 'span' | 'p' | 'div' | 'strong' | 'em' | undefined;
+  class?: string | undefined;
+}
+
+export function Text(props: TextProps): JSX.Element {
+  const Tag = props.as ?? 'span';
+
+  // Size and weight are set only when asked for: unset means inherit, so <Text>
+  // inside a heading or a caption does not silently reset to the body scale.
+  return (
+    <Tag
+      class={cx(styles['text'], styles[`tone-${props.tone ?? 'default'}`], props.class)}
+      style={{
+        ...(props.size === undefined ? {} : { '--text-scale': `var(--text-${props.size})` }),
+        ...(props.weight === undefined
+          ? {}
+          : { '--text-strength': `var(--weight-${props.weight})` }),
+      }}
+    >
+      {props.children}
+    </Tag>
+  );
+}

package/src/components/Textarea.module.scss

@@ -0,0 +1,15 @@
+@use '../tokens' as t;
+
+.textarea {
+  @include t.control;
+  @include t.custom-scrollbar;
+  display: block;
+  min-block-size: calc(1lh * 3);
+  resize: vertical;
+  line-height: t.leading(normal);
+}
+
+.autoGrow {
+  field-sizing: content;
+  resize: none;
+}

package/src/components/Textarea.tsx

@@ -0,0 +1,48 @@
+// Multi-line text control. `field-sizing: content` grows the box natively where
+// supported, with `rows` as the floor — no resize observer, no JS.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './Textarea.module.scss';
+
+export interface TextareaProps {
+  id?: string | undefined;
+  name?: string | undefined;
+  value?: string | undefined;
+  placeholder?: string | undefined;
+  rows?: number | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  readonly?: boolean | undefined;
+  maxlength?: number | undefined;
+  autoGrow?: boolean | undefined;
+  class?: string | undefined;
+  'aria-label'?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  'aria-invalid'?: boolean | undefined;
+  onInput?: JSX.EventHandlerUnion<HTMLTextAreaElement, InputEvent> | undefined;
+  onBlur?: JSX.EventHandlerUnion<HTMLTextAreaElement, FocusEvent> | undefined;
+}
+
+export function Textarea(props: TextareaProps): JSX.Element {
+  return (
+    <textarea
+      class={cx(styles['textarea'], props.autoGrow === true && styles['autoGrow'], props.class)}
+      id={props.id}
+      name={props.name}
+      value={props.value ?? ''}
+      placeholder={props.placeholder}
+      rows={props.rows ?? 3}
+      required={props.required === true}
+      disabled={props.disabled === true}
+      readonly={props.readonly === true}
+      maxlength={props.maxlength}
+      aria-label={props['aria-label']}
+      aria-describedby={props['aria-describedby']}
+      aria-invalid={ariaBool(props['aria-invalid'])}
+      onInput={props.onInput}
+      onBlur={props.onBlur}
+    />
+  );
+}

package/src/components/ThemeToggle.module.scss

@@ -0,0 +1,23 @@
+@use '../tokens' as t;
+
+.toggle {
+  color: t.role('fg-muted');
+}
+
+.select {
+  min-inline-size: 9rem;
+}
+
+// A pure-CSS sun/moon: a filled disc that a box-shadow crops into a crescent.
+.glyph {
+  display: block;
+  inline-size: 0.9rem;
+  block-size: 0.9rem;
+  border-radius: t.radius(full);
+  background: currentcolor;
+
+  &[data-theme-glyph='dark'] {
+    background: transparent;
+    box-shadow: inset -0.28rem -0.18rem 0 0 currentcolor;
+  }
+}