prosebook 0.0.1 → 0.2.0

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();
+}

package/src/runtime/types.ts

@@ -0,0 +1,106 @@
+/**
+ * The shapes the generated catalog and the runtime agree on.
+ *
+ * A catalog is compiled at build time: every ICU message becomes either a string (no placeholders)
+ * or a small function over its arguments and a set of locale-bound helpers. The runtime never parses
+ * ICU, so it carries no parser, needs no `eval`, and a message costs a property read or one call.
+ */
+
+/** What the generator knows about one message: the arguments it takes and the tags it wraps text in. */
+export interface MessageShape {
+  args: object;
+  tags: string;
+}
+
+/** Every key of a catalog, mapped to its shape. The generated `Messages` interface is one of these. */
+export type MessageShapes = { [key: string]: MessageShape };
+
+/**
+ * Augmented by the generated module, so hooks and components that are not handed a catalog
+ * (`useCopy()`, `<Text>`) still know its keys:
+ *
+ * ```ts
+ * declare module 'prosebook' {
+ *   interface Register { messages: Messages; locale: Locale }
+ * }
+ * ```
+ *
+ * Add `tags: 'b' | 'link'` to say which tags the provider renders by default, so a call site
+ * needs to supply only the others.
+ */
+// oxlint-disable-next-line typescript/no-empty-interface -- filled in by declaration merging
+export interface Register {}
+
+export type RegisteredMessages = Register extends { messages: infer M extends MessageShapes } ? M : MessageShapes;
+export type RegisteredLocale = Register extends { locale: infer L extends string } ? L : string;
+/** Tags the provider renders unless a call site says otherwise. */
+export type DefaultTags = Register extends { tags: infer T extends string } ? T : never;
+
+/**
+ * The helpers a compiled message calls, bound to the locale its words are in. Names are one letter
+ * because they appear once per placeholder in every generated module.
+ */
+export interface Helpers {
+  readonly locale: string;
+  /** `{x, number, …}` and the `#` of a plural. */
+  n(value: number, options?: Intl.NumberFormatOptions): string;
+  /** `{x, date, …}` and `{x, time, …}`. */
+  d(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+  /** `{x, plural, …}` and `{x, selectordinal, …}`: picks an arm and renders it. */
+  p(value: number, offset: number, ordinal: boolean, arms: Arms): unknown;
+  /** `{x, select, …}`. */
+  s(value: unknown, arms: Arms): unknown;
+  /** `<tag>…</tag>`: the tag's function from the values, or the bare children when there is none. */
+  t(values: Values, tag: string, children: unknown): unknown;
+}
+
+export type Arms = { [arm: string]: () => unknown };
+// `any`, not `unknown`: call sites are checked against the generated `Messages`, so a compiled
+// message can hand its arguments to the helpers without a cast per placeholder.
+// oxlint-disable-next-line typescript/no-explicit-any
+export type Values = { readonly [name: string]: any };
+
+/**
+ * Told of every message read: its key, the text it came to and the locale it was found in, which is
+ * the fallback's when the current locale lacks it. The Vite plugin's dev inspector sets one on
+ * `globalThis` to map text on screen back to keys; nothing sets it in a build.
+ */
+export type ReadHook = (key: string, text: string, locale: string) => void;
+
+/** Hands a copy a locale's messages, regenerated after a catalog edit, in place of the ones it loaded. */
+export type HotHook = (locale: string, messages: CompiledMessages) => void;
+
+/**
+ * What the Vite plugin sets on `globalThis` in dev. `__PROSEBOOK_HOT__` is there before the app runs,
+ * so each copy adds itself, and the generated modules call every copy when they are updated.
+ */
+export type DevHooks = { __PROSEBOOK_READ__?: ReadHook; __PROSEBOOK_HOT__?: Set<HotHook> };
+
+/** One compiled message. */
+export type Compiled = string | ((values: Values, h: Helpers) => unknown);
+
+/** One locale's compiled messages: what a generated `<locale>.ts` module exports by default. */
+export type CompiledMessages = { readonly [key: string]: Compiled };
+
+/** What a tag's function receives: the pieces it wraps, adjacent text already joined. */
+export type Chunks<N> = (string | N)[];
+export type TagFn<N> = (chunks: Chunks<N>) => N;
+/** A tag renderer for any kind of node, as configured once on a `Copy`. */
+export type AnyTagFn = (chunks: never) => unknown;
+
+type NoArgs<T> = {} extends T ? true : false;
+
+/** The arguments of a plain read: optional when the message takes none. */
+export type ArgsParam<S extends MessageShape> = NoArgs<S['args']> extends true ? [args?: S['args']] : [args: S['args']];
+
+type TagValues<S extends MessageShape, N> = { [T in Exclude<S['tags'], DefaultTags>]: TagFn<N> } & {
+  [T in Extract<S['tags'], DefaultTags>]?: TagFn<N>;
+};
+
+/** A rich read takes the message's arguments and a function per tag it wraps, beside the defaults. */
+export type RichValues<S extends MessageShape, N> = S['args'] & TagValues<S, N>;
+export type RichParam<S extends MessageShape, N> =
+  NoArgs<RichValues<S, N>> extends true ? [values?: RichValues<S, N>] : [values: RichValues<S, N>];
+
+/** The keys whose message wraps part of itself in a tag. */
+export type RichKey<M extends MessageShapes> = { [K in keyof M]: [M[K]['tags']] extends [never] ? never : K }[keyof M] & string;