locon 1.4.6 → 1.5.0

package/dist/index.d.ts

@@ -1,19 +1,196 @@
 import * as react from 'react';
-import { ReactElement, PropsWithChildren } from 'react';
-import LoconContext$1 from './types/LoconContext.js';
-export { default as LText } from './components/LText.js';
-export { default as useLocon } from './hooks/useLocon.js';
-import './types/Assets.js';
-import 'react-native';
+import { ComponentProps, ReactElement, PropsWithChildren } from 'react';
+import { Text } from 'react-native';
+
+type Assets = Record<string, Record<string, string>>;
+
+/**
+ * Per-call options for `l()`, `lIn()` and `<LText>`.
+ *
+ * All four are optional and independent: `params` interpolates, `count`
+ * selects a plural form, and `locale` renders one call in a language other
+ * than the current one (used when an app exports a document in a language
+ * the interface is not currently showing). `fallback` is returned only when
+ * no locale resolves the input.
+ */
+interface TranslateOptions {
+    /** Values for `{token}` placeholders inside the resolved string. */
+    params?: Record<string, string | number>;
+    /** Selects `key_one` / `key_few` / `key_other` … via `Intl.PluralRules`. */
+    count?: number;
+    /** Resolve against this locale instead of the current one. */
+    locale?: string;
+    /** Human-readable fallback when no locale resolves the key/value. */
+    fallback?: string;
+}
+
+interface LoconContext$1 {
+    /** Localizes a key — or a phrase in the project language. */
+    l: (assetKey: string, options?: TranslateOptions) => string;
+    /** Localizes into an explicit locale, whatever the current one is. */
+    lIn: (locale: string, assetKey: string, options?: Omit<TranslateOptions, 'locale'>) => string;
+    assets: Assets;
+    /** Every locale present in `assets`. */
+    locales: string[];
+    currentLocale: string;
+    defaultLocale: string;
+    projectLocale: string;
+    /** Locale detected from the device, or `null` when none matched. */
+    systemLocale: string | null;
+    /** Whether `currentLocale` is written right-to-left. */
+    isRTL: boolean;
+    autodetect: boolean;
+    /** Switches locale. Pass `null` to go back to following the device. */
+    setLocale: (locale: string | null) => void;
+}
+
+interface LTextProps extends ComponentProps<typeof Text> {
+    children: string;
+    assetKey?: string;
+    /** Values for `{token}` placeholders. */
+    params?: Record<string, string | number>;
+    /** Selects a plural form via `Intl.PluralRules`. */
+    count?: number;
+    /** Renders in this locale instead of the current one. */
+    locale?: string;
+}
+declare function LText({ children, assetKey, params, count, locale, ...props }: LTextProps): ReactElement;
+
+declare function useLocon(): LoconContext$1;
+
+/**
+ * The resolver behind `l()`, usable without React.
+ *
+ * The provider builds one of these per render; export pipelines (PDF, XLSX,
+ * e-mail) build their own with an explicit locale, so a document can be
+ * produced in a language the interface is not currently showing.
+ */
+
+interface TranslatorConfig {
+    assets: Assets;
+    locale: string;
+    defaultLocale?: string;
+    projectLocale?: string;
+}
+type Translator = (assetKey: string, options?: TranslateOptions) => string;
+declare function createTranslator({ assets, locale, defaultLocale, projectLocale }: TranslatorConfig): Translator;
+
+/**
+ * Best available locale for this device, or `null` when none of the device's
+ * languages is one the app ships.
+ */
+declare function getSystemLanguage(availableLocales?: string[]): string | null;
+
+/**
+ * Decides which locale to display.
+ *
+ * The provider uses this, and so can anything running outside React — a
+ * background task building a notification, an export pipeline, a native
+ * bridge. Keeping the precedence in one place is the point: an app that
+ * re-derives "explicit choice, else device, else default" on its own will
+ * eventually disagree with the provider about what language it is in.
+ */
+
+interface ResolveLocaleConfig {
+    assets: Assets;
+    /** An explicit choice, `null` to follow the device, `undefined` for neither. */
+    currentLocale?: string | null;
+    defaultLocale?: string;
+    autodetect?: boolean;
+    /**
+     * A device locale already detected by the caller.
+     *
+     * Pass it to skip a second detection pass; omit it to let this function
+     * detect. `null` states that detection ran and matched nothing.
+     */
+    systemLocale?: string | null;
+}
+declare function resolveLocale({ assets, currentLocale, defaultLocale, autodetect, systemLocale, }: ResolveLocaleConfig): string;
+
+/**
+ * Builds a BCP-47 tag carrying Unicode extensions, for handing to `Intl`.
+ *
+ * `locon` has no opinion on which calendar or numbering system your app
+ * should use — a Persian journal app wants Jalali dates, a Persian payroll
+ * export usually does not. That is a product decision. What the library can
+ * do is get the tag syntax right, which naive concatenation does not:
+ * appending `-u-ca-gregory` to a locale that already reads `de-u-nu-latn`
+ * yields a tag with two `-u-` singletons, and `Intl` throws on it.
+ */
+interface IntlExtensions {
+    /** Calendar system, e.g. `gregory`, `islamic`, `persian`. */
+    calendar?: string;
+    /** Numbering system, e.g. `latn`, `arab`, `deva`. */
+    numbering?: string;
+}
+/**
+ * Returns `locale` with the given Unicode extensions applied, merging into an
+ * existing `-u-` section rather than adding a second one. Keys already present
+ * in the tag are left alone, so an explicit choice by the caller wins.
+ */
+declare function intlLocale(locale: string, extensions?: IntlExtensions): string;
+
+/**
+ * Right-to-left helpers.
+ *
+ * This is a writing-direction table, not a platform support table: it answers
+ * "is this locale written right-to-left" per CLDR, regardless of whether Apple
+ * or Google happen to offer that language as a system UI language.
+ *
+ * `locon` does not flip your layout on its own — React Native can only change
+ * writing direction through `I18nManager`, and that change needs an app
+ * restart to take effect. So the library tells you *whether* a locale is RTL
+ * and gives you one explicit call to apply it; when to restart stays yours.
+ */
+/**
+ * Language subtags whose default script is right-to-left, per CLDR.
+ *
+ * Deliberately excludes languages that merely *have* an RTL historical
+ * orthography — Hausa is Latin-script (Boko) in CLDR and therefore LTR, even
+ * though Ajami exists.
+ */
+declare const RTL_LANGUAGES: Set<string>;
+/**
+ * Right-to-left ISO 15924 script subtags.
+ *
+ * Checked before the language table so that explicitly scripted tags resolve
+ * correctly in both directions: `pa-Arab` (Shahmukhi Punjabi) is RTL although
+ * plain `pa` is not, and `ku-Latn` is LTR although `ku-Arab` is not.
+ */
+declare const RTL_SCRIPTS: Set<string>;
+/** True when the locale is written right-to-left. */
+declare function isRtlLocale(locale?: string | null): boolean;
+/**
+ * Aligns React Native's layout direction with `locale`.
+ *
+ * Returns `true` when the direction actually changed, which means the running
+ * UI is now inconsistent and the app must restart for the new direction to
+ * render. Callers typically prompt the user, or reload via `expo-updates`.
+ *
+ * No-ops (returning `false`) outside React Native, so calling it on web or in
+ * tests is safe.
+ */
+declare function applyRTL(locale: string): boolean;
 
 declare const LoconContext: react.Context<LoconContext$1>;
