@ultimat3/ui 1.0.0

package/src/cx.ts

@@ -0,0 +1,42 @@
+// Class-name combiner. Deliberately tiny: SCSS modules mean class lists are
+// short, so there is no need for a `clsx`-sized dependency.
+
+export type ClassValue =
+  | string
+  | number
+  | false
+  | null
+  | undefined
+  | Record<string, boolean | null | undefined>
+  | readonly ClassValue[];
+
+/**
+ * Join truthy class values. Object keys are emitted when their value is truthy,
+ * arrays are flattened, and duplicates collapse so `cx(a, a)` is stable.
+ */
+export function cx(...values: readonly ClassValue[]): string {
+  const out: string[] = [];
+  collect(values, out);
+  return out.join(' ');
+}
+
+function collect(values: readonly ClassValue[], out: string[]): void {
+  for (const value of values) {
+    if (value === null || value === undefined || value === false || value === '') continue;
+    if (typeof value === 'string' || typeof value === 'number') {
+      push(String(value), out);
+    } else if (Array.isArray(value)) {
+      collect(value, out);
+    } else if (typeof value === 'object') {
+      for (const [key, enabled] of Object.entries(value)) {
+        if (enabled) push(key, out);
+      }
+    }
+  }
+}
+
+function push(raw: string, out: string[]): void {
+  for (const name of raw.split(/\s+/)) {
+    if (name && !out.includes(name)) out.push(name);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,72 @@
+// @ultimat3/ui error codes. Every throw carries a stable code, the cause, and
+// the exact fix — identical in the terminal, the browser overlay, and `--json`.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const UI_ERROR_CODES = {
+  tokenUnknown: 'X_TOKEN_UNKNOWN',
+  themeInvalid: 'X_THEME_INVALID',
+  runtimeMissing: 'X_UI_RUNTIME_MISSING',
+  invalidValue: 'X_UI_INVALID_VALUE',
+} as const;
+
+export type UiErrorCode = (typeof UI_ERROR_CODES)[keyof typeof UI_ERROR_CODES];
+
+// Unconditional like every other package: all four codes are ui's own, and a second package
+// claiming one has to throw X_ERROR_CODE_DUPLICATE at import. Taking the process down there is the
+// point — the alternative is two packages shipping two meanings for one code, decided by load order.
+registerErrorCodes({
+  X_TOKEN_UNKNOWN: { title: 'design token role does not exist' },
+  X_THEME_INVALID: { title: 'theme is not "light" or "dark"' },
+  X_UI_RUNTIME_MISSING: { title: 'a host capability @ultimat3/ui needs is absent' },
+  X_UI_INVALID_VALUE: { title: 'a formatting component received an unrenderable value' },
+});
+
+export class UiError extends UltimateError {
+  override readonly name: string = 'UiError';
+
+  constructor(init: { code: UiErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+    });
+  }
+}
+
+/** A component asked for a token role that the SCSS source does not define. */
+export function unknownTokenError(kind: string, name: string, known: readonly string[]): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.tokenUnknown,
+    cause: `unknown ${kind} token "${name}"; known roles: ${known.join(', ')}`,
+    fix: `use one of the ${kind} roles above, or add "${name}" to packages/ui/src/tokens/_${kind}s.scss and mirror it in tokens.ts`,
+  });
+}
+
+/** `data-theme` or a stored preference held something other than light/dark. */
+export function invalidThemeError(value: unknown): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.themeInvalid,
+    cause: `theme must be "light" or "dark", received ${JSON.stringify(value)}`,
+    fix: "call setTheme('light') or setTheme('dark'), or clearTheme() to follow the OS",
+  });
+}
+
+/** A helper reached for a host capability the current environment does not have. */
+export function runtimeMissingError(api: string, fix: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.runtimeMissing,
+    cause: `@ultimat3/ui needed ${api} but it is not available in this environment`,
+    fix,
+  });
+}
+
+/** A formatting component was handed a value it cannot render. */
+export function invalidValueError(kind: string, value: unknown, expected: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `<${kind}> received ${JSON.stringify(value)}, which is not ${expected}`,
+    fix: `pass ${expected} — parse or validate the value in the loader, not in the component`,
+  });
+}

