@ultimat3/ui 1.0.0

package/src/components/IconButton.tsx

@@ -0,0 +1,53 @@
+// A button whose only content is an icon, so `label` is mandatory: it becomes
+// the accessible name and the tooltip. There is no unlabelled icon button.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './IconButton.module.scss';
+import type { ButtonVariant, Size, Tone } from './variants';
+
+export interface IconButtonProps {
+  /** Required accessible name — also used as the native tooltip. */
+  label: string;
+  children: JSX.Element;
+  variant?: ButtonVariant | undefined;
+  tone?: Tone | undefined;
+  size?: Size | undefined;
+  disabled?: boolean | undefined;
+  round?: boolean | undefined;
+  id?: string | undefined;
+  class?: string | undefined;
+  'aria-pressed'?: boolean | undefined;
+  'aria-expanded'?: boolean | undefined;
+  'aria-controls'?: string | undefined;
+  onClick?: JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent> | undefined;
+}
+
+export function IconButton(props: IconButtonProps): JSX.Element {
+  return (
+    <button
+      id={props.id}
+      type="button"
+      title={props.label}
+      aria-label={props.label}
+      aria-pressed={ariaBool(props['aria-pressed'])}
+      aria-expanded={ariaBool(props['aria-expanded'])}
+      aria-controls={props['aria-controls']}
+      disabled={props.disabled === true}
+      class={cx(
+        styles['iconButton'],
+        styles[`variant-${props.variant ?? 'ghost'}`],
+        styles[`tone-${props.tone ?? 'neutral'}`],
+        styles[`size-${props.size ?? 'md'}`],
+        props.round === true && styles['round'],
+        props.class,
+      )}
+      onClick={props.onClick}
+    >
+      <span aria-hidden="true" class={styles['glyph']}>
+        {props.children}
+      </span>
+    </button>
+  );
+}

package/src/components/Image.module.scss

@@ -0,0 +1,14 @@
+@use '../tokens' as t;
+
+.image {
+  // The inlined width/height give the browser the ratio; `block-size: auto` keeps
+  // it as the box scales down, so a decode never moves what is under the image.
+  display: block;
+  max-inline-size: 100%;
+  block-size: auto;
+
+  // Painted only when the image fails to load: the browser renders the alt text
+  // inside this box, and it inherits the img's own colour and font-size.
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+}

package/src/components/Image.tsx

@@ -0,0 +1,59 @@
+// Zero-CLS image primitive: a plain <img>, no JS, no fetch, no client state.
+//
+// The build-time half of the pipeline in `docs/idea/07-rendering-seo.md` — reading
+// real dimensions, encoding AVIF/WebP renditions, the data-URI blur placeholder —
+// is NOT here. This component emits exactly what it is handed and fabricates
+// nothing: no variants it was not given, no dimensions it did not measure.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Image.module.scss';
+import {
+  assertNonEmptySrc,
+  boxFor,
+  type ImageBox,
+  type ImageLoadingHints,
+  type ImageVariant,
+  loadingHints,
+  srcsetFor,
+} from './image-source';
+
+export interface ImageProps {
+  src: string;
+  /**
+   * Required, with no default: an <Image> whose meaning is undescribed is a type
+   * error at the call site. Pass `alt=""` for a decorative image, deliberately.
+   */
+  alt: string;
+  /** Renditions to offer; the descriptors and their order are derived, not written. */
+  variants?: readonly ImageVariant[] | undefined;
+  /** Layout width of the box, e.g. `(max-width: 700px) 100vw, 620px`. */
+  sizes?: string | undefined;
+  /** The LCP image, at most one per route: eager, high fetch priority. */
+  priority?: boolean | undefined;
+  /** Intrinsic dimensions, from the build step that measured them. Both or neither. */
+  width?: number | undefined;
+  height?: number | undefined;
+  class?: string | undefined;
+}
+
+export function Image(props: ImageProps): JSX.Element {
+  const src = (): string => assertNonEmptySrc('Image', props.src, props.src);
+  const hints = (): ImageLoadingHints => loadingHints(props.priority);
+  const box = (): ImageBox | undefined => boxFor(props.width, props.height);
+
+  return (
+    <img
+      class={cx(styles['image'], props.class)}
+      src={src()}
+      alt={props.alt}
+      srcset={srcsetFor(props.variants)}
+      sizes={props.sizes}
+      width={box()?.width}
+      height={box()?.height}
+      loading={hints().loading}
+      fetchpriority={hints().fetchpriority}
+      decoding={hints().decoding}
+    />
+  );
+}

