@fusion.dev/helix-core 0.148.0 → 0.149.0

package/dist/utils/reorder/reorder.js

@@ -0,0 +1,112 @@
+export const IDLE = { phase: 'idle' };
+export const reorderStep = (state, input) => {
+    switch (input.type) {
+        case 'press':
+            return state.phase === 'idle'
+                ? {
+                    from: input.from,
+                    key: input.key,
+                    phase: 'pressed',
+                    pointer: input.pointer,
+                    x: input.x,
+                    y: input.y,
+                }
+                : null;
+        case 'drag':
+            if (state.phase === 'pressed') {
+                return Math.hypot(input.x - state.x, input.y - state.y) < input.slop
+                    ? null
+                    : { by: 'pointer', from: state.from, key: state.key, phase: 'held', to: input.to };
+            }
+            return state.phase === 'held' && state.by === 'pointer' && state.to !== input.to
+                ? { ...state, to: input.to }
+                : null;
+        case 'release':
+            if (state.phase === 'pressed') {
+                return IDLE;
+            }
+            return state.phase === 'held' && state.by === 'pointer'
+                ? { ...state, phase: 'dropped' }
+                : null;
+        case 'pick':
+            if (state.phase === 'idle') {
+                return { by: 'keyboard', from: input.from, key: input.key, phase: 'held', to: input.from };
+            }
+            return state.phase === 'held' && state.by === 'keyboard' && state.key === input.key
+                ? { ...state, phase: 'dropped' }
+                : null;
+        case 'step':
+            return state.phase === 'held' && state.by === 'keyboard' && state.to !== input.to
+                ? { ...state, to: input.to }
+                : null;
+        case 'target':
+            return state.phase === 'held' && state.by === 'keyboard'
+                ? { ...state, phase: 'dropped', to: input.to }
+                : null;
+        case 'drop':
+            return state.phase === 'held' ? { ...state, phase: 'dropped' } : null;
+        case 'cancel':
+            if (state.phase === 'pressed') {
+                return IDLE;
+            }
+            return state.phase === 'held' ? { by: state.by, key: state.key, phase: 'canceled' } : null;
+        case 'settle':
+            return state.phase === 'dropped' || state.phase === 'canceled' ? IDLE : null;
+    }
+};
+export const passedCount = (centers, at, reversed = false) => centers.filter((center) => (reversed ? at < center : at > center)).length;
+export const centersOf = (spans, reversed = false) => {
+    const drawn = spans.flatMap((span, index) => (span ? [index] : []));
+    const first = drawn[0] ?? spans.length;
+    const last = drawn[drawn.length - 1] ?? -1;
+    let before = reversed ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+    return spans.map((span, index) => {
+        if (span) {
+            before = (span.start + span.end) / 2;
+            return before;
+        }
+        if (index < first) {
+            return reversed ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+        }
+        return index > last ? (reversed ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY) : before;
+    });
+};
+export const reorderKey = (key, { axis, count, rtl, to }) => {
+    const last = Math.max(0, count - 1);
+    if (key === 'Home') {
+        return 0;
+    }
+    if (key === 'End') {
+        return last;
+    }
+    const back = axis === 'block' ? 'ArrowUp' : rtl ? 'ArrowRight' : 'ArrowLeft';
+    const forward = axis === 'block' ? 'ArrowDown' : rtl ? 'ArrowLeft' : 'ArrowRight';
+    if (key !== back && key !== forward) {
+        return null;
+    }
+    return Math.min(last, Math.max(0, to + (key === forward ? 1 : -1)));
+};
+export const dropMark = (from, to) => to === from ? undefined : { edge: to < from ? 'before' : 'after', index: to };
+export const placeKey = (all, shown, key, to) => {
+    const others = shown.filter((one) => one !== key);
+    const rest = all.filter((one) => one !== key);
+    const beside = others[to - 1] ?? others[0];
+    if (beside === undefined) {
+        return [...all];
+    }
+    rest.splice(rest.indexOf(beside) + (to > 0 ? 1 : 0), 0, key);
+    return rest;
+};
+export const edgeSpeed = (at, start, end, { most = 12, zone = 40 } = {}) => {
+    const reach = Math.min(zone, (end - start) / 2);
+    if (reach <= 0) {
+        return 0;
+    }
+    if (at < start + reach) {
+        return -Math.round(most * Math.min(1, (start + reach - at) / reach)) || 0;
+    }
+    if (at > end - reach) {
+        return Math.round(most * Math.min(1, (at - (end - reach)) / reach));
+    }
+    return 0;
+};

package/dist/utils/report-runtime/report-runtime.d.ts

@@ -30,7 +30,7 @@ export type RuntimeKind =
  | 'min-out-of-range'
 /** A Stat was given one of Trend's directions, `up`, `down` or `neutral`, which lay nothing out. */
  | 'misread-direction'
-/** A React handler prop names an event the element never dispatches itself. */
+/** A React handler prop names an event the element never dispatches itself. Development builds only. */
  | 'misplaced-handler'
 /** An Image has no `alt`, so a screen reader announces its file name. */
  | 'missing-alt'
@@ -59,9 +59,12 @@ export type RuntimeKind =
  | 'picture-in-picture-refused'
 /** A Grid's `min` is no length it can write, so the grid lays out by its column count. */
  | 'refused-length'