package/src/global.scss

@@ -0,0 +1,5 @@
+// One import for an app document shell: every custom property, then the reset.
+// Component modules add nothing global — they only ever emit their own classes.
+
+@use 'tokens/theme';
+@use 'tokens/reset';

package/src/i18n-keys.ts

@@ -0,0 +1,34 @@
+// Every string the design system needs but cannot receive as a prop. Components
+// resolve these through the context translator, so an app can localise the whole
+// system by adding one namespace to its catalog — and a miss is loud (⟦key⟧).
+
+export const UI_KEYS = {
+  close: 'ui.close',
+  cancel: 'ui.cancel',
+  confirm: 'ui.confirm',
+  dismiss: 'ui.dismiss',
+  loading: 'ui.loading',
+  empty: 'ui.empty',
+  error: 'ui.error',
+  retry: 'ui.retry',
+  next: 'ui.next',
+  previous: 'ui.previous',
+  page: 'ui.page',
+  sortAscending: 'ui.sort.ascending',
+  sortDescending: 'ui.sort.descending',
+  breadcrumb: 'ui.breadcrumb',
+  menu: 'ui.menu',
+  more: 'ui.more',
+  required: 'ui.required',
+  optional: 'ui.optional',
+  theme: 'ui.theme',
+  themeLight: 'ui.theme.light',
+  themeDark: 'ui.theme.dark',
+  themeSystem: 'ui.theme.system',
+  language: 'ui.language',
+  errorCode: 'ui.error.code',
+  errorCause: 'ui.error.cause',
+  errorFix: 'ui.error.fix',
+} as const;
+
+export type UiKey = (typeof UI_KEYS)[keyof typeof UI_KEYS];

package/src/index.ts

