@saykit/react 0.0.0 → 0.2.0

package/README.md

@@ -0,0 +1,34 @@
+# @saykit/react
+
+> React integration for [SayKit](https://saykit.js.org).
+
+[![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 small server runtime (`setSay`, `getSay`, `unstable_createWithSay`).
+
+## Install
+
+```sh
+pnpm add @saykit/react saykit
+```
+
+You will also need a SayKit build-tool plugin and a `saykit.config.ts`.
+
+## Usage
+
+```tsx
+import { Say, SayProvider } from '@saykit/react/client';
+
+function App() {
+  return (
+    <SayProvider locale="fr" messages={fr}>
+      <Say>Hello, {name}!</Say>
+      <Say.Plural _={count} one="# item" other="# items" />
+    </SayProvider>
+  );
+}
+```
+
+## Documentation
+
+[React integration guide](https://saykit.js.org/integrations/react) at [saykit.js.org](https://saykit.js.org).

package/dist/client.d.mts

@@ -0,0 +1,33 @@
+import * as _$react from "react";
+import { PropsWithChildren } from "react";
+import { ReadonlySay, Say } from "saykit";
+
+//#region src/runtime/client.d.ts
+type SayRef = {
+  current: ReadonlySay | null;
+};
+/**
+ * Provide a localised {@link runtime.Say} instance to descendant **client** components via context.
+ * Must wrap any component tree using {@link useSay} or {@link Say}.
+ *
+ * @param props.locale The current locale
+ * @param props.messages The current messages for the locale
+ */
+declare function SayProvider({
+  locale,
+  messages,
+  children
+}: PropsWithChildren<{
+  locale: string;
+  messages: Say.Messages;
+}>): _$react.FunctionComponentElement<_$react.ProviderProps<SayRef>>;
+/**
+ * Get the current {@link Say} **client** instance.
+ * Must be called within a {@link SayProvider}.
+ *
+ * @returns The current {@link Say} instance
+ * @throws If no provider is in the component tree
+ */
+declare function useSay(): any;
+//#endregion
+export { SayProvider, useSay };

package/dist/client.mjs

@@ -0,0 +1,39 @@
+"use client";
+import { createContext, createElement, useContext, useState } from "react";
+import { Say } from "saykit";
+//#region src/runtime/client.ts
+const SayContext = createContext({ current: null });
+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}.
+*
+* @param props.locale The current locale
+* @param props.messages The current messages for the locale
+*/
+function SayProvider({ locale, messages, children }) {
+	const [say] = useState(() => {
+		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);
+}
+/**
+* Get the current {@link Say} **client** instance.
+* Must be called within a {@link SayProvider}.
+*
+* @returns The current {@link Say} instance
+* @throws If no provider is in the component tree
+*/
+function useSay() {
+	const ref = useContext(SayContext);
+	if (!ref.current) throw new Error("'useSay' must be used within a 'SayProvider'");
+	return ref.current;
+}
+//#endregion
+export { SayProvider, useSay };

package/dist/index.client.mjs

@@ -0,0 +1,92 @@
+"use client"; import { useSay as GET_SAY } from "./client.mjs";import { Fragment, cloneElement, createElement, isValidElement } from "react";
+//#region src/components/renderer.ts
+function Renderer({ html, components, whitespace = true }) {
+	function getComponent(tag) {
+		if (typeof components === "function")
+ /* v8 ignore next */
+		return components(tag) ?? tag ?? Fragment;
+		return tag && tag in components ? components[tag] : Fragment;
+	}
+	let nodeKey = 0;
+	function parseNode(input) {
+		const stack = [];
+		let current = [];
+		let i = 0;
+		while (i < input.length) if (input[i] === "<") {
+			const isClosing = input[i + 1] === "/";
+			const isSelfClosing = input.slice(i, input.indexOf(">", i) + 1).endsWith("/>");
+			const tagStart = i + (isClosing ? 2 : 1);
+			const tagEnd = input.indexOf(">", tagStart);
+			const tagName = input.slice(tagStart, tagEnd).replace("/", "").trim();
+			i = tagEnd + 1;
+			if (isSelfClosing) {
+				const Component = getComponent(tagName);
+				current.push(createElement(Component, { key: nodeKey++ }));
+			} else if (isClosing) {
+				const last = stack.pop();
+				const element = createElement(getComponent(last.tag), { key: nodeKey++ }, ...current);
+				current = last.children;
+				current.push(element);
+			} else {
+				stack.push({
+					tag: tagName,
+					children: current
+				});
+				current = [];
+			}
+		} else {
+			let textEnd = input.indexOf("<", i);
+			if (textEnd === -1) textEnd = input.length;
+			const text = input.slice(i, textEnd);
+			if (whitespace || text.trim() !== "") current.push(text);
+			i = textEnd;
+		}
+		return current;
+	}
+	return createElement(Fragment, void 0, ...parseNode(html));
+}
+//#endregion
+//#region src/types.ts
+function resolveJsxSafePropKeys(props) {
+	const result = {};
+	for (const key in props) if (/^_\d+$/.test(key)) result[key.slice(1)] = props[key];
+	else result[key] = props[key];
+	return result;
+}
+//#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") });
+	const say = GET_SAY();
+	const { whitespace, ...rest } = props;
+	const descriptor = resolveJsxSafePropKeys(rest);
+	return createElement(Renderer, {
+		html: say.call(descriptor),
+		whitespace,
+		components(tag) {
+			if (tag && tag in descriptor && isValidElement(descriptor[tag])) {
+				const element = descriptor[tag];
+				return (props) => cloneElement(element, {
+					...element.props,
+					...props
+				});
+			} else return tag;
+		}
+	});
+}
+(function(_Say) {
+	function Plural(props) {
+		throw new Error("'Say.Plural' is a macro and must be used with the relevant saykit plugin");
+	}
+	_Say.Plural = Plural;
+	function Ordinal(props) {
+		throw new Error("'Say.Ordinal' is a macro and must be used with the relevant saykit plugin");
+	}
+	_Say.Ordinal = Ordinal;
+	function Select(props) {
+		throw new Error("'Say.Select' is a macro and must be used with the relevant saykit plugin");
+	}
+	_Say.Select = Select;
+})(Say || (Say = {}));
+//#endregion
+export { Say };

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+import { PropsWithChildren, ReactElement, ReactNode } from "react";
+import { Disallow, NumeralOptions, SelectOptions } from "saykit";
+
+//#region src/types.d.ts
+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.
+ *
+ * @param descriptor Descriptor to render the translation for
+ * @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<{
+  context?: string;
+  whitespace?: boolean;
+}, 'id'>>): ReactElement;
+declare namespace Say {
+  /**
+   * Define a pluralised message.
+   *
+   * @example
+   * ```tsx
+   * <Say.Plural
+   *   _={count}
+   *   one="You have 1 item"
+   *   other="You have # items"
+   * />
+   * ```
+   *
+   * @param props._ Number to determine the plural form of
+   * @param props Options pluralisation rules keyed by CLDR categories or specific numbers
+   * @returns The plural form of the number, as a React node
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  function Plural(props: {
+    _: number;
+  } & PropsWithJSXSafeKeys<Disallow<NumeralOptions, 'id' | 'context'>>): ReactNode;
+  /**
+   * Define an ordinal message (e.g. "1st", "2nd", "3rd").
+   *
+   * @example
+   * ```tsx
+   * <Say.Ordinal
+   *   _={position}
+   *   1="#st"
+   *   2="#nd"
+   *   3="#rd"
+   *   other="#th"
+   * />
+   * ```
+   *
+   * @param props._ Number to determine the ordinal form of
+   * @param props Options ordinal rules keyed by CLDR categories or specific numbers
+   * @returns The ordinal form of the number, as a React node
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  function Ordinal(props: {
+    _: number;
+  } & PropsWithJSXSafeKeys<Disallow<NumeralOptions, 'id' | 'context'>>): ReactNode;
+  /**
+   * Define a select message, useful for handling gender, status, or other categories.
+   *
+   * @example
+   * ```tsx
+   * <Say.Select
+   *   _={gender}
+   *   male="He"
+   *   female="She"
+   *   other="They"
+   * />
+   * ```
+   *
+   * @param props._ Selector value to determine which option is chosen
+   * @param props Options a mapping of possible selector values to message strings
+   * @returns The select form of the value, as a React node
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  function Select(props: {
+    _: string;
+  } & PropsWithJSXSafeKeys<Disallow<SelectOptions, 'id' | 'context'>>): ReactNode;
+}
+//#endregion
+export { Say };

package/dist/index.server.mjs

@@ -0,0 +1,92 @@
+import { getSay as GET_SAY } from "./server.mjs";import { Fragment, cloneElement, createElement, isValidElement } from "react";
+//#region src/components/renderer.ts
+function Renderer({ html, components, whitespace = true }) {
+	function getComponent(tag) {
+		if (typeof components === "function")
+ /* v8 ignore next */
+		return components(tag) ?? tag ?? Fragment;
+		return tag && tag in components ? components[tag] : Fragment;
+	}
+	let nodeKey = 0;
+	function parseNode(input) {
+		const stack = [];
+		let current = [];
+		let i = 0;
+		while (i < input.length) if (input[i] === "<") {
+			const isClosing = input[i + 1] === "/";
+			const isSelfClosing = input.slice(i, input.indexOf(">", i) + 1).endsWith("/>");
+			const tagStart = i + (isClosing ? 2 : 1);
+			const tagEnd = input.indexOf(">", tagStart);
+			const tagName = input.slice(tagStart, tagEnd).replace("/", "").trim();
+			i = tagEnd + 1;
+			if (isSelfClosing) {
+				const Component = getComponent(tagName);
+				current.push(createElement(Component, { key: nodeKey++ }));
+			} else if (isClosing) {
+				const last = stack.pop();
+				const element = createElement(getComponent(last.tag), { key: nodeKey++ }, ...current);
+				current = last.children;
+				current.push(element);
+			} else {
+				stack.push({
+					tag: tagName,
+					children: current
+				});
+				current = [];
+			}
+		} else {
+			let textEnd = input.indexOf("<", i);
+			if (textEnd === -1) textEnd = input.length;
+			const text = input.slice(i, textEnd);
+			if (whitespace || text.trim() !== "") current.push(text);
+			i = textEnd;
+		}
+		return current;
+	}
+	return createElement(Fragment, void 0, ...parseNode(html));
+}
+//#endregion
+//#region src/types.ts
+function resolveJsxSafePropKeys(props) {
+	const result = {};
+	for (const key in props) if (/^_\d+$/.test(key)) result[key.slice(1)] = props[key];
+	else result[key] = props[key];
+	return result;
+}
+//#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") });
+	const say = GET_SAY();
+	const { whitespace, ...rest } = props;
+	const descriptor = resolveJsxSafePropKeys(rest);
+	return createElement(Renderer, {
+		html: say.call(descriptor),
+		whitespace,
+		components(tag) {
+			if (tag && tag in descriptor && isValidElement(descriptor[tag])) {
+				const element = descriptor[tag];
+				return (props) => cloneElement(element, {
+					...element.props,
+					...props
+				});
+			} else return tag;
+		}
+	});
+}
+(function(_Say) {
+	function Plural(props) {
+		throw new Error("'Say.Plural' is a macro and must be used with the relevant saykit plugin");
+	}
+	_Say.Plural = Plural;
+	function Ordinal(props) {
+		throw new Error("'Say.Ordinal' is a macro and must be used with the relevant saykit plugin");
+	}
+	_Say.Ordinal = Ordinal;
+	function Select(props) {
+		throw new Error("'Say.Select' is a macro and must be used with the relevant saykit plugin");
+	}
+	_Say.Select = Select;
+})(Say || (Say = {}));
+//#endregion
+export { Say };

