@texuli/core 0.7.0 → 0.9.0

package/dist/expression/types.js

@@ -0,0 +1,35 @@
+/**
+ * The closed expression language of ADR-015: one JSON AST, one bounded
+ * evaluator. Every node names its operation in `op`. The base is the
+ * blueprint spec's `numberFormula` and `condition` shapes (ADR-008), which
+ * stay valid expressions; the extensions add strings, booleans, null,
+ * field references, calls to a closed function table, and the `ref` and
+ * `range` reference nodes a dialect (the planned sheets formula layer) can
+ * enable. There is no loop, no closure, no dynamic reference and no way to
+ * reach host objects.
+ */
+/** The limits of ADR-015. Exceeding one is a diagnostic at parse time or `#LIMIT!` at run time. */
+export const EXPRESSION_LIMITS = Object.freeze({
+    /** AST nodes per expression. */
+    nodes: 1000,
+    /** Nesting depth per expression. */
+    depth: 32,
+    /** Evaluation steps per expression. */
+    steps: 100_000,
+    /** Evaluation steps per recalculation pass (an `ExpressionBudget`). */
+    passSteps: 10_000_000,
+    /** UTF-16 code units in any string value. */
+    stringLength: 32_768,
+    /** Items in any list value. */
+    listItems: 10_000,
+    /** Characters of expression text the text parser reads. */
+    sourceLength: 16_384,
+    /** Arguments of one `and`, `or`, `min`, `max`, `concat` or `call`. */
+    args: 64,
+    /** Largest absolute `pow` exponent. */
+    exponent: 64,
+    /** `round` digits range (±). */
+    roundDigits: 12,
+});
+/** Field, var and function names: a letter or underscore, then letters, digits or underscores. */
+export const EXPRESSION_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;

package/dist/expression/values.d.ts

@@ -0,0 +1,14 @@
+import { type ExpressionError, type ExpressionErrorCode, type ExpressionValue } from './types.js';
+export declare const ERRORS: Readonly<Record<ExpressionErrorCode, ExpressionError>>;
+/** The (frozen, shared) error value for a code. */
+export declare function expressionError(code: ExpressionErrorCode): ExpressionError;
+/** Whether a value is an error value. */
+export declare function isExpressionError(value: unknown): value is ExpressionError;
+/** Only `true` is true: errors, `null` (unknown) and everything else are not. */
+export declare function isTrue(value: ExpressionValue): boolean;
+export declare const LIMIT: ExpressionError;
+export declare const VALUE: ExpressionError;
+/** Normalize an outside value (an input or a function result) into an expression value. */
+export declare function toExpressionValue(raw: unknown): ExpressionValue;
+/** Rounds half away from zero to `digits` decimals (negative: tens, hundreds…). */
+export declare function roundHalfAway(value: number, digits?: number): number | null;

package/dist/expression/values.js

@@ -0,0 +1,68 @@
+import { EXPRESSION_LIMITS, } from "./types.js";
+/* Values: the error singletons, normalization of outside values and rounding. */
+export const ERRORS = Object.freeze({
+    '#DIV/0!': Object.freeze({ error: '#DIV/0!' }),
+    '#VALUE!': Object.freeze({ error: '#VALUE!' }),
+    '#REF!': Object.freeze({ error: '#REF!' }),
+    '#NAME?': Object.freeze({ error: '#NAME?' }),
+    '#NUM!': Object.freeze({ error: '#NUM!' }),
+    '#N/A': Object.freeze({ error: '#N/A' }),
+    '#CYCLE!': Object.freeze({ error: '#CYCLE!' }),
+    '#LIMIT!': Object.freeze({ error: '#LIMIT!' }),
+});
+/** The (frozen, shared) error value for a code. */
+export function expressionError(code) {
+    return ERRORS[code];
+}
+/** Whether a value is an error value. */
+export function isExpressionError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.error === 'string' &&
+        Object.hasOwn(ERRORS, value.error));
+}
+/** Only `true` is true: errors, `null` (unknown) and everything else are not. */
+export function isTrue(value) {
+    return value === true;
+}
+export const LIMIT = ERRORS['#LIMIT!'];
+export const VALUE = ERRORS['#VALUE!'];
+function scalar(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === 'number')
+        return Number.isFinite(raw) ? (raw === 0 ? 0 : raw) : null;
+    if (typeof raw === 'string')
+        return raw.length > EXPRESSION_LIMITS.stringLength ? LIMIT : raw;
+    if (typeof raw === 'boolean')
+        return raw;
+    if (isExpressionError(raw))
+        return ERRORS[raw.error];
+    return VALUE;
+}
+/** Normalize an outside value (an input or a function result) into an expression value. */
+export function toExpressionValue(raw) {
+    if (!Array.isArray(raw))
+        return scalar(raw);
+    if (raw.length > EXPRESSION_LIMITS.listItems)
+        return LIMIT;
+    const out = [];
+    for (const item of raw) {
+        const value = scalar(item);
+        if (isExpressionError(value))
+            return value;
+        out.push(value);
+    }
+    return Object.freeze(out);
+}
+/** Rounds half away from zero to `digits` decimals (negative: tens, hundreds…). */
+export function roundHalfAway(value, digits = 0) {
+    const factor = 10 ** Math.abs(digits);
+    const scaled = digits >= 0 ? Math.abs(value) * factor : Math.abs(value) / factor;
+    const rounded = Math.round(scaled + scaled * Number.EPSILON);
+    const result = Math.sign(value) * (digits >= 0 ? rounded / factor : rounded * factor);
+    if (!Number.isFinite(result))
+        return null;
+    return result === 0 ? 0 : result;
+}

