@saykit/react 0.0.0-beta-20260911005306 → 0.0.0-beta-20261017001906

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/client.d.mts

@@ -17,14 +17,17 @@ type SayProviderProps = {
   store: Store;
   locale?: never;
   messages?: never;
+  options?: never;
 } | {
   store?: never;
   locale: string;
   messages: View.Messages;
+  options?: View.Options;
 } | {
   store?: never;
   locale?: never;
   messages?: never;
+  options?: never;
 };
 /**
  * Provide a {@link View} to descendant **client** components via context.
@@ -36,8 +39,10 @@ type SayProviderProps = {
  *   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
+ * @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, children }: PropsWithChildren<SayProviderProps>): import("react").FunctionComponentElement<import("react").ProviderProps<any>>;
+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}.

package/dist/client.mjs

@@ -4,15 +4,17 @@ import { createCatalogue, createStore } from "saykit";
 //#region src/runtime/client.ts
 const SayContext = createContext(null);
 SayContext.displayName = "SayContext";
-function SayProvider({ store, locale, messages, children }) {
+function SayProvider({ store, locale, messages, options, children }) {
+	const bidiIsolation = options?.bidiIsolation;
 	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);
+		return createStore(createCatalogue({ [locale]: messages }, { bidiIsolation }), locale);
 	}, [
 		store,
 		locale,
-		messages
+		messages,
+		bidiIsolation
 	]);
 	return createElement(SayContext.Provider, { value: held }, children);
 }

package/dist/client.server.d.mts

@@ -6,10 +6,10 @@ 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
- * 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.
+ * 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.
  */
 declare function SayProvider({ children }: {
   children?: ReactNode;

package/dist/client.server.mjs

@@ -7,7 +7,8 @@ function SayProvider({ children }) {
 	const say = getSay();
 	return createElement(SayProvider$1, {
 		locale: say.locale,
-		messages: say.messages
+		messages: say.messages,
+		options: say.options
 	}, children);
 }
 //#endregion

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

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/react",
-  "version": "0.0.0-beta-20260911005306",
+  "version": "0.0.0-beta-20261017001906",
   "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-20260911005306"
+    "saykit": "^0.0.0-beta-20261017001906"
   },
   "peerDependencies": {
     "react": "*",
-    "saykit": "0.0.0-beta-20260911005306"
+    "saykit": "0.0.0-beta-20261017001906"
   },
   "scripts": {
     "check": "tsc --noEmit",