prosebook 0.3.0 → 0.5.0

package/src/react/index.tsx

@@ -7,16 +7,14 @@
  */
 import { createContext, Fragment, isValidElement, use, useMemo, useSyncExternalStore, type ReactNode } from 'react';
 
+import { bindCopy, type BoundCopy, type TextProps as Props } from '#src/runtime/bind.ts';
 import type { Copy } from '#src/runtime/copy.ts';
-import type { MessageShape, RegisteredLocale, RegisteredMessages, RichKey, RichParam, TagFn } from '#src/runtime/types.ts';
+import type { RegisteredLocale, RegisteredMessages, TagFn } from '#src/runtime/types.ts';
 
 type M = RegisteredMessages;
-type L = RegisteredLocale;
 
 /** `Copy`, with `rich` returning a `ReactNode`. */
-export interface ReactCopy extends Omit<Copy, 'rich'> {
-  rich<K extends RichKey<M>>(this: void, key: K, ...values: RichParam<M[K], ReactNode>): ReactNode;
-}
+export type ReactCopy = BoundCopy<ReactNode>;
 
 const CopyContext = createContext<{ copy: Copy; tags: Tags } | null>(null);
 
@@ -29,8 +27,8 @@ export interface CopyProviderProps {
   children?: ReactNode;
 }
 
-export function CopyProvider({ copy, tags, children }: CopyProviderProps) {
-  const value = useMemo(() => ({ copy: copy, tags: { ...(copy.tags as unknown as Tags), ...tags } }), [copy, tags]);
+export function CopyProvider({ copy, tags = {}, children }: CopyProviderProps) {
+  const value = useMemo(() => ({ copy, tags }), [copy, tags]);
   return <CopyContext value={value}>{children}</CopyContext>;
 }
 
@@ -44,11 +42,12 @@ export function useCopy(): ReactCopy {
     () => copy.version,
     () => copy.version,
   );
-  return useMemo(() => readerFor(copy, tags, version), [copy, tags, version]);
+  // Rebuilt on each version, so its identity changes when what it reads does.
+  return useMemo(() => bindCopy(copy, tags, { tag, whole }), [copy, tags, version]);
 }
 
 /** The current locale alone, for components that only format or switch. */
