@fusion.dev/helix-core 0.147.0 → 0.149.0

package/dist/words/message.js

@@ -0,0 +1,152 @@
+import { formatNumber } from '../utils/number-format/number-format.js';
+const parsed = new Map();
+const WORD = /\s*([^\s,{}]+)\s*/y;
+const SPACE = /\s*/y;
+const parse = (source) => {
+    let at = 0;
+    const fail = () => {
+        throw at;
+    };
+    const match = (pattern) => {
+        pattern.lastIndex = at;
+        const found = pattern.exec(source) ?? fail();
+        at = pattern.lastIndex;
+        return found[1];
+    };
+    const take = (char) => {
+        if (source[at++] !== char) {
+            fail();
+        }
+    };
+    const text = (plural) => {
+        const parts = [];
+        let written = '';
+        const flush = () => {
+            if (written) {
+                parts.push(written);
+            }
+            written = '';
+        };
+        for (let char = source[at]; char && char !== '}'; char = source[at]) {
+            const next = source[++at];
+            if (char === "'" && next === "'") {
+                written += char;
+                at++;
+            }
+            else if (char === "'" && (next === '{' || next === '}' || (plural && next === '#'))) {
+                while (at < source.length) {
+                    const quoted = source[at++];
+                    if (quoted === "'") {
+                        if (source[at] !== "'") {
+                            break;
+                        }
+                        at++;
+                    }
+                    written += quoted;
+                }
+            }
+            else if (char === '#' && plural) {
+                flush();
+                parts.push(0);
+            }
+            else if (char === '{') {
+                flush();
+                parts.push(argument(plural));
+            }
+            else {
+                written += char;
+            }
+        }
+        flush();
+        return parts;
+    };
+    const argument = (plural) => {
+        const found = { n: match(WORD) };
+        if (source[at] !== '}') {
+            take(',');
+            const type = match(WORD);
+            found.t = type;
+            if (source[at] !== '}') {
+                take(',');
+                if (type !== 'plural' && type !== 'selectordinal' && type !== 'select') {
+                    const end = source.indexOf('}', at);
+                    found.s = source.slice(at, end < 0 ? fail() : end).trim();
+                    at = end;
+                }
+                else {
+                    const branches = {};
+                    found.b = branches;
+                    while (source[at] !== '}') {
+                        let key = match(WORD);
+                        if (key.startsWith('offset:')) {
+                            found.o = Number(key.slice(7) || match(WORD));
+                            key = match(WORD);
+                        }
+                        take('{');
+                        branches[key] = text(type !== 'select' || plural);
+                        take('}');
+                        match(SPACE);
+                    }
+                }
+            }
+        }
+        at++;
+        return found;
+    };
+    try {
+        const parts = text(false);
+        return at < source.length ? fail() : parts;
+    }
+    catch {
+        return [source];
+    }
+};
+const rules = new Map();
+const STYLES = {
+    integer: { maximumFractionDigits: 0 },
+    percent: { style: 'percent' },
+};
+export const formatMessage = (message, values, locale, options = {}) => {
+    let parts = parsed.get(message);
+    if (!parts) {
+        parts = parse(message);
+        parsed.set(message, parts);
+    }
+    const plurals = options.plurals ?? locale;
+    const isolated = (text) => (options.isolate ? `\u2068${text}\u2069` : text);
+    const run = (from, count) => from
+        .map((part) => {
+        if (typeof part === 'string') {
+            return part;
+        }
+        if (part === 0) {
+            return formatNumber(count, locale);
+        }
+        const { b: branches, n: name, t: type } = part;
+        const value = values[name];
+        if (value === undefined) {
+            return `{${name}}`;
+        }
+        if (type === 'number' || (!type && typeof value === 'number')) {
+            return isolated(formatNumber(+value, locale, STYLES[part.s]));
+        }
+        if (!branches) {
+            return isolated(String(value));
+        }
+        if (type === 'select') {
+            return run(branches[value] ?? branches.other ?? [], count);
+        }
+        const shifted = +value - (part.o ?? 0);
+        const key = `${plurals}|${type}`;
+        let rule = rules.get(key);
+        if (!rule) {
+            rule = new Intl.PluralRules(plurals || undefined, {
+                type: type === 'plural' ? 'cardinal' : 'ordinal',
+            });
+            rules.set(key, rule);
+        }
+        return run(branches[`=${value}`] ?? branches[rule.select(shifted)] ?? branches.other ?? [], shifted);
+    })
+        .join('');
+    return run(parts, 0);
+};

