@object-ui/i18n 3.1.5 → 3.3.1

package/src/provider.tsx

@@ -1,177 +0,0 @@
-/**
- * @object-ui/i18n - React integration
- *
- * Provides I18nProvider and useObjectTranslation hook for React components.
- */
-import React, { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import { I18nextProvider, useTranslation } from 'react-i18next';
-import type { i18n as I18nInstance } from 'i18next';
-import { createI18n, getDirection, type I18nConfig } from './i18n';
-
-interface I18nContextValue {
-  /** Current language code */
-  language: string;
-  /** Change the active language */
-  changeLanguage: (lang: string) => Promise<void>;
-  /** Current text direction ('ltr' or 'rtl') */
-  direction: 'ltr' | 'rtl';
-  /** The underlying i18next instance */
-  i18n: I18nInstance;
-}
-
-const ObjectI18nContext = createContext<I18nContextValue | null>(null);
-
-export interface I18nProviderProps {
-  /** i18n configuration options */
-  config?: I18nConfig;
-  /** Pre-created i18next instance (overrides config) */
-  instance?: I18nInstance;
-  /**
-   * Dynamic language pack loader (v2.0.7).
-   * When set, language packs are loaded lazily instead of being bundled.
-   * Should return a translation resource object for the given language code.
-   *
-   * @example
-   * ```tsx
-   * <I18nProvider
-   *   loadLanguage={async (lang) => {
-   *     const mod = await import(`./locales/${lang}.json`);
-   *     return mod.default;
-   *   }}
-   * >
-   *   <App />
-   * </I18nProvider>
-   * ```
-   */
-  loadLanguage?: (lang: string) => Promise<Record<string, unknown>>;
-  /** Children to render */
-  children: React.ReactNode;
-}
-
-/**
- * I18nProvider - Wraps your app with i18n support
- *
- * @example
- * ```tsx
- * <I18nProvider config={{ defaultLanguage: 'zh' }}>
- *   <App />
- * </I18nProvider>
- * ```
- */
-export function I18nProvider({ config, instance: externalInstance, loadLanguage, children }: I18nProviderProps) {
-  const i18nInstance = useMemo(
-    () => externalInstance || createI18n(config),
-    [externalInstance, config],
-  );
-
-  const [language, setLanguage] = useState(i18nInstance.language || 'en');
-  const direction = getDirection(language);
-
-  // Track which languages have had app-specific translations loaded
-  // (separate from built-in locales that ship with the library)
-  const loadedAppLangs = useRef<Set<string>>(new Set());
-
-  useEffect(() => {
-    const handleLanguageChanged = (lng: string) => {
-      setLanguage(lng);
-      // Update document direction for RTL support
-      if (typeof document !== 'undefined') {
-        document.documentElement.dir = getDirection(lng);
-        document.documentElement.lang = lng;
-      }
-    };
-
-    i18nInstance.on('languageChanged', handleLanguageChanged);
-    return () => {
-      i18nInstance.off('languageChanged', handleLanguageChanged);
-    };
-  }, [i18nInstance]);
-
-  // Load app-specific translations for the initial language on mount
-  useEffect(() => {
-    if (!loadLanguage) return;
-    const currentLang = i18nInstance.language || 'en';
-    if (loadedAppLangs.current.has(currentLang)) return;
-    loadedAppLangs.current.add(currentLang);
-    loadLanguage(currentLang).then((resources) => {
-      if (resources && Object.keys(resources).length > 0) {
-        i18nInstance.addResourceBundle(currentLang, 'translation', resources, true, true);
-        // Force re-render so components pick up newly loaded translations
-        setLanguage(currentLang);
-      }
-    }).catch((err) => {
-      // Allow retry on failure by removing from loaded set
-      loadedAppLangs.current.delete(currentLang);
-      console.warn(`[i18n] Failed to load app translations for '${currentLang}':`, err);
-    });
-  }, [i18nInstance, loadLanguage]);
-
-  const contextValue = useMemo<I18nContextValue>(
-    () => ({
-      language,
-      changeLanguage: async (lang: string) => {
-        // Dynamic language pack loading (v2.0.7)
-        if (loadLanguage && !loadedAppLangs.current.has(lang)) {
-          loadedAppLangs.current.add(lang);
-          try {
-            const resources = await loadLanguage(lang);
-            i18nInstance.addResourceBundle(lang, 'translation', resources, true, true);
-          } catch (err) {
-            loadedAppLangs.current.delete(lang);
-            console.warn(`[i18n] Failed to load app translations for '${lang}':`, err);
-          }
-        }
-        await i18nInstance.changeLanguage(lang);
-      },
-      direction,
-      i18n: i18nInstance,
-    }),
-    [language, direction, i18nInstance, loadLanguage],
-  );
-
-  return React.createElement(
-    ObjectI18nContext.Provider,
-    { value: contextValue },
-    React.createElement(I18nextProvider, { i18n: i18nInstance }, children),
-  );
-}
-
-/**
- * Hook to access Object UI i18n context
- *
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { t, language, changeLanguage, direction } = useObjectTranslation();
- *   return <div dir={direction}>{t('common.save')}</div>;
- * }
- * ```
- */
-export function useObjectTranslation(ns?: string) {
-  const context = useContext(ObjectI18nContext);
-  const { t, i18n } = useTranslation(ns);
-
-  return {
-    /** Translation function */
-    t,
-    /** Current language code */
-    language: context?.language || i18n.language || 'en',
-    /** Change the active language */
-    changeLanguage: context?.changeLanguage || (async (lang: string) => { await i18n.changeLanguage(lang); }),
-    /** Current text direction */
-    direction: context?.direction || 'ltr',
-    /** The underlying i18next instance */
-    i18n,
-  };
-}
-
-/**
- * Hook to access the i18n context directly
- */
-export function useI18nContext(): I18nContextValue {
-  const context = useContext(ObjectI18nContext);
-  if (!context) {
-    throw new Error('useI18nContext must be used within an I18nProvider');
-  }
-  return context;
-}

package/src/useObjectLabel.ts

@@ -1,122 +0,0 @@
-/**
- * @object-ui/i18n - Convention-based Object & Field Label i18n
- *
- * Provides automatic translation resolution for object metadata labels
- * using Salesforce-style convention-based key generation.
- *
- * The app namespace (e.g. "crm") is discovered dynamically from loaded
- * i18next resources — no hardcoded app names in platform code.
- *
- * Convention Rules:
- * | What               | Auto-generated key                              | Fallback              |
- * |--------------------|-------------------------------------------------|-----------------------|
- * | Object label       | {ns}.objects.{objectName}.label                  | objectDef.label       |
- * | Object description | {ns}.objects.{objectName}.description             | objectDef.description |
- * | Field label        | {ns}.fields.{objectName}.{fieldName}              | field.label           |
- *
- * @module useObjectLabel
- */
-
-import { useObjectTranslation } from './provider';
-
-/**
- * Built-in Object UI top-level locale keys — not app namespaces.
- * Update this set when new top-level platform translation keys are added
- * to `packages/i18n/src/locales/en.ts` to prevent them from being treated
- * as app namespaces during dynamic namespace discovery.
- */
-const BUILTIN_KEYS = new Set([
-  'common', 'validation', 'form', 'table', 'grid', 'calendar',
-  'list', 'kanban', 'chart', 'dashboard', 'configPanel',
-  'appDesigner', 'console', 'errors', 'detail',
-]);
-
-/**
- * Hook for convention-based auto-resolution of object and field labels.
- *
- * Automatically constructs i18n keys from object/field names and looks up
- * translations, falling back to the plain-string label when no translation exists.
- *
- * The app namespace is discovered dynamically from loaded i18next resources
- * by finding top-level keys that contain an `objects` sub-key.
- *
- * @example
- * ```tsx
- * const { objectLabel, fieldLabel } = useObjectLabel();
- * <h1>{objectLabel(objectDef)}</h1>
- * ```
- */
-export function useObjectLabel() {
-  const { t, i18n } = useObjectTranslation();
-
-  /**
-   * Discover app namespace(s) from loaded i18next resources.
-   * Returns top-level keys (outside built-in Object UI keys) that contain
-   * an `objects` or `fields` sub-key — e.g. "crm" when resources include crm.objects.*.
-   */
-  const getAppNamespaces = (): string[] => {
-    if (!i18n || typeof i18n.getResourceBundle !== 'function') return [];
-    const lang = i18n.language || 'en';
-    const bundle = i18n.getResourceBundle(lang, 'translation') as Record<string, any> | undefined;
-    if (!bundle) return [];
-    return Object.keys(bundle).filter(
-      (key) => !BUILTIN_KEYS.has(key) && bundle[key] && typeof bundle[key] === 'object'
-        && (bundle[key].objects || bundle[key].fields),
-    );
-  };
-
-  /** Try resolving a key across all discovered app namespaces. */
-  const resolve = (suffix: string, fallback: string): string => {
-    try {
-      const namespaces = getAppNamespaces();
-      for (const ns of namespaces) {
-        const key = `${ns}.${suffix}`;
-        const translated = t(key, { defaultValue: '' });
-        if (translated && translated !== key && translated !== '') {
-          return translated;
-        }
-      }
-    } catch {
-      // Graceful degradation when i18n provider is not available
-    }
-    return fallback;
-  };
-
-  return {
-    /**
-     * Resolve translated object label, falling back to objectDef.label.
-     */
-    objectLabel: (objectDef: { name: string; label: string }) =>
-      resolve(`objects.${objectDef.name}.label`, objectDef.label),
-
-    /**
-     * Resolve translated object description, falling back to objectDef.description.
-     */
-    objectDescription: (objectDef: { name: string; description?: string }) => {
-      if (!objectDef.description) return undefined;
-      return resolve(`objects.${objectDef.name}.description`, objectDef.description);
-    },
-
-    /**
-     * Resolve translated field label, falling back to the provided fallback string.
-     */
-    fieldLabel: (objectName: string, fieldName: string, fallback: string) =>
-      resolve(`fields.${objectName}.${fieldName}`, fallback),
-  };
-}
-
-/**
- * Safe wrapper for useObjectLabel that falls back to identity functions
- * when no I18nProvider is available. Suitable for plugin components that
- * may be rendered outside an i18n context.
- */
-export function useSafeFieldLabel() {
-  try {
-    const { fieldLabel } = useObjectLabel();
-    return { fieldLabel };
-  } catch {
-    return {
-      fieldLabel: (_objectName: string, _fieldName: string, fallback: string) => fallback,
-    };
-  }
-}

package/src/utils/formatting.ts

@@ -1,136 +0,0 @@
-/**
- * @object-ui/i18n - Date and currency formatting utilities
- *
- * Uses the native Intl API for locale-aware formatting.
- */
-
-export interface DateFormatOptions {
-  locale?: string;
-  style?: 'short' | 'medium' | 'long' | 'full';
-  dateStyle?: Intl.DateTimeFormatOptions['dateStyle'];
-  timeStyle?: Intl.DateTimeFormatOptions['timeStyle'];
-}
-
-export interface CurrencyFormatOptions {
-  locale?: string;
-  currency?: string;
-  style?: 'currency' | 'decimal' | 'percent';
-  minimumFractionDigits?: number;
-  maximumFractionDigits?: number;
-}
-
-export interface NumberFormatOptions {
-  locale?: string;
-  style?: 'decimal' | 'percent' | 'unit';
-  minimumFractionDigits?: number;
-  maximumFractionDigits?: number;
-  notation?: 'standard' | 'scientific' | 'engineering' | 'compact';
-}
-
-/**
- * Format a date according to locale conventions
- */
-export function formatDate(
-  date: Date | string | number,
-  options: DateFormatOptions = {},
-): string {
-  const { locale = 'en', style = 'medium' } = options;
-  const d = date instanceof Date ? date : new Date(date);
-
-  if (isNaN(d.getTime())) {
-    return String(date);
-  }
-
-  const styleMap: Record<string, Intl.DateTimeFormatOptions> = {
-    short: { year: '2-digit', month: 'numeric', day: 'numeric' },
-    medium: { year: 'numeric', month: 'short', day: 'numeric' },
-    long: { year: 'numeric', month: 'long', day: 'numeric' },
-    full: { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' },
-  };
-
-  const formatOptions = options.dateStyle
-    ? { dateStyle: options.dateStyle, timeStyle: options.timeStyle }
-    : styleMap[style] || styleMap.medium;
-
-  return new Intl.DateTimeFormat(locale, formatOptions).format(d);
-}
-
-/**
- * Format a date and time according to locale conventions
- */
-export function formatDateTime(
-  date: Date | string | number,
-  options: DateFormatOptions = {},
-): string {
-  const { locale = 'en', style = 'medium' } = options;
-  const d = date instanceof Date ? date : new Date(date);
-
-  if (isNaN(d.getTime())) {
-    return String(date);
-  }
-
-  const styleMap: Record<string, Intl.DateTimeFormatOptions> = {
-    short: { year: '2-digit', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric' },
-    medium: { year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: 'numeric' },
-    long: { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric' },
-    full: { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric', timeZoneName: 'short' },
-  };
-
-  return new Intl.DateTimeFormat(locale, styleMap[style] || styleMap.medium).format(d);
-}
-
-/**
- * Format a relative time (e.g., "2 days ago", "in 3 hours")
- */
-export function formatRelativeTime(
-  date: Date | string | number,
-  locale = 'en',
-): string {
-  const d = date instanceof Date ? date : new Date(date);
-  const now = new Date();
-  const diffMs = d.getTime() - now.getTime();
-  const diffSec = Math.round(diffMs / 1000);
-  const diffMin = Math.round(diffSec / 60);
-  const diffHour = Math.round(diffMin / 60);
-  const diffDay = Math.round(diffHour / 24);
-
-  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
-
-  if (Math.abs(diffSec) < 60) return rtf.format(diffSec, 'second');
-  if (Math.abs(diffMin) < 60) return rtf.format(diffMin, 'minute');
-  if (Math.abs(diffHour) < 24) return rtf.format(diffHour, 'hour');
-  if (Math.abs(diffDay) < 30) return rtf.format(diffDay, 'day');
-
-  const diffMonth = Math.round(diffDay / 30);
-  if (Math.abs(diffMonth) < 12) return rtf.format(diffMonth, 'month');
-
-  return rtf.format(Math.round(diffDay / 365), 'year');
-}
-
-/**
- * Format a currency value according to locale conventions
- */
-export function formatCurrency(
-  value: number,
-  options: CurrencyFormatOptions = {},
-): string {
-  const { locale = 'en', currency = 'USD', minimumFractionDigits, maximumFractionDigits } = options;
-
-  return new Intl.NumberFormat(locale, {
-    style: 'currency',
-    currency,
-    minimumFractionDigits,
-    maximumFractionDigits,
-  }).format(value);
-}
-
-/**
- * Format a number according to locale conventions
- */
-export function formatNumber(
-  value: number,
-  options: NumberFormatOptions = {},
-): string {
-  const { locale = 'en', ...rest } = options;
-  return new Intl.NumberFormat(locale, rest).format(value);
-}

package/src/utils/index.ts

@@ -1,21 +0,0 @@
-export {
-  formatDate,
-  formatDateTime,
-  formatRelativeTime,
-  formatCurrency,
-  formatNumber,
-  type DateFormatOptions,
-  type CurrencyFormatOptions,
-  type NumberFormatOptions,
-} from './formatting';
-
-export {
-  resolvePlural,
-  formatDateSpec,
-  formatNumberSpec,
-  applyLocaleConfig,
-  type SpecPluralRule,
-  type SpecDateFormat,
-  type SpecNumberFormat,
-  type SpecLocaleConfig,
-} from './spec-formatters';

package/src/utils/spec-formatters.ts

@@ -1,220 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * @object-ui/i18n - Spec-aligned i18n utilities
- *
- * Runtime consumers for @objectstack/spec v2.0.7 i18n types:
- * - PluralRuleSchema → resolvePlural()
- * - DateFormatSchema → formatDateSpec()
- * - NumberFormatSchema → formatNumberSpec()
- * - LocaleConfigSchema → applyLocaleConfig()
- *
- * @module spec-formatters
- */
-
-// ============================================================================
-// PluralRuleSchema Consumer
-// ============================================================================
-
-/**
- * Spec-aligned PluralRule (mirrors @objectstack/spec PluralRuleSchema).
- */
-export interface SpecPluralRule {
-  /** Translation key */
-  key: string;
-  /** Form for zero items */
-  zero?: string;
-  /** Form for exactly one item */
-  one?: string;
-  /** Form for exactly two items */
-  two?: string;
-  /** Form for few items (language-specific) */
-  few?: string;
-  /** Form for many items (language-specific) */
-  many?: string;
-  /** Default/fallback form (required) */
-  other: string;
-}
-
-/**
- * Resolve a plural form based on count, following CLDR plural rules.
- * Uses the Intl.PluralRules API for correct locale-aware pluralization.
- *
- * @example
- * ```ts
- * const rule: SpecPluralRule = {
- *   key: 'items.count',
- *   zero: 'No items',
- *   one: '{count} item',
- *   other: '{count} items',
- * };
- * resolvePlural(rule, 0, 'en'); // → 'No items'
- * resolvePlural(rule, 1, 'en'); // → '1 item'
- * resolvePlural(rule, 5, 'en'); // → '5 items'
- * ```
- */
-export function resolvePlural(
-  rule: SpecPluralRule,
-  count: number,
-  locale = 'en',
-): string {
-  const pr = new Intl.PluralRules(locale);
-  const category = pr.select(count);
-
-  // Prefer the explicit form, fall back to 'other'
-  const template =
-    (category === 'zero' && rule.zero) ||
-    (category === 'one' && rule.one) ||
-    (category === 'two' && rule.two) ||
-    (category === 'few' && rule.few) ||
-    (category === 'many' && rule.many) ||
-    rule.other;
-
-  // Replace {count} placeholder
-  return template.replace(/\{count\}/g, String(count));
-}
-
-// ============================================================================
-// DateFormatSchema Consumer
-// ============================================================================
-
-/**
- * Spec-aligned DateFormat (mirrors @objectstack/spec DateFormatSchema).
- */
-export interface SpecDateFormat {
-  dateStyle?: 'full' | 'long' | 'medium' | 'short';
-  timeStyle?: 'full' | 'long' | 'medium' | 'short';
-  timeZone?: string;
-  hour12?: boolean;
-}
-
-/**
- * Format a date using @objectstack/spec DateFormatSchema configuration.
- *
- * @example
- * ```ts
- * formatDateSpec(new Date(), {
- *   dateStyle: 'medium',
- *   timeStyle: 'short',
- *   timeZone: 'America/New_York',
- * }, 'en-US');
- * ```
- */
-export function formatDateSpec(
-  date: Date | string | number,
-  format: SpecDateFormat,
-  locale = 'en',
-): string {
-  const d = date instanceof Date ? date : new Date(date);
-  if (isNaN(d.getTime())) return String(date);
-
-  const options: Intl.DateTimeFormatOptions = {};
-  if (format.dateStyle) options.dateStyle = format.dateStyle;
-  if (format.timeStyle) options.timeStyle = format.timeStyle;
-  if (format.timeZone) options.timeZone = format.timeZone;
-  if (format.hour12 !== undefined) options.hour12 = format.hour12;
-
-  return new Intl.DateTimeFormat(locale, options).format(d);
-}
-
-// ============================================================================
-// NumberFormatSchema Consumer
-// ============================================================================
-
-/**
- * Spec-aligned NumberFormat (mirrors @objectstack/spec NumberFormatSchema).
- */
-export interface SpecNumberFormat {
-  style?: 'currency' | 'percent' | 'decimal' | 'unit';
-  currency?: string;
-  unit?: string;
-  minimumFractionDigits?: number;
-  maximumFractionDigits?: number;
-  useGrouping?: boolean;
-}
-
-/**
- * Format a number using @objectstack/spec NumberFormatSchema configuration.
- *
- * @example
- * ```ts
- * formatNumberSpec(1234.56, {
- *   style: 'currency',
- *   currency: 'USD',
- *   maximumFractionDigits: 2,
- * }, 'en-US'); // → '$1,234.56'
- * ```
- */
-export function formatNumberSpec(
-  value: number,
-  format: SpecNumberFormat,
-  locale = 'en',
-): string {
-  const options: Intl.NumberFormatOptions = {
-    style: format.style || 'decimal',
-  };
-
-  if (format.currency) options.currency = format.currency;
-  if (format.unit) options.unit = format.unit;
-  if (format.minimumFractionDigits !== undefined) options.minimumFractionDigits = format.minimumFractionDigits;
-  if (format.maximumFractionDigits !== undefined) options.maximumFractionDigits = format.maximumFractionDigits;
-  if (format.useGrouping !== undefined) options.useGrouping = format.useGrouping;
-
-  return new Intl.NumberFormat(locale, options).format(value);
-}
-
-// ============================================================================
-// LocaleConfigSchema Consumer
-// ============================================================================
-
-/**
- * Spec-aligned LocaleConfig (mirrors @objectstack/spec LocaleConfigSchema).
- */
-export interface SpecLocaleConfig {
-  /** BCP 47 language code (e.g., 'en-US', 'zh-CN') */
-  code: string;
-  /** Fallback locale chain */
-  fallbackChain?: string[];
-  /** Text direction */
-  direction?: 'ltr' | 'rtl';
-  /** Number formatting defaults */
-  numberFormat?: SpecNumberFormat;
-  /** Date formatting defaults */
-  dateFormat?: SpecDateFormat;
-}
-
-/**
- * Apply a LocaleConfigSchema to configure i18n formatting defaults.
- * Returns resolved formatting functions bound to the locale config.
- *
- * @example
- * ```ts
- * const locale = applyLocaleConfig({
- *   code: 'zh-CN',
- *   direction: 'ltr',
- *   numberFormat: { style: 'decimal', useGrouping: true },
- *   dateFormat: { dateStyle: 'medium' },
- * });
- * locale.formatDate(new Date()); // Chinese medium date
- * locale.formatNumber(1234.5);   // 1,234.5
- * ```
- */
-export function applyLocaleConfig(config: SpecLocaleConfig) {
-  return {
-    code: config.code,
-    direction: config.direction || 'ltr',
-    fallbackChain: config.fallbackChain || [],
-    formatDate: (date: Date | string | number, overrides?: Partial<SpecDateFormat>) =>
-      formatDateSpec(date, { ...config.dateFormat, ...overrides }, config.code),
-    formatNumber: (value: number, overrides?: Partial<SpecNumberFormat>) =>
-      formatNumberSpec(value, { ...config.numberFormat, ...overrides }, config.code),
-    resolvePlural: (rule: SpecPluralRule, count: number) =>
-      resolvePlural(rule, count, config.code),
-  };
-}

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "noEmit": false,
-    "declaration": true,
-    "composite": true
-  },
-  "include": ["src"],
-  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
-}