package/src/components/Input.module.scss

@@ -0,0 +1,55 @@
+@use '../tokens' as t;
+
+.wrap {
+  @include t.control;
+  display: flex;
+  align-items: center;
+  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 control itself is transparent.
+.input {
+  flex: 1;
+  min-inline-size: 0;
+  border: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  outline: none;
+}
+
+.adornment {
+  display: inline-flex;
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  white-space: nowrap;
+}
+
+.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/Input.tsx

@@ -0,0 +1,84 @@
+// Single-line text control. No `type="number"` convenience wrapper: numeric
+// input uses `inputmode` + a text type so locale decimal separators survive.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './Input.module.scss';
+import type { Size } from './variants';
+
+export type InputType =
+  | 'text'
+  | 'email'
+  | 'password'
+  | 'search'
+  | 'tel'
+  | 'url'
+  | 'date'
+  | 'time'
+  | 'datetime-local';
+
+export interface InputProps {
+  id?: string | undefined;
+  name?: string | undefined;
+  type?: InputType | undefined;
+  value?: string | undefined;
+  placeholder?: string | undefined;
+  size?: Size | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  readonly?: boolean | undefined;
+  autocomplete?: string | undefined;
+  inputmode?: 'text' | 'numeric' | 'decimal' | 'tel' | 'email' | 'url' | 'search' | undefined;
+  maxlength?: number | undefined;
+  /** Non-interactive adornments; keep them icons or units, never controls. */
+  prefix?: JSX.Element | undefined;
+  suffix?: JSX.Element | undefined;
+  class?: string | undefined;
+  'aria-label'?: string | undefined;
+  'aria-describedby'?: string | undefined;
+  'aria-invalid'?: boolean | undefined;
+  onInput?: JSX.EventHandlerUnion<HTMLInputElement, InputEvent> | undefined;
+  onChange?: JSX.EventHandlerUnion<HTMLInputElement, Event> | undefined;
+  onBlur?: JSX.EventHandlerUnion<HTMLInputElement, FocusEvent> | undefined;
+}
+
+export function Input(props: InputProps): JSX.Element {
+  return (
+    <span
+      class={cx(styles['wrap'], styles[`size-${props.size ?? 'md'}`], props.class)}
+      data-disabled={props.disabled === true ? 'true' : undefined}
+    >
+      {props.prefix === undefined ? null : (
+        <span aria-hidden="true" class={styles['adornment']}>
+          {props.prefix}
+        </span>
+      )}
+      <input
+        class={styles['input']}
+        id={props.id}
+        name={props.name}
+        type={props.type ?? 'text'}
+        value={props.value ?? ''}
+        placeholder={props.placeholder}
+        required={props.required === true}
+        disabled={props.disabled === true}
+        readonly={props.readonly === true}
+        autocomplete={props.autocomplete}
+        inputmode={props.inputmode}
+        maxlength={props.maxlength}
+        aria-label={props['aria-label']}
+        aria-describedby={props['aria-describedby']}
+        aria-invalid={ariaBool(props['aria-invalid'])}
+        onInput={props.onInput}
+        onChange={props.onChange}
+        onBlur={props.onBlur}
+      />
+      {props.suffix === undefined ? null : (
+        <span aria-hidden="true" class={styles['adornment']}>
+          {props.suffix}
+        </span>
+      )}
+    </span>
+  );
+}

package/src/components/Link.module.scss

@@ -0,0 +1,42 @@
+@use '../tokens' as t;
+
+.link {
+  @include t.focus-ring;
+  @include t.transition(color, text-decoration-color);
+  border-radius: t.radius(sm);
+  text-underline-offset: 0.18em;
+  text-decoration-thickness: 1px;
+}
+
+.tone-accent {
+  color: t.role('accent');
+
+  &:hover {
+    color: t.role('accent-strong');
+  }
+}
+
+.tone-inherit {
+  color: inherit;
+}
+
+.underline-always {
+  text-decoration-line: underline;
+}
+
+.underline-hover {
+  text-decoration-line: none;
+
+  &:hover {
+    text-decoration-line: underline;
+  }
+}
+
+.underline-none {
+  text-decoration-line: none;
+}
+
+// Screen-reader-only suffix, e.g. "(opens in a new tab)".
+.hint {
+  @include t.visually-hidden;
+}

package/src/components/Link.tsx

@@ -0,0 +1,46 @@
+// Anchor primitive. External links get `rel` hardening and a translated
+// "opens in a new tab" hint automatically — never a bare `target="_blank"`.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Link.module.scss';
+
+export interface LinkProps {
+  href: string;
+  children: JSX.Element;
+  external?: boolean | undefined;
+  /** Announced suffix for external links; supply via `t()` at the call site. */
+  externalHint?: string | undefined;
+  underline?: 'always' | 'hover' | 'none' | undefined;
+  tone?: 'accent' | 'inherit' | undefined;
+  id?: string | undefined;
+  class?: string | undefined;
+  'aria-current'?: 'page' | 'step' | 'true' | false | undefined;
+  onClick?: JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent> | undefined;
+}
+
+export function Link(props: LinkProps): JSX.Element {
+  const isExternal = (): boolean => props.external === true || /^https?:\/\//.test(props.href);
+
+  return (
+    <a
+      id={props.id}
+      href={props.href}
+      target={isExternal() ? '_blank' : undefined}
+      rel={isExternal() ? 'noopener noreferrer' : undefined}
+      aria-current={props['aria-current']}
+      class={cx(
+        styles['link'],
+        styles[`underline-${props.underline ?? 'hover'}`],
+        styles[`tone-${props.tone ?? 'accent'}`],
+        props.class,
+      )}
+      onClick={props.onClick}
+    >
+      {props.children}
+      {isExternal() && props.externalHint !== undefined ? (
+        <span class={styles['hint']}>{props.externalHint}</span>
+      ) : null}
+    </a>
+  );
+}

package/src/components/LocaleSwitcher.module.scss

@@ -0,0 +1,28 @@
+@use '../tokens' as t;
+
+.select {
+  min-inline-size: 9rem;
+}
+
+.links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: t.space(2);
+  font-size: t.text(sm);
+}
+
+.link {
+  @include t.focus-ring;
+  border-radius: t.radius(sm);
+  color: t.role('fg-muted');
+  text-decoration: none;
+
+  &:hover {
+    color: t.role('accent');
+  }
+
+  &[aria-current='true'] {
+    color: t.role('fg-strong');
+    font-weight: t.weight(semibold);
+  }
+}