@@ -0,0 +1,199 @@
+// The public surface of @ultimat3/ui. Explicit exports only — this list is the
+// design system's contract, and anything not named here is internal.
+
+// Ambient declarations are not reachable through imports, so a consuming app's
+// program would never load them — every `*.module.scss` import in this package
+// would be TS2307 there. The reference pulls the contract along with the entry.
+/// <reference path="./scss.d.ts" />
+
+export type { FocusTrap, Politeness, RovingOptions, RovingOrientation } from './a11y';
+export {
+  announce,
+  ariaBool,
+  createFocusTrap,
+  createRovingTabindex,
+  FOCUSABLE_SELECTOR,
+  focusableWithin,
+  nextRovingIndex,
+  resetIdCounter,
+  useId,
+} from './a11y';
+export type { AlertProps } from './components/Alert';
+// --- components --------------------------------------------------------------
+export { Alert } from './components/Alert';
+export type { AvatarProps } from './components/Avatar';
+export { Avatar, initialsOf } from './components/Avatar';
+export type { BadgeProps } from './components/Badge';
+export { Badge } from './components/Badge';
+export type { BreadcrumbItem, BreadcrumbProps } from './components/Breadcrumb';
+export { Breadcrumb } from './components/Breadcrumb';
+export type { ButtonProps } from './components/Button';
+export { Button } from './components/Button';
+export type { CardProps, Elevation } from './components/Card';
+export { Card } from './components/Card';
+export type { CheckboxProps } from './components/Checkbox';
+export { Checkbox } from './components/Checkbox';
+export type { ContainerProps, ContainerSize } from './components/Container';
+export { Container } from './components/Container';
+export type { Column, DataTableProps } from './components/DataTable';
+export { DataTable } from './components/DataTable';
+export type { DateTimeProps } from './components/DateTime';
+export { DateTime } from './components/DateTime';
+export type { DialogProps } from './components/Dialog';
+export { Dialog } from './components/Dialog';
+export type { DividerProps } from './components/Divider';
+export { Divider } from './components/Divider';
+export type { DrawerProps, DrawerSide } from './components/Drawer';
+export { Drawer } from './components/Drawer';
+export type {
+  DateStyle,
+  DateTimeFormatter,
+  DateTimeView,
+  DateTimeViewOptions,
+  TimeInput,
+} from './components/date-time-view';
+export { dateTimeView, toDate, toInstant, toIsoInstant } from './components/date-time-view';
+export type { EmptyStateProps } from './components/EmptyState';
+export { EmptyState } from './components/EmptyState';
+export type { ErrorStateProps } from './components/ErrorState';
+export { ErrorState, errorParts } from './components/ErrorState';
+export type { FieldControl, FieldProps } from './components/Field';
+export { Field } from './components/Field';
+export type { FormProps } from './components/Form';
+export { Form } from './components/Form';
+export type { GridProps } from './components/Grid';
+export { Grid } from './components/Grid';
+export type { IconButtonProps } from './components/IconButton';
+export { IconButton } from './components/IconButton';
+export type { ImageProps } from './components/Image';
+export { Image } from './components/Image';
+export type { InputProps, InputType } from './components/Input';
+export { Input } from './components/Input';
+export type { ImageBox, ImageLoadingHints, ImageVariant } from './components/image-source';
+export { boxFor, loadingHints, srcsetFor } from './components/image-source';
+export type { LinkProps } from './components/Link';
+export { Link } from './components/Link';
+export type { LocaleSwitcherProps } from './components/LocaleSwitcher';
+export { LocaleSwitcher, localeLabel } from './components/LocaleSwitcher';
+export type { MenuItem, MenuProps } from './components/Menu';
+export { Menu } from './components/Menu';
+export type { MoneyProps } from './components/Money';
+export { Money } from './components/Money';
+export type { MoneyFormatter, MoneyInput, MoneyViewOptions } from './components/money-view';
+// --- formatting cores (pure, renderer-free) ----------------------------------
+export { moneyText, toMoney } from './components/money-view';
+export type { PaginationProps } from './components/Pagination';
+export { Pagination } from './components/Pagination';
+export type { Placement, PopoverProps } from './components/Popover';
+export { Popover } from './components/Popover';
+export type { RadioOption, RadioProps } from './components/Radio';
+export { Radio } from './components/Radio';
+export type { RelativeTimeProps } from './components/RelativeTime';
+export { RelativeTime } from './components/RelativeTime';
+export type { RelativeTimeOptions } from './components/relative-time-view';
+export { relativeTimeText } from './components/relative-time-view';
+export type { SelectOption, SelectProps } from './components/Select';
+export { Select } from './components/Select';
+export type { SkeletonProps } from './components/Skeleton';
+export { Skeleton } from './components/Skeleton';
+export type { SpinnerProps } from './components/Spinner';
+export { Spinner } from './components/Spinner';
+export type { StackProps } from './components/Stack';
+export { Stack } from './components/Stack';
+export type { SwitchProps } from './components/Switch';
+export { Switch } from './components/Switch';
+export type { SortDirection, SortState } from './components/sort-state';
+export { ariaSortFor, nextSortState } from './components/sort-state';
+export type { TableProps } from './components/Table';
+export { Table } from './components/Table';
+export type { TabItem, TabsProps } from './components/Tabs';
+export { Tabs } from './components/Tabs';
+export type { TextProps, TextSize, TextTone, TextWeight } from './components/Text';
+export { TEXT_TONES, Text } from './components/Text';
+export type { TextareaProps } from './components/Textarea';
+export { Textarea } from './components/Textarea';
+export type { ThemeChoice, ThemeToggleProps } from './components/ThemeToggle';
+export { ThemeToggle } from './components/ThemeToggle';
+export type { ToastProps, ToastRegionProps } from './components/Toast';
+export { Toast, ToastRegion } from './components/Toast';
+export type { TooltipProps } from './components/Tooltip';
+export { Tooltip } from './components/Tooltip';
+export type { Align, ButtonVariant, Size, SpaceStep, Tone } from './components/variants';
+// --- variants ----------------------------------------------------------------
+export { BUTTON_VARIANTS, SIZES, TONES } from './components/variants';
+export type { ClassValue } from './cx';
+// --- helpers -----------------------------------------------------------------
+export { cx } from './cx';
+export type { UiErrorCode } from './errors';
+export {
+  invalidThemeError,
+  invalidValueError,
+  runtimeMissingError,
+  UI_ERROR_CODES,
+  UiError,
+  unknownTokenError,
+} from './errors';
+export type { UiKey } from './i18n-keys';
+export { UI_KEYS } from './i18n-keys';
+export type { Direction, UiContextValue } from './theme/context';
+export {
+  defaultUiContext,
+  fallbackTranslator,
+  UI_DEFAULT_CURRENCY,
+  UI_DEFAULT_LOCALE,
+  UI_DEFAULT_TIME_ZONE,
+  uiContext,
+  useUi,
+} from './theme/context';
+export {
+  THEME_INLINE_SCRIPT,
+  themeInlineScriptCspSource,
+  themeInlineScriptHash,
+  themeInlineScriptTag,
+} from './theme/inline-script';
+export type { UiProviderProps } from './theme/provider';
+export { UiProvider } from './theme/provider';
+export type { Accessor, Setter, SolidContext, SolidRuntime } from './theme/solid-adapter';
+export {
+  clearSolidRuntime,
+  hasSolidRuntime,
+  setSolidRuntime,
+  solid,
+} from './theme/solid-adapter';
+export type { ThemeEnv } from './theme/theme';
+// --- theme -------------------------------------------------------------------
+export {
+  browserThemeEnv,
+  clearTheme,
+  initTheme,
+  isTheme,
+  osTheme,
+  resolveTheme,
+  setTheme,
+  storedTheme,
+  THEME_ATTRIBUTE,
+  THEME_MEDIA_QUERY,
+  THEME_STORAGE_KEY,
+  toggleTheme,
+  watchOsTheme,
+} from './theme/theme';
+export type { ColorRole, Theme } from './tokens/tokens';
+// --- tokens ------------------------------------------------------------------
+export {
+  assertColorRole,
+  breakpointTokens,
+  COLOR_ROLES,
+  color,
+  colorRgb,
+  colorTokens,
+  colorVar,
+  durationTokens,
+  easingTokens,
+  fontSizeTokens,
+  fontWeightTokens,
+  lineHeightTokens,
+  radiusTokens,
+  shadowTokens,
+  spaceTokens,
+  zTokens,
+} from './tokens/tokens';

