@ultimat3/ui 1.0.0

package/src/components/Drawer.tsx

@@ -0,0 +1,76 @@
+// Edge-anchored panel, also a native <dialog> so it inherits the top layer and
+// inert background. `side` is logical (`inline-start`/`inline-end`), so a drawer
+// pinned to the start edge lands on the right in an RTL locale automatically.
+
+import type { JSX } from 'solid-js';
+import { 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 './Drawer.module.scss';
+import { IconButton } from './IconButton';
+
+export type DrawerSide = 'inline-start' | 'inline-end' | 'block-start' | 'block-end';
+
+export interface DrawerProps {
+  open: boolean;
+  /** Already-translated title. Becomes the drawer's accessible name. */
+  title: string;
+  children: JSX.Element;
+  onClose: () => void;
+  side?: DrawerSide | undefined;
+  size?: string | undefined;
+  footer?: JSX.Element | undefined;
+  class?: string | undefined;
+}
+
+export function Drawer(props: DrawerProps): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const titleId = useId('drawer-title');
+  let element: HTMLDialogElement | undefined;
+
+  rt.createEffect(() => {
+    const dialog = element;
+    if (dialog === undefined) return;
+    if (props.open && !dialog.open) dialog.showModal();
+    if (!props.open && dialog.open) dialog.close();
+  });
+
+  return (
+    // The backdrop's keyboard equivalent is Esc, which <dialog> raises as `cancel`, and
+    // `onCancel` below closes on it.
+    // biome-ignore lint/a11y/useKeyWithClickEvents: Esc closes through onCancel
+    <dialog
+      ref={(el: HTMLDialogElement) => {
+        element = el;
+      }}
+      class={cx(styles['drawer'], styles[`side-${props.side ?? 'inline-end'}`], props.class)}
+      style={{ '--drawer-size': props.size ?? '22rem' }}
+      aria-labelledby={titleId}
+      onCancel={(event) => {
+        event.preventDefault();
+        props.onClose();
+      }}
+      onClick={(event) => {
+        if (event.target === element) props.onClose();
+      }}
+    >
+      <div class={styles['panel']}>
+        <header class={styles['header']}>
+          <h2 class={styles['title']} id={titleId}>
+            {props.title}
+          </h2>
+          <IconButton label={ui.t(UI_KEYS.close)} size="sm" onClick={() => props.onClose()}>
+            <span aria-hidden="true">×</span>
+          </IconButton>
+        </header>
+        <div class={styles['body']}>{props.children}</div>
+        {props.footer === undefined ? null : (
+          <footer class={styles['footer']}>{props.footer}</footer>
+        )}
+      </div>
+    </dialog>
+  );
+}

package/src/components/EmptyState.module.scss

@@ -0,0 +1,34 @@
+@use '../tokens' as t;
+
+.empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: t.space(2);
+  padding-block: t.space(12);
+  padding-inline: t.space(6);
+  border: 1px dashed t.role('line');
+  border-radius: t.radius(lg);
+  color: t.role('fg-muted');
+  text-align: center;
+}
+
+.icon {
+  color: t.role('fg-muted');
+  font-size: t.text(2xl);
+}
+
+.title {
+  color: t.role('fg-strong');
+  font-size: t.text(lg);
+  font-weight: t.weight(semibold);
+}
+
+.description {
+  max-inline-size: 44ch;
+  font-size: t.text(sm);
+}
+
+.action {
+  margin-block-start: t.space(2);
+}

package/src/components/EmptyState.tsx

@@ -0,0 +1,35 @@
+// The "nothing here yet" surface. Title and description arrive as already
+// translated strings; the action slot takes a Button so there is one CTA shape.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './EmptyState.module.scss';
+
+export interface EmptyStateProps {
+  /** Already-translated. Falls back to the `ui.empty` catalog key. */
+  title?: string | undefined;
+  description?: string | undefined;
+  icon?: JSX.Element | undefined;
+  action?: JSX.Element | undefined;
+  class?: string | undefined;
+}
+
+export function EmptyState(props: EmptyStateProps): JSX.Element {
+  const ui = useUi();
+  return (
+    <div class={cx(styles['empty'], props.class)}>
+      {props.icon === undefined ? null : (
+        <span aria-hidden="true" class={styles['icon']}>
+          {props.icon}
+        </span>
+      )}
+      <p class={styles['title']}>{props.title ?? ui.t(UI_KEYS.empty)}</p>
+      {props.description === undefined ? null : (
+        <p class={styles['description']}>{props.description}</p>
+      )}
+      {props.action === undefined ? null : <div class={styles['action']}>{props.action}</div>}
+    </div>
+  );
+}

