convex-cms 0.0.1

package/dist/component/localeFallbackChain.d.ts

@@ -0,0 +1,410 @@
+/**
+ * Locale Fallback Chain Configuration and Utilities
+ *
+ * This module provides configuration and utility functions for locale fallback chains.
+ * When content isn't available in a requested locale, the system falls back through
+ * a configured chain until content is found.
+ *
+ * @example
+ * ```typescript
+ * // Configure fallback chains
+ * const config: LocaleFallbackConfig = {
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES", "en-US"],  // Mexican Spanish -> Spain Spanish -> US English
+ *     "es-ES": ["en-US"],            // Spain Spanish -> US English
+ *     "fr-CA": ["fr-FR", "en-US"],   // Canadian French -> France French -> US English
+ *     "zh-Hans-CN": ["zh-Hans", "en-US"], // Simplified Chinese (China) -> Simplified Chinese -> US English
+ *   },
+ * };
+ *
+ * // Resolve fallback chain for a locale
+ * const chain = resolveFallbackChain("es-MX", config);
+ * // Returns: ["es-ES", "en-US", "en-US"] -> deduplicated to ["es-ES", "en-US"]
+ * ```
+ *
+ * @module localeFallbackChain
+ */
+import type { LocaleResolutionOptions } from "./localeFields.js";
+/**
+ * BCP 47 locale code (e.g., "en-US", "zh-Hans", "zh-Hans-CN").
+ */
+export type LocaleCode = string;
+/**
+ * Configuration for locale fallback behavior.
+ *
+ * Defines how the system should resolve content when the requested locale
+ * is not available. Fallback chains are tried in order until content is found.
+ */
+export interface LocaleFallbackConfig {
+    /**
+     * The default locale used as the final fallback when all other options are exhausted.
+     * This should be the locale with the most complete content.
+     *
+     * @default "en"
+     */
+    defaultLocale: LocaleCode;
+    /**
+     * Mapping of locale codes to their fallback chains.
+     * Each locale can have an ordered array of fallback locales to try.
+     *
+     * @example
+     * ```typescript
+     * fallbackChains: {
+     *   "es-MX": ["es-ES", "en-US"],  // Try Spain Spanish, then US English
+     *   "es-AR": ["es-ES", "en-US"],  // Argentine Spanish also falls back to Spain Spanish
+     *   "pt-BR": ["pt-PT", "en-US"],  // Brazilian Portuguese -> Portugal Portuguese
+     * }
+     * ```
+     */
+    fallbackChains?: Record<LocaleCode, LocaleCode[]>;
+    /**
+     * Whether to automatically generate fallback chains based on locale hierarchy.
+     *
+     * When enabled, the system will automatically create fallback chains based on
+     * the BCP 47 locale structure:
+     * - "zh-Hans-CN" -> ["zh-Hans", "zh", defaultLocale]
+     * - "en-US" -> ["en", defaultLocale]
+     *
+     * Explicit fallbackChains take precedence over auto-generated ones.
+     *
+     * @default true
+     */
+    autoGenerateFallbacks?: boolean;
+    /**
+     * List of supported locales. If provided, fallback chains will only include
+     * locales from this list.
+     *
+     * @example
+     * ```typescript
+     * supportedLocales: ["en-US", "es-ES", "fr-FR", "de-DE"]
+     * ```
+     */
+    supportedLocales?: LocaleCode[];
+}
+/**
+ * Result of resolving a fallback chain for a locale.
+ */
+export interface ResolvedFallbackChain {
+    /**
+     * The original locale that was requested.
+     */
+    requestedLocale: LocaleCode;
+    /**
+     * The complete fallback chain in priority order.
+     * Does not include the requested locale itself.
+     */
+    fallbackChain: LocaleCode[];
+    /**
+     * The default locale (final fallback).
+     */
+    defaultLocale: LocaleCode;
+    /**
+     * Whether the chain was auto-generated or explicitly configured.
+     */
+    isAutoGenerated: boolean;
+}
+/**
+ * Options for building a fallback chain.
+ */
+export interface BuildFallbackChainOptions {
+    /**
+     * Whether to include the default locale in the chain.
+     * @default true
+     */
+    includeDefault?: boolean;
+    /**
+     * Whether to deduplicate the chain (remove duplicate locales).
+     * @default true
+     */
+    deduplicate?: boolean;
+    /**
+     * Maximum length of the fallback chain.
+     * @default 10
+     */
+    maxLength?: number;
+}
+/**
+ * Default fallback configuration.
+ */
+export declare const DEFAULT_FALLBACK_CONFIG: Required<LocaleFallbackConfig>;
+/**
+ * Parsed components of a BCP 47 locale code.
+ */
+export interface ParsedLocale {
+    /**
+     * The language code (2-3 lowercase letters).
+     * @example "en", "zh", "pt"
+     */
+    language: string;
+    /**
+     * The script code (4 letters, title case), if present.
+     * @example "Hans", "Hant", "Latn"
+     */
+    script?: string;
+    /**
+     * The region code (2 uppercase letters), if present.
+     * @example "US", "CN", "BR"
+     */
+    region?: string;
+}
+/**
+ * Parses a BCP 47 locale code into its components.
+ *
+ * Supports the following formats:
+ * - "en" (language only)
+ * - "en-US" (language + region)
+ * - "zh-Hans" (language + script)
+ * - "zh-Hans-CN" (language + script + region)
+ *
+ * @param locale - The locale code to parse
+ * @returns The parsed locale components, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseLocale("en-US");
+ * // Returns: { language: "en", region: "US" }
+ *
+ * parseLocale("zh-Hans-CN");
+ * // Returns: { language: "zh", script: "Hans", region: "CN" }
+ *
+ * parseLocale("invalid");
+ * // Returns: null
+ * ```
+ */
+export declare function parseLocale(locale: LocaleCode): ParsedLocale | null;
+/**
+ * Formats parsed locale components back into a BCP 47 locale code.
+ *
+ * @param parsed - The parsed locale components
+ * @returns The formatted locale code
+ *
+ * @example
+ * ```typescript
+ * formatLocale({ language: "en", region: "US" });
+ * // Returns: "en-US"
+ *
+ * formatLocale({ language: "zh", script: "Hans", region: "CN" });
+ * // Returns: "zh-Hans-CN"
+ * ```
+ */
+export declare function formatLocale(parsed: ParsedLocale): LocaleCode;
+/**
+ * Generates the locale hierarchy (parent locales) for a given locale.
+ *
+ * @param locale - The locale to get hierarchy for
+ * @returns Array of parent locales from most specific to least specific
+ *
+ * @example
+ * ```typescript
+ * getLocaleHierarchy("zh-Hans-CN");
+ * // Returns: ["zh-Hans", "zh"]
+ *
+ * getLocaleHierarchy("en-US");
+ * // Returns: ["en"]
+ *
+ * getLocaleHierarchy("en");
+ * // Returns: []
+ * ```
+ */
+export declare function getLocaleHierarchy(locale: LocaleCode): LocaleCode[];
+/**
+ * Resolves the complete fallback chain for a locale.
+ *
+ * The resolution order is:
+ * 1. Explicit fallback chain from configuration (if defined)
+ * 2. Auto-generated hierarchy-based chain (if enabled)
+ * 3. Default locale as final fallback
+ *
+ * @param locale - The locale to resolve the fallback chain for
+ * @param config - The fallback configuration
+ * @param options - Options for building the chain
+ * @returns The resolved fallback chain
+ *
+ * @example
+ * ```typescript
+ * const config: LocaleFallbackConfig = {
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES"],
+ *   },
+ * };
+ *
+ * // Explicit chain
+ * resolveFallbackChain("es-MX", config);
+ * // Returns: { requestedLocale: "es-MX", fallbackChain: ["es-ES", "en-US"], ... }
+ *
+ * // Auto-generated chain
+ * resolveFallbackChain("fr-CA", config);
+ * // Returns: { requestedLocale: "fr-CA", fallbackChain: ["fr", "en-US"], ... }
+ * ```
+ */
+export declare function resolveFallbackChain(locale: LocaleCode, config?: LocaleFallbackConfig, options?: BuildFallbackChainOptions): ResolvedFallbackChain;
+/**
+ * Gets the fallback chain as a simple array of locale codes.
+ *
+ * This is a convenience function for use with `getLocalizedValue`.
+ *
+ * @param locale - The locale to get fallback chain for
+ * @param config - The fallback configuration
+ * @returns Array of fallback locale codes
+ *
+ * @example
+ * ```typescript
+ * const chain = getFallbackChain("es-MX", config);
+ * // Returns: ["es-ES", "en-US"]
+ *
+ * // Use with getLocalizedValue
+ * const result = getLocalizedValue(value, {
+ *   locale: "es-MX",
+ *   fallbackChain: chain,
+ * });
+ * ```
+ */
+export declare function getFallbackChain(locale: LocaleCode, config?: LocaleFallbackConfig): LocaleCode[];
+/**
+ * Creates a LocaleFallbackConfig with defaults applied.
+ *
+ * @param config - Partial configuration to merge with defaults
+ * @returns Complete configuration with defaults
+ *
+ * @example
+ * ```typescript
+ * const config = createFallbackConfig({
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES"],
+ *   },
+ * });
+ * ```
+ */
+export declare function createFallbackConfig(config?: Partial<LocaleFallbackConfig>): Required<LocaleFallbackConfig>;
+/**
+ * Validates a LocaleFallbackConfig for common issues.
+ *
+ * @param config - The configuration to validate
+ * @returns Array of validation errors (empty if valid)
+ *
+ * @example
+ * ```typescript
+ * const errors = validateFallbackConfig({
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["invalid-locale"],
+ *   },
+ *   supportedLocales: ["en-US", "es-ES"],
+ * });
+ * // Returns: ["Fallback chain for 'es-MX' contains unsupported locale: 'invalid-locale'"]
+ * ```
+ */
+export declare function validateFallbackConfig(config: LocaleFallbackConfig): string[];
+/**
+ * Builds LocaleResolutionOptions from a locale and fallback configuration.
+ *
+ * This function creates the options object needed by `getLocalizedValue` and
+ * `resolveContentData` from the locale fallback configuration.
+ *
+ * @param locale - The requested locale
+ * @param config - The fallback configuration
+ * @returns LocaleResolutionOptions for use with locale resolution functions
+ *
+ * @example
+ * ```typescript
+ * const config: LocaleFallbackConfig = {
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES"],
+ *   },
+ * };
+ *
+ * const options = buildLocaleResolutionOptions("es-MX", config);
+ * // Returns: {
+ * //   locale: "es-MX",
+ * //   fallbackChain: ["es-ES", "en-US"],
+ * //   defaultLocale: "en-US"
+ * // }
+ *
+ * // Use with getLocalizedValue
+ * const result = getLocalizedValue(value, options);
+ * ```
+ */
+export declare function buildLocaleResolutionOptions(locale: LocaleCode, config?: LocaleFallbackConfig): LocaleResolutionOptions;
+/**
+ * Preset fallback configurations for common localization scenarios.
+ */
+export declare const FALLBACK_PRESETS: {
+    /**
+     * Spanish locale family fallback chain.
+     * Regional Spanish variants fall back to Spain Spanish, then English.
+     */
+    readonly spanish: {
+        readonly "es-MX": readonly ["es-ES", "en"];
+        readonly "es-AR": readonly ["es-ES", "en"];
+        readonly "es-CO": readonly ["es-ES", "en"];
+        readonly "es-CL": readonly ["es-ES", "en"];
+        readonly "es-PE": readonly ["es-ES", "en"];
+        readonly "es-VE": readonly ["es-ES", "en"];
+        readonly "es-ES": readonly ["en"];
+    };
+    /**
+     * Portuguese locale family fallback chain.
+     * Brazilian Portuguese falls back to Portugal Portuguese, then English.
+     */
+    readonly portuguese: {
+        readonly "pt-BR": readonly ["pt-PT", "en"];
+        readonly "pt-PT": readonly ["en"];
+    };
+    /**
+     * Chinese locale family fallback chain.
+     * Simplified and Traditional Chinese with regional variants.
+     */
+    readonly chinese: {
+        readonly "zh-Hans-CN": readonly ["zh-Hans", "zh", "en"];
+        readonly "zh-Hans-SG": readonly ["zh-Hans", "zh", "en"];
+        readonly "zh-Hant-TW": readonly ["zh-Hant", "zh", "en"];
+        readonly "zh-Hant-HK": readonly ["zh-Hant", "zh", "en"];
+        readonly "zh-Hans": readonly ["zh", "en"];
+        readonly "zh-Hant": readonly ["zh", "en"];
+    };
+    /**
+     * French locale family fallback chain.
+     */
+    readonly french: {
+        readonly "fr-CA": readonly ["fr-FR", "en"];
+        readonly "fr-BE": readonly ["fr-FR", "en"];
+        readonly "fr-CH": readonly ["fr-FR", "en"];
+        readonly "fr-FR": readonly ["en"];
+    };
+    /**
+     * German locale family fallback chain.
+     */
+    readonly german: {
+        readonly "de-AT": readonly ["de-DE", "en"];
+        readonly "de-CH": readonly ["de-DE", "en"];
+        readonly "de-DE": readonly ["en"];
+    };
+    /**
+     * English locale family fallback chain.
+     */
+    readonly english: {
+        readonly "en-GB": readonly ["en-US", "en"];
+        readonly "en-AU": readonly ["en-GB", "en-US", "en"];
+        readonly "en-CA": readonly ["en-US", "en"];
+        readonly "en-NZ": readonly ["en-AU", "en-GB", "en"];
+        readonly "en-US": readonly ["en"];
+    };
+};
+/**
+ * Merges multiple fallback chain presets into a single configuration.
+ *
+ * @param presets - Array of preset names to merge
+ * @returns Combined fallback chains
+ *
+ * @example
+ * ```typescript
+ * const chains = mergeFallbackPresets(["spanish", "portuguese"]);
+ * // Returns merged chains for both Spanish and Portuguese locales
+ * ```
+ */
+export declare function mergeFallbackPresets(presets: (keyof typeof FALLBACK_PRESETS)[]): Record<LocaleCode, LocaleCode[]>;
+//# sourceMappingURL=localeFallbackChain.d.ts.map

