langsys-js-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+## 0.1.0 - 2026-05-29
+
+Initial release. `langsys-js-react` is a thin React binding over the framework-agnostic [`langsys-js-typescript`](https://github.com/langsys/langsys-js-typescript) package — the React sibling of `langsys-js-svelte`. The base SDK owns the API client, translation lifecycle, token discovery, DOM tokenizer, and SSR-aware token strategies; this package adds only the React-native concerns.
+
+### Added
+
+- **`LangsysApp`** — wrapper whose `init` accepts a `Signal<string>` as `UserLocaleStore` and delegates every other method to the base SDK singleton.
+- **Hooks** built on `useSyncExternalStore`:
+    - `useT()` — returns the current `TFunction`; re-renders the component whenever translations or the loaded locale change. Signature `t(phrase, category?, params?)`.
+    - `useCurrentLocale()` — the locale whose translations are currently loaded.
+    - `useTranslations()` — the raw translation catalog.
+    - `useLocaleStore(initial?)` — creates one stable user-locale `Signal<string>`, reads it reactively, and returns `[locale, setLocale, store]`.
+    - `useSignal(signal)` — low-level bridge from any base-SDK `Signal<T>` to a reactive value.
+- **`createLocaleStore(initial?)`** — make a user-locale store outside React (the analog of Svelte's `writable`).
+- **`<Translate>`** — React component wrapping the base SDK's vanilla DOM `Translate` class via a ref + mount/destroy effect. Props: `category?`, `custom_id?`, `label?`, `tag?` (default `translate`), `className?`, `children`.
+- **Raw signal re-exports** — `t` (the base SDK's `tSignal`), `currentlyLoadedLocale`, `sTranslations`, plus `createSignal`, for direct subscription outside React.
+- **`{name}`-style placeholder interpolation** with compile-time-checked params via template-literal types. Allowed value types: `string | number | Date | boolean`; `Date` serializes to ISO 8601.
+- **Type re-exports** sourced from `langsys-js-typescript`: `TFunction`, `TranslationParams`, `ParamPrimitive`, `ExtractParamKeys`, `ParamsFor`, `TArgs`, `Signal`, `iLangsysInitConfig` (React-flavored), `iLangsysResponse`, `iCategories`, `iTranslations`, `iContentBlock`, `iCountry`, `iCountryDialCode`, `iCountryList`, `iCurrency`, `iCurrencyList`, `iLanguageName`, `iLocaleData`, `iLocaleDefault`, `iLocaleFlat`, `iProject`.
+- **`LangsysAppAPI`** re-export for direct (vanilla) API access.
+- **`README-SSR.md`** documenting Next.js App Router and Pages Router usage.
+- **`example/`** — a Vite playground (`npm run dev`) demonstrating `useT`, interpolation, categorization, locale switching, and `<Translate>`.
+
+### Tooling
+
+- Built with `tsup` (ESM + CJS + `.d.ts`), matching `langsys-js-typescript`.
+- `react` (`^18 || ^19`) is a peer dependency.
+- CI (`typecheck` + `test`) and trusted-publishing release workflow mirror the Langsys SDK family.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Flexark International Ltda.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-SSR.md

@@ -0,0 +1,249 @@
+# SSR Usage Guide (Next.js / Remix)
+
+This guide shows how to use `langsys-js-react` with Server-Side Rendering (SSR) to eliminate duplicate API calls and improve performance.
+
+## The problem
+
+In a traditional SSR flow:
+1. The server fetches translations during render.
+2. The client re-fetches the same translations after hydration.
+3. Duplicate API calls, slower initial render, possible flash of untranslated content.
+
+## The solution
+
+Pass pre-fetched translations from server to client using the `initialTranslations` config option. The client SDK uses them as-is and skips the initial fetch. Because the hooks are built on `useSyncExternalStore` with a server snapshot, the first paint already reflects the seeded translations.
+
+## Next.js — App Router
+
+### Step 1: Fetch translations on the server
+
+```tsx
+// app/layout.tsx (Server Component)
+import type { iCategories } from 'langsys-js-react';
+import { LangsysClient } from './LangsysClient';
+
+async function getTranslations(locale: string): Promise<iCategories> {
+    const res = await fetch(
+        `https://api.langsys.dev/api/projects/${process.env.LANGSYS_PROJECT_ID}/translations?locale=${locale}`,
+        { headers: { 'x-Authorization': process.env.LANGSYS_API_KEY!, 'Content-Type': 'application/json' } }
+    );
+    const result = await res.json();
+    return result.data as iCategories;
+}
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+    const locale = 'en'; // from cookie / Accept-Language / route segment
+    const translations = await getTranslations(locale);
+
+    return (
+        <html lang={locale}>
+            <body>
+                <LangsysClient
+                    locale={locale}
+                    translations={translations}
+                    projectId={process.env.LANGSYS_PROJECT_ID!}
+                    apiKey={process.env.NEXT_PUBLIC_LANGSYS_API_KEY!} // read-only key for the client
+                >
+                    {children}
+                </LangsysClient>
+            </body>
+        </html>
+    );
+}
+```
+
+### Step 2: Initialize on the client
+
+```tsx
+// app/LangsysClient.tsx
+'use client';
+
+import { useEffect, useState, type ReactNode } from 'react';
+import { LangsysApp, useLocaleStore, type iCategories } from 'langsys-js-react';
+
+export function LangsysClient({
+    locale,
+    translations,
+    projectId,
+    apiKey,
+    children,
+}: {
+    locale: string;
+    translations: iCategories;
+    projectId: string;
+    apiKey: string;
+    children: ReactNode;
+}) {
+    const [, , localeStore] = useLocaleStore(locale);
+
+    useEffect(() => {
+        LangsysApp.init({
+            projectid: projectId,
+            key: apiKey,
+            UserLocaleStore: localeStore,
+            baseLocale: 'en',
+            initialTranslations: translations,
+            initialTranslationsLocale: locale,
+            ssrTokenStrategy: 'client',
+        });
+    }, [localeStore, projectId, apiKey, translations, locale]);
+
+    return <>{children}</>;
+}
+```
+
+### Step 3: Use translations in any client component
+
+```tsx
+'use client';
+import { useT } from 'langsys-js-react';
+
+export function Hero() {
+    const t = useT();
+    return (
+        <>
+            <h1>{t('Welcome', 'HomePage')}</h1>
+            <p>{t('Hello, {name}!', 'HomePage', { name: 'Sarah' })}</p>
+        </>
+    );
+}
+```
+
+## Next.js — Pages Router
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import { useEffect } from 'react';
+import { LangsysApp, useLocaleStore } from 'langsys-js-react';
+
+export default function App({ Component, pageProps }: AppProps) {
+    const locale = pageProps.locale ?? 'en';
+    const [, , localeStore] = useLocaleStore(locale);
+
+    useEffect(() => {
+        LangsysApp.init({
+            projectid: process.env.NEXT_PUBLIC_LANGSYS_PROJECT_ID!,
+            key: process.env.NEXT_PUBLIC_LANGSYS_API_KEY!,
+            UserLocaleStore: localeStore,
+            baseLocale: 'en',
+            initialTranslations: pageProps.translations,
+            initialTranslationsLocale: locale,
+        });
+    }, [localeStore, pageProps.translations, locale]);
+
+    return <Component {...pageProps} />;
+}
+```
+
+```tsx
+// pages/index.tsx — fetch translations in getServerSideProps
+import type { iCategories } from 'langsys-js-react';
+
+export async function getServerSideProps() {
+    const locale = 'en';
+    const res = await fetch(
+        `https://api.langsys.dev/api/projects/${process.env.LANGSYS_PROJECT_ID}/translations?locale=${locale}`,
+        { headers: { 'x-Authorization': process.env.LANGSYS_API_KEY!, 'Content-Type': 'application/json' } }
+    );
+    const { data } = await res.json();
+    return { props: { locale, translations: data as iCategories } };
+}
+```
+
+## Locale switching
+
+Update the store from the same `useLocaleStore` call; the SDK reacts and fetches the new locale's translations:
+
+```tsx
+'use client';
+import { LangsysApp, useLocaleStore } from 'langsys-js-react';
+
+export function LocaleSwitcher() {
+    const [locale, setLocale] = useLocaleStore('en');
+
+    function changeLocale(next: string) {
+        setLocale(next); // subscribers in the SDK trigger a fetch
+        return LangsysApp.translationsLoadingPromise; // optional: await the in-flight fetch
+    }
+
+    return (
+        <select value={locale} onChange={(e) => changeLocale(e.target.value)}>
+            <option value="en">English</option>
+            <option value="es">Español</option>
+            <option value="fr">Français</option>
+        </select>
+    );
+}
+```
+
+> Keep one locale store for the app (created where you call `init`) and thread `setLocale` down via context or props, rather than calling `useLocaleStore` with a fresh initial value in unrelated trees.
+
+## Benefits
+
+### Performance
+- No duplicate API calls (server + client).
+- Translations ready immediately on hydration.
+- Faster Time to Interactive (TTI).
+- Reduced API usage and costs.
+
+### User experience
+- No flash of untranslated content.
+- Instant translation display.
+- Better SEO with server-rendered translations.
+
+### Developer experience
+- Simple configuration.
+- Full TypeScript support, including compile-time-checked interpolation params on `t()`.
+
+## Configuration options
+
+### SSR token strategy
+
+```typescript
+{ ssrTokenStrategy: 'client' | 'server' | 'auto' }
+```
+
+- `'client'` (default) — queue tokens, send from client after hydration.
+- `'server'` — send tokens immediately from server.
+- `'auto'` — small batches (≤5) from server, larger batches from client.
+
+### Debug mode
+
+```typescript
+{ debug: true, initialTranslations: translations, initialTranslationsLocale: locale }
+```
+
+Look for:
+- `SSR initial translations config:` on init — confirms pre-fetched data is detected.
+- `Using pre-fetched translations for locale` — confirms the initial fetch was skipped.
+- `Locale change detected!` — fires on a subsequent locale switch.
+
+## Important notes
+
+1. **One-time use.** `initialTranslations` is consumed only at init. Locale changes after init go through the normal fetch path.
+2. **Matching locales.** Always provide `initialTranslationsLocale` with `initialTranslations` so the SDK knows what locale the data represents.
+3. **Data format.** The translations payload must match the `iCategories` shape returned by `LangsysAppAPI.getTranslations()`.
+4. **Cache.** The 60-second locale cache still applies. Pre-fetched translations count as cached.
+5. **Token creation.** Use a read-only API key for the client in production — missing tokens won't be sent. Keep the write key on the server (and ideally pre-populate tokens via your local dev environment).
+6. **`'use client'`.** `useT`, `useLocaleStore`, `<Translate>`, and `LangsysApp.init` run on the client — keep them in Client Components.
+
+## Troubleshooting
+
+### Translations not appearing
+- Check that `initialTranslationsLocale` matches the `UserLocaleStore` value at init.
+- Verify the translations payload matches the `iCategories` shape.
+- Enable `debug: true` and look for the messages above.
+
+### Still seeing duplicate API calls
+- Confirm both `initialTranslations` *and* `initialTranslationsLocale` are passed.
+- Confirm init runs before any rendering that calls `t(...)`.
+- Confirm the locale hasn't drifted between server and client.
+
+### Hydration mismatch warnings
+- Make sure the `locale` you seed on the server matches the initial value you pass to `useLocaleStore` on the client.
+- Keep `LangsysApp.init` inside `useEffect` (client-only) so the server render and the first client render agree.
+
+### TypeScript errors on `t()`
+- Placeholders are compile-time-checked: `t('Hello, {name}!', 'Cat')` *requires* a params object with `name`. Either add the key or remove the placeholder.
+- Allowed param value types: `string | number | Date | boolean`.

package/README.md

@@ -0,0 +1,254 @@
+# Langsys SDK - React
+
+Langsys revolutionizes localization for apps with easy to integrate, realtime, continuous translations. Read more about Langsys Translation Manager [at the website](https://Langsys.dev/).
+
+Integrate the Langsys Translation Manager into your React, Next.js, Remix, or Vite applications using this SDK.
+
+## Requirements
+
+- **React 18 or 19** (the reactive layer is built on `useSyncExternalStore`).
+
+[![GitHub Release](https://img.shields.io/github/release/langsys/langsys-js-react.svg?style=flat)]()
+[![GitHub last commit](https://img.shields.io/github/last-commit/langsys/langsys-js-react.svg?style=flat)]()
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/langsys/langsys-js-react.svg?style=flat)]()
+[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
+[![NPM License](https://img.shields.io/npm/l/all-contributors.svg?style=flat)](https://github.com/langsys/langsys-js-react/blob/main/LICENSE)
+
+## How it's layered
+
+`langsys-js-react` is a thin React binding over the framework-agnostic [`langsys-js-typescript`](https://github.com/langsys/langsys-js-typescript) package — which owns the API client, translation lifecycle, token discovery, DOM tokenizer, and SSR-aware token strategies. This package adds only the React-native concerns:
+
+- A `LangsysApp` whose `init` accepts a `Signal<string>` (made with `createLocaleStore`) for the user locale
+- Hooks — `useT`, `useCurrentLocale`, `useTranslations`, `useLocaleStore` — that re-render components when translations or the loaded locale change
+- A `<Translate>` component wrapping the underlying DOM walker
+
+If you need the SDK outside React (a Node script, a non-React web app), import from `langsys-js-typescript` directly.
+
+## Install
+
+```bash
+npm install langsys-js-react
+```
+
+`langsys-js-typescript` is installed automatically as a transitive dependency. `react` is a peer dependency you already have.
+
+## Creating a Langsys project
+
+Visit [Langsys.dev](https://Langsys.dev/) to create your account, then create your project. Take note of your project ID and API key.
+
+### API key permissions
+
+- **Write key** (development): the SDK auto-creates new translation tokens and content blocks as they appear in your app.
+- **Read-only key** (production): the SDK fetches translations only — no token creation, no content-block writes.
+
+The SDK detects the key type automatically and behaves accordingly.
+
+## Initialization
+
+Initialize once, high in your tree. Create the user-locale store with `useLocaleStore` and pass it to `LangsysApp.init`:
+
+```tsx
+// src/LangsysProvider.tsx
+import { useEffect, useState, type ReactNode } from 'react';
+import { LangsysApp, useLocaleStore } from 'langsys-js-react';
+
+export function LangsysGate({ children }: { children: ReactNode }) {
+    const [, , localeStore] = useLocaleStore('en-us');
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    useEffect(() => {
+        LangsysApp.init({
+            projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
+            key: import.meta.env.VITE_LANGSYS_API_KEY,
+            UserLocaleStore: localeStore,
+            baseLocale: 'en-us',
+            debug: false,
+            ssrTokenStrategy: 'client',
+        }).then((res) => {
+            if (res.status) setReady(true);
+            else setError(res.errors?.join(', ') ?? 'Init failed');
+        });
+    }, [localeStore]);
+
+    if (error) return <p>Langsys init failed: {error}</p>;
+    if (!ready) return <p>Loading…</p>;
+    return <>{children}</>;
+}
+```
+
+`UserLocaleStore` is a `Signal<string>` — switch it with `setLocale(...)` (from the same `useLocaleStore` call) or `localeStore.set('fr-fr')`, and the SDK reacts. If you'd rather keep the locale store at module scope, `const localeStore = createLocaleStore('en-us')` works too.
+
+### SSR token strategy
+
+`ssrTokenStrategy` (default `'client'`) controls when missing tokens are sent during server rendering:
+
+- `'client'` — tokens collected on the server are flushed from the client after hydration. Best for performance.
+- `'server'` — tokens are sent immediately during SSR. Best for reliability and immediate registration.
+- `'auto'` — small batches (≤5) sent from server, larger queued for client.
+
+## Using translations
+
+### `useT()` — the everyday API
+
+`useT()` returns the current translation function and re-renders the component whenever translations or the loaded locale change.
+
+```tsx
+import { useT } from 'langsys-js-react';
+
+function Welcome() {
+    const t = useT();
+    return (
+        <>
+            <h1>{t('Welcome to my app', 'UI')}</h1>
+            <p>{t('Hello, {name}!', 'UI', { name: 'Sarah' })}</p>
+        </>
+    );
+}
+```
+
+The translation function signature is **`t(phrase, category?, params?)`**:
+
+```tsx
+t('Save');                                  // no category, no params
+t('Save', 'UI');                            // categorized
+t('Hello, {name}!', { name: 'X' });         // no category, with params
+t('Hello, {name}!', 'Greetings', { name: 'X' }); // category + params
+```
+
+The **phrase itself is the lookup key** *and* the base-language default — there's no separate keys file to maintain. The first render of a phrase registers it in the Translation Manager (when using a write key); from then on, translations are fetched and rendered automatically as locales change.
+
+#### Interpolation
+
+Curly-brace placeholders are substituted from the params argument:
+
+```tsx
+t('You have {count} new messages', 'Notifications', { count: 3 });
+```
+
+Placeholder names are extracted from the phrase at compile time and **type-checked**: omitting a required key or adding an extra one is a TypeScript error.
+
+```tsx
+t('You have {count} new messages', 'Notifications', {});
+// ❌ Property 'count' is missing in type '{}'
+
+t('You have {count} new messages', 'Notifications', { count: 3, extra: 'x' });
+// ❌ Object literal may only specify known properties, and 'extra' does not exist
+```
+
+Allowed value types: `string | number | Date | boolean`. Dates serialize to ISO 8601.
+
+> Future versions will swap the simple `{name}` runtime for ICU MessageFormat — adding plural / select / date formatting — without changing the public signature. Today's `t('{count} items', 'Cart', { count })` will evolve to `t('{count, plural, one {# item} other {# items}}', 'Cart', { count })`.
+
+#### Categorization disambiguates context
+
+Different categories give the *same* phrase different translations:
+
+```tsx
+<strong>{t('Home', 'Main Menu')}</strong>     {/* "Inicio" in Spanish */}
+<strong>{t('Home', 'Home repairs')}</strong>  {/* "Hogar" in Spanish */}
+```
+
+Without categorization, "Home" would only have one translation — which can't work for both contexts. Langsys's philosophy is *translate once, use everywhere*; categorize when the same phrase legitimately means different things.
+
+A good rule for category names: the module or feature the phrase lives in (`Account`, `Errors`, `Checkout`, `UI`).
+
+### `<Translate>` — HTML content blocks
+
+For larger blocks of HTML where the structure should be preserved for the translator:
+
+```tsx
+import { Translate } from 'langsys-js-react';
+
+function Article() {
+    return (
+        <Translate category="Blog" tag="article">
+            <h1 className="title">My article title</h1>
+            <p>My content <strong>is the best</strong> when internationalized by Langsys.</p>
+            <p>Translators see this exactly as users do — same styling, same structure.</p>
+        </Translate>
+    );
+}
+```
+
+The component:
+- Recursively tokenizes text nodes and translatable attributes (`placeholder`, `alt`, `title`, `aria-label`, plus button/input `value` attributes and `<option>` text).
+- Captures semantic CSS so translators see the styled appearance in the Translation Manager.
+- Registers the whole thing as a **content block** that translators handle as one unit while still translating the individual phrases inside.
+- Auto re-translates on locale change.
+
+`<Translate>` mounts the SDK's DOM walker on its host element and lets it mutate the rendered output in place, so **keep its children static** — prose, marketing copy, CMS-rendered articles, forms with placeholders. For dynamic per-string values that React owns, use `useT()`.
+
+```tsx
+{/* CMS content goes through Translate as-is */}
+<Translate category="News" tag="div">
+    <div dangerouslySetInnerHTML={{ __html: article?.content ?? '' }} />
+</Translate>
+```
+
+`<Translate>` props: `category?`, `custom_id?`, `label?`, `tag?` (defaults to `translate`), `className?`, `children`.
+
+## Hooks & reactive primitives
+
+| Export | Type | Notes |
+|---|---|---|
+| `useT()` | `() => TFunction` | Re-renders on translations/locale change. Call as `const t = useT(); t('Phrase', 'Cat', params?)`. |
+| `useCurrentLocale()` | `() => string` | The locale whose translations are currently loaded (lags the user-selected locale until the fetch completes). |
+| `useTranslations()` | `() => iCategories` | Raw translation catalog. Rarely needed in app code. |
+| `useLocaleStore(initial?)` | `() => [locale, setLocale, store]` | Creates a stable user-locale `Signal<string>`, reads it reactively, returns a setter. Pass `store` to `init`. |
+| `useSignal(signal)` | `<T>(s: Signal<T>) => T` | Low-level: subscribe a component to any base-SDK signal. |
+| `createLocaleStore(initial?)` | `(s?: string) => Signal<string>` | Make a user-locale store outside React (module scope). |
+| `t` / `currentlyLoadedLocale` / `sTranslations` | `Signal<…>` | Raw signals for direct subscription outside React. In components, prefer the hooks. |
+
+## Server-Side Rendering (Next.js, Remix)
+
+The SDK is SSR-compatible. The main pattern is to pre-fetch translations server-side and seed them through `initialTranslations` / `initialTranslationsLocale` so the client doesn't refetch on hydration. `useT` and friends are built on `useSyncExternalStore` with a server snapshot, so they hydrate without a flash of untranslated content when seeded.
+
+📖 **See [README-SSR.md](./README-SSR.md)** for a complete Next.js (App Router & Pages Router) walkthrough.
+
+## Utilities
+
+`LangsysApp` exposes localized helpers (call them from effects / event handlers):
+
+```tsx
+import { LangsysApp, type iCountryList, type iCurrencyList, type iLocaleDefault } from 'langsys-js-react';
+
+const countries: iCountryList   = await LangsysApp.getCountries();     // [{ code: "US", label: "United States" }, ...]
+const dialCodes                 = await LangsysApp.getDialCodes();     // [{ country_code: "US", dial_code: "+1", name: "United States" }, ...]
+const currencies: iCurrencyList = await LangsysApp.getCurrencies();    // [{ code: "USD", name: "US Dollar", symbol: "$", ... }, ...]
+const locales: iLocaleDefault   = await LangsysApp.getLocales();       // { "English": [{ code: "en-US", name: "English (US)" }, ...], ... }
+const localeName                = await LangsysApp.getLocaleNameWithLookup('es-es', true, 'fr-fr'); // "espagnol"
+```
+
+### Detecting the user's preferred locale
+
+```typescript
+// Browser: navigator.languages → fallback to navigator.language
+const locale = LangsysApp.detectPreferredLocale();
+// Returns 'en-US', 'fr', etc., or false if not detected
+
+// SSR (route handler / middleware): parses Accept-Language
+const locale = LangsysApp.detectPreferredLocale(request.headers.get('Accept-Language'));
+
+// Matched against your app's supported locales
+const supportedLocales = (await LangsysApp.getLocalesFlat()).map((l) => l.code);
+const locale = LangsysApp.detectPreferredLocale(request.headers.get('Accept-Language'), supportedLocales);
+```
+
+The matcher tries exact match first (e.g. `en-US`), then language-only (`en` matches `en-GB`), then returns `false` if no match.
+
+### Waiting for translations to load
+
+When changing locale mid-session, you may want to re-run dependent code after the new translations arrive:
+
+```tsx
+useEffect(() => {
+    LangsysApp.translationsLoadingPromise.then(() => {
+        // re-render content / regenerate UI here
+    });
+}, [locale]);
+```
+
+## License
+
+MIT © Langsys

package/dist/index.d.mts

@@ -0,0 +1,161 @@
+import * as langsys_js_typescript from 'langsys-js-typescript';
+import { Signal, TFunction, iCategories, iLangsysInitConfig as iLangsysInitConfig$1, iLangsysResponse, iCountryList, iCurrencyList, iCountryDialCode, iLocaleDefault, iLocaleFlat, iLocaleData } from 'langsys-js-typescript';
+export { ExtractParamKeys, LangsysAppAPI, ParamPrimitive, ParamsFor, Signal, TArgs, TFunction, TranslationParams, createSignal, currentlyLoadedLocale, iCategories, iContentBlock, iCountry, iCountryDialCode, iCountryList, iCurrency, iCurrencyList, iLangsysResponse, iLanguageName, iLocaleData, iLocaleDefault, iLocaleFlat, iProject, iTranslations, sTranslations, tSignal as t } from 'langsys-js-typescript';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Subscribe a React component to a base-SDK `Signal<T>` and return its current
+ * value, re-rendering whenever the signal changes.
+ *
+ * This is the React mirror of Svelte's `$store` auto-subscription. Where the
+ * Svelte wrapper adapts a native store *into* the SDK (`writable` → `Signal`),
+ * the React wrapper adapts the SDK's signals *out* to the render cycle. It is
+ * built on `useSyncExternalStore`, so it is concurrent-safe and SSR-safe — the
+ * server snapshot reads the same `.get()`, which the base SDK seeds from
+ * `initialTranslations` during SSR.
+ *
+ * The base SDK's signals are stable between changes (every `set` replaces the
+ * value, so `.get()` returns a fresh reference only after a real change). That
+ * is exactly the identity contract `useSyncExternalStore` requires — no tearing,
+ * no render loops.
+ *
+ * `signal` must be stable across renders: a module-level singleton (the SDK's
+ * `t` / `currentlyLoadedLocale` / `sTranslations`) or one created once with
+ * `useState(() => createLocaleStore(...))`. Passing a freshly-created signal on
+ * every render would resubscribe on every render.
+ */
+declare function useSignal<T>(signal: Signal<T>): T;
+/**
+ * Create a reactive `Signal<string>` to hold the user's selected locale — the
+ * React analog of Svelte's `writable('en-us')`.
+ *
+ * Pass the result as `UserLocaleStore` to `LangsysApp.init`, read it reactively
+ * with `useSignal(store)` (or use the all-in-one `useLocaleStore` hook), and
+ * switch locale with `store.set('fr-fr')`. The base SDK only ever reads and
+ * subscribes to it — it never writes.
+ */
+declare function createLocaleStore(initial?: string): Signal<string>;
+
+/**
+ * The current translation function, re-rendering the calling component whenever
+ * translations or the loaded locale change. This is the React analog of Svelte's
+ * `$t` store read.
+ *
+ *   const t = useT();
+ *   return <h1>{t('Welcome to my app', 'UI')}</h1>;
+ *
+ * The phrase is both the lookup key and the base-language default. Signature:
+ * `t(phrase, category?, params?)`. Placeholder names in the phrase are
+ * type-checked against the params object at the call site.
+ */
+declare function useT(): TFunction;
+/**
+ * The locale whose translations are currently loaded. This lags the
+ * user-selected locale (`UserLocaleStore`) until the fetch for the new locale
+ * settles, which makes it the right value to gate "translations are ready" UI on.
+ */
+declare function useCurrentLocale(): string;
+/**
+ * The raw translation catalog. Rarely needed in app code — prefer `useT()`.
+ * Exposed for advanced cases (inspecting which categories/phrases are loaded).
+ */
+declare function useTranslations(): iCategories;
+/**
+ * All-in-one convenience for the user-locale store. Creates one stable
+ * `Signal<string>` (the React analog of Svelte's `writable`), subscribes the
+ * component to it, and returns `[locale, setLocale, store]`.
+ *
+ *   const [locale, setLocale, store] = useLocaleStore('en-us');
+ *   useEffect(() => {
+ *     LangsysApp.init({ projectid, key, UserLocaleStore: store });
+ *   }, [store]);
+ *
+ *   <select value={locale} onChange={(e) => setLocale(e.target.value)}>...
+ *
+ * The store is created lazily once and never re-created across renders, so it is
+ * safe to pass to `LangsysApp.init` and to depend on in effects.
+ */
+declare function useLocaleStore(initial?: string): [string, (locale: string) => void, Signal<string>];
+
+/**
+ * Props for the React `Translate` component. Mirrors the Svelte component's
+ * props 1:1, with Svelte's `class` renamed to React's idiomatic `className`.
+ */
+interface TranslateProps {
+    /** Optional category under which tokens are registered. Helps translators disambiguate. */
+    category?: string;
+    /** Optional stable id for the content block. If omitted, the SDK hashes category + tokens. */
+    custom_id?: string;
+    /** Optional human-readable label shown in the Translation Manager. */
+    label?: string;
+    /** Host element tag. Defaults to a `<translate>` custom element. */
+    tag?: string;
+    /** Class applied to the host element. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * React wrapper around the vanilla `Translate` DOM class from
+ * `langsys-js-typescript`. It renders a host element, then on mount lets the
+ * vanilla class walk and tokenize the rendered children (text nodes plus
+ * translatable attributes), register the content block, and re-translate on
+ * locale change. On unmount it tears the instance down.
+ *
+ * This is the React analog of the Svelte `<Translate>` component — pure
+ * mount/destroy glue. The DOM walking, content-block registration, attribute
+ * harvesting, and re-translation lifecycle all live in the base SDK.
+ *
+ * Like the Svelte component, this lets the SDK mutate the rendered DOM in place,
+ * so keep the children static: prose, marketing copy, CMS-rendered HTML — the
+ * content-block use case. For dynamic per-string values that React owns and
+ * re-renders, use `useT()` instead.
+ */
+declare function Translate({ category, custom_id, label, tag, className, children, }: TranslateProps): react.ReactElement<{
+    ref: react.RefObject<HTMLElement | null>;
+    className: string | undefined;
+}, string | react.JSXElementConstructor<any>>;
+
+/**
+ * React-flavored init config. Identical to the base SDK's config except
+ * `UserLocaleStore` is typed as a `Signal<string>` — create one with
+ * `createLocaleStore()` (or get one from the `useLocaleStore` hook). The base
+ * SDK only reads and subscribes to it.
+ */
+interface iLangsysInitConfig extends Omit<iLangsysInitConfig$1, 'UserLocaleStore'> {
+    UserLocaleStore: Signal<string>;
+}
+/**
+ * React SDK entry point. Delegates everything to the underlying
+ * `langsys-js-typescript` singleton. Because React's locale store is already a
+ * `Signal` (unlike Svelte's `Writable`, which needs adapting), `init` is a
+ * straight passthrough — the React-native concerns live in the hooks and the
+ * `<Translate>` component, not here.
+ */
+declare class LangsysAppReact {
+    /** Initialize Langsys. Pass a `Signal<string>` (from `createLocaleStore`) as `UserLocaleStore`. */
+    init(config: iLangsysInitConfig): Promise<iLangsysResponse>;
+    get Translations(): langsys_js_typescript.Translations;
+    get translationsLoadingPromise(): Promise<unknown>;
+    /** Current translation function. Reads fresh state on every call (not reactive on its own — use `useT()` in components). */
+    get t(): TFunction;
+    get debug(): langsys_js_typescript.Logger;
+    refresh(): Promise<boolean>;
+    getCountries(inLocale?: string): Promise<iCountryList>;
+    getCountryName(forCountryCode: string, inLocale?: string): Promise<string>;
+    getCurrencies(inLocale?: string): Promise<iCurrencyList>;
+    getCurrencyName(forCurrencyCode: string, inLocale?: string): Promise<string>;
+    getDialCodes(inLocale?: string): Promise<iCountryDialCode[]>;
+    getLocales(inLocale?: string): Promise<iLocaleDefault>;
+    getLocalesFlat(inLocale?: string): Promise<iLocaleFlat[]>;
+    getLocalesData(inLocale?: string, forceRefresh?: boolean): Promise<iLocaleData[]>;
+    getLocalesFormat(format?: '' | 'flat' | 'data', inLocale?: string): Promise<iLocaleFlat[] | iLocaleDefault | iLocaleData[]>;
+    getLocaleName(forLocale: string, shortName?: boolean, inLocale?: string): string;
+    getLocaleNameWithLookup(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */
+    getLanguageName(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    detectPreferredLocale(acceptLanguageHeader?: string | null, supportedLocales?: string[]): string | false;
+}
+declare const LangsysApp: LangsysAppReact;
+
+export { LangsysApp, Translate, type TranslateProps, createLocaleStore, type iLangsysInitConfig, useCurrentLocale, useLocaleStore, useSignal, useT, useTranslations };

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+import * as langsys_js_typescript from 'langsys-js-typescript';
+import { Signal, TFunction, iCategories, iLangsysInitConfig as iLangsysInitConfig$1, iLangsysResponse, iCountryList, iCurrencyList, iCountryDialCode, iLocaleDefault, iLocaleFlat, iLocaleData } from 'langsys-js-typescript';
+export { ExtractParamKeys, LangsysAppAPI, ParamPrimitive, ParamsFor, Signal, TArgs, TFunction, TranslationParams, createSignal, currentlyLoadedLocale, iCategories, iContentBlock, iCountry, iCountryDialCode, iCountryList, iCurrency, iCurrencyList, iLangsysResponse, iLanguageName, iLocaleData, iLocaleDefault, iLocaleFlat, iProject, iTranslations, sTranslations, tSignal as t } from 'langsys-js-typescript';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Subscribe a React component to a base-SDK `Signal<T>` and return its current
+ * value, re-rendering whenever the signal changes.
+ *
+ * This is the React mirror of Svelte's `$store` auto-subscription. Where the
+ * Svelte wrapper adapts a native store *into* the SDK (`writable` → `Signal`),
+ * the React wrapper adapts the SDK's signals *out* to the render cycle. It is
+ * built on `useSyncExternalStore`, so it is concurrent-safe and SSR-safe — the
+ * server snapshot reads the same `.get()`, which the base SDK seeds from
+ * `initialTranslations` during SSR.
+ *
+ * The base SDK's signals are stable between changes (every `set` replaces the
+ * value, so `.get()` returns a fresh reference only after a real change). That
+ * is exactly the identity contract `useSyncExternalStore` requires — no tearing,
+ * no render loops.
+ *
+ * `signal` must be stable across renders: a module-level singleton (the SDK's
+ * `t` / `currentlyLoadedLocale` / `sTranslations`) or one created once with
+ * `useState(() => createLocaleStore(...))`. Passing a freshly-created signal on
+ * every render would resubscribe on every render.
+ */
+declare function useSignal<T>(signal: Signal<T>): T;
+/**
+ * Create a reactive `Signal<string>` to hold the user's selected locale — the
+ * React analog of Svelte's `writable('en-us')`.
+ *
+ * Pass the result as `UserLocaleStore` to `LangsysApp.init`, read it reactively
+ * with `useSignal(store)` (or use the all-in-one `useLocaleStore` hook), and
+ * switch locale with `store.set('fr-fr')`. The base SDK only ever reads and
+ * subscribes to it — it never writes.
+ */
+declare function createLocaleStore(initial?: string): Signal<string>;
+
+/**
+ * The current translation function, re-rendering the calling component whenever
+ * translations or the loaded locale change. This is the React analog of Svelte's
+ * `$t` store read.
+ *
+ *   const t = useT();
+ *   return <h1>{t('Welcome to my app', 'UI')}</h1>;
+ *
+ * The phrase is both the lookup key and the base-language default. Signature:
+ * `t(phrase, category?, params?)`. Placeholder names in the phrase are
+ * type-checked against the params object at the call site.
+ */
+declare function useT(): TFunction;
+/**
+ * The locale whose translations are currently loaded. This lags the
+ * user-selected locale (`UserLocaleStore`) until the fetch for the new locale
+ * settles, which makes it the right value to gate "translations are ready" UI on.
+ */
+declare function useCurrentLocale(): string;
+/**
+ * The raw translation catalog. Rarely needed in app code — prefer `useT()`.
+ * Exposed for advanced cases (inspecting which categories/phrases are loaded).
+ */
+declare function useTranslations(): iCategories;
+/**
+ * All-in-one convenience for the user-locale store. Creates one stable
+ * `Signal<string>` (the React analog of Svelte's `writable`), subscribes the
+ * component to it, and returns `[locale, setLocale, store]`.
+ *
+ *   const [locale, setLocale, store] = useLocaleStore('en-us');
+ *   useEffect(() => {
+ *     LangsysApp.init({ projectid, key, UserLocaleStore: store });
+ *   }, [store]);
+ *
+ *   <select value={locale} onChange={(e) => setLocale(e.target.value)}>...
+ *
+ * The store is created lazily once and never re-created across renders, so it is
+ * safe to pass to `LangsysApp.init` and to depend on in effects.
+ */
+declare function useLocaleStore(initial?: string): [string, (locale: string) => void, Signal<string>];
+
+/**
+ * Props for the React `Translate` component. Mirrors the Svelte component's
+ * props 1:1, with Svelte's `class` renamed to React's idiomatic `className`.
+ */
+interface TranslateProps {
+    /** Optional category under which tokens are registered. Helps translators disambiguate. */
+    category?: string;
+    /** Optional stable id for the content block. If omitted, the SDK hashes category + tokens. */
+    custom_id?: string;
+    /** Optional human-readable label shown in the Translation Manager. */
+    label?: string;
+    /** Host element tag. Defaults to a `<translate>` custom element. */
+    tag?: string;
+    /** Class applied to the host element. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * React wrapper around the vanilla `Translate` DOM class from
+ * `langsys-js-typescript`. It renders a host element, then on mount lets the
+ * vanilla class walk and tokenize the rendered children (text nodes plus
+ * translatable attributes), register the content block, and re-translate on
+ * locale change. On unmount it tears the instance down.
+ *
+ * This is the React analog of the Svelte `<Translate>` component — pure
+ * mount/destroy glue. The DOM walking, content-block registration, attribute
+ * harvesting, and re-translation lifecycle all live in the base SDK.
+ *
+ * Like the Svelte component, this lets the SDK mutate the rendered DOM in place,
+ * so keep the children static: prose, marketing copy, CMS-rendered HTML — the
+ * content-block use case. For dynamic per-string values that React owns and
+ * re-renders, use `useT()` instead.
+ */
+declare function Translate({ category, custom_id, label, tag, className, children, }: TranslateProps): react.ReactElement<{
+    ref: react.RefObject<HTMLElement | null>;
+    className: string | undefined;
+}, string | react.JSXElementConstructor<any>>;
+
+/**
+ * React-flavored init config. Identical to the base SDK's config except
+ * `UserLocaleStore` is typed as a `Signal<string>` — create one with
+ * `createLocaleStore()` (or get one from the `useLocaleStore` hook). The base
+ * SDK only reads and subscribes to it.
+ */
+interface iLangsysInitConfig extends Omit<iLangsysInitConfig$1, 'UserLocaleStore'> {
+    UserLocaleStore: Signal<string>;
+}
+/**
+ * React SDK entry point. Delegates everything to the underlying
+ * `langsys-js-typescript` singleton. Because React's locale store is already a
+ * `Signal` (unlike Svelte's `Writable`, which needs adapting), `init` is a
+ * straight passthrough — the React-native concerns live in the hooks and the
+ * `<Translate>` component, not here.
+ */
+declare class LangsysAppReact {
+    /** Initialize Langsys. Pass a `Signal<string>` (from `createLocaleStore`) as `UserLocaleStore`. */
+    init(config: iLangsysInitConfig): Promise<iLangsysResponse>;
+    get Translations(): langsys_js_typescript.Translations;
+    get translationsLoadingPromise(): Promise<unknown>;
+    /** Current translation function. Reads fresh state on every call (not reactive on its own — use `useT()` in components). */
+    get t(): TFunction;
+    get debug(): langsys_js_typescript.Logger;
+    refresh(): Promise<boolean>;
+    getCountries(inLocale?: string): Promise<iCountryList>;
+    getCountryName(forCountryCode: string, inLocale?: string): Promise<string>;
+    getCurrencies(inLocale?: string): Promise<iCurrencyList>;
+    getCurrencyName(forCurrencyCode: string, inLocale?: string): Promise<string>;
+    getDialCodes(inLocale?: string): Promise<iCountryDialCode[]>;
+    getLocales(inLocale?: string): Promise<iLocaleDefault>;
+    getLocalesFlat(inLocale?: string): Promise<iLocaleFlat[]>;
+    getLocalesData(inLocale?: string, forceRefresh?: boolean): Promise<iLocaleData[]>;
+    getLocalesFormat(format?: '' | 'flat' | 'data', inLocale?: string): Promise<iLocaleFlat[] | iLocaleDefault | iLocaleData[]>;
+    getLocaleName(forLocale: string, shortName?: boolean, inLocale?: string): string;
+    getLocaleNameWithLookup(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */
+    getLanguageName(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    detectPreferredLocale(acceptLanguageHeader?: string | null, supportedLocales?: string[]): string | false;
+}
+declare const LangsysApp: LangsysAppReact;
+
+export { LangsysApp, Translate, type TranslateProps, createLocaleStore, type iLangsysInitConfig, useCurrentLocale, useLocaleStore, useSignal, useT, useTranslations };

package/dist/index.js

@@ -0,0 +1,139 @@
+'use strict';
+
+var langsysJsTypescript = require('langsys-js-typescript');
+var react = require('react');
+
+// src/index.ts
+function useSignal(signal) {
+  return react.useSyncExternalStore(signal.subscribe, signal.get, signal.get);
+}
+function createLocaleStore(initial = "en-us") {
+  return langsysJsTypescript.createSignal(initial);
+}
+function useT() {
+  return useSignal(langsysJsTypescript.tSignal);
+}
+function useCurrentLocale() {
+  return useSignal(langsysJsTypescript.currentlyLoadedLocale);
+}
+function useTranslations() {
+  return useSignal(langsysJsTypescript.sTranslations);
+}
+function useLocaleStore(initial = "en-us") {
+  const [store] = react.useState(() => createLocaleStore(initial));
+  const locale = useSignal(store);
+  return [locale, store.set, store];
+}
+function Translate({
+  category = "",
+  custom_id = "",
+  label = "",
+  tag = "translate",
+  className,
+  children
+}) {
+  const hostRef = react.useRef(null);
+  react.useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    const instance = new langsysJsTypescript.Translate(host, { category, custom_id, label });
+    return () => instance.destroy();
+  }, [category, custom_id, label]);
+  return react.createElement(tag, { ref: hostRef, className }, children);
+}
+
+// src/index.ts
+var LangsysAppReact = class {
+  /** Initialize Langsys. Pass a `Signal<string>` (from `createLocaleStore`) as `UserLocaleStore`. */
+  init(config) {
+    return langsysJsTypescript.LangsysApp.init(config);
+  }
+  get Translations() {
+    return langsysJsTypescript.LangsysApp.Translations;
+  }
+  get translationsLoadingPromise() {
+    return langsysJsTypescript.LangsysApp.translationsLoadingPromise;
+  }
+  /** Current translation function. Reads fresh state on every call (not reactive on its own — use `useT()` in components). */
+  get t() {
+    return langsysJsTypescript.LangsysApp.t;
+  }
+  get debug() {
+    return langsysJsTypescript.LangsysApp.debug;
+  }
+  refresh() {
+    return langsysJsTypescript.LangsysApp.refresh();
+  }
+  getCountries(inLocale) {
+    return langsysJsTypescript.LangsysApp.getCountries(inLocale);
+  }
+  getCountryName(forCountryCode, inLocale) {
+    return langsysJsTypescript.LangsysApp.getCountryName(forCountryCode, inLocale);
+  }
+  getCurrencies(inLocale) {
+    return langsysJsTypescript.LangsysApp.getCurrencies(inLocale);
+  }
+  getCurrencyName(forCurrencyCode, inLocale) {
+    return langsysJsTypescript.LangsysApp.getCurrencyName(forCurrencyCode, inLocale);
+  }
+  getDialCodes(inLocale) {
+    return langsysJsTypescript.LangsysApp.getDialCodes(inLocale);
+  }
+  getLocales(inLocale) {
+    return langsysJsTypescript.LangsysApp.getLocales(inLocale);
+  }
+  getLocalesFlat(inLocale) {
+    return langsysJsTypescript.LangsysApp.getLocalesFlat(inLocale);
+  }
+  getLocalesData(inLocale, forceRefresh) {
+    return langsysJsTypescript.LangsysApp.getLocalesData(inLocale, forceRefresh);
+  }
+  getLocalesFormat(format = "", inLocale) {
+    return langsysJsTypescript.LangsysApp.getLocalesFormat(format, inLocale);
+  }
+  getLocaleName(forLocale, shortName, inLocale) {
+    return langsysJsTypescript.LangsysApp.getLocaleName(forLocale, shortName, inLocale);
+  }
+  getLocaleNameWithLookup(forLocale, shortName, inLocale) {
+    return langsysJsTypescript.LangsysApp.getLocaleNameWithLookup(forLocale, shortName, inLocale);
+  }
+  /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */
+  getLanguageName(forLocale, shortName, inLocale) {
+    return langsysJsTypescript.LangsysApp.getLanguageName(forLocale, shortName, inLocale);
+  }
+  detectPreferredLocale(acceptLanguageHeader, supportedLocales) {
+    return langsysJsTypescript.LangsysApp.detectPreferredLocale(acceptLanguageHeader, supportedLocales);
+  }
+};
+var LangsysApp = new LangsysAppReact();
+
+Object.defineProperty(exports, "LangsysAppAPI", {
+  enumerable: true,
+  get: function () { return langsysJsTypescript.LangsysAppAPI; }
+});
+Object.defineProperty(exports, "createSignal", {
+  enumerable: true,
+  get: function () { return langsysJsTypescript.createSignal; }
+});
+Object.defineProperty(exports, "currentlyLoadedLocale", {
+  enumerable: true,
+  get: function () { return langsysJsTypescript.currentlyLoadedLocale; }
+});
+Object.defineProperty(exports, "sTranslations", {
+  enumerable: true,
+  get: function () { return langsysJsTypescript.sTranslations; }
+});
+Object.defineProperty(exports, "t", {
+  enumerable: true,
+  get: function () { return langsysJsTypescript.tSignal; }
+});
+exports.LangsysApp = LangsysApp;
+exports.Translate = Translate;
+exports.createLocaleStore = createLocaleStore;
+exports.useCurrentLocale = useCurrentLocale;
+exports.useLocaleStore = useLocaleStore;
+exports.useSignal = useSignal;
+exports.useT = useT;
+exports.useTranslations = useTranslations;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters.ts","../src/hooks.ts","../src/components/Translate.tsx","../src/index.ts"],"names":["useSyncExternalStore","createSignal","tSignal","currentlyLoadedLocale","sTranslations","useState","useRef","useEffect","VanillaTranslate","createElement","_LangsysApp"],"mappings":";;;;;;AAwBO,SAAS,UAAa,MAAA,EAAsB;AAC/C,EAAA,OAAOA,2BAAqB,MAAA,CAAO,SAAA,EAAW,MAAA,CAAO,GAAA,EAAK,OAAO,GAAG,CAAA;AACxE;AAWO,SAAS,iBAAA,CAAkB,UAAU,OAAA,EAAyB;AACjE,EAAA,OAAOC,iCAAqB,OAAO,CAAA;AACvC;ACtBO,SAAS,IAAA,GAAkB;AAC9B,EAAA,OAAO,UAAUC,2BAAO,CAAA;AAC5B;AAOO,SAAS,gBAAA,GAA2B;AACvC,EAAA,OAAO,UAAUC,yCAAqB,CAAA;AAC1C;AAMO,SAAS,eAAA,GAA+B;AAC3C,EAAA,OAAO,UAAUC,iCAAa,CAAA;AAClC;AAiBO,SAAS,cAAA,CAAe,UAAU,OAAA,EAA6D;AAClG,EAAA,MAAM,CAAC,KAAK,CAAA,GAAIC,eAAS,MAAM,iBAAA,CAAkB,OAAO,CAAC,CAAA;AACzD,EAAA,MAAM,MAAA,GAAS,UAAU,KAAK,CAAA;AAC9B,EAAA,OAAO,CAAC,MAAA,EAAQ,KAAA,CAAM,GAAA,EAAK,KAAK,CAAA;AACpC;ACnBO,SAAS,SAAA,CAAU;AAAA,EACtB,QAAA,GAAW,EAAA;AAAA,EACX,SAAA,GAAY,EAAA;AAAA,EACZ,KAAA,GAAQ,EAAA;AAAA,EACR,GAAA,GAAM,WAAA;AAAA,EACN,SAAA;AAAA,EACA;AACJ,CAAA,EAAmB;AACf,EAAA,MAAM,OAAA,GAAUC,aAA2B,IAAI,CAAA;AAE/C,EAAAC,eAAA,CAAU,MAAM;AACZ,IAAA,MAAM,OAAO,OAAA,CAAQ,OAAA;AACrB,IAAA,IAAI,CAAC,IAAA,EAAM;AACX,IAAA,MAAM,QAAA,GAAW,IAAIC,6BAAA,CAAiB,IAAA,EAAM,EAAE,QAAA,EAAU,SAAA,EAAW,OAAO,CAAA;AAC1E,IAAA,OAAO,MAAM,SAAS,OAAA,EAAQ;AAAA,EAClC,CAAA,EAAG,CAAC,QAAA,EAAU,SAAA,EAAW,KAAK,CAAC,CAAA;AAE/B,EAAA,OAAOC,oBAAc,GAAA,EAAK,EAAE,KAAK,OAAA,EAAS,SAAA,IAAa,QAAQ,CAAA;AACnE;;;AC4CA,IAAM,kBAAN,MAAsB;AAAA;AAAA,EAEX,KAAK,MAAA,EAAuD;AAC/D,IAAA,OAAOC,8BAAA,CAAY,KAAK,MAAM,CAAA;AAAA,EAClC;AAAA,EAEA,IAAW,YAAA,GAAe;AACtB,IAAA,OAAOA,8BAAA,CAAY,YAAA;AAAA,EACvB;AAAA,EAEA,IAAW,0BAAA,GAA6B;AACpC,IAAA,OAAOA,8BAAA,CAAY,0BAAA;AAAA,EACvB;AAAA;AAAA,EAGA,IAAW,CAAA,GAAe;AACtB,IAAA,OAAOA,8BAAA,CAAY,CAAA;AAAA,EACvB;AAAA,EAEA,IAAW,KAAA,GAAQ;AACf,IAAA,OAAOA,8BAAA,CAAY,KAAA;AAAA,EACvB;AAAA,EAEO,OAAA,GAAU;AACb,IAAA,OAAOA,+BAAY,OAAA,EAAQ;AAAA,EAC/B;AAAA,EAEO,aAAa,QAAA,EAAmB;AACnC,IAAA,OAAOA,8BAAA,CAAY,aAAa,QAAQ,CAAA;AAAA,EAC5C;AAAA,EACO,cAAA,CAAe,gBAAwB,QAAA,EAAmB;AAC7D,IAAA,OAAOA,8BAAA,CAAY,cAAA,CAAe,cAAA,EAAgB,QAAQ,CAAA;AAAA,EAC9D;AAAA,EACO,cAAc,QAAA,EAAmB;AACpC,IAAA,OAAOA,8BAAA,CAAY,cAAc,QAAQ,CAAA;AAAA,EAC7C;AAAA,EACO,eAAA,CAAgB,iBAAyB,QAAA,EAAmB;AAC/D,IAAA,OAAOA,8BAAA,CAAY,eAAA,CAAgB,eAAA,EAAiB,QAAQ,CAAA;AAAA,EAChE;AAAA,EACO,aAAa,QAAA,EAAmB;AACnC,IAAA,OAAOA,8BAAA,CAAY,aAAa,QAAQ,CAAA;AAAA,EAC5C;AAAA,EAEO,WAAW,QAAA,EAAmB;AACjC,IAAA,OAAOA,8BAAA,CAAY,WAAW,QAAQ,CAAA;AAAA,EAC1C;AAAA,EACO,eAAe,QAAA,EAAmB;AACrC,IAAA,OAAOA,8BAAA,CAAY,eAAe,QAAQ,CAAA;AAAA,EAC9C;AAAA,EACO,cAAA,CAAe,UAAmB,YAAA,EAAwB;AAC7D,IAAA,OAAOA,8BAAA,CAAY,cAAA,CAAe,QAAA,EAAU,YAAY,CAAA;AAAA,EAC5D;AAAA,EACO,gBAAA,CAAiB,MAAA,GAA+B,EAAA,EAAI,QAAA,EAAmB;AAC1E,IAAA,OAAOA,8BAAA,CAAY,gBAAA,CAAiB,MAAA,EAAQ,QAAQ,CAAA;AAAA,EACxD;AAAA,EACO,aAAA,CAAc,SAAA,EAAmB,SAAA,EAAqB,QAAA,EAAmB;AAC5E,IAAA,OAAOA,8BAAA,CAAY,aAAA,CAAc,SAAA,EAAW,SAAA,EAAW,QAAQ,CAAA;AAAA,EACnE;AAAA,EACO,uBAAA,CAAwB,SAAA,EAAmB,SAAA,EAAqB,QAAA,EAAmB;AACtF,IAAA,OAAOA,8BAAA,CAAY,uBAAA,CAAwB,SAAA,EAAW,SAAA,EAAW,QAAQ,CAAA;AAAA,EAC7E;AAAA;AAAA,EAGO,eAAA,CAAgB,SAAA,EAAmB,SAAA,EAAqB,QAAA,EAAmB;AAC9E,IAAA,OAAOA,8BAAA,CAAY,eAAA,CAAgB,SAAA,EAAW,SAAA,EAAW,QAAQ,CAAA;AAAA,EACrE;AAAA,EAEO,qBAAA,CAAsB,sBAAsC,gBAAA,EAA6B;AAC5F,IAAA,OAAOA,8BAAA,CAAY,qBAAA,CAAsB,oBAAA,EAAsB,gBAAgB,CAAA;AAAA,EACnF;AACJ,CAAA;AAEO,IAAM,UAAA,GAAa,IAAI,eAAA","file":"index.js","sourcesContent":["import { useSyncExternalStore } from 'react';\nimport { createSignal, type Signal } from 'langsys-js-typescript';\n\n/**\n * Subscribe a React component to a base-SDK `Signal<T>` and return its current\n * value, re-rendering whenever the signal changes.\n *\n * This is the React mirror of Svelte's `$store` auto-subscription. Where the\n * Svelte wrapper adapts a native store *into* the SDK (`writable` → `Signal`),\n * the React wrapper adapts the SDK's signals *out* to the render cycle. It is\n * built on `useSyncExternalStore`, so it is concurrent-safe and SSR-safe — the\n * server snapshot reads the same `.get()`, which the base SDK seeds from\n * `initialTranslations` during SSR.\n *\n * The base SDK's signals are stable between changes (every `set` replaces the\n * value, so `.get()` returns a fresh reference only after a real change). That\n * is exactly the identity contract `useSyncExternalStore` requires — no tearing,\n * no render loops.\n *\n * `signal` must be stable across renders: a module-level singleton (the SDK's\n * `t` / `currentlyLoadedLocale` / `sTranslations`) or one created once with\n * `useState(() => createLocaleStore(...))`. Passing a freshly-created signal on\n * every render would resubscribe on every render.\n */\nexport function useSignal<T>(signal: Signal<T>): T {\n    return useSyncExternalStore(signal.subscribe, signal.get, signal.get);\n}\n\n/**\n * Create a reactive `Signal<string>` to hold the user's selected locale — the\n * React analog of Svelte's `writable('en-us')`.\n *\n * Pass the result as `UserLocaleStore` to `LangsysApp.init`, read it reactively\n * with `useSignal(store)` (or use the all-in-one `useLocaleStore` hook), and\n * switch locale with `store.set('fr-fr')`. The base SDK only ever reads and\n * subscribes to it — it never writes.\n */\nexport function createLocaleStore(initial = 'en-us'): Signal<string> {\n    return createSignal<string>(initial);\n}\n","import { useState } from 'react';\nimport { currentlyLoadedLocale, sTranslations, tSignal } from 'langsys-js-typescript';\nimport type { Signal, TFunction, iCategories } from 'langsys-js-typescript';\nimport { createLocaleStore, useSignal } from './adapters.js';\n\n/**\n * The current translation function, re-rendering the calling component whenever\n * translations or the loaded locale change. This is the React analog of Svelte's\n * `$t` store read.\n *\n *   const t = useT();\n *   return <h1>{t('Welcome to my app', 'UI')}</h1>;\n *\n * The phrase is both the lookup key and the base-language default. Signature:\n * `t(phrase, category?, params?)`. Placeholder names in the phrase are\n * type-checked against the params object at the call site.\n */\nexport function useT(): TFunction {\n    return useSignal(tSignal);\n}\n\n/**\n * The locale whose translations are currently loaded. This lags the\n * user-selected locale (`UserLocaleStore`) until the fetch for the new locale\n * settles, which makes it the right value to gate \"translations are ready\" UI on.\n */\nexport function useCurrentLocale(): string {\n    return useSignal(currentlyLoadedLocale);\n}\n\n/**\n * The raw translation catalog. Rarely needed in app code — prefer `useT()`.\n * Exposed for advanced cases (inspecting which categories/phrases are loaded).\n */\nexport function useTranslations(): iCategories {\n    return useSignal(sTranslations);\n}\n\n/**\n * All-in-one convenience for the user-locale store. Creates one stable\n * `Signal<string>` (the React analog of Svelte's `writable`), subscribes the\n * component to it, and returns `[locale, setLocale, store]`.\n *\n *   const [locale, setLocale, store] = useLocaleStore('en-us');\n *   useEffect(() => {\n *     LangsysApp.init({ projectid, key, UserLocaleStore: store });\n *   }, [store]);\n *\n *   <select value={locale} onChange={(e) => setLocale(e.target.value)}>...\n *\n * The store is created lazily once and never re-created across renders, so it is\n * safe to pass to `LangsysApp.init` and to depend on in effects.\n */\nexport function useLocaleStore(initial = 'en-us'): [string, (locale: string) => void, Signal<string>] {\n    const [store] = useState(() => createLocaleStore(initial));\n    const locale = useSignal(store);\n    return [locale, store.set, store];\n}\n","import { createElement, useEffect, useRef } from 'react';\nimport type { ReactNode } from 'react';\nimport { Translate as VanillaTranslate } from 'langsys-js-typescript';\n\n/**\n * Props for the React `Translate` component. Mirrors the Svelte component's\n * props 1:1, with Svelte's `class` renamed to React's idiomatic `className`.\n */\nexport interface TranslateProps {\n    /** Optional category under which tokens are registered. Helps translators disambiguate. */\n    category?: string;\n    /** Optional stable id for the content block. If omitted, the SDK hashes category + tokens. */\n    custom_id?: string;\n    /** Optional human-readable label shown in the Translation Manager. */\n    label?: string;\n    /** Host element tag. Defaults to a `<translate>` custom element. */\n    tag?: string;\n    /** Class applied to the host element. */\n    className?: string;\n    children?: ReactNode;\n}\n\n/**\n * React wrapper around the vanilla `Translate` DOM class from\n * `langsys-js-typescript`. It renders a host element, then on mount lets the\n * vanilla class walk and tokenize the rendered children (text nodes plus\n * translatable attributes), register the content block, and re-translate on\n * locale change. On unmount it tears the instance down.\n *\n * This is the React analog of the Svelte `<Translate>` component — pure\n * mount/destroy glue. The DOM walking, content-block registration, attribute\n * harvesting, and re-translation lifecycle all live in the base SDK.\n *\n * Like the Svelte component, this lets the SDK mutate the rendered DOM in place,\n * so keep the children static: prose, marketing copy, CMS-rendered HTML — the\n * content-block use case. For dynamic per-string values that React owns and\n * re-renders, use `useT()` instead.\n */\nexport function Translate({\n    category = '',\n    custom_id = '',\n    label = '',\n    tag = 'translate',\n    className,\n    children,\n}: TranslateProps) {\n    const hostRef = useRef<HTMLElement | null>(null);\n\n    useEffect(() => {\n        const host = hostRef.current;\n        if (!host) return;\n        const instance = new VanillaTranslate(host, { category, custom_id, label });\n        return () => instance.destroy();\n    }, [category, custom_id, label]);\n\n    return createElement(tag, { ref: hostRef, className }, children);\n}\n\nexport default Translate;\n","/**\n * langsys-js-react — idiomatic React binding over `langsys-js-typescript`.\n *\n * Public API:\n *   - `LangsysApp` — `init` accepts a `Signal<string>` (make one with\n *     `createLocaleStore`) for the user locale; every other method delegates.\n *   - Hooks — `useT`, `useCurrentLocale`, `useTranslations`, `useLocaleStore`,\n *     and the low-level `useSignal`. These are the reactive layer; in components\n *     prefer them over the raw signals.\n *   - `createLocaleStore` — make the user-locale store (React analog of Svelte's\n *     `writable`).\n *   - `Translate` — React component wrapping the vanilla DOM `Translate` class.\n *   - Raw signals `t` / `currentlyLoadedLocale` / `sTranslations` — re-exported\n *     for advanced/direct subscription outside React's render cycle.\n */\n\nimport {\n    LangsysApp as _LangsysApp,\n    type ExtractParamKeys,\n    type ParamPrimitive,\n    type ParamsFor,\n    type Signal,\n    type TArgs,\n    type TFunction,\n    type TranslationParams,\n    type iCategories,\n    type iContentBlock,\n    type iCountry,\n    type iCountryDialCode,\n    type iCountryList,\n    type iCurrency,\n    type iCurrencyList,\n    type iLangsysInitConfig as iVanillaInitConfig,\n    type iLangsysResponse,\n    type iLanguageName,\n    type iLocaleData,\n    type iLocaleDefault,\n    type iLocaleFlat,\n    type iProject,\n    type iTranslations,\n} from 'langsys-js-typescript';\n\n// Reactive primitives (raw signals) — re-exported for advanced/direct\n// subscription. `tSignal` is exposed under the friendlier name `t`. In\n// components, prefer the hooks (`useT`, `useCurrentLocale`, …).\nexport { currentlyLoadedLocale, createSignal, sTranslations, tSignal as t } from 'langsys-js-typescript';\n\n// API client (vanilla — no React concerns)\nexport { LangsysAppAPI } from 'langsys-js-typescript';\n\n// Hooks + adapters (the React-idiomatic reactive layer)\nexport { createLocaleStore, useSignal } from './adapters.js';\nexport { useCurrentLocale, useLocaleStore, useT, useTranslations } from './hooks.js';\n\n// Component\nexport { Translate, type TranslateProps } from './components/Translate.js';\n\n// Type re-exports — these are framework-agnostic, so consumers can rely on them\n// directly without reaching into `langsys-js-typescript`.\nexport type {\n    ExtractParamKeys,\n    ParamPrimitive,\n    ParamsFor,\n    Signal,\n    TArgs,\n    TFunction,\n    TranslationParams,\n    iCategories,\n    iContentBlock,\n    iCountry,\n    iCountryDialCode,\n    iCountryList,\n    iCurrency,\n    iCurrencyList,\n    iLangsysResponse,\n    iLanguageName,\n    iLocaleData,\n    iLocaleDefault,\n    iLocaleFlat,\n    iProject,\n    iTranslations,\n};\n\n/**\n * React-flavored init config. Identical to the base SDK's config except\n * `UserLocaleStore` is typed as a `Signal<string>` — create one with\n * `createLocaleStore()` (or get one from the `useLocaleStore` hook). The base\n * SDK only reads and subscribes to it.\n */\nexport interface iLangsysInitConfig extends Omit<iVanillaInitConfig, 'UserLocaleStore'> {\n    UserLocaleStore: Signal<string>;\n}\n\n/**\n * React SDK entry point. Delegates everything to the underlying\n * `langsys-js-typescript` singleton. Because React's locale store is already a\n * `Signal` (unlike Svelte's `Writable`, which needs adapting), `init` is a\n * straight passthrough — the React-native concerns live in the hooks and the\n * `<Translate>` component, not here.\n */\nclass LangsysAppReact {\n    /** Initialize Langsys. Pass a `Signal<string>` (from `createLocaleStore`) as `UserLocaleStore`. */\n    public init(config: iLangsysInitConfig): Promise<iLangsysResponse> {\n        return _LangsysApp.init(config);\n    }\n\n    public get Translations() {\n        return _LangsysApp.Translations;\n    }\n\n    public get translationsLoadingPromise() {\n        return _LangsysApp.translationsLoadingPromise;\n    }\n\n    /** Current translation function. Reads fresh state on every call (not reactive on its own — use `useT()` in components). */\n    public get t(): TFunction {\n        return _LangsysApp.t;\n    }\n\n    public get debug() {\n        return _LangsysApp.debug;\n    }\n\n    public refresh() {\n        return _LangsysApp.refresh();\n    }\n\n    public getCountries(inLocale?: string) {\n        return _LangsysApp.getCountries(inLocale);\n    }\n    public getCountryName(forCountryCode: string, inLocale?: string) {\n        return _LangsysApp.getCountryName(forCountryCode, inLocale);\n    }\n    public getCurrencies(inLocale?: string) {\n        return _LangsysApp.getCurrencies(inLocale);\n    }\n    public getCurrencyName(forCurrencyCode: string, inLocale?: string) {\n        return _LangsysApp.getCurrencyName(forCurrencyCode, inLocale);\n    }\n    public getDialCodes(inLocale?: string) {\n        return _LangsysApp.getDialCodes(inLocale);\n    }\n\n    public getLocales(inLocale?: string) {\n        return _LangsysApp.getLocales(inLocale);\n    }\n    public getLocalesFlat(inLocale?: string) {\n        return _LangsysApp.getLocalesFlat(inLocale);\n    }\n    public getLocalesData(inLocale?: string, forceRefresh?: boolean) {\n        return _LangsysApp.getLocalesData(inLocale, forceRefresh);\n    }\n    public getLocalesFormat(format: '' | 'flat' | 'data' = '', inLocale?: string) {\n        return _LangsysApp.getLocalesFormat(format, inLocale);\n    }\n    public getLocaleName(forLocale: string, shortName?: boolean, inLocale?: string) {\n        return _LangsysApp.getLocaleName(forLocale, shortName, inLocale);\n    }\n    public getLocaleNameWithLookup(forLocale: string, shortName?: boolean, inLocale?: string) {\n        return _LangsysApp.getLocaleNameWithLookup(forLocale, shortName, inLocale);\n    }\n\n    /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */\n    public getLanguageName(forLocale: string, shortName?: boolean, inLocale?: string) {\n        return _LangsysApp.getLanguageName(forLocale, shortName, inLocale);\n    }\n\n    public detectPreferredLocale(acceptLanguageHeader?: string | null, supportedLocales?: string[]) {\n        return _LangsysApp.detectPreferredLocale(acceptLanguageHeader, supportedLocales);\n    }\n}\n\nexport const LangsysApp = new LangsysAppReact();\n"]}

package/dist/index.mjs

@@ -0,0 +1,111 @@
+import { createSignal, tSignal, currentlyLoadedLocale, sTranslations, Translate as Translate$1, LangsysApp as LangsysApp$1 } from 'langsys-js-typescript';
+export { LangsysAppAPI, createSignal, currentlyLoadedLocale, sTranslations, tSignal as t } from 'langsys-js-typescript';
+import { useSyncExternalStore, useState, useRef, useEffect, createElement } from 'react';
+
+// src/index.ts
+function useSignal(signal) {
+  return useSyncExternalStore(signal.subscribe, signal.get, signal.get);
+}
+function createLocaleStore(initial = "en-us") {
+  return createSignal(initial);
+}
+function useT() {
+  return useSignal(tSignal);
+}
+function useCurrentLocale() {
+  return useSignal(currentlyLoadedLocale);
+}
+function useTranslations() {
+  return useSignal(sTranslations);
+}
+function useLocaleStore(initial = "en-us") {
+  const [store] = useState(() => createLocaleStore(initial));
+  const locale = useSignal(store);
+  return [locale, store.set, store];
+}
+function Translate({
+  category = "",
+  custom_id = "",
+  label = "",
+  tag = "translate",
+  className,
+  children
+}) {
+  const hostRef = useRef(null);
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    const instance = new Translate$1(host, { category, custom_id, label });
+    return () => instance.destroy();
+  }, [category, custom_id, label]);
+  return createElement(tag, { ref: hostRef, className }, children);
+}
+
+// src/index.ts
+var LangsysAppReact = class {
+  /** Initialize Langsys. Pass a `Signal<string>` (from `createLocaleStore`) as `UserLocaleStore`. */
+  init(config) {
+    return LangsysApp$1.init(config);
+  }
+  get Translations() {
+    return LangsysApp$1.Translations;
+  }
+  get translationsLoadingPromise() {
+    return LangsysApp$1.translationsLoadingPromise;
+  }
+  /** Current translation function. Reads fresh state on every call (not reactive on its own — use `useT()` in components). */
+  get t() {
+    return LangsysApp$1.t;
+  }
+  get debug() {
+    return LangsysApp$1.debug;
+  }
+  refresh() {
+    return LangsysApp$1.refresh();
+  }
+  getCountries(inLocale) {
+    return LangsysApp$1.getCountries(inLocale);
+  }
+  getCountryName(forCountryCode, inLocale) {
+    return LangsysApp$1.getCountryName(forCountryCode, inLocale);
+  }
+  getCurrencies(inLocale) {
+    return LangsysApp$1.getCurrencies(inLocale);
+  }
+  getCurrencyName(forCurrencyCode, inLocale) {
+    return LangsysApp$1.getCurrencyName(forCurrencyCode, inLocale);
+  }
+  getDialCodes(inLocale) {
+    return LangsysApp$1.getDialCodes(inLocale);
+  }
+  getLocales(inLocale) {
+    return LangsysApp$1.getLocales(inLocale);
+  }
+  getLocalesFlat(inLocale) {
+    return LangsysApp$1.getLocalesFlat(inLocale);
+  }
+  getLocalesData(inLocale, forceRefresh) {
+    return LangsysApp$1.getLocalesData(inLocale, forceRefresh);
+  }
+  getLocalesFormat(format = "", inLocale) {
+    return LangsysApp$1.getLocalesFormat(format, inLocale);
+  }
+  getLocaleName(forLocale, shortName, inLocale) {
+    return LangsysApp$1.getLocaleName(forLocale, shortName, inLocale);
+  }
+  getLocaleNameWithLookup(forLocale, shortName, inLocale) {
+    return LangsysApp$1.getLocaleNameWithLookup(forLocale, shortName, inLocale);
+  }
+  /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */
+  getLanguageName(forLocale, shortName, inLocale) {
+    return LangsysApp$1.getLanguageName(forLocale, shortName, inLocale);
+  }
+  detectPreferredLocale(acceptLanguageHeader, supportedLocales) {
+    return LangsysApp$1.detectPreferredLocale(acceptLanguageHeader, supportedLocales);
+  }
+};
+var LangsysApp = new LangsysAppReact();
+
+export { LangsysApp, Translate, createLocaleStore, useCurrentLocale, useLocaleStore, useSignal, useT, useTranslations };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters.ts","../src/hooks.ts","../src/components/Translate.tsx","../src/index.ts"],"names":["VanillaTranslate","_LangsysApp"],"mappings":"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","file":"index.mjs","sourcesContent":["import { useSyncExternalStore } from 'react';\nimport { createSignal, type Signal } from 'langsys-js-typescript';\n\n/**\n * Subscribe a React component to a base-SDK `Signal<T>` and return its current\n * value, re-rendering whenever the signal changes.\n *\n * This is the React mirror of Svelte's `$store` auto-subscription. Where the\n * Svelte wrapper adapts a native store *into* the SDK (`writable` → `Signal`),\n * the React wrapper adapts the SDK's signals *out* to the render cycle. It is\n * built on `useSyncExternalStore`, so it is concurrent-safe and SSR-safe — the\n * server snapshot reads the same `.get()`, which the base SDK seeds from\n * `initialTranslations` during SSR.\n *\n * The base SDK's signals are stable between changes (every `set` replaces the\n * value, so `.get()` returns a fresh reference only after a real change). That\n * is exactly the identity contract `useSyncExternalStore` requires — no tearing,\n * no render loops.\n *\n * `signal` must be stable across renders: a module-level singleton (the SDK's\n * `t` / `currentlyLoadedLocale` / `sTranslations`) or one created once with\n * `useState(() => createLocaleStore(...))`. Passing a freshly-created signal on\n * every render would resubscribe on every render.\n */\nexport function useSignal<T>(signal: Signal<T>): T {\n    return useSyncExternalStore(signal.subscribe, signal.get, signal.get);\n}\n\n/**\n * Create a reactive `Signal<string>` to hold the user's selected locale — the\n * React analog of Svelte's `writable('en-us')`.\n *\n * Pass the result as `UserLocaleStore` to `LangsysApp.init`, read it reactively\n * with `useSignal(store)` (or use the all-in-one `useLocaleStore` hook), and\n * switch locale with `store.set('fr-fr')`. The base SDK only ever reads and\n * subscribes to it — it never writes.\n */\nexport function createLocaleStore(initial = 'en-us'): Signal<string> {\n    return createSignal<string>(initial);\n}\n","import { useState } from 'react';\nimport { currentlyLoadedLocale, sTranslations, tSignal } from 'langsys-js-typescript';\nimport type { Signal, TFunction, iCategories } from 'langsys-js-typescript';\nimport { createLocaleStore, useSignal } from './adapters.js';\n\n/**\n * The current translation function, re-rendering the calling component whenever\n * translations or the loaded locale change. This is the React analog of Svelte's\n * `$t` store read.\n *\n *   const t = useT();\n *   return <h1>{t('Welcome to my app', 'UI')}</h1>;\n *\n * The phrase is both the lookup key and the base-language default. Signature:\n * `t(phrase, category?, params?)`. Placeholder names in the phrase are\n * type-checked against the params object at the call site.\n */\nexport function useT(): TFunction {\n    return useSignal(tSignal);\n}\n\n/**\n * The locale whose translations are currently loaded. This lags the\n * user-selected locale (`UserLocaleStore`) until the fetch for the new locale\n * settles, which makes it the right value to gate \"translations are ready\" UI on.\n */\nexport function useCurrentLocale(): string {\n    return useSignal(currentlyLoadedLocale);\n}\n\n/**\n * The raw translation catalog. Rarely needed in app code — prefer `useT()`.\n * Exposed for advanced cases (inspecting which categories/phrases are loaded).\n */\nexport function useTranslations(): iCategories {\n    return useSignal(sTranslations);\n}\n\n/**\n * All-in-one convenience for the user-locale store. Creates one stable\n * `Signal<string>` (the React analog of Svelte's `writable`), subscribes the\n * component to it, and returns `[locale, setLocale, store]`.\n *\n *   const [locale, setLocale, store] = useLocaleStore('en-us');\n *   useEffect(() => {\n *     LangsysApp.init({ projectid, key, UserLocaleStore: store });\n *   }, [store]);\n *\n *   <select value={locale} onChange={(e) => setLocale(e.target.value)}>...\n *\n * The store is created lazily once and never re-created across renders, so it is\n * safe to pass to `LangsysApp.init` and to depend on in effects.\n */\nexport function useLocaleStore(initial = 'en-us'): [string, (locale: string) => void, Signal<string>] {\n    const [store] = useState(() => createLocaleStore(initial));\n    const locale = useSignal(store);\n    return [locale, store.set, store];\n}\n","import { createElement, useEffect, useRef } from 'react';\nimport type { ReactNode } from 'react';\nimport { Translate as VanillaTranslate } from 'langsys-js-typescript';\n\n/**\n * Props for the React `Translate` component. Mirrors the Svelte component's\n * props 1:1, with Svelte's `class` renamed to React's idiomatic `className`.\n */\nexport interface TranslateProps {\n    /** Optional category under which tokens are registered. Helps translators disambiguate. */\n    category?: string;\n    /** Optional stable id for the content block. If omitted, the SDK hashes category + tokens. */\n    custom_id?: string;\n    /** Optional human-readable label shown in the Translation Manager. */\n    label?: string;\n    /** Host element tag. Defaults to a `<translate>` custom element. */\n    tag?: string;\n    /** Class applied to the host element. */\n    className?: string;\n    children?: ReactNode;\n}\n\n/**\n * React wrapper around the vanilla `Translate` DOM class from\n * `langsys-js-typescript`. It renders a host element, then on mount lets the\n * vanilla class walk and tokenize the rendered children (text nodes plus\n * translatable attributes), register the content block, and re-translate on\n * locale change. On unmount it tears the instance down.\n *\n * This is the React analog of the Svelte `<Translate>` component — pure\n * mount/destroy glue. The DOM walking, content-block registration, attribute\n * harvesting, and re-translation lifecycle all live in the base SDK.\n *\n * Like the Svelte component, this lets the SDK mutate the rendered DOM in place,\n * so keep the children static: prose, marketing copy, CMS-rendered HTML — the\n * content-block use case. For dynamic per-string values that React owns and\n * re-renders, use `useT()` instead.\n */\nexport function Translate({\n    category = '',\n    custom_id = '',\n    label = '',\n    tag = 'translate',\n    className,\n    children,\n}: TranslateProps) {\n    const hostRef = useRef<HTMLElement | null>(null);\n\n    useEffect(() => {\n        const host = hostRef.current;\n        if (!host) return;\n        const instance = new VanillaTranslate(host, { category, custom_id, label });\n        return () => instance.destroy();\n    }, [category, custom_id, label]);\n\n    return createElement(tag, { ref: hostRef, className }, children);\n}\n\nexport default Translate;\n","/**\n * langsys-js-react — idiomatic React binding over `langsys-js-typescript`.\n *\n * Public API:\n *   - `LangsysApp` — `init` accepts a `Signal<string>` (make one with\n *     `createLocaleStore`) for the user locale; every other method delegates.\n *   - Hooks — `useT`, `useCurrentLocale`, `useTranslations`, `useLocaleStore`,\n *     and the low-level `useSignal`. These are the reactive layer; in components\n *     prefer them over the raw signals.\n *   - `createLocaleStore` — make the user-locale store (React analog of Svelte's\n *     `writable`).\n *   - `Translate` — React component wrapping the vanilla DOM `Translate` class.\n *   - Raw signals `t` / `currentlyLoadedLocale` / `sTranslations` — re-exported\n *     for advanced/direct subscription outside React's render cycle.\n */\n\nimport {\n    LangsysApp as _LangsysApp,\n    type ExtractParamKeys,\n    type ParamPrimitive,\n    type ParamsFor,\n    type Signal,\n    type TArgs,\n    type TFunction,\n    type TranslationParams,\n    type iCategories,\n    type iContentBlock,\n    type iCountry,\n    type iCountryDialCode,\n    type iCountryList,\n    type iCurrency,\n    type iCurrencyList,\n    type iLangsysInitConfig as iVanillaInitConfig,\n    type iLangsysResponse,\n    type iLanguageName,\n    type iLocaleData,\n    type iLocaleDefault,\n    type iLocaleFlat,\n    type iProject,\n    type iTranslations,\n} from 'langsys-js-typescript';\n\n// Reactive primitives (raw signals) — re-exported for advanced/direct\n// subscription. `tSignal` is exposed under the friendlier name `t`. In\n// components, prefer the hooks (`useT`, `useCurrentLocale`, …).\nexport { currentlyLoadedLocale, createSignal, sTranslations, tSignal as t } from 'langsys-js-typescript';\n\n// API client (vanilla — no React concerns)\nexport { LangsysAppAPI } from 'langsys-js-typescript';\n\n// Hooks + adapters (the React-idiomatic reactive layer)\nexport { createLocaleStore, useSignal } from './adapters.js';\nexport { useCurrentLocale, useLocaleStore, useT, useTranslations } from './hooks.js';\n\n// Component\nexport { Translate, type TranslateProps } from './components/Translate.js';\n\n// Type re-exports — these are framework-agnostic, so consumers can rely on them\n// directly without reaching into `langsys-js-typescript`.\nexport type {\n    ExtractParamKeys,\n    ParamPrimitive,\n    ParamsFor,\n    Signal,\n    TArgs,\n    TFunction,\n    TranslationParams,\n    iCategories,\n    iContentBlock,\n    iCountry,\n    iCountryDialCode,\n    iCountryList,\n    iCurrency,\n    iCurrencyList,\n    iLangsysResponse,\n    iLanguageName,\n    iLocaleData,\n    iLocaleDefault,\n    iLocaleFlat,\n    iProject,\n    iTranslations,\n};\n\n/**\n * React-flavored init config. Identical to the base SDK's config except\n * `UserLocaleStore` is typed as a `Signal<string>` — create one with\n * `createLocaleStore()` (or get one from the `useLocaleStore` hook). The base\n * SDK only reads and subscribes to it.\n */\nexport interface iLangsysInitConfig extends Omit<iVanillaInitConfig, 'UserLocaleStore'> {\n    UserLocaleStore: Signal<string>;\n}\n\n/**\n * React SDK entry point. Delegates everything to the underlying\n * `langsys-js-typescript` singleton. Because React's locale store is already a\n * `Signal` (unlike Svelte's `Writable`, which needs adapting), `init` is a\n * straight passthrough — the React-native concerns live in the hooks and the\n * `<Translate>` component, not here.\n */\nclass LangsysAppReact {\n    /** Initialize Langsys. Pass a `Signal<string>` (from `createLocaleStore`) as `UserLocaleStore`. */\n    public init(config: iLangsysInitConfig): Promise<iLangsysResponse> {\n        return _LangsysApp.init(config);\n    }\n\n    public get Translations() {\n        return _LangsysApp.Translations;\n    }\n\n    public get translationsLoadingPromise() {\n        return _LangsysApp.translationsLoadingPromise;\n    }\n\n    /** Current translation function. Reads fresh state on every call (not reactive on its own — use `useT()` in components). */\n    public get t(): TFunction {\n        return _LangsysApp.t;\n    }\n\n    public get debug() {\n        return _LangsysApp.debug;\n    }\n\n    public refresh() {\n        return _LangsysApp.refresh();\n    }\n\n    public getCountries(inLocale?: string) {\n        return _LangsysApp.getCountries(inLocale);\n    }\n    public getCountryName(forCountryCode: string, inLocale?: string) {\n        return _LangsysApp.getCountryName(forCountryCode, inLocale);\n    }\n    public getCurrencies(inLocale?: string) {\n        return _LangsysApp.getCurrencies(inLocale);\n    }\n    public getCurrencyName(forCurrencyCode: string, inLocale?: string) {\n        return _LangsysApp.getCurrencyName(forCurrencyCode, inLocale);\n    }\n    public getDialCodes(inLocale?: string) {\n        return _LangsysApp.getDialCodes(inLocale);\n    }\n\n    public getLocales(inLocale?: string) {\n        return _LangsysApp.getLocales(inLocale);\n    }\n    public getLocalesFlat(inLocale?: string) {\n        return _LangsysApp.getLocalesFlat(inLocale);\n    }\n    public getLocalesData(inLocale?: string, forceRefresh?: boolean) {\n        return _LangsysApp.getLocalesData(inLocale, forceRefresh);\n    }\n    public getLocalesFormat(format: '' | 'flat' | 'data' = '', inLocale?: string) {\n        return _LangsysApp.getLocalesFormat(format, inLocale);\n    }\n    public getLocaleName(forLocale: string, shortName?: boolean, inLocale?: string) {\n        return _LangsysApp.getLocaleName(forLocale, shortName, inLocale);\n    }\n    public getLocaleNameWithLookup(forLocale: string, shortName?: boolean, inLocale?: string) {\n        return _LangsysApp.getLocaleNameWithLookup(forLocale, shortName, inLocale);\n    }\n\n    /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */\n    public getLanguageName(forLocale: string, shortName?: boolean, inLocale?: string) {\n        return _LangsysApp.getLanguageName(forLocale, shortName, inLocale);\n    }\n\n    public detectPreferredLocale(acceptLanguageHeader?: string | null, supportedLocales?: string[]) {\n        return _LangsysApp.detectPreferredLocale(acceptLanguageHeader, supportedLocales);\n    }\n}\n\nexport const LangsysApp = new LangsysAppReact();\n"]}

package/package.json

@@ -0,0 +1,83 @@
+{
+    "name": "langsys-js-react",
+    "version": "0.1.0",
+    "description": "React binding for the Langsys translation SDK — realtime continuous translations with automatic token discovery, delivered as hooks and a <Translate> component.",
+    "author": "Langsys",
+    "license": "MIT",
+    "homepage": "https://github.com/langsys/langsys-js-react",
+    "repository": {
+        "type": "git",
+        "url": "git+ssh://git@github.com/langsys/langsys-js-react.git"
+    },
+    "bugs": {
+        "url": "https://github.com/langsys/langsys-js-react/issues"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "README-SSR.md",
+        "CHANGELOG.md",
+        "LICENSE"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "dev": "vite",
+        "build": "tsup",
+        "build:watch": "tsup --watch",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "prettier --check . && eslint .",
+        "format": "prettier --write .",
+        "prepublishOnly": "npm run build",
+        "release": "./_dev_/publish.sh"
+    },
+    "keywords": [
+        "i18n",
+        "l10n",
+        "react",
+        "react-hooks",
+        "language",
+        "localization",
+        "internationalization",
+        "translation",
+        "langsys",
+        "sdk"
+    ],
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+    },
+    "dependencies": {
+        "langsys-js-typescript": "^0.2.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^5.0.0",
+        "eslint": "^9.0.0",
+        "eslint-config-prettier": "^10.0.0",
+        "eslint-plugin-react-hooks": "^5.0.0",
+        "prettier": "^3.3.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "tsup": "^8.4.0",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.0.0",
+        "vite": "^6.0.0",
+        "vitest": "^4.1.7"
+    }
+}