langsys-js-react 0.6.6 → 0.7.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import * as langsys_js_typescript from 'langsys-js-typescript';
-import { Signal, TFunction, iCategories, ParamPrimitive, iLangsysInitConfig as iLangsysInitConfig$1, iLangsysResponse, iCountryList, iCurrencyList, iCountryDialCode, iLocaleDefault, iLocaleFlat, iLocaleData } from 'langsys-js-typescript';
-export { ExtractParamKeys, LangsysAppAPI, ParamPrimitive, ParamsFor, Signal, TArgs, TFunction, TranslationParams, canonicalizeLocale, 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 { Signal, ServerMessage, TFunction, iCategories, ParamPrimitive, RequestSeed, RequestScope } from 'langsys-js-typescript';
+export { CatalogSnapshot, CategoryMoveOptions, CategoryRef, DEFAULT_SERVER_MESSAGE_CATEGORY, ExtractParamKeys, LangsysAppAPI, LangsysConfigurationError, LegacyFormatError, LegacyKeyFile, ParamPrimitive, ParamsFor, RegistrationReason, RegistrationResult, ResolveServerMessagesOptions, ServerMessage, ServerMessagePieces, Signal, SnapshotError, TArgs, TFunction, TranslationParams, WriteGrant, canonicalizeLocale, createSignal, currentlyLoadedLocale, iCategories, iContentBlock, iCountry, iCountryDialCode, iCountryList, iCurrency, iCurrencyList, iLangsysResponse, iLanguageName, iLocaleData, iLocaleDefault, iLocaleFlat, iProject, iTranslations, inCategory, interpolate, isCategoryRef, localeHeaders, notifyNavigation, renderServerMessage, resolveServerMessages, sTranslations, setWriteGrant, tSignal as t } from 'langsys-js-typescript';
 import * as react from 'react';
 import { ReactNode } from 'react';
+export { L as LangsysApp, c as createLocaleStore, i as iLangsysInitConfig } from './app-zQKL7-vo.js';
 
 /**
  * Subscribe a React component to a base-SDK `Signal<T>` and return its current
@@ -11,9 +11,12 @@ import { ReactNode } from 'react';
  * 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.
+ * built on `useSyncExternalStore`, so it is concurrent-safe: a render never
+ * observes two different values of the same signal (no tearing). On the
+ * server the snapshot reads the value for the current request: inside a core
+ * request scope the signals answer from the scope, and under a
+ * `<LangsysProvider seed>` the server snapshot — used for the server render and
+ * the hydration render — reads through the scope the provider rebuilt.
  *
  * 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
@@ -26,21 +29,6 @@ import { ReactNode } from 'react';
  * 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.
- *
- * Locale identifiers are canonicalized to BCP 47 by the base SDK (v0.3.0+), so
- * `'en-us'` still works on input — but `currentlyLoadedLocale` always emits the
- * canonical form (`'en-US'`), so prefer canonical casing to keep comparisons
- * against it straightforward.
- */
-declare function createLocaleStore(initial?: string): Signal<string>;
 
 /**
  * The current translation function, re-rendering the calling component whenever
@@ -82,6 +70,66 @@ declare function useTranslations(): iCategories;
  * safe to pass to `LangsysApp.init` and to depend on in effects.
  */
 declare function useLocaleStore(initial?: string): [string, (locale: string) => void, Signal<string>];
+/**
+ * Whether the current session may register content, as decided by the server.
+ *
+ * Tri-state, and the three states are genuinely distinct:
+ *   - `undefined` — authorization hasn't landed yet. Not the same as read-only.
+ *   - `false`     — read-only session; the SDK may report the page URL instead,
+ *                   subject to the key's auto-discovery permission. A read-only
+ *                   key with discovery disallowed reports nothing at all.
+ *   - `true`      — this session registers content directly.
+ *
+ * Don't collapse it to a boolean and don't default `undefined` to `false`: the
+ * same key can be write-enabled from one IP and read-only from another, so only
+ * the server can answer, and "not yet known" is a real state to render for.
+ *
+ * Unlike the other hooks this does *not* go through `useSignal`. `writeEnabled`
+ * is browser-authoritative — it is only ever written client-side and stays
+ * `undefined` during SSR. Reusing `useSignal` would pass `signal.get` as the
+ * server snapshot, and `getServerSnapshot` is used both on the server *and* for
+ * the hydration render on the client. If authorization resolved before
+ * hydration, that render would disagree with the server HTML and React would
+ * throw the markup away. Pinning the server snapshot to `undefined` keeps the
+ * hydration pass matching the server; the real value arrives right after.
+ */
+declare function useWriteEnabled(): boolean | undefined;
+/**
+ * Tell the SDK the route changed, whenever `location` changes. Call it once, anywhere under
+ * your router, with the router's current location:
+ *
+ *   // React Router
+ *   useNotifyNavigation(useLocation().key);
+ *   // Next.js App Router
+ *   useNotifyNavigation(usePathname() + '?' + useSearchParams());
+ *
+ * Why it exists: content that stays mounted across a route change — a persistent layout, a
+ * header — is never re-rendered by React when only the route changes, because React skips
+ * a subtree whose element is unchanged. Nothing then calls back into the SDK, so the new
+ * page is never credited with that content. `notifyNavigation()` makes every mounted
+ * translated node look itself up again at the new URL. This hook only times that call; the
+ * SDK decides everything else (spec HINT-13).
+ *
+ * This package cannot know which router an app uses, so it takes the router's location as a
+ * plain value instead of importing any router. Calling `notifyNavigation` directly from a
+ * router's own after-navigation hook is equivalent.
+ */
+declare function useNotifyNavigation(location: unknown): void;
+/**
+ * A function that renders server message entries, re-rendering the calling component whenever
+ * translations or the loaded locale change:
+ *
+ *   const render = useRenderServerMessage();
+ *   const entries = resolveServerMessages(responseBody);
+ *   return <ul>{entries.map((e, i) => <li key={i}>{render(e)}</li>)}</ul>;
+ *
+ * It is the SDK's `renderServerMessage` and decides nothing itself: the entry's template is
+ * looked up under the messages category (`messagesCategory` in `init`, `Errors` by default) and
+ * filled from its params, and the entry's `message` is shown when the catalog has no
+ * translation for it (spec MSG-5). The returned function changes identity exactly when a
+ * lookup could give a different answer, so it can be depended on in memos and effects.
+ */
+declare function useRenderServerMessage(): (entry: ServerMessage, category?: string) => string;
 
 /**
  * Props for the React `Translate` component. Mirrors the Svelte component's
@@ -90,6 +138,15 @@ declare function useLocaleStore(initial?: string): [string, (locale: string) =>
 interface TranslateProps {
     /** Optional category under which tokens are registered. Helps translators disambiguate. */
     category?: string;
+    /**
+     * The category this content was registered under before it moved to `category` (MOVE-1):
+     * `''` for none, absent for no move. Its translations follow it instead of being made, and
+     * charged for, again; until the catalog holds it under `category`, the previous category's
+     * entry renders and the host says so (MOVE-4, MOVE-5). Never part of its identity (MOVE-2),
+     * and sent only on the registration a miss triggers (MOVE-3), so once the catalog has it the
+     * prop does nothing and can be deleted whenever convenient.
+     */
+    previousCategory?: string | null;
     /** 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. */
@@ -100,6 +157,13 @@ interface TranslateProps {
      * `{key}` at capture). Applied to content-block text nodes, translatable
      * attributes, `<option>` text, and single-token content — including
      * untranslated fallbacks. Number/Date values get CLDR locale formatting.
+     *
+     * A bare `{key}` doesn't just break interpolation — JSX evaluates it before
+     * the walker runs, so the *value* is captured as part of the phrase and each
+     * distinct value hashes to its own content block. A `<Translate>` around a
+     * live counter registers a new block per tick while rendering correctly in
+     * the base locale the whole time. `%key%` yields one stable id for all
+     * values.
      */
     params?: Record<string, ParamPrimitive>;
     /** Host element tag. Defaults to a `<translate>` custom element. */
@@ -107,24 +171,30 @@ interface TranslateProps {
     /** Class applied to the host element. */
     className?: string;
     children?: ReactNode;
+    /**
+     * Set by the build transform when the block would store a value it left as written (inside
+     * MathML or SVG, `<script>` or `<style>`, or an element that holds text only): the block
+     * registers nothing (VAR-7) and renders what the catalog holds.
+     */
+    'data-ls-unnamed'?: string;
 }
 /**
- * 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.
+ * Translates a block of static content: prose, markup, CMS copy.
+ *
+ * Content made of host elements, text and numbers renders through the core's `renderBlock`: the
+ * translated tree, the block's id and its markers come back as data, and this component renders
+ * them as React elements — the originals, cloned with their handlers, refs and keys, in the
+ * places the translation puts them. The same call runs on a server (inside a request scope) and
+ * in the browser (over the seeded catalog), so the first client render matches the server's HTML,
+ * and a locale change re-renders it. Registration goes through the core's `registerBlock`; no DOM
+ * class ever walks text nodes React owns.
+ *
+ * Content whose DOM is unknown until React renders it — a component, `lazy`, `Suspense`, or
+ * `dangerouslySetInnerHTML` — is rendered as it is, with an explicit `custom_id` stamped, and the
+ * core's DOM `Translate` class translates it after mount. On a server the core warns once per
+ * reason that such a block was served as source.
  */
-declare function Translate({ category, custom_id, label, params, tag, className, children, }: TranslateProps): react.ReactElement<{
+declare function Translate({ category: named, previousCategory: namedPrevious, custom_id, label, params: given, tag, className, children: content, 'data-ls-unnamed': unmarked, }: TranslateProps): react.ReactElement<{
     ref: react.RefObject<HTMLElement | null>;
     className: string | undefined;
 }, string | react.JSXElementConstructor<any>>;
@@ -136,13 +206,34 @@ declare function Translate({ category, custom_id, label, params, tag, className,
 interface PhraseProps {
     /** Category the phrase registers under (disambiguation for translators). */
     category?: string;
-    /** Interpolation params. Write placeholders as `%n%` / `%name%` in the markup (a bare `{n}` in JSX is an expression). */
+    /**
+     * The category this content was registered under before it moved to `category` (MOVE-1):
+     * `''` for none, absent for no move. Its translations follow it instead of being made, and
+     * charged for, again; until the catalog holds it under `category`, the previous category's
+     * entry renders and the host says so (MOVE-4, MOVE-5). Never part of its identity (MOVE-2),
+     * and sent only on the registration a miss triggers (MOVE-3), so once the catalog has it the
+     * prop does nothing and can be deleted whenever convenient.
+     */
+    previousCategory?: string | null;
+    /**
+     * Interpolation params. Write placeholders as `%n%` / `%name%` in the markup.
+     * A bare `{n}` in JSX is an expression React evaluates before the SDK sees the
+     * text, so the *value* lands in the captured phrase and each distinct value
+     * becomes its own phrase to translate. `%n%` yields one stable phrase.
+     */
     params?: Record<string, ParamPrimitive>;
     /** Host element tag. Defaults to `<span>`. */
     tag?: string;
     /** Class applied to the host element. */
     className?: string;
     children?: ReactNode;
+    /**
+     * Set by the build transform when every value of the phrase is marked (it holds a marker of its
+     * own) and one in its translated text stands where no marker can (in a translated `<svg>`, or an
+     * element that holds text only), so it is left as written: the phrase registers nothing (VAR-7)
+     * and renders what the catalog holds.
+     */
+    'data-ls-unnamed'?: string;
 }
 /**
  * React wrapper around the vanilla `Phrase` rich-text handler.
@@ -158,6 +249,15 @@ interface PhraseProps {
  * expression React evaluates before the SDK sees the text. `%n%` passes through
  * as literal text and the SDK normalizes it to canonical `{n}` at capture.
  *
+ * The cost of getting this wrong is not a broken placeholder, it's catalog
+ * churn. `<Phrase>` keys on the encoded phrase string, so the substituted value
+ * becomes part of the key — a new phrase per distinct value, none reusable,
+ * with the base locale rendering correctly throughout. Measured against the
+ * shipped `encodeRichText`:
+ *
+ *   {n} via JSX        "Based on 0 {m0o}reviews{m0c}"   (and 1, 2, … each new)
+ *   %n% placeholder    "Based on {n} {m0o}reviews{m0c}" (stable for all values)
+ *
  * The inline markup never reaches the translator — it's replaced with neutral
  * tokens and the real elements are reconstituted at render (see richtext.ts in
  * the base SDK). The host carries `data-ls-phrase` so a wrapping `<Translate>`
@@ -166,10 +266,9 @@ interface PhraseProps {
  * Keep children static (literal markup): the handler takes over the rendered
  * subtree. For values React owns and re-renders, pass them through `params`.
  */
-declare function Phrase({ category, params, tag, className, children }: PhraseProps): react.ReactElement<{
+declare function Phrase({ category: named, previousCategory: namedPrevious, params: given, tag, className, children: content, 'data-ls-unnamed': unmarked, }: PhraseProps): react.ReactElement<{
     ref: react.RefObject<HTMLElement | null>;
     className: string | undefined;
-    "data-ls-phrase": string;
 }, string | react.JSXElementConstructor<any>>;
 
 /**
@@ -192,7 +291,9 @@ interface DontTranslateProps {
  * The host carries the standard `translate="no"` attribute, which both the
  * tokenizer and the renderer in the base SDK already honor — so its content is
  * never tokenized, registered, or replaced. Pure presentational glue; no
- * vanilla handler needed.
+ * vanilla handler needed. Inside `<Translate>` / `<Phrase>` the block mapping reads it as the host
+ * element it renders (`toBlockNodes`), so the unit around it stays on the core's tree path, and the
+ * build transform marks a value inside it rather than replacing it (VAR-3).
  *
  * `data-ls-dont-translate` is a **wrapper-level hook only** — a styling and
  * debugging handle. The base SDK has never matched on it (verified against
@@ -207,46 +308,30 @@ declare function DontTranslate({ tag, className, children }: DontTranslateProps)
     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>;
+interface LangsysProviderProps {
+    /** The request's seed, from `scope.seed()` in a server component, passed down as a prop. */
+    seed: RequestSeed | null | undefined;
+    children?: ReactNode;
 }
 /**
- * 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.
+ * Renders a request in its own locale and catalog where the framework renders client
+ * components separately from the code that opened the request's scope — Next.js's App Router,
+ * where server components and client components use separate copies of the SDK.
+ *
+ *   // app/layout.tsx (a server component)
+ *   const scope = await createRequestScope({ locale, url });   // from langsys-js-react/server
+ *   return <LangsysProvider seed={scope.seed()}>{children}</LangsysProvider>;
+ *
+ * On the server, the provider rebuilds the request's scope from the seed with the core's
+ * `scopeFromSeed` and hands it down: `useT()`, `useCurrentLocale()`, `useTranslations()`,
+ * `<Translate>` and `<Phrase>` render from it. In the browser it seeds the SDK with the same
+ * catalog before any child's effect runs, and the hydration render reads the same scope, so the
+ * client's first render matches the server's HTML.
+ *
+ * Content a client component misses during the server render is registered by the browser after
+ * hydration. Under the `server` SSR strategy those misses are not sent from the server: the
+ * provider's side of the render has no after-response hook.
  */
-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;
+declare function LangsysProvider({ seed, children }: LangsysProviderProps): react.FunctionComponentElement<react.ProviderProps<RequestScope | null>>;
 
-export { DontTranslate, type DontTranslateProps, LangsysApp, Phrase, type PhraseProps, Translate, type TranslateProps, createLocaleStore, type iLangsysInitConfig, useCurrentLocale, useLocaleStore, useSignal, useT, useTranslations };
+export { DontTranslate, type DontTranslateProps, LangsysProvider, type LangsysProviderProps, Phrase, type PhraseProps, Translate, type TranslateProps, useCurrentLocale, useLocaleStore, useNotifyNavigation, useRenderServerMessage, useSignal, useT, useTranslations, useWriteEnabled };