@frame-kit/utils 0.2.9 → 0.2.10

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.2.9 (2026-09-13)
+
+This was a version bump only for utils to align it with other projects, there were no code changes.
+
 ## 0.2.8 (2026-09-13)
 
 This was a version bump only for utils to align it with other projects, there were no code changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frame-kit/utils",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Framework-agnostic color and date utilities for FrameKit.",
   "license": "MIT",
   "repository": {

package/src/index.d.ts

@@ -2,3 +2,6 @@ export * from './lib/color/color.js';
 export * from './lib/color/color.types.js';
 export * from './lib/date/date.js';
 export * from './lib/date/date.types.js';
+export * from './lib/i18n/i18n.js';
+export * from './lib/i18n/i18n.locale.js';
+export * from './lib/i18n/i18n.types.js';

package/src/index.js

@@ -2,4 +2,7 @@ export * from './lib/color/color.js';
 export * from './lib/color/color.types.js';
 export * from './lib/date/date.js';
 export * from './lib/date/date.types.js';
+export * from './lib/i18n/i18n.js';
+export * from './lib/i18n/i18n.locale.js';
+export * from './lib/i18n/i18n.types.js';
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/utils/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/utils/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC"}

package/src/lib/i18n/i18n.d.ts

@@ -0,0 +1,55 @@
+import type { LocaleMap, MessageKey, Messages } from './i18n.types.js';
+/**
+ * Dot-path message lookup with `{{var}}` interpolation, a minimal ICU plural
+ * subset, and deep merge across several sources.
+ *
+ * Deliberately free of any framework or DOM dependency, so the same instance
+ * works in a browser app, in server-side rendering, and in a backend that
+ * renders emails or hosted pages — the three places a product's copy has to
+ * agree. The Angular wrapper that adds signal reactivity and browser locale
+ * detection lives in `@frame-kit/ui-ng/services/i18n`.
+ */
+export declare class I18nService {
+    protected localeValue: string;
+    protected messages: Messages;
+    protected readonly localeMaps: LocaleMap[];
+    protected readonly staticSources: Messages[];
+    protected readonly supportedLocaleList: string[];
+    constructor(config: {
+        locale?: string;
+        supportedLocales?: string[];
+        localeMaps?: LocaleMap[];
+        sources?: Messages[];
+    });
+    getLocale(): string;
+    getSupportedLocales(): string[];
+    /**
+     * A message by dot-path, with optional interpolation.
+     *
+     * Returns the key itself when nothing is found. That is deliberate: a missing
+     * message renders as `auth.signIn.title` rather than as an empty space, so it
+     * is visible in review instead of silently disappearing.
+     */
+    get(key: MessageKey, vars?: Record<string, string | number>): string;
+    /**
+     * A non-string value by dot-path — a list of steps, a table of rows.
+     *
+     * With `vars`, every string reachable inside is interpolated and the shape is
+     * preserved. Content of this kind mixes strings, arrays and objects, and a
+     * placeholder left in any one of them renders literally, so substitution has
+     * to follow the data rather than assume a shape.
+     */
+    getRaw<T = unknown>(path: string, vars?: Record<string, string | number>): T | undefined;
+    /** No-ops on an unsupported locale rather than rendering keys. */
+    setLocale(locale: string): void;
+    /**
+     * Add a locale map after construction — for a lazily loaded feature that
+     * ships its own copy and should not be paid for at boot.
+     */
+    registerLocaleMap(map: LocaleMap): void;
+    /** Overridden by the reactive subclass to read from a signal. */
+    protected currentMessages(): Messages;
+    /** Fires after messages are rebuilt; the reactive subclass syncs signals. */
+    protected onLocaleChanged(): void;
+    private buildMessages;
+}

package/src/lib/i18n/i18n.js

@@ -0,0 +1,175 @@
+/**
+ * Dot-path message lookup with `{{var}}` interpolation, a minimal ICU plural
+ * subset, and deep merge across several sources.
+ *
+ * Deliberately free of any framework or DOM dependency, so the same instance
+ * works in a browser app, in server-side rendering, and in a backend that
+ * renders emails or hosted pages — the three places a product's copy has to
+ * agree. The Angular wrapper that adds signal reactivity and browser locale
+ * detection lives in `@frame-kit/ui-ng/services/i18n`.
+ */
+export class I18nService {
+    constructor(config) {
+        var _a, _b, _c, _d, _e;
+        this.supportedLocaleList = (_a = config.supportedLocales) !== null && _a !== void 0 ? _a : ['en'];
+        this.localeMaps = (_b = config.localeMaps) !== null && _b !== void 0 ? _b : [];
+        this.staticSources = (_c = config.sources) !== null && _c !== void 0 ? _c : [];
+        // No detection here: the caller passes an explicit locale. A browser app
+        // resolves it from storage or `navigator`, a backend from `Accept-Language`
+        // — neither of which this base should know about.
+        this.localeValue = (_e = (_d = config.locale) !== null && _d !== void 0 ? _d : this.supportedLocaleList[0]) !== null && _e !== void 0 ? _e : 'en';
+        this.messages = this.buildMessages(this.localeValue);
+    }
+    getLocale() {
+        return this.localeValue;
+    }
+    getSupportedLocales() {
+        return [...this.supportedLocaleList];
+    }
+    /**
+     * A message by dot-path, with optional interpolation.
+     *
+     * Returns the key itself when nothing is found. That is deliberate: a missing
+     * message renders as `auth.signIn.title` rather than as an empty space, so it
+     * is visible in review instead of silently disappearing.
+     */
+    get(key, vars) {
+        const value = getByPath(this.currentMessages(), key);
+        if (value === undefined) {
+            return key;
+        }
+        const str = String(value);
+        if (!vars || Object.keys(vars).length === 0) {
+            return str;
+        }
+        return interpolate(str, vars);
+    }
+    /**
+     * A non-string value by dot-path — a list of steps, a table of rows.
+     *
+     * With `vars`, every string reachable inside is interpolated and the shape is
+     * preserved. Content of this kind mixes strings, arrays and objects, and a
+     * placeholder left in any one of them renders literally, so substitution has
+     * to follow the data rather than assume a shape.
+     */
+    getRaw(path, vars) {
+        const value = getByPath(this.currentMessages(), path);
+        if (value === undefined || !vars || Object.keys(vars).length === 0) {
+            return value;
+        }
+        return interpolateDeep(value, vars);
+    }
+    /** No-ops on an unsupported locale rather than rendering keys. */
+    setLocale(locale) {
+        if (!this.supportedLocaleList.includes(locale)) {
+            return;
+        }
+        this.localeValue = locale;
+        this.messages = this.buildMessages(locale);
+        this.onLocaleChanged();
+    }
+    /**
+     * Add a locale map after construction — for a lazily loaded feature that
+     * ships its own copy and should not be paid for at boot.
+     */
+    registerLocaleMap(map) {
+        this.localeMaps.push(map);
+        this.messages = this.buildMessages(this.localeValue);
+        this.onLocaleChanged();
+    }
+    /** Overridden by the reactive subclass to read from a signal. */
+    currentMessages() {
+        return this.messages;
+    }
+    /** Fires after messages are rebuilt; the reactive subclass syncs signals. */
+    onLocaleChanged() {
+        // no-op in the framework-agnostic base
+    }
+    buildMessages(locale) {
+        const sources = [];
+        for (const map of this.localeMaps) {
+            if (map[locale]) {
+                sources.push(map[locale]);
+            }
+        }
+        for (const source of this.staticSources) {
+            sources.push(source);
+        }
+        return mergeMessages(...sources);
+    }
+}
+// ── internals ────────────────────────────────────────────────────────────
+function getByPath(obj, path) {
+    let current = obj;
+    for (const key of path.split('.')) {
+        if (current === null ||
+            current === undefined ||
+            typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+function interpolateDeep(value, vars) {
+    if (typeof value === 'string') {
+        return interpolate(value, vars);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => interpolateDeep(entry, vars));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            interpolateDeep(entry, vars),
+        ]));
+    }
+    return value;
+}
+function interpolate(str, vars) {
+    // An unknown placeholder is left as written rather than blanked: `{{name}}`
+    // on the page says which variable was not passed.
+    return applyPlurals(str, vars).replace(/\{\{(\w+)}}/g, (match, key) => (key in vars ? String(vars[key]) : match));
+}
+/**
+ * A minimal ICU plural subset: `{count, plural, =0 {none} other {# items}}`.
+ *
+ * Exact selectors plus `other`, with no nested braces in branch bodies. Enough
+ * for the counts copy actually contains, without pulling in a full ICU parser.
+ */
+function applyPlurals(str, vars) {
+    const PLURAL = /\{(\w+),\s*plural,\s*((?:[^{}]+|\{[^{}]*\})*)\}/g;
+    return str.replace(PLURAL, (match, name, cases) => {
+        if (!(name in vars)) {
+            return match;
+        }
+        const count = Number(vars[name]);
+        const exact = new RegExp(`=${count}\\s*\\{([^{}]*)\\}`).exec(cases);
+        if (exact) {
+            return exact[1].replace(/#/g, String(count));
+        }
+        const other = /other\s*\{([^{}]*)\}/.exec(cases);
+        return other ? other[1].replace(/#/g, String(count)) : match;
+    });
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function deepMerge(target, source) {
+    const result = Object.assign({}, target);
+    for (const key of Object.keys(source)) {
+        result[key] =
+            isObject(result[key]) && isObject(source[key])
+                ? deepMerge(result[key], source[key])
+                : source[key];
+    }
+    return result;
+}
+function mergeMessages(...sources) {
+    let merged = {};
+    for (const source of sources) {
+        merged = deepMerge(merged, source);
+    }
+    return merged;
+}
+//# sourceMappingURL=i18n.js.map

package/src/lib/i18n/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../../../../../../packages/utils/src/lib/i18n/i18n.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAW;IAOtB,YAAY,MAKX;;QACC,IAAI,CAAC,mBAAmB,GAAG,MAAA,MAAM,CAAC,gBAAgB,mCAAI,CAAC,IAAI,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,GAAG,MAAA,MAAM,CAAC,UAAU,mCAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,aAAa,GAAG,MAAA,MAAM,CAAC,OAAO,mCAAI,EAAE,CAAC;QAE1C,yEAAyE;QACzE,4EAA4E;QAC5E,kDAAkD;QAClD,IAAI,CAAC,WAAW,GAAG,MAAA,MAAA,MAAM,CAAC,MAAM,mCAAI,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,mCAAI,IAAI,CAAC;QACxE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACvD,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,mBAAmB;QACjB,OAAO,CAAC,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,GAAe,EAAE,IAAsC;QACzD,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,GAAa,CAAC,CAAC;QAE/D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,GAAa,CAAC;QACvB,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAE1B,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5C,OAAO,GAAG,CAAC;QACb,CAAC;QAED,OAAO,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CACJ,IAAY,EACZ,IAAsC;QAEtC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,IAAI,CAAC,CAAC;QAEtD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnE,OAAO,KAAsB,CAAC;QAChC,CAAC;QAED,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,CAAM,CAAC;IAC3C,CAAC;IAED,kEAAkE;IAClE,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/C,OAAO;QACT,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,GAAc;QAC9B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrD,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAED,iEAAiE;IACvD,eAAe;QACvB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,6EAA6E;IACnE,eAAe;QACvB,uCAAuC;IACzC,CAAC;IAEO,aAAa,CAAC,MAAc;QAClC,MAAM,OAAO,GAAe,EAAE,CAAC;QAE/B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAClC,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAChB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAED,OAAO,aAAa,CAAC,GAAG,OAAO,CAAC,CAAC;IACnC,CAAC;CACF;AAED,4EAA4E;AAE5E,SAAS,SAAS,CAAC,GAAa,EAAE,IAAY;IAC5C,IAAI,OAAO,GAAY,GAAG,CAAC;IAE3B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,IACE,OAAO,KAAK,IAAI;YAChB,OAAO,KAAK,SAAS;YACrB,OAAO,OAAO,KAAK,QAAQ,EAC3B,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,GAAI,OAAoB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,eAAe,CACtB,KAAc,EACd,IAAqC;IAErC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;YAC1C,GAAG;YACH,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC;SAC7B,CAAC,CACH,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAClB,GAAW,EACX,IAAqC;IAErC,4EAA4E;IAC5E,kDAAkD;IAClD,OAAO,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,OAAO,CACpC,cAAc,EACd,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAClE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CACnB,GAAW,EACX,IAAqC;IAErC,MAAM,MAAM,GAAG,kDAAkD,CAAC;IAElE,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,KAAa,EAAE,EAAE;QAChE,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACpB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEpE,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/C,CAAC;QAED,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEjD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,SAAS,CAAC,MAAgB,EAAE,MAAgB;IACnD,MAAM,MAAM,qBAAkB,MAAM,CAAE,CAAC;IAEvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC;YACT,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC5C,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAa,EAAE,MAAM,CAAC,GAAG,CAAa,CAAC;gBAC7D,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,GAAG,OAAmB;IAC3C,IAAI,MAAM,GAAa,EAAE,CAAC;IAE1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/src/lib/i18n/i18n.locale.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Locale detection and persistence.
+ *
+ * Browser concerns, but no framework: the same functions serve an Angular SPA
+ * and any other client. Every access is guarded, so importing this on a server
+ * (SSR, Node) is safe — detection simply falls through to the default.
+ */
+/** How to resolve the locale a visitor should see. */
+export interface LocaleDetectionOptions {
+    /** Locale codes the app ships messages for, e.g. `['en', 'es']`. */
+    supportedLocales: string[];
+    /**
+     * `localStorage` key holding the visitor's chosen locale. Omit to skip
+     * persistence entirely — detection then reads the browser language only.
+     *
+     * Name it per product (`'acme-locale'`); two apps on one origin sharing a
+     * key would overwrite each other's preference.
+     */
+    storageKey?: string;
+    /** Used when nothing else matches. Defaults to the first supported locale. */
+    defaultLocale?: string;
+}
+/** Reduce a locale tag to its language subtag: `en-US` → `en`. */
+export declare function normalizeLocale(locale: string): string;
+/** The persisted locale, or `null` when there is none or storage is unavailable. */
+export declare function readStoredLocale(storageKey: string): string | null;
+/** Persist the visitor's locale. Silently no-ops when storage is unavailable. */
+export declare function saveLocale(storageKey: string, locale: string): void;
+/**
+ * Resolve the active locale: stored preference, then browser language, then
+ * the default. Each candidate is normalized and must be in `supportedLocales`
+ * to win, so an unsupported language falls through rather than rendering keys.
+ */
+export declare function detectLocale(options: LocaleDetectionOptions): string;

package/src/lib/i18n/i18n.locale.js

@@ -0,0 +1,62 @@
+/**
+ * Locale detection and persistence.
+ *
+ * Browser concerns, but no framework: the same functions serve an Angular SPA
+ * and any other client. Every access is guarded, so importing this on a server
+ * (SSR, Node) is safe — detection simply falls through to the default.
+ */
+/** Reduce a locale tag to its language subtag: `en-US` → `en`. */
+export function normalizeLocale(locale) {
+    return locale.split('-')[0].toLowerCase();
+}
+/** The persisted locale, or `null` when there is none or storage is unavailable. */
+export function readStoredLocale(storageKey) {
+    if (typeof localStorage === 'undefined') {
+        return null;
+    }
+    try {
+        return localStorage.getItem(storageKey);
+    }
+    catch (_a) {
+        // Private-mode and blocked-cookie browsers throw on access rather than
+        // returning null. A remembered locale is a convenience, never a hard
+        // requirement, so failing to read one is not an error.
+        return null;
+    }
+}
+/** Persist the visitor's locale. Silently no-ops when storage is unavailable. */
+export function saveLocale(storageKey, locale) {
+    if (typeof localStorage === 'undefined') {
+        return;
+    }
+    try {
+        localStorage.setItem(storageKey, locale);
+    }
+    catch (_a) {
+        // See readStoredLocale: storage is best-effort.
+    }
+}
+/**
+ * Resolve the active locale: stored preference, then browser language, then
+ * the default. Each candidate is normalized and must be in `supportedLocales`
+ * to win, so an unsupported language falls through rather than rendering keys.
+ */
+export function detectLocale(options) {
+    var _a, _b;
+    const { supportedLocales, storageKey } = options;
+    const fallback = (_b = (_a = options.defaultLocale) !== null && _a !== void 0 ? _a : supportedLocales[0]) !== null && _b !== void 0 ? _b : 'en';
+    if (storageKey) {
+        const stored = readStoredLocale(storageKey);
+        if (stored && supportedLocales.includes(normalizeLocale(stored))) {
+            return normalizeLocale(stored);
+        }
+    }
+    if (typeof navigator !== 'undefined' && navigator.language) {
+        const fromBrowser = normalizeLocale(navigator.language);
+        if (supportedLocales.includes(fromBrowser)) {
+            return fromBrowser;
+        }
+    }
+    return fallback;
+}
+//# sourceMappingURL=i18n.locale.js.map

package/src/lib/i18n/i18n.locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.locale.js","sourceRoot":"","sources":["../../../../../../packages/utils/src/lib/i18n/i18n.locale.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC5C,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IAAC,WAAM,CAAC;QACP,uEAAuE;QACvE,qEAAqE;QACrE,uDAAuD;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,MAAc;IAC3D,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;QACxC,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAAC,WAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAA+B;;IAC1D,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACjD,MAAM,QAAQ,GAAG,MAAA,MAAA,OAAO,CAAC,aAAa,mCAAI,gBAAgB,CAAC,CAAC,CAAC,mCAAI,IAAI,CAAC;IAEtE,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAE5C,IAAI,MAAM,IAAI,gBAAgB,CAAC,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YACjE,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC3D,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAExD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3C,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/src/lib/i18n/i18n.types.d.ts

@@ -0,0 +1,17 @@
+/** Message bundles are plain nested objects, usually loaded from JSON. */
+export type Messages = Record<string, unknown>;
+/** One message bundle per locale code. */
+export type LocaleMap = Record<string, Messages>;
+export type SupportedLocale = string;
+/**
+ * Every dot-path reachable in a message bundle.
+ *
+ * Pass a bundle's type as `T` and key lookups are checked against it, so a
+ * renamed or deleted message is a compile error rather than a key rendered
+ * literally on the page.
+ */
+export type Paths<T> = T extends object ? {
+    [K in keyof T]: K extends string ? T[K] extends object ? `${K}.${Paths<T[K]>}` : K : never;
+}[keyof T] : never;
+/** A dot-path key. Falls back to `string` when no bundle type is supplied. */
+export type MessageKey<T = Record<string, unknown>> = Paths<T> | string;

package/src/lib/i18n/i18n.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=i18n.types.js.map

package/src/lib/i18n/i18n.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.types.js","sourceRoot":"","sources":["../../../../../../packages/utils/src/lib/i18n/i18n.types.ts"],"names":[],"mappings":""}