package/dist/server.d.mts

@@ -0,0 +1,33 @@
+import * as _$react from "react";
+import { ReactNode } from "react";
+import { ReadonlySay, Say } from "saykit";
+//#region src/runtime/server.d.ts
+/**
+ * Set the current {@link Say} **server** instance.
+ * Must be called before any {@link getSay} calls.
+ *
+ * @param say The current {@link Say} instance
+ */
+declare function setSay(say: Say | ReadonlySay | (() => Say | ReadonlySay)): void;
+/**
+ * Get the current {@link Say} **server** instance.
+ * Must only be called after any {@link setSay} calls.
+ *
+ * @returns The current {@link Say} instance
+ * @throws If no {@link Say} instance has been set
+ */
+declare function getSay(): ReadonlySay;
+/**
+ * Create a {@link withSay} higher-order component factory bound to a specific {@link Say} instance.
+ *
+ * @param say The {@link Say} instance to bind into the server context
+ *
+ * @returns A {@link withSay} higher-order component factory
+ */
+declare function unstable_createWithSay(say: Say): <P = unknown>(Component: (props: PropsWithSay<P>) => ReactNode, getLocale: (props: P) => string | Promise<string>) => (props: P) => Promise<_$react.FunctionComponentElement<PropsWithSay<P>>>;
+type PropsWithSay<P = unknown> = P & {
+  locale: string;
+  messages: Say.Messages;
+};
+//#endregion
+export { PropsWithSay, getSay, setSay, unstable_createWithSay };

