@ultimat3/ui 1.1.0 → 2.0.0

package/src/components/Combobox.module.scss

@@ -0,0 +1,62 @@
+@use '../tokens' as t;
+
+.combobox {
+  @include t.column(t.space(1));
+  inline-size: 100%;
+}
+
+.control {
+  @include t.control;
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(2);
+
+  &:focus-within {
+    border-color: t.role('accent');
+  }
+}
+
+.icon {
+  color: t.role('fg-muted');
+}
+
+.input {
+  flex: 1;
+  min-inline-size: 0;
+  border: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  outline: none;
+
+  // The engine's own picker button duplicates an affordance the field already has.
+  &::-webkit-calendar-picker-indicator {
+    display: none;
+  }
+}
+
+// The count is for assistive tech only; the suggestion list is the sighted answer.
+.status {
+  @include t.visually-hidden;
+}
+
+// …except "nothing matched", which a sighted user has no other way to learn.
+.empty {
+  margin: 0;
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+}
+
+.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/Combobox.tsx

@@ -0,0 +1,111 @@
+// A searchable text field with suggestions: one `<input list>` plus a `<datalist>`, which is a
+// real combobox in every engine — typing, filtering, keyboard and mobile are the platform's, and
+// the field still works with scripting off. `onFilter` is the debounced enhancement on top.
+
+import type { JSX } from 'solid-js';
+import { ariaBool, useId } from '../a11y';
+import { cx } from '../cx';
+import { DEBOUNCE_DEFAULT_MS, debounce } from '../debounce';
+import { UI_KEYS } from '../i18n-keys';
+import { iconSearch } from '../icons/glyphs/search';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import styles from './Combobox.module.scss';
+import type { ComboboxOption } from './combobox-filter';
+import { filterOptions } from './combobox-filter';
+import { Icon } from './Icon';
+import type { Size } from './variants';
+
+export interface ComboboxProps {
+  options: readonly ComboboxOption[];
+  /** The current query. Suggestions are filtered to it before they are rendered. */
+  value?: string | undefined;
+  /**
+   * Fires `debounceMs` after typing stops, and immediately when a suggestion is picked. Left out,
+   * the field is a plain filtered datalist — still correct, just not live.
+   */
+  onFilter?: ((query: string) => void) | undefined;
+  /** Debounce window in ms. Read once, when the field mounts. */
+  debounceMs?: number | undefined;
+  /** Cap on rendered suggestions. */
+  limit?: number | undefined;
+  id?: string | undefined;
+  name?: string | undefined;
+  /** Already-translated placeholder. */
+  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;
+}
+
+export function Combobox(props: ComboboxProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const base = useId('combobox');
+  const listId = `${base}-list`;
+  const statusId = `${base}-status`;
+
+  // Reads `props.onFilter` at call time, so a caller may swap the handler without rebuilding
+  // the timer — and the timer is cancelled on cleanup rather than firing into a dead tree.
+  const notify = debounce(
+    (query: string) => props.onFilter?.(query),
+    props.debounceMs ?? DEBOUNCE_DEFAULT_MS,
+  );
+  rt.createEffect(() => {
+    rt.onCleanup(() => notify.cancel());
+  });
+
+  const matches = (): readonly ComboboxOption[] =>
+    filterOptions(props.options, props.value ?? '', props.limit);
+
+  const describedBy = (): string =>
+    [props['aria-describedby'], statusId].filter((id) => id !== undefined).join(' ');
+
+  return (
+    <span class={cx(styles['combobox'], props.class)}>
+      <span class={cx(styles['control'], styles[`size-${props.size ?? 'md'}`])}>
+        <Icon glyph={iconSearch} class={styles['icon']} size={props.size ?? 'md'} />
+        <input
+          class={styles['input']}
+          type="text"
+          list={listId}
+          id={props.id}
+          name={props.name}
+          value={props.value ?? ''}
+          placeholder={props.placeholder}
+          required={props.required === true}
+          disabled={props.disabled === true}
+          // The browser's own history dropdown would cover the suggestion list.
+          autocomplete="off"
+          aria-label={props['aria-label']}
+          aria-describedby={describedBy()}
+          aria-invalid={ariaBool(props['aria-invalid'])}
+          onInput={(event) => notify(event.currentTarget.value)}
+          onChange={(event) => {
+            // Picking a suggestion is a decision, not a keystroke: it must not wait out the window.
+            notify.cancel();
+            props.onFilter?.(event.currentTarget.value);
+          }}
+        />
+        <datalist id={listId}>
+          {matches().map((option) => (
+            <option value={option.value} label={option.hint} />
+          ))}
+        </datalist>
+      </span>
+      <p
+        id={statusId}
+        role="status"
+        class={matches().length === 0 ? styles['empty'] : styles['status']}
+      >
+        {matches().length === 0
+          ? ui.t(UI_KEYS.noResults)
+          : ui.t(UI_KEYS.suggestions, { count: matches().length })}
+      </p>
+    </span>
+  );
+}