package/dist/i18n/catalog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Message catalogs (ADR-016): `{ locale, messages }`, where each message id
+ * is namespaced (`texuli.dialog.close`) and maps to a `Message`. Catalogs
+ * may come from untrusted JSON (a translation file a host loads), so
+ * `parseCatalog` checks every id, message and size and copies the result
+ * into a prototype-free map.
+ */
+import type { Message } from './format.js';
+export interface MessageCatalog {
+    /** A BCP 47 language tag, such as `en`, `pt-BR` or the pseudo-locale `en-XA`. */
+    readonly locale: string;
+    readonly messages: Readonly<Record<string, Message>>;
+}
+export interface CatalogIssue {
+    /** The message id, or `''` for the catalog itself. */
+    id: string;
+    message: string;
+}
+export interface CatalogParse {
+    /** The checked catalog (only its valid messages), or `null` when the catalog itself is unusable. */
+    catalog: MessageCatalog | null;
+    issues: CatalogIssue[];
+}
+/** Caps for `parseCatalog`. */
+export declare const CATALOG_LIMITS: Readonly<{
+    /** Messages in one catalog. */
+    messages: 5000;
+    /** Characters in one message string or plural or select case. */
+    messageLength: 2000;
+    /** Cases in one plural or select message. */
+    cases: 16;
+}>;
+/** A message id: two or more dot-separated segments of letters, digits and `-`, at most 128 characters. */
+export declare const MESSAGE_ID: RegExp;
+/** A BCP 47-like tag: letters and digits in `-` separated subtags (`en`, `pt-BR`, `zh-Hant-TW`, `en-XA`). */
+export declare const LOCALE_TAG: RegExp;
+export type MessageCheck = {
+    ok: true;
+    message: Message;
+} | {
+    ok: false;
+    reason: string;
+};
+/** A checked, frozen copy of one message, or the reason it is refused. */
+export declare function checkMessage(value: unknown): MessageCheck;
+/**
+ * Check an untrusted catalog: the locale tag, every id (`MESSAGE_ID`), every
+ * message and the caps in `CATALOG_LIMITS`. Invalid messages are dropped
+ * with an issue; the rest are kept. Never throws.
+ */
+export declare function parseCatalog(input: unknown): CatalogParse;

package/dist/i18n/catalog.js