package/src/components/ErrorState.module.scss

@@ -0,0 +1,77 @@
+@use '../tokens' as t;
+
+.error {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(3);
+  padding: t.space(5);
+  border: 1px solid t.role('danger', 0.4);
+  border-radius: t.radius(lg);
+  background: t.role('danger-soft');
+  color: t.role('fg');
+}
+
+.head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: t.space(2);
+}
+
+.code {
+  padding-block: 0.1rem;
+  padding-inline: t.space(2);
+  border-radius: t.radius(sm);
+  background: t.role('danger');
+  color: t.role('danger-fg');
+  font-family: var(--font-mono);
+  font-size: t.text(xs);
+  font-weight: t.weight(semibold);
+}
+
+.title {
+  color: t.role('fg-strong');
+  font-weight: t.weight(semibold);
+}
+
+.detail {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: t.space(1) t.space(3);
+  font-size: t.text(sm);
+
+  > :global(dt) {
+    color: t.role('fg-muted');
+    font-weight: t.weight(medium);
+  }
+
+  > :global(dd) {
+    min-inline-size: 0;
+    overflow-wrap: anywhere;
+  }
+}
+
+.fix {
+  display: inline-block;
+  padding-block: 0.1rem;
+  padding-inline: t.space(2);
+  border: 1px solid t.role('line');
+  border-radius: t.radius(sm);
+  background: t.role('surface-raised');
+  font-family: var(--font-mono);
+  font-size: t.text(xs);
+  user-select: all;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: t.space(3);
+}
+
+.docs {
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+  text-decoration: underline;
+}

package/src/components/ErrorState.tsx