package/src/components/Dropzone.module.scss

@@ -0,0 +1,73 @@
+@use '../tokens' as t;
+
+.zone {
+  @include t.column(t.space(2), center);
+  @include t.transition(background-color, border-color);
+  position: relative;
+  border: 2px dashed t.role('line');
+  border-radius: t.radius(lg);
+  background: t.role('surface');
+  padding-block: t.space(8);
+  padding-inline: t.space(6);
+  text-align: center;
+  cursor: pointer;
+
+  // The hidden input keeps the focus, so the ring has to be drawn on the surface around it.
+  &:focus-within {
+    border-color: t.role('accent');
+    outline: 2px solid t.role('accent');
+    outline-offset: 2px;
+  }
+
+  &[data-over='true'] {
+    border-color: t.role('accent');
+    border-style: solid;
+    background: t.role('bg-soft');
+  }
+
+  &[data-disabled='true'] {
+    @include t.disabled;
+    background: t.role('bg-soft');
+    cursor: not-allowed;
+  }
+
+  &:has([aria-invalid='true']) {
+    border-color: t.role('danger');
+  }
+}
+
+.label {
+  color: t.role('fg-strong');
+  font-weight: t.weight(medium);
+}
+
+.hint {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+}
+
+// Hidden, never `display: none` — a display-none input is unfocusable, and the keyboard path
+// through this control is the input itself.
+.input {
+  @include t.visually-hidden;
+}
+
+.progress {
+  display: block;
+  inline-size: 100%;
+  block-size: 0.375rem;
+  border-radius: t.radius(pill);
+  background: t.role('bg-soft');
+  overflow: hidden;
+}
+
+// Inline-start, not `left`: the bar has to fill from the reading edge under `dir="rtl"` too.
+.bar {
+  display: block;
+  block-size: 100%;
+  inline-size: var(--file-progress, 0%);
+  border-start-start-radius: t.radius(pill);
+  border-end-start-radius: t.radius(pill);
+  background: t.role('accent');
+  @include t.transition(inline-size);
+}

package/src/components/Dropzone.tsx