@@ -0,0 +1,109 @@
+/** Caps for `parseCatalog`. */
+export const CATALOG_LIMITS = Object.freeze({
+    /** Messages in one catalog. */
+    messages: 5_000,
+    /** Characters in one message string or plural or select case. */
+    messageLength: 2_000,
+    /** Cases in one plural or select message. */
+    cases: 16,
+});
+/** A message id: two or more dot-separated segments of letters, digits and `-`, at most 128 characters. */
+export const MESSAGE_ID = /^[A-Za-z0-9-]{1,48}(?:\.[A-Za-z0-9-]{1,48}){1,6}$/;
+/** A BCP 47-like tag: letters and digits in `-` separated subtags (`en`, `pt-BR`, `zh-Hant-TW`, `en-XA`). */
+export const LOCALE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8}){0,4}$/;
+const PLURAL_KEYS = new Set(['plural', 'other', 'zero', 'one', 'two', 'few', 'many']);
+const EXACT_KEY = /^=\d{1,9}$/;
+const CASE_KEY = /^[A-Za-z0-9_-]{1,48}$/;
+const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype']);
+function isRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+function checkString(value) {
+    return typeof value === 'string' && value.length <= CATALOG_LIMITS.messageLength;
+}
+const refuse = (reason) => ({ ok: false, reason });
+/** A checked, frozen copy of one message, or the reason it is refused. */
+export function checkMessage(value) {
+    if (typeof value === 'string') {
+        return value.length <= CATALOG_LIMITS.messageLength
+            ? { ok: true, message: value }
+            : refuse('the message is too long');
+    }
+    if (!isRecord(value))
+        return refuse('a message is a string, or a plural or select object');
+    const keys = Object.keys(value);
+    if (keys.length > CATALOG_LIMITS.cases + 1)
+        return refuse('the message has too many cases');
+    const isPlural = typeof value.plural === 'string';
+    const isSelect = typeof value.select === 'string';
+    if (isPlural === isSelect) {
+        return refuse('a message object has exactly one of `plural` or `select`');
+    }
+    if (!checkString(value.other))
+        return refuse('a plural or select message needs an `other` string');
+    const out = Object.create(null);
+    for (const key of keys) {
+        if (FORBIDDEN.has(key))
+            return refuse(`the case \`${key}\` is not allowed`);
+        const text = value[key];
+        if (!checkString(text)) {
+            return refuse(`the case \`${key}\` is not a string of at most ${CATALOG_LIMITS.messageLength} characters`);
+        }
+        if (key === 'plural' || key === 'select') {
+            if (!CASE_KEY.test(text))
+                return refuse(`\`${key}\` names a value: letters, digits, \`_\` or \`-\``);
+        }
+        else if (isPlural ? !PLURAL_KEYS.has(key) && !EXACT_KEY.test(key) : !CASE_KEY.test(key)) {
+            return refuse(`the case \`${key}\` is not allowed`);
+        }
+        out[key] = text;
+    }
+    return { ok: true, message: Object.freeze(out) };
+}
+/**
+ * Check an untrusted catalog: the locale tag, every id (`MESSAGE_ID`), every
+ * message and the caps in `CATALOG_LIMITS`. Invalid messages are dropped
+ * with an issue; the rest are kept. Never throws.
+ */
+export function parseCatalog(input) {
+    const issues = [];
+    if (!isRecord(input)) {
+        return { catalog: null, issues: [{ id: '', message: 'a catalog is an object' }] };
+    }
+    const locale = input.locale;
+    if (typeof locale !== 'string' || !LOCALE_TAG.test(locale)) {
+        issues.push({ id: '', message: 'the catalog needs a BCP 47 `locale`' });
+        return { catalog: null, issues };
+    }
+    if (!isRecord(input.messages)) {
+        issues.push({ id: '', message: 'the catalog needs a `messages` object' });
+        return { catalog: null, issues };
+    }
+    const ids = Object.keys(input.messages);
+    if (ids.length > CATALOG_LIMITS.messages) {
+        issues.push({
+            id: '',
+            message: `the catalog has more than ${CATALOG_LIMITS.messages} messages`,
+        });
+        return { catalog: null, issues };
+    }
+    const messages = Object.create(null);
+    for (const id of ids) {
+        if (!MESSAGE_ID.test(id)) {
+            if (issues.length < 50)
+                issues.push({ id, message: 'not a namespaced message id' });
+            continue;
+        }
+        const checked = checkMessage(input.messages[id]);
+        if (!checked.ok) {
+            if (issues.length < 50)
+                issues.push({ id, message: checked.reason });
+            continue;
+        }
+        messages[id] = checked.message;
+    }
+    return { catalog: Object.freeze({ locale, messages: Object.freeze(messages) }), issues };
+}

package/dist/i18n/format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Message formatting for `@texuli/core/i18n` (ADR-016): `{name}`
+ * placeholders, and plural or select objects resolved through
+ * `Intl.PluralRules`. One left-to-right pass, no recursion: a substituted
+ * value is never scanned again, so a value that contains `{name}` stays
+ * literal text. Output is always a string (text, never markup).
+ */
+/** A plural message: `#` in a case is the formatted count. `=0`, `=1`… match exact counts first. */
+export interface PluralMessage {
+    readonly plural: string;
+    readonly other: string;
+    readonly zero?: string;
+    readonly one?: string;
+    readonly two?: string;
+    readonly few?: string;
+    readonly many?: string;
+    readonly [exact: `=${number}`]: string | undefined;
+}
+/** A select message: the case named by the value of `select`, else `other`. */
+export interface SelectMessage {
+    readonly select: string;
+    readonly other: string;
+    readonly [value: string]: string;
+}
+/** A message: a string with `{name}` placeholders, or a plural or select object of such strings. */
+export type Message = string | PluralMessage | SelectMessage;
+/** Values a message substitutes. Strings are inserted as is; numbers are formatted for the locale. */
+export type MessageValues = Readonly<Record<string, string | number>>;
+/**
+ * Substitute `{name}` placeholders in one pass. An unknown or malformed
+ * placeholder stays literal; `count` (when given) replaces a bare `#`.
+ */
+export declare function interpolate(template: string, values: MessageValues | undefined, locale?: string, count?: string): string;
+/**
+ * The small English-path formatter: `{name}` placeholders only, values
+ * inserted with `String()`, unknown names left as written. One regex pass
+ * with a bounded name, so it is linear and never rescans a value.
+ */
+export declare function fillPlaceholders(template: string, values?: MessageValues): string;
+/** Format one message for `locale`. A malformed message formats as the empty string. */
+export declare function formatMessage(message: Message, values?: MessageValues, locale?: string): string;

