@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/lib/context.tsx

@@ -0,0 +1,156 @@
+import { createContext, useContext, useEffect, useMemo, type ReactNode } from "react";
+import { Direction } from "radix-ui";
+import { currentConfig, directionOf, translate, type MessageVars, type Messages } from "./i18n.ts";
+import {
+  displayTimeZone,
+  formatCompact,
+  formatCurrency,
+  formatDate,
+  formatList,
+  formatNumber,
+  formatZonedDateTime,
+} from "./format.ts";
+import { applyTheme, type ThemePreference } from "./theme.ts";
+import { DEFAULT_PREFERENCES, type DisplayPreferences } from "./preferences.ts";
+import { resolveUnitSystem, type UnitSystem } from "@xos/i18n/units";
+
+interface LocaleState {
+  locale: string;
+  messages: Messages;
+}
+
+const LocaleContext = createContext<LocaleState | null>(null);
+const PreferencesContext = createContext<DisplayPreferences>(DEFAULT_PREFERENCES);
+/** The viewer's own IANA time zone (locale.time_zone), for me.time_zone_display. */
+const ViewerZoneContext = createContext<string | null>(null);
+
+export interface XOSProviderProps {
+  /** BCP 47 locale for copy and Intl formatting; en-US by default. */
+  locale?: string;
+  /** Flat `ui` messages merged over the catalog, keyed without the namespace. */
+  messages?: Messages;
+  /** Applies a theme preference to the document root while mounted. */
+  theme?: ThemePreference;
+  /** The person's display preferences (density, date format, units, week start); defaults when omitted. */
+  preferences?: DisplayPreferences;
+  children: ReactNode;
+}
+
+/**
+ * Sets the locale, text direction and, optionally, the theme for every component below it. Without a
+ * provider, components read the locale set by `configure`.
+ */
+export function XOSProvider({ locale, messages, theme, preferences, children }: XOSProviderProps) {
+  const fallback = currentConfig();
+  const resolvedLocale = locale ?? fallback.locale;
+  const value = useMemo(
+    () => ({ locale: resolvedLocale, messages: { ...fallback.messages, ...messages } }),
+    [resolvedLocale, fallback.messages, messages],
+  );
+  useEffect(() => (theme === undefined ? undefined : applyTheme(theme)), [theme]);
+  return (
+    <LocaleContext.Provider value={value}>
+      <PreferencesContext.Provider value={preferences ?? DEFAULT_PREFERENCES}>
+        <Direction.Provider dir={directionOf(resolvedLocale)}>{children}</Direction.Provider>
+      </PreferencesContext.Provider>
+    </LocaleContext.Provider>
+  );
+}
+
+/**
+ * Sets the display preferences for the components below it, under an `XOSProvider`. The app shells use it
+ * with the person's resolved settings, so a saved setting shows on the page it was saved from.
+ */
+export function PreferencesProvider({
+  preferences,
+  timeZone,
+  children,
+}: {
+  preferences: DisplayPreferences;
+  /** The viewer's own IANA time zone (locale.time_zone), which "my time zone" shows schedule times in. */
+  timeZone?: string | null;
+  children: ReactNode;
+}) {
+  return (
+    <PreferencesContext.Provider value={preferences}>
+      <ViewerZoneContext.Provider value={timeZone ?? null}>{children}</ViewerZoneContext.Provider>
+    </PreferencesContext.Provider>
+  );
+}
+
+/** The person's display preferences from the nearest provider (Section 4.5.6, A65-001). */
+export function usePreferences(): DisplayPreferences {
+  return useContext(PreferencesContext);
+}
+
+/** The viewer's own time zone from the nearest PreferencesProvider, or null when the shell gave none. */
+export function useViewerTimeZone(): string | null {
+  return useContext(ViewerZoneContext);
+}
+
+/**
+ * Formats schedule times in the zone the person chose (me.time_zone_display, Section 15): the event's zone by
+ * default, their own when they chose it. Every time carries its zone abbreviation.
+ */
+export function useZonedTime() {
+  const locale = useLocale();
+  const { timeZoneDisplay } = usePreferences();
+  const viewer = useViewerTimeZone();
+  return {
+    zone: (eventZone: string | null | undefined) =>
+      displayTimeZone(eventZone, timeZoneDisplay, viewer),
+    dateTime: (iso: string, eventZone: string | null | undefined) => {
+      const zone = displayTimeZone(eventZone, timeZoneDisplay, viewer);
+      return zone
+        ? formatZonedDateTime(locale, iso, zone)
+        : formatZonedDateTime(locale, iso, "UTC");
+    },
+    time: (iso: string, eventZone: string | null | undefined) => {
+      const zone = displayTimeZone(eventZone, timeZoneDisplay, viewer);
+      return formatZonedDateTime(locale, iso, zone ?? "UTC", "time");
+    },
+  };
+}
+
+/** The unit system to show values in (locale.units), given the page's project jurisdiction when it has one. */
+export function useUnitSystem(jurisdiction?: UnitSystem | null): UnitSystem {
+  const locale = useLocale();
+  const { units } = usePreferences();
+  return resolveUnitSystem(units, { jurisdiction: jurisdiction ?? null, locale });
+}
+
+function useLocaleState(): LocaleState {
+  return useContext(LocaleContext) ?? currentConfig();
+}
+
+/** The active locale for Intl formatting. */
+export function useLocale(): string {
+  return useLocaleState().locale;
+}
+
+/** The message overrides of the nearest provider, for components that take messages as a prop. */
+export function useMessages(): Messages {
+  return useLocaleState().messages;
+}
+
+export type Translate = (key: string, vars?: MessageVars) => string;
+
+/** A `t` bound to the provider's locale and messages. */
+export function useT(): Translate {
+  const { locale, messages } = useLocaleState();
+  return (key, vars) => translate(locale, key, vars, messages);
+}
+
+/** Number, money, list and date formatters bound to the active locale and the person's date format. */
+export function useFormat() {
+  const locale = useLocale();
+  const { dateFormat } = usePreferences();
+  return {
+    locale,
+    number: (value: number) => formatNumber(locale, value),
+    currency: (value: number, currency?: string) => formatCurrency(locale, value, currency),
+    compact: (value: number, currency?: string) => formatCompact(locale, value, currency),
+    list: (items: string[]) => formatList(locale, items),
+    date: (iso: string) => formatDate(locale, iso, dateFormat),
+  };
+}

