@magicvr/schema-ui-lib 0.1.0

package/i18n/catalog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { type Locale } from "./locale";
+export type MessageParams = Record<string, string | number>;
+export interface MissingTranslationDetail {
+    locale: Locale;
+    key: string;
+    /** Optional rendering context (e.g. "nav.sidebar", "page.users.form"). */
+    path?: string;
+}
+export declare const MISSING_TRANSLATION_EVENT = "schema-ui:missing-translation";
+/** True when the key exists in the given locale catalog. */
+export declare function hasTranslation(key: string, locale: Locale): boolean;
+/** Raw catalog text for a key, or null when the locale catalog lacks it. */
+export declare function lookupTranslation(key: string, locale: Locale): string | null;
+/** Replaces `{name}` placeholders with params; unknown placeholders stay. */
+export declare function interpolate(template: string, params?: MessageParams): string;
+/** Publishes a deduped missing-key report to the window event bus. */
+export declare function reportMissingTranslation(detail: MissingTranslationDetail): void;
+/** Resets the missing-key dedupe set (test seam). */
+export declare function resetMissingTranslationReports(): void;
+/**
+ * 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 declare function translate(key: string, params?: MessageParams, locale?: Locale, path?: string, literalFallback?: string): string;
+/** Binds a locale (+ optional context path) to a translate function. */
+export declare function createTranslator(locale: Locale, options?: {
+    path?: string;
+}): (key: string, params?: MessageParams, literalFallback?: string) => string;
+/**
+ * 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 declare function resolveTextProp(props: Record<string, unknown> | undefined, keyProp: string, literalProp: string, t: (key: string, params?: MessageParams, literalFallback?: string) => string, fallback?: string): string;

package/i18n/format.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { type Locale } from "./locale";
+export interface FormatOptions {
+    /** IANA timezone name; omitted = the environment's default zone. */
+    timeZone?: string;
+}
+/** Formats a date value in the given locale. Returns "" for invalid input. */
+export declare function formatDate(value: Date | string | number, locale?: Locale, options?: FormatOptions): string;
+/** Formats a finite number in the given locale. Returns "" for invalid input. */
+export declare function formatNumber(value: number, locale?: Locale, options?: Intl.NumberFormatOptions): string;

package/i18n/locale.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 declare const SUPPORTED_LOCALES: readonly ["zh-CN", "en-US"];
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+/** The user-facing choice; "auto" defers to system/browser preference. */
+export type LocalePreference = Locale | "auto";
+export declare const DEFAULT_LOCALE: Locale;
+export interface LocaleResolutionInput {
+    /**
+     * localStorage["schema-ui:locale"] — the user's explicit choice.
+     * null / undefined / invalid → no explicit choice.
+     */
+    stored: string | null;
+    /**
+     * System default from the public bootstrap (/api/branding defaultLocale).
+     * "auto" or null → no system default.
+     */
+    systemDefault: string | null;
+    /** Browser language preferences in order (navigator.languages). */
+    browserLanguages: readonly string[];
+}
+export declare function isSupportedLocale(raw: string | null | undefined): raw is Locale;
+/**
+ * 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 declare function normalizeLocaleCandidate(raw: string | null | undefined): Locale | null;
+/**
+ * Resolves the effective locale using the frozen priority. Pure — no I/O.
+ */
+export declare function resolveLocale(input: LocaleResolutionInput): Locale;
+/**
+ * Normalizes a raw stored value into a LocalePreference.
+ * Any value that is not a supported locale resolves to "auto".
+ */
+export declare function normalizePreference(raw: string | null | undefined): LocalePreference;
+/** Real browser inputs for the boot path (provider default). */
+export declare function defaultBrowserLanguages(): readonly string[];

