domma-js 0.56.0 → 0.58.0

package/assets/types/generated/src/globals.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Read a load-time option from `window.DommaOptions`.
+ * @param {keyof DommaLoadOptions} key
+ * @param {*} fallback
+ * @returns {*}
+ */
+export function loadOption(key: keyof DommaLoadOptions, fallback: any): any;
+/**
+ * Install Domma and its aliases on `window`, and attach `Domma.noConflict`.
+ * @param {Function} Domma - The Domma function
+ * @param {Object<string, *>} aliases - Alias name -> value
+ * @returns {Function} Domma
+ */
+export function installGlobals(Domma: Function, aliases: {
+    [x: string]: any;
+}): Function;
+/**
+ * Options read from `window.DommaOptions` when Domma loads - set it before the script tag.
+ */
+export type DommaLoadOptions = {
+    /**
+     * true (default): every alias; 'safe': only aliases nobody else owns; false: window.Domma only
+     */
+    globals?: boolean | "safe";
+    /**
+     * false: never add the `dm-cloaked` class
+     */
+    cloak?: boolean;
+    /**
+     * false: don't initialise the theme engine automatically
+     */
+    theme?: boolean;
+    /**
+     * false: no console warning when DOMPurify is missing
+     */
+    purifyWarning?: boolean;
+    /**
+     * false: no deprecation warnings
+     */
+    deprecationWarnings?: boolean;
+    /**
+     * false: no console warning for a missing translation
+     */
+    i18nWarnings?: boolean;
+};

package/assets/types/generated/src/http.d.ts

@@ -0,0 +1,131 @@
+export namespace http {
+    /**
+     * Make a request with any method.
+     * @template [T=any]
+     * @param {HttpMethod} method HTTP method
+     * @param {string} url Request URL
+     * @param {any} [data] Body - JSON-encoded unless FormData, URLSearchParams, Blob, ArrayBuffer/view or a stream. Not sent for GET/HEAD.
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function request<T = any>(method: HttpMethod, url: string, data?: any, config?: RequestOptions): Promise<T>;
+    /**
+     * Make a GET request.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function get<T = any>(url: string, config?: RequestOptions): Promise<T>;
+    /**
+     * Make a POST request.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {any} [data] Request body (JSON-encoded unless a raw body such as FormData)
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function post<T = any>(url: string, data?: any, config?: RequestOptions): Promise<T>;
+    /**
+     * Make a PUT request.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {any} [data] Request body (JSON-encoded unless a raw body such as FormData)
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function put<T = any>(url: string, data?: any, config?: RequestOptions): Promise<T>;
+    /**
+     * Make a PATCH request.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {any} [data] Request body (JSON-encoded unless a raw body such as FormData)
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function patch<T = any>(url: string, data?: any, config?: RequestOptions): Promise<T>;
+    /**
+     * Make a DELETE request. DELETE sends no body unless one is given as `config.data`.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {DeleteRequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    function _delete<T = any>(url: string, config?: DeleteRequestOptions): Promise<T>;
+    export { _delete as delete };
+    /**
+     * Make a HEAD request.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function head<T = any>(url: string, config?: RequestOptions): Promise<T>;
+    /**
+     * Make a OPTIONS request.
+     * @template [T=any]
+     * @param {string} url Request URL
+     * @param {RequestOptions} [config] Request options
+     * @returns {Promise<T>} The response body
+     */
+    export function options<T = any>(url: string, config?: RequestOptions): Promise<T>;
+}
+/**
+ * Options for a request. Anything not listed by name here is passed to `fetch()` as it is.
+ */
+export type RequestOptions = Omit<RequestInit, "method" | keyof RequestOwnOptions> & RequestOwnOptions;
+/**
+ * The options Domma reads itself (the rest of {@link RequestOptions} goes to `fetch()`).
+ */
+export type RequestOwnOptions = {
+    /**
+     * Request headers (plain object, `Headers` or entry pairs); copied, never mutated.
+     * `Content-Type: application/json` is added for a JSON body unless one is given.
+     */
+    headers?: HeadersInit;
+    /**
+     * Do not log a failure to the console (useful for expected errors such as a 401 check).
+     */
+    silent?: boolean;
+    /**
+     * Abort after this many milliseconds (rejects with a `TimeoutError`).
+     */
+    timeout?: number;
+    /**
+     * Defaults to `'same-origin'`; pass `'include'` to send cookies cross-origin.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Abort signal, composed with `timeout` (whichever fires first aborts).
+     */
+    signal?: AbortSignal;
+    mode?: RequestMode;
+    cache?: RequestCache;
+    redirect?: RequestRedirect;
+    referrer?: string;
+    referrerPolicy?: ReferrerPolicy;
+    integrity?: string;
+    keepalive?: boolean;
+};
+/**
+ * Options for `http.delete()`: a body is sent only when given as `data`.
+ */
+export type DeleteRequestOptions = RequestOptions & {
+    data?: any;
+};
+/**
+ * The error a failed request rejects with: the server's `message` (or `error`) from a JSON body,
+ * otherwise `HTTP Error: <status> <statusText>`.
+ */
+export type HttpError = Error & {
+    status?: number;
+    statusText?: string;
+    body?: any;
+};
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | (string & {});
+/**
+ * Fetch-based HTTP client. Every method resolves to the response BODY (not a response object):
+ * parsed JSON for a JSON or unlabelled body, text for any other type, `null` when there is no body
+ * (204/205/304, HEAD, an empty body). A non-2xx status rejects with an {@link HttpError}.
+ */
+export type Http = typeof http;

