@ccheever/exact-ibex-runtime 0.1.0

package/src/core/i18n-helpers.ts

@@ -0,0 +1,189 @@
+export type LocaleDirection = 'ltr' | 'rtl';
+
+export interface ParsedLocaleTag {
+  language: string;
+  script?: string;
+  region?: string;
+}
+
+const RTL_SCRIPT_SUBTAGS = new Set([
+  'adlm',
+  'arab',
+  'hebr',
+  'mand',
+  'nkoo',
+  'rohg',
+  'samr',
+  'syrc',
+  'thaa',
+]);
+
+const RTL_LANGUAGE_SUBTAGS = new Set([
+  'ae',
+  'aeb',
+  'ar',
+  'arc',
+  'arq',
+  'ars',
+  'ary',
+  'arz',
+  'azb',
+  'bal',
+  'bcc',
+  'bqi',
+  'ckb',
+  'dv',
+  'fa',
+  'glk',
+  'he',
+  'iw',
+  'ks',
+  'khw',
+  'lrc',
+  'mzn',
+  'nqo',
+  'pnb',
+  'ps',
+  'sd',
+  'syr',
+  'ug',
+  'ur',
+  'yi',
+]);
+
+export function canonicalizeLocaleTag(tag: string): string {
+  const input = tag.trim();
+  if (input.length === 0) {
+    return input;
+  }
+
+  if (typeof Intl === 'object' && Intl && typeof Intl.getCanonicalLocales === 'function') {
+    try {
+      const [canonical] = Intl.getCanonicalLocales(input);
+      if (typeof canonical === 'string' && canonical.length > 0) {
+        return canonical;
+      }
+    } catch {
+      // Fall through to the local canonicalizer.
+    }
+  }
+
+  const parts = input.split('-');
+  if (parts.length > 0) {
+    parts[0] = parts[0]!.toLowerCase();
+  }
+
+  for (let index = 1; index < parts.length; index += 1) {
+    const part = parts[index];
+    if (!part) {
+      continue;
+    }
+
+    if (part.length === 4) {
+      parts[index] = part[0]!.toUpperCase() + part.slice(1).toLowerCase();
+      continue;
+    }
+
+    if (part.length === 2 || (part.length === 3 && /^[0-9A-Za-z]{3}$/.test(part))) {
+      parts[index] = part.toUpperCase();
+      continue;
+    }
+
+    parts[index] = part.toLowerCase();
+  }
+
+  return parts.join('-');
+}
+
+export function parseLocaleTag(tag: string): ParsedLocaleTag {
+  const canonical = canonicalizeLocaleTag(tag);
+  const parts = canonical.split('-').filter(Boolean);
+  const parsed: ParsedLocaleTag = {
+    language: parts[0]?.toLowerCase() || 'en',
+  };
+
+  for (const part of parts.slice(1)) {
+    if (part.length === 4 && parsed.script === undefined) {
+      parsed.script = part;
+      continue;
+    }
+
+    if ((part.length === 2 || part.length === 3) && parsed.region === undefined) {
+      parsed.region = part;
+      continue;
+    }
+
+    if (part.length === 1) {
+      break;
+    }
+  }
+
+  return parsed;
+}
+
+export function directionForLocaleTag(tag: string): LocaleDirection {
+  const parsed = parseLocaleTag(tag);
+  if (parsed.script && RTL_SCRIPT_SUBTAGS.has(parsed.script.toLowerCase())) {
+    return 'rtl';
+  }
+
+  return RTL_LANGUAGE_SUBTAGS.has(parsed.language) ? 'rtl' : 'ltr';
+}
+
+function isAsciiNeutral(codePoint: number): boolean {
+  return (
+    codePoint <= 0x20 ||
+    (codePoint >= 0x30 && codePoint <= 0x39) ||
+    (codePoint >= 0x21 && codePoint <= 0x2f) ||
+    (codePoint >= 0x3a && codePoint <= 0x40) ||
+    (codePoint >= 0x5b && codePoint <= 0x60) ||
+    (codePoint >= 0x7b && codePoint <= 0x7e)
+  );
+}
+
+function isRtlCodePoint(codePoint: number): boolean {
+  return (
+    (codePoint >= 0x0590 && codePoint <= 0x08ff) ||
+    (codePoint >= 0xfb1d && codePoint <= 0xfdff) ||
+    (codePoint >= 0xfe70 && codePoint <= 0xfefc) ||
+    (codePoint >= 0x10800 && codePoint <= 0x10fff) ||
+    (codePoint >= 0x1e800 && codePoint <= 0x1eeff)
+  );
+}
+
+function isNeutralCodePoint(codePoint: number): boolean {
+  return (
+    isAsciiNeutral(codePoint) ||
+    (codePoint >= 0x0660 && codePoint <= 0x0669) ||
+    (codePoint >= 0x06f0 && codePoint <= 0x06f9) ||
+    (codePoint >= 0x2000 && codePoint <= 0x206f) ||
+    (codePoint >= 0x20a0 && codePoint <= 0x20cf) ||
+    (codePoint >= 0x2190 && codePoint <= 0x21ff) ||
+    (codePoint >= 0x2460 && codePoint <= 0x27ff) ||
+    (codePoint >= 0x1f000 && codePoint <= 0x1faff)
+  );
+}
+
+export function detectTextDirection(
+  text: string | undefined,
+  fallback: LocaleDirection,
+): LocaleDirection {
+  if (typeof text !== 'string' || text.length === 0) {
+    return fallback;
+  }
+
+  for (const char of text) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === undefined) {
+      continue;
+    }
+
+    if (isNeutralCodePoint(codePoint)) {
+      continue;
+    }
+
+    return isRtlCodePoint(codePoint) ? 'rtl' : 'ltr';
+  }
+
+  return fallback;
+}

