@saykit/react 0.5.0 → 0.6.1

package/dist/client.d.mts

@@ -8,6 +8,10 @@ type SayRef = {
  * Provide a localised {@link runtime.Say} instance to descendant **client** components via context.
  * Must wrap any component tree using {@link useSay} or {@link Say}.
  *
+ * 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.
+ *
  * @param props.locale The current locale
  * @param props.messages The current messages for the locale
  */

package/dist/client.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { createContext, createElement, useContext, useState } from "react";
+import { createContext, createElement, useContext, useMemo } from "react";
 import { Say } from "saykit";
 //#region src/runtime/client.ts
 const SayContext = createContext({ current: null });
@@ -8,20 +8,24 @@ SayContext.displayName = "SayContext";
 * Provide a localised {@link runtime.Say} instance to descendant **client** components via context.
 * Must wrap any component tree using {@link useSay} or {@link Say}.
 *
+* 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.
+*
 * @param props.locale The current locale
 * @param props.messages The current messages for the locale
 */
 function SayProvider({ locale, messages, children }) {
-	const [say] = useState(() => {
+	const ref = useMemo(() => {
 		const instance = new Say({
 			locales: [locale],
 			loader: () => messages
 		});
 		instance.load(locale);
 		instance.activate(locale);
-		return instance.freeze();
-	});
-	return createElement(SayContext.Provider, { value: { current: say } }, children);
+		return { current: instance.freeze() };
+	}, [locale, messages]);
+	return createElement(SayContext.Provider, { value: ref }, children);
 }
 /**
 * Get the current {@link Say} **client** instance.

package/dist/index.d.mts

@@ -1,6 +1,17 @@
-import { PropsWithChildren, ReactElement, ReactNode } from "react";
-import { Disallow, NumeralOptions, SelectOptions } from "saykit";
+import { ReactElement, ReactNode } from "react";
+import { Disallow, Named, 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
+ * 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.
+ */
+type SayNode = ReactNode | Named<unknown> | Iterable<SayNode>;
+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
@@ -11,7 +22,7 @@ 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: PropsWithChildren<Disallow<{
+declare function Say(props: PropsWithSayChildren<Disallow<{
   context?: string;
   whitespace?: boolean;
 }, 'id'>>): ReactElement;
@@ -34,7 +45,7 @@ declare namespace Say {
    * @remark This is a macro and must be used with the relevant saykit plugin
    */
   function Plural(props: {
-    _: number;
+    _: number | Named<number>;
   } & PropsWithJSXSafeKeys<Disallow<NumeralOptions, 'id' | 'context'>>): ReactNode;
   /**
    * Define an ordinal message (e.g. "1st", "2nd", "3rd").
@@ -56,7 +67,7 @@ declare namespace Say {
    * @remark This is a macro and must be used with the relevant saykit plugin
    */
   function Ordinal(props: {
-    _: number;
+    _: number | Named<number>;
   } & PropsWithJSXSafeKeys<Disallow<NumeralOptions, 'id' | 'context'>>): ReactNode;
   /**
    * Define a select message, useful for handling gender, status, or other categories.
@@ -77,7 +88,7 @@ declare namespace Say {
    * @remark This is a macro and must be used with the relevant saykit plugin
    */
   function Select(props: {
-    _: string;
+    _: string | Named<string>;
   } & PropsWithJSXSafeKeys<Disallow<SelectOptions, 'id' | 'context'>>): ReactNode;
 }
 //#endregion

package/dist/index.mjs

@@ -47,9 +47,20 @@ function Renderer({ html, components, whitespace = true }) {
 }
 //#endregion
 //#region src/types.ts
-function resolveJsxSafePropKeys(props) {
+/**
+* Map the props the transform compiled a message's values into back to the
+* identifiers they carry. Every value is emitted with one underscore in front,
+* which is what keeps a numbered identifier a valid prop name and what keeps
+* any name a message chooses out of `Say`'s own namespace, so stripping exactly
+* one is the whole inverse — `_0` is `0`, and `__link` is a tag named `_link`.
+*
+* The result is deliberately not typed as the props that went in: renaming the
+* keys is the point, so claiming they survived would be a lie the only caller
+* cannot use anyway, it looks tags up by a name that comes from a translation.
+*/
+function resolveValuePropKeys(props) {
 	const result = {};
-	for (const key in props) if (/^_\d+$/.test(key)) result[key.slice(1)] = props[key];
+	for (const key in props) if (key.startsWith("_")) result[key.slice(1)] = props[key];
 	else result[key] = props[key];
 	return result;
 }
@@ -58,14 +69,17 @@ function resolveJsxSafePropKeys(props) {
 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") });
 	const say = GET_SAY();
-	const { whitespace, ...rest } = props;
-	const descriptor = resolveJsxSafePropKeys(rest);
+	const { id, whitespace, ...rest } = props;
+	const values = resolveValuePropKeys(rest);
 	return createElement(Renderer, {
-		html: say.call(descriptor),
+		html: say.call({
+			...rest,
+			id
+		}),
 		whitespace,
 		components(tag) {
-			if (tag && tag in descriptor && isValidElement(descriptor[tag])) {
-				const element = descriptor[tag];
+			if (tag && tag in values && isValidElement(values[tag])) {
+				const element = values[tag];
 				return (props) => cloneElement(element, {
 					...element.props,
 					...props

package/dist/index.server.mjs

@@ -47,9 +47,20 @@ function Renderer({ html, components, whitespace = true }) {
 }
 //#endregion
 //#region src/types.ts
-function resolveJsxSafePropKeys(props) {
+/**
+* Map the props the transform compiled a message's values into back to the
+* identifiers they carry. Every value is emitted with one underscore in front,
+* which is what keeps a numbered identifier a valid prop name and what keeps
+* any name a message chooses out of `Say`'s own namespace, so stripping exactly
+* one is the whole inverse — `_0` is `0`, and `__link` is a tag named `_link`.
+*
+* The result is deliberately not typed as the props that went in: renaming the
+* keys is the point, so claiming they survived would be a lie the only caller
+* cannot use anyway, it looks tags up by a name that comes from a translation.
+*/
+function resolveValuePropKeys(props) {
 	const result = {};
-	for (const key in props) if (/^_\d+$/.test(key)) result[key.slice(1)] = props[key];
+	for (const key in props) if (key.startsWith("_")) result[key.slice(1)] = props[key];
 	else result[key] = props[key];
 	return result;
 }
@@ -58,14 +69,17 @@ function resolveJsxSafePropKeys(props) {
 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") });
 	const say = GET_SAY();
-	const { whitespace, ...rest } = props;
-	const descriptor = resolveJsxSafePropKeys(rest);
+	const { id, whitespace, ...rest } = props;
+	const values = resolveValuePropKeys(rest);
 	return createElement(Renderer, {
-		html: say.call(descriptor),
+		html: say.call({
+			...rest,
+			id
+		}),
 		whitespace,
 		components(tag) {
-			if (tag && tag in descriptor && isValidElement(descriptor[tag])) {
-				const element = descriptor[tag];
+			if (tag && tag in values && isValidElement(values[tag])) {
+				const element = values[tag];
 				return (props) => cloneElement(element, {
 					...element.props,
 					...props

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "React integration for saykit, i18n hooks and components",
   "keywords": [
     "i18n",
@@ -46,11 +46,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.5.0"
+    "saykit": "^0.6.1"
   },
   "peerDependencies": {
     "react": "*",