npm - @ozsarman/clarityjs - Versions diffs - 0.6.0 - Mend

@ozsarman/clarityjs 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/src/i18n.js ADDED Viewed

@@ -0,0 +1,403 @@
+/**
+ * Clarity.js — Internationalization (i18n)
+ *
+ * Lightweight, signal-based i18n with first-class RTL support.
+ *
+ * Features:
+ *   - Reactive locale / translation signals
+ *   - Pluralisation (CLDR-style: zero | one | two | few | many | other)
+ *   - Nested key paths:  t('user.profile.title')
+ *   - Interpolation:     t('greeting', { name: 'Özdemir' })  → "Hello, Özdemir!"
+ *   - RTL detection + automatic <html dir="rtl|ltr"> update
+ *   - isRTL() signal — drive CSS logical properties in components
+ *   - Currency / date / number formatters via Intl
+ *   - Lazy locale loading: loadLocale(code, () => import('./locales/ar.js'))
+ *   - SSR-safe: no DOM dependency at module level
+ *
+ * Usage:
+ *   import { createI18n, useI18n, t, locale, isRTL } from '@ozsarman/clarityjs/i18n';
+ *
+ *   const i18n = createI18n({
+ *     locale: 'en',
+ *     messages: {
+ *       en: { greeting: 'Hello, {name}!', items: { one: '{count} item', other: '{count} items' } },
+ *       ar: { greeting: 'مرحباً، {name}!', items: { one: '{count} عنصر', other: '{count} عناصر' } },
+ *     },
+ *   });
+ *
+ *   // In a component:
+ *   const { t, locale, isRTL } = useI18n();
+ *   t('greeting', { name: 'Özdemir' });   // "Hello, Özdemir!"
+ *   locale.set('ar');                     // switches to Arabic → sets dir="rtl"
+ *   isRTL.get();                          // true
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+import { signal, effect } from './runtime.js';
+// ─── RTL locale list (ISO 639-1 + regional codes) ─────────────────────────────
+/**
+ * Languages written right-to-left.
+ * Includes all major RTL scripts: Arabic, Hebrew, Persian, Urdu, …
+ */
+export const RTL_LOCALES = new Set([
+  // Arabic
+  'ar', 'ar-AE', 'ar-BH', 'ar-DZ', 'ar-EG', 'ar-IQ', 'ar-JO', 'ar-KW',
+  'ar-LB', 'ar-LY', 'ar-MA', 'ar-OM', 'ar-QA', 'ar-SA', 'ar-SY', 'ar-TN',
+  'ar-YE',
+  // Hebrew
+  'he', 'he-IL',
+  // Persian / Farsi
+  'fa', 'fa-IR', 'fa-AF',
+  // Urdu
+  'ur', 'ur-PK', 'ur-IN',
+  // Sindhi
+  'sd',
+  // Pashto
+  'ps', 'ps-AF',
+  // Kurdish (Sorani)
+  'ckb', 'ku',
+  // Dhivehi (Maldivian)
+  'dv',
+  // Yiddish
+  'yi',
+  // Azerbaijani (Arabic script variant)
+  'az-Arab',
+  // Kashmiri
+  'ks',
+  // Uyghur
+  'ug',
+]);
+/**
+ * Returns true if the given locale code is a known RTL language.
+ *
+ * @param {string} localeCode  e.g. 'ar', 'he-IL', 'en-US'
+ * @returns {boolean}
+ */
+export function isRTLLocale(localeCode) {
+  if (!localeCode) return false;
+  if (RTL_LOCALES.has(localeCode)) return true;
+  // Match on language subtag: 'ar-EG' → 'ar'
+  const lang = localeCode.split('-')[0].toLowerCase();
+  return RTL_LOCALES.has(lang);
+}
+// ─── Global i18n singleton ────────────────────────────────────────────────────
+let _globalI18n = null;
+/**
+ * Create (and register globally) an i18n instance.
+ *
+ * @param {object} config
+ * @param {string}          config.locale           - Initial locale code (e.g. 'en')
+ * @param {object}          config.messages         - { [locale]: { [key]: string | object } }
+ * @param {string}          [config.fallbackLocale] - Fallback when a key is missing
+ * @param {boolean}         [config.updateHtmlDir=true] - Auto-set <html dir> on locale change
+ * @param {boolean}         [config.ssr=false]      - Disable DOM side-effects (for SSR)
+ * @returns {I18nInstance}
+ */
+export function createI18n(config = {}) {
+  const instance = new I18nInstance(config);
+  _globalI18n = instance;
+  return instance;
+}
+/**
+ * Access the global i18n instance (must call createI18n first).
+ *
+ * @returns {I18nInstance}
+ */
+export function useI18n() {
+  if (!_globalI18n) {
+    throw new Error(
+      '[Clarity i18n] No i18n instance found.\n' +
+      'Call createI18n({ locale, messages }) before using useI18n().'
+    );
+  }
+  return _globalI18n;
+}
+// ─── Convenience top-level exports ───────────────────────────────────────────
+/** Reactive translation function (delegates to global instance). */
+export function t(key, vars) {
+  return _globalI18n?.t(key, vars) ?? key;
+}
+/** Reactive locale signal (read: locale.get(), write: locale.set('fr')). */
+export function getLocale() {
+  return _globalI18n?.locale ?? signal('en');
+}
+/** Reactive isRTL signal — true when current locale is RTL. */
+export function getIsRTL() {
+  return _globalI18n?.isRTL ?? signal(false);
+}
+// ─── I18nInstance ─────────────────────────────────────────────────────────────
+class I18nInstance {
+  constructor({
+    locale: initialLocale = 'en',
+    messages = {},
+    fallbackLocale,
+    updateHtmlDir = true,
+    ssr = false,
+  } = {}) {
+    this._messages  = { ...messages };
+    this._fallback  = fallbackLocale;
+    this._ssr       = ssr;
+    this._loaders   = new Map(); // locale → () => Promise<messages>
+    this._loaded    = new Set(Object.keys(messages));
+    /** @type {Signal<string>} */
+    this.locale = signal(initialLocale);
+    /** @type {Signal<boolean>} */
+    this.isRTL = signal(isRTLLocale(initialLocale));
+    /** @type {Signal<string>} Convenience alias: 'ltr' | 'rtl' */
+    this.dir = signal(isRTLLocale(initialLocale) ? 'rtl' : 'ltr');
+    // Keep isRTL and dir in sync with locale
+    effect(() => {
+      const code = this.locale.get();
+      const rtl  = isRTLLocale(code);
+      this.isRTL.set(rtl);
+      this.dir.set(rtl ? 'rtl' : 'ltr');
+      // Update <html dir="…"> automatically
+      if (updateHtmlDir && !ssr && typeof document !== 'undefined') {
+        document.documentElement.setAttribute('dir', rtl ? 'rtl' : 'ltr');
+        document.documentElement.setAttribute('lang', code);
+      }
+    });
+  }
+  // ── Core translation ────────────────────────────────────────────────────────
+  /**
+   * Translate a key in the current locale.
+   *
+   * @param {string}  key    Dot-separated key path, e.g. 'user.profile.title'
+   * @param {object}  [vars] Interpolation variables + optional `count` for pluralisation
+   * @returns {string}
+   */
+  t(key, vars = {}) {
+    const code = this.locale.get(); // reactive dependency
+    const msg  = this._resolve(code, key, vars)
+              ?? (this._fallback ? this._resolve(this._fallback, key, vars) : null)
+              ?? key;
+    return msg;
+  }
+  /**
+   * Translate in a specific locale (non-reactive).
+   */
+  tIn(localeCode, key, vars = {}) {
+    return this._resolve(localeCode, key, vars)
+        ?? (this._fallback ? this._resolve(this._fallback, key, vars) : null)
+        ?? key;
+  }
+  // ── Locale management ───────────────────────────────────────────────────────
+  /**
+   * Change the active locale, loading it lazily if needed.
+   *
+   * @param {string} code  e.g. 'fr', 'ar', 'zh-TW'
+   * @returns {Promise<void>}
+   */
+  async setLocale(code) {
+    if (!this._loaded.has(code) && this._loaders.has(code)) {
+      await this._lazyLoad(code);
+    }
+    this.locale.set(code);
+  }
+  /**
+   * Register a lazy locale loader.
+   *
+   * @param {string}   code    Locale code
+   * @param {function} loader  () => Promise<{ default: messages } | messages>
+   */
+  loadLocale(code, loader) {
+    this._loaders.set(code, loader);
+    return this;
+  }
+  /**
+   * Add or merge message keys for a locale.
+   */
+  addMessages(code, msgs) {
+    this._messages[code] = _deepMerge(this._messages[code] ?? {}, msgs);
+    this._loaded.add(code);
+    return this;
+  }
+  /**
+   * Returns all registered locale codes.
+   */
+  availableLocales() {
+    return [...new Set([...Object.keys(this._messages), ...this._loaders.keys()])];
+  }
+  // ── Intl formatters ─────────────────────────────────────────────────────────
+  /**
+   * Format a number using Intl.NumberFormat.
+   *
+   * @param {number}  value
+   * @param {object}  [opts]  Intl.NumberFormat options
+   * @returns {string}
+   */
+  n(value, opts = {}) {
+    const code = this.locale.get();
+    return new Intl.NumberFormat(code, opts).format(value);
+  }
+  /**
+   * Format a currency amount.
+   *
+   * @param {number}  value
+   * @param {string}  currency  ISO 4217 code, e.g. 'USD', 'EUR', 'TRY'
+   * @param {object}  [opts]    Additional Intl.NumberFormat options
+   * @returns {string}
+   */
+  currency(value, currency, opts = {}) {
+    const code = this.locale.get();
+    return new Intl.NumberFormat(code, { style: 'currency', currency, ...opts }).format(value);
+  }
+  /**
+   * Format a date.
+   *
+   * @param {Date|number|string} value
+   * @param {object}  [opts]  Intl.DateTimeFormat options
+   * @returns {string}
+   */
+  d(value, opts = {}) {
+    const code = this.locale.get();
+    return new Intl.DateTimeFormat(code, opts).format(new Date(value));
+  }
+  /**
+   * Format a relative time (e.g. "3 hours ago").
+   *
+   * @param {number}  value    Numeric value (negative = past, positive = future)
+   * @param {string}  unit     'second'|'minute'|'hour'|'day'|'week'|'month'|'year'
+   * @param {object}  [opts]   Intl.RelativeTimeFormat options
+   * @returns {string}
+   */
+  relative(value, unit = 'day', opts = {}) {
+    const code = this.locale.get();
+    return new Intl.RelativeTimeFormat(code, { numeric: 'auto', ...opts }).format(value, unit);
+  }
+  // ── Private ─────────────────────────────────────────────────────────────────
+  _resolve(code, key, vars) {
+    const messages = this._messages[code];
+    if (!messages) return null;
+    // Traverse dot-separated key path
+    const parts = key.split('.');
+    let node = messages;
+    for (const part of parts) {
+      if (node == null || typeof node !== 'object') return null;
+      node = node[part];
+    }
+    if (node == null) return null;
+    // Pluralisation: if node is an object with plural keys
+    if (typeof node === 'object') {
+      node = this._pluralize(code, node, vars.count);
+      if (node == null) return null;
+    }
+    // Interpolation: replace {varName} placeholders
+    return _interpolate(String(node), vars);
+  }
+  _pluralize(code, forms, count) {
+    if (count === undefined || count === null) {
+      return forms.other ?? forms.one ?? Object.values(forms)[0] ?? null;
+    }
+    // Use CLDR plural rules via Intl.PluralRules
+    try {
+      const rule = new Intl.PluralRules(code).select(count);
+      return forms[rule] ?? forms.other ?? Object.values(forms)[0] ?? null;
+    } catch {
+      // Fallback: simple singular/plural
+      return count === 1 ? (forms.one ?? forms.other) : forms.other;
+    }
+  }
+  async _lazyLoad(code) {
+    const loader = this._loaders.get(code);
+    if (!loader) return;
+    try {
+      let msgs = await loader();
+      // Support both { default: msgs } and direct object
+      if (msgs?.default && typeof msgs.default === 'object') msgs = msgs.default;
+      this.addMessages(code, msgs);
+    } catch (e) {
+      console.error(`[Clarity i18n] Failed to load locale "${code}":`, e);
+    }
+  }
+}
+// ─── RTL utilities ────────────────────────────────────────────────────────────
+/**
+ * Apply dir="rtl|ltr" to any element (useful for portals / shadow roots).
+ *
+ * @param {Element} el
+ * @param {boolean} rtl
+ */
+export function applyDir(el, rtl) {
+  if (!el) return;
+  el.setAttribute('dir', rtl ? 'rtl' : 'ltr');
+}
+/**
+ * A Clarity component that wraps children in a dir-aware container.
+ * Use for mixed-direction content.
+ *
+ * @param {object} props
+ * @param {boolean} props.rtl  - Force RTL direction
+ * @param {*}       props.children
+ * @returns {HTMLElement}
+ */
+export function BiDiWrapper({ rtl, children }) {
+  const el = document.createElement('div');
+  el.setAttribute('dir', rtl ? 'rtl' : 'ltr');
+  const nodes = Array.isArray(children) ? children : [children];
+  nodes.forEach(child => child && el.appendChild(child));
+  return el;
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function _interpolate(template, vars) {
+  return template.replace(/\{(\w+)\}/g, (_, key) => {
+    const val = vars[key];
+    return val !== undefined ? String(val) : `{${key}}`;
+  });
+}
+function _deepMerge(target, source) {
+  const result = { ...target };
+  for (const [k, v] of Object.entries(source)) {
+    result[k] = (v && typeof v === 'object' && !Array.isArray(v) && typeof result[k] === 'object')
+      ? _deepMerge(result[k], v)
+      : v;
+  }
+  return result;
+}