@object-ui/i18n 3.3.0 → 3.3.2

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/useSafeTranslation.ts

@@ -1,49 +0,0 @@
-/**
- * Safe translation hook with fallback to default strings.
- *
- * When no I18nProvider is available (e.g., in tests or standalone usage),
- * this hook falls back to the provided default translations instead of
- * returning raw i18n keys.
- *
- * @param defaults - Fallback English translations keyed by i18n key
- * @param testKey - A key to test if i18n is properly configured (must be in defaults)
- */
-import { useObjectTranslation } from './provider';
-
-export function createSafeTranslation(
-  defaults: Record<string, string>,
-  testKey: string,
-) {
-  return function useSafeTranslation() {
-    try {
-      const result = useObjectTranslation();
-      const testValue = result.t(testKey);
-      if (testValue === testKey) {
-        return {
-          t: (key: string, options?: Record<string, unknown>) => {
-            let value = defaults[key] || key;
-            if (options) {
-              for (const [k, v] of Object.entries(options)) {
-                value = value.replace(`{{${k}}}`, String(v));
-              }
-            }
-            return value;
-          },
-        };
-      }
-      return { t: result.t };
-    } catch {
-      return {
-        t: (key: string, options?: Record<string, unknown>) => {
-          let value = defaults[key] || key;
-          if (options) {
-            for (const [k, v] of Object.entries(options)) {
-              value = value.replace(`{{${k}}}`, String(v));
-            }
-          }
-          return value;
-        },
-      };
-    }
-  };
-}

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';