@@ -0,0 +1,84 @@
+// Renders an UltimateError with the same three strings the terminal prints:
+// 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 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 './ErrorState.module.scss';
+
+export interface ErrorStateProps {
+  /** An UltimateError, or any thrown value; unknown values get X_INTERNAL text. */
+  error: unknown;
+  onRetry?: (() => void) | undefined;
+  /** Already-translated; falls back to the ui.* catalog keys. */
+  retryLabel?: string | undefined;
+  /** Link the code to its docs page. On by default. */
+  showDocs?: boolean | undefined;
+  class?: string | undefined;
+}
+
+interface ErrorParts {
+  readonly code: string;
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+}
+
+export function errorParts(error: unknown): ErrorParts {
+  if (isUltimateError(error)) {
+    return {
+      code: error.code,
+      title: error.title,
+      cause: error.cause,
+      fix: error.fix,
+      docs: error.docs,
+    };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    code: 'X_INTERNAL',
+    title: 'unexpected internal framework error',
+    cause: message,
+    fix: 'x logs --json | tail -50',
+    docs: 'https://ultimate.dev/errors/X_INTERNAL',
+  };
+}
+
+export function ErrorState(props: ErrorStateProps): JSX.Element {
+  const ui = useUi();
+  const parts = (): ErrorParts => errorParts(props.error);
+
+  return (
+    <div class={cx(styles['error'], props.class)} role="alert">
+      <p class={styles['head']}>
+        <code class={styles['code']}>{parts().code}</code>
+        <span class={styles['title']}>{parts().title}</span>
+      </p>
+      <dl class={styles['detail']}>
+        <dt>{ui.t(UI_KEYS.errorCause)}</dt>
+        <dd>{parts().cause}</dd>
+        <dt>{ui.t(UI_KEYS.errorFix)}</dt>
+        <dd>
+          <code class={styles['fix']}>{parts().fix}</code>
+        </dd>
+      </dl>
+      <div class={styles['actions']}>
+        {props.onRetry === undefined ? null : (
+          <Button size="sm" variant="secondary" tone="danger" onClick={() => props.onRetry?.()}>
+            {props.retryLabel ?? ui.t(UI_KEYS.retry)}
+          </Button>
+        )}
+        {props.showDocs === false ? null : (
+          <a class={styles['docs']} href={parts().docs} target="_blank" rel="noopener noreferrer">
+            {parts().code}
+          </a>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/Field.module.scss

@@ -0,0 +1,41 @@
+@use '../tokens' as t;
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(1);
+}
+
+.label {
+  display: flex;
+  align-items: baseline;
+  gap: t.space(1);
+  color: t.role('fg-strong');
+  font-size: t.text(sm);
+  font-weight: t.weight(medium);
+}
+
+.required {
+  color: t.role('danger');
+}
+
+.optional {
+  color: t.role('fg-muted');
+  font-weight: t.weight(normal);
+}
+
+.hint {
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+}
+
+.error {
+  color: t.role('danger');
+  font-size: t.text(xs);
+  font-weight: t.weight(medium);
+}
+
+// `:has()` lets the whole field react to an invalid control with no extra class.
+.field:has([aria-invalid='true']) .label {
+  color: t.role('danger');
+}

package/src/components/Field.tsx

@@ -0,0 +1,86 @@
+// Label + hint + error, wired for a11y. Field owns the ids and hands them to the
+// control through a render prop, so `aria-describedby` and `aria-invalid` can
+// never drift out of sync with what is actually rendered.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './Field.module.scss';
+
+/** Spread straight onto Input/Textarea/Select/Checkbox. */
+export interface FieldControl {
+  readonly id: string;
+  readonly 'aria-describedby': string | undefined;
+  readonly 'aria-invalid': boolean;
+  readonly required: boolean;
+}
+
+export interface FieldProps {
+  /** Already-translated label. Rendered as a real <label for>. */
+  label: string;
+  children: (control: FieldControl) => JSX.Element;
+  hint?: string | undefined;
+  /** Present means invalid; the string is announced with the control. */
+  error?: string | undefined;
+  required?: boolean | undefined;
+  /** Appends a translated "(optional)" marker instead of marking required. */
+  markOptional?: boolean | undefined;
+  class?: string | undefined;
+}
+
+export function Field(props: FieldProps): JSX.Element {
+  const ui = useUi();
+  const id = useId('field');
+  const hintId = `${id}-hint`;
+  const errorId = `${id}-error`;
+
+  const describedBy = (): string | undefined => {
+    const ids = [
+      props.hint === undefined ? null : hintId,
+      props.error === undefined ? null : errorId,
+    ].filter((value): value is string => value !== null);
+    return ids.length === 0 ? undefined : ids.join(' ');
+  };
+
+  const control = (): FieldControl => ({
+    id,
+    'aria-describedby': describedBy(),
+    'aria-invalid': props.error !== undefined,
+    required: props.required === true,
+  });
+
+  return (
+    <div
+      class={cx(
+        styles['field'],
+        props.error === undefined ? undefined : styles['invalid'],
+        props.class,
+      )}
+    >
+      <label class={styles['label']} for={id}>
+        {props.label}
+        {props.required === true ? (
+          <span class={styles['required']} title={ui.t(UI_KEYS.required)}>
+            *
+          </span>
+        ) : null}
+        {props.markOptional === true ? (
+          <span class={styles['optional']}>{ui.t(UI_KEYS.optional)}</span>
+        ) : null}
+      </label>
+      {props.hint === undefined ? null : (
+        <p class={styles['hint']} id={hintId}>
+          {props.hint}
+        </p>
+      )}
+      {props.children(control())}
+      {props.error === undefined ? null : (
+        <p class={styles['error']} id={errorId} role="alert">
+          {props.error}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/Form.module.scss

@@ -0,0 +1,21 @@
+@use '../tokens' as t;
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--form-gap, #{t.space(5)});
+}
+
+.summary:focus {
+  outline: 2px solid t.role('danger');
+  outline-offset: 4px;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: t.space(3);
+  align-items: center;
+  // Trailing edge in both writing directions.
+  justify-content: flex-end;
+}

package/src/components/Form.tsx

@@ -0,0 +1,51 @@
+// Form shell. Owns the one thing every form needs and always forgets: a
+// top-of-form error summary that is focusable and announced on submit.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { Alert } from './Alert';
+import styles from './Form.module.scss';
+import type { SpaceStep } from './variants';
+
+export interface FormProps {
+  children: JSX.Element;
+  /** Already-translated summary shown above the fields when submit fails. */
+  error?: string | undefined;
+  /** Already-translated heading for the error summary region. */
+  errorTitle?: string | undefined;
+  actions?: JSX.Element | undefined;
+  gap?: SpaceStep | undefined;
+  method?: 'get' | 'post' | undefined;
+  action?: string | undefined;
+  novalidate?: boolean | undefined;
+  class?: string | undefined;
+  'aria-label'?: string | undefined;
+  onSubmit?: JSX.EventHandlerUnion<HTMLFormElement, SubmitEvent> | undefined;
+}
+
+export function Form(props: FormProps): JSX.Element {
+  const summaryId = useId('form-error');
+  return (
+    <form
+      class={cx(styles['form'], props.class)}
+      style={{ '--form-gap': `var(--space-${props.gap ?? 5})` }}
+      method={props.method ?? 'post'}
+      action={props.action}
+      novalidate={props.novalidate === true}
+      aria-label={props['aria-label']}
+      aria-describedby={props.error === undefined ? undefined : summaryId}
+      onSubmit={props.onSubmit}
+    >
+      {props.error === undefined ? null : (
+        <div id={summaryId} tabindex="-1" class={styles['summary']}>
+          <Alert tone="danger" title={props.errorTitle}>
+            {props.error}
+          </Alert>
+        </div>
+      )}
+      {props.children}
+      {props.actions === undefined ? null : <div class={styles['actions']}>{props.actions}</div>}
+    </form>
+  );
+}

package/src/components/Grid.module.scss

@@ -0,0 +1,9 @@
+@use '../tokens' as t;
+
+.grid {
+  display: grid;
+  grid-template-columns: var(--grid-tracks, 1fr);
+  column-gap: var(--grid-gap, #{t.space(4)});
+  row-gap: var(--grid-row-gap, #{t.space(4)});
+  list-style: none;
+}

package/src/components/Grid.tsx

@@ -0,0 +1,40 @@
+// Grid layout primitive. The default is an intrinsic responsive grid
+// (`auto-fit` + `minmax`) so most layouts need no breakpoint at all.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Grid.module.scss';
+import type { SpaceStep } from './variants';
+
+export interface GridProps {
+  children: JSX.Element;
+  /** Fixed track count. Omit for the intrinsic `auto-fit` behaviour. */
+  columns?: number | undefined;
+  /** Minimum track width for the intrinsic grid. */
+  minColumn?: string | undefined;
+  gap?: SpaceStep | undefined;
+  rowGap?: SpaceStep | undefined;
+  as?: 'div' | 'ul' | 'ol' | 'section' | undefined;
+  class?: string | undefined;
+}
+
+export function Grid(props: GridProps): JSX.Element {
+  const Tag = props.as ?? 'div';
+  const tracks = (): string =>
+    props.columns === undefined
+      ? `repeat(auto-fit, minmax(${props.minColumn ?? '16rem'}, 1fr))`
+      : `repeat(${props.columns}, minmax(0, 1fr))`;
+
+  return (
+    <Tag
+      class={cx(styles['grid'], props.class)}
+      style={{
+        '--grid-tracks': tracks(),
+        '--grid-gap': `var(--space-${props.gap ?? 4})`,
+        '--grid-row-gap': `var(--space-${props.rowGap ?? props.gap ?? 4})`,
+      }}
+    >
+      {props.children}
+    </Tag>
+  );
+}

package/src/components/IconButton.module.scss

@@ -0,0 +1,99 @@
+@use '../tokens' as t;
+
+.iconButton {
+  @include t.focus-ring;
+  @include t.transition(background, color, border-color);
+  display: inline-grid;
+  place-items: center;
+  border: 1px solid transparent;
+  border-radius: t.radius(md);
+  color: t.role('fg-muted');
+  cursor: pointer;
+
+  &:disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+}
+
+.round {
+  border-radius: t.radius(full);
+}
+
+.glyph {
+  display: inline-flex;
+  // Icons inherit the text colour so a tone change needs no icon variant.
+  color: currentcolor;
+}
+
+.size-sm {
+  inline-size: 1.75rem;
+  block-size: 1.75rem;
+  font-size: t.text(sm);
+}
+
+.size-md {
+  inline-size: 2.25rem;
+  block-size: 2.25rem;
+  font-size: t.text(md);
+}
+
+.size-lg {
+  inline-size: 2.75rem;
+  block-size: 2.75rem;
+  font-size: t.text(lg);
+}
+
+.tone-neutral {
+  --tone: #{t.role('fg-strong')};
+  --tone-soft: #{t.role('bg-soft')};
+}
+
+.tone-accent {
+  --tone: #{t.role('accent')};
+  --tone-soft: #{t.role('accent', 0.12)};
+}
+
+.tone-success {
+  --tone: #{t.role('success')};
+  --tone-soft: #{t.role('success-soft')};
+}
+
+.tone-warning {
+  --tone: #{t.role('warning')};
+  --tone-soft: #{t.role('warning-soft')};
+}
+
+.tone-danger {
+  --tone: #{t.role('danger')};
+  --tone-soft: #{t.role('danger-soft')};
+}
+
+.tone-info {
+  --tone: #{t.role('info')};
+  --tone-soft: #{t.role('info-soft')};
+}
+
+.variant-primary {
+  background: var(--tone);
+  color: t.role('accent-fg');
+}
+
+.variant-secondary {
+  border-color: t.role('line');
+  background: t.role('surface-raised');
+
+  &:hover:not(:disabled) {
+    color: var(--tone);
+  }
+}
+
+.variant-ghost,
+.variant-link {
+  background: transparent;
+
+  &:hover:not(:disabled) {
+    background: var(--tone-soft);
+    color: var(--tone);
+  }
+}