package/src/lib/cx.ts

@@ -0,0 +1,4 @@
+/** Joins class names, dropping falsy entries. Every class string in this package goes through cx or a className literal, which the utility test scans. */
+export function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}

package/src/lib/format.ts

@@ -0,0 +1,200 @@
+/** Locale-aware formatting through Intl. Nothing here stores a display format; values are formatted at render. */
+
+/*
+ * Intl formatters are reused per locale and options. Building one loads locale data and costs far
+ * more than formatting with it: a table built a currency formatter per Money cell, and the first
+ * formatters of a page were a large part of its hydration time on a slow CPU (gate 10, Total
+ * Blocking Time).
+ */
+const numberFormats = new Map<string, Intl.NumberFormat>();
+const dateTimeFormats = new Map<string, Intl.DateTimeFormat>();
+const listFormats = new Map<string, Intl.ListFormat>();
+
+function cached<T>(cache: Map<string, T>, key: string, make: () => T): T {
+  let formatter = cache.get(key);
+  if (formatter === undefined) {
+    formatter = make();
+    cache.set(key, formatter);
+  }
+  return formatter;
+}
+
+function numberFormat(locale: string, options: Intl.NumberFormatOptions = {}): Intl.NumberFormat {
+  return cached(numberFormats, `${locale}|${JSON.stringify(options)}`, () => {
+    return new Intl.NumberFormat(locale, options);
+  });
+}
+
+function dateTimeFormat(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  return cached(dateTimeFormats, `${locale}|${JSON.stringify(options)}`, () => {
+    return new Intl.DateTimeFormat(locale, options);
+  });
+}
+
+export function formatNumber(locale: string, value: number): string {
+  return numberFormat(locale).format(value);
+}
+
+/**
+ * A date and time in a given IANA zone, always labeled with the zone's abbreviation (Section 15: schedule
+ * times "always labeled with the zone abbreviation"), for example "Oct 21, 2026, 7:30 PM EDT". `timeZoneName`
+ * cannot be combined with dateStyle or timeStyle, so the parts are spelled out.
+ */
+export function formatZonedDateTime(
+  locale: string,
+  iso: string | Date,
+  timeZone: string,
+  parts: "dateTime" | "time" = "dateTime",
+): string {
+  const options: Intl.DateTimeFormatOptions =
+    parts === "time"
+      ? { hour: "numeric", minute: "2-digit", timeZone, timeZoneName: "short" }
+      : {
+          year: "numeric",
+          month: "short",
+          day: "numeric",
+          hour: "numeric",
+          minute: "2-digit",
+          timeZone,
+          timeZoneName: "short",
+        };
+  return dateTimeFormat(locale, options).format(typeof iso === "string" ? new Date(iso) : iso);
+}
+
+/** Whether a schedule shows times in the event's zone or the viewer's own (me.time_zone_display). */
+export type TimeZoneDisplay = "event" | "viewer";
+
+/**
+ * The zone a schedule time is shown in (Section 15): the event's (the venue's or project's) by default, or
+ * the viewer's own when they chose that (me.time_zone_display) and their zone is known.
+ */
+export function displayTimeZone(
+  eventZone: string | null | undefined,
+  display: TimeZoneDisplay,
+  viewerZone: string | null | undefined,
+): string | undefined {
+  if (display === "viewer" && viewerZone) return viewerZone;
+  return eventZone ?? viewerZone ?? undefined;
+}
+
+export function formatCurrency(locale: string, value: number, currency = "USD"): string {
+  return numberFormat(locale, { style: "currency", currency }).format(value);
+}
+
+/**
+ * Compact axis ticks (`notation: compact`), as the data visualization rules require. The minimum of no fraction
+ * digits is explicit: with currency, ICU versions disagree on the default (Node 22's gives "$5.0K", Chromium's "$5K"),
+ * and a server-rendered chart whose ticks differ from the browser's fails hydration.
+ */
+export function formatCompact(locale: string, value: number, currency?: string): string {
+  return numberFormat(
+    locale,
+    currency === undefined
+      ? { notation: "compact", minimumFractionDigits: 0, maximumFractionDigits: 1 }
+      : {
+          style: "currency",
+          currency,
+          notation: "compact",
+          minimumFractionDigits: 0,
+          maximumFractionDigits: 1,
+        },
+  ).format(value);
+}
+
+export function formatList(locale: string, items: string[]): string {
+  return cached(listFormats, locale, () => new Intl.ListFormat(locale)).format(items);
+}
+
+interface WeekInfoLocale {
+  getWeekInfo?: () => { firstDay: number };
+  weekInfo?: { firstDay: number };
+}
+
+/**
+ * First day of the week, 0 for Sunday through 6 for Saturday: the person's choice when given
+ * (payroll.week_start), otherwise the locale's.
+ */
+export function weekStart(locale: string, override: number | null = null): number {
+  if (override !== null) return override;
+  try {
+    const intlLocale = new Intl.Locale(locale) as Intl.Locale & WeekInfoLocale;
+    const info = intlLocale.getWeekInfo ? intlLocale.getWeekInfo() : intlLocale.weekInfo;
+    return info ? info.firstDay % 7 : 0;
+  } catch (error) {
+    if (error instanceof RangeError) return 0;
+    throw error;
+  }
+}
+
+export interface IsoParts {
+  y: number;
+  m: number;
+  d: number;
+}
+
+export function parseIso(value: string): IsoParts {
+  const [y = "1970", m = "1", d = "1"] = value.split("-");
+  return { y: Number(y), m: Number(m) - 1, d: Number(d) };
+}
+
+export function toIso(y: number, m: number, d: number): string {
+  return `${y}-${String(m + 1).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+}
+
+export function monthTitle(locale: string, y: number, m: number): string {
+  return dateTimeFormat(locale, { month: "long", year: "numeric" }).format(new Date(y, m, 1));
+}
+
+/** Short weekday names starting from the first day of the week. */
+export function weekdayNames(locale: string, override: number | null = null): string[] {
+  const formatter = dateTimeFormat(locale, { weekday: "short" });
+  const start = weekStart(locale, override);
+  // 2026-02-01 is a Sunday.
+  return Array.from({ length: 7 }, (_, i) =>
+    formatter.format(new Date(2026, 1, 1 + ((start + i) % 7))),
+  );
+}
+
+/** A calendar date for display: by the locale, or year-month-day everywhere (locale.date_format iso). */
+export function formatDate(
+  locale: string,
+  iso: string,
+  dateFormat: "locale" | "iso" = "locale",
+): string {
+  const { y, m, d } = parseIso(iso);
+  if (dateFormat === "iso") return toIso(y, m, d);
+  return dateTimeFormat(locale, { month: "short", day: "numeric", year: "numeric" }).format(
+    new Date(y, m, d),
+  );
+}
+
+export function formatTimeOfDay(locale: string, hours: number, minutes: number): string {
+  return dateTimeFormat(locale, { hour: "numeric", minute: "2-digit" }).format(
+    new Date(2026, 0, 1, hours, minutes),
+  );
+}
+
+/** Month cells for a calendar grid: leading and trailing nulls pad whole weeks. */
+export function monthCells(
+  locale: string,
+  y: number,
+  m: number,
+  override: number | null = null,
+): (number | null)[][] {
+  const first = (new Date(y, m, 1).getDay() - weekStart(locale, override) + 7) % 7;
+  const days = new Date(y, m + 1, 0).getDate();
+  const cells: (number | null)[] = Array.from({ length: first }, () => null);
+  for (let d = 1; d <= days; d++) cells.push(d);
+  while (cells.length % 7) cells.push(null);
+  const weeks: (number | null)[][] = [];
+  for (let w = 0; w < cells.length; w += 7) weeks.push(cells.slice(w, w + 7));
+  return weeks;
+}
+
+/** Seconds as mm:ss; a negative value (overrun) reads +mm:ss. */
+export function formatClock(seconds: number): string {
+  const over = seconds < 0;
+  const s = Math.abs(seconds);
+  const m = Math.floor(s / 60);
+  return `${over ? "+" : ""}${String(m).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}`;
+}

package/src/lib/hooks.ts

@@ -0,0 +1,187 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import { singleKeyShortcutsEnabled } from "./preferences.ts";
+
+/**
+ * Whether a media query matches. Server rendering and hydration see false, so a layout that switches
+ * on it renders the wide markup first and swaps after hydration.
+ */
+export function useMediaQuery(query: string): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+        return () => undefined;
+      }
+      const list = window.matchMedia(query);
+      list.addEventListener("change", onChange);
+      return () => list.removeEventListener("change", onChange);
+    },
+    [query],
+  );
+  const matches = useCallback(
+    () => typeof window.matchMedia === "function" && window.matchMedia(query).matches,
+    [query],
+  );
+  return useSyncExternalStore(subscribe, matches, () => false);
+}
+
+/** True below md (48rem, a phone). */
+export function useNarrow(): boolean {
+  return useMediaQuery("(max-width: 47.999rem)");
+}
+
+/** State that a parent may control (`value` given) or leave to the component (`defaultValue`). */
+export function useControllable<T>(
+  value: T | undefined,
+  defaultValue: T,
+  onChange?: (next: T) => void,
+): [T, (next: T) => void] {
+  const [inner, setInner] = useState(defaultValue);
+  const controlled = value !== undefined;
+  const current = controlled ? value : inner;
+  const set = useCallback(
+    (next: T) => {
+      if (!controlled) setInner(next);
+      onChange?.(next);
+    },
+    [controlled, onChange],
+  );
+  return [current, set];
+}
+
+export interface HotkeyOptions {
+  /** Requires Cmd on Apple platforms or Ctrl elsewhere. */
+  mod?: boolean;
+  /** Ignore the key while typing in a field (default true for unmodified keys). */
+  ignoreInFields?: boolean;
+  enabled?: boolean;
+}
+
+function inField(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return (
+    target.isContentEditable ||
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement
+  );
+}
+
+/**
+ * Binds a document-level shortcut: `useHotkey("k", open, { mod: true })` for the command menu,
+ * `useHotkey("?", openSheet)` for the shortcut sheet. Unmodified keys are ignored while typing.
+ */
+export function useHotkey(
+  key: string,
+  handler: (event: KeyboardEvent) => void,
+  options: HotkeyOptions = {},
+): void {
+  const { mod = false, ignoreInFields = !mod, enabled = true } = options;
+  const latest = useRef(handler);
+  useEffect(() => {
+    latest.current = handler;
+  });
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key.toLowerCase() !== key.toLowerCase()) return;
+      if (mod !== (event.metaKey || event.ctrlKey)) return;
+      if (!mod && !singleKeyShortcutsEnabled()) return;
+      if (ignoreInFields && inField(event.target)) return;
+      event.preventDefault();
+      latest.current(event);
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [key, mod, ignoreInFields, enabled]);
+}
+
+/** Roving focus over a list of elements along one axis, honoring the text direction. */
+export function rovingIndex(
+  key: string,
+  index: number,
+  count: number,
+  orientation: "horizontal" | "vertical",
+  dir: "ltr" | "rtl" = "ltr",
+): number | null {
+  const next =
+    orientation === "horizontal" ? (dir === "rtl" ? "ArrowLeft" : "ArrowRight") : "ArrowDown";
+  const prev =
+    orientation === "horizontal" ? (dir === "rtl" ? "ArrowRight" : "ArrowLeft") : "ArrowUp";
+  if (key === next) return (index + 1) % count;
+  if (key === prev) return (index - 1 + count) % count;
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  return null;
+}
+
+/** The control that asked for an overlay a later render mounts (rememberOverlayOpener). */
+let requestedBy: HTMLElement | null = null;
+
+/**
+ * Remembers the focused control as the opener of an overlay that mounts after a navigation, such as
+ * the side peek a page renders for `?peek`. The route's loading state can hide that control first,
+ * which drops focus to the page body, so the overlay would find no opener when it mounts and could
+ * not hand focus back on close (WCAG 2.4.3). The next overlay that opens takes it.
+ */
+export function rememberOverlayOpener(): void {
+  const active = document.activeElement;
+  requestedBy = active instanceof HTMLElement && active !== document.body ? active : null;
+}
+
+/** Whether an element and its ancestors are displayed (React hides a suspended boundary's content). */
+function displayed(element: HTMLElement): boolean {
+  for (let node: HTMLElement | null = element; node; node = node.parentElement) {
+    if (getComputedStyle(node).display === "none") return false;
+  }
+  return true;
+}
+
+/**
+ * Focus return for an overlay opened without its own trigger (a hotkey, a row click): remembers the
+ * element focused when `open` turns true (or, with focus on the page body, the control that asked
+ * for the overlay) and hands it back on close, so focus never drops to the page body (WCAG 2.4.3).
+ * Pass the result to Radix `onCloseAutoFocus`.
+ *
+ * A route's loading state can hide an open overlay together with its opener (React hides a
+ * suspended boundary's content and runs its effects again when it shows it). Radix then reports a
+ * close while both are hidden, and this effect runs again with focus on the page body; while `open`
+ * stays true the opener survives both and takes focus on the real close. Once `open` turns false
+ * the opener is used or dropped, so a later open never inherits it.
+ */
+export function useReturnFocus(open: boolean): (event: Event) => void {
+  const opener = useRef<HTMLElement | null>(null);
+  const isOpen = useRef(false);
+  /* A layout effect runs before the dialog's own focus move (a passive effect), so it still sees
+     the opener. */
+  useLayoutEffect(() => {
+    if (open) {
+      const active = document.activeElement;
+      const focused = active instanceof HTMLElement && active !== document.body ? active : null;
+      const requested = requestedBy?.isConnected ? requestedBy : null;
+      requestedBy = null;
+      // Kept from the run before only when shown again: the overlay has been open all along.
+      const kept = isOpen.current && opener.current?.isConnected ? opener.current : null;
+      opener.current = kept ?? focused ?? requested;
+    }
+    isOpen.current = open;
+  }, [open]);
+  return useCallback((event: Event) => {
+    const target = opener.current;
+    if (!target?.isConnected) {
+      opener.current = null;
+      return;
+    }
+    event.preventDefault();
+    // A loading state hid the open overlay and its opener: keep it for the real close.
+    if (isOpen.current && !displayed(target)) return;
+    opener.current = null;
+    target.focus();
+  }, []);
+}

package/src/lib/i18n.ts

@@ -0,0 +1,97 @@
+import { defaultLocale } from "@xos/i18n/locales";
+import enUSui from "@xos/i18n/messages/en-US/ui.json" with { type: "json" };
+import { formatNumber } from "./format.ts";
+
+/**
+ * Component copy (ADR 0010, D6). Every visible string comes from the `ui` namespace of the
+ * @xos/i18n catalogs; keys are written without the namespace (`money.unpriced`) and this helper
+ * prefixes `ui.`. Only the en-US `ui` namespace ships with the library: it is the source locale
+ * and the fallback. Any other locale's messages come from `XOSProvider` or `configure`, so the
+ * browser never downloads a locale it does not show (A24-009). Keys those messages do not supply
+ * fall back to en-US.
+ */
+
+export type MessageVars = Record<string, string | number>;
+export type Messages = Record<string, string>;
+
+const NAMESPACE = "ui";
+
+function flatten(value: unknown, prefix: string, out: Messages): Messages {
+  if (typeof value === "string") {
+    out[prefix] = value;
+  } else if (typeof value === "object" && value !== null) {
+    for (const [key, child] of Object.entries(value)) {
+      flatten(child, prefix ? `${prefix}.${key}` : key, out);
+    }
+  }
+  return out;
+}
+
+let source: Messages | undefined;
+
+/** The flat en-US `ui` catalog, keyed without the namespace: the fallback for every locale. */
+export function catalogFor(): Messages {
+  source ??= flatten(enUSui, "", {});
+  return source;
+}
+
+/** Flattens a nested `ui` catalog (such as a pseudo-locale file) into the flat form `configure` takes. */
+export function flattenMessages(nested: unknown): Messages {
+  const root =
+    typeof nested === "object" && nested !== null && NAMESPACE in nested
+      ? (nested as Record<string, unknown>)[NAMESPACE]
+      : nested;
+  return flatten(root, "", {});
+}
+
+export interface XOSConfig {
+  locale?: string;
+  messages?: Record<string, string>;
+}
+
+const config: { locale: string; messages: Messages } = { locale: defaultLocale, messages: {} };
+
+/** Sets the locale for Intl formatting and merges messages over the catalog, for code outside a provider. */
+export function configure(next: XOSConfig): void {
+  if (next.locale !== undefined) config.locale = next.locale;
+  if (next.messages !== undefined) config.messages = { ...config.messages, ...next.messages };
+}
+
+/** The locale and message overrides set by `configure`. */
+export function currentConfig(): { locale: string; messages: Messages } {
+  return config;
+}
+
+/** Fills `{name}` arguments; numbers are formatted for the locale, as an ICU simple argument is. */
+export function format(message: string, locale: string, vars?: MessageVars): string {
+  if (vars === undefined) return message;
+  return message.replace(/\{(\w+)\}/g, (match, name: string) => {
+    const value = vars[name];
+    if (value === undefined) return match;
+    return typeof value === "number" ? formatNumber(locale, value) : value;
+  });
+}
+
+/** Looks up a `ui` message for a locale, with overrides first, and fills its arguments. Unknown keys return the key. */
+export function translate(
+  locale: string,
+  key: string,
+  vars?: MessageVars,
+  overrides: Messages = {},
+): string {
+  const message = overrides[key] ?? catalogFor()[key];
+  return message === undefined ? key : format(message, locale, vars);
+}
+
+/** Looks up a catalog message and fills its arguments, using the locale set by `configure`. */
+export function t(key: string, vars?: MessageVars): string {
+  return translate(config.locale, key, vars, config.messages);
+}
+
+/** Right-to-left scripts, matched on the language subtag; `ar-XB` is the right-to-left pseudo-locale. */
+const RTL_LANGUAGES = new Set(["ar", "fa", "he", "ps", "ur", "yi", "dv", "ckb"]);
+
+export function directionOf(locale: string): "ltr" | "rtl" {
+  const language = locale.split("-")[0]?.toLowerCase() ?? "";
+  return RTL_LANGUAGES.has(language) ? "rtl" : "ltr";
+}

package/src/lib/icons.ts

@@ -0,0 +1,45 @@
+import { isRegisteredIcon, lucideName } from "@xos/icons/names";
+import sprite from "@xos/icons/sprite.svg";
+
+export { lucideName };
+
+/** Icons that point along the reading direction and mirror in right-to-left locales. */
+const MIRRORED = new Set([
+  "ChevronRight",
+  "ChevronLeft",
+  "ArrowUpRight",
+  "ArrowRight",
+  "ArrowLeft",
+  "Undo2",
+  "Send",
+  "ExternalLink",
+]);
+
+/**
+ * URL of the icon sprite (ADR 0027): one SVG file of every registered icon, emitted by the bundler
+ * with a content hash so browsers cache it as a static asset. Next.js imports a static file as
+ * `{ src }`, Vite as a string.
+ */
+export const iconSpriteUrl: string = typeof sprite === "string" ? sprite : sprite.src;
+
+const warned = new Set<string>();
+
+/**
+ * The sprite symbol id for an icon name. In development a name outside the @xos/icons registry
+ * warns once, so it is added to the owner's registry list rather than shipping an empty square;
+ * production skips the check, so no name list reaches the page.
+ */
+export function iconSymbol(name: string): string {
+  const id = lucideName(name);
+  if (process.env["NODE_ENV"] !== "production" && !warned.has(name) && !isRegisteredIcon(name)) {
+    warned.add(name);
+    console.warn(
+      `@xos/ui Icon: "${name}" is not in the @xos/icons registry. Add ${id} to packages/icons/registry/<owner>.txt and run pnpm --filter @xos/icons generate:registry.`,
+    );
+  }
+  return id;
+}
+
+export function isMirrored(name: string): boolean {
+  return MIRRORED.has(lucideName(name));
+}