@symbiote-native/localization 0.0.1

package/src/core/types.ts

@@ -0,0 +1,181 @@
+// Hand-ported verbatim from .vendors/expo/packages/expo-localization/src/Localization.types.ts
+// (sdk-57) — plain data shapes, no expo-modules-core dependency at all. Every JSDoc comment is
+// kept as-is: they document real, per-platform behavior differences, not restated obviousness.
+
+export type Locale = {
+  /**
+   * An [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) with a region code.
+   * @example
+   * `'en-US'`, `'es-419'`, `'pl-PL'`.
+   */
+  languageTag: string;
+  /**
+   * An [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) without the region code.
+   * @example
+   * `'en'`, `'es'`, `'pl'`.
+   */
+  languageCode: string | null;
+  /**
+   * An [ISO 15924](https://en.wikipedia.org/wiki/ISO_15924) 4-letter script code. On Android and Web, it may be `null` if none is defined.
+   * @example
+   * `'Latn'`, `'Hans'`, `'Hebr'`.
+   */
+  languageScriptCode: string | null;
+  /**
+   * The region code for your device that comes from the Region setting under Language & Region on iOS, Region settings on Android and is parsed from locale on Web (can be `null` on Web).
+   * @example
+   * `'US'`.
+   */
+  regionCode: string | null;
+  /**
+   * The region code for the preferred language. When the language is not region-specific, it returns the same value as `regionCode`. When the language is region-specific, it returns the region code for the language (`en-CA` -> `CA`).
+   * Prefer using `regionCode` for any internalization purposes.
+   * @example
+   * `'US'`.
+   */
+  languageRegionCode: string | null;
+  /**
+   * Currency code for the locale.
+   * On iOS, it's the currency code from the `Region` setting under Language & Region, not for the current locale.
+   * On Android, it's the currency specifc to the locale in the list, as there are no separate settings for selecting a region.
+   * Is `null` on Web, use a table lookup based on region instead.
+   * @example
+   * `'USD'`, `'EUR'`, `'PLN'`.
+   */
+  currencyCode: string | null;
+  /**
+   * Currency symbol for the currency specified by `currencyCode`.
+   * @example
+   * `'$'`, `'€'`, `'zł'`.
+   */
+  currencySymbol: string | null;
+  /**
+   * Currency code for the locale.
+   * On iOS, it's the currency code for the current locale in the list, not the device region.
+   * On Android, it's equal to `currencyCode`.
+   * Is `null` on Web.
+   * Prefer using `currencyCode` for any internalization purposes.
+   * @example
+   * `'USD'`, `'EUR'`, `'PLN'`.
+   */
+  languageCurrencyCode: string | null;
+  /**
+   * Currency symbol for the currency specified by `languageCurrencyCode`.
+   * Prefer using `currencySymbol` for any internalization purposes.
+   * @example
+   * `'$'`, `'€'`, `'zł'`.
+   */
+  languageCurrencySymbol: string | null;
+  /**
+   * Decimal separator used for formatting numbers with fractional parts.
+   * @example
+   * `'.'`, `','`.
+   */
+  decimalSeparator: string | null;
+  /**
+   * Digit grouping separator used for formatting large numbers.
+   * @example
+   * `'.'`, `','`.
+   */
+  digitGroupingSeparator: string | null;
+  /**
+   * Text direction for the locale. One of: `'ltr'`, `'rtl'`.
+   */
+  textDirection: 'ltr' | 'rtl';
+  /**
+   * The measurement system used in the locale.
+   * Is `null` on Web, as user chosen measurement system is not exposed on the web and using locale to determine measurement systems is unreliable.
+   * Ask for user preferences if possible.
+   */
+  measurementSystem: `metric` | `us` | `uk` | null;
+  /**
+   * The temperature unit used in the locale.
+   * Returns `null` if the region code is unknown.
+   */
+  temperatureUnit: 'celsius' | 'fahrenheit' | null;
+};
+
+/**
+ * An enum mapping days of the week in Gregorian calendar to their index as returned by the `firstWeekday` property.
+ */
+export enum Weekday {
+  SUNDAY = 1,
+  MONDAY = 2,
+  TUESDAY = 3,
+  WEDNESDAY = 4,
+  THURSDAY = 5,
+  FRIDAY = 6,
+  SATURDAY = 7,
+}
+
+/**
+ * The calendar identifier, one of [Unicode calendar types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar).
+ */
+export enum CalendarIdentifier {
+  /** Thai Buddhist calendar */
+  BUDDHIST = 'buddhist',
+  /** Traditional Chinese calendar */
+  CHINESE = 'chinese',
+  /** Coptic calendar */
+  COPTIC = 'coptic',
+  /** Traditional Korean calendar */
+  DANGI = 'dangi',
+  /** Ethiopic calendar, Amete Alem (epoch approx. 5493 B.C.E) */
+  ETHIOAA = 'ethioaa',
+  /** Ethiopic calendar, Amete Mihret (epoch approx, 8 C.E.) */
+  ETHIOPIC = 'ethiopic',
+  /** Gregorian calendar (also referred to upstream as "gregorian" — dropped as a separate
+   * member here since this repo's lint bans duplicate enum values). */
+  GREGORY = 'gregory',
+  /** Traditional Hebrew calendar */
+  HEBREW = 'hebrew',
+  /** Indian calendar */
+  INDIAN = 'indian',
+  /** Islamic calendar */
+  ISLAMIC = 'islamic',
+  /** Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - civil epoch) */
+  ISLAMIC_CIVIL = 'islamic-civil',
+  /** Islamic calendar, Saudi Arabia sighting */
+  ISLAMIC_RGSA = 'islamic-rgsa',
+  /**Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - astronomical epoch) */
+  ISLAMIC_TBLA = 'islamic-tbla',
+  /** Islamic calendar, Umm al-Qura */
+  ISLAMIC_UMALQURA = 'islamic-umalqura',
+  /** ISO calendar (Gregorian calendar using the ISO 8601 calendar week rules) */
+  ISO8601 = 'iso8601',
+  /** Japanese imperial calendar */
+  JAPANESE = 'japanese',
+  /** Persian calendar */
+  PERSIAN = 'persian',
+  /** Civil (algorithmic) Arabic calendar */
+  ROC = 'roc',
+}
+
+export type Calendar = {
+  /**
+   * The calendar identifier, one of [Unicode calendar types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar).
+   *
+   * On Android is limited to one of device's [available calendar types](https://developer.android.com/reference/java/util/Calendar#getAvailableCalendarTypes()).
+   *
+   * On iOS uses [calendar identifiers](https://developer.apple.com/documentation/foundation/calendar/identifier), but maps them to the corresponding Unicode types, will also never contain `'dangi'` or `'islamic-rgsa'` due to it not being implemented on iOS.
+   */
+  calendar: CalendarIdentifier | null;
+  /**
+   * True when current device settings use 24-hour time format.
+   * Can be null on some browsers that don't support the [hourCycle](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle) property in [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API.
+   */
+  uses24hourClock: boolean | null;
+  /**
+   * The first day of the week. For most calendars Sunday is numbered `1`, with Saturday being number `7`.
+   * Can be null on some browsers that don't support the [weekInfo](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/weekInfo) property in [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API.
+   * @example
+   * `1`, `7`.
+   */
+  firstWeekday: Weekday | null;
+  /**
+   * Time zone for the calendar. Can be `null` on Web.
+   * @example
+   * `'America/Los_Angeles'`, `'Europe/Warsaw'`, `'GMT+1'`.
+   */
+  timeZone: string | null;
+};

