@dokebi/template-inertia 0.4.1 → 0.4.4

package/dist/i18n.d.ts

@@ -0,0 +1,216 @@
+import { type App, type ComputedRef } from 'vue';
+import { BundleStore, type StoreHost } from './i18n-store.js';
+export type PageI18nErrorCode = 'UNAVAILABLE' | 'INVALID_CATALOG' | 'INVALID_LOCALE' | 'INVALID_FORMAT' | 'MISSING_MESSAGE' | 'INVALID_PARAMETER' | 'OUTPUT_LIMIT' | 'RECOVERY_FAILED';
+/** A coded error of the browser runtime; the codes are the server translator's. */
+export declare class PageI18nError extends Error {
+    readonly code: PageI18nErrorCode;
+    readonly plugin = "dokebi-template-inertia";
+    readonly fix: string;
+    constructor(code: PageI18nErrorCode, message: string, fix?: string, cause?: unknown);
+}
+export type PageMessage = string | Readonly<Partial<Record<Intl.LDMLPluralRule, string>> & {
+    other: string;
+}>;
+export type PageParameters = Readonly<Record<string, string | number>>;
+/** How the browser keeps bundles (dokebi-i18n http.pageCache); absent on seal hosts and when off. */
+export interface PageI18nCache {
+    readonly cookie: string;
+    readonly maxCookieBytes: number;
+    readonly maxAgeSeconds: number;
+    readonly maxBundles: number;
+    readonly maxStoreCharacters: number;
+}
+/** Settings the server sends once per catalog version (dokebi-i18n options and formats). */
+export interface PageI18nSettings {
+    readonly locales: readonly string[];
+    readonly defaultLocale: string;
+    readonly missing: 'error' | 'key';
+    readonly timeZone: string;
+    readonly maxOutputLength: number;
+    /** Longest message key (dokebi-i18n maxKeyLength). Default 256. */
+    readonly maxKeyLength?: number;
+    /** Longest message or plural branch, a `t()` default included (maxBranchLength). Default 16384. */
+    readonly maxBranchLength?: number;
+    /** The preference cookie dokebi-i18n reads (http.cookieName). */
+    readonly cookie: string;
+    readonly numberFormats: Readonly<Record<string, Intl.NumberFormatOptions>>;
+    readonly dateFormats: Readonly<Record<string, Intl.DateTimeFormatOptions>>;
+    /** Longest X-Dokebi-I18n header the server reads (http.maxPageHeaderBytes). Default 4096. */
+    readonly maxHeaderBytes?: number;
+    readonly cache?: PageI18nCache;
+}
+/** The shared page prop `i18n` of dokebi-i18n (D-0099, D-0126). */
+export interface PageI18nPayload {
+    readonly locale: string;
+    readonly version: string;
+    /** Message lookup chain of `locale`, `locale` first. */
+    readonly fallback: readonly string[];
+    /** Namespaces the page needs. */
+    readonly namespaces: readonly string[];
+    /** locale → flat key → message: the messages of the bundles in `bundles`. */
+    readonly messages?: Readonly<Record<string, Readonly<Record<string, PageMessage>>>>;
+    /** namespace → token of every bundle this answer carries. */
+    readonly bundles?: Readonly<Record<string, string>>;
+    /** namespace → token of the bundles the server left out because the cookie named them. */
+    readonly held?: Readonly<Record<string, string>>;
+    readonly settings?: PageI18nSettings;
+}
+/** The debug log of the runtime (D-0047); the core Logger and a console adapter fit. */
+export interface PageI18nLogger {
+    isEnabled?(level: 'debug' | 'warn' | 'error'): boolean;
+    log(level: 'debug' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+}
+/** Messages of one locale: flat keys (`auth.password.minimum`) or nested namespace objects. */
+export interface MessageTree {
+    readonly [key: string]: PageMessage | MessageTree;
+}
+export interface CreateI18nOptions {
+    readonly locale: string;
+    /** locale → messages (flat dot keys or nested objects, as in locales/<locale>/<ns>.json). */
+    readonly messages: Readonly<Record<string, MessageTree>>;
+    /** Lookup chain of `locale` (default: `locale`, its parent tags with messages, `defaultLocale`). */
+    readonly fallback?: readonly string[];
+    /** Default: `locale`. */
+    readonly defaultLocale?: string;
+    readonly missing?: 'error' | 'key';
+    readonly timeZone?: string;
+    readonly maxOutputLength?: number;
+    /** Longest message key (dokebi-i18n maxKeyLength). Default 256. */
+    readonly maxKeyLength?: number;
+    /** Longest message or plural branch (dokebi-i18n maxBranchLength). Default 16384. */
+    readonly maxBranchLength?: number;
+    readonly numberFormats?: Readonly<Record<string, Intl.NumberFormatOptions>>;
+    readonly dateFormats?: Readonly<Record<string, Intl.DateTimeFormatOptions>>;
+    readonly logger?: PageI18nLogger;
+}
+/** The part of Inertia's `router` the page connector uses (`import { router } from '@inertiajs/vue3'`). */
+export interface PageI18nRouter {
+    on(event: 'before', callback: (event: {
+        detail: {
+            visit: {
+                headers: Record<string, string>;
+            };
+        };
+    }) => void): unknown;
+    reload(options?: {
+        only?: readonly string[];
+        onFinish?: () => void;
+    }): void;
+}
+export interface PageI18nOptions {
+    /** Inertia's router: adds the held-messages header to visits, follows new pages, switches. */
+    readonly router?: PageI18nRouter;
+    readonly logger?: PageI18nLogger;
+    /**
+     * Where bundles are kept between page loads (D-0126). Default: the browser's localStorage when
+     * the server allows it (`settings.cache`); `false` keeps nothing (and names nothing).
+     */
+    readonly storage?: StoreHost['storage'] | false;
+}
+/** Request header naming what this browser holds: `v=<version>; h=<token><token>…`. */
+export declare const PAGE_I18N_HEADER = "X-Dokebi-I18n";
+/**
+ * @internal How pageI18n feeds an I18n: the payload of the page being shown (reactive in an
+ * Inertia app, read where it is used, so a new page's messages are there before it renders).
+ */
+interface PageFeed {
+    attach(app: App): void;
+    current(): PageI18nPayload | undefined;
+    /** A payload was taken in; true when its missing messages are being fetched. */
+    absorbed(payload: PageI18nPayload, complete: boolean): boolean;
+}
+/**
+ * One app's translations: `t`, `n`, `d` and `has` are bound (destructure them from useI18n()),
+ * `locale` and `locales` are read-only refs, so templates re-render when the language changes.
+ */
+export declare class I18n {
+    #private;
+    readonly locale: ComputedRef<string>;
+    readonly locales: ComputedRef<readonly string[]>;
+    constructor(options: CreateI18nOptions);
+    /** Translates `key` with the lookup chain; with `defaultValue`, only the locale's own message wins. */
+    readonly t: {
+        (key: string, parameters?: PageParameters): string;
+        (key: string, defaultValue: string, parameters?: PageParameters): string;
+    };
+    /** True when the lookup chain of the current locale has `key`. */
+    readonly has: (key: string) => boolean;
+    /** A finite number with a named format of the dokebi-i18n entry (`default`: Intl's). */
+    readonly n: (value: number, format?: string) => string;
+    /**
+     * The application's time zone of this page's settings (D-0178: it follows i18n setTimeZone on
+     * the server): pass it to the @dokebi/i18n/calendar helpers so pages count days as the server does.
+     */
+    readonly timeZone: () => string;
+    /** A Date or epoch milliseconds with a named format, in the configured time zone. */
+    readonly d: (value: Date | number, format?: string) => string;
+    /** The language's own name (`English`, `Français`) for a language switch. */
+    readonly localeName: (locale: string) => string;
+    /**
+     * Shows another language. On an Inertia page (pageI18n) it writes the preference cookie and
+     * reloads the page's props from the server (no document reload); otherwise the messages of
+     * `locale` must be loaded already.
+     */
+    readonly switchLocale: (locale: string) => Promise<void>;
+    /** Vue plugin: provides this instance to useI18n() and `$t`, `$n`, `$d` to templates. */
+    install(app: App): void;
+    /** @internal pageI18n's connection: the page payloads, the language switch and the store. */
+    connect(feed: PageFeed, switcher: ((locale: string) => Promise<void>) | undefined, store: StoreHost | undefined): void;
+    /**
+     * @internal The value of X-Dokebi-I18n: the catalog version and the tokens of the bundles this
+     * document holds (the shown locale's first), within the server's header limit.
+     */
+    heldHeader(): string;
+    /** @internal */
+    get cookie(): string | undefined;
+    /** @internal The claim cookie of the store (settings.cache.cookie), if bundles are kept. */
+    get claimCookie(): string | undefined;
+    /** @internal The store, for pageI18n and tests (undefined when nothing is kept). */
+    get store(): BundleStore | undefined;
+    /**
+     * @internal Takes in the `i18n` of a recovery answer (pageI18n's fetch) and checks the shown
+     * page again; true when nothing is missing now.
+     */
+    recovered(payload: PageI18nPayload): boolean;
+}
+/** An I18n for plain Vue apps and tests: the messages are given, nothing is fetched. */
+export declare function createI18n(options: CreateI18nOptions): I18n;
+/**
+ * The page's I18n (from a component's setup). Without the `i18n` prop (no @dokebi/i18n, or
+ * http integration off) it throws UNAVAILABLE; `{ optional: true }` returns undefined instead.
+ */
+export declare function useI18n(): I18n;
+export declare function useI18n(options: {
+    optional: true;
+}): I18n | undefined;
+interface PageLike {
+    readonly props?: Readonly<Record<string, unknown>>;
+    readonly component?: string;
+    readonly version?: string | null;
+    readonly url?: string;
+}
+/**
+ * The Vue plugin of an Inertia app (views/app.js and views/ssr.js install it): translations from
+ * the `i18n` prop of the page being shown (Inertia's `$page`, from `page` until Inertia's plugin
+ * is installed). A new page's messages are taken in where the page first translates, before it
+ * is drawn. With `router` (the browser), every visit names what this document holds (header
+ * X-Dokebi-I18n) so the server sends only what is new, a page whose messages this document never
+ * received is completed with `router.reload({ only: ['i18n'] })`, and switchLocale writes the
+ * preference cookie and reloads the props. In a browser it keeps the bundles it received
+ * (D-0126) when the server allows it, and when a first page lacks some (the server trusted a
+ * cookie the store does not match) it fetches them before `app.mount` mounts the app. Without
+ * the prop it installs nothing, so the same entry works before @dokebi/i18n is added.
+ */
+export declare function pageI18n(page: PageLike | undefined, options?: PageI18nOptions): I18n | {
+    install(_app: App): void;
+};
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        /** `t` of the page's I18n (@dokebi/template-inertia/i18n). */
+        $t: I18n['t'];
+        $n: I18n['n'];
+        $d: I18n['d'];
+        $i18n: I18n;
+    }
+}
+export {};