package/dist/words/registry.d.ts

@@ -0,0 +1,89 @@
+import type { Message, MessageTable } from './message.js';
+/**
+ * The words of every family, keyed by the family's styled tag, each with its
+ * word properties.
+ *
+ * Empty here. The styled and headless packages fill it from their manifests,
+ * in `types/words.d.ts`, and an element of your own adds its tag the same way:
+ *
+ * ```ts
+ * declare module '@fusion.dev/helix-core' {
+ *   interface HelixWords {
+ *     'my-uploader': { dropLabel: Message }
+ *   }
+ * }
+ * ```
+ */
+export interface HelixWords {
+}
+/**
+ * Words for one locale, by tag and property. A tag that `HelixWords` names is
+ * checked against it, and any other tag takes any words.
+ */
+export type Words = {
+    readonly [T in keyof HelixWords]?: Readonly<Partial<HelixWords[T]>>;
+} & {
+    readonly [tag: string]: Readonly<Record<string, Message | MessageTable>> | undefined;
+};
+/**
+ * Adds words for a locale, merged over the words already registered for it.
+ * Elements on the page update once, in a microtask.
+ *
+ * `locale` is a BCP 47 tag. Name a pack by its full tag where a language has
+ * regional forms, such as `pt-BR`, `pt-PT` and `es-419`. A word table, such
+ * as Color Picker's `colorWords`, merges entry by entry.
+ *
+ * ```js
+ * registerWords('de', { 'helix-combobox': { emptyText: 'Keine Treffer' } })
+ * ```
+ */
+export declare const registerWords: (locale: string, ...words: Words[]) => void;
+/** Removes a locale's words, or every locale's where no locale is given. */
+export declare const clearWords: (locale?: string) => void;
+/**
+ * Sets the locale an element speaks on a server, and in its first render
+ * while it hydrates, where neither its `locale` nor its own `lang` says.
+ * Defaults to `en`.
+ *
+ * **Process-wide**, so it suits a server that renders one language. A server
+ * that renders several sets `lang` or `locale` on the elements.
+ */
+export declare const setDefaultWordsLocale: (locale: string) => void;
+/** The locale set with `setDefaultWordsLocale`. */
+export declare const defaultWordsLocale: () => string;
+/**
+ * Asks every element that reads words to update, after an ancestor's `lang`
+ * changes. A change to the document's own `lang` is watched for you.
+ */
+export declare const refreshWords: () => void;
+/**
+ * The locales a word is looked for in, most specific first, ending in `en`.
+ *
+ * **The script comes before the bare language**, so Hong Kong (`zh-HK`)
+ * reaches a Traditional Chinese pack (`zh-Hant`) before a `zh` pack, which is
+ * usually Simplified. Unicode extensions are dropped, and a tag `Intl` refuses
+ * falls straight to `en`.
+ *
+ * `de-CH` tries `de-ch`, `de-latn-ch`, `de-latn`, `de`, then `en`.
+ */
+export declare const localeChain: (locale: string) => string[];
+/** Whether any words are registered, for a read that can skip the lookup. */
+export declare const wordsRegistered: () => boolean;
+/**
+ * A registered word for a tag's property in a locale, with the locale it was
+ * found in, or `undefined`.
+ *
+ * **Per key, along the chain.** A `de-CH` pack that holds only the Swiss
+ * spellings falls through to `de` for every other word. A word table merges
+ * along the chain, the more specific entry winning.
+ */
+export declare const lookupWord: (locale: string, tag: string, name: string) => [Message | MessageTable, string] | undefined;
+/**
+ * Calls `watcher` once in the microtask after words are registered or
+ * cleared, or the document's `lang` changes. Returns the function that stops
+ * it.
+ *
+ * The first watcher in a browser starts watching the document's `lang`, once
+ * for the page.
+ */
+export declare const watchWords: (watcher: () => void) => (() => void);