package/src/react/hooks/use-calendars/index.ts

@@ -0,0 +1,16 @@
+// React lifecycle wiring over the framework-agnostic core — mirrors use-locales' shape exactly.
+// Ported from expo-localization's own useCalendars hook (sdk-57).
+import { useEffect, useMemo, useReducer } from 'react';
+import { addCalendarListener, getCalendars, type Calendar } from '../../../core';
+
+export function useCalendars(): Calendar[] {
+  const [invalidationKey, invalidate] = useReducer((key: number) => key + 1, 0);
+  const calendars = useMemo(() => getCalendars(), [invalidationKey]);
+
+  useEffect(() => {
+    const subscription = addCalendarListener(invalidate);
+    return () => subscription.remove();
+  }, []);
+
+  return calendars;
+}

package/src/react/hooks/use-calendars/use-calendars.test.tsx

@@ -0,0 +1,87 @@
+// Co-located React-driven test (ADR 0025) for useCalendars. See use-locales' test for the shared
+// rationale (mocks `core`, not expo-modules-core internals).
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { CalendarIdentifier, Weekday, type Calendar } from '../../../core/types';
+import { useCalendars } from './index';
+
+const FAKE_CALENDARS_INITIAL: Calendar[] = [
+  {
+    calendar: CalendarIdentifier.GREGORY,
+    uses24hourClock: true,
+    firstWeekday: Weekday.SUNDAY,
+    timeZone: 'Europe/Warsaw',
+  },
+];
+
+const FAKE_CALENDARS_UPDATED: Calendar[] = [
+  {
+    calendar: CalendarIdentifier.ISO8601,
+    uses24hourClock: false,
+    firstWeekday: Weekday.MONDAY,
+    timeZone: 'America/New_York',
+  },
+];
+
+const { addListener, getCalendars, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: () => void) => ({ remove })),
+    getCalendars: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  addCalendarListener: addListener,
+  getCalendars,
+}));
+
+const ROOT_TAG = 955;
+
+const results: Calendar[][] = [];
+
+function Probe(): ReactElement {
+  results.push(useCalendars());
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+  getCalendars.mockReturnValue(FAKE_CALENDARS_INITIAL);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useCalendars', () => {
+  it('reads the current calendars synchronously on first render', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    expect(results[results.length - 1]).toEqual(FAKE_CALENDARS_INITIAL);
+  });
+
+  it('recomputes calendars when the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    const invalidate = addListener.mock.calls[0][0];
+    getCalendars.mockReturnValue(FAKE_CALENDARS_UPDATED);
+    invalidate();
+
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(FAKE_CALENDARS_UPDATED));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/hooks/use-locales/index.ts