package/src/core/locale-state.ts

@@ -0,0 +1,253 @@
+// @system @ref LLP 0011#state-modules — startup imports only locale state.
+import {
+  canonicalizeLocaleTag,
+  directionForLocaleTag,
+  parseLocaleTag,
+  type LocaleDirection,
+} from './i18n-helpers.js';
+
+export interface ExactLocaleSnapshot {
+  readonly language: string;
+  readonly region: string;
+  readonly tag: string;
+  readonly tags: readonly string[];
+  readonly direction: LocaleDirection;
+  readonly uses24Hour: boolean;
+}
+
+export interface NativeLocaleSnapshot {
+  readonly tag?: string;
+  readonly tags?: readonly string[];
+  readonly uses24Hour?: boolean;
+}
+
+export interface ExactLocaleOverride {
+  readonly locale?: string;
+  readonly direction?: LocaleDirection;
+}
+
+export type ExactLocaleListener = (snapshot: ExactLocaleSnapshot) => void;
+
+interface ExactLocaleRuntimeState {
+  snapshot: ExactLocaleSnapshot;
+  override: ExactLocaleOverride | null;
+  listeners: Set<ExactLocaleListener>;
+  changeTimer: ReturnType<typeof setTimeout> | null;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __exactLocaleState: ExactLocaleRuntimeState | undefined;
+  // eslint-disable-next-line no-var
+  var __exactLocaleSnapshot: NativeLocaleSnapshot | undefined;
+  // eslint-disable-next-line no-var
+  var __exactLocaleChanged: ((snapshot?: NativeLocaleSnapshot | null) => void) | undefined;
+}
+
+function freezeSnapshot(snapshot: ExactLocaleSnapshot): ExactLocaleSnapshot {
+  return Object.freeze({
+    ...snapshot,
+    tags: Object.freeze([...snapshot.tags]),
+  });
+}
+
+export function readNativeLocaleSnapshot(): NativeLocaleSnapshot | null {
+  const nativeSnapshot = globalThis.__exactLocaleSnapshot;
+  if (nativeSnapshot && typeof nativeSnapshot === 'object') {
+    return nativeSnapshot;
+  }
+
+  const g = globalThis as typeof globalThis & {
+    __exactLocale?: unknown;
+    __exactLanguage?: unknown;
+    __exactHostNavigator?: {
+      language?: unknown;
+      languages?: unknown;
+    };
+  };
+
+  const hostNavigator =
+    g.__exactHostNavigator && typeof g.__exactHostNavigator === 'object'
+      ? g.__exactHostNavigator
+      : undefined;
+  const hostLanguages = Array.isArray(hostNavigator?.languages)
+    ? hostNavigator.languages.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0)
+    : [];
+  const hostLanguage =
+    typeof hostNavigator?.language === 'string' && hostNavigator.language.length > 0
+      ? hostNavigator.language
+      : undefined;
+
+  const fallbackTag =
+    typeof g.__exactLocale === 'string' && g.__exactLocale.length > 0
+      ? g.__exactLocale
+      : typeof g.__exactLanguage === 'string' && g.__exactLanguage.length > 0
+        ? g.__exactLanguage
+        : hostLanguage;
+
+  if (!fallbackTag && hostLanguages.length === 0) {
+    return null;
+  }
+
+  return {
+    tag: fallbackTag,
+    tags: hostLanguages,
+  };
+}
+
+function detectUses24Hour(localeTag: string): boolean {
+  if (typeof Intl !== 'object' || !Intl || typeof Intl.DateTimeFormat !== 'function') {
+    return false;
+  }
+
+  try {
+    const resolved = new Intl.DateTimeFormat(localeTag, { hour: 'numeric' }).resolvedOptions();
+    if (typeof resolved.hour12 === 'boolean') {
+      return resolved.hour12 === false;
+    }
+    if (typeof resolved.hourCycle === 'string') {
+      return resolved.hourCycle === 'h23' || resolved.hourCycle === 'h24';
+    }
+  } catch {
+    // Ignore Intl failures and fall back to 12-hour.
+  }
+
+  return false;
+}
+
+function buildLocaleSnapshot(
+  nativeSnapshot: NativeLocaleSnapshot | null,
+  override: ExactLocaleOverride | null,
+): ExactLocaleSnapshot {
+  const rawTags = Array.isArray(nativeSnapshot?.tags)
+    ? nativeSnapshot.tags.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0)
+    : [];
+  const primaryTag = canonicalizeLocaleTag(
+    override?.locale ??
+      nativeSnapshot?.tag ??
+      rawTags[0] ??
+      'en-US',
+  );
+  const tags =
+    override?.locale != null
+      ? [primaryTag]
+      : rawTags.length > 0
+        ? rawTags.map((tag) => canonicalizeLocaleTag(tag))
+        : [primaryTag];
+  const parsed = parseLocaleTag(primaryTag);
+  const region = parsed.region ?? '';
+  const uses24Hour =
+    typeof nativeSnapshot?.uses24Hour === 'boolean'
+      ? nativeSnapshot.uses24Hour
+      : detectUses24Hour(primaryTag);
+
+  return freezeSnapshot({
+    language: parsed.language,
+    region,
+    tag: primaryTag,
+    tags: Object.freeze(tags),
+    direction: override?.direction ?? directionForLocaleTag(primaryTag),
+    uses24Hour,
+  });
+}
+
+function createDefaultState(): ExactLocaleRuntimeState {
+  return {
+    snapshot: buildLocaleSnapshot(readNativeLocaleSnapshot(), null),
+    override: null,
+    listeners: new Set(),
+    changeTimer: null,
+  };
+}
+
+function getLocaleState(): ExactLocaleRuntimeState {
+  if (!globalThis.__exactLocaleState) {
+    globalThis.__exactLocaleState = createDefaultState();
+  }
+  return globalThis.__exactLocaleState;
+}
+
+function dispatchLocaleChange(state: ExactLocaleRuntimeState): void {
+  const snapshot = state.snapshot;
+  for (const listener of state.listeners) {
+    try {
+      listener(snapshot);
+    } catch {
+      // Ignore listener failures.
+    }
+  }
+}
+
+function scheduleLocaleChange(state: ExactLocaleRuntimeState): void {
+  if (state.changeTimer != null) {
+    clearTimeout(state.changeTimer);
+  }
+
+  state.changeTimer = setTimeout(() => {
+    state.changeTimer = null;
+    dispatchLocaleChange(state);
+  }, 100);
+}
+
+export function updateLocaleSnapshot(
+  nativeSnapshot: NativeLocaleSnapshot | null,
+  override: ExactLocaleOverride | null,
+  notify: boolean,
+): ExactLocaleSnapshot {
+  const state = getLocaleState();
+  const nextSnapshot = buildLocaleSnapshot(nativeSnapshot, override);
+  const prevSnapshot = state.snapshot;
+  state.snapshot = nextSnapshot;
+  state.override = override;
+
+  const changed =
+    prevSnapshot.tag !== nextSnapshot.tag ||
+    prevSnapshot.direction !== nextSnapshot.direction ||
+    prevSnapshot.uses24Hour !== nextSnapshot.uses24Hour ||
+    prevSnapshot.tags.length !== nextSnapshot.tags.length ||
+    prevSnapshot.tags.some((tag, index) => tag !== nextSnapshot.tags[index]);
+
+  if (notify && changed) {
+    scheduleLocaleChange(state);
+  }
+
+  return nextSnapshot;
+}
+
+export function subscribeExactLocaleChanges(listener: ExactLocaleListener): () => void {
+  const state = getLocaleState();
+  state.listeners.add(listener);
+  return () => {
+    state.listeners.delete(listener);
+  };
+}
+
+export function getExactLocaleSnapshot(): ExactLocaleSnapshot {
+  return getLocaleState().snapshot;
+}
+
+export function getExactLocaleOverride(): ExactLocaleOverride | null {
+  return getLocaleState().override;
+}
+
+export function refreshExactLocale(): ExactLocaleSnapshot {
+  return updateLocaleSnapshot(readNativeLocaleSnapshot(), getLocaleState().override, true);
+}
+
+export function setExactLocaleOverride(override: ExactLocaleOverride | null): ExactLocaleSnapshot {
+  return updateLocaleSnapshot(readNativeLocaleSnapshot(), override, true);
+}
+
+export function clearExactLocaleOverride(): ExactLocaleSnapshot {
+  return setExactLocaleOverride(null);
+}
+
+export function _resetExactLocaleForTests(): void {
+  const state = globalThis.__exactLocaleState;
+  if (state?.changeTimer != null) {
+    clearTimeout(state.changeTimer);
+  }
+  delete globalThis.__exactLocaleState;
+  delete globalThis.__exactLocaleChanged;
+  delete globalThis.__exactLocaleSnapshot;
+}

