@saykit/react 0.11.1 → 0.12.0

package/README.md

@@ -12,7 +12,7 @@ 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 ([`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.
+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.
 
 ## Usage
 
@@ -20,8 +20,8 @@ You will also need a SayKit build-tool plugin ([`unplugin-saykit`](https://githu
 import { createCatalogue, createStore } from 'saykit';
 
 export const catalogue = createCatalogue({
-  en: () => import('./locales/en.po'),
-  fr: () => import('./locales/fr.po'),
+  en: () => import('./locales/en.js'),
+  fr: () => import('./locales/fr.js'),
 });
 
 const initial = catalogue.match(navigator.languages);

package/dist/client.d.mts

@@ -1,19 +1,12 @@
 import { PropsWithChildren } from "react";
 import { Store, View } from "saykit";
-//#region src/runtime/client.d.ts
 /**
  * Where a provider takes its view from.
  *
- * 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.
- *
- * 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.
+ * A store is reactive and can switch locale, but cannot cross the server/client boundary.
+ * A locale and its messages can, though the provider built from them has nothing to switch to.
  */
-type SayProviderProps = {
+export type SayProviderProps = {
   store: Store;
   locale?: never;
   messages?: never;
@@ -42,7 +35,7 @@ type SayProviderProps = {
  * @param props.options How that locale's view formats its messages, as the
  *   server's view was built with
  */
-declare function SayProvider({ store, locale, messages, options, children }: PropsWithChildren<SayProviderProps>): import("react").FunctionComponentElement<import("react").ProviderProps<any>>;
+export declare function SayProvider({ store, locale, messages, options, 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}.
@@ -58,6 +51,4 @@ declare function SayProvider({ store, locale, messages, options, children }: Pro
  * @returns The current {@link View}
  * @throws If no provider is in the component tree
  */
-declare function useSay(): View;
-//#endregion
-export { SayProvider, SayProviderProps, useSay };
+export declare function useSay(): View;

package/dist/client.mjs

@@ -1,7 +1,7 @@
 "use client";
 import { createContext, createElement, useContext, useMemo, useSyncExternalStore } from "react";
 import { createCatalogue, createStore } from "saykit";
-//#region src/runtime/client.ts
+// src/runtime/client.ts
 const SayContext = createContext(null);
 SayContext.displayName = "SayContext";
 function SayProvider({ store, locale, messages, options, children }) {
@@ -21,7 +21,7 @@ function SayProvider({ store, locale, messages, options, children }) {
 function useSay() {
 	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);
+	const subscribe = useMemo(() => (listener) => store.subscribe(listener), [store]);
+	return useSyncExternalStore(subscribe, () => store.say, () => store.say);
 }
-//#endregion
 export { SayProvider, useSay };

package/dist/client.server.d.mts

@@ -1,18 +1,12 @@
 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, its messages and the view's options, so this reads them
- * off the view 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.
+ * A store cannot cross the server/client boundary, but the locale, messages and options can.
+ * This reads them off the view set by {@link import('./server.js').setSay} and passes them
+ * to the real provider, so `<SayProvider>` on the server takes no props.
  */
-declare function SayProvider({ children }: {
+export declare function SayProvider({ children }: {
   children?: ReactNode;
-}): import("react").FunctionComponentElement<import("react").PropsWithChildren<import("./client.js").SayProviderProps>>;
-//#endregion
-export { SayProvider };
+}): import("react").FunctionComponentElement<import("react").PropsWithChildren<import("./client.js").SayProviderProps>>;

package/dist/client.server.mjs

@@ -2,7 +2,7 @@ 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
+// src/runtime/client.server.ts
 function SayProvider({ children }) {
 	const say = getSay();
 	return createElement(SayProvider$1, {
@@ -11,5 +11,4 @@ function SayProvider({ children }) {
 		options: say.options
 	}, children);
 }
-//#endregion
 export { SayProvider };

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import { ReactElement, ReactNode } from "react";
 import { DateTimeOptions, Disallow, Named, NumberOptions, NumeralOptions, SelectOptions } from "saykit";
-//#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
@@ -13,8 +12,6 @@ type PropsWithSayChildren<P = unknown> = P & {
   children?: SayNode;
 };
 type PropsWithJSXSafeKeys<T> = { [K in keyof T as K extends number | `${number}${string}` ? `_${K}` : K extends `_${number}${string}` ? never : K]: T[K]; };
-//#endregion
-//#region src/runtime/index.d.ts
 /**
  * Render the translation for a descriptor.
  *
@@ -22,12 +19,12 @@ 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<{
+export declare function Say(props: PropsWithSayChildren<{
   id?: string;
   context?: string;
   whitespace?: boolean;
 }>): ReactElement;
-declare namespace Say {
+export declare namespace Say {
   /**
    * Define a pluralised message.
    *
@@ -148,5 +145,4 @@ declare namespace Say {
     _: globalThis.Date | number | Named<globalThis.Date | number>;
   } & Disallow<DateTimeOptions, 'id' | 'context'>): ReactNode;
 }
-//#endregion
-export { Say };
+export {};

package/dist/index.mjs

@@ -1,5 +1,5 @@
 "use client"; import { useSay as GET_SAY } from "./client.mjs";import { Fragment, cloneElement, createElement, isValidElement } from "react";
-//#region src/components/renderer.ts
+// src/components/renderer.ts
 function Renderer({ html, components, whitespace = true }) {
 	function getComponent(tag) {
 		if (typeof components === "function")
@@ -24,7 +24,8 @@ function Renderer({ html, components, whitespace = true }) {
 				current.push(createElement(Component, { key: nodeKey++ }));
 			} else if (isClosing) {
 				const last = stack.pop();
-				const element = createElement(getComponent(last.tag), { key: nodeKey++ }, ...current);
+				const Component = getComponent(last.tag);
+				const element = createElement(Component, { key: nodeKey++ }, ...current);
 				current = last.children;
 				current.push(element);
 			} else {
@@ -45,16 +46,14 @@ function Renderer({ html, components, whitespace = true }) {
 	}
 	return createElement(Fragment, void 0, ...parseNode(html));
 }
-//#endregion
-//#region src/types.ts
+// src/types.ts
 function resolveValuePropKeys(props) {
 	const result = {};
 	for (const key in props) if (key.startsWith("_")) result[key.slice(1)] = props[key];
 	else result[key] = props[key];
 	return result;
 }
-//#endregion
-//#region src/runtime/index.ts
+// src/runtime/index.ts
 function Say(props) {
 	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();
@@ -106,5 +105,4 @@ function Say(props) {
 	}
 	_Say.Time = Time;
 })(Say || (Say = {}));
-//#endregion
 export { Say };

package/dist/index.server.mjs

@@ -1,5 +1,5 @@
 import { getSay as GET_SAY } from "./server.mjs";import { Fragment, cloneElement, createElement, isValidElement } from "react";
-//#region src/components/renderer.ts
+// src/components/renderer.ts
 function Renderer({ html, components, whitespace = true }) {
 	function getComponent(tag) {
 		if (typeof components === "function")
@@ -24,7 +24,8 @@ function Renderer({ html, components, whitespace = true }) {
 				current.push(createElement(Component, { key: nodeKey++ }));
 			} else if (isClosing) {
 				const last = stack.pop();
-				const element = createElement(getComponent(last.tag), { key: nodeKey++ }, ...current);
+				const Component = getComponent(last.tag);
+				const element = createElement(Component, { key: nodeKey++ }, ...current);
 				current = last.children;
 				current.push(element);
 			} else {
@@ -45,16 +46,14 @@ function Renderer({ html, components, whitespace = true }) {
 	}
 	return createElement(Fragment, void 0, ...parseNode(html));
 }
-//#endregion
-//#region src/types.ts
+// src/types.ts
 function resolveValuePropKeys(props) {
 	const result = {};
 	for (const key in props) if (key.startsWith("_")) result[key.slice(1)] = props[key];
 	else result[key] = props[key];
 	return result;
 }
-//#endregion
-//#region src/runtime/index.ts
+// src/runtime/index.ts
 function Say(props) {
 	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();
@@ -106,5 +105,4 @@ function Say(props) {
 	}
 	_Say.Time = Time;
 })(Say || (Say = {}));
-//#endregion
 export { Say };

package/dist/server.d.mts

@@ -1,7 +1,6 @@
 import { ReactNode } from "react";
 import { Catalogue, View } from "saykit";
 import "server-only";
-//#region src/runtime/server.d.ts
 /**
  * Get the current {@link View}, on the server.
  * Must be called below a {@link setSay}, which {@link createWithSay} does for
@@ -20,20 +19,18 @@ import "server-only";
  * @returns The current {@link View}
  * @throws If no view has been established for this request
  */
-declare function getSay(): View;
+export declare function getSay(): View;
 /**
  * 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.
  *
- * 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.
+ * A view lasts the whole request, not a subtree: a second view takes over everything rendered
+ * after it. Development warns when that happens.
  *
  * @param view The view to establish
  */
-declare function setSay(view: View): void;
+export declare function setSay(view: View): void;
 /**
  * Bind a `withSay` to a {@link Catalogue}, normally once beside the catalogue
  * itself.
@@ -47,9 +44,8 @@ declare function setSay(view: View): void;
  * 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.
+ * A `<SayProvider>` inside a wrapped component takes no props: the server build of
+ * `@saykit/react/client` reads the established view.
  *
  * @example
  * ```tsx
@@ -63,6 +59,4 @@ declare function setSay(view: View): void;
  * @param catalogue The catalogue to take views from
  * @returns A `withSay` bound to that catalogue
  */
-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 { createWithSay, getSay, setSay };
+export 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>;

package/dist/server.mjs

@@ -1,12 +1,12 @@
 import { cache, createElement } from "react";
 import "server-only";
-//#region src/runtime/server.ts
+// src/runtime/server.ts
 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.`;
+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' hands 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);
@@ -28,5 +28,4 @@ function createWithSay(catalogue) {
 		};
 	};
 }
-//#endregion
 export { createWithSay, getSay, setSay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "React integration for saykit, i18n hooks and components",
   "keywords": [
     "i18n",
@@ -23,6 +23,9 @@
     "!dist/**/*.map"
   ],
   "type": "module",
+  "imports": {
+    "#/*": "./src/*"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -47,13 +50,13 @@
     "server-only": "^0.0.1"
   },
   "devDependencies": {
-    "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "jsdom": "^29.1.1",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "saykit": "^0.11.1"
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "saykit": "^0.12.0"
   },
   "peerDependencies": {
     "react": "*",