@magicvr/schema-ui-lib 0.1.2 → 0.1.3

package/i18n/catalog.d.ts

@@ -12,7 +12,7 @@
  * observable via the `schema-ui:missing-translation` window event (deduped
  * per locale+key, so the first occurrence always reports).
  */
-import { type Locale } from "./locale";
+import { type Locale } from "./locale.js";
 export type MessageParams = Record<string, string | number>;
 export interface MissingTranslationDetail {
     locale: Locale;

package/i18n/catalog.js

@@ -0,0 +1,96 @@
+/**
+ * Translation catalog (S1 · C2/C3).
+ *
+ * Catalogs are pure data files under `messages/`; `en-US` is the canonical
+ * baseline. Resolution order for a key in locale L:
+ *
+ *   catalog[L] → catalog[en-US] → observable missing-key event → key itself
+ *
+ * A key is "missing" only when neither the current catalog nor the en-US
+ * catalog has it; the en-US fallback is silent (designed behavior). Missing
+ * keys never render empty, never throw, and never block the flow; they are
+ * observable via the `schema-ui:missing-translation` window event (deduped
+ * per locale+key, so the first occurrence always reports).
+ */
+import enUS from "./messages/en-US.json";
+import zhCN from "./messages/zh-CN.json";
+import { DEFAULT_LOCALE } from "./locale.js";
+export const MISSING_TRANSLATION_EVENT = "schema-ui:missing-translation";
+const catalogs = {
+    "en-US": enUS,
+    "zh-CN": zhCN,
+};
+const reportedMissing = new Set();
+/** True when the key exists in the given locale catalog. */
+export function hasTranslation(key, locale) {
+    return Object.prototype.hasOwnProperty.call(catalogs[locale], key);
+}
+/** Raw catalog text for a key, or null when the locale catalog lacks it. */
+export function lookupTranslation(key, locale) {
+    if (hasTranslation(key, locale)) {
+        return catalogs[locale][key];
+    }
+    return null;
+}
+/** Replaces `{name}` placeholders with params; unknown placeholders stay. */
+export function interpolate(template, params) {
+    if (params === undefined) {
+        return template;
+    }
+    return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (match, name) => Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : match);
+}
+/** Publishes a deduped missing-key report to the window event bus. */
+export function reportMissingTranslation(detail) {
+    const dedupeKey = `${detail.locale}:${detail.key}`;
+    if (reportedMissing.has(dedupeKey)) {
+        return;
+    }
+    reportedMissing.add(dedupeKey);
+    if (typeof window !== "undefined") {
+        window.dispatchEvent(new CustomEvent(MISSING_TRANSLATION_EVENT, { detail }));
+    }
+}
+/** Resets the missing-key dedupe set (test seam). */
+export function resetMissingTranslationReports() {
+    reportedMissing.clear();
+}
+/**
+ * Resolves a message key for a locale with the frozen fallback chain.
+ * Never throws, never returns an empty string for a missing key.
+ *
+ * Fallback order: catalog[locale] → catalog[en-US] → `literalFallback`
+ * (protocol literal text, when supplied) → key itself.
+ */
+export function translate(key, params, locale = DEFAULT_LOCALE, path, literalFallback) {
+    const direct = lookupTranslation(key, locale);
+    if (direct !== null) {
+        return interpolate(direct, params);
+    }
+    const fallback = lookupTranslation(key, DEFAULT_LOCALE);
+    if (fallback !== null) {
+        return interpolate(fallback, params);
+    }
+    reportMissingTranslation({ locale, key, path });
+    return literalFallback !== undefined && literalFallback !== "" ? literalFallback : key;
+}
+/** Binds a locale (+ optional context path) to a translate function. */
+export function createTranslator(locale, options) {
+    return (key, params, literalFallback) => translate(key, params, locale, options?.path, literalFallback);
+}
+/**
+ * Resolves a schema/manifest text prop pair — the `*Key` field wins over the
+ * literal protocol text, and the literal text is the last fallback before the
+ * key itself (frozen chain: 当前语种 → en-US → 字面文本 → key).
+ */
+export function resolveTextProp(props, keyProp, literalProp, t, fallback = "") {
+    if (props === undefined) {
+        return fallback;
+    }
+    const key = props[keyProp];
+    if (typeof key === "string" && key !== "") {
+        const literal = typeof props[literalProp] === "string" ? props[literalProp] : undefined;
+        return t(key, undefined, literal);
+    }
+    const literal = props[literalProp];
+    return typeof literal === "string" ? literal : fallback;
+}

package/i18n/format.d.ts