-/** A React handler prop is a removed callback, which never ran from JSX. */
+/** A React handler prop is a removed callback, which never ran from JSX. Development builds only. */
  | 'removed-callback'
-/** A React handler prop uses Solid's `on:`, which React reads as another event's name. */
+/**
+ * A React handler prop uses Solid's `on:`, which React reads as another event's name.
+ * Development builds only.
+ */
  | 'solid-handler-syntax'
 /** A stencil's regions went unused: no named parts, or parts too small. */
  | 'stencil-regions-unused'
@@ -73,7 +76,7 @@ export type RuntimeKind =
  | 'two-default-operators'
 /** A Quote's text starts or ends with a quotation mark, so the browser's marks double it. */
  | 'typed-marks'
-/** A React handler prop names an event nothing dispatches. */
+/** A React handler prop names an event nothing dispatches. Development builds only. */
  | 'unknown-event'
 /** An Icon's `name` is in no icon set it can read, so it draws nothing. */
  | 'unknown-icon'

package/dist/utils/slotted-words/slotted-words.d.ts

@@ -5,7 +5,8 @@
  * For a component that says what the page put in it, which is the page's own
  * text and not anything this library wrote: an empty state's heading and
  * message, a banner's message. Text nodes count toward the default slot, as
- * they are assigned to it. Nothing on a server, whose element has no children
- * to read.
+ * they are assigned to it; comments, such as the markers a template writes
+ * around its text, are left out. Nothing on a server, whose element has no
+ * children to read.
  */
 export declare const slottedWords: (host: Element, slots: readonly string[]) => string;

package/dist/utils/slotted-words/slotted-words.js

@@ -1,5 +1,7 @@
 export const slottedWords = (host, slots) => [...(host.childNodes ?? [])]
-    .filter((node) => (node instanceof Element ? slots.includes(node.slot) : slots.includes('')))
+    .filter((node) => node instanceof Element
+    ? slots.includes(node.slot)
+    : node.nodeType === 3 && slots.includes(''))
     .map((node) => node.textContent?.replace(/\s+/g, ' ').trim() ?? '')
     .filter(Boolean)
     .join(' ');

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.148.0";
+export declare const VERSION = "0.149.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.148.0';
+export const VERSION = '0.149.0';

package/dist/words/index.d.ts

@@ -0,0 +1,3 @@
+export { formatMessage, type Message, type MessageOptions, type MessageTable, type MessageValues, } from './message.js';
+export { clearWords, type HelixWords, localeChain, refreshWords, registerWords, setDefaultWordsLocale, type Words, } from './registry.js';
+export { handedLocale, wordsLocale } from './words-locale.js';

package/dist/words/index.js

@@ -0,0 +1,3 @@
+export { formatMessage, } from './message.js';
+export { clearWords, localeChain, refreshWords, registerWords, setDefaultWordsLocale, } from './registry.js';
+export { handedLocale, wordsLocale } from './words-locale.js';

package/dist/words/message.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A sentence a component says, written in a small subset of ICU
+ * MessageFormat, the syntax translation tools already read:
+ *
+ * - `{name}`, a value put in where the sentence says. A number is written in
+ *   the element's locale.
+ * - `{n, number}`, `{n, number, percent}` and `{n, number, integer}`.
+ * - `{n, plural, =0 {...} one {# ...} other {...}}`, with `offset:`, and
+ *   `{n, selectordinal, ...}` in the same shape. `#` is the number.
+ * - `{x, select, a {...} other {...}}`.
+ * - `''` for one apostrophe, and `'{'` for a brace written as text. A lone
+ *   apostrophe is text, so "L'élément" needs no escaping.
+ */
+export type Message = string;
+/** A word table, such as `color-words`. Its entries merge one by one. */
+export type MessageTable = Readonly<Record<string, Message>>;
+/** The values a message puts in, by name. */
+export type MessageValues = Readonly<Record<string, string | number>>;
+/** How a message is formatted. */
+export interface MessageOptions {
+    /**
+     * Wraps each value in Unicode isolates (U+2068 and U+2069), so a number or
+     * a Latin name keeps its order inside a right-to-left sentence.
+     */
+    isolate?: boolean;
+    /**
+     * The locale whose plural rules pick a form, where it is not the locale
+     * the numbers are written in. A message from the English fallback counts
+     * with English rules on a Polish page, because its forms are English.
+     */
+    plurals?: string;
+}
+/**
+ * A message with its values put in, its numbers written in `locale`, and its
+ * plural forms picked by the rules of `options.plurals`, or of `locale`.
+ *
+ * **A value that is missing leaves its placeholder as written**, so
+ * `{count}` shows on the page as the mistake it is. An unknown argument type
+ * writes the value as text, so a type added later changes only the messages
+ * that use it.
+ *
+ * ```js
+ * formatMessage('{count, plural, one {# wynik} few {# wyniki} many {# wyników} other {# wyniku}}', { count: 5 }, 'pl')
+ * // '5 wyników'
+ * ```
+ */
+export declare const formatMessage: (message: Message, values: MessageValues, locale: string, options?: MessageOptions) => string;

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);
+};