package/src/scss.d.ts

@@ -0,0 +1,7 @@
+// SCSS modules resolve to a class-name map at build time. The default export is
+// the bundler's contract, not ours — component code never re-exports it.
+
+declare module '*.module.scss' {
+  const classes: Readonly<Record<string, string>>;
+  export default classes;
+}

package/src/theme/context.ts

@@ -0,0 +1,65 @@
+// The ambient presentation contract every component reads: theme, locale, tz,
+// currency, direction, translator. Formatting components take nothing from a
+// process-wide default — everything they need arrives here, via UiProvider.
+
+import type { Translator } from '@ultimat3/i18n';
+import { createTranslator, type Direction, directionOf, type Locale } from '@ultimat3/i18n';
+import type { TimeZone } from '@ultimat3/time';
+import type { Theme } from '../tokens/tokens';
+import { type SolidContext, type SolidRuntime, solid } from './solid-adapter';
+
+export type { Direction };
+
+export interface UiContextValue {
+  readonly theme: Theme;
+  /** BCP-47 tag. Drives every Intl call in the tree. */
+  readonly locale: Locale;
+  /** IANA zone. A date is never formatted without one. */
+  readonly timeZone: TimeZone;
+  /** ISO-4217 default for <Money> when the value is bare minor units. */
+  readonly currency: string;
+  readonly dir: Direction;
+  readonly t: Translator;
+}
+
+export const UI_DEFAULT_LOCALE: Locale = 'en';
+export const UI_DEFAULT_TIME_ZONE = 'UTC' as TimeZone;
+export const UI_DEFAULT_CURRENCY = 'USD';
+
+/** Loud-miss translator: a forgotten catalog key renders ⟦key⟧, never blank. */
+export function fallbackTranslator(locale: Locale = UI_DEFAULT_LOCALE): Translator {
+  return createTranslator({}, locale);
+}
+
+export function defaultUiContext(): UiContextValue {
+  return {
+    theme: 'light',
+    locale: UI_DEFAULT_LOCALE,
+    timeZone: UI_DEFAULT_TIME_ZONE,
+    currency: UI_DEFAULT_CURRENCY,
+    dir: directionOf(UI_DEFAULT_LOCALE),
+    t: fallbackTranslator(),
+  };
+}
+
+let cached: {
+  readonly runtime: SolidRuntime;
+  readonly context: SolidContext<UiContextValue>;
+} | null = null;
+
+/**
+ * Created lazily so importing this module never needs a Solid runtime, and keyed on the runtime
+ * that built it: a context belongs to the reactive graph that created it, so handing a stale one
+ * to a replaced runtime reads as a working provider while every consumer sees the default value.
+ */
+export function uiContext(): SolidContext<UiContextValue> {
+  const runtime = solid();
+  if (cached === null || cached.runtime !== runtime) {
+    cached = { runtime, context: runtime.createContext(defaultUiContext()) };
+  }
+  return cached.context;
+}
+
+export function useUi(): UiContextValue {
+  return solid().useContext(uiContext());
+}

