@fanee/react 0.6.0

package/README.md

@@ -0,0 +1,79 @@
+# @fanee/react
+
+React bindings for Fanee.
+
+Provides a Context-based provider and hooks to consume a `FaneeRuntime` from `@fanee/core` inside a React component tree.
+
+## Installation
+
+```bash
+npm install @fanee/core @fanee/react
+```
+
+## Quick Start
+
+```tsx
+import { FaneeRuntime } from "@fanee/core";
+import { FaneeProvider, useT, useLocale, useSetLocale } from "@fanee/react";
+
+const runtime = new FaneeRuntime().config({
+	defaultLocale: "en",
+	currentLocale: "en",
+	resources: {
+		"": {
+			en: { hello: "Hello, {name}!" },
+			fr: { hello: "Bonjour, {name}!" },
+		},
+	},
+});
+
+function App() {
+	return (
+		<FaneeProvider runtime={runtime}>
+			<Greeting />
+		</FaneeProvider>
+	);
+}
+
+function Greeting() {
+	const t = useT();
+	const locale = useLocale();
+	const setLocale = useSetLocale();
+
+	return (
+		<div>
+			<p>{t("hello", { name: "World" })}</p>
+			<p>Current locale: {locale}</p>
+			<button onClick={() => setLocale(locale === "en" ? "fr" : "en")}>
+				Switch locale
+			</button>
+		</div>
+	);
+}
+```
+
+## API
+
+### `FaneeProvider`
+
+Wraps your app and exposes a `FaneeRuntime` instance to descendant hooks.
+
+### `useT(context?)`
+
+Returns a bound translate function. Re-renders when the locale, namespace, or resources change.
+
+### `useLocale()`
+
+Returns the active locale.
+
+### `useSetLocale()`
+
+Returns a function to update the active locale.
+
+### `useFanee()`
+
+Returns `{ runtime, locale }` for direct access to the runtime instance.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { ReactNode } from "react";
+import { FaneeRuntime, Locale, TranslateContext, TranslateFunction } from "@fanee/core";
+
+//#region src/provider.d.ts
+interface FaneeProviderProps {
+  /** FaneeRuntime instance to expose to the React tree. */
+  runtime: FaneeRuntime;
+  /** React children. */
+  children: ReactNode;
+}
+/**
+ * Provides a FaneeRuntime instance to descendant components.
+ *
+ * @example
+ * ```tsx
+ * const runtime = new FaneeRuntime().config({ currentLocale: "en" });
+ *
+ * <FaneeProvider runtime={runtime}>
+ *   <App />
+ * </FaneeProvider>
+ * ```
+ */
+declare function FaneeProvider({
+  runtime,
+  children
+}: FaneeProviderProps): import("react").JSX.Element;
+/** @internal */
+declare function useRuntime(): FaneeRuntime;
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Subscribe to the Fanee runtime and access it alongside the current locale.
+ *
+ * @returns An object with the runtime and the active locale.
+ *
+ * @example
+ * ```tsx
+ * const { runtime, locale } = useFanee();
+ * ```
+ */
+declare function useFanee(): {
+  runtime: ReturnType<typeof useRuntime>;
+  locale: Locale;
+};
+/**
+ * Return a translation function bound to the current runtime state and
+ * an optional namespace/locale context.
+ *
+ * The returned function is recreated whenever the active locale, namespace,
+ * or underlying resources change, so it remains reactive to runtime updates.
+ *
+ * @param context - Optional locale/namespace overrides.
+ * @returns A `(key, vars?) => string` translate function.
+ *
+ * @example
+ * ```tsx
+ * const t = useT({ namespace: "errors" });
+ * return <p>{t("not_found")}</p>;
+ * ```
+ */
+declare function useT(context?: Partial<TranslateContext>): TranslateFunction;
+/**
+ * Read the currently active locale from the runtime.
+ *
+ * @returns The BCP-47 locale tag.
+ */
+declare function useLocale(): Locale;
+/**
+ * Return a setter for the runtime locale.
+ *
+ * @returns A function that updates the active locale.
+ */
+declare function useSetLocale(): (locale: Locale) => void;
+//#endregion
+export { FaneeProvider, type FaneeProviderProps, useFanee, useLocale, useSetLocale, useT };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/provider.tsx","../src/hooks.ts"],"mappings":";;;;UAKiB,kBAAA;;EAEhB,OAAA,EAAS,YAAA;EAFyB;EAIlC,QAAA,EAAU,SAAS;AAAA;;;;;;AAAA;AAepB;;;;;;iBAAgB,aAAA;EAAgB,OAAA;EAAS;AAAA,GAAY,kBAAA,mBAAkB,GAAA,CAAA,OAAA;;iBAKvD,UAAA,IAAc,YAAY;;;;;AAxB1C;;;;;;;;iBCsBgB,QAAA;EAAc,OAAA,EAAS,UAAA,QAAkB,UAAA;EAAa,MAAA,EAAQ,MAAA;AAAA;;;;;;;;;;;;;;;ADHP;AAKvE;iBCoBgB,IAAA,CAAK,OAAA,GAAU,OAAA,CAAQ,gBAAA,IAAoB,iBAAA;;;ADpBjB;;;iBCyC1B,SAAA,IAAa,MAAM;AA3CnC;;;;;AAAA,iBAsDgB,YAAA,KAAiB,MAAc,EAAN,MAAM"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import{createContext as e,useCallback as t,useContext as n,useEffect as r,useMemo as i,useReducer as a}from"react";import{jsx as o}from"react/jsx-runtime";const s=e(null);function c({runtime:e,children:t}){return o(s.Provider,{value:e,children:t})}function l(){let e=n(s);if(!e)throw Error(`[fanee] Fanee hooks must be used within a FaneeProvider`);return e}function u(){let e=l(),[t,n]=a(e=>e+1,0);return r(()=>e.subscribe(()=>{n()}),[e]),t}function d(){let e=l(),t=p();return i(()=>({runtime:e,locale:t}),[e,t])}function f(e){let n=l(),r=u(),i=e?.locale,a=e?.namespace;return t((e,t)=>n.getT({locale:i,namespace:a})(e,t),[n,i,a,r])}function p(){let e=l();return u(),e.getLocale()}function m(){let e=l();return t(t=>e.setLocale(t),[e])}export{c as FaneeProvider,d as useFanee,p as useLocale,m as useSetLocale,f as useT};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/provider.tsx","../src/hooks.ts"],"sourcesContent":["import { createContext, useContext, type ReactNode } from \"react\";\nimport type { FaneeRuntime } from \"@fanee/core\";\n\nconst FaneeContext = createContext<FaneeRuntime | null>(null);\n\nexport interface FaneeProviderProps {\n\t/** FaneeRuntime instance to expose to the React tree. */\n\truntime: FaneeRuntime;\n\t/** React children. */\n\tchildren: ReactNode;\n}\n\n/**\n * Provides a FaneeRuntime instance to descendant components.\n *\n * @example\n * ```tsx\n * const runtime = new FaneeRuntime().config({ currentLocale: \"en\" });\n *\n * <FaneeProvider runtime={runtime}>\n *   <App />\n * </FaneeProvider>\n * ```\n */\nexport function FaneeProvider({ runtime, children }: FaneeProviderProps) {\n\treturn <FaneeContext.Provider value={runtime}>{children}</FaneeContext.Provider>;\n}\n\n/** @internal */\nexport function useRuntime(): FaneeRuntime {\n\tconst runtime = useContext(FaneeContext);\n\tif (!runtime) {\n\t\tthrow new Error(\"[fanee] Fanee hooks must be used within a FaneeProvider\");\n\t}\n\treturn runtime;\n}\n","import { useCallback, useEffect, useReducer, useMemo } from \"react\";\nimport type { Locale, MessageKey, TranslateContext, TranslateFunction } from \"@fanee/core\";\nimport { useRuntime } from \"./provider\";\n\nfunction useRuntimeVersion(): number {\n\tconst runtime = useRuntime();\n\tconst [version, bump] = useReducer((v: number) => v + 1, 0);\n\n\tuseEffect(() => {\n\t\treturn runtime.subscribe(() => {\n\t\t\tbump();\n\t\t});\n\t}, [runtime]);\n\n\treturn version;\n}\n\n/**\n * Subscribe to the Fanee runtime and access it alongside the current locale.\n *\n * @returns An object with the runtime and the active locale.\n *\n * @example\n * ```tsx\n * const { runtime, locale } = useFanee();\n * ```\n */\nexport function useFanee(): { runtime: ReturnType<typeof useRuntime>; locale: Locale } {\n\tconst runtime = useRuntime();\n\tconst locale = useLocale();\n\treturn useMemo(() => ({ runtime, locale }), [runtime, locale]);\n}\n\n/**\n * Return a translation function bound to the current runtime state and\n * an optional namespace/locale context.\n *\n * The returned function is recreated whenever the active locale, namespace,\n * or underlying resources change, so it remains reactive to runtime updates.\n *\n * @param context - Optional locale/namespace overrides.\n * @returns A `(key, vars?) => string` translate function.\n *\n * @example\n * ```tsx\n * const t = useT({ namespace: \"errors\" });\n * return <p>{t(\"not_found\")}</p>;\n * ```\n */\nexport function useT(context?: Partial<TranslateContext>): TranslateFunction {\n\tconst runtime = useRuntime();\n\tconst version = useRuntimeVersion();\n\tconst locale = context?.locale;\n\tconst namespace = context?.namespace;\n\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: version forces update on resource changes\n\treturn useCallback(\n\t\t(key: MessageKey, vars?: Record<string, unknown>) => {\n\t\t\tconst result = runtime.getT({ locale, namespace })(key, vars);\n\t\t\treturn result;\n\t\t},\n\t\t[runtime, locale, namespace, version]\n\t);\n}\n\n/**\n * Read the currently active locale from the runtime.\n *\n * @returns The BCP-47 locale tag.\n */\nexport function useLocale(): Locale {\n\tconst runtime = useRuntime();\n\tuseRuntimeVersion();\n\treturn runtime.getLocale();\n}\n\n/**\n * Return a setter for the runtime locale.\n *\n * @returns A function that updates the active locale.\n */\nexport function useSetLocale(): (locale: Locale) => void {\n\tconst runtime = useRuntime();\n\treturn useCallback((locale: Locale) => runtime.setLocale(locale), [runtime]);\n}\n"],"mappings":"2JAGA,MAAM,EAAe,EAAmC,IAAI,EAqB5D,SAAgB,EAAc,CAAE,UAAS,YAAgC,CACxE,OAAO,EAAC,EAAa,SAAd,CAAuB,MAAO,EAAU,UAAgC,CAAA,CAChF,CAGA,SAAgB,GAA2B,CAC1C,IAAM,EAAU,EAAW,CAAY,EACvC,GAAI,CAAC,EACJ,MAAU,MAAM,yDAAyD,EAE1E,OAAO,CACR,CC/BA,SAAS,GAA4B,CACpC,IAAM,EAAU,EAAW,EACrB,CAAC,EAAS,GAAQ,EAAY,GAAc,EAAI,EAAG,CAAC,EAQ1D,OANA,MACQ,EAAQ,cAAgB,CAC9B,EAAK,CACN,CAAC,EACC,CAAC,CAAO,CAAC,EAEL,CACR,CAYA,SAAgB,GAAuE,CACtF,IAAM,EAAU,EAAW,EACrB,EAAS,EAAU,EACzB,OAAO,OAAe,CAAE,UAAS,QAAO,GAAI,CAAC,EAAS,CAAM,CAAC,CAC9D,CAkBA,SAAgB,EAAK,EAAwD,CAC5E,IAAM,EAAU,EAAW,EACrB,EAAU,EAAkB,EAC5B,EAAS,GAAS,OAClB,EAAY,GAAS,UAG3B,OAAO,GACL,EAAiB,IACF,EAAQ,KAAK,CAAE,SAAQ,WAAU,CAAC,CAAC,CAAC,EAAK,CAC5C,EAEb,CAAC,EAAS,EAAQ,EAAW,CAAO,CACrC,CACD,CAOA,SAAgB,GAAoB,CACnC,IAAM,EAAU,EAAW,EAE3B,OADA,EAAkB,EACX,EAAQ,UAAU,CAC1B,CAOA,SAAgB,GAAyC,CACxD,IAAM,EAAU,EAAW,EAC3B,OAAO,EAAa,GAAmB,EAAQ,UAAU,CAAM,EAAG,CAAC,CAAO,CAAC,CAC5E"}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@fanee/react",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"version": "0.6.0",
+	"type": "module",
+	"private": false,
+	"license": "MIT",
+	"repository": {
+		"url": "https://github.com/project-cvsa/fanee"
+	},
+	"scripts": {
+		"build": "bunx --bun tsdown",
+		"lint": "bunx --bun biome lint",
+		"test": "bun test --preload ./tests/setup.ts",
+		"test:coverage": "bun test --preload ./tests/setup.ts --coverage",
+		"typecheck": "bunx --bun tsgo --noEmit"
+	},
+	"peerDependencies": {
+		"react": ">=18"
+	},
+	"dependencies": {
+		"@fanee/core": "workspace:*"
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.0.0",
+		"@types/bun": "latest",
+		"@types/react": "^19.2.14",
+		"happy-dom": "^17.0.0",
+		"react": "^19.2.6",
+		"react-dom": "^19.2.7",
+		"tsdown": "^0.22.2"
+	},
+	"files": [
+		"dist/"
+	]
+}