@@ -0,0 +1,18 @@
+// React lifecycle wiring over the framework-agnostic core (core/localization.ts /
+// core/native-module.ts). Ported from expo-localization's own useLocales hook (sdk-57): a
+// useReducer-driven invalidation counter that useMemo recomputes getLocales() from, whenever the
+// native module fires onLocaleSettingsChanged.
+import { useEffect, useMemo, useReducer } from 'react';
+import { addLocaleListener, getLocales, type Locale } from '../../../core';
+
+export function useLocales(): Locale[] {
+  const [invalidationKey, invalidate] = useReducer((key: number) => key + 1, 0);
+  const locales = useMemo(() => getLocales(), [invalidationKey]);
+
+  useEffect(() => {
+    const subscription = addLocaleListener(invalidate);
+    return () => subscription.remove();
+  }, []);
+
+  return locales;
+}

package/src/react/hooks/use-locales/use-locales.test.tsx

@@ -0,0 +1,107 @@
+// Co-located React-driven test (ADR 0025) for useLocales. Mocks `core`, not expo-modules-core
+// internals — same pattern packages/battery's hook tests use.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import type { Locale } from '../../../core';
+import { useLocales } from './index';
+
+const FAKE_LOCALES_INITIAL: Locale[] = [
+  {
+    languageTag: 'pl-PL',
+    languageCode: 'pl',
+    languageScriptCode: 'Latn',
+    regionCode: 'PL',
+    languageRegionCode: 'PL',
+    currencyCode: 'PLN',
+    currencySymbol: 'zł',
+    languageCurrencyCode: 'PLN',
+    languageCurrencySymbol: 'zł',
+    decimalSeparator: ',',
+    digitGroupingSeparator: ' ',
+    textDirection: 'ltr',
+    measurementSystem: 'metric',
+    temperatureUnit: 'celsius',
+  },
+];
+
+const FAKE_LOCALES_UPDATED: Locale[] = [
+  {
+    languageTag: 'en-US',
+    languageCode: 'en',
+    languageScriptCode: 'Latn',
+    regionCode: 'US',
+    languageRegionCode: 'US',
+    currencyCode: 'USD',
+    currencySymbol: '$',
+    languageCurrencyCode: 'USD',
+    languageCurrencySymbol: '$',
+    decimalSeparator: '.',
+    digitGroupingSeparator: ',',
+    textDirection: 'ltr',
+    measurementSystem: 'us',
+    temperatureUnit: 'fahrenheit',
+  },
+];
+
+const { addListener, getLocales, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: () => void) => ({ remove })),
+    getLocales: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  addLocaleListener: addListener,
+  getLocales,
+}));
+
+const ROOT_TAG = 954;
+
+const results: Locale[][] = [];
+
+function Probe(): ReactElement {
+  results.push(useLocales());
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+  getLocales.mockReturnValue(FAKE_LOCALES_INITIAL);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useLocales', () => {
+  it('reads the current locales synchronously on first render', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    expect(results[results.length - 1]).toEqual(FAKE_LOCALES_INITIAL);
+  });
+
+  it('recomputes locales when the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    const invalidate = addListener.mock.calls[0][0];
+    getLocales.mockReturnValue(FAKE_LOCALES_UPDATED);
+    invalidate();
+
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(FAKE_LOCALES_UPDATED));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/index.ts