package/src/components/LocaleSwitcher.tsx

@@ -0,0 +1,61 @@
+// Locale picker. Option labels come from `Intl.DisplayNames` in each locale's own
+// language (endonyms), so the list needs no translation catalog of its own.
+
+import type { Locale } from '@ultimat3/i18n';
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './LocaleSwitcher.module.scss';
+import { Select, type SelectOption } from './Select';
+
+export interface LocaleSwitcherProps {
+  locales: readonly Locale[];
+  /** Defaults to the context locale. */
+  value?: Locale | undefined;
+  onLocaleChange?: ((locale: Locale) => void) | undefined;
+  /** Render as links instead of a select, for a 0kb-JS `site/` route. */
+  hrefFor?: ((locale: Locale) => string) | undefined;
+  class?: string | undefined;
+}
+
+/** Endonym: the language's name in its own language, e.g. `de` -> "Deutsch". */
+export function localeLabel(tag: Locale): string {
+  const names = new Intl.DisplayNames([tag], { type: 'language' });
+  return names.of(tag) ?? tag;
+}
+
+export function LocaleSwitcher(props: LocaleSwitcherProps): JSX.Element {
+  const ui = useUi();
+  const current = (): Locale => props.value ?? ui.locale;
+  const options = (): SelectOption[] =>
+    props.locales.map((tag) => ({ value: tag, label: localeLabel(tag) }));
+
+  if (props.hrefFor !== undefined) {
+    return (
+      <nav class={cx(styles['links'], props.class)} aria-label={ui.t(UI_KEYS.language)}>
+        {props.locales.map((tag) => (
+          <a
+            class={styles['link']}
+            href={props.hrefFor?.(tag)}
+            hreflang={tag}
+            lang={tag}
+            aria-current={tag === current() ? 'true' : undefined}
+          >
+            {localeLabel(tag)}
+          </a>
+        ))}
+      </nav>
+    );
+  }
+
+  return (
+    <Select
+      class={cx(styles['select'], props.class)}
+      aria-label={ui.t(UI_KEYS.language)}
+      value={current()}
+      options={options()}
+      onChange={(event) => props.onLocaleChange?.(event.currentTarget.value)}
+    />
+  );
+}