@@ -0,0 +1,108 @@
+// A drop surface that is a real `<label>` around a real, visually-hidden `<input type="file">`.
+// That shape is what makes it usable without a mouse: click, Enter and Space already open the
+// picker, focus already lands somewhere, and the accessible name is the instruction the label
+// renders. A `<div onClick>` with `tabindex` would reimplement all four and get one of them wrong.
+// Dragging is the enhancement on top, never the only way in.
+
+import type { JSX } from 'solid-js';
+import { ariaBool, 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 './Dropzone.module.scss';
+import type { FileSelection } from './file-input-view';
+import { progressPercent, selectFiles } from './file-input-view';
+
+export interface DropzoneProps {
+  /** Already-translated instruction. Required — it is the control's accessible name. */
+  label: string;
+  /** Already-translated secondary line: the accepted types, the size ceiling. */
+  hint?: string | undefined;
+  id?: string | undefined;
+  name?: string | undefined;
+  /** The `accept` attribute, and the same list a dropped file is partitioned against. */
+  accept?: string | undefined;
+  multiple?: boolean | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Client-side ceiling. The server enforces its own; this only spares a doomed transfer. */
+  maxBytes?: number | undefined;
+  maxFiles?: number | undefined;
+  /** 0..1 while an upload runs. Absent renders no bar at all — never one stuck at zero. */
+  progress?: number | undefined;
+  /** Already-translated accessible name for the progress bar. */
+  progressLabel?: string | undefined;
+  class?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  'aria-invalid'?: boolean | undefined;
+  /** Every file offered, partitioned into accepted and refused-with-a-reason. */
+  onSelect: (selection: FileSelection<File>) => void;
+}
+
+export function Dropzone(props: DropzoneProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const [over, setOver] = rt.createSignal(false);
+  const fallbackId = useId('dropzone');
+  const inputId = (): string => props.id ?? fallbackId;
+  const percent = (): number => progressPercent(props.progress ?? 0);
+
+  const offer = (files: FileList | null | undefined): void => {
+    props.onSelect(selectFiles([...(files ?? [])], props));
+  };
+
+  // `dragover` must be cancelled on every tick or the browser refuses the drop and navigates to
+  // the file instead — the failure mode where the whole app disappears mid-upload.
+  const allowDrop = (event: DragEvent): void => {
+    if (props.disabled === true) return;
+    event.preventDefault();
+    setOver(true);
+  };
+
+  return (
+    <label
+      class={cx(styles['zone'], props.class)}
+      for={inputId()}
+      data-over={over() ? 'true' : undefined}
+      data-disabled={props.disabled === true ? 'true' : undefined}
+      onDragEnter={allowDrop}
+      onDragOver={allowDrop}
+      onDragLeave={() => setOver(false)}
+      onDrop={(event: DragEvent) => {
+        event.preventDefault();
+        setOver(false);
+        if (props.disabled !== true) offer(event.dataTransfer?.files);
+      }}
+    >
+      <span class={styles['label']}>{props.label}</span>
+      {props.hint === undefined ? null : <span class={styles['hint']}>{props.hint}</span>}
+      <input
+        class={styles['input']}
+        type="file"
+        id={inputId()}
+        name={props.name}
+        accept={props.accept}
+        multiple={props.multiple === true}
+        required={props.required === true}
+        disabled={props.disabled === true}
+        aria-describedby={props['aria-describedby']}
+        aria-invalid={ariaBool(props['aria-invalid'])}
+        onChange={(event) => offer(event.currentTarget.files)}
+      />
+      {props.progress === undefined ? null : (
+        <span
+          class={styles['progress']}
+          role="progressbar"
+          aria-label={props.progressLabel ?? ui.t(UI_KEYS.loading)}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={percent()}
+          style={{ '--file-progress': `${percent()}%` }}
+        >
+          <span class={styles['bar']} />
+        </span>
+      )}
+    </label>
+  );
+}

package/src/components/ErrorState.tsx

@@ -2,7 +2,7 @@
 // code, cause, fix. Identical text in the CLI, the overlay, and `--json` is the
 // whole point of the error contract — this component must not paraphrase.
 
-import { isUltimateError } from '@ultimat3/core';
+import { isUltimateError, renderCauseValue } from '@ultimat3/core';
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
@@ -39,12 +39,19 @@ export function errorParts(error: unknown): ErrorParts {
       docs: error.docs,
     };
   }
-  const message = error instanceof Error ? error.message : String(error);
+  // `props.error` is any thrown value, so `String()` ran the app's own `toString` — and this is the
+  // component that RENDERS an error, so its throw replaced the screen that was reporting one with a
+  // blank tree. Laundering it through a local `message` is exactly what `scripts/error-render.ts`
+  // says it cannot see, which is why this one shipped.
+  const message = error instanceof Error ? error.message : renderCauseValue(error);
   return {
     code: 'X_INTERNAL',
     title: 'unexpected internal framework error',
     cause: message,
-    fix: 'x logs --json | tail -50',
+    // No command can name a throw site the framework never saw typed. The one repair is at the
+    // throw itself, which is also the repo's own rule — never a bare Error — so the fix says that
+    // rather than sending the reader to a log that holds the same message this screen already has.
+    fix: 'throw an UltimateError subclass where this failed — new UltimateError({ code, cause, fix }) — so this screen renders that code and its fix instead of X_INTERNAL',
     docs: 'https://ultimate.dev/errors/X_INTERNAL',
   };
 }

package/src/components/FileInput.module.scss