package/src/core/locale.ts

@@ -0,0 +1,95 @@
+import {
+  getExactLocaleOverride,
+  getExactLocaleSnapshot,
+  readNativeLocaleSnapshot,
+  subscribeExactLocaleChanges,
+  updateLocaleSnapshot,
+  type ExactLocaleListener,
+  type ExactLocaleSnapshot,
+  type NativeLocaleSnapshot,
+} from './locale-state.js';
+
+export {
+  _resetExactLocaleForTests,
+  clearExactLocaleOverride,
+  getExactLocaleSnapshot,
+  refreshExactLocale,
+  setExactLocaleOverride,
+  subscribeExactLocaleChanges,
+  type ExactLocaleSnapshot,
+} from './locale-state.js';
+
+interface ExactLocaleNamespace {
+  readonly language: string;
+  readonly region: string;
+  readonly tag: string;
+  readonly tags: readonly string[];
+  readonly direction: ExactLocaleSnapshot['direction'];
+  readonly uses24Hour: boolean;
+  addListener(event: 'change', listener: ExactLocaleListener): () => void;
+}
+
+function createLocaleNamespace(): ExactLocaleNamespace {
+  return {
+    get language() {
+      return getExactLocaleSnapshot().language;
+    },
+    get region() {
+      return getExactLocaleSnapshot().region;
+    },
+    get tag() {
+      return getExactLocaleSnapshot().tag;
+    },
+    get tags() {
+      return getExactLocaleSnapshot().tags;
+    },
+    get direction() {
+      return getExactLocaleSnapshot().direction;
+    },
+    get uses24Hour() {
+      return getExactLocaleSnapshot().uses24Hour;
+    },
+    addListener(_event: 'change', listener: ExactLocaleListener): () => void {
+      return subscribeExactLocaleChanges(listener);
+    },
+  };
+}
+
+export function installExactLocaleGlobal(): ExactLocaleNamespace {
+  const g = globalThis as typeof globalThis & {
+    Exact?: Record<string, unknown>;
+  };
+
+  if (typeof g.Exact !== 'object' || g.Exact === null) {
+    g.Exact = {};
+  }
+
+  const exact = g.Exact as Record<string, unknown>;
+  const existing = exact.locale;
+  if (existing && typeof existing === 'object' && typeof (existing as ExactLocaleNamespace).addListener === 'function') {
+    return existing as ExactLocaleNamespace;
+  }
+
+  updateLocaleSnapshot(readNativeLocaleSnapshot(), getExactLocaleOverride(), false);
+
+  const locale = createLocaleNamespace();
+  Object.defineProperty(exact, 'locale', {
+    value: locale,
+    writable: true,
+    configurable: true,
+    enumerable: true,
+  });
+
+  globalThis.__exactLocaleChanged = (snapshot?: NativeLocaleSnapshot | null) => {
+    if (snapshot && typeof snapshot === 'object') {
+      globalThis.__exactLocaleSnapshot = snapshot;
+    }
+    updateLocaleSnapshot(
+      snapshot ?? readNativeLocaleSnapshot(),
+      getExactLocaleOverride(),
+      true,
+    );
+  };
+
+  return locale;
+}