package/src/theme/inline-script.ts

@@ -0,0 +1,44 @@
+// The blocking <head> snippet that kills the flash of wrong theme. Built from the
+// same constants as theme.ts so the two can never disagree. Server/build-only:
+// the hash is computed with Bun's hasher for the CSP header.
+
+import { runtimeMissingError } from '../errors';
+import { THEME_ATTRIBUTE, THEME_MEDIA_QUERY, THEME_STORAGE_KEY } from './theme';
+
+/**
+ * Minified on purpose — this runs before first paint and is inlined into every
+ * document. Reads the explicit choice, falls back to the OS, and always stamps
+ * `data-theme` so screenshots and Playwright runs are deterministic.
+ */
+export const THEME_INLINE_SCRIPT =
+  `try{var d=document.documentElement,` +
+  `s=localStorage.getItem('${THEME_STORAGE_KEY}');` +
+  `d.setAttribute('${THEME_ATTRIBUTE}',` +
+  `s==='light'||s==='dark'?s:` +
+  `matchMedia('${THEME_MEDIA_QUERY}').matches?'dark':'light')}catch(e){}`;
+
+/** The exact tag to inline. No attributes, so the CSP hash stays valid. */
+export function themeInlineScriptTag(): string {
+  return `<script>${THEME_INLINE_SCRIPT}</script>`;
+}
+
+let cachedHash: string | null = null;
+
+/** `sha256-<base64>` for `script-src`. Stable for a given script text. */
+export function themeInlineScriptHash(): string {
+  if (cachedHash !== null) return cachedHash;
+  if (typeof Bun === 'undefined') {
+    throw runtimeMissingError(
+      'Bun.CryptoHasher to hash the theme inline script',
+      'call themeInlineScriptHash() during build or SSR, never in browser code',
+    );
+  }
+  const digest = new Bun.CryptoHasher('sha256').update(THEME_INLINE_SCRIPT).digest('base64');
+  cachedHash = `sha256-${digest}`;
+  return cachedHash;
+}
+
+/** Quoted CSP source expression, ready to concatenate into a `script-src`. */
+export function themeInlineScriptCspSource(): string {
+  return `'${themeInlineScriptHash()}'`;
+}

package/src/theme/provider.tsx

