@hydraharness/harness-client-locale 0.1.1-rc.6

package/lib/index.js

@@ -0,0 +1,26 @@
+import { settingsNamespace } from "@hydraharness/harness-settings";
+import z from "@hydraharness/schemastery";
+//#region lib/types/locale-settings.js
+/** Locale preference stored in the Host user-settings document. */
+/** Settings namespace owned by the locale plugin. */
+const LOCALE_SETTINGS_NAMESPACE = "locale";
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+const LOCALE_PREFERENCE_FIELD = "preference";
+/** Locale identifiers shipped by the browser client. */
+const LOCALE_IDS = ["en"];
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+const LocaleSettingsSchema = z.object({ [LOCALE_PREFERENCE_FIELD]: z.union([...LOCALE_IDS]).required(false) });
+//#endregion
+//#region lib/types/index.js
+/** Host registration for the browser locale preference. */
+/**
+* Register the durable locale section when a settings provider exists.
+* @param ctx - Host context whose optional settings service owns the section.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(settingsNamespace(LOCALE_SETTINGS_NAMESPACE), LocaleSettingsSchema);
+	});
+}
+//#endregion
+export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-client-locale`.
+* @module @hydraharness/harness-client-locale/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-client-locale";
+/** Cordis companion plugin name. */
+const name = "client-locale-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: ns-by-locale dictionary registry with a stable
+* bind(ns) API — it emits no cordis events and owns no cross-plugin
+* mutable relation; fallback-chain resolution and locale-store behavior are
+* asserted directly by this package's behavior specs.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/LanguageRow.d.ts

