@saykit/react 0.0.0-beta-20260810145057 → 0.0.0-beta-20260906064714

package/README.md

@@ -4,7 +4,7 @@
 
 [![Coverage](https://codecov.io/gh/k0d13/saykit/graph/badge.svg?flag=integration-react)](https://codecov.io/gh/k0d13/saykit?flags%5B0%5D=integration-react)
 
-A `<Say>` component for rendering translated content in server and client components, a `<SayProvider>` and `useSay()` for client trees, and a small server runtime (`setSay`, `getSay`, `unstable_createWithSay`).
+A `<Say>` component for rendering translated content in server and client components, a `<SayProvider>` and `useSay()` for client trees, and a `withSay` and `getSay()` that mirror them on the server.
 
 ## Install
 
@@ -17,11 +17,18 @@ You will also need a SayKit build-tool plugin and a `saykit.config.ts`.
 ## Usage
 
 ```tsx
-import { Say, SayProvider } from '@saykit/react/client';
+import { Say } from '@saykit/react';
+import { SayProvider } from '@saykit/react/client';
+import { createCatalogue, createStore } from 'saykit';
+
+const en = { greeting: 'Hello, {name}!' };
+const fr = { greeting: 'Bonjour, {name} !' };
+
+const store = createStore(createCatalogue({ en, fr }), 'fr');
 
 function App() {
   return (
-    <SayProvider locale="fr" messages={fr}>
+    <SayProvider store={store}>
       <Say>Hello, {name}!</Say>
       <Say.Plural _={count} one={<>{count} item</>} other={<>{count} items</>} />
     </SayProvider>

package/dist/client.d.mts

@@ -1,31 +1,58 @@
 import { PropsWithChildren } from "react";
-import { ReadonlySay, Say } from "saykit";
+import { Store, View } from "saykit";
 //#region src/runtime/client.d.ts
-type SayRef = {
-  current: ReadonlySay | null;
-};
 /**
- * Provide a localised {@link runtime.Say} instance to descendant **client** components via context.
- * Must wrap any component tree using {@link useSay} or {@link Say}.
+ * Where a provider takes its view from.
  *
- * The instance is rebuilt whenever `locale` or `messages` changes, so keep `messages`
- * referentially stable (module scope, or memoised) rather than passing a fresh object
- * literal on every render.
+ * A store is the reactive form: it owns a catalogue, so it can switch locale,
+ * and every consumer re-renders when it does. Being a live object, it cannot
+ * cross the server/client boundary.
  *
- * @param props.locale The current locale
- * @param props.messages The current messages for the locale
+ * A locale and its messages are the serialisable form a server can hand across
+ * that boundary. Only that one locale comes over, so the provider built from
+ * it has nothing to switch to: switching is the server's to do, normally
+ * through navigation.
  */
-declare function SayProvider({ locale, messages, children }: PropsWithChildren<{
+type SayProviderProps = {
+  store: Store;
+  locale?: never;
+  messages?: never;
+} | {
+  store?: never;
   locale: string;
-  messages: Say.Messages;
-}>): import("react").FunctionComponentElement<import("react").ProviderProps<SayRef>>;
+  messages: View.Messages;
+} | {
+  store?: never;
+  locale?: never;
+  messages?: never;
+};
 /**
- * Get the current {@link Say} **client** instance.
+ * Provide a {@link View} to descendant **client** components via context.
+ * Must wrap any component tree using {@link useSay} or {@link Say}.
+ *
+ * @param props.store The store to follow, for an application that switches
+ *   locale on the client
+ * @param props.locale The current locale, for one that was given a single
+ *   locale by the server
+ * @param props.messages The messages for that locale, which should be
+ *   referentially stable rather than a fresh object literal per render
+ */
+declare function SayProvider({ store, locale, messages, children }: PropsWithChildren<SayProviderProps>): import("react").FunctionComponentElement<import("react").ProviderProps<any>>;
+/**
+ * Get the current {@link View}, on the client.
  * Must be called within a {@link SayProvider}.
  *
- * @returns The current {@link Say} instance
+ * The component re-renders when the store switches locale, so the view this
+ * returns is the current one rather than the one the tree first mounted with.
+ *
+ * There is no hook for the store behind it: a store is a module-scope value,
+ * so a locale picker imports the one it built and calls {@link Store.set} on
+ * it. A provider given a locale and its messages has no catalogue to switch
+ * through anyway.
+ *
+ * @returns The current {@link View}
  * @throws If no provider is in the component tree
  */
-declare function useSay(): any;
+declare function useSay(): View;
 //#endregion
-export { SayProvider, useSay };
+export { SayProvider, SayProviderProps, useSay };

package/dist/client.mjs

@@ -1,25 +1,25 @@
 "use client";
-import { createContext, createElement, useContext, useMemo } from "react";
-import { Say } from "saykit";
+import { createContext, createElement, useContext, useMemo, useSyncExternalStore } from "react";
+import { createCatalogue, createStore } from "saykit";
 //#region src/runtime/client.ts
-const SayContext = createContext({ current: null });
+const SayContext = createContext(null);
 SayContext.displayName = "SayContext";
-function SayProvider({ locale, messages, children }) {
-	const ref = useMemo(() => {
-		const instance = new Say({
-			locales: [locale],
-			loader: () => messages
-		});
-		instance.load(locale);
-		instance.activate(locale);
-		return { current: instance.freeze() };
-	}, [locale, messages]);
-	return createElement(SayContext.Provider, { value: ref }, children);
+function SayProvider({ store, locale, messages, children }) {
+	const held = useMemo(() => {
+		if (store) return store;
+		if (locale === void 0 || !messages) throw new Error("'SayProvider' must be given a store, or a locale and its messages");
+		return createStore(createCatalogue({ [locale]: messages }), locale);
+	}, [
+		store,
+		locale,
+		messages
+	]);
+	return createElement(SayContext.Provider, { value: held }, children);
 }
 function useSay() {
-	const ref = useContext(SayContext);
-	if (!ref.current) throw new Error("'useSay' must be used within a 'SayProvider'");
-	return ref.current;
+	const store = useContext(SayContext);
+	if (!store) throw new Error("'useSay' must be used within a 'SayProvider'");
+	return useSyncExternalStore(useMemo(() => (listener) => store.subscribe(listener), [store]), () => store.say, () => store.say);
 }
 //#endregion
 export { SayProvider, useSay };

package/dist/client.server.d.mts

@@ -0,0 +1,18 @@
+import { ReactNode } from "react";
+import "server-only";
+//#region src/runtime/client.server.d.ts
+/**
+ * The server build of `@saykit/react/client`.
+ *
+ * A store is a live object and cannot cross the server/client boundary, and a
+ * server component cannot hand its own scope to a client one either. What can
+ * cross is the locale and its messages, so this reads them off the view the
+ * the enclosing segment established with {@link import('./server.js').setSay}, and passes them
+ * to the real provider, which is why `<SayProvider>` written on the server
+ * takes no props.
+ */
+declare function SayProvider({ children }: {
+  children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").PropsWithChildren<import("./client.js").SayProviderProps>>;
+//#endregion
+export { SayProvider };

package/dist/client.server.mjs

@@ -0,0 +1,14 @@
+import { createElement } from "react";
+import "server-only";
+import { SayProvider as SayProvider$1 } from "./client.mjs";
+import { getSay } from "./server.mjs";
+//#region src/runtime/client.server.ts
+function SayProvider({ children }) {
+	const say = getSay();
+	return createElement(SayProvider$1, {
+		locale: say.locale,
+		messages: say.messages
+	}, children);
+}
+//#endregion
+export { SayProvider };

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { DateTimeOptions, Disallow, Named, NumberOptions, NumeralOptions, Select
 //#region src/types.d.ts
 /**
  * What a message is allowed to contain. On top of everything React renders, a
- * named placeholder — `{{ name: value }}` — reaches the type checker as a plain
+ * named placeholder, `{{ name: value }}`, reaches the type checker as a plain
  * object child, so the object form has to be part of the contract even though
  * nothing ever renders it: the transform reads the name off it and compiles the
  * child away before React sees the tree.
@@ -48,7 +48,7 @@ declare namespace Say {
     _: number | Named<number>;
   } & PropsWithJSXSafeKeys<Disallow<NumeralOptions<ReactNode>, 'id' | 'context'>>): ReactNode;
   /**
-   * Define an ordinal message (e.g. "1st", "2nd", "3rd").
+   * Define an ordinal message ("1st", "2nd", "3rd").
    *
    * @example
    * ```tsx
@@ -70,7 +70,7 @@ declare namespace Say {
     _: number | Named<number>;
   } & PropsWithJSXSafeKeys<Disallow<NumeralOptions<ReactNode>, 'id' | 'context'>>): ReactNode;
   /**
-   * Define a select message, useful for handling gender, status, or other categories.
+   * Define a select message, for gender, status, or other categories.
    *
    * @example
    * ```tsx
@@ -93,7 +93,7 @@ declare namespace Say {
   /**
    * Format a number the way the active locale writes one.
    *
-   * Unlike `Say.Plural`, `Say.Ordinal`, and `Say.Select`, this is a fragment
+   * Unlike `Say.Plural`, `Say.Ordinal` and `Say.Select`, this is a fragment
    * rather than a whole message, and is normally written inside one.
    *
    * @example
@@ -104,8 +104,8 @@ declare namespace Say {
    * ```
    *
    * @param props._ Number to format
-   * @param props.style Formatting style: a named style, an ICU skeleton such as
-   *   `::currency/EUR`, or a literal number pattern such as `#,##0.00`
+   * @param props.style A named style, an ICU skeleton such as
+   *   `::currency/EUR`, or a pattern such as `#,##0.00`
    * @returns The formatted number, as a React node
    * @remark This is a macro and must be used with the relevant saykit plugin
    */
@@ -122,8 +122,7 @@ declare namespace Say {
    * ```
    *
    * @param props._ Date to format
-   * @param props.style Formatting style, either a named style or an ICU
-   *   skeleton such as `::yyyyMMdd`
+   * @param props.style A named style or an ICU skeleton such as `::yyyyMMdd`
    * @returns The formatted date, as a React node
    * @remark This is a macro and must be used with the relevant saykit plugin
    */
@@ -140,8 +139,7 @@ declare namespace Say {
    * ```
    *
    * @param props._ Date to format
-   * @param props.style Formatting style, either a named style or an ICU
-   *   skeleton such as `::Hm`
+   * @param props.style A named style or an ICU skeleton such as `::Hm`
    * @returns The formatted time, as a React node
    * @remark This is a macro and must be used with the relevant saykit plugin
    */

package/dist/server.d.mts

@@ -1,33 +1,68 @@
 import { ReactNode } from "react";
-import { ReadonlySay, Say } from "saykit";
+import { Catalogue, View } from "saykit";
 import "server-only";
 //#region src/runtime/server.d.ts
 /**
- * Set the current {@link Say} **server** instance.
- * Must be called before any {@link getSay} calls.
+ * Get the current {@link View}, on the server.
+ * Must be called below a {@link setSay}, which {@link createWithSay} does for
+ * you.
  *
- * @param say The current {@link Say} instance
+ * The server counterpart of `useSay`. Reach for it when you need the locale as
+ * *data*, to build an `Intl.NumberFormat` say, rather than as a rendered
+ * message, which is what `<Say>` is for.
+ *
+ * @example
+ * ```tsx
+ * const say = getSay();
+ * const price = new Intl.NumberFormat(say.locale, { style: 'currency', currency }).format(total);
+ * ```
+ *
+ * @returns The current {@link View}
+ * @throws If no view has been established for this request
  */
-declare function setSay(say: Say | ReadonlySay | (() => Say | ReadonlySay)): void;
+declare function getSay(): View;
 /**
- * Get the current {@link Say} **server** instance.
- * Must only be called after any {@link setSay} calls.
+ * Establish the {@link View} for everything rendered after this point, on the
+ * server. Reach for it when you already have a view; {@link createWithSay}
+ * negotiates and loads one for you.
  *
- * @returns The current {@link Say} instance
- * @throws If no {@link Say} instance has been set
+ * Per request is the limit. React renders a server component's children after
+ * it returns, so a view does not end where a subtree does: a second view takes
+ * over for everything rendered after it, including the messages
+ * `<SayProvider>` serialises. Development warns when that happens.
+ *
+ * @param view The view to establish
  */
-declare function getSay(): ReadonlySay;
+declare function setSay(view: View): void;
 /**
- * Create a {@link withSay} higher-order component factory bound to a specific {@link Say} instance.
+ * Bind a `withSay` to a {@link Catalogue}, normally once beside the catalogue
+ * itself.
+ *
+ * `withSay` wraps a server component so its view is negotiated, loaded and
+ * established before the component renders, which `<Say>` and {@link getSay}
+ * then read at any depth below.
+ *
+ * Every route segment that renders messages wraps itself, rather than
+ * inheriting from a parent. A framework is free to render a page before the
+ * layout above it - Next.js does - and a parent that has not run yet has
+ * established nothing.
+ *
+ * A `<SayProvider>` written inside a wrapped component takes no props of its
+ * own: the server build of `@saykit/react/client` reads the established view
+ * and serialises the locale and its messages across the boundary.
+ *
+ * @example
+ * ```tsx
+ * // i18n.ts
+ * export const withSay = createWithSay(catalogue);
  *
- * @param say The {@link Say} instance to bind into the server context
+ * // app/[locale]/page.tsx
+ * export default withSay(Page, (props) => props.params.then((params) => params.locale));
+ * ```
  *
- * @returns A {@link withSay} higher-order component factory
+ * @param catalogue The catalogue to take views from
+ * @returns A `withSay` bound to that catalogue
  */
-declare function unstable_createWithSay(say: Say): <P = unknown>(Component: (props: PropsWithSay<P>) => ReactNode, getLocale: (props: P) => string | Promise<string>) => (props: P) => Promise<import("react").FunctionComponentElement<PropsWithSay<P>>>;
-type PropsWithSay<P = unknown> = P & {
-  locale: string;
-  messages: Say.Messages;
-};
+declare function createWithSay<Locale extends string>(catalogue: Catalogue<Locale>): <P>(Component: (props: P) => ReactNode, locale: (props: P) => Catalogue.Guess | Promise<Catalogue.Guess>) => (props: P) => Promise<ReactNode>;
 //#endregion
-export { PropsWithSay, getSay, setSay, unstable_createWithSay };
+export { createWithSay, getSay, setSay };

package/dist/server.mjs

@@ -1,33 +1,32 @@
 import { cache, createElement } from "react";
-import { Say } from "saykit";
 import "server-only";
 //#region src/runtime/server.ts
-const serverContext = cache(() => ({ current: null }));
-function setSay(say) {
-	const ref = serverContext();
-	if (say instanceof Say) ref.current = say.clone().freeze();
-	else ref.current = say().clone().freeze();
-}
+const cell = cache(() => ({
+	view: void 0,
+	warned: false
+}));
+const NO_VIEW = "'getSay' must be called below a 'withSay'. Wrap the component in 'withSay(Component, (props) => props.params.then((params) => params.locale))'.";
+const SECOND_VIEW = (established, next) => `A view for '${next}' was established while '${established}' was already established for this request. A view is per request rather than per subtree: React renders a server component's children after it returns, so there is nowhere to put the previous view back, and everything rendered after this point reads '${next}' - including components outside the one that established it, and the messages 'SayProvider' serialises to the client. Render the other locale in its own request, or resolve its view yourself and pass it to the components that need it.`;
 function getSay() {
-	const ref = serverContext();
-	if (!ref.current) throw new Error("Attempt to access the server-only Say instance before initialisation", { cause: /* @__PURE__ */ new Error("'getSay' must be called after 'setSay'") });
-	return ref.current;
+	const view = cell().view;
+	if (!view) throw new Error(NO_VIEW);
+	return view;
+}
+function setSay(view) {
+	const request = cell();
+	if (process.env.NODE_ENV !== "production" && !request.warned && request.view && request.view.locale !== view.locale) {
+		request.warned = true;
+		console.warn(SECOND_VIEW(request.view.locale, view.locale));
+	}
+	request.view = view;
 }
-function unstable_createWithSay(say) {
-	return function withSay(Component, getLocale) {
+function createWithSay(catalogue) {
+	return function withSay(Component, locale) {
 		return async function WithSay(props) {
-			const guess = await getLocale(props);
-			const locale = say.match(guess);
-			await say.load(locale);
-			say.activate(locale);
-			setSay(say);
-			return createElement(Component, {
-				...props,
-				locale: say.locale,
-				messages: say.messages
-			});
+			setSay(await catalogue.load(catalogue.match(await locale(props))));
+			return createElement(Component, props);
 		};
 	};
 }
 //#endregion
-export { getSay, setSay, unstable_createWithSay };
+export { createWithSay, getSay, setSay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.0.0-beta-20260810145057",
+  "version": "0.0.0-beta-20260906064714",
   "description": "React integration for saykit, i18n hooks and components",
   "keywords": [
     "i18n",
@@ -31,6 +31,7 @@
     },
     "./client": {
       "types": "./dist/client.d.mts",
+      "react-server": "./dist/client.server.mjs",
       "default": "./dist/client.mjs"
     },
     "./server": {
@@ -52,11 +53,11 @@
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "saykit": "^0.0.0-beta-20260810145057"
+    "saykit": "^0.0.0-beta-20260906064714"
   },
   "peerDependencies": {
     "react": "*",
-    "saykit": "0.0.0-beta-20260810145057"
+    "saykit": "0.0.0-beta-20260906064714"
   },
   "scripts": {
     "check": "tsc --noEmit",