-export function useLocale(): L {
+export function useLocale(): RegisteredLocale {
   const context = use(CopyContext);
   if (context === null) throw new Error('prosebook: useLocale() needs a <CopyProvider> above it');
   return useSyncExternalStore(
@@ -58,33 +57,8 @@ export function useLocale(): L {
   );
 }
 
-// Takes the version only so the reader is rebuilt, and its identity changes, when what it reads does.
-function readerFor(copy: Copy, 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))}</>;
-    },
-  };
-}
+const tag = (render: (chunks: never) => unknown, chunks: unknown[]) => render(keyed(chunks) as never);
+const whole = (parts: unknown[]): ReactNode => <>{keyed(parts)}</>;
 
 /** 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)[] {
@@ -95,11 +69,7 @@ function keyed(parts: unknown[]): (string | 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]>;
+export type TextProps<K extends Extract<keyof M, string>> = Props<K, ReactNode>;
 
 /**
  * A message as an element: `<Text id="cart.items" values={{ count }} />`. Rich messages render their
@@ -108,5 +78,5 @@ export type TextProps<K extends Extract<keyof M, string>> = { id: K } & ValuesPr
 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, values as never)}</>;
+  return <>{copy.rich(props.id as never, values as never)}</>;
 }

package/src/runtime/bind.ts

@@ -0,0 +1,96 @@
+/**
+ * What every framework binding shares: a copy read through the framework's reactivity, with a
+ * provider's tag renderers under each rich read's own.
+ */
+import type { Copy } from './copy.ts';
+import type { MessageShape, RegisteredLocale, RegisteredMessages, RichKey, RichParam, TagFn } from './types.ts';
+
+type M = RegisteredMessages;
+
+/**
+ * `Copy`, with `rich` returning `R`, a node of the framework's, whose tag renderers make `N`s. The locale is
+ * a parameter so it survives a lint that, where no catalog is registered, sees `RegisteredLocale` as the default.
+ */
+export interface BoundCopy<N, R = N, L extends string = RegisteredLocale> extends Omit<Copy<M, L>, 'rich'> {
+  rich<K extends RichKey<M>>(this: void, key: K, ...values: RichParam<M[K], N>): R;
+}
+
+export type Tags = { readonly [tag: string]: (chunks: never) => unknown };
+
+export interface Binding<R> {
+  /** Called on every read, so the framework knows the reader depends on the copy's version. */
+  track?: () => void;
+  /** What a tag's renderer is turned into, given what it wraps. Calls it by default. */
+  tag?: (render: (chunks: never) => unknown, chunks: unknown[]) => unknown;
+  /** What a rich read returns, given its parts. */
+  whole: (parts: unknown[]) => R;
+}
+
+/** A reader of `copy` whose reads go through `track`, and whose rich reads get `tags` unless they give their own. */
+export function bindCopy<N, R>(copy: Copy, tags: Tags, { track = () => {}, tag, whole }: Binding<R>): BoundCopy<N, R> {
+  const merged = { ...copy.tags, ...tags };
+  return {
+    get locale() {
+      track();
+      return copy.locale;
+    },
+    get version() {
+      track();
+      return copy.version;
+    },
+    locales: copy.locales,
+    source: copy.source,
+    tags: copy.tags,
+    ready: copy.ready,
+    t(key, ...args) {
+      track();
+      return copy.t(key, ...args);
+    },
+    has(key): key is keyof M & string {
+      track();
+      return copy.has(key);
+    },
+    setLocale: copy.setLocale,
+    subscribe: copy.subscribe,
+    number(value, options) {
+      track();
+      return copy.number(value, options);
+    },
+    date(value, options) {
+      track();
+      return copy.date(value, options);
+    },
+    list(items, options) {
+      track();
+      return copy.list(items, options);
+    },
+    relative(value, unit, options) {
+      track();
+      return copy.relative(value, unit, options);
+    },
+    rich(key, ...values) {
+      track();
+      const all: Record<string, unknown> = { ...merged, ...(values[0] as object | undefined) };
+      if (tag !== undefined) {
+        for (const [name, value] of Object.entries(all))
+          if (typeof value === 'function') all[name] = (chunks: unknown[]) => tag(value as (chunks: never) => unknown, chunks);
+      }
+      return whole(copy.rich(key, all as never));
+    },
+  };
+}
+
+type NoValues<S extends MessageShape> = {} extends S['args'] & { [T in S['tags']]: unknown } ? true : false;
+
+/**
+ * A `<Text>`'s props where the call site renders every tag the provider doesn't: `values` is needed
+ * once the message takes arguments or wraps text in a tag.
+ */
+export type TextProps<K extends Extract<keyof M, string>, N> = { id: K } & (NoValues<M[K]> extends true
+  ? { values?: M[K]['args'] & { [T in M[K]['tags']]?: TagFn<N> } }
+  : { values: RichParam<M[K], N>[0] });
+
+/** A `<Text>`'s props where tags may come from elsewhere (slots, snippets): `values` holds arguments, and tags if you like. */
+export type LooseTextProps<K extends Extract<keyof M, string>, N> = { id: K } & ({} extends M[K]['args']
+  ? { values?: M[K]['args'] & { [T in M[K]['tags']]?: TagFn<N> } }
+  : { values: M[K]['args'] & { [T in M[K]['tags']]?: TagFn<N> } });

package/src/runtime/copy.ts

@@ -16,6 +16,12 @@ import type {
 
 type Loader = () => Promise<{ default: CompiledMessages }>;
 
+/** Messages that ship in the bundle and loaders for the rest, per locale: a catalog's, or one area's. */
+interface Pieces<L extends string = string> {
+  readonly messages: { readonly [locale in L]?: CompiledMessages };
+  readonly loaders: { readonly [locale in L]?: Loader };
+}
+
 /** 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. */
@@ -25,10 +31,49 @@ export interface Catalog<M extends MessageShapes = MessageShapes, L extends stri
   readonly messages: { readonly [locale in L]?: CompiledMessages };
   /** Locales fetched when first asked for. */
   readonly loaders: { readonly [locale in L]?: Loader };
+  /**
+   * Set when a build splits the catalog by area (the Vite plugin's `split`): `messages` and `loaders`
+   * are empty, and each area adds its own (`addArea`) as the code reading it loads.
+   */
+  readonly split?: { readonly id: string; readonly areas: readonly string[] };
+  /**
+   * Set in a server build whose client is split (the Vite plugin's `split`): the file the browser
+   * loads each area's messages from, per lazy locale, which `CopyOptions.preload` is handed.
+   */
+  readonly areaFiles?: { readonly [area: string]: { readonly [locale in L]?: string } };
   /** Type-only: carries the message shapes from the generated module to `createCopy`. */
   readonly '~messages'?: M;
 }
 
