@saykit/react 0.10.0 → 0.11.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 `<SayScope>` and `getSay()` that mirror them on the server.
+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
 
@@ -12,30 +12,66 @@ A `<Say>` component for rendering translated content in server and client compon
 pnpm add @saykit/react saykit
 ```
 
-You will also need a SayKit build-tool plugin and a `saykit.config.ts`.
+You will also need a SayKit build-tool plugin ([`unplugin-saykit`](https://github.com/k0d13/saykit/tree/main/packages/plugin-unplugin) or [`babel-plugin-saykit`](https://github.com/k0d13/saykit/tree/main/packages/plugin-babel)) and a `saykit.config.ts` with `@saykit/transform-jsx` in the bucket. The lazy `() => import(...)` catalogues below need `unplugin-saykit` or `babel-plugin-saykit` with `catalogues: 'module'`; Babel's default inline mode only handles static imports.
 
 ## Usage
 
-```tsx
-import { Say } from '@saykit/react';
-import { SayProvider } from '@saykit/react/client';
+```ts title="src/i18n.ts"
 import { createCatalogue, createStore } from 'saykit';
 
-const en = { greeting: 'Hello, {name}!' };
-const fr = { greeting: 'Bonjour, {name} !' };
+export const catalogue = createCatalogue({
+  en: () => import('./locales/en.po'),
+  fr: () => import('./locales/fr.po'),
+});
+
+const initial = catalogue.match(navigator.languages);
+await catalogue.load(initial);
+
+export const store = createStore(catalogue, initial);
+export type Locale = (typeof catalogue.locales)[number];
+```
+
+```tsx title="src/app.tsx"
+import { Say } from '@saykit/react';
+import { SayProvider, useSay } from '@saykit/react/client';
+import { type Locale, store } from './i18n.js';
+
+function Cart({ name, items }: { name: string; items: string[] }) {
+  return (
+    <p>
+      <Say>Hello, {name}!</Say>{' '}
+      <Say.Plural
+        _={items.length}
+        _0="Your cart is empty."
+        one="You have 1 item."
+        other={<>You have {items.length} items.</>}
+      />
+    </p>
+  );
+}
 
-const store = createStore(createCatalogue({ en, fr }), 'fr');
+function LocalePicker() {
+  const say = useSay();
+  return (
+    <select value={say.locale} onChange={(event) => store.set(event.target.value as Locale)}>
+      <option value="en">English</option>
+      <option value="fr">Français</option>
+    </select>
+  );
+}
 
-function App() {
+export function App() {
   return (
     <SayProvider store={store}>
-      <Say>Hello, {name}!</Say>
-      <Say.Plural _={count} one={<>{count} item</>} other={<>{count} items</>} />
+      <LocalePicker />
+      <Cart name="Ada" items={[]} />
     </SayProvider>
   );
 }
 ```
 