@@ -0,0 +1,56 @@
+// UiProvider — the single place an app injects presentation context. Reactive
+// access goes through the Solid adapter, so this file imports only solid types.
+
+import { directionOf, type Locale, type Translator } from '@ultimat3/i18n';
+import type { TimeZone } from '@ultimat3/time';
+import type { JSX } from 'solid-js';
+import type { Theme } from '../tokens/tokens';
+import {
+  fallbackTranslator,
+  UI_DEFAULT_CURRENCY,
+  UI_DEFAULT_LOCALE,
+  UI_DEFAULT_TIME_ZONE,
+  type UiContextValue,
+  uiContext,
+} from './context';
+import { solid } from './solid-adapter';
+
+export interface UiProviderProps {
+  theme?: Theme | undefined;
+  locale?: Locale | undefined;
+  timeZone?: TimeZone | undefined;
+  currency?: string | undefined;
+  t?: Translator | undefined;
+  children?: JSX.Element | undefined;
+}
+
+/**
+ * Also reflects `lang` and `dir` onto <html>, so the document, native form
+ * controls, and every logical property agree with the injected locale.
+ */
+export function UiProvider(props: UiProviderProps): JSX.Element {
+  const rt = solid();
+  const value = rt.createMemo<UiContextValue>(() => {
+    const locale = props.locale ?? UI_DEFAULT_LOCALE;
+    return {
+      theme: props.theme ?? 'light',
+      locale,
+      timeZone: props.timeZone ?? UI_DEFAULT_TIME_ZONE,
+      currency: props.currency ?? UI_DEFAULT_CURRENCY,
+      dir: directionOf(locale),
+      t: props.t ?? fallbackTranslator(locale),
+    };
+  });
+
+  rt.createEffect(() => {
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+    const next = value();
+    root.setAttribute('lang', next.locale);
+    root.setAttribute('dir', next.dir);
+    if (props.theme !== undefined) root.setAttribute('data-theme', next.theme);
+  });
+
+  const Ctx = uiContext();
+  return <Ctx.Provider value={value()}>{props.children}</Ctx.Provider>;
+}

package/src/theme/solid-adapter.ts

@@ -0,0 +1,51 @@
+// Solid runtime adapter. @ultimat3/ui imports *types* from solid-js and nothing
+// else, so the package installs, typechecks, and tests with no reactive runtime
+// present. The app entry (or @ultimat3/render) registers the real one once.
+
+import type { JSX } from 'solid-js';
+import { runtimeMissingError } from '../errors';
+
+export type Accessor<T> = () => T;
+export type Setter<T> = (next: T) => void;
+
+export interface SolidContext<T> {
+  readonly id: symbol;
+  readonly defaultValue: T;
+  readonly Provider: (props: { value: T; children?: JSX.Element }) => JSX.Element;
+}
+
+/** The exact slice of solid-js the design system touches. */
+export interface SolidRuntime {
+  createContext<T>(defaultValue: T): SolidContext<T>;
+  useContext<T>(context: SolidContext<T>): T;
+  createSignal<T>(value: T): [Accessor<T>, Setter<T>];
+  createMemo<T>(fn: () => T): Accessor<T>;
+  createEffect(fn: () => void): void;
+  onCleanup(fn: () => void): void;
+}
+
+let runtime: SolidRuntime | null = null;
+
+/** Register once, in the app entry, before the first render. */
+export function setSolidRuntime(next: SolidRuntime): void {
+  runtime = next;
+}
+
+export function hasSolidRuntime(): boolean {
+  return runtime !== null;
+}
+
+/** For tests: drop the registration so cases stay independent. */
+export function clearSolidRuntime(): void {
+  runtime = null;
+}
+
+export function solid(): SolidRuntime {
+  if (runtime === null) {
+    throw runtimeMissingError(
+      'a registered Solid runtime',
+      "add setSolidRuntime(await import('solid-js')) to the app entry before render",
+    );
+  }
+  return runtime;
+}