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

package/README.md

@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.0.0-beta-20260906064714",
+  "version": "0.0.0-beta-20260912200031",
   "description": "React integration for saykit, i18n hooks and components",
   "keywords": [
     "i18n",
@@ -53,11 +53,11 @@
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "saykit": "^0.0.0-beta-20260906064714"
+    "saykit": "^0.0.0-beta-20260912200031"
   },
   "peerDependencies": {
     "react": "*",
-    "saykit": "0.0.0-beta-20260906064714"
+    "saykit": "0.0.0-beta-20260912200031"
   },
   "scripts": {
     "check": "tsc --noEmit",