+/** A split catalog's areas, as they load, and each copy's hook for taking a new one in. */
+interface Registry {
+  areas: Map<string, Pieces>;
+  copies: Set<(area: string) => Promise<unknown>>;
+}
+
+// By `split.id`, not by catalog: in dev an edit runs the index again, and an area that loads after it
+// must still reach the copies made from the catalog before.
+const registries = new Map<string, Registry>();
+
+function registry(id: string): Registry {
+  let r = registries.get(id);
+  if (r === undefined) registries.set(id, (r = { areas: new Map(), copies: new Set() }));
+  return r;
+}
+
+/**
+ * Adds an area's messages to a split catalog. Called by generated code, from a module beside the code
+ * that reads the area; settles once every copy holds the area in its locale, so that code's first
+ * render reads it. A locale that fails to load reads in its fallback, and is reported.
+ */
+export async function addArea(id: string, area: string, messages: Pieces['messages'], loaders: Pieces['loaders']): Promise<void> {
+  const r = registry(id);
+  if (r.areas.has(area)) return;
+  r.areas.set(area, { messages, loaders });
+  for (const result of await Promise.allSettled([...r.copies].map((take) => take(area))))
+    if (result.status === 'rejected') console.error(`prosebook: the ${area} area did not load:`, result.reason);
+}
+
 /** 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'>,
@@ -45,9 +90,17 @@ export interface CopyOptions<L extends string> {
   onMissing?: (key: string, locale: L) => string;
   /**
    * Told of a placeholder that had no value, or one `Intl` refused (`currency: 'euro'`): the message
-   * still renders, showing `{name}` there. Defaults to `console.error`.
+   * still renders, showing `{name}` there. In a split build, also of a key read before its area
+   * loaded. Defaults to `console.error`.
    */
   onError?: (error: Error, key: string, locale: L) => void;
+  /**
+   * On a server, handed each file the browser will load for the areas this copy reads, once each,
+   * so the page can link it and the browser fetch it beside the code reading it rather than after:
+   * `(href) => preloadModule(href, { as: 'script' })` under React. Only a catalog built for a split
+   * client has such files (`Catalog.areaFiles`), and only its lazy locales.
+   */
+  preload?: (href: string) => void;
 }
 
 /** Its methods don't use `this`, so they can be passed around and destructured: `const { t } = copy`. */
@@ -81,7 +134,19 @@ export interface Copy<M extends MessageShapes = MessageShapes, L extends string
   relative(this: void, value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
 }
 