+Elements inside a message survive translation as numbered tags: `<Say>Read the <a href="/docs">docs</a></Say>` extracts as `Read the <0>docs</0>`.
+
 ## Documentation
 
 [React integration guide](https://saykit.js.org/integrations/react) at [saykit.js.org](https://saykit.js.org).

package/dist/client.d.mts

@@ -37,7 +37,7 @@ type SayProviderProps = {
  * @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>>;
+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}.

package/dist/client.server.d.mts

@@ -7,7 +7,7 @@ import "server-only";
  * 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
+ * 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.
  */

package/dist/index.d.mts

@@ -22,10 +22,11 @@ type PropsWithJSXSafeKeys<T> = { [K in keyof T as K extends number | `${number}$
  * @returns The translation node for the descriptor
  * @remark This is a macro and must be used with the relevant saykit plugin
  */
-declare function Say(props: PropsWithSayChildren<Disallow<{
+declare function Say(props: PropsWithSayChildren<{
+  id?: string;
   context?: string;
   whitespace?: boolean;
-}, 'id'>>): ReactElement;
+}>): ReactElement;
 declare namespace Say {
   /**
    * Define a pluralised message.

package/dist/index.mjs

@@ -56,14 +56,17 @@ function resolveValuePropKeys(props) {
 //#endregion
 //#region src/runtime/index.ts
 function Say(props) {
-	if (!("id" in props)) throw new Error("'Say' is a macro and must be used with the relevant saykit plugin", { cause: /* @__PURE__ */ new Error("The 'id' property is required for a descriptor") });
+	if (!("id" in props) && !("message" in props)) throw new Error("'Say' is a macro and must be used with the relevant saykit plugin", { cause: /* @__PURE__ */ new Error("The 'id' property is required for a descriptor") });
 	const say = GET_SAY();
-	const { id, whitespace, ...rest } = props;
+	const { id, message, whitespace, ...rest } = props;
 	const values = resolveValuePropKeys(rest);
 	return createElement(Renderer, {
-		html: say.call({
+		html: say.call(message === void 0 ? {
 			...rest,
 			id
+		} : {
+			...rest,
+			message
 		}),
 		whitespace,
 		components(tag) {

package/dist/index.server.mjs

@@ -56,14 +56,17 @@ function resolveValuePropKeys(props) {
 //#endregion
 //#region src/runtime/index.ts
 function Say(props) {
-	if (!("id" in props)) throw new Error("'Say' is a macro and must be used with the relevant saykit plugin", { cause: /* @__PURE__ */ new Error("The 'id' property is required for a descriptor") });
+	if (!("id" in props) && !("message" in props)) throw new Error("'Say' is a macro and must be used with the relevant saykit plugin", { cause: /* @__PURE__ */ new Error("The 'id' property is required for a descriptor") });
 	const say = GET_SAY();
-	const { id, whitespace, ...rest } = props;
+	const { id, message, whitespace, ...rest } = props;
 	const values = resolveValuePropKeys(rest);
 	return createElement(Renderer, {
-		html: say.call({
+		html: say.call(message === void 0 ? {
 			...rest,
 			id
+		} : {
+			...rest,
+			message
 		}),
 		whitespace,
 		components(tag) {

package/dist/server.d.mts

@@ -4,7 +4,8 @@ import "server-only";
 //#region src/runtime/server.d.ts
 /**
  * Get the current {@link View}, on the server.
- * Must be called below a {@link SayScope}.
+ * Must be called below a {@link setSay}, which {@link createWithSay} does for
+ * you.
  *
  * 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
@@ -17,61 +18,51 @@ import "server-only";
  * ```
  *
  * @returns The current {@link View}
- * @throws If no {@link SayScope} is above the caller
+ * @throws If no view has been established for this request
  */
 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;
-  });
-}
 /**
- * Establish the {@link View} for everything rendered inside it, on the server.
+ * 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.
  *
- * 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 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.
  *
- * 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.
+ * @param view The view to establish
+ */
+declare function setSay(view: View): void;
+/**
+ * Bind a `withSay` to a {@link Catalogue}, normally once beside the catalogue
+ * itself.
  *
- * 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.
+ * `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.
  *
- * @example
- * ```tsx
- * <SayScope catalogue={catalogue} locale={locale}>
- *   <SayProvider>{children}</SayProvider>
- * </SayScope>
- * ```
+ * 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
- * <SayScope view={await catalogue.load('fr')}>{children}</SayScope>
+ * // i18n.ts
+ * export const withSay = createWithSay(catalogue);
+ *
+ * // app/[locale]/page.tsx
+ * export default withSay(Page, (props) => props.params.then((params) => params.locale));
  * ```
  *
- * @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
+ * @param catalogue The catalogue to take views from
+ * @returns A `withSay` bound to that catalogue
  */
-declare function SayScope<Locale extends string>({ catalogue, locale, view, children }: SayScope.Props<Locale>): Promise<ReactNode>;
+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 { SayScope, getSay };
+export { createWithSay, getSay, setSay };

package/dist/server.mjs

@@ -1,26 +1,32 @@
-import { cache } from "react";
+import { cache, createElement } from "react";
 import "server-only";
 //#region src/runtime/server.ts
 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.`;
+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 view = cell().view;
 	if (!view) throw new Error(NO_VIEW);
 	return view;
 }
-async function SayScope({ catalogue, locale, view, children }) {
-	const resolved = view ?? await catalogue.load(catalogue.match(locale));
+function setSay(view) {
 	const request = cell();
-	if (process.env.NODE_ENV !== "production" && !request.warned && request.view && request.view.locale !== resolved.locale) {
+	if (process.env.NODE_ENV !== "production" && !request.warned && request.view && request.view.locale !== view.locale) {
 		request.warned = true;
-		console.warn(NESTED_SCOPE(request.view.locale, resolved.locale));
+		console.warn(SECOND_VIEW(request.view.locale, view.locale));
 	}
-	request.view = resolved;
-	return children;
+	request.view = view;
+}
+function createWithSay(catalogue) {
+	return function withSay(Component, locale) {
+		return async function WithSay(props) {
+			setSay(await catalogue.load(catalogue.match(await locale(props))));
+			return createElement(Component, props);
+		};
+	};
 }
 //#endregion
-export { SayScope, getSay };
+export { createWithSay, getSay, setSay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "React integration for saykit, i18n hooks and components",
   "keywords": [
     "i18n",
@@ -53,7 +53,7 @@
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "saykit": "^0.10.0"
+    "saykit": "^0.11.0"
   },
   "peerDependencies": {
     "react": "*",