@@ -0,0 +1,16 @@
+import type { PropsLocale, PropsRuntime, PropsStore } from '@hydraharness/harness-client-ui-slots';
+import type { createLanguageRowStore } from './settings-store.ts';
+/** Injected business face: the preference write (t rides the standard locale seat). */
+export interface LanguageRowInjected {
+    /** Switch the active locale (a registered locale id). */
+    setLocale: (id: string) => void;
+}
+/** Full component props: runtime share + store share + locale seat + injected face. */
+export type LanguageRowComponentProps = PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createLanguageRowStore>> & PropsLocale<'settings.locale'> & LanguageRowInjected;
+/**
+ * Render the Language row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export declare function LanguageRow({ t, setLocale, useStore }: LanguageRowComponentProps): import("react").JSX.Element;
+//# sourceMappingURL=LanguageRow.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Browser-side locale registry. Bound translation functions retain stable
+ * identity for injected consumers. The plugin also registers the Language
+ * preference row into the settings General section — the locale feature owns
+ * its own settings surface.
+ */
+import type { Context } from '@hydraharness/cordis';
+import { type LocaleDictOf, type LocaleNamespaceMap, type Translate, type TranslateNS } from '@hydraharness/harness-client-ui-slots';
+import type { ClientContext, SettingsScope } from '@hydraharness/harness-client-runtime/client';
+import { type LocaleId, type LocaleSettings } from '../locale-settings.ts';
+import { type CommonKey } from '../locales/index.ts';
+import { type SettingsLocaleKey } from '../locales/settings.ts';
+export type { LanguageRowComponentProps, LanguageRowInjected } from './LanguageRow.tsx';
+export type { LanguageOptionRow, LanguageRowState } from './settings-store.ts';
+export type { CommonKey } from '../locales/index.ts';
+export type { LocaleId, LocaleSettings } from '../locale-settings.ts';
+export type { Translate, TranslateNS } from '@hydraharness/harness-client-ui-slots';
+declare module '@hydraharness/harness-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Shared cross-feature vocabulary, consulted by the lookup chain after the entry's own namespace misses. */
+        common: CommonKey;
+        /** This feature's own settings-row copy (the Language row). */
+        'settings.locale': SettingsLocaleKey;
+    }
+}
+/** Locale dictionary: flat key to template string ({name} placeholders). */
+export type LocaleDict = Record<string, string>;
+/** One selectable locale: id plus its self-described display name. */
+export interface LocaleDefinition {
+    /** Locale id (persisted; the setLocale argument). */
+    id: LocaleId;
+    /** Display name in its own language (English). */
+    label: string;
+}
+/** Immutable locale state published on every change. */
+export interface LocaleSnapshot {
+    /** Active locale id. */
+    active: LocaleId;
+    /** Selectable locales in display order. */
+    locales: readonly LocaleDefinition[];
+    /** Monotonic change counter (registry or active changes). */
+    revision: number;
+}
+declare module '@hydraharness/cordis' {
+    interface Context {
+        locale: LocaleRuntime;
+    }
+    interface Events {
+        /**
+         * The active locale switched. Dictionary registrations do NOT emit this
+         * event (listeners may re-register slots in response, and boot registers
+         * one namespace per package); continuous render refresh rides the
+         * LocaleFace revision instead.
+         * @param snapshot - Current immutable locale snapshot.
+         * @mode emit
+         */
+        'locale/change'(snapshot: LocaleSnapshot): void;
+    }
+}
+/**
+ * English is both the locale the UI opens in when the browser names no shipped
+ * language (and for non-browser runs), and the dictionary consulted after the
+ * active locale misses a key. It is currently the only shipped locale, so
+ * neither direction can leave a key unresolved.
+ */
+export declare const FALLBACK_LOCALE: LocaleId;
+/** Shared namespace for shell-level texts. */
+export declare const COMMON_NS = "common";
+/** Namespace owning this feature's settings-row copy. */
+export declare const SETTINGS_NS = "settings.locale";
+/**
+ * Dictionary registry plus locale preference. Lookup chain per key: the
+ * entry's namespace in the active locale -> that namespace's en fallback ->
+ * the shared common namespace (active, then en) -> the key itself (missing
+ * text stays visible, fail loud in the UI rather than blank). Reads go
+ * through {@link getLocale}; writes only through {@link setLocale};
+ * continuous sync through the `locale/change` event, or through the
+ * LocaleFace getSnapshot/subscribe pair the render machinery consumes
+ * (installed via `ctx.slots.installLocale`).
+ */
+export declare class LocaleRuntime {
+    private dicts;
+    private bound;
+    private snapshot;
+    private listeners;
+    private readonly ctx;
+    private readonly host;
+    /** Browser-derived locale standing wherever no explicit Host selection does. */
+    private readonly provisional;
+    /**
+     * @param ctx - owning context (change events are emitted on it; the scope
+     * listener is released through ctx.effect on dispose).
+     * @param host - durable preference scope owned by the providing plugin;
+     * absent compositions (standalone dictionary registries) stay process-local.
+     */
+    constructor(ctx: Context, host?: SettingsScope<LocaleSettings>);
+    /**
+     * Read the current immutable locale snapshot.
+     * @returns the current snapshot (stable reference until the next change).
+     */
+    getLocale(): LocaleSnapshot;
+    /**
+     * LocaleFace getSnapshot: the current snapshot (carries `revision`; stable
+     * reference between changes, uSES-safe).
+     * @returns the current snapshot.
+     */
+    getSnapshot(): LocaleSnapshot;
+    /**
+     * LocaleFace subscribe: notified on every snapshot change (locale switch
+     * or dictionary registration — registrations bump the revision so already
+     * rendered outlets pick up late-arriving dictionaries).
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Switch the active locale — the only user preference write entry.
+     *
+     * The durable write happens even when the id already matches the active
+     * locale, because the active value may be a provisional browser-derived or
+     * fallback resolution that nothing has stored yet. Picking the language
+     * already on screen is still an explicit choice, and it must survive a
+     * different browser sharing the same Hydra home. Only the render notification
+     * is conditional: republishing an unchanged locale would churn every
+     * subscriber for nothing.
+     * @param id - a registered locale id; unknown ids throw.
+     */
+    setLocale(id: string): void;
+    /**
+     * Adopt the scope's accepted durable selection without writing it back; an
+     * absent selection returns to the browser-derived locale.
+     * @param host - the constructor-narrowed scope driving this adoption.
+     */
+    private adopt;
+    /**
+     * Register a declared namespace's dictionaries, all locales in one call —
+     * the typed form: each dictionary is checked against the namespace's
+     * {@link LocaleNamespaceMap} key union (a missing or extra key is a
+     * compile error), and every shipped locale is required at registration.
+     * Duplicate (ns, locale) throws (single occupant; a
+     * namespace's texts have one owner). Registration bumps the revision so
+     * mounted outlets pick up late-arriving dictionaries.
+     * @param ns - a namespace merged into LocaleNamespaceMap.
+     * @param dicts - complete dictionaries keyed by locale id.
+     * @returns disposer removing every locale registered by this call (idempotent).
+     */
+    register<N extends keyof LocaleNamespaceMap & string>(ns: N, dicts: Record<LocaleId, LocaleDictOf<N>>): () => void;
+    /**
+     * Single-locale untyped form for namespaces outside the merge table
+     * (dynamic composition, tests).
+     * @param ns - namespace.
+     * @param locale - locale tag.
+     * @param dict - dictionary.
+     * @returns disposer (idempotent).
+     */
+    register(ns: string, locale: string, dict: LocaleDict): () => void;
+    /**
+     * Bind a declared namespace to a translate function typed to its
+     * dictionary key union (plus the shared common vocabulary) — the same key
+     * domain the framework-injected `t` seat carries. The returned reference
+     * is stable per namespace (repeat binds return the same function), so it
+     * can ride inject surfaces without breaking memoization.
+     * @param ns - a namespace merged into LocaleNamespaceMap.
+     * @returns the typed translate function (reads the active locale at call time).
+     */
+    bind<N extends keyof LocaleNamespaceMap & string>(ns: N): TranslateNS<N>;
+    /**
+     * Untyped form for namespaces outside the merge table (dynamic
+     * composition, tests).
+     * @param ns - namespace.
+     * @returns the translate function.
+     */
+    bind(ns: string): Translate;
+    private translate;
+    private lookup;
+    /**
+     * Advance the snapshot revision and notify LocaleFace subscribers (render
+     * refresh). Only an active-locale switch additionally emits
+     * `locale/change` — dictionary registrations stay off the event so
+     * registration-heavy boot cannot storm event listeners (which may
+     * re-register slots in response).
+     */
+    private publish;
+}
+/** Required services: slot registration plus the settings transport. */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide the locale service with base dictionaries and
+ * register the feature-owned Language preference row into the General
+ * section's item slot (a feature owns its settings surface).
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/settings-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Language row slot store: a mirror of the locale service snapshot. The
+ * plugin's apply-world change listener is the only writer; the row component
+ * reads via props.useStore.
+ */
+import { type EngineStoreHandle } from '@hydraharness/harness-client-runtime/client';
+/** One selectable locale row (id + self-described label). */
+export interface LanguageOptionRow {
+    /** Locale id (the setLocale argument). */
+    id: string;
+    /** Display name in its own language (English). */
+    label: string;
+}
+/** Store state mirrored from the locale snapshot. */
+export interface LanguageRowState {
+    /** Active locale id. */
+    active: string;
+    /** Selectable locales in display order. */
+    options: LanguageOptionRow[];
+    /** Service revision; -1 until first sync so revision 0 lands as a change. */
+    revision: number;
+}
+/** Declared action shape giving the exported factory a stable return type. */
+type LanguageRowActions = {
+    sync: (draft: LanguageRowState, active: string, options: LanguageOptionRow[], revision: number) => void;
+};
+/**
+ * Declares the Language row state and write surface.
+ * @returns the store handle.
+ */
+export declare function createLanguageRowStore(): EngineStoreHandle<LanguageRowState, LanguageRowActions>;
+export {};
+//# sourceMappingURL=settings-store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/** Host registration for the browser locale preference. */
+import type { Context } from '@hydraharness/cordis';
+export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, type LocaleId, type LocaleSettings, } from './locale-settings.ts';
+/**
+ * Register the durable locale section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-client-locale`.
+ * @module @hydraharness/harness-client-locale/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-locale-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/locale-settings.d.ts

@@ -0,0 +1,18 @@
+/** Locale preference stored in the Host user-settings document. */
+import z from '@hydraharness/schemastery';
+/** Settings namespace owned by the locale plugin. */
+export declare const LOCALE_SETTINGS_NAMESPACE = "locale";
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+export declare const LOCALE_PREFERENCE_FIELD = "preference";
+/** Locale identifiers shipped by the browser client. */
+export declare const LOCALE_IDS: readonly ["en"];
+/** Shipped locale identifier. */
+export type LocaleId = typeof LOCALE_IDS[number];
+/** Durable locale section shared by the Host schema and the browser scope. */
+export interface LocaleSettings {
+    /** Explicit locale selection; absence delegates to the browser. */
+    preference?: LocaleId;
+}
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+export declare const LocaleSettingsSchema: z<LocaleSettings>;
+//# sourceMappingURL=locale-settings.d.ts.map