@@ -0,0 +1,91 @@
+@use '../tokens' as t;
+
+.wrap {
+  @include t.control;
+  display: flex;
+  flex-direction: column;
+  gap: t.space(2);
+
+  &:focus-within {
+    border-color: t.role('accent');
+    outline: 2px solid t.role('accent');
+    outline-offset: 1px;
+  }
+
+  &[data-disabled='true'] {
+    background: t.role('bg-soft');
+    color: t.role('fg-muted');
+  }
+
+  &:has([aria-invalid='true']) {
+    border-color: t.role('danger');
+  }
+}
+
+// The wrapper owns the box; the native control is transparent inside it. Its own button is
+// styled rather than replaced — it is already focusable, keyboard-driven and localised.
+.input {
+  min-inline-size: 0;
+  border: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  outline: none;
+
+  &::file-selector-button {
+    @include t.transition(background-color, border-color);
+    margin-inline-end: t.space(3);
+    border: 1px solid t.role('line');
+    border-radius: t.radius(md);
+    background: t.role('surface');
+    color: t.role('fg-strong');
+    font: inherit;
+    font-weight: t.weight(medium);
+    padding-block: t.space(1);
+    padding-inline: t.space(3);
+    cursor: pointer;
+  }
+
+  &::file-selector-button:hover {
+    background: t.role('bg-soft');
+    border-color: t.role('accent');
+  }
+
+  &:disabled::file-selector-button {
+    @include t.disabled;
+    cursor: not-allowed;
+  }
+}
+
+.progress {
+  display: block;
+  block-size: 0.375rem;
+  border-radius: t.radius(pill);
+  background: t.role('bg-soft');
+  overflow: hidden;
+}
+
+// Inline-start, not `left`: the bar has to fill from the reading edge under `dir="rtl"` too.
+.bar {
+  display: block;
+  block-size: 100%;
+  inline-size: var(--file-progress, 0%);
+  border-start-start-radius: t.radius(pill);
+  border-end-start-radius: t.radius(pill);
+  background: t.role('accent');
+  @include t.transition(inline-size);
+}
+
+.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/FileInput.tsx

@@ -0,0 +1,82 @@
+// A file picker that keeps the platform control and dresses it. The native button and the
+// browser's own "no file chosen" summary are already localised, focusable and keyboard-driven,
+// so replacing them with a div buys nothing and costs an accessible name. What the platform has
+// no opinion about is added here: a determinate progress bar, and a partition of what it refused.
+
+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 './FileInput.module.scss';
+import type { FileSelection } from './file-input-view';
+import { progressPercent, selectFiles } from './file-input-view';
+import type { Size } from './variants';
+
+export interface FileInputProps {
+  id?: string | undefined;
+  name?: string | undefined;
+  /** The `accept` attribute, and the same list the refusal partition is computed against. */
+  accept?: string | undefined;
+  multiple?: boolean | undefined;
+  size?: Size | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Client-side ceiling. The server enforces its own; this only spares a doomed transfer. */
+  maxBytes?: number | undefined;
+  maxFiles?: number | undefined;
+  /** 0..1 while an upload runs. Absent renders no bar at all — never one stuck at zero. */
+  progress?: number | undefined;
+  /** Already-translated accessible name for the progress bar. */
+  progressLabel?: string | undefined;
+  class?: string | undefined;
+  'aria-label'?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  'aria-invalid'?: boolean | undefined;
+  /** Every chosen file, partitioned into accepted and refused-with-a-reason. */
+  onSelect?: ((selection: FileSelection<File>) => void) | undefined;
+  onBlur?: JSX.EventHandlerUnion<HTMLInputElement, FocusEvent> | undefined;
+}
+
+export function FileInput(props: FileInputProps): JSX.Element {
+  const ui = useUi();
+  const percent = (): number => progressPercent(props.progress ?? 0);
+
+  return (
+    <span
+      class={cx(styles['wrap'], styles[`size-${props.size ?? 'md'}`], props.class)}
+      data-disabled={props.disabled === true ? 'true' : undefined}
+    >
+      <input
+        class={styles['input']}
+        type="file"
+        id={props.id}
+        name={props.name}
+        accept={props.accept}
+        multiple={props.multiple === true}
+        required={props.required === true}
+        disabled={props.disabled === true}
+        aria-label={props['aria-label']}
+        aria-describedby={props['aria-describedby']}
+        aria-invalid={ariaBool(props['aria-invalid'])}
+        onBlur={props.onBlur}
+        onChange={(event) => {
+          props.onSelect?.(selectFiles([...(event.currentTarget.files ?? [])], props));
+        }}
+      />
+      {props.progress === undefined ? null : (
+        <span
+          class={styles['progress']}
+          role="progressbar"
+          aria-label={props.progressLabel ?? ui.t(UI_KEYS.loading)}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={percent()}
+          style={{ '--file-progress': `${percent()}%` }}
+        >
+          <span class={styles['bar']} />
+        </span>
+      )}
+    </span>
+  );
+}