package/i18n/money.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Money / number pure-logic unit (workspace-020 · R3 · C1/C2/C3/C5).
+ *
+ * Contract GOAL-002 D-001 §3 / §4.3 (user-confirmed I-002, 2026-08-26):
+ * - Display + input semantics live on the frontend; API stays a machine
+ *   contract (amounts = int64 JSON in the smallest currency unit).
+ * - No custom format templates: symbols / positions / fraction digits are
+ *   derived from `Intl.NumberFormat` (locale + currency).
+ * - Embedded default currency map (§4.3): zh-CN → CNY, en-US → USD,
+ *   unknown locale → USD. Missing configuration never throws.
+ * - Input parsing normalizes localized strings back to machine values
+ *   (amount in minor units); unparsable input → null (callers show a
+ *   localized input error and must NOT submit the raw string).
+ */
+import { type Locale } from "./locale";
+/** Site/machine default currency (ISO 4217). */
+export declare const DEFAULT_CURRENCY = "USD";
+/** Default minor-unit exponent per currency group (ISO 4217 minor units). */
+export declare const DEFAULT_MINOR_UNITS = 2;
+/** Uppercase three-letter ISO 4217 code; null for anything else. */
+export declare function normalizeCurrencyCode(raw: string | null | undefined): string | null;
+/**
+ * Embedded default currency for a locale (§4.3). Unknown locales fall back to
+ * USD; never throws.
+ */
+export declare function defaultCurrencyFor(locale: Locale | string): string;
+/**
+ * Effective default currency: the explicit site default (branding
+ * `defaultCurrency`, ISO 4217) wins when set; otherwise the embedded
+ * per-locale map (§4.3) applies. Never throws.
+ */
+export declare function resolveEffectiveCurrency(locale: Locale, siteDefault: string | null | undefined): string;
+/** Locale group/decimal separators derived from Intl (no hardcoded tables). */
+export interface LocaleSeparators {
+    group: string;
+    decimal: string;
+}
+export declare function localeSeparators(locale: Locale): LocaleSeparators;
+export interface MoneyFormatOptions {
+    /** ISO 4217 currency code (uppercase 3 letters). Explicit override. */
+    currency?: string;
+    /** Site-wide default currency from /api/branding ("" = unset). */
+    siteDefaultCurrency?: string;
+    /** Minor-unit exponent. Defaults to 2 (CNY/USD). */
+    minorUnits?: number;
+}
+/**
+ * Formats an amount given as machine value (minor units) into a
+ * locale+currency display string. Invalid input renders "" (fail-safe).
+ * R4 F-007: values beyond Number.MAX_SAFE_INTEGER render "" — the machine
+ * contract declares int64 minor units, which JS number cannot carry.
+ */
+export declare function formatMoney(minorValue: number, locale: Locale, options?: MoneyFormatOptions): string;
+export interface MoneyParseOptions {
+    /** Expected ISO 4217 currency (affects symbol stripping only). */
+    currency?: string;
+    /** Site-wide default currency from /api/branding ("" = unset). */
+    siteDefaultCurrency?: string;
+    /** Minor-unit exponent for the returned integer. Defaults to 2. */
+    minorUnits?: number;
+}
+/**
+ * Parses a localized money string into the machine value (minor-unit
+ * integer per contract §3.3). Returns null when the input is not a
+ * parseable amount — callers must NOT submit the raw string.
+ */
+export declare function parseLocalizedMoney(raw: string, locale: Locale, options?: MoneyParseOptions): number | null;
+/** Parses a localized plain number into a machine number; null on failure. */
+export declare function parseLocalizedNumber(raw: string, locale: Locale): number | null;

package/i18n/runtime.d.ts

@@ -0,0 +1,90 @@
+/**
+ * I18n React runtime (S1 · C4/C5).
+ *
+ * - Resolves the effective locale via `resolveLocale` (frozen priority).
+ * - Persists the user's explicit choice in localStorage["schema-ui:locale"]
+ *   (single channel, same pattern as the theme mechanism; login/logout never
+ *   clears it — D-002 §I-L10N-002).
+ * - Applies `document.documentElement.lang` on locale change.
+ * - Exposes `t` / `formatDate` / `formatNumber` to components.
+ */
+import { type ReactNode } from "react";
+import { type MessageParams } from "./catalog";
+import { type Locale, type LocalePreference } from "./locale";
+import { type TimezonePreference } from "./timezone";
+export declare const LOCALE_STORAGE_KEY = "schema-ui:locale";
+export declare function readStoredLocale(): string | null;
+export declare function writeStoredLocale(preference: LocalePreference): void;
+/** Applies the effective locale to <html lang>. No-op outside a browser. */
+export declare function applyLocaleToDocument(locale: Locale): void;
+/** Returns the provider's currently effective locale (defaults en-US). */
+export declare function getActiveLocale(): Locale;
+/** Internal: keeps the registry in sync with the provider's effective locale. */
+export declare function setActiveLocale(locale: Locale): void;
+export interface I18nState {
+    /** Effective (resolved) locale — always a supported locale. */
+    locale: Locale;
+    /** User preference; "auto" defers to system/browser defaults. */
+    preference: LocalePreference;
+    /** Sets the user preference and persists it (localStorage single channel). */
+    setPreference: (preference: LocalePreference) => void;
+    /** Effective timezone (IANA name or "auto" per contract §2 / L1–L4). */
+    timezone: string;
+    /** User timezone preference; "auto" defers to session/site defaults. */
+    timezonePreference: TimezonePreference;
+    /** Sets the user timezone preference and persists it (single channel). */
+    setTimezonePreference: (preference: TimezonePreference) => void;
+    /**
+     * Site-wide default currency (ISO 4217 from /api/branding; "" = unset).
+     * Money consumers use this as the explicit currency before falling back
+     * to the embedded per-locale map (contract §4.1 / §4.3).
+     */
+    defaultCurrency: string;
+    /** Translate a catalog key with the effective locale. */
+    t: (key: string, params?: MessageParams) => string;
+    /** Locale-aware date formatting (defaults to the effective timezone). */
+    formatDate: (value: Date | string | number, options?: {
+        timeZone?: string;
+    }) => string;
+    /** Locale-aware number formatting. */
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
+}
+export interface I18nProviderProps {
+    children: ReactNode;
+    /** System default locale from the public bootstrap; null/"auto" = none. */
+    systemDefault?: string | null;
+    /** Test seam: explicit stored preference (defaults to localStorage). */
+    stored?: string | null;
+    /** Test seam: browser language list (defaults to navigator.languages). */
+    browserLanguages?: readonly string[];
+    /**
+     * Site default timezone from /api/branding (contract §2 · L3). The provider
+     * also captures it from `systemDefaultUrl` when present; this prop wins.
+     */
+    siteTimezone?: string | null;
+    /** Test seam: explicit stored timezone preference (defaults to localStorage). */
+    storedTimezone?: string | null;
+    /** Test seam: session timezone probe (defaults to detectBrowserTimezone). */
+    detectTimezone?: () => string;
+    /** Site default currency (ISO 4217); test seam for /api/branding. */
+    siteDefaultCurrency?: string | null;
+    /**
+     * When set, the provider fetches this public startup endpoint once and
+     * re-resolves the system default locale from `defaultLocale` (VP-007 S3:
+     * the shell/login apply the site-wide default when the user has no
+     * explicit choice) and the site default timezone from `siteTimezone`
+     * (workspace-020 · contract §2 · L3). Applies after the initial resolve.
+     */
+    systemDefaultUrl?: string;
+}
+export declare function I18nProvider({ children, systemDefault, stored, browserLanguages, siteTimezone, storedTimezone, detectTimezone, siteDefaultCurrency, systemDefaultUrl, }: I18nProviderProps): import("react").JSX.Element;
+export declare function useI18n(): I18nState;
+/**
+ * Tolerant translator hook for deep renderer internals.
+ *
+ * Returns the provider's translator, or a safe default (en-US resolution +
+ * missing-key observable fallback) when no provider is mounted. Production
+ * always mounts I18nProvider; bare component tests and pre-provider surfaces
+ * degrade to the documented safe fallback instead of throwing.
+ */
+export declare function useTranslate(): (key: string, params?: MessageParams) => string;