@@ -6,7 +6,7 @@
  * Formatting is fail-safe: invalid inputs render empty, invalid timezones
  * degrade to the locale's default zone instead of throwing.
  */
-import { type Locale } from "./locale";
+import { type Locale } from "./locale.js";
 export interface FormatOptions {
     /** IANA timezone name; omitted = the environment's default zone. */
     timeZone?: string;

package/i18n/format.js

@@ -0,0 +1,35 @@
+/**
+ * Locale-aware date/number formatting (S1 · C5).
+ *
+ * Formatting follows the effective locale through Intl.* — no custom format
+ * templates (VP-007: "首版不暴露任意日期/数字格式模板，随有效 locale").
+ * Formatting is fail-safe: invalid inputs render empty, invalid timezones
+ * degrade to the locale's default zone instead of throwing.
+ */
+import { DEFAULT_LOCALE } from "./locale.js";
+/** Formats a date value in the given locale. Returns "" for invalid input. */
+export function formatDate(value, locale = DEFAULT_LOCALE, options = {}) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (!Number.isFinite(date.getTime())) {
+        return "";
+    }
+    const timeZone = options.timeZone !== undefined && options.timeZone !== "" ? options.timeZone : undefined;
+    try {
+        return new Intl.DateTimeFormat(locale, {
+            dateStyle: "medium",
+            timeStyle: "short",
+            ...(timeZone === undefined ? {} : { timeZone }),
+        }).format(date);
+    }
+    catch {
+        // Invalid IANA name — degrade to the default zone, never throw.
+        return new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short" }).format(date);
+    }
+}
+/** Formats a finite number in the given locale. Returns "" for invalid input. */
+export function formatNumber(value, locale = DEFAULT_LOCALE, options = {}) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return "";
+    }
+    return new Intl.NumberFormat(locale, options).format(value);
+}

package/i18n/locale.js

@@ -0,0 +1,79 @@
+/**
+ * Locale pure-logic unit (S1 · C1).
+ *
+ * `resolveLocale` is a side-effect-free function that computes the effective
+ * locale from the user's explicit choice, the system default, and the browser
+ * language preferences. Keeping the decision logic in a plain function lets
+ * vitest exercise every branch without a browser.
+ *
+ * Frozen priority (VP-007 / D-002 §I-L10N-002, user-confirmed 2026-08-09):
+ *
+ *   user explicit choice → system default (non-auto) → browser preference
+ *   (auto) → en-US safe fallback
+ */
+export const SUPPORTED_LOCALES = ["zh-CN", "en-US"];
+export const DEFAULT_LOCALE = "en-US";
+export function isSupportedLocale(raw) {
+    return raw === "zh-CN" || raw === "en-US";
+}
+/**
+ * Normalizes a BCP 47-ish candidate to a supported locale.
+ * Accepts exact tags, case variants, underscore separators, and language-only
+ * prefixes ("zh", "zh-cn", "zh_CN", "en-US", "en", "en-us", "en-GB" → en-US).
+ * Returns null for anything else (including "auto").
+ */
+export function normalizeLocaleCandidate(raw) {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        return null;
+    }
+    const lower = trimmed.toLowerCase().replace(/_/g, "-");
+    if (lower === "zh-cn" || lower === "zh") {
+        return "zh-CN";
+    }
+    if (lower === "en-us" || lower === "en") {
+        return "en-US";
+    }
+    if (lower.startsWith("en-")) {
+        return "en-US";
+    }
+    return null;
+}
+/**
+ * Resolves the effective locale using the frozen priority. Pure — no I/O.
+ */
+export function resolveLocale(input) {
+    const explicit = normalizeLocaleCandidate(input.stored);
+    if (explicit !== null) {
+        return explicit;
+    }
+    const system = normalizeLocaleCandidate(input.systemDefault);
+    if (system !== null) {
+        return system;
+    }
+    for (const candidate of input.browserLanguages ?? []) {
+        const normalized = normalizeLocaleCandidate(candidate);
+        if (normalized !== null) {
+            return normalized;
+        }
+    }
+    return DEFAULT_LOCALE;
+}
+/**
+ * Normalizes a raw stored value into a LocalePreference.
+ * Any value that is not a supported locale resolves to "auto".
+ */
+export function normalizePreference(raw) {
+    const normalized = normalizeLocaleCandidate(raw);
+    return normalized === null ? "auto" : normalized;
+}
+/** Real browser inputs for the boot path (provider default). */
+export function defaultBrowserLanguages() {
+    if (typeof navigator === "undefined" || typeof navigator.languages !== "object") {
+        return [];
+    }
+    return navigator.languages;
+}