package/dist/words/registry.js

@@ -0,0 +1,101 @@
+const held = (globalThis[Symbol.for('helix.words')] ??= {
+    fallback: 'en',
+    packs: new Map(),
+    watchers: new Set(),
+});
+const changed = () => {
+    if (!held.queued) {
+        held.queued = true;
+        queueMicrotask(() => {
+            held.queued = false;
+            for (const watcher of held.watchers) {
+                watcher();
+            }
+        });
+    }
+};
+export const registerWords = (locale, ...words) => {
+    const key = locale.toLowerCase();
+    const pack = held.packs.get(key) ?? {};
+    held.packs.set(key, pack);
+    for (const one of words) {
+        for (const tag in one) {
+            const into = (pack[tag] ??= {});
+            for (const [name, value] of Object.entries(one[tag] ?? {})) {
+                const before = into[name];
+                into[name] =
+                    typeof value === 'object' && typeof before === 'object' ? { ...before, ...value } : value;
+            }
+        }
+    }
+    changed();
+};
+export const clearWords = (locale) => {
+    if (locale === undefined) {
+        held.packs.clear();
+    }
+    else {
+        held.packs.delete(locale.toLowerCase());
+    }
+    changed();
+};
+export const setDefaultWordsLocale = (locale) => {
+    held.fallback = locale;
+    changed();
+};
+export const defaultWordsLocale = () => held.fallback;
+export const refreshWords = () => changed();
+const chains = new Map();
+export const localeChain = (locale) => {
+    let found = chains.get(locale);
+    if (found) {
+        return found;
+    }
+    let tags = [];
+    try {
+        const asked = new Intl.Locale(locale);
+        const full = asked.maximize?.();
+        const script = `${full?.language}-${full?.script}`;
+        tags = [
+            asked.baseName,
+            `${script}-${full?.region}`,
+            script,
+            `${asked.language}-${asked.region}`,
+            asked.language,
+        ];
+    }
+    catch {
+    }
+    found = [
+        ...new Set([...tags, 'en']
+            .filter((tag) => tag && !tag.includes('undefined'))
+            .map((tag) => tag.toLowerCase())),
+    ];
+    chains.set(locale, found);
+    return found;
+};
+export const wordsRegistered = () => held.packs.size > 0;
+export const lookupWord = (locale, tag, name) => {
+    let found;
+    for (const one of localeChain(locale)) {
+        const word = held.packs.get(one)?.[tag]?.[name];
+        if (word === undefined) {
+            continue;
+        }
+        if (typeof word === 'string') {
+            return found ?? [word, one];
+        }
+        found = found ? [{ ...word, ...found[0] }, found[1]] : [word, one];
+    }
+    return found;
+};
+export const watchWords = (watcher) => {
+    held.watchers.add(watcher);
+    if (!held.observed && typeof MutationObserver === 'function' && globalThis.document) {
+        held.observed = true;
+        new MutationObserver(changed).observe(document.documentElement, {
+            attributeFilter: ['lang'],
+        });
+    }
+    return () => held.watchers.delete(watcher);
+};

