@ultimat3/ui 29.4.0 → 30.0.0

package/src/components/SearchableSelect.tsx

@@ -0,0 +1,331 @@
+// One — or many — of a long, closed list, chosen by typing, where the posted value is not the
+// label. Without script it IS a native `<select>` (`multiple`, `<optgroup>`), which posts the same
+// `name` and values; with script an effect swaps in a WAI-ARIA combobox whose text is never posted:
+// hidden inputs carry the chosen values, so a half-typed name cannot reach the server.
+
+import { finiteCount, finiteOption } from '@ultimat3/core';
+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 { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import { COMBOBOX_LIMIT } from './combobox-filter';
+import styles from './SearchableSelect.module.scss';
+import { SearchableSelectChips } from './SearchableSelectChips';
+import { SearchableSelectNative } from './SearchableSelectNative';
+import { searchableKeys } from './searchable-select-keys';
+import type { SearchableOption, SearchableView } from './searchable-select-view';
+import { checkOptions, chosenOptions, searchableView } from './searchable-select-view';
+import { thunk } from './thunk';
+import type { Size } from './variants';
+
+interface SearchableSelectBase {
+  /** The form field name every chosen value posts under. */
+  name: string;
+  /** Unique by `value`; a group's options adjacent. Chosen values must be among them. */
+  options: readonly SearchableOption[];
+  /**
+   * The caller searches: called `debounceMs` after typing stops, and hands back `options`. The
+   * list is then shown as given, never filtered again here; keep the chosen options in it.
+   */
+  onSearch?: ((query: string) => void) | undefined;
+  /** Debounce window for `onSearch`, in ms. Read once. */
+  debounceMs?: number | undefined;
+  /** Rows shown at most; past it the control says "first N of M". Default `COMBOBOX_LIMIT`. */
+  limit?: number | undefined;
+  /** Already translated: the no-script placeholder option and the empty field's hint. */
+  placeholder?: string | undefined;
+  /** Lands on whichever control is live, so `Field`'s `<label for>` names it in both modes. */
+  id?: string | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  size?: Size | undefined;
+  class?: string | undefined;
+  'aria-label'?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  'aria-invalid'?: boolean | undefined;
+}
+
+export interface SearchableSelectOneProps extends SearchableSelectBase {
+  multiple?: false | undefined;
+  /** The chosen value; absent is nothing chosen. */
+  value?: string | undefined;
+  onChange?: ((value: string) => void) | undefined;
+}
+
+export interface SearchableSelectManyProps extends SearchableSelectBase {
+  multiple: true;
+  value?: readonly string[] | undefined;
+  onChange?: ((values: readonly string[]) => void) | undefined;
+}
+
+export type SearchableSelectProps = SearchableSelectOneProps | SearchableSelectManyProps;
+
+const valuesOf = (props: SearchableSelectProps): readonly string[] => {
+  if (props.multiple === true) return props.value ?? [];
+  return props.value === undefined ? [] : [props.value];
+};
+
+export function SearchableSelect(props: SearchableSelectProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const base = props.id ?? useId('searchable-select');
+  const listId = `${base}-list`;
+  const statusId = `${base}-status`;
+  const initial = valuesOf(props);
+  const [mounted, setMounted] = rt.createSignal(false);
+  const [chosen, setChosen] = rt.createSignal<readonly string[]>(initial);
+  // `null` is "not typing": the field shows the chosen label. Free text lives only here.
+  const [query, setQuery] = rt.createSignal<string | null>(null);
+  const [open, setOpen] = rt.createSignal(false);
+  const [active, setActive] = rt.createSignal(-1);
+  let select: HTMLSelectElement | undefined;
+  let input: HTMLInputElement | undefined;
+  let list: HTMLDivElement | undefined;
+  let root: HTMLSpanElement | undefined;
+  const many = (): boolean => props.multiple === true;
+
+  const notify = debounce(
+    (text: string) => props.onSearch?.(text),
+    finiteOption('SearchableSelect', 'debounceMs', props.debounceMs ?? DEBOUNCE_DEFAULT_MS),
+  );
+
+  const view = (): SearchableView => {
+    checkOptions(props.options, chosen());
+    const limit = finiteCount('SearchableSelect', 'limit', props.limit ?? COMBOBOX_LIMIT, 0);
+    // Under `onSearch` the caller already matched: ranking again could drop what it found.
+    return props.onSearch === undefined
+      ? searchableView(props.options, query() ?? '', limit)
+      : searchableView(props.options, '', limit);
+  };
+  const picked = (): readonly SearchableOption[] => chosenOptions(props.options, chosen());
+  const text = (): string => query() ?? (many() ? '' : (picked()[0]?.label ?? ''));
+
+  const commit = (next: readonly string[]): void => {
+    setChosen(next);
+    if (props.multiple === true) props.onChange?.(next);
+    else props.onChange?.(next[0] ?? '');
+  };
+
+  const keys = searchableKeys({
+    view,
+    chosen,
+    multiple: many,
+    open,
+    active,
+    query,
+    setOpen,
+    setActive,
+    setQuery,
+    commit,
+  });
+
+  rt.createEffect(() => {
+    const value = valuesOf(props);
+    setChosen(value);
+  });
+  let held = false;
+  let form: HTMLFormElement | null = null;
+  const reset = (): void => {
+    setQuery(null);
+    setOpen(false);
+    commit(initial);
+  };
+  // A required control with nothing chosen refuses the submit; typed text never satisfies it.
+  // Written only once `required` was ever asked for: an optional control has no refusal to clear.
+  let refuses = false;
+  const validity = (): void => {
+    if (props.required !== true && !refuses) return;
+    refuses = props.required === true && chosen().length === 0;
+    input?.setCustomValidity(refuses ? ui.t(UI_KEYS.selectNone) : '');
+  };
+  /**
+   * The field's ref. A ref runs before the element is in the document — no form, no focus — so
+   * the work waits one microtask, by when the swap has inserted it.
+   */
+  const adopt = (el: HTMLInputElement): void => {
+    input = el;
+    queueMicrotask(() => {
+      // The swap: the select held focus, so the field takes it — the reader is never dropped.
+      if (held) el.focus();
+      validity();
+      form = el.form;
+      form?.addEventListener('reset', reset);
+    });
+  };
+  rt.createEffect(() => {
+    held = select !== undefined && document.activeElement === select;
+    setMounted(true);
+    rt.onCleanup(() => {
+      form?.removeEventListener('reset', reset);
+      notify.cancel();
+    });
+  });
+  rt.createEffect(() => {
+    chosen();
+    validity();
+  });
+  rt.createEffect(() => {
+    // On a touch screen the keyboard takes the lower half: the field goes to the top on open, so
+    // the list opens into the half that is still visible.
+    if (!open() || typeof matchMedia !== 'function') return;
+    if (matchMedia('(pointer: coarse)').matches) root?.scrollIntoView?.({ block: 'start' });
+  });
+  rt.createEffect(() => {
+    if (!open() || active() < 0) return;
+    // `?.()`: a DOM with no layout (jsdom, a test harness) has no `scrollIntoView`, and a missing
+    // scroll is no reason to lose the keystroke that asked for it.
+    list?.querySelector(`[id="${base}-row-${active()}"]`)?.scrollIntoView?.({ block: 'nearest' });
+  });
+
+  const status = (): string => {
+    if (!open()) return '';
+    const { rows, total } = view();
+    if (total === 0) return ui.t(UI_KEYS.noResults);
+    return rows.length < total ? ui.t(UI_KEYS.selectMore, { shown: rows.length, total }) : '';
+  };
+
+  const native = (): JSX.Element => {
+    // Refused here too: the server render never reaches `view()`, and it is the one that ships.
+    checkOptions(props.options, chosen());
+    return (
+      <SearchableSelectNative
+        ref={(el) => {
+          select = el;
+        }}
+        name={props.name}
+        options={props.options}
+        chosen={chosen()}
+        multiple={many()}
+        placeholder={props.placeholder}
+        id={props.id}
+        required={props.required}
+        disabled={props.disabled}
+        size={props.size}
+        aria-label={props['aria-label']}
+        aria-describedby={props['aria-describedby']}
+        aria-invalid={props['aria-invalid']}
+      />
+    );
+  };
+
+  const listbox = (): JSX.Element => (
+    <div
+      ref={(el: HTMLDivElement) => {
+        list = el;
+      }}
+      id={listId}
+      role="listbox"
+      class={styles['listbox']}
+      aria-label={props['aria-label']}
+      aria-multiselectable={many() ? 'true' : undefined}
+      hidden={!open()}
+    >
+      {view().rows.map((row, index) => (
+        <>
+          {row.opensGroup === undefined ? null : (
+            <div class={styles['group']} role="presentation" data-group={row.opensGroup}>
+              {row.opensGroup}
+            </div>
+          )}
+          {/* biome-ignore lint/a11y/useFocusableInteractive: focus never leaves the combobox; the active row is aria-activedescendant */}
+          {/* biome-ignore lint/a11y/useKeyWithClickEvents: the combobox's own onKeyDown is the keyboard path to every row */}
+          <div
+            id={`${base}-row-${index}`}
+            role="option"
+            tabindex={-1}
+            class={styles['option']}
+            aria-selected={chosen().includes(row.option.value) ? 'true' : 'false'}
+            aria-disabled={row.option.disabled === true ? 'true' : undefined}
+            data-active={index === active() ? 'true' : undefined}
+            data-value={row.option.value}
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={() => keys.pickRow(index)}
+          >
+            <span class={styles['optionLabel']}>{row.option.label}</span>
+            {row.option.description === undefined ? null : (
+              <span class={styles['description']}>{row.option.description}</span>
+            )}
+          </div>
+        </>
+      ))}
+    </div>
+  );
+
+  const enhanced = (): JSX.Element => (
+    <span class={styles['enhanced']}>
+      {many() && picked().length > 0 ? (
+        <SearchableSelectChips
+          chosen={picked()}
+          disabled={props.disabled}
+          onRemove={(value) => commit(chosen().filter((v) => v !== value))}
+        />
+      ) : null}
+      <span class={cx(styles['control'], styles[`size-${props.size ?? 'md'}`])}>
+        <input
+          ref={adopt}
+          class={styles['input']}
+          type="text"
+          role="combobox"
+          id={props.id}
+          value={text()}
+          placeholder={props.placeholder ?? ui.t(UI_KEYS.selectNone)}
+          disabled={props.disabled === true}
+          autocomplete="off"
+          aria-autocomplete="list"
+          aria-expanded={open() ? 'true' : 'false'}
+          aria-controls={listId}
+          aria-activedescendant={open() && active() >= 0 ? `${base}-row-${active()}` : undefined}
+          aria-required={props.required === true ? 'true' : undefined}
+          aria-label={props['aria-label']}
+          aria-describedby={[props['aria-describedby'], statusId].filter(Boolean).join(' ')}
+          aria-invalid={ariaBool(props['aria-invalid'])}
+          onInput={(event) => {
+            keys.typed(event.currentTarget.value);
+            notify(event.currentTarget.value);
+          }}
+          onKeyDown={keys.onKeyDown}
+          onClick={() => keys.toggle()}
+          onBlur={() => keys.close()}
+        />
+        {chosen().length > 0 && (many() || props.required !== true) ? (
+          <button
+            type="button"
+            class={styles['clear']}
+            disabled={props.disabled === true}
+            data-clear="true"
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={() => {
+              keys.close();
+              commit([]);
+            }}
+          >
+            {ui.t(UI_KEYS.selectClear)}
+          </button>
+        ) : null}
+      </span>
+      {chosen().map((value) => (
+        <input type="hidden" name={props.name} value={value} data-posted="true" />
+      ))}
+      {listbox()}
+      <p id={statusId} role="status" class={status() === '' ? styles['quiet'] : styles['status']}>
+        {status()}
+      </p>
+    </span>
+  );
+
+  return (
+    <span
+      ref={(el: HTMLSpanElement) => {
+        root = el;
+      }}
+      class={cx(styles['root'], props.class)}
+      data-mounted={mounted() ? 'true' : 'false'}
+    >
+      {/* A thunk: the one branch the swap re-decides, and what a test re-walks after it. */}
+      {thunk(() => (mounted() ? enhanced() : native()))}
+    </span>
+  );
+}

package/src/components/SearchableSelectChips.tsx

@@ -0,0 +1,41 @@
+// The chosen values of a many-valued SearchableSelect, as removable chips: each a label and one
+// button naming what it removes. Split from `SearchableSelect.tsx` by the 200-line target; it owns
+// no state — every removal is the parent's `onRemove`, so a chip and the posted inputs agree.
+
+import type { JSX } from 'solid-js';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './SearchableSelect.module.scss';
+import type { SearchableOption } from './searchable-select-view';
+
+export interface SearchableSelectChipsProps {
+  /** The chosen options, in the order they were chosen. */
+  chosen: readonly SearchableOption[];
+  onRemove: (value: string) => void;
+  disabled?: boolean | undefined;
+}
+
+export function SearchableSelectChips(props: SearchableSelectChipsProps): JSX.Element {
+  const ui = useUi();
+  return (
+    <ul class={styles['chips']} data-chips="true">
+      {props.chosen.map((option) => (
+        <li class={styles['chip']}>
+          <span class={styles['chipLabel']}>{option.label}</span>
+          <button
+            type="button"
+            class={styles['chipRemove']}
+            disabled={props.disabled === true}
+            aria-label={ui.t(UI_KEYS.selectRemove, { label: option.label })}
+            data-remove={option.value}
+            // Pressed with the mouse, the field keeps focus: the listbox stays where it was.
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={() => props.onRemove(option.value)}
+          >
+            <span aria-hidden="true" class={styles['cross']} />
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/SearchableSelectNative.tsx

@@ -0,0 +1,89 @@
+// A SearchableSelect with scripting off — and its first client render: the real `<select>`, with
+// `multiple` for many and `<optgroup>` for groups, posting the same `name` and values the enhanced
+// control does. Split from `SearchableSelect.tsx` by the 200-line target; it holds no state.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './SearchableSelect.module.scss';
+import type { SearchableOption } from './searchable-select-view';
+import type { Size } from './variants';
+
+export interface SearchableSelectNativeProps {
+  ref: (el: HTMLSelectElement) => void;
+  name: string;
+  options: readonly SearchableOption[];
+  chosen: readonly string[];
+  multiple: boolean;
+  placeholder: string | undefined;
+  id: string | undefined;
+  required: boolean | undefined;
+  disabled: boolean | undefined;
+  size: Size | undefined;
+  'aria-label': string | undefined;
+  'aria-describedby': string | undefined;
+  'aria-invalid': boolean | undefined;
+}
+
+export function SearchableSelectNative(props: SearchableSelectNativeProps): JSX.Element {
+  return (
+    <span class={cx(styles['native'], styles[`size-${props.size ?? 'md'}`])}>
+      <select
+        ref={props.ref}
+        class={styles['select']}
+        id={props.id}
+        name={props.name}
+        multiple={props.multiple}
+        required={props.required === true}
+        disabled={props.disabled === true}
+        aria-label={props['aria-label']}
+        aria-describedby={props['aria-describedby']}
+        aria-invalid={ariaBool(props['aria-invalid'])}
+      >
+        {/* A disabled first option: an unset single field is never a submittable value. */}
+        {props.multiple || props.placeholder === undefined ? null : (
+          <option value="" disabled selected={props.chosen.length === 0}>
+            {props.placeholder}
+          </option>
+        )}
+        {groupsOf(props.options).map((part) =>
+          part.group === undefined ? (
+            part.options.map((option) => nativeOption(option, props.chosen))
+          ) : (
+            <optgroup label={part.group}>
+              {part.options.map((option) => nativeOption(option, props.chosen))}
+            </optgroup>
+          ),
+        )}
+      </select>
+    </span>
+  );
+}
+
+function nativeOption(option: SearchableOption, chosen: readonly string[]): JSX.Element {
+  return (
+    <option
+      value={option.value}
+      disabled={option.disabled === true}
+      selected={chosen.includes(option.value)}
+    >
+      {option.label}
+    </option>
+  );
+}
+
+interface OptionRun {
+  readonly group: string | undefined;
+  readonly options: readonly SearchableOption[];
+}
+
+/** Adjacent options of one group as one run — `checkOptions` already refused a split group. */
+function groupsOf(options: readonly SearchableOption[]): readonly OptionRun[] {
+  const runs: { group: string | undefined; options: SearchableOption[] }[] = [];
+  for (const option of options) {
+    const last = runs.at(-1);
+    if (last !== undefined && last.group === option.group) last.options.push(option);
+    else runs.push({ group: option.group, options: [option] });
+  }
+  return runs;
+}

package/src/components/ShortcutSheet.module.scss

@@ -0,0 +1,33 @@
+@use '../tokens' as t;
+
+.sheet {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(2);
+  margin: 0;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: t.space(4);
+}
+
+.label {
+  color: t.role('fg');
+}
+
+.keys {
+  display: flex;
+  flex-wrap: wrap;
+  gap: t.space(2);
+  margin: 0;
+}
+
+.binding,
+.step {
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(1);
+}

package/src/components/ShortcutSheet.tsx

@@ -0,0 +1,67 @@
+// The page's keyboard legend: a `Dialog` listing every row every island registered, opened by `?`
+// — itself a row of the same table, so the sheet lists exactly the bindings that work. Hidden with
+// scripting off (a shortcut needs a listener) and never offered where nothing hovers: a phone.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { hotkeyKeycaps } from '../hotkeys-view';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import { useHotkeyRows, useHotkeys } from '../use-hotkeys';
+import { Dialog } from './Dialog';
+import { Kbd } from './Kbd';
+import styles from './ShortcutSheet.module.scss';
+
+export interface ShortcutSheetProps {
+  /** The dialog's title and the `?` row's legend. Defaults to the translated `ui.shortcuts`. */
+  title?: string | undefined;
+  class?: string | undefined;
+}
+
+/** A touch-only device has no keyboard to read the legend for. */
+const offered = (): boolean =>
+  typeof matchMedia !== 'function' || !matchMedia('(hover: none)').matches;
+
+export function ShortcutSheet(props: ShortcutSheetProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const [open, setOpen] = rt.createSignal(false);
+  const title = (): string => props.title ?? ui.t(UI_KEYS.shortcuts);
+  const table = useHotkeyRows();
+
+  useHotkeys([
+    {
+      keys: ['?'],
+      label: title(),
+      run: () => {
+        if (offered()) setOpen(!open());
+      },
+    },
+  ]);
+
+  return (
+    <Dialog open={open()} title={title()} size="sm" onClose={() => setOpen(false)}>
+      <dl class={cx(styles['sheet'], props.class)}>
+        {table().rows.map((row) => (
+          <div class={styles['row']}>
+            <dt class={styles['label']}>{row.label}</dt>
+            <dd class={styles['keys']}>
+              {row.keys.map((binding) => (
+                <span class={styles['binding']}>
+                  {hotkeyKeycaps(binding, table().mac).map((step) => (
+                    <span class={styles['step']}>
+                      {step.map((cap) => (
+                        <Kbd>{cap}</Kbd>
+                      ))}
+                    </span>
+                  ))}
+                </span>
+              ))}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </Dialog>
+  );
+}

package/src/components/Slider.module.scss

@@ -0,0 +1,50 @@
+@use '../tokens' as t;
+
+.slider {
+  display: grid;
+  gap: t.space(1);
+  min-inline-size: 0;
+}
+
+.head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: t.space(2);
+}
+
+.label {
+  color: t.role('fg-strong');
+  font-size: t.text(sm);
+  font-weight: t.weight(medium);
+}
+
+.output {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  font-variant-numeric: tabular-nums;
+}
+
+// The thumb's hit area is the touch target: the input is that tall, the track stays thin.
+.input {
+  inline-size: 100%;
+  min-block-size: t.touch(target);
+  margin: 0;
+  cursor: pointer;
+
+  &:focus-visible {
+    outline: t.stroke(thick) solid t.role('accent');
+    outline-offset: t.stroke(thick);
+  }
+
+  &:disabled {
+    @include t.disabled;
+  }
+}
+
+// The fill and thumb painted from the accent token where the engine paints a range natively.
+@supports (accent-color: auto) {
+  .input {
+    accent-color: t.role('accent');
+  }
+}

package/src/components/Slider.tsx

@@ -0,0 +1,68 @@
+// A bounded number: a native `<input type="range">` with its label and an `<output>` bound to it.
+// The platform owns the thumb, the keyboard and the touch; the paint is tokens (`accent-color`).
+// No thumb script — a kit without one sends an agent to a div. Rules: `slider-view.ts`.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { solid } from '../theme/solid-adapter';
+import styles from './Slider.module.scss';
+import { sliderNumbers } from './slider-view';
+
+export interface SliderProps {
+  name: string;
+  /** Already-translated visible label. */
+  label: string;
+  id?: string | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  step?: number | undefined;
+  value?: number | undefined;
+  /** The output's text and the control's `aria-valuetext`, in the caller's locale and unit. */
+  format?: ((value: number) => string) | undefined;
+  disabled?: boolean | undefined;
+  'aria-describedby'?: string | undefined;
+  onInput?: ((value: number) => void) | undefined;
+  class?: string | undefined;
+}
+
+export function Slider(props: SliderProps): JSX.Element {
+  const rt = solid();
+  const fallbackId = useId('slider');
+  const id = (): string => props.id ?? fallbackId;
+  const numbers = () =>
+    sliderNumbers({ min: props.min, max: props.max, step: props.step, value: props.value });
+  const [value, setValue] = rt.createSignal(numbers().value);
+  const text = (): string => (props.format === undefined ? String(value()) : props.format(value()));
+
+  return (
+    <div class={cx(styles['slider'], props.class)}>
+      <div class={styles['head']}>
+        <label class={styles['label']} for={id()}>
+          {props.label}
+        </label>
+        <output class={styles['output']} for={id()}>
+          {text()}
+        </output>
+      </div>
+      <input
+        class={styles['input']}
+        type="range"
+        id={id()}
+        name={props.name}
+        min={numbers().min}
+        max={numbers().max}
+        step={numbers().step}
+        value={numbers().value}
+        disabled={props.disabled === true}
+        aria-valuetext={props.format === undefined ? undefined : text()}
+        aria-describedby={props['aria-describedby']}
+        onInput={(event: InputEvent) => {
+          const next = Number((event.currentTarget as HTMLInputElement).value);
+          setValue(next);
+          props.onInput?.(next);
+        }}
+      />
+    </div>
+  );
+}