-interface Props extends PropsWithChildren {
+interface LoconProps extends PropsWithChildren {
     assets?: Record<string, Record<string, string>>;
-    currentLocale?: string;
+    /**
+     * Locale to display.
+     *
+     * - a string selects that locale; later prop changes select the new value
+     * - `null` explicitly follows the device language
+     * - omitted leaves the locale uncontrolled after the initial detection
+     *
+     * The `null` form exists for apps that persist a user choice: storing
+     * "follow the system" as `null` and passing it straight through switches
+     * detection back on without an app restart.
+     */
+    currentLocale?: string | null;
     defaultLocale?: string;
     projectLocale?: string;
     autodetect?: boolean;
 }
-declare function Locon({ children, assets, currentLocale: currentLocaleProps, defaultLocale, projectLocale, autodetect, }: Props): ReactElement;
+declare function Locon({ children, assets, currentLocale: currentLocaleProps, defaultLocale, projectLocale, autodetect, }: LoconProps): ReactElement;
 
-export { LoconContext, Locon as default };
+export { type Assets, type IntlExtensions, LText, type LTextProps, LoconContext, type LoconContext$1 as LoconContextValue, type LoconProps, RTL_LANGUAGES, RTL_SCRIPTS, type ResolveLocaleConfig, type TranslateOptions, type Translator, type TranslatorConfig, applyRTL, createTranslator, Locon as default, getSystemLanguage, intlLocale, isRtlLocale, resolveLocale, useLocon };