package/src/components/Menu.module.scss

@@ -0,0 +1,63 @@
+@use '../tokens' as t;
+
+.anchor {
+  position: relative;
+  display: inline-block;
+}
+
+.menu {
+  @include t.surface('surface-raised', 'lg');
+  position: absolute;
+  z-index: t.z(dropdown);
+  inset-block-start: calc(100% + #{t.space(1)});
+  display: flex;
+  flex-direction: column;
+  min-inline-size: 12rem;
+  padding: t.space(1);
+}
+
+.align-start {
+  inset-inline-start: 0;
+}
+
+.align-end {
+  inset-inline-end: 0;
+}
+
+.item {
+  @include t.focus-ring;
+  @include t.transition(background, color);
+  display: flex;
+  align-items: center;
+  gap: t.space(2);
+  padding-block: t.space(2);
+  padding-inline: t.space(3);
+  border-radius: t.radius(sm);
+  color: t.role('fg');
+  font-size: t.text(sm);
+  // Menu labels read from the start edge in both writing directions.
+  text-align: start;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: t.role('bg-soft');
+  }
+
+  &:disabled {
+    color: t.role('fg-muted');
+    cursor: not-allowed;
+  }
+}
+
+.destructive {
+  color: t.role('danger');
+
+  &:hover:not(:disabled) {
+    background: t.role('danger-soft');
+  }
+}
+
+.icon {
+  display: inline-flex;
+  color: t.role('fg-muted');
+}

package/src/components/Menu.tsx