package/dist/words/words-locale.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The locale an element speaks: the one its words, its plural forms, and the
+ * numbers in its sentences are in.
+ *
+ * 1. The element's `locale` property, where it has one and it is set.
+ * 2. On a server, and in the first render while the element hydrates, its own
+ *    `lang` attribute, then the locale set with `setDefaultWordsLocale`, which
+ *    is `en` until you set it. A server knows the element's attributes and
+ *    nothing around it, so a hydrating render reads the same inputs and draws
+ *    what the server drew.
+ * 3. Otherwise, the nearest `lang`, read out through shadow roots, then the
+ *    runtime's own locale.
+ *
+ * **One rule for every family**, so one sentence never mixes the words of one
+ * language with the plural rules or digits of another. A `lang` that names a
+ * bare language the runtime already speaks, such as `en` in a British
+ * browser, is the runtime's locale, as `localeOf` reads it for dates.
+ *
+ * Always a tag `Intl` takes.
+ */
+export declare const wordsLocale: (element: Element & {
+    locale?: string | undefined;
+}) => string;
+/**
+ * The locale an element hands a child that reads only its own `lang` or
+ * `locale`, such as the list inside a combobox: the element's `locale`, or
+ * the nearest `lang` where it names a locale the runtime does not already
+ * speak. Empty where nothing says, so the child keeps the runtime's locale and
+ * gains no attribute, and empty while the element hydrates, as a server could
+ * not have known it.
+ */
+export declare const handedLocale: (element: Element & {
+    locale?: string | undefined;
+}) => string;

package/dist/words/words-locale.js

@@ -0,0 +1,30 @@
+import { localeOf, runtimeLocale } from '../utils/locale-of/locale-of.js';
+import { defaultWordsLocale } from './registry.js';
+const checked = new Map();
+const tagOf = (written) => {
+    let found = checked.get(written);
+    if (found === undefined) {
+        found = '';
+        try {
+            found = Intl.getCanonicalLocales(written)[0] ?? '';
+        }
+        catch {
+        }
+        checked.set(written, found);
+    }
+    return found;
+};
+export const wordsLocale = (element) => {
+    const own = tagOf(element.locale || '');
+    if (own) {
+        return own;
+    }
+    if (typeof element.closest !== 'function' || element.hydrating) {
+        return tagOf(element.getAttribute?.('lang') ?? '') || defaultWordsLocale();
+    }
+    return localeOf(element) || runtimeLocale();
+};
+export const handedLocale = (element) => {
+    const own = typeof element.locale === 'string' ? element.locale : '';
+    return element.hydrating ? own : localeOf(element, own);
+};

package/dist/words/words.d.ts

@@ -0,0 +1,52 @@
+import type { ReactiveElement } from 'lit';
+import { type MessageValues } from './message.js';
+/** An element that reads words: a Lit element, perhaps with a `locale`. */
+type Host = ReactiveElement & {
+    locale?: string | undefined;
+};
+/**
+ * Makes a property a word property: one a page can set, register for a
+ * locale with `registerWords`, or leave in English. Written above
+ * `@property`, which declares its attribute:
+ *
+ * ```ts
+ * static words = 'helix-combobox'
+ *
+ * @words
+ * @property({ attribute: 'empty-text' })
+ * emptyText = 'No matches'
+ * ```
+ *
+ * **Reading the property gives the word in the element's locale**: a value
+ * you set, then the words registered for the element's locale, then the
+ * initializer, which is the English. Setting any value, the English included,
+ * makes it yours. Setting `null` or `undefined`, or removing the attribute,
+ * gives the registry's word back. So does an empty validation message, a
+ * property whose name ends in `Message`: a field never reports a failed check
+ * with no sentence, and a template that renders an empty variable into
+ * `range-overflow-message=""` gets the built-in sentence.
+ *
+ * **A subclass or a family that overrides a word's English writes `@words`
+ * above the override**, and its initializer is the English: a family's
+ * `Remove filter` over a mixin's `Dismiss`. Every `@words` declaration has an
+ * initializer, so an element knows how many of its sets are English.
+ *
+ * The class's static `words` names the key its words are registered under, the
+ * family's styled tag, so the headless and styled tiers share one key. A mixin
+ * that declares words writes `static words = ''`, which its host's key
+ * replaces; a host with no key of its own reads its tag name. An element whose
+ * words change updates once, with each changed property named.
+ */
+export declare const words: (proto: object, name: string) => void;
+/**
+ * A word property of an element, formatted: its values put in, its numbers
+ * written in the element's locale, and its plural forms picked by the rules
+ * of the language its words are in. A property no `@words` declares is
+ * formatted as it reads, with the element's own plural rules.
+ *
+ * ```ts
+ * formatWords(this, 'resultsLabel', { count: 3 }) // '3 results'
+ * ```
+ */
+export declare const formatWords: (host: Host, name: string, values?: MessageValues) => string;
+export {};

