@texuli/core 0.7.0 → 0.8.0

package/dist/i18n/i18n.js

@@ -0,0 +1,185 @@
+/**
+ * The message runtime (ADR-016). An `I18n` holds the catalogs of the
+ * locales it has loaded, loads a locale lazily the first time it becomes
+ * active (`registerLocale(locale, () => import('./pt-BR.ts'))`), and
+ * resolves an id against the active locale, then its base language
+ * (`pt-BR` → `pt`), then the English default the component passes. It is
+ * framework-free: components read it from context (`I18N_CONTEXT`) and
+ * re-read their labels when `subscribe` reports a change.
+ */
+import { LOCALE_TAG, parseCatalog } from "./catalog.js";
+import { fillPlaceholders, formatMessage, interpolate, } from "./format.js";
+import { pseudoLocalize } from "./pseudo.js";
+/** The context key components read an `I18n` from (`setContext(I18N_CONTEXT, i18n)`); one per realm. */
+export const I18N_CONTEXT = Symbol.for('texuli.i18n');
+/** The pseudo-locale (`en-XA`): every resolved string is accented and bracketed, so unlocalized text stands out. */
+export const PSEUDO_LOCALE = 'en-XA';
+/** The base language of a tag: `pt-BR` → `pt`; `undefined` for a bare language. */
+function baseLanguage(locale) {
+    const dash = locale.indexOf('-');
+    return dash > 0 ? locale.slice(0, dash) : undefined;
+}
+function normalizeLocale(locale) {
+    return LOCALE_TAG.test(locale) ? locale : 'en';
+}
+/** Create a message runtime. Never throws on bad catalogs; bad messages are dropped with issues. */
+export function createI18n(options = {}) {
+    const catalogs = new Map();
+    const loaders = new Map(Object.entries(options.loaders ?? {}));
+    const loading = new Map();
+    const listeners = new Set();
+    let locale = normalizeLocale(options.locale ?? 'en');
+    let version = 0;
+    let request = 0;
+    const notify = () => {
+        version += 1;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const add = (input, silent) => {
+        const parsed = parseCatalog(input);
+        if (!parsed.catalog)
+            return parsed.issues;
+        const target = catalogs.get(parsed.catalog.locale) ?? Object.create(null);
+        Object.assign(target, parsed.catalog.messages);
+        catalogs.set(parsed.catalog.locale, target);
+        if (!silent)
+            notify();
+        return parsed.issues;
+    };
+    for (const catalog of options.catalogs ?? []) {
+        const issues = add(catalog, true);
+        if (issues.length > 0)
+            options.onIssues?.(catalog.locale ?? '', issues);
+    }
+    const lookup = (id) => {
+        const own = catalogs.get(locale);
+        if (own && Object.hasOwn(own, id))
+            return own[id];
+        const base = baseLanguage(locale);
+        const parent = base ? catalogs.get(base) : undefined;
+        return parent && Object.hasOwn(parent, id) ? parent[id] : undefined;
+    };
+    const load = (tag) => {
+        if (catalogs.has(tag) || tag === PSEUDO_LOCALE)
+            return Promise.resolve(true);
+        const pending = loading.get(tag);
+        if (pending)
+            return pending;
+        const loader = loaders.get(tag);
+        if (!loader)
+            return Promise.resolve(false);
+        const promise = Promise.resolve()
+            .then(loader)
+            .then((module) => {
+            const catalog = module && typeof module === 'object' && 'default' in module ? module.default : module;
+            const issues = add(catalog && typeof catalog === 'object' ? { ...catalog, locale: tag } : catalog, true);
+            if (issues.length > 0)
+                options.onIssues?.(tag, issues);
+            return catalogs.has(tag);
+        })
+            .catch((error) => {
+            options.onIssues?.(tag, [
+                { id: '', message: error instanceof Error ? error.message : 'the locale failed to load' },
+            ]);
+            return false;
+        })
+            .finally(() => loading.delete(tag));
+        loading.set(tag, promise);
+        return promise;
+    };
+    const i18n = {
+        get locale() {
+            return locale;
+        },
+        get version() {
+            return version;
+        },
+        t(id, english, values) {
+            const found = lookup(id);
+            const text = formatMessage(found ?? english, values, locale);
+            return locale === PSEUDO_LOCALE ? pseudoLocalize(text) : text;
+        },
+        has(id) {
+            return lookup(id) !== undefined;
+        },
+        async setLocale(next) {
+            if (!LOCALE_TAG.test(next))
+                return false;
+            const ticket = ++request;
+            const base = baseLanguage(next);
+            const [own, parent] = await Promise.all([load(next), base ? load(base) : false]);
+            // A later call wins. A locale with neither its own nor a base catalog
+            // activates only when it is English (the defaults are English).
+            if (ticket !== request)
+                return false;
+            if (!own && !parent && next !== 'en' && base !== 'en')
+                return false;
+            if (locale !== next) {
+                locale = next;
+                notify();
+            }
+            return true;
+        },
+        registerLocale(tag, loader) {
+            if (!LOCALE_TAG.test(tag) || typeof loader !== 'function')
+                return;
+            loaders.set(tag, loader);
+        },
+        addCatalog(catalog) {
+            return add(catalog, false);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    // A loader registered for the starting locale loads right away.
+    if (!catalogs.has(locale) && loaders.has(locale)) {
+        void load(locale).then((ok) => {
+            if (ok)
+                notify();
+        });
+    }
+    return i18n;
+}
+/**
+ * The resolution order for one label (ADR-016): the instance prop when the
+ * caller set one, then the catalog from context, then the English default.
+ */
+export function resolveLabel(instance, i18n, id, english, values) {
+    if (typeof instance === 'string')
+        return values ? interpolate(instance, values) : instance;
+    if (i18n)
+        return i18n.t(id, english, values);
+    return formatMessage(english, values);
+}
+/** The English-only `Translate`: what components use with no `I18n` in context. */
+export const englishMessages = (_id, english, values) => fillPlaceholders(typeof english === 'string' ? english : english.other, values);
+/** `pageLabel` → `page-label`: the id segment of a label key. */
+function kebab(key) {
+    return key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+}
+/**
+ * Resolve a component's English label object through the catalog: every
+ * string label becomes `messages(`${prefix}.${kebab(key)}`, english)`. A
+ * function label (`remove: (tag) => …`) stays as is unless the catalog has
+ * its id, whose message then receives the arguments as `{0}`, `{1}`…
+ * Callers spread their instance overrides on top (the instance prop wins).
+ */
+export function localizeLabels(messages, prefix, defaults) {
+    const out = {};
+    for (const [key, value] of Object.entries(defaults)) {
+        const id = `${prefix}.${kebab(key)}`;
+        if (typeof value === 'string')
+            out[key] = messages(id, value);
+        else if (typeof value === 'function' && messages.has?.(id)) {
+            out[key] = (...args) => messages(id, '', Object.fromEntries(args.map((arg, index) => [String(index), arg])));
+        }
+        else
+            out[key] = value;
+    }
+    return out;
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @texuli/core/i18n: message catalogs, lazy locales and label resolution
+ * (ADR-016). Framework-free; components read an `I18n` from context.
+ */
+export { CATALOG_LIMITS, type CatalogIssue, type CatalogParse, checkMessage, LOCALE_TAG, MESSAGE_ID, type MessageCatalog, type MessageCheck, parseCatalog, } from './catalog.js';
+export { fillPlaceholders, formatMessage, interpolate, type Message, type MessageValues, type PluralMessage, type SelectMessage, } from './format.js';
+export { createI18n, englishMessages, I18N_CONTEXT, type I18n, type I18nOptions, type LocaleLoader, localizeLabels, type MessageLookup, PSEUDO_LOCALE, resolveLabel, type Translate, } from './i18n.js';
+export { isPseudoLocalized, pseudoLocalize } from './pseudo.js';

package/dist/i18n/index.js

@@ -0,0 +1,8 @@
+/**
+ * @texuli/core/i18n: message catalogs, lazy locales and label resolution
+ * (ADR-016). Framework-free; components read an `I18n` from context.
+ */
+export { CATALOG_LIMITS, checkMessage, LOCALE_TAG, MESSAGE_ID, parseCatalog, } from "./catalog.js";
+export { fillPlaceholders, formatMessage, interpolate, } from "./format.js";
+export { createI18n, englishMessages, I18N_CONTEXT, localizeLabels, PSEUDO_LOCALE, resolveLabel, } from "./i18n.js";
+export { isPseudoLocalized, pseudoLocalize } from "./pseudo.js";

package/dist/i18n/pseudo.d.ts

@@ -0,0 +1,4 @@
+/** The pseudo form of `text`: `⟦Çlóśé⟧`-style, linear in the length of the text. */
+export declare function pseudoLocalize(text: string): string;
+/** Whether `text` is pseudo-localized (starts with `⟦` and ends with `⟧`). */
+export declare function isPseudoLocalized(text: string): boolean;

package/dist/i18n/pseudo.js

@@ -0,0 +1,41 @@
+/**
+ * Pseudo-localization for coverage (ADR-016): accented, bracketed and
+ * slightly longer text, so a label that skipped the catalog (still plain
+ * English) or a layout that clips longer translations stands out. `{name}`
+ * placeholders are kept as is.
+ */
+const ACCENTS = {
+    a: 'á',
+    c: 'ç',
+    e: 'é',
+    i: 'í',
+    n: 'ñ',
+    o: 'ó',
+    u: 'ú',
+    y: 'ý',
+    A: 'Á',
+    C: 'Ç',
+    E: 'É',
+    I: 'Í',
+    N: 'Ñ',
+    O: 'Ó',
+    U: 'Ú',
+    Y: 'Ý',
+};
+/** The pseudo form of `text`: `⟦Çlóśé⟧`-style, linear in the length of the text. */
+export function pseudoLocalize(text) {
+    let out = '';
+    let inPlaceholder = false;
+    for (const char of text) {
+        if (char === '{')
+            inPlaceholder = true;
+        else if (char === '}')
+            inPlaceholder = false;
+        out += inPlaceholder ? char : (ACCENTS[char] ?? char);
+    }
+    return `⟦${out}⟧`;
+}
+/** Whether `text` is pseudo-localized (starts with `⟦` and ends with `⟧`). */
+export function isPseudoLocalized(text) {
+    return text.startsWith('⟦') && text.endsWith('⟧');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texuli/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Texels: framework-free behavior and policy that every Texuli component is built from.",
   "keywords": [
     "svelte",
@@ -26,6 +26,7 @@
     ".": "./dist/index.js",
     "./announcer": "./dist/announcer/index.js",
     "./controllable": "./dist/controllable/controllable-state.js",
+    "./data-source": "./dist/data-source/index.js",
     "./dir-locale": "./dist/dir-locale/dir-locale.js",
     "./dismiss": "./dist/dismiss/index.js",
     "./editor-history": "./dist/editor/history.js",
@@ -34,8 +35,10 @@
     "./editor-model": "./dist/editor/model.js",
     "./editor-transforms": "./dist/editor/edit.js",
     "./env": "./dist/env/index.js",
+    "./expression": "./dist/expression/index.js",
     "./focus-scope": "./dist/focus-scope/index.js",
     "./form-bridge": "./dist/form-bridge/form-bridge.js",
+    "./i18n": "./dist/i18n/index.js",
     "./ids": "./dist/ids/ids.js",
     "./inert": "./dist/inert/index.js",
     "./keyboard": "./dist/keyboard/index.js",