package/i18n/timezone.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Timezone pure-logic unit (workspace-020 · R2 · C1).
+ *
+ * `resolveEffectiveTimezone` computes the effective timezone from the user's
+ * explicit override, the session probe, and the site default, per contract
+ * GOAL-002 D-001 §2 (user-confirmed I-001, 2026-08-26):
+ *
+ *   L1 user override (localStorage "schema-ui:timezone") → L2 session probe
+ *   (Intl) → L3 site default (siteTimezone) → L4 "auto" fallback
+ *
+ * Keeping the decision logic in plain functions lets vitest exercise every
+ * branch; the probe is injectable so tests do not depend on the host zone.
+ */
+export declare const TIMEZONE_STORAGE_KEY = "schema-ui:timezone";
+export declare const AUTO_TIMEZONE = "auto";
+/** The user-facing choice; a timezone IANA name or "auto". */
+export type TimezonePreference = string | "auto";
+export interface TimezoneResolutionInput {
+    /**
+     * localStorage["schema-ui:timezone"] — the user's explicit override.
+     * null / undefined / invalid / "auto" → no override (skip to L2).
+     */
+    stored: string | null;
+    /**
+     * Site default from the public bootstrap (/api/branding siteTimezone).
+     * "auto" / "" / null → unset (skip to L4 when L2 is empty).
+     */
+    siteDefault: string | null;
+    /**
+     * Session probe of the host zone (injectable; real default is
+     * `detectBrowserTimezone`). Invalid or empty results are skipped.
+     */
+    detect: () => string;
+}
+/**
+ * Validates an IANA timezone name via Intl (RangeError on invalid names).
+ * Side-effect-free apart from the noexcept Intl probe; returns false for
+ * empty / non-string / unknown zones instead of throwing.
+ */
+export declare function isValidIanaTimeZone(raw: string | null | undefined): raw is string;
+/**
+ * Normalizes a raw stored/site value into a TimezonePreference.
+ * Any value that is not a valid IANA name resolves to "auto".
+ */
+export declare function normalizeTimezonePreference(raw: string | null | undefined): TimezonePreference;
+/** Reads the stored user override; best-effort (privacy mode → null). */
+export declare function readStoredTimezone(): string | null;
+/** Persists the user override; "auto" removes the key (single channel). */
+export declare function writeStoredTimezone(preference: TimezonePreference): void;
+/** Real session probe: the host zone from Intl.resolvedOptions(). */
+export declare function detectBrowserTimezone(): string;
+/**
+ * Resolves the effective timezone per contract §2 (L1 → L2 → L3 → L4).
+ * Returns an IANA name, or "auto" when nothing is configured/detectable —
+ * consumers then fall back to the locale's default zone.
+ */
+export declare function resolveEffectiveTimezone(input: TimezoneResolutionInput): string;