@@ -0,0 +1,115 @@
+// Action menu: a trigger plus a `role="menu"` list with roving tabindex.
+// Distinct from Select — a menu runs commands, it does not hold a form value.
+
+import type { JSX } from 'solid-js';
+import { createRovingTabindex, useId } from '../a11y';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import styles from './Menu.module.scss';
+
+export interface MenuItem {
+  id: string;
+  /** Already-translated item label. */
+  label: string;
+  onSelect: () => void;
+  disabled?: boolean | undefined;
+  /** Renders with the danger role; use for irreversible actions. */
+  destructive?: boolean | undefined;
+  icon?: JSX.Element | undefined;
+}
+
+export interface MenuProps {
+  items: readonly MenuItem[];
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  trigger: (control: {
+    id: string;
+    'aria-haspopup': 'menu';
+    'aria-expanded': boolean;
+    'aria-controls': string;
+  }) => JSX.Element;
+  /** Already-translated accessible name for the menu. */
+  label: string;
+  align?: 'start' | 'end' | undefined;
+  class?: string | undefined;
+}
+
+export function Menu(props: MenuProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const menuId = useId('menu');
+  let root: HTMLDivElement | undefined;
+  let list: HTMLDivElement | undefined;
+
+  const onKeyDown = createRovingTabindex(
+    () =>
+      list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>('[role="menuitem"]')),
+    { orientation: 'vertical', dir: ui.dir },
+  );
+
+  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 onEscape = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') props.onOpenChange(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown, true);
+    document.addEventListener('keydown', onEscape);
+    rt.onCleanup(() => {
+      document.removeEventListener('pointerdown', onPointerDown, true);
+      document.removeEventListener('keydown', onEscape);
+    });
+  });
+
+  return (
+    <div
+      class={cx(styles['anchor'], props.class)}
+      ref={(el: HTMLDivElement) => {
+        root = el;
+      }}
+    >
+      {props.trigger({
+        id: `${menuId}-trigger`,
+        'aria-haspopup': 'menu',
+        'aria-expanded': props.open,
+        'aria-controls': menuId,
+      })}
+      {props.open ? (
+        <div
+          ref={(el: HTMLDivElement) => {
+            list = el;
+          }}
+          id={menuId}
+          role="menu"
+          aria-label={props.label}
+          class={cx(styles['menu'], styles[`align-${props.align ?? 'start'}`])}
+          onKeyDown={onKeyDown}
+        >
+          {props.items.map((item, index) => (
+            <button
+              type="button"
+              role="menuitem"
+              class={cx(styles['item'], item.destructive === true && styles['destructive'])}
+              tabindex={index === 0 ? 0 : -1}
+              disabled={item.disabled === true}
+              onClick={() => {
+                item.onSelect();
+                props.onOpenChange(false);
+              }}
+            >
+              {item.icon === undefined ? null : (
+                <span aria-hidden="true" class={styles['icon']}>
+                  {item.icon}
+                </span>
+              )}
+              {item.label}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/Money.module.scss

@@ -0,0 +1,11 @@
+@use '../tokens' as t;
+
+.money {
+  // Tabular figures so a column of amounts lines up without a monospace font.
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.negative {
+  color: t.role('danger');
+}

package/src/components/Money.tsx

@@ -0,0 +1,49 @@
+// Formats through @ultimat3/money using the locale and currency from context —
+// never a process-wide default, never a float, never a hardcoded symbol.
+
+import type { FormatMoneyOptions, Money as MoneyValue } from '@ultimat3/money';
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import styles from './Money.module.scss';
+import { type MoneyFormatter, moneyText } from './money-view';
+
+export interface MoneyProps {
+  /** A Money value, or bare minor units in the context currency. */
+  value: MoneyValue | number;
+  /** Overrides the context currency for bare-number values. */
+  currency?: string | undefined;
+  /** Overrides the context locale. Use only for side-by-side comparisons. */
+  locale?: string | undefined;
+  /** Colour negatives with the danger role, e.g. in a ledger. */
+  signed?: boolean | undefined;
+  /** Passed to @ultimat3/money: display, accounting, grouping, fractionDigits. */
+  options?: FormatMoneyOptions | undefined;
+  format?: MoneyFormatter | undefined;
+  class?: string | undefined;
+}
+
+export function Money(props: MoneyProps): JSX.Element {
+  const ui = useUi();
+  const minor = (): number => (typeof props.value === 'number' ? props.value : props.value.minor);
+  const text = (): string =>
+    moneyText({
+      value: props.value,
+      locale: props.locale ?? ui.locale,
+      currency: props.currency ?? ui.currency,
+      ...(props.options === undefined ? {} : { options: props.options }),
+      ...(props.format === undefined ? {} : { format: props.format }),
+    });
+
+  return (
+    <span
+      class={cx(
+        styles['money'],
+        props.signed === true && minor() < 0 && styles['negative'],
+        props.class,
+      )}
+    >
+      {text()}
+    </span>
+  );
+}