package/assets/types/generated/src/i18n.d.ts

@@ -0,0 +1,261 @@
+export namespace i18n {
+    /**
+     * Add messages for a locale. Nested objects become dot keys; later calls merge (a key
+     * already there is replaced, everything else is kept).
+     * @param {string} locale
+     * @param {I18nMessages} source
+     * @returns {I18n} i18n
+     */
+    function add(locale: string, source: I18nMessages): I18n;
+    /**
+     * Load a locale's messages from a JSON URL (via H.get) or a loader function returning a
+     * Promise of messages. The result is cached, and a load already under way is shared, so
+     * calling this from three places makes one request. A failed load is not cached.
+     * `{locale}` in the URL is replaced with the code.
+     * @param {string} locale
+     * @param {string|((locale: string) => Promise<I18nMessages>|I18nMessages)} source - URL, or () => Promise<Object>
+     * @param {{reload?: boolean}} [options]
+     * @returns {Promise<I18nMessages>} The messages loaded
+     */
+    function load(locale: string, source: string | ((locale: string) => Promise<I18nMessages> | I18nMessages), options?: {
+        reload?: boolean;
+    }): Promise<I18nMessages>;
+    /**
+     * Get the current locale.
+     * @overload
+     * @returns {string} The current locale
+     */
+    function locale(): string;
+    /**
+     * Set the locale: fires change, sets <html lang dir>, re-translates the document.
+     * @overload
+     * @param {string} code
+     * @returns {string} The current locale
+     */
+    function locale(code: string): string;
+    /**
+     * Set the fallback locale(s) searched after the current one (and its parent language).
+     * With no argument, returns them.
+     * @param {string|string[]} [codes]
+     * @returns {string[]}
+     */
+    function fallback(codes?: string | string[]): string[];
+    /**
+     * Whether a key has a message in the current locale or its fallbacks.
+     * @param {string} key
+     * @param {{locale?: string}} [options]
+     * @returns {boolean}
+     */
+    function has(key: string, options?: {
+        locale?: string;
+    }): boolean;
+    /**
+     * Translate a key to plain text. Params fill `{name}` placeholders (not escaped - this is
+     * text, not HTML); `count` chooses a plural form. A missing key returns `default` (itself
+     * interpolated) or the key.
+     * @param {string} key
+     * @param {Record<string, any>|null} [params]
+     * @param {I18nTranslateOptions} [options]
+     * @returns {string}
+     */
+    function t(key: string, params?: Record<string, any> | null, options?: I18nTranslateOptions): string;
+    /**
+     * Translate a key to HTML: the message's own markup is kept and every param is escaped.
+     * The message itself is trusted (it is yours); `translate()` sanitises before inserting.
+     * @param {string} key
+     * @param {Record<string, any>|null} [params]
+     * @param {I18nTranslateOptions} [options] - As for t()
+     * @returns {string}
+     */
+    function html(key: string, params?: Record<string, any> | null, options?: I18nTranslateOptions): string;
+    /**
+     * Register the hook for a missing key: fn(key, locale). A string it returns is used as the
+     * translation. Pass null to remove it.
+     * @param {((key: string, locale: string) => string|void)|null} fn
+     * @returns {I18n} i18n
+     */
+    function onMissing(fn: ((key: string, locale: string) => string | void) | null): I18n;
+    /**
+     * @overload
+     * @param {'change'} event
+     * @param {(detail: I18nChangeDetail) => void} fn
+     * @returns {() => void} Unsubscribe
+     */
+    function on(event: "change", fn: (detail: I18nChangeDetail) => void): () => void;
+    /**
+     * @overload
+     * @param {'missing'} event
+     * @param {(detail: I18nMissingDetail) => void} fn
+     * @returns {() => void} Unsubscribe
+     */
+    function on(event: "missing", fn: (detail: I18nMissingDetail) => void): () => void;
+    /**
+     * @overload
+     * @param {'loaded'} event
+     * @param {(detail: I18nLoadedDetail) => void} fn
+     * @returns {() => void} Unsubscribe
+     */
+    function on(event: "loaded", fn: (detail: I18nLoadedDetail) => void): () => void;
+    /**
+     * Unsubscribe (with no fn, every listener for that event).
+     * @param {'change'|'missing'|'loaded'} event
+     * @param {(...args: any[]) => void} [fn]
+     * @returns {I18n} i18n
+     */
+    function off(event: "change" | "missing" | "loaded", fn?: (...args: any[]) => void): I18n;
+    /** @returns {string[]} Locales that have messages */
+    function locales(): string[];
+    /**
+     * Text direction of a locale: 'rtl' or 'ltr'.
+     * @param {string} [code] - Defaults to the current locale
+     * @returns {'rtl'|'ltr'}
+     */
+    function dir(code?: string): "rtl" | "ltr";
+    /**
+     * Fill translations in the DOM: `[data-i18n]` (textContent), `[data-i18n-html]` (sanitised
+     * HTML), `[data-i18n-attr="placeholder:key; title:key2"]`, each taking params from
+     * `data-i18n-params` (JSON). What the page first said is kept and shown when a key is
+     * missing, so authored text doubles as the default. Call it on content you add later.
+     * @param {Element|Document|string|ArrayLike<Element>} [root=document] - Element, selector or Domma collection
+     * @returns {number} Elements translated
+     */
+    function translate(root?: Element | Document | string | ArrayLike<Element>): number;
+    /**
+     * Pick a locale from storage, the browser and/or `<html lang>`, in the order given, set
+     * it, and return it. With `storageKey`, the choice (and every later `locale(code)`) is
+     * kept in S under that key. With `supported`, only those (or their base language) count.
+     * @param {I18nDetectOptions} [options]
+     * @returns {string}
+     */
+    function detect(options?: I18nDetectOptions): string;
+    /**
+     * @param {number|bigint} n
+     * @param {WithLocale<Intl.NumberFormatOptions>} [opts]
+     * @returns {string}
+     */
+    function number(n: number | bigint, opts?: WithLocale<Intl.NumberFormatOptions>): string;
+    /**
+     * @param {number|bigint} n
+     * @param {string} code - ISO 4217 currency, e.g. 'GBP'
+     * @param {WithLocale<Intl.NumberFormatOptions>} [opts]
+     * @returns {string}
+     */
+    function currency(n: number | bigint, code: string, opts?: WithLocale<Intl.NumberFormatOptions>): string;
+    /**
+     * Format a date. Accepts a Date, timestamp, date string or a D() wrapper.
+     * An invalid date formats as ''.
+     * @param {Date|number|string|{toDate(): Date}} d
+     * @param {WithLocale<Intl.DateTimeFormatOptions>} [opts]
+     * @returns {string}
+     */
+    function date(d: Date | number | string | {
+        toDate(): Date;
+    }, opts?: WithLocale<Intl.DateTimeFormatOptions>): string;
+    /**
+     * "in 3 days", "2 hours ago" - Intl.RelativeTimeFormat.
+     * @param {number} value - Negative for the past
+     * @param {Intl.RelativeTimeFormatUnit} unit - 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
+     * @param {WithLocale<Intl.RelativeTimeFormatOptions>} [opts]
+     * @returns {string}
+     */
+    function relative(value: number, unit: Intl.RelativeTimeFormatUnit, opts?: WithLocale<Intl.RelativeTimeFormatOptions>): string;
+    /**
+     * "a, b and c" - Intl.ListFormat.
+     * @param {Iterable<string>} items
+     * @param {WithLocale<{type?: 'conjunction'|'disjunction'|'unit', style?: 'long'|'short'|'narrow'}>} [opts] - Intl.ListFormat options plus `locale`
+     * @returns {string}
+     */
+    function list(items: Iterable<string>, opts?: WithLocale<{
+        type?: "conjunction" | "disjunction" | "unit";
+        style?: "long" | "short" | "narrow";
+    }>): string;
+    /**
+     * Forget every message, load, listener, hook and setting (tests, or a full reload).
+     * @returns {I18n} i18n
+     */
+    function reset(): I18n;
+}
+export default i18n;
+/**
+ * A plural message: chosen by `params.count`; `=N` keys match exactly, `zero` matches 0.
+ * `ordinal: true` uses ordinal rules (1st, 2nd, 3rd...).
+ */
+export type I18nPluralForms = {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+    ordinal?: boolean;
+    [exact: `=${number}`]: string;
+};
+/**
+ * A select message: `select` names the param whose value picks the form; `other` otherwise.
+ */
+export type I18nSelectForms = {
+    select: string;
+    other: string;
+    [value: string]: string;
+};
+/**
+ * Nested message tree; nesting becomes dot keys.
+ */
+export type I18nMessages = {
+    [key: string]: string | number | boolean | I18nPluralForms | I18nSelectForms | I18nMessages;
+};
+export type I18nTranslateOptions = {
+    /**
+     * Translate in this locale instead of the current one
+     */
+    locale?: string;
+    /**
+     * Returned (interpolated) when the key is missing, instead of the key
+     */
+    default?: string;
+    /**
+     * Choose plural forms by ordinal rules
+     */
+    ordinal?: boolean;
+};
+export type I18nDetectOptions = {
+    /**
+     * Sources in order. Default ['storage', 'navigator', 'html']
+     */
+    from?: Array<"storage" | "navigator" | "html">;
+    /**
+     * S key: read in 'storage', and every later locale(code) is saved there
+     */
+    storageKey?: string;
+    /**
+     * Only these locales (or their base language) are accepted
+     */
+    supported?: string[];
+    /**
+     * Used when nothing matches (else the current locale stays)
+     */
+    fallback?: string;
+    /**
+     * Set the found locale (default true)
+     */
+    apply?: boolean;
+};
+export type I18nChangeDetail = {
+    locale: string;
+    previous: string;
+};
+export type I18nMissingDetail = {
+    key: string;
+    locale: string;
+};
+export type I18nLoadedDetail = {
+    locale: string;
+    messages: I18nMessages;
+};
+/**
+ * Formatter options plus an optional `locale` override.
+ */
+export type WithLocale<T> = T & {
+    locale?: string;
+};
+export type I18n = typeof i18n;