package/dist/words/words.js

@@ -0,0 +1,100 @@
+import { formatMessage } from './message.js';
+import { lookupWord, watchWords, wordsRegistered } from './registry.js';
+import { wordsLocale } from './words-locale.js';
+const HELD = Symbol();
+const heldBy = (host) => host[HELD] ?? {};
+const declared = new WeakMap();
+const initializers = (host, name) => {
+    let count = 0;
+    for (let proto = Object.getPrototypeOf(host); proto; proto = Object.getPrototypeOf(proto)) {
+        count += declared.get(proto)?.has(name) ? 1 : 0;
+    }
+    return count;
+};
+const resolve = (host, name) => {
+    const word = heldBy(host)[name];
+    if (!word) {
+        return [host[name], ''];
+    }
+    const { e: english, o: own } = word;
+    const table = typeof english === 'object' && english;
+    let found = [own, ''];
+    if (own == null || table) {
+        const registered = wordsRegistered()
+            ? lookupWord(wordsLocale(host), host.constructor.words || host.localName, name)
+            : undefined;
+        found = table
+            ? [{ ...table, ...registered?.[0], ...own }, '']
+            : (registered ?? [english, 'en']);
+    }
+    word.l = found[0];
+    return found;
+};
+const same = (one, two) => one === two || JSON.stringify(one) === JSON.stringify(two);
+const recheck = (host) => {
+    for (const [name, word] of Object.entries(heldBy(host))) {
+        const before = word.l;
+        if ('l' in word && !same(before, resolve(host, name)[0])) {
+            host.requestUpdate(name, before);
+        }
+    }
+};
+const watcher = (host) => {
+    let stop;
+    let locale = '';
+    return {
+        hostConnected: () => {
+            locale = wordsLocale(host);
+            stop = watchWords(() => {
+                recheck(host);
+                const now = wordsLocale(host);
+                if (now !== locale) {
+                    locale = now;
+                    host.requestUpdate();
+                }
+            });
+        },
+        hostDisconnected: () => stop?.(),
+        hostUpdated: () => {
+            if (host.hydrating === true) {
+                queueMicrotask(() => recheck(host));
+            }
+        },
+    };
+};
+export const words = (proto, name) => {
+    if (!Object.getOwnPropertyDescriptor(proto, name)) {
+        ;
+        proto.constructor.createProperty(name);
+    }
+    const names = declared.get(proto) ?? new Set();
+    declared.set(proto, names.add(name));
+    Object.defineProperty(proto, name, {
+        configurable: true,
+        enumerable: true,
+        get() {
+            return resolve(this, name)[0];
+        },
+        set(value) {
+            if (!this[HELD]) {
+                this[HELD] = {};
+                this.addController(watcher(this));
+            }
+            const word = (this[HELD][name] ??= { i: 0 });
+            if (word.i < initializers(this, name)) {
+                word.i++;
+                word.e = value;
+                this.requestUpdate(name, undefined, undefined, true, value);
+                return;
+            }
+            const before = this[name];
+            word.o = value === '' && name.endsWith('Message') ? undefined : value;
+            this.requestUpdate(name, before);
+        },
+    });
+};
+export const formatWords = (host, name, values = {}) => {
+    const [message, from] = resolve(host, name);
+    const locale = wordsLocale(host);
+    return formatMessage(String(message ?? ''), values, locale, { plurals: from || locale });
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.147.0",
+  "version": "0.149.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -17,7 +17,29 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./custom-elements.json": "./custom-elements.json"
+    "./audits/name": {
+      "types": "./dist/utils/audit-name/audit-name.d.ts",
+      "development": "./dist/utils/audit-name/audit-name.js",
+      "helix-development": "./dist/utils/audit-name/audit-name.js",
+      "default": "./dist/utils/audit-name/audit-name-off.js"
+    },
+    "./audits/react": {
+      "types": "./dist/helix-element/react-audit.d.ts",
+      "development": "./dist/helix-element/react-audit.js",
+      "helix-development": "./dist/helix-element/react-audit.js",
+      "default": "./dist/helix-element/react-audit-off.js"
+    },
+    "./audits/source": {
+      "types": "./dist/utils/audit-source/audit-source.d.ts",
+      "development": "./dist/utils/audit-source/audit-source.js",
+      "helix-development": "./dist/utils/audit-source/audit-source.js",
+      "default": "./dist/utils/audit-source/audit-source-off.js"
+    },
+    "./custom-elements.json": "./custom-elements.json",
+    "./words": {
+      "types": "./dist/words/index.d.ts",
+      "default": "./dist/words/index.js"
+    }
   },
   "files": [
     "custom-elements.json",
@@ -27,44 +49,37 @@
   "sideEffects": false,
   "scripts": {
     "analyze": "bun --bun helix-cem",
-    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
-    "test": "bun test src --conditions helix-source --conditions helix-development",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json && bun scripts/development-imports.mjs",
+    "test": "bun test src --conditions helix-development",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.147.0"
+    "@fusion.dev/helix-icons": "0.149.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.147.0",
-    "@fusion.dev/helix-testing": "0.147.0",
+    "@fusion.dev/helix-cem": "0.149.0",
+    "@fusion.dev/helix-testing": "0.149.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",
   "imports": {
     "#audit-name": {
-      "helix-source": {
-        "development": "./src/utils/audit-name/audit-name.ts",
-        "helix-development": "./src/utils/audit-name/audit-name.ts",
-        "default": "./src/utils/audit-name/audit-name-off.ts"
-      },
-      "types": "./dist/utils/audit-name/audit-name.d.ts",
-      "development": "./dist/utils/audit-name/audit-name.js",
-      "helix-development": "./dist/utils/audit-name/audit-name.js",
-      "default": "./dist/utils/audit-name/audit-name-off.js"
+      "development": "./src/utils/audit-name/audit-name.ts",
+      "helix-development": "./src/utils/audit-name/audit-name.ts",
+      "default": "./src/utils/audit-name/audit-name-off.ts"
     },
     "#audit-source": {
-      "helix-source": {
-        "development": "./src/utils/audit-source/audit-source.ts",
-        "helix-development": "./src/utils/audit-source/audit-source.ts",
-        "default": "./src/utils/audit-source/audit-source-off.ts"
-      },
-      "types": "./dist/utils/audit-source/audit-source.d.ts",
-      "development": "./dist/utils/audit-source/audit-source.js",
-      "helix-development": "./dist/utils/audit-source/audit-source.js",
-      "default": "./dist/utils/audit-source/audit-source-off.js"
+      "development": "./src/utils/audit-source/audit-source.ts",
+      "helix-development": "./src/utils/audit-source/audit-source.ts",
+      "default": "./src/utils/audit-source/audit-source-off.ts"
+    },
+    "#react-audit": {
+      "development": "./src/helix-element/react-audit.ts",
+      "helix-development": "./src/helix-element/react-audit.ts",
+      "default": "./src/helix-element/react-audit-off.ts"
     }
   },
   "keywords": [