package/dist/i18n/format.js

@@ -0,0 +1,117 @@
+/**
+ * Message formatting for `@texuli/core/i18n` (ADR-016): `{name}`
+ * placeholders, and plural or select objects resolved through
+ * `Intl.PluralRules`. One left-to-right pass, no recursion: a substituted
+ * value is never scanned again, so a value that contains `{name}` stays
+ * literal text. Output is always a string (text, never markup).
+ */
+/** A placeholder name: letters, digits, `_`, `-` and `.`, at most 64 characters. */
+const NAME = /^[A-Za-z0-9_.-]{1,64}$/;
+const numberFormats = new Map();
+const pluralRules = new Map();
+function cached(cache, locale, make) {
+    if (cache.has(locale))
+        return cache.get(locale) ?? null;
+    let value = null;
+    try {
+        value = make();
+    }
+    catch {
+        value = null;
+    }
+    if (cache.size > 64)
+        cache.clear();
+    cache.set(locale, value);
+    return value;
+}
+function formatNumber(value, locale) {
+    if (!Number.isFinite(value))
+        return String(value);
+    const format = cached(numberFormats, locale, () => new Intl.NumberFormat(locale));
+    return format ? format.format(value) : String(value);
+}
+function valueText(value, locale) {
+    if (typeof value === 'number')
+        return formatNumber(value, locale);
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Substitute `{name}` placeholders in one pass. An unknown or malformed
+ * placeholder stays literal; `count` (when given) replaces a bare `#`.
+ */
+export function interpolate(template, values, locale = 'en', count) {
+    if (template.indexOf('{') === -1 && (count === undefined || template.indexOf('#') === -1)) {
+        return template;
+    }
+    let out = '';
+    let index = 0;
+    while (index < template.length) {
+        const char = template[index];
+        if (char === '#' && count !== undefined) {
+            out += count;
+            index += 1;
+            continue;
+        }
+        if (char === '{') {
+            // Names are short: look at most 65 characters ahead, so a run of `{` stays linear.
+            const close = template.slice(index + 1, index + 66).indexOf('}') + index + 1;
+            if (close > index) {
+                const name = template.slice(index + 1, close);
+                const text = NAME.test(name) ? valueText(values?.[name], locale) : undefined;
+                if (text !== undefined) {
+                    out += text;
+                    index = close + 1;
+                    continue;
+                }
+            }
+        }
+        out += char;
+        index += 1;
+    }
+    return out;
+}
+/**
+ * The small English-path formatter: `{name}` placeholders only, values
+ * inserted with `String()`, unknown names left as written. One regex pass
+ * with a bounded name, so it is linear and never rescans a value.
+ */
+export function fillPlaceholders(template, values) {
+    if (!values || template.indexOf('{') === -1)
+        return template;
+    return template.replace(/\{([A-Za-z0-9_.-]{1,64})\}/g, (match, name) => Object.hasOwn(values, name) ? String(values[name]) : match);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function caseText(message, key) {
+    if (!Object.hasOwn(message, key))
+        return undefined;
+    const value = message[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/** Format one message for `locale`. A malformed message formats as the empty string. */
+export function formatMessage(message, values, locale = 'en') {
+    if (typeof message === 'string')
+        return interpolate(message, values, locale);
+    if (!isRecord(message))
+        return '';
+    const other = caseText(message, 'other') ?? '';
+    if (typeof message.plural === 'string') {
+        const raw = values?.[message.plural];
+        const count = typeof raw === 'number' ? raw : Number(raw);
+        if (!Number.isFinite(count))
+            return interpolate(other, values, locale);
+        const exact = caseText(message, `=${count}`);
+        const rules = cached(pluralRules, locale, () => new Intl.PluralRules(locale));
+        const category = rules ? rules.select(count) : count === 1 ? 'one' : 'other';
+        const chosen = exact ?? caseText(message, category) ?? other;
+        return interpolate(chosen, values, locale, formatNumber(count, locale));
+    }
+    if (typeof message.select === 'string') {
+        const raw = values?.[message.select];
+        const key = raw === undefined ? '' : String(raw);
+        const chosen = key !== '' && key !== 'select' && key !== 'other' ? (caseText(message, key) ?? other) : other;
+        return interpolate(chosen, values, locale);
+    }
+    return '';
+}

package/dist/i18n/i18n.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The message runtime (ADR-016). An `I18n` holds the catalogs of the
+ * locales it has loaded, loads a locale lazily the first time it becomes
+ * active (`registerLocale(locale, () => import('./pt-BR.js'))`), and
+ * resolves an id against the active locale, then its base language
+ * (`pt-BR` → `pt`), then the English default the component passes. It is
+ * framework-free: components read it from context (`I18N_CONTEXT`) and
+ * re-read their labels when `subscribe` reports a change.
+ */
+import { type CatalogIssue, type MessageCatalog } from './catalog.js';
+import { type Message, type MessageValues } from './format.js';
+/** What a lazy locale loader resolves to: a catalog, or a module whose default export is one. */
+export type LocaleLoader = () => Promise<MessageCatalog | {
+    default: MessageCatalog;
+}>;
+/** The context key components read an `I18n` from (`setContext(I18N_CONTEXT, i18n)`); one per realm. */
+export declare const I18N_CONTEXT: unique symbol;
+/** The pseudo-locale (`en-XA`): every resolved string is accented and bracketed, so unlocalized text stands out. */
+export declare const PSEUDO_LOCALE = "en-XA";
+export interface I18nOptions {
+    /** The active locale. Default `en`. */
+    locale?: string;
+    /** Catalogs available at once (no loading). */
+    catalogs?: readonly MessageCatalog[];
+    /** Lazy loaders by locale; only the active locale loads. */
+    loaders?: Readonly<Record<string, LocaleLoader>>;
+    /** Called with the issues of a loaded catalog that `parseCatalog` reported, or a load failure. */
+    onIssues?: (locale: string, issues: readonly CatalogIssue[]) => void;
+}
+/** Resolve a message id to text. */
+export type Translate = (id: string, english: Message, values?: MessageValues) => string;
+export interface I18n {
+    /** The active locale. Changes only once its catalog is loaded. */
+    readonly locale: string;
+    /** Bumped on every change (locale switch, catalog added); handy as a reactive key. */
+    readonly version: number;
+    /** Resolve `id` (active locale, then base language), else format `english`. */
+    t: Translate;
+    /** Whether the active locale (or its base language) has `id`. */
+    has(id: string): boolean;
+    /** Load (if needed) and activate `locale`. Resolves `false` when it could not load (the locale stays). */
+    setLocale(locale: string): Promise<boolean>;
+    /** Register a lazy loader. Loading happens when the locale becomes active. */
+    registerLocale(locale: string, loader: LocaleLoader): void;
+    /** Add or merge a catalog (checked with `parseCatalog`); returns its issues. */
+    addCatalog(catalog: MessageCatalog | unknown): readonly CatalogIssue[];
+    /** Listen for changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/** Create a message runtime. Never throws on bad catalogs; bad messages are dropped with issues. */
+export declare function createI18n(options?: I18nOptions): I18n;
+/**
+ * The resolution order for one label (ADR-016): the instance prop when the
+ * caller set one, then the catalog from context, then the English default.
+ */
+export declare function resolveLabel(instance: string | null | undefined, i18n: Pick<I18n, 't'> | null | undefined, id: string, english: Message, values?: MessageValues): string;
+/** The English-only `Translate`: what components use with no `I18n` in context. */
+export declare const englishMessages: Translate;
+/** A `Translate` that can also tell whether the catalog has an id (what components get from context). */
+export type MessageLookup = Translate & {
+    has?: (id: string) => boolean;
+};
+/**
+ * Resolve a component's English label object through the catalog: every
+ * string label becomes `messages(`${prefix}.${kebab(key)}`, english)`. A
+ * function label (`remove: (tag) => …`) stays as is unless the catalog has
+ * its id, whose message then receives the arguments as `{0}`, `{1}`…
+ * Callers spread their instance overrides on top (the instance prop wins).
+ */
+export declare function localizeLabels<T extends object>(messages: MessageLookup, prefix: string, defaults: T): T;