@saykit/react 0.9.1 → 0.10.0

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 `<SayScope>` 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<Store<string> | null>>;
+/**
+ * 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
+ * enclosing {@link import('./server.js').SayScope} established 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,77 @@
 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 SayScope}.
  *
- * @param say The current {@link Say} instance
- */
-declare function setSay(say: Say | ReadonlySay | (() => Say | ReadonlySay)): void;
-/**
- * Get the current {@link Say} **server** instance.
- * Must only be called after any {@link setSay} calls.
+ * 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.
  *
- * @returns The current {@link Say} instance
- * @throws If no {@link Say} instance has been set
+ * @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 {@link SayScope} is above the caller
  */
-declare function getSay(): ReadonlySay;
+declare function getSay(): View;
+declare namespace SayScope {
+  /**
+   * Which view a scope establishes: a catalogue and a locale to negotiate
+   * against it, or a view already resolved.
+   */
+  type Props<Locale extends string = string> = {
+    children?: ReactNode;
+  } & ({
+    catalogue: Catalogue<Locale>;
+    locale: Catalogue.Guess;
+    view?: never;
+  } | {
+    view: View<Locale>;
+    catalogue?: never;
+    locale?: never;
+  });
+}
 /**
- * Create a {@link withSay} higher-order component factory bound to a specific {@link Say} instance.
+ * Establish the {@link View} for everything rendered inside it, on the server.
+ *
+ * Given a catalogue and a locale, the locale is negotiated against the
+ * catalogue and its messages are loaded before the children render. Given a
+ * view, that view is established as it is. Either way `<Say>` and
+ * {@link getSay} resolve at any depth below, and the scope is per request.
+ *
+ * Per request is also the limit. React renders a server component's children
+ * after it returns, so a scope does not end where its children do: a second
+ * scope takes over for everything rendered after it, including components
+ * outside it and the messages `<SayProvider>` serialises. Development warns
+ * when that happens. Render another locale in its own request, or resolve its
+ * view yourself and pass it to the components that need it.
+ *
+ * A `<SayProvider>` written inside one 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
+ * <SayScope catalogue={catalogue} locale={locale}>
+ *   <SayProvider>{children}</SayProvider>
+ * </SayScope>
+ * ```
  *
- * @param say The {@link Say} instance to bind into the server context
+ * @example
+ * ```tsx
+ * <SayScope view={await catalogue.load('fr')}>{children}</SayScope>
+ * ```
  *
- * @returns A {@link withSay} higher-order component factory
+ * @param props.catalogue The catalogue to take the view from
+ * @param props.locale The locale to negotiate against it
+ * @param props.view A view to establish as it is, instead of both of those
  */
-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 SayScope<Locale extends string>({ catalogue, locale, view, children }: SayScope.Props<Locale>): Promise<ReactNode>;
 //#endregion
-export { PropsWithSay, getSay, setSay, unstable_createWithSay };
+export { SayScope, getSay };

package/dist/server.mjs

@@ -1,33 +1,26 @@
-import { cache, createElement } from "react";
-import { Say } from "saykit";
+import { cache } from "react";
 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 'SayScope'. Wrap the tree in '<SayScope catalogue={catalogue} locale={locale}>'.";
+const NESTED_SCOPE = (established, next) => `A 'SayScope' established '${next}' while '${established}' was already established for this request. A scope 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 inner scope, 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 unstable_createWithSay(say) {
-	return function withSay(Component, getLocale) {
-		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
-			});
-		};
-	};
+async function SayScope({ catalogue, locale, view, children }) {
+	const resolved = view ?? await catalogue.load(catalogue.match(locale));
+	const request = cell();
+	if (process.env.NODE_ENV !== "production" && !request.warned && request.view && request.view.locale !== resolved.locale) {
+		request.warned = true;
+		console.warn(NESTED_SCOPE(request.view.locale, resolved.locale));
+	}
+	request.view = resolved;
+	return children;
 }
 //#endregion
-export { getSay, setSay, unstable_createWithSay };
+export { SayScope, getSay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "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,7 +53,7 @@
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "saykit": "^0.9.1"
+    "saykit": "^0.10.0"
   },
   "peerDependencies": {
     "react": "*",