-type Layer = { messages: CompiledMessages; h: Helpers };
+/** A locale's messages, from each area loaded in it so far. */
+type Layer = { messages: CompiledMessages; h: Helpers; areas: Set<string> };
+
+/** The one area of a catalog that isn't split. */
+const WHOLE = '';
+
+const areaOf = (key: string) => key.slice(0, key.indexOf('.'));
+
+function pick(messages: CompiledMessages, keep: (key: string) => boolean): CompiledMessages {
+  const out: Record<string, Compiled> = {};
+  for (const key in messages) if (keep(key)) out[key] = messages[key]!;
+  return out;
+}
 
 /** 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 {
@@ -93,24 +158,50 @@ function textOf(message: Compiled, values: Values, h: Helpers): string {
 /** 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 pending = new Map<string, Promise<void>>();
   const listeners = new Set<() => void>();
   const defaultTags = options.tags ?? {};
   const formatters = new Map<string, Intl.NumberFormat | Intl.DateTimeFormat | Intl.ListFormat | Intl.RelativeTimeFormat>();
+  const split = catalog.split === undefined ? undefined : registry(catalog.split.id);
   // The key being rendered, which a helper's report names; none while the inspector renders it again.
   let reading: string | undefined;
+  // The files handed to `preload`, and each area and locale read, which hands on nothing new after.
+  const preloaded = new Set<string>();
+  const report = (error: Error, key: string, l: L) => {
+    if (options.onError) options.onError(error, key, l);
+    else console.error(`prosebook: ${key} in ${l}: ${error.message}`);
+  };
   const helpers = (l: L) =>
     createHelpers(l, (error) => {
-      if (reading === undefined) return;
-      if (options.onError) options.onError(error, reading, l);
-      else console.error(`prosebook: ${reading} in ${l}: ${error.message}`);
+      if (reading !== undefined) report(error, reading, l);
     });
 
-  for (const [locale, messages] of Object.entries(catalog.messages) as [L, CompiledMessages][])
-    loaded.set(locale, { messages, h: helpers(locale) });
+  const areas = () => (split === undefined ? [WHOLE] : [...split.areas.keys()]);
+  const piecesOf = (area: string): Pieces<L> => (area === WHOLE ? catalog : split!.areas.get(area)!);
+
+  function layerOf(l: L): Layer {
+    let layer = loaded.get(l);
+    if (layer === undefined) loaded.set(l, (layer = { messages: {}, h: helpers(l), areas: new Set() }));
+    return layer;
+  }
+
+  function take(l: L, area: string, messages: CompiledMessages) {
+    const layer = layerOf(l);
+    layer.areas.add(area);
+    // In dev an area is handed its locales whole; only the area's own keys are its.
+    layer.messages = area === WHOLE ? messages : { ...layer.messages, ...pick(messages, (key) => areaOf(key) === area) };
+  }
+
+  function takeBundled(area: string) {
+    for (const [l, messages] of Object.entries(piecesOf(area).messages) as [L, CompiledMessages][]) take(l, area, messages);
+  }
+
+  for (const area of areas()) takeBundled(area);
 
   let locale = catalog.source;
   let chain: Layer[] = layers(chainOf(locale, catalog.locales, catalog.source));
+  // The locales the latest switch asked for, which an area arriving during it loads in too.
+  let wanted: L[] = chainOf(locale, catalog.locales, catalog.source);
   let latest = 0;
   let version = 0;
 
@@ -123,30 +214,41 @@ export function createCopy<M extends MessageShapes, L extends string>(catalog: C
   (globalThis as DevHooks).__PROSEBOOK_HOT__?.add((l, messages) => {
     const layer = loaded.get(l as L);
     if (layer === undefined) return;
-    layer.messages = messages;
+    layer.messages = layer.areas.has(WHOLE) ? messages : pick(messages, (key) => layer.areas.has(areaOf(key)));
+    changed();
+  });
+
+  // An area that loads after the copy was made comes in, in the locale shown and the one being switched to.
+  split?.copies.add(async (area) => {
+    takeBundled(area);
+    const locales = new Set([...chainOf(locale, catalog.locales, catalog.source), ...wanted]);
+    await Promise.all([...locales].map((l) => load(l, area)));
     changed();
   });
 
   function layers(locales: L[]): Layer[] {
-    return locales.flatMap((l) => loaded.get(l) ?? []);
+    return locales.map(layerOf);
   }
 
-  function load(l: L): Promise<Layer> {
-    const done = loaded.get(l);
-    if (done) return Promise.resolve(done);
-    let p = pending.get(l);
+  function load(l: L, area: string): Promise<void> {
+    if (loaded.get(l)?.areas.has(area) === true) return Promise.resolve();
+    const id = `${area}/${l}`;
+    let p = pending.get(id);
     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}"`));
+      const loader = piecesOf(area).loaders[l];
+      if (loader === undefined) {
+        if (split === undefined) return Promise.reject(new Error(`prosebook: no messages for locale "${l}"`));
+        // An area with nothing translated in a locale has no loader for it.
+        take(l, area, {});
+        return Promise.resolve();
+      }
       p = loader().then((mod) => {
-        const layer = { messages: mod.default, h: helpers(l) };
-        loaded.set(l, layer);
-        pending.delete(l);
-        return layer;
+        take(l, area, mod.default);
+        pending.delete(id);
       });
-      p.catch(() => pending.delete(l));
-      pending.set(l, p);
+      p.catch(() => pending.delete(id));
+      pending.set(id, p);
     }
     return p;
   }
@@ -155,7 +257,8 @@ export function createCopy<M extends MessageShapes, L extends string>(catalog: C
     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));
+    wanted = locales;
+    await Promise.all(locales.flatMap((l) => areas().map((area) => load(l, area))));
     // A slower load must not undo a later switch.
     if (ticket !== latest || target === locale) return;
     locale = target;
@@ -172,9 +275,30 @@ export function createCopy<M extends MessageShapes, L extends string>(catalog: C
     return undefined;
   }
 
+  function preload(area: string) {
+    const files = catalog.areaFiles?.[area];
+    const read = `${area}/${locale}`;
+    if (files === undefined || options.preload === undefined || preloaded.has(read)) return;
+    preloaded.add(read);
+    for (const l of chainOf(locale, catalog.locales, catalog.source)) {
+      const href = files[l];
+      if (href === undefined || preloaded.has(href)) continue;
+      preloaded.add(href);
+      options.preload(href);
+    }
+  }
+
   function render(key: string, values: Values): unknown {
+    preload(areaOf(key));
     const found = find(key);
-    if (found === undefined) return options.onMissing ? options.onMissing(key, locale) : key;
+    if (found === undefined) {
+      const area = areaOf(key);
+      if (split !== undefined && !split.areas.has(area) && catalog.split!.areas.includes(area)) {
+        const fix = `name one of its keys in the module that reads it, or keep it: \`keep: ['${area}.*']\``;
+        report(new Error(`the ${area} area has not loaded: ${fix}`), key, locale);
+      }
+      return options.onMissing ? options.onMissing(key, locale) : key;
+    }
     const [message, h] = found;
     reading = key;
     let out: unknown;

package/src/solid/index.ts

@@ -0,0 +1,67 @@
+/**
+ * `prosebook/solid`: the catalog in Solid components.
+ *
+ * Every read tracks a signal the copy sets on each change, so JSX that reads a message updates in
+ * place when the locale switches; components never run again. `rich` returns what its tag renderers
+ * made, beside the text, ready to put in JSX. Written without JSX, so it needs no Solid compiler.
+ */
+import { createComponent, createContext, createMemo, createSignal, onCleanup, useContext, type Accessor, type JSX } from 'solid-js';
+
+import { bindCopy, type BoundCopy, type TextProps as Props } from '#src/runtime/bind.ts';
+import type { Copy } from '#src/runtime/copy.ts';
+import type { RegisteredLocale, RegisteredMessages, TagFn } from '#src/runtime/types.ts';
+
+type M = RegisteredMessages;
+
+/** `Copy`, with `rich` returning a `JSX.Element`, whose reads are tracked. */
+export type SolidCopy = BoundCopy<JSX.Element>;
+
+type Tags = { readonly [tag: string]: TagFn<JSX.Element> };
+
+const CopyContext = createContext<SolidCopy>();
+
+export interface CopyProviderProps {
+  /** Read once: give a provider a new key to change the copy under it. */
+  copy: Copy;
+  /** Tag renderers every rich read under this provider gets, beside the copy's own. */
+  tags?: Tags;
+  children?: JSX.Element;
+}
+
+export function CopyProvider(props: CopyProviderProps): JSX.Element {
+  const { copy, tags = {} } = props;
+  const [version, setVersion] = createSignal(copy.version);
+  onCleanup(copy.subscribe(() => setVersion(copy.version)));
+  const value = bindCopy<JSX.Element, JSX.Element>(copy, tags, { track: version, whole: (parts) => parts as JSX.Element });
+  return createComponent(CopyContext.Provider, {
+    value,
+    get children() {
+      return props.children;
+    },
+  });
+}
+
+/** The catalog, in the current locale. What reads it updates when the locale changes, or in dev the catalog. */
+export function useCopy(): SolidCopy {
+  const reader = useContext(CopyContext);
+  if (reader === undefined) throw new Error('prosebook: useCopy() needs a <CopyProvider> above it');
+  return reader;
+}
+
+/** The current locale, as an accessor. */
+export function useLocale(): Accessor<RegisteredLocale> {
+  const reader = useCopy();
+  return () => reader.locale;
+}
+
+export type TextProps<K extends Extract<keyof M, string>> = Props<K, JSX.Element>;
+
+/**
+ * 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>): JSX.Element {
+  const copy = useCopy();
+  // An accessor is something JSX renders, and runs again when the message or its values change.
+  return createMemo(() => copy.rich(props.id as never, (props as { values?: object }).values as never)) as unknown as JSX.Element;
+}

package/src/svelte/Text.svelte

@@ -0,0 +1,13 @@
+<!--
+  A message, its tags rendered by snippets of the same name: `<Text id="cart.items" values={{ count }} />`.
+  Given `chunks` instead, as a tag's snippet is, renders what the tag wraps.
+-->
+<script lang="ts">
+  import { getCopy, type RichPart } from 'prosebook/svelte';
+
+  let { id, values, chunks, ...snippets }: { id?: string; values?: object; chunks?: RichPart[]; [tag: string]: unknown } = $props();
+  const copy = getCopy();
+  const parts = $derived(chunks ?? copy.rich(id as never, { ...snippets, ...values } as never));
+</script>
+
+{#each parts as part}{#if typeof part === 'string'}{part}{:else}{@render part.snippet(part.chunks)}{/if}{/each}

package/src/svelte/Text.svelte.d.ts

@@ -0,0 +1,20 @@
+// Beside `Text.svelte` in src and in dist, so it names prosebook by package rather than by path.
+import type { RegisteredMessages } from 'prosebook';
+import type { RichPart, TagSnippet } from 'prosebook/svelte';
+import type { Component } from 'svelte';
+
+type M = RegisteredMessages;
+
+/**
+ * A message's props: its key, `values` once it takes arguments, and a snippet per tag no default renders.
+ * Per key, so a key Svelte's tooling widens to the union still needs its own `values`.
+ */
+export type TextProps<K extends Extract<keyof M, string>> = K extends unknown
+  ? { id: K } & ({} extends M[K]['args'] ? { values?: M[K]['args'] } : { values: M[K]['args'] }) & { [T in M[K]['tags']]?: TagSnippet }
+  : never;
+
+/** A message as markup, or with `chunks`, what a tag wraps. */
+declare const Text: <K extends Extract<keyof M, string>>(
+  ...args: Parameters<Component<TextProps<K> | { chunks: RichPart[] }>>
+) => ReturnType<Component<TextProps<K> | { chunks: RichPart[] }>>;
+export default Text;