package/dist/server.mjs

@@ -0,0 +1,56 @@
+import { cache, createElement } from "react";
+import { Say } from "saykit";
+import "server-only";
+//#region src/runtime/server.ts
+const serverContext = cache(() => ({ current: null }));
+/**
+* Set the current {@link Say} **server** instance.
+* Must be called before any {@link getSay} calls.
+*
+* @param say The current {@link Say} instance
+*/
+function setSay(say) {
+	const ref = serverContext();
+	if (say instanceof Say) ref.current = say.clone().freeze();
+	else ref.current = say().clone().freeze();
+}
+/**
+* Get the current {@link Say} **server** instance.
+* Must only be called after any {@link setSay} calls.
+*
+* @returns The current {@link Say} instance
+* @throws If no {@link Say} instance has been set
+*/
+function getSay() {
+	const ref = serverContext();
+	if (!ref.current) throw new Error("Attempt to access the server-only Say instance before initialisation", { cause: /* @__PURE__ */ new Error("'getSay' must be called after 'setSay'") });
+	return ref.current;
+}
+/**
+* Create a {@link withSay} higher-order component factory bound to a specific {@link Say} instance.
+*
+* @param say The {@link Say} instance to bind into the server context
+*
+* @returns A {@link withSay} higher-order component factory
+*/
+function unstable_createWithSay(say) {
+	/**
+	* Wrap a server component so that a {@link Say} instance is initialised before render.
+	*/
+	return function withSay(Component, getLocale) {
+		return async function WithSay(props) {
+			const guess = await getLocale(props);
+			const locale = say.match(guess);
+			await say.load(locale);
+			say.activate(locale);
+			setSay(say);
+			return createElement(Component, {
+				...props,
+				locale: say.locale,
+				messages: say.messages
+			});
+		};
+	};
+}
+//#endregion
+export { getSay, setSay, unstable_createWithSay };

package/package.json

@@ -1,4 +1,63 @@
-{
-  "name": "@saykit/react",
-  "version": "0.0.0"
+{
+  "name": "@saykit/react",
+  "version": "0.2.0",
+  "description": "React integration for saykit, i18n hooks and components",
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "react",
+    "saykit"
+  ],
+  "homepage": "https://github.com/k0d13/saykit#readme",
+  "bugs": {
+    "url": "https://github.com/k0d13/saykit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k0d13/saykit.git",
+    "directory": "packages/integration-react"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "react-server": "./dist/index.server.mjs",
+      "default": "./dist/index.client.mjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.mts",
+      "default": "./dist/client.mjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.mts",
+      "default": "./dist/server.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "saykit": "^0.2.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "saykit": "*"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsdown"
+  }
 }