@@ -0,0 +1,18 @@
+// @symbiote-native/localization/react: the React entry over the framework-agnostic core. Locales
+// and calendars each get their own lifecycle hook, matching upstream's own useLocales/
+// useCalendars being two separate hooks, not one combined hook — mirrors the lifecycle-bucket
+// naming convention of adapters/react/src/hooks (never `composables`, that's Vue's term).
+
+export { useLocales } from './hooks/use-locales';
+export { useCalendars } from './hooks/use-calendars';
+export {
+  getLocales,
+  getCalendars,
+  addLocaleListener,
+  addCalendarListener,
+  Weekday,
+  CalendarIdentifier,
+  type Locale,
+  type Calendar,
+  type EventSubscription,
+} from '../core';

package/src/vue/composables/use-calendars/index.ts

@@ -0,0 +1,25 @@
+// Vue lifecycle wiring over the framework-agnostic core — mirrors use-locales' shape exactly.
+import { onMounted, onUnmounted, ref, type Ref } from '@vue/runtime-core';
+import {
+  addCalendarListener,
+  getCalendars,
+  type Calendar,
+  type EventSubscription,
+} from '../../../core';
+
+export function useCalendars(): Ref<Calendar[]> {
+  const calendars = ref<Calendar[]>(getCalendars());
+  let subscription: EventSubscription | undefined;
+
+  onMounted(() => {
+    subscription = addCalendarListener(() => {
+      calendars.value = getCalendars();
+    });
+  });
+
+  onUnmounted(() => {
+    subscription?.remove();
+  });
+
+  return calendars;
+}

package/src/vue/composables/use-calendars/use-calendars.test.ts