package/lib/types/locales/en.d.ts

@@ -0,0 +1,30 @@
+/** en base dictionary for the common namespace (the key-set source of truth). */
+export declare const en: {
+    ok: string;
+    cancel: string;
+    close: string;
+    copy: string;
+    copied: string;
+    retry: string;
+    loading: string;
+    'load.failed': string;
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    delete: string;
+    edit: string;
+    save: string;
+    search: string;
+    more: string;
+    collapse: string;
+    expand: string;
+    back: string;
+    unknown: string;
+    none: string;
+    truncated: string;
+};
+/** The common-namespace key union. */
+export type CommonKey = keyof typeof en;
+//# sourceMappingURL=en.d.ts.map

package/lib/types/locales/index.d.ts

@@ -0,0 +1,4 @@
+/** The common-namespace dictionary: shared cross-feature vocabulary. */
+export { en } from './en.ts';
+export type { CommonKey } from './en.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/locales/settings.d.ts

@@ -0,0 +1,8 @@
+/** `settings.locale` namespace dictionaries (the Language row's copy). */
+/** English dictionary (the key-set source of truth). */
+export declare const en: {
+    'language.title': string;
+};
+/** The settings.locale namespace key union. */
+export type SettingsLocaleKey = keyof typeof en;
+//# sourceMappingURL=settings.d.ts.map

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@hydraharness/harness-client-locale",
+  "description": "Locale plugin: Host-backed en preference, browser-derived fallback, locale snapshots, and typed namespace dictionaries",
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/client/locale"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "hydra": {
+    "plugin": {
+      "application": "Apply the saved interface language and supply translations to interface plugins."
+    },
+    "client": {
+      "inject": [
+        "@hydraharness/harness-client-connection",
+        "@hydraharness/harness-client-runtime",
+        "@hydraharness/harness-client-ui-settings",
+        "@hydraharness/harness-api-remotes"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-api-remotes": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-runtime": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-ui-settings": "^0.1.1-rc.6",
+    "@hydraharness/harness-settings": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-connection": "^0.1.1-rc.6"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-api-remotes": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-runtime": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-test-runtime": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-ui-primitives": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-ui-slots": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-ui-settings": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-client-connection": "^0.1.1-rc.6",
+    "@hydraharness/harness-settings": "^0.1.1-rc.6"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}