package/assets/types/generated/src/icons.d.ts

@@ -0,0 +1,213 @@
+export default icons;
+/**
+ * Built-in icon categories (keys of `listCategories()`); `custom` appears once an icon is registered.
+ */
+export type IconCategory = "ui" | "communication" | "media" | "files" | "social" | "commerce" | "status" | "navigation" | "seasonal" | "weather" | "devices" | "finance" | "health" | "sport" | "buildings" | "emojis" | "transport" | "code" | "forms" | "custom";
+/**
+ * A category entry as returned by `listCategories()`.
+ */
+export type IconCategoryInfo = {
+    /**
+     * Display name
+     */
+    name: string;
+    description: string;
+    /**
+     * Icon names in the category
+     */
+    icons: string[];
+};
+/**
+ * An icon: SVG path data plus the attributes put on the `<svg>`.
+ */
+export type IconDefinition = {
+    /**
+     * SVG viewBox (default '0 0 24 24')
+     */
+    viewBox?: string;
+    /**
+     * Single path data
+     */
+    path?: string;
+    /**
+     * Multiple path data
+     */
+    paths?: string[];
+    /**
+     * Stroke colour (usually 'currentColor')
+     */
+    stroke?: string;
+    /**
+     * Fill colour ('none', or 'currentColor' for filled icons)
+     */
+    fill?: string;
+    /**
+     * Stroke width
+     */
+    strokeWidth?: number | string;
+    strokeLinecap?: string;
+    strokeLinejoin?: string;
+};
+/**
+ * Options for `render()`, `html()` and `use()` (`use()` reads only `size` and `class`).
+ */
+export type RenderOptions = {
+    /**
+     * Icon size in pixels
+     */
+    size?: number | string;
+    /**
+     * Additional CSS classes
+     */
+    class?: string;
+    /**
+     * Icon colour (overrides currentColor)
+     */
+    colour?: string;
+    /**
+     * Alias for colour
+     */
+    color?: string;
+    /**
+     * Additional attributes
+     */
+    attrs?: Record<string, string>;
+};
+/**
+ * Options for `inject()`: render options plus where the icon goes.
+ */
+export type IconInjectOptions = RenderOptions & {
+    position?: "prepend" | "append" | "replace";
+};
+export type Icons = IconRegistry;
+export const icons: IconRegistry;
+/**
+ * Built-in icon categories (keys of `listCategories()`); `custom` appears once an icon is registered.
+ * @typedef {'ui'|'communication'|'media'|'files'|'social'|'commerce'|'status'|'navigation'|'seasonal'|'weather'|'devices'|'finance'|'health'|'sport'|'buildings'|'emojis'|'transport'|'code'|'forms'|'custom'} IconCategory
+ */
+/**
+ * A category entry as returned by `listCategories()`.
+ * @typedef {object} IconCategoryInfo
+ * @property {string} name Display name
+ * @property {string} description
+ * @property {string[]} icons Icon names in the category
+ */
+/**
+ * An icon: SVG path data plus the attributes put on the `<svg>`.
+ * @typedef {object} IconDefinition
+ * @property {string} [viewBox] SVG viewBox (default '0 0 24 24')
+ * @property {string} [path] Single path data
+ * @property {string[]} [paths] Multiple path data
+ * @property {string} [stroke] Stroke colour (usually 'currentColor')
+ * @property {string} [fill] Fill colour ('none', or 'currentColor' for filled icons)
+ * @property {number|string} [strokeWidth] Stroke width
+ * @property {string} [strokeLinecap]
+ * @property {string} [strokeLinejoin]
+ */
+/**
+ * Options for `render()`, `html()` and `use()` (`use()` reads only `size` and `class`).
+ * @typedef {object} RenderOptions
+ * @property {number|string} [size=24] Icon size in pixels
+ * @property {string} [class] Additional CSS classes
+ * @property {string} [colour] Icon colour (overrides currentColor)
+ * @property {string} [color] Alias for colour
+ * @property {Record<string, string>} [attrs] Additional attributes
+ */
+/**
+ * Options for `inject()`: render options plus where the icon goes.
+ * @typedef {RenderOptions & {position?: 'prepend'|'append'|'replace'}} IconInjectOptions
+ */
+/** @typedef {IconRegistry} Icons */
+export class IconRegistry {
+    /** @type {Record<string, IconDefinition>} @private */
+    private _icons;
+    /** @type {Partial<Record<IconCategory, IconCategoryInfo>>} @private */
+    private _categories;
+    /**
+     * Render an icon as an SVG element
+     * @param {string} name - Icon name
+     * @param {RenderOptions} [options] - Render options
+     * @returns {SVGElement|null}
+     */
+    render(name: string, options?: RenderOptions): SVGElement | null;
+    /**
+     * Get icon as HTML string
+     * @param {string} name - Icon name
+     * @param {RenderOptions} [options] - Render options (same as render())
+     * @returns {string}
+     */
+    html(name: string, options?: RenderOptions): string;
+    /**
+     * Inject icon into an element
+     * @param {string|HTMLElement} target - Target element or selector
+     * @param {string} name - Icon name
+     * @param {IconInjectOptions} [options] - Render options (same as render()), plus `position`: 'prepend' (default), 'append', or 'replace'
+     * @returns {SVGElement|null}
+     */
+    inject(target: string | HTMLElement, name: string, options?: IconInjectOptions): SVGElement | null;
+    /**
+     * Scan document for [data-icon] elements and replace with SVGs
+     * @param {Element|Document|DocumentFragment|string} [container=document] - Container to scan
+     * @returns {number} Number of icons replaced
+     */
+    scan(container?: Element | Document | DocumentFragment | string): number;
+    /**
+     * Register a custom icon
+     * @param {string} name - Icon name
+     * @param {IconDefinition} definition - Icon definition (needs `path` or `paths`; `viewBox` defaults to '0 0 24 24')
+     * @returns {this}
+     */
+    register(name: string, definition: IconDefinition): this;
+    /**
+     * Unregister an icon
+     * @param {string} name - Icon name
+     * @returns {boolean}
+     */
+    unregister(name: string): boolean;
+    /**
+     * Check if an icon exists
+     * @param {string} name - Icon name
+     * @returns {boolean}
+     */
+    has(name: string): boolean;
+    /**
+     * Get icon definition
+     * @param {string} name - Icon name
+     * @returns {IconDefinition|null}
+     */
+    get(name: string): IconDefinition | null;
+    /**
+     * List all icon names
+     * @param {IconCategory|null} [category] - Filter by category
+     * @returns {string[]}
+     */
+    list(category?: IconCategory | null): string[];
+    /**
+     * List all categories
+     * @returns {Partial<Record<IconCategory, IconCategoryInfo>>}
+     */
+    listCategories(): Partial<Record<IconCategory, IconCategoryInfo>>;
+    /**
+     * Get icon count
+     * @returns {number}
+     */
+    count(): number;
+    /**
+     * Search icons by name
+     * @param {string} query - Search query
+     * @returns {string[]}
+     */
+    search(query: string): string[];
+    /**
+     * Create a sprite sheet of all icons (for performance)
+     * @returns {SVGElement}
+     */
+    createSprite(): SVGElement;
+    /**
+     * Use an icon from sprite sheet
+     * @param {string} name - Icon name
+     * @param {RenderOptions} [options] - Render options (`size` and `class`)
+     * @returns {SVGElement|null}
+     */
+    use(name: string, options?: RenderOptions): SVGElement | null;
+}