package/dist/component/localeFallbackChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localeFallbackChain.d.ts","sourceRoot":"","sources":["../../src/component/localeFallbackChain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAMjE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,aAAa,EAAE,UAAU,CAAC;IAE1B;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;IAElD;;;;;;;;;;;OAWG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,UAAU,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,eAAe,EAAE,UAAU,CAAC;IAE5B;;;OAGG;IACH,aAAa,EAAE,UAAU,EAAE,CAAC;IAE5B;;OAEG;IACH,aAAa,EAAE,UAAU,CAAC;IAE1B;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,oBAAoB,CAKlE,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,IAAI,CA4BnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAK7D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,CAoBnE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,oBAA8C,EACtD,OAAO,GAAE,yBAA8B,GACtC,qBAAqB,CAuDvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,oBAA8C,GACrD,UAAU,EAAE,CAEd;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM,GACzC,QAAQ,CAAC,oBAAoB,CAAC,CAOhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAiD7E;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,oBAA8C,GACrD,uBAAuB,CAQzB;AAMD;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;OAGG;;;;;;;;;;IAWH;;;OAGG;;;;;IAMH;;;OAGG;;;;;;;;;IAUH;;OAEG;;;;;;;IAQH;;OAEG;;;;;;IAOH;;OAEG;;;;;;;;CAQK,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,CAAC,MAAM,OAAO,gBAAgB,CAAC,EAAE,GACzC,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC,CAWlC"}