prosebook 0.0.0-stage → 0.1.0

package/src/inspector.ts

@@ -0,0 +1,228 @@
+/**
+ * The dev inspector the Vite plugin loads into the page: hold Alt and point at a string to see its
+ * key, Alt-click to open the entry it came from, Alt-Shift-click to open the catalog entry instead of
+ * the translation. Alt-right-click edits the entry on the page instead (`inspector-dialog.ts`).
+ *
+ * Text on screen carries no key. `<Text>` renders a fragment, so marking it would take a wrapper
+ * element that exists only in dev and changes what a stylesheet sees; `t()` returns a bare string. So
+ * the runtime reports every read (`ReadHook`) and the text under the pointer is matched back to them.
+ */
+import type { DevHooks } from '#src/runtime/types.ts';
+
+import { openDialog } from './inspector-dialog.ts';
+
+export interface Read {
+  key: string;
+  /** The locale the message was found in. */
+  locale: string;
+}
+
+/** Recent reads by the text they came to, least recent text first; each text's keys most recent first. */
+export type Reads = Map<string, Read[]>;
+
+/** The character under the pointer: a text node and its index there. */
+export interface Caret {
+  node: Node;
+  offset: number;
+}
+
+export interface Hit {
+  text: string;
+  read: Read;
+  /** How many other keys came to the same text. */
+  others: number;
+  /** The innermost element holding all of the text. */
+  element: Element;
+}
+
+// Enough for every string on a busy screen and the ones it showed a moment ago.
+const LIMIT = 2000;
+const ATTRIBUTES = ['placeholder', 'title', 'aria-label', 'alt', 'value'];
+
+export function record(reads: Reads, key: string, text: string, locale: string): void {
+  if (text.trim() === '') return;
+  const seen = reads.get(text) ?? [];
+  reads.delete(text);
+  reads.set(text, seen[0]?.key === key && seen[0].locale === locale ? seen : [{ key, locale }, ...seen.filter((r) => r.key !== key)]);
+  if (reads.size > LIMIT) reads.delete(reads.keys().next().value!);
+}
+
+/**
+ * The read under the caret: the longest text that covers it, in the innermost element holding all of
+ * it. A rich message runs across its elements, so it wins over a shorter text inside one of them.
+ * Without a caret (over an input, or padding) an element's whole text, or the target's readable
+ * attribute, must equal a read.
+ */
+export function keyAt(target: Element, caret: Caret | undefined, reads: Reads): Hit | undefined {
+  let best: Hit | undefined;
+  for (let el: Element | null = target; el !== null; el = el.parentElement) {
+    const text = el.textContent ?? '';
+    const at = caret === undefined ? undefined : offsetIn(el, caret);
+    for (const [said, seen] of reads) {
+      if (said.length <= (best?.text.length ?? 0)) continue;
+      if (at === undefined ? text.trim() === said.trim() : covers(text, said, at))
+        best = { text: said, read: seen[0]!, others: seen.length - 1, element: el };
+    }
+    if (best !== undefined || el !== target) continue;
+    for (const name of ATTRIBUTES) {
+      const value = el.getAttribute(name);
+      const seen = value === null ? undefined : reads.get(value);
+      if (value !== null && seen !== undefined) return { text: value, read: seen[0]!, others: seen.length - 1, element: el };
+    }
+  }
+  return best;
+}
+
+/** Whether an occurrence of `said` in `text` holds the character at `at`. */
+function covers(text: string, said: string, at: number): boolean {
+  const start = text.indexOf(said, Math.max(0, at - said.length + 1));
+  return start !== -1 && start <= at;
+}
+
+/** The caret's index in the element's text, or nothing when the caret is outside it. */
+function offsetIn(el: Element, caret: Caret): number | undefined {
+  if (caret.node.nodeType !== Node.TEXT_NODE || !el.contains(caret.node)) return undefined;
+  const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  let offset = 0;
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    if (node === caret.node) return offset + caret.offset;
+    offset += node.textContent?.length ?? 0;
+  }
+  return undefined;
+}
+
+/** The character under a point on screen, where the browser can say. */
+export function caretAt(x: number, y: number): Caret | undefined {
+  if (typeof document.caretPositionFromPoint !== 'function') return undefined;
+  const position = document.caretPositionFromPoint(x, y);
+  if (position === null) return undefined;
+  const { offsetNode: node, offset } = position;
+  // A caret position sits between two characters, and where one string ends the next may begin: take
+  // the character the pointer is over, or the one before (past the end of a line, in padding).
+  if (node.nodeType !== Node.TEXT_NODE || offset === 0) return { node, offset };
+  const range = document.createRange();
+  range.setStart(node, offset);
+  range.setEnd(node, Math.min(offset + 1, node.textContent?.length ?? 0));
+  const r = range.getBoundingClientRect();
+  const over = !range.collapsed && x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+  return { node, offset: over ? offset : offset - 1 };
+}
+
+export interface InspectorOptions {
+  /** The dev server's base URL, ending in `/`. */
+  base: string;
+}
+
+/** Starts listening for reads and for Alt on the page. Called by the module the Vite plugin serves. */
+export function install({ base }: InspectorOptions): void {
+  const reads: Reads = new Map();
+  (globalThis as DevHooks).__PROSEBOOK_READ__ = (key, text, locale) => record(reads, key, text, locale);
+
+  const box = document.createElement('div');
+  const label = document.createElement('div');
+  box.append(label);
+  Object.assign(box.style, {
+    position: 'fixed',
+    display: 'none',
+    zIndex: '2147483647',
+    pointerEvents: 'none',
+    boxSizing: 'border-box',
+    outline: '2px solid #7c3aed',
+    background: 'rgb(124 58 237 / 0.08)',
+  });
+  Object.assign(label.style, {
+    position: 'absolute',
+    left: '-2px',
+    padding: '1px 6px',
+    font: '12px/1.5 ui-monospace, monospace',
+    whiteSpace: 'nowrap',
+    color: '#fff',
+    background: '#7c3aed',
+  });
+
+  let pointer: { x: number; y: number } | undefined;
+  let frame = 0;
+
+  const hitAt = (x: number, y: number) => {
+    const target = document.elementFromPoint(x, y);
+    return target === null ? undefined : keyAt(target, caretAt(x, y), reads);
+  };
+  const hide = () => {
+    box.style.display = 'none';
+  };
+  const show = () => {
+    frame = 0;
+    const hit = pointer === undefined ? undefined : hitAt(pointer.x, pointer.y);
+    if (hit === undefined) return hide();
+    const r = hit.element.getBoundingClientRect();
+    Object.assign(box.style, { display: 'block', left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px` });
+    // Below the box when there is no room above it.
+    Object.assign(label.style, r.top < 24 ? { top: '100%', bottom: '' } : { top: '', bottom: '100%' });
+    label.textContent = `${hit.read.key} · ${hit.read.locale}${hit.others > 0 ? ` (+${hit.others} with this text)` : ''}`;
+    if (!box.isConnected) document.body.append(box);
+  };
+  const update = (e: MouseEvent | KeyboardEvent) => {
+    if (!e.altKey) return hide();
+    if (frame === 0) frame = requestAnimationFrame(show);
+  };
+
+  window.addEventListener(
+    'mousemove',
+    (e) => {
+      pointer = { x: e.clientX, y: e.clientY };
+      update(e);
+    },
+    { capture: true, passive: true },
+  );
+  window.addEventListener('keydown', update, true);
+  window.addEventListener('keyup', update, true);
+  window.addEventListener('blur', hide);
+  // Alt-click on a link would otherwise download it, and on a field focus it.
+  window.addEventListener(
+    'mousedown',
+    (e) => {
+      if (e.altKey && hitAt(e.clientX, e.clientY) !== undefined) e.preventDefault();
+    },
+    true,
+  );
+  window.addEventListener(
+    'click',
+    (e) => {
+      if (!e.altKey) return;
+      const hit = hitAt(e.clientX, e.clientY);
+      if (hit === undefined) return;
+      e.preventDefault();
+      e.stopPropagation();
+      void open(base, hit.read, e.shiftKey);
+    },
+    true,
+  );
+  window.addEventListener(
+    'contextmenu',
+    (e) => {
+      if (!e.altKey) return;
+      const hit = hitAt(e.clientX, e.clientY);
+      if (hit === undefined) return;
+      e.preventDefault();
+      e.stopPropagation();
+      hide();
+      const catalog = e.shiftKey;
+      void openDialog({
+        base,
+        key: hit.read.key,
+        locale: catalog ? undefined : hit.read.locale,
+        x: e.clientX,
+        y: e.clientY,
+        openFile: () => void open(base, hit.read, catalog),
+      });
+    },
+    true,
+  );
+}
+
+async function open(base: string, read: Read, catalog: boolean): Promise<void> {
+  const query = new URLSearchParams({ key: read.key, locale: read.locale });
+  if (catalog) query.set('catalog', '');
+  const res = await fetch(`${base}__prosebook/open?${query}`);
+  if (!res.ok) console.warn(`prosebook: ${await res.text()}`);
+}

package/src/react/index.tsx

@@ -0,0 +1,112 @@
+/**
+ * `prosebook/react`: the catalog in components.
+ *
+ * `useCopy()` re-renders its component when the locale changes, and its `rich` returns a ready
+ * `ReactNode`: elements are keyed and tag functions receive keyed children, so a sentence with a
+ * link inside it is one catalog entry and one call, with no wrapper to remember.
+ */
+import { createContext, Fragment, isValidElement, use, useMemo, useSyncExternalStore, type ReactNode } from 'react';
+
+import type { Copy } from '#src/runtime/copy.ts';
+import type { MessageShape, RegisteredLocale, RegisteredMessages, RichKey, RichParam, TagFn } from '#src/runtime/types.ts';
+
+type M = RegisteredMessages;
+type L = RegisteredLocale;
+
+/** `Copy`, with `rich` returning a `ReactNode`. */
+export interface ReactCopy extends Omit<Copy<M, L>, 'rich'> {
+  rich<K extends RichKey<M>>(this: void, key: K, ...values: RichParam<M[K], ReactNode>): ReactNode;
+}
+
+const CopyContext = createContext<{ copy: Copy<M, L>; tags: Tags } | null>(null);
+
+type Tags = { readonly [tag: string]: TagFn<ReactNode> };
+
+export interface CopyProviderProps {
+  copy: Copy<M, L> | Copy;
+  /** Tag renderers every rich read under this provider gets, beside the copy's own. */
+  tags?: Tags;
+  children?: ReactNode;
+}
+
+export function CopyProvider({ copy, tags, children }: CopyProviderProps) {
+  const value = useMemo(() => ({ copy: copy as Copy<M, L>, tags: { ...(copy.tags as unknown as Tags), ...tags } }), [copy, tags]);
+  return <CopyContext value={value}>{children}</CopyContext>;
+}
+
+/** The catalog, in the current locale. Re-renders the component when the locale changes, or in dev the catalog. */
+export function useCopy(): ReactCopy {
+  const context = use(CopyContext);
+  if (context === null) throw new Error('prosebook: useCopy() needs a <CopyProvider> above it');
+  const { copy, tags } = context;
+  const version = useSyncExternalStore(
+    copy.subscribe,
+    () => copy.version,
+    () => copy.version,
+  );
+  return useMemo(() => readerFor(copy, tags, version), [copy, tags, version]);
+}
+
+/** The current locale alone, for components that only format or switch. */
+export function useLocale(): L {
+  const context = use(CopyContext);
+  if (context === null) throw new Error('prosebook: useLocale() needs a <CopyProvider> above it');
+  return useSyncExternalStore(
+    context.copy.subscribe,
+    () => context.copy.locale,
+    () => context.copy.locale,
+  );
+}
+
+// Takes the version only so the reader is rebuilt, and its identity changes, when what it reads does.
+function readerFor(copy: Copy<M, L>, tags: Tags, version: number): ReactCopy {
+  return {
+    locale: copy.locale,
+    version,
+    locales: copy.locales,
+    source: copy.source,
+    tags: copy.tags,
+    ready: copy.ready,
+    t: copy.t,
+    has: copy.has,
+    setLocale: copy.setLocale,
+    subscribe: copy.subscribe,
+    number: copy.number,
+    date: copy.date,
+    list: copy.list,
+    relative: copy.relative,
+    rich(key, ...values) {
+      const given = (values[0] ?? {}) as Record<string, unknown>;
+      const merged: Record<string, unknown> = { ...tags, ...given };
+      for (const [name, value] of Object.entries(merged))
+        if (typeof value === 'function') merged[name] = (chunks: unknown[]) => (value as TagFn<ReactNode>)(keyed(chunks));
+
+      return <>{keyed(copy.rich(key as never, merged as never))}</>;
+    },
+  };
+}
+
+/** Text joined where it can be, and each element under its own key, so React never warns about a list. */
+function keyed(parts: unknown[]): (string | ReactNode)[] {
+  if (parts.every((p) => typeof p === 'string')) return [parts.join('')];
+  return parts.map((p, i) =>
+    // oxlint-disable-next-line react/no-array-index-key -- the parts of one message never reorder, so positions are stable keys
+    isValidElement(p) || typeof p === 'object' ? <Fragment key={i}>{p as ReactNode}</Fragment> : (p as ReactNode),
+  );
+}
+
+type ValuesProp<S extends MessageShape> = {} extends S['args'] & { [T in S['tags']]: unknown }
+  ? { values?: S['args'] & { [T in S['tags']]?: TagFn<ReactNode> } }
+  : { values: RichParam<S, ReactNode>[0] };
+
+export type TextProps<K extends Extract<keyof M, string>> = { id: K } & ValuesProp<M[K]>;
+
+/**
+ * A message as an element: `<Text id="cart.items" values={{ count }} />`. Rich messages render their
+ * tags through the provider's renderers and any given in `values`.
+ */
+export function Text<K extends Extract<keyof M, string>>(props: TextProps<K>) {
+  const copy = useCopy();
+  const values = (props as { values?: object }).values;
+  return <>{copy.rich(props.id as RichKey<M>, values)}</>;
+}

package/src/runtime/copy.ts

@@ -0,0 +1,221 @@
+import { createHelpers, flatten } from './helpers.ts';
+import { chainOf, negotiate } from './locale.ts';
+import type {
+  AnyTagFn,
+  ArgsParam,
+  Chunks,
+  Compiled,
+  CompiledMessages,
+  Helpers,
+  DevHooks,
+  MessageShapes,
+  RichKey,
+  RichParam,
+  Values,
+} from './types.ts';
+
+type Loader = () => Promise<{ default: CompiledMessages }>;
+
+/** A generated catalog: which locales exist, which ship in the bundle and how to fetch the rest. */
+export interface Catalog<M extends MessageShapes = MessageShapes, L extends string = string> {
+  /** The locale the catalog is written in, which every other falls back to. */
+  readonly source: L;
+  readonly locales: readonly L[];
+  /** Locales whose messages ship in the bundle. Always holds the source. */
+  readonly messages: { readonly [locale in L]?: CompiledMessages };
+  /** Locales fetched when first asked for. */
+  readonly loaders: { readonly [locale in L]?: Loader };
+  /** Type-only: carries the message shapes from the generated module to `createCopy`. */
+  readonly '~messages'?: M;
+}
+
+/** Ties a generated catalog to its message shapes. Called by generated code. */
+export function defineCatalog<M extends MessageShapes, L extends string = string>(
+  catalog: Omit<Catalog<M, L>, '~messages'>,
+): Catalog<M, L> {
+  return catalog;
+}
+
+export interface CopyOptions<L extends string> {
+  /** The locale to start in, or the locales a reader prefers, most preferred first. Defaults to the source. */
+  locale?: L | (string & {}) | readonly string[];
+  /** Tag renderers every rich read gets unless it supplies its own, such as `b` or `link`. */
+  tags?: { [tag: string]: AnyTagFn };
+  /** What a key the catalog lacks reads as. Defaults to the key itself. */
+  onMissing?: (key: string, locale: L) => string;
+}
+
+/** Its methods don't use `this`, so they can be passed around and destructured: `const { t } = copy`. */
+export interface Copy<M extends MessageShapes = MessageShapes, L extends string = string> {
+  /** The locale messages are coming back in. */
+  readonly locale: L;
+  readonly locales: readonly L[];
+  readonly source: L;
+  /** The tag renderers rich reads fall back to, from `CopyOptions.tags`. */
+  readonly tags: { readonly [tag: string]: AnyTagFn };
+  /** Settles once the starting locale's messages are loaded. */
+  readonly ready: Promise<void>;
+  /** A message as plain text. Tags render as the text they wrap. */
+  t<K extends keyof M & string>(this: void, key: K, ...args: ArgsParam<M[K]>): string;
+  /** A message with elements inside it: each tag's function turns what it wraps into a node. */
+  rich<K extends RichKey<M>, N = unknown>(this: void, key: K, ...values: RichParam<M[K], N>): Chunks<N>;
+  has(this: void, key: string): key is keyof M & string;
+  /** Switches locale once its messages (and its fallbacks') are loaded. */
+  setLocale(this: void, next: L | (string & {}) | readonly string[]): Promise<void>;
+  /** Counts changes to what messages read as: each locale switch, and each catalog edit in dev. */
+  readonly version: number;
+  /** Called after each locale switch, and in dev after each catalog edit. Returns the unsubscribe. */
+  subscribe(this: void, listener: () => void): () => void;
+  /** Formats a number in the current locale. */
+  number(this: void, value: number | bigint, options?: Intl.NumberFormatOptions): string;
+  /** Formats a date in the current locale. */
+  date(this: void, value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+  /** Joins items as a list in the current locale: `a, b and c`. */
+  list(this: void, items: Iterable<string>, options?: Intl.ListFormatOptions): string;
+  /** `in 3 days`, `2 hours ago`, in the current locale. */
+  relative(this: void, value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+}
+
+type Layer = { messages: CompiledMessages; h: Helpers };
+
+/** A message as the text it puts on screen: rendered again with its tags left as their text. */
+function textOf(message: Compiled, values: Values, h: Helpers): string {
+  if (typeof message === 'string') return message;
+  const plain = Object.fromEntries(Object.entries(values).filter(([, v]) => typeof v !== 'function'));
+  return flatten(message(plain, h)).join('');
+}
+
+/** A catalog reader with a current locale. Create one per app, or one per request on a server. */
+export function createCopy<M extends MessageShapes, L extends string>(catalog: Catalog<M, L>, options: CopyOptions<L> = {}): Copy<M, L> {
+  const loaded = new Map<L, Layer>();
+  const pending = new Map<L, Promise<Layer>>();
+  const listeners = new Set<() => void>();
+  const defaultTags = options.tags ?? {};
+  const formatters = new Map<string, Intl.NumberFormat | Intl.DateTimeFormat | Intl.ListFormat | Intl.RelativeTimeFormat>();
+
+  for (const [locale, messages] of Object.entries(catalog.messages) as [L, CompiledMessages][])
+    loaded.set(locale, { messages, h: createHelpers(locale) });
+
+  let locale = catalog.source;
+  let chain: Layer[] = layers(chainOf(locale, catalog.locales, catalog.source));
+  let latest = 0;
+  let version = 0;
+
+  function changed() {
+    version++;
+    for (const listener of listeners) listener();
+  }
+
+  // A layer's messages are swapped in place, so the chain that holds it reads the new ones.
+  (globalThis as DevHooks).__PROSEBOOK_HOT__?.add((l, messages) => {
+    const layer = loaded.get(l as L);
+    if (layer === undefined) return;
+    layer.messages = messages;
+    changed();
+  });
+
+  function layers(locales: L[]): Layer[] {
+    return locales.flatMap((l) => loaded.get(l) ?? []);
+  }
+
+  function load(l: L): Promise<Layer> {
+    const done = loaded.get(l);
+    if (done) return Promise.resolve(done);
+    let p = pending.get(l);
+    if (p === undefined) {
+      // oxlint-disable-next-line typescript/no-unsafe-enum-assignment -- `L` is a string union, not an enum; the rule misreads the mapped type
+      const loader = catalog.loaders[l];
+      if (loader === undefined) return Promise.reject(new Error(`prosebook: no messages for locale "${l}"`));
+      p = loader().then((mod) => {
+        const layer = { messages: mod.default, h: createHelpers(l) };
+        loaded.set(l, layer);
+        pending.delete(l);
+        return layer;
+      });
+      p.catch(() => pending.delete(l));
+      pending.set(l, p);
+    }
+    return p;
+  }
+
+  async function setLocale(next: L | (string & {}) | readonly string[]): Promise<void> {
+    const target = negotiate(next, catalog.locales, catalog.source);
+    const ticket = ++latest;
+    const locales = chainOf(target, catalog.locales, catalog.source);
+    await Promise.all(locales.map(load));
+    // A slower load must not undo a later switch.
+    if (ticket !== latest || target === locale) return;
+    locale = target;
+    chain = layers(locales);
+    formatters.clear();
+    changed();
+  }
+
+  function find(key: string): [Compiled, Helpers] | undefined {
+    for (const layer of chain) {
+      const message = layer.messages[key];
+      if (message !== undefined) return [message, layer.h];
+    }
+    return undefined;
+  }
+
+  function render(key: string, values: Values): unknown {
+    const found = find(key);
+    if (found === undefined) return options.onMissing ? options.onMissing(key, locale) : key;
+    const [message, h] = found;
+    const out = typeof message === 'string' ? message : message(values, h);
+    const read = (globalThis as DevHooks).__PROSEBOOK_READ__;
+    if (read !== undefined) read(key, typeof out === 'string' ? out : textOf(message, values, h), h.locale);
+    return out;
+  }
+
+  function formatter<F>(kind: string, options: object | undefined, make: () => F): F {
+    const id = `${kind}${JSON.stringify(options ?? {})}`;
+    let made = formatters.get(id) as F | undefined;
+    if (made === undefined) formatters.set(id, (made = make()) as never);
+    return made;
+  }
+
+  const ready = options.locale === undefined ? Promise.resolve() : setLocale(options.locale);
+
+  return {
+    get locale() {
+      return locale;
+    },
+    get version() {
+      return version;
+    },
+    locales: catalog.locales,
+    source: catalog.source,
+    tags: defaultTags,
+    ready,
+    t(key, ...args) {
+      const out = render(key, (args[0] as Values | undefined) ?? {});
+      return typeof out === 'string' ? out : flatten(out).join('');
+    },
+    rich(key, ...values) {
+      const out = render(key, { ...defaultTags, ...(values[0] as Values | undefined) });
+      return flatten(out) as Chunks<never>;
+    },
+    has(key): key is keyof M & string {
+      return find(key) !== undefined;
+    },
+    setLocale,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    number(value, opts) {
+      return formatter('n', opts, () => new Intl.NumberFormat(locale, opts)).format(value);
+    },
+    date(value, opts) {
+      return formatter('d', opts, () => new Intl.DateTimeFormat(locale, opts)).format(value);
+    },
+    list(items, opts) {
+      return formatter('l', opts, () => new Intl.ListFormat(locale, opts)).format(items);
+    },
+    relative(value, unit, opts) {
+      return formatter('r', opts, () => new Intl.RelativeTimeFormat(locale, opts)).format(value, unit);
+    },
+  };
+}

package/src/runtime/helpers.ts

@@ -0,0 +1,66 @@
+import type { Arms, Helpers, Values } from './types.ts';
+
+/**
+ * The helpers compiled messages call, for one locale. Formatters are built once per options object:
+ * the generator hoists each message's options to a module-level constant, so identity is a stable key.
+ */
+export function createHelpers(locale: string): Helpers {
+  const numbers = new Map<Intl.NumberFormatOptions | undefined, Intl.NumberFormat>();
+  const dates = new Map<Intl.DateTimeFormatOptions | undefined, Intl.DateTimeFormat>();
+  let cardinal: Intl.PluralRules | undefined;
+  let ordinal: Intl.PluralRules | undefined;
+
+  return {
+    locale,
+    n(value, options) {
+      let format = numbers.get(options);
+      if (format === undefined) numbers.set(options, (format = new Intl.NumberFormat(locale, options)));
+      return format.format(value);
+    },
+    d(value, options) {
+      let format = dates.get(options);
+      if (format === undefined) dates.set(options, (format = new Intl.DateTimeFormat(locale, options)));
+      return format.format(value);
+    },
+    p(value, offset, isOrdinal, arms) {
+      const exact = arms[`=${value}`];
+      if (exact !== undefined) return exact();
+      const rules = isOrdinal
+        ? (ordinal ??= new Intl.PluralRules(locale, { type: 'ordinal' }))
+        : (cardinal ??= new Intl.PluralRules(locale));
+      return pick(arms, rules.select(value - offset));
+    },
+    s(value, arms) {
+      return pick(arms, String(value));
+    },
+    t(values: Values, tag, children) {
+      const render = values[tag];
+      return typeof render === 'function' ? (render as (chunks: unknown[]) => unknown)(flatten(children)) : children;
+    },
+  };
+}
+
+function pick(arms: Arms, arm: string): unknown {
+  // ICU requires an `other` arm, and the generator refuses a message without one.
+  return (Object.hasOwn(arms, arm) ? arms[arm]! : arms['other']!)();
+}
+
+/**
+ * A compiled message's output as a flat list: nested arrays opened, adjacent text joined, and
+ * `null`, `undefined` and booleans dropped, as React drops them.
+ */
+export function flatten(output: unknown): unknown[] {
+  const out: unknown[] = [];
+  const walk = (part: unknown) => {
+    if (Array.isArray(part)) {
+      for (const p of part) walk(p);
+      return;
+    }
+    if (part === null || part === undefined || typeof part === 'boolean') return;
+    if (typeof part === 'number' || typeof part === 'bigint') part = String(part);
+    if (typeof part === 'string' && typeof out.at(-1) === 'string') out[out.length - 1] += part;
+    else out.push(part);
+  };
+  walk(output);
+  return out;
+}

package/src/runtime/locale.ts

@@ -0,0 +1,49 @@
+/**
+ * Picks the best available locale for what was asked, in the order it was asked.
+ *
+ * Each requested tag tries an exact match, then its parents (`pt-BR` finds `pt`), then any locale
+ * of the same language (`pt` finds `pt-BR`). Matching ignores case, as BCP 47 does.
+ */
+export function negotiate<L extends string>(requested: string | readonly string[], available: readonly L[], fallback: L): L {
+  const find = (tag: string) => available.find((a) => a.toLowerCase() === tag.toLowerCase());
+  for (const want of typeof requested === 'string' ? [requested] : requested) {
+    let tag = want;
+    for (;;) {
+      const found = find(tag);
+      if (found !== undefined) return found;
+      const cut = tag.lastIndexOf('-');
+      if (cut < 0) break;
+      tag = tag.slice(0, cut);
+    }
+    const language = languageOf(want);
+    const sibling = available.find((a) => languageOf(a) === language);
+    if (sibling !== undefined) return sibling;
+  }
+  return fallback;
+}
+
+/** The locales a message is looked up in, in order: the locale, its available parents, then the source. */
+export function chainOf<L extends string>(locale: L, available: readonly L[], source: L): L[] {
+  const chain: L[] = [locale];
+  let tag: string = locale;
+  while (tag.includes('-')) {
+    tag = tag.slice(0, tag.lastIndexOf('-'));
+    const parent = available.find((a) => a.toLowerCase() === tag.toLowerCase());
+    if (parent !== undefined && !chain.includes(parent)) chain.push(parent);
+  }
+  if (!chain.includes(source)) chain.push(source);
+  return chain;
+}
+
+/** The locales the browser or the environment asks for, most preferred first. */
+export function preferredLocales(): string[] {
+  const nav = (globalThis as { navigator?: { languages?: readonly string[]; language?: string } }).navigator;
+  if (nav?.languages && nav.languages.length > 0) return [...nav.languages];
+  if (nav?.language) return [nav.language];
+  const resolved = Intl.DateTimeFormat().resolvedOptions().locale;
+  return resolved ? [resolved] : [];
+}
+
+function languageOf(tag: string): string {
+  return tag.split('-', 1)[0]!.toLowerCase();
+}