package/src/svelte/index.ts

@@ -0,0 +1,65 @@
+/**
+ * `prosebook/svelte`: the catalog in Svelte 5 components.
+ *
+ * Every read goes through a subscriber the copy updates on each change, so markup, `$derived` and
+ * effects that read a message run again when the locale switches. Tags render through snippets:
+ * a rich read returns text and `{ snippet, chunks }` parts, which `<Text>` renders.
+ */
+import { getContext, setContext, type Snippet } from 'svelte';
+import { createSubscriber } from 'svelte/reactivity';
+
+import { bindCopy, type BoundCopy } from '#src/runtime/bind.ts';
+import type { Copy } from '#src/runtime/copy.ts';
+import type { DefaultTags, MessageShape, RegisteredMessages, RichKey } from '#src/runtime/types.ts';
+
+export { default as Text } from './Text.svelte';
+
+type M = RegisteredMessages;
+
+/** What a rich read returns: text, and each tag as the snippet that renders it and what it wraps. */
+export type RichPart = string | { snippet: TagSnippet; chunks: RichPart[] };
+
+/** Renders a tag: `{#snippet link(chunks)}<a href="/terms"><Text {chunks} /></a>{/snippet}`. */
+export type TagSnippet = Snippet<[chunks: RichPart[]]>;
+
+type Tags = { readonly [tag: string]: TagSnippet };
+
+/** The arguments of a rich read, and a snippet for each tag no default renders. */
+export type RichSnippets<S extends MessageShape> = S['args'] & { [T in Exclude<S['tags'], DefaultTags>]: TagSnippet } & {
+  [T in Extract<S['tags'], DefaultTags>]?: TagSnippet;
+};
+
+/** `Copy`, whose reads are reactive, with `rich` taking snippets and returning parts for `<Text>`. */
+export interface SvelteCopy extends Omit<BoundCopy<never>, 'rich'> {
+  rich<K extends RichKey<M>>(
+    this: void,
+    key: K,
+    ...values: {} extends RichSnippets<M[K]> ? [values?: RichSnippets<M[K]>] : [values: RichSnippets<M[K]>]
+  ): RichPart[];
+}
+
+export interface CopyOptions {
+  /** Snippets every rich read gets for these tags, beside the copy's own renderers. */
+  tags?: Tags;
+}
+
+const KEY = Symbol('prosebook');
+
+/** Gives this component and those under it the copy, and returns it as `getCopy()` would. Call it while the component initialises. */
+export function setCopy(copy: Copy, options: CopyOptions = {}): SvelteCopy {
+  const track = createSubscriber((update) => copy.subscribe(update));
+  const reader = bindCopy<never, RichPart[]>(copy, options.tags ?? {}, {
+    track,
+    // A snippet renders only inside markup, so a tag's parts wait there for `<Text>`.
+    tag: (snippet, chunks) => ({ snippet, chunks }),
+    whole: (parts) => parts as RichPart[],
+  });
+  return setContext(KEY, reader as unknown as SvelteCopy);
+}
+
+/** The catalog, in the current locale. What reads it runs again when the locale changes, or in dev the catalog. */
+export function getCopy(): SvelteCopy {
+  const reader = getContext<SvelteCopy | undefined>(KEY);
+  if (reader === undefined) throw new Error('prosebook: getCopy() needs setCopy(copy) in a component above it');
+  return reader;
+}