@@ -0,0 +1,96 @@
+// Co-located Vue-driven test (ADR 0025) for useCalendars. See use-locales' test for the shared
+// rationale.
+
+import { defineComponent, h, type Ref } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount } from '@symbiote-native/vue';
+import { installFabric } from '@symbiote-native/test-utils';
+import { CalendarIdentifier, Weekday, type Calendar } from '../../../core/types';
+import { useCalendars } from './index';
+
+const ROOT_TAG = 9955;
+
+const FAKE_CALENDARS_INITIAL: Calendar[] = [
+  {
+    calendar: CalendarIdentifier.GREGORY,
+    uses24hourClock: true,
+    firstWeekday: Weekday.SUNDAY,
+    timeZone: 'Europe/Warsaw',
+  },
+];
+
+const FAKE_CALENDARS_UPDATED: Calendar[] = [
+  {
+    calendar: CalendarIdentifier.ISO8601,
+    uses24hourClock: false,
+    firstWeekday: Weekday.MONDAY,
+    timeZone: 'America/New_York',
+  },
+];
+
+let registeredListener: (() => void) | undefined;
+const removeMock = vi.fn();
+const addListenerMock = vi.fn((listener: () => void) => {
+  registeredListener = listener;
+  return { remove: removeMock };
+});
+const getCalendarsMock = vi.fn(() => FAKE_CALENDARS_INITIAL);
+
+vi.mock('../../../core', () => ({
+  addCalendarListener: (listener: () => void) => addListenerMock(listener),
+  getCalendars: () => getCalendarsMock(),
+}));
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  registeredListener = undefined;
+  addListenerMock.mockClear();
+  removeMock.mockClear();
+  getCalendarsMock.mockClear();
+  getCalendarsMock.mockReturnValue(FAKE_CALENDARS_INITIAL);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+function mountCalendars(): Ref<Calendar[]> {
+  let calendars: Ref<Calendar[]> | undefined;
+  mount(
+    ROOT_TAG,
+    defineComponent({
+      setup: () => {
+        calendars = useCalendars();
+        return () => h('symbiote-text', {}, 'calendars');
+      },
+    }),
+  );
+  if (calendars === undefined) {
+    throw new Error('setup() did not run');
+  }
+  return calendars;
+}
+
+describe('useCalendars (Vue)', () => {
+  it('reads the current calendars synchronously at setup', () => {
+    const calendars = mountCalendars();
+
+    expect(calendars.value).toEqual(FAKE_CALENDARS_INITIAL);
+  });
+
+  it('recomputes the ref when the native listener fires', () => {
+    const calendars = mountCalendars();
+
+    getCalendarsMock.mockReturnValue(FAKE_CALENDARS_UPDATED);
+    registeredListener?.();
+
+    expect(calendars.value).toEqual(FAKE_CALENDARS_UPDATED);
+  });
+
+  it('removes the subscription on unmount', () => {
+    mountCalendars();
+    unmount(ROOT_TAG);
+
+    expect(removeMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/vue/composables/use-locales/index.ts

@@ -0,0 +1,24 @@
+// Vue lifecycle wiring over the framework-agnostic core (core/localization.ts). Unlike
+// packages/network's use-network-state (which seeds a placeholder and fetches asynchronously in
+// onMounted), getLocales() is a synchronous native call, so the ref is computed once, directly at
+// setup — onMounted only wires the change listener, mirroring use-network-state's
+// onMounted/onUnmounted subscription shape otherwise.
+import { onMounted, onUnmounted, ref, type Ref } from '@vue/runtime-core';
+import { addLocaleListener, getLocales, type EventSubscription, type Locale } from '../../../core';
+
+export function useLocales(): Ref<Locale[]> {
+  const locales = ref<Locale[]>(getLocales());
+  let subscription: EventSubscription | undefined;
+
+  onMounted(() => {
+    subscription = addLocaleListener(() => {
+      locales.value = getLocales();
+    });
+  });
+
+  onUnmounted(() => {
+    subscription?.remove();
+  });
+
+  return locales;
+}

package/src/vue/composables/use-locales/use-locales.test.ts

@@ -0,0 +1,116 @@
+// Co-located Vue-driven test (ADR 0025) for useLocales. See packages/battery's
+// use-battery-state.test.ts for the shared rationale.
+
+import { defineComponent, h, type Ref } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount } from '@symbiote-native/vue';
+import { installFabric } from '@symbiote-native/test-utils';
+import type { Locale } from '../../../core';
+import { useLocales } from './index';
+
+const ROOT_TAG = 9954;
+
+const FAKE_LOCALES_INITIAL: Locale[] = [
+  {
+    languageTag: 'pl-PL',
+    languageCode: 'pl',
+    languageScriptCode: 'Latn',
+    regionCode: 'PL',
+    languageRegionCode: 'PL',
+    currencyCode: 'PLN',
+    currencySymbol: 'zł',
+    languageCurrencyCode: 'PLN',
+    languageCurrencySymbol: 'zł',
+    decimalSeparator: ',',
+    digitGroupingSeparator: ' ',
+    textDirection: 'ltr',
+    measurementSystem: 'metric',
+    temperatureUnit: 'celsius',
+  },
+];
+
+const FAKE_LOCALES_UPDATED: Locale[] = [
+  {
+    languageTag: 'en-US',
+    languageCode: 'en',
+    languageScriptCode: 'Latn',
+    regionCode: 'US',
+    languageRegionCode: 'US',
+    currencyCode: 'USD',
+    currencySymbol: '$',
+    languageCurrencyCode: 'USD',
+    languageCurrencySymbol: '$',
+    decimalSeparator: '.',
+    digitGroupingSeparator: ',',
+    textDirection: 'ltr',
+    measurementSystem: 'us',
+    temperatureUnit: 'fahrenheit',
+  },
+];
+
+let registeredListener: (() => void) | undefined;
+const removeMock = vi.fn();
+const addListenerMock = vi.fn((listener: () => void) => {
+  registeredListener = listener;
+  return { remove: removeMock };
+});
+const getLocalesMock = vi.fn(() => FAKE_LOCALES_INITIAL);
+
+vi.mock('../../../core', () => ({
+  addLocaleListener: (listener: () => void) => addListenerMock(listener),
+  getLocales: () => getLocalesMock(),
+}));
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  registeredListener = undefined;
+  addListenerMock.mockClear();
+  removeMock.mockClear();
+  getLocalesMock.mockClear();
+  getLocalesMock.mockReturnValue(FAKE_LOCALES_INITIAL);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+function mountLocales(): Ref<Locale[]> {
+  let locales: Ref<Locale[]> | undefined;
+  mount(
+    ROOT_TAG,
+    defineComponent({
+      setup: () => {
+        locales = useLocales();
+        return () => h('symbiote-text', {}, 'locales');
+      },
+    }),
+  );
+  if (locales === undefined) {
+    throw new Error('setup() did not run');
+  }
+  return locales;
+}
+
+describe('useLocales (Vue)', () => {
+  it('reads the current locales synchronously at setup', () => {
+    const locales = mountLocales();
+
+    expect(locales.value).toEqual(FAKE_LOCALES_INITIAL);
+  });
+
+  it('recomputes the ref when the native listener fires', () => {
+    const locales = mountLocales();
+
+    getLocalesMock.mockReturnValue(FAKE_LOCALES_UPDATED);
+    registeredListener?.();
+
+    expect(locales.value).toEqual(FAKE_LOCALES_UPDATED);
+  });
+
+  it('removes the subscription on unmount', () => {
+    mountLocales();
+    unmount(ROOT_TAG);
+
+    expect(removeMock).toHaveBeenCalledTimes(1);
+  });
+});