package/src/components/Icon.module.scss

@@ -0,0 +1,29 @@
+@use '../tokens' as t;
+
+// Lucide's stroke geometry, stated once here instead of on every generated glyph: presentation
+// attributes would repeat 1767 times and could not be themed.
+.icon {
+  display: inline-block;
+  flex: none;
+  inline-size: 1em;
+  block-size: 1em;
+  fill: none;
+  stroke: currentcolor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  vertical-align: text-bottom;
+}
+
+// The box is one `em`, so sizing is a type step — no icon carries a pixel literal.
+.size-sm {
+  font-size: t.text(sm);
+}
+
+.size-md {
+  font-size: t.text(md);
+}
+
+.size-lg {
+  font-size: t.text(lg);
+}

package/src/components/Icon.tsx

@@ -0,0 +1,72 @@
+// Inline SVG from one Lucide glyph. Decorative by default (`aria-hidden`); a `label`
+// promotes it to `role="img"` with a name. Paint is `currentColor` and the box is one
+// `em`, so an icon takes the tone and the type step of whatever it sits inside.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Icon.module.scss';
+import type { IconElement, IconGlyph } from './icon-glyph';
+import { iconElements } from './icon-glyph';
+import type { Size } from './variants';
+
+/** Every Lucide glyph is drawn on this grid; the box is sized in CSS, never here. */
+const VIEW_BOX = '0 0 24 24';
+
+export interface IconProps {
+  /** One glyph module: `import { iconSearch } from '@ultimat3/ui/icons/search'`. */
+  glyph: IconGlyph;
+  /**
+   * Already-translated accessible name. Omitted means decorative, and a decorative icon is hidden
+   * from assistive tech rather than read as a nameless image.
+   */
+  label?: string | undefined;
+  size?: Size | undefined;
+  class?: string | undefined;
+}
+
+export function Icon(props: IconProps): JSX.Element {
+  return (
+    <svg
+      class={cx(styles['icon'], styles[`size-${props.size ?? 'md'}`], props.class)}
+      viewBox={VIEW_BOX}
+      role={props.label === undefined ? undefined : 'img'}
+      aria-hidden={props.label === undefined ? 'true' : undefined}
+      aria-label={props.label}
+    >
+      {iconElements(props.glyph).map((element) => glyphNode(element))}
+    </svg>
+  );
+}
+
+/**
+ * One element per tag, written out. A `<Dynamic>` would need solid-js as a value import (this
+ * package only ever types against it), and a spread would put unchecked keys on an attribute sink.
+ */
+function glyphNode(element: IconElement): JSX.Element {
+  const attrs = element.attrs;
+  switch (element.tag) {
+    case 'circle':
+      return <circle cx={attrs['cx']} cy={attrs['cy']} r={attrs['r']} fill={attrs['fill']} />;
+    case 'ellipse':
+      return <ellipse cx={attrs['cx']} cy={attrs['cy']} rx={attrs['rx']} ry={attrs['ry']} />;
+    case 'line':
+      return <line x1={attrs['x1']} x2={attrs['x2']} y1={attrs['y1']} y2={attrs['y2']} />;
+    case 'path':
+      return <path d={attrs['d']} />;
+    case 'polygon':
+      return <polygon points={attrs['points']} />;
+    case 'polyline':
+      return <polyline points={attrs['points']} />;
+    case 'rect':
+      return (
+        <rect
+          x={attrs['x']}
+          y={attrs['y']}
+          width={attrs['width']}
+          height={attrs['height']}
+          rx={attrs['rx']}
+          ry={attrs['ry']}
+        />
+      );
+  }
+}