entasis 0.11.0 → 0.12.0

package/dist/utils/listFilter.js

@@ -0,0 +1,130 @@
+/**
+ * Locale-aware text matching for filterable lists (Combobox, TagsInput, Command, PhoneInput,
+ * menus). Comparisons go through `Intl.Collator` with `usage: 'search'` and, by default,
+ * `sensitivity: 'base'`, so `eclair` finds `Éclair` and case never matters, while each language
+ * keeps its own rules (in Turkish, `i` matches `İ` but not `I`).
+ */
+const CACHE_LIMIT = 64;
+const cache = new Map();
+const ASCII_RE = /^[\x20-\x7e]*$/;
+const MARK_RE = /\p{M}/u;
+const MARK_CHAR_RE = /^\p{M}$/u;
+const localeKey = (locale) => {
+    if (locale === undefined)
+        return '';
+    return Array.isArray(locale) ? locale.map(String).join(',') : String(locale);
+};
+// Offsets of the characters of `text` that are not combining marks.
+const baseOffsets = (text) => {
+    const offsets = [];
+    for (let index = 0; index < text.length; index++) {
+        if (!MARK_CHAR_RE.test(text[index]))
+            offsets.push(index);
+    }
+    return offsets;
+};
+const buildFilter = (locale, collatorOptions) => {
+    const collator = new Intl.Collator(locale, {
+        sensitivity: 'base',
+        ...collatorOptions,
+        usage: 'search'
+    });
+    const resolved = collator.resolvedOptions();
+    const resolvedLocale = resolved.locale;
+    const ignoresCase = resolved.sensitivity === 'base' || resolved.sensitivity === 'accent';
+    // Plain comparisons decide most queries; the collator only runs when they can't. Lower-casing
+    // in the resolved locale keeps Turkish dotted and dotless i apart, as the collator does.
+    const fold = (text) => (ignoresCase ? text.toLocaleLowerCase(resolvedLocale) : text);
+    // Printable ASCII has no accents to ignore, so a plain miss is a collator miss as well.
+    const plainSuffices = (text, query) => !resolved.ignorePunctuation && ASCII_RE.test(text) && ASCII_RE.test(query);
+    const equals = (text, query) => collator.compare(text.normalize('NFC'), query.normalize('NFC')) === 0;
+    const same = (text, start, end, query) => collator.compare(text.slice(start, end), query) === 0;
+    // Whether a slice of `text` equals `query` (both normalized), trying only the slice at the
+    // start with `prefixOnly`. Slices are as long as the query. When either side carries combining
+    // marks (Arabic tashkeel, Hebrew niqqud, which the default sensitivity ignores), a slice holds
+    // as many characters other than marks as the query instead, tried with and without the marks
+    // that follow it, so marks present on one side only don't shift it.
+    const matchesSlice = (text, query, prefixOnly) => {
+        if (!MARK_RE.test(text) && !MARK_RE.test(query)) {
+            const last = prefixOnly ? 0 : text.length - query.length;
+            for (let start = 0; start <= last; start++) {
+                if (same(text, start, start + query.length, query))
+                    return true;
+            }
+            return false;
+        }
+        const count = baseOffsets(query).length;
+        const bases = baseOffsets(text);
+        if (count === 0 || bases.length < count)
+            return false;
+        const last = prefixOnly ? 0 : bases.length - count;
+        for (let first = 0; first <= last; first++) {
+            const start = first === 0 ? 0 : bases[first];
+            const withMarks = bases[first + count] ?? text.length;
+            const withoutMarks = bases[first + count - 1] + 1;
+            if (same(text, start, withMarks, query))
+                return true;
+            if (withoutMarks !== withMarks && same(text, start, withoutMarks, query))
+                return true;
+        }
+        return false;
+    };
+    const startsWith = (text, query) => {
+        if (query === '' || text.startsWith(query))
+            return true;
+        if (fold(text).startsWith(fold(query)))
+            return true;
+        if (plainSuffices(text, query))
+            return false;
+        return matchesSlice(text.normalize('NFC'), query.normalize('NFC'), true);
+    };
+    const contains = (text, query) => {
+        if (query === '' || text.includes(query))
+            return true;
+        if (fold(text).includes(fold(query)))
+            return true;
+        if (plainSuffices(text, query))
+            return false;
+        return matchesSlice(text.normalize('NFC'), query.normalize('NFC'), false);
+    };
+    const filter = (items, query, { text, match = 'contains', limit = Infinity } = {}) => {
+        const results = [];
+        if (limit <= 0)
+            return results;
+        const predicate = typeof match === 'function' ? match : match === 'startsWith' ? startsWith : contains;
+        for (const item of items) {
+            const texts = text ? text(item) : String(item);
+            const matched = typeof texts === 'string'
+                ? predicate(texts, query)
+                : texts.some((candidate) => candidate != null && predicate(candidate, query));
+            if (!matched)
+                continue;
+            results.push(item);
+            if (results.length >= limit)
+                break;
+        }
+        return results;
+    };
+    return { locale: resolvedLocale, contains, startsWith, equals, filter };
+};
+/**
+ * A cached filter for `options`. Building an `Intl.Collator` is expensive, so filters are shared
+ * per locale and collator options.
+ */
+export const createListFilter = (options = {}) => {
+    const { locale, ...rest } = options;
+    // An option given as `undefined` is not set: it neither overrides a default nor gets a cache
+    // entry of its own (JSON drops it, so it would share the key of the defaults).
+    const collatorOptions = Object.fromEntries(Object.entries(rest)
+        .filter(([, value]) => value !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    const key = `${localeKey(locale)}|${JSON.stringify(collatorOptions)}`;
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const listFilter = buildFilter(locale, collatorOptions);
+    if (cache.size >= CACHE_LIMIT)
+        cache.delete(cache.keys().next().value);
+    cache.set(key, listFilter);
+    return listFilter;
+};

package/dist/utils/match.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The default search matcher for Command, filterable menus and lists: an item matches when the
+ * query appears in its text, ignoring case and accents in the given locale.
+ */
+import { type ListFilterOptions } from './listFilter.js';
+/** The searchable fields of a list, menu or command item. */
+export type MatchableItem = {
+    /** Visible label. */
+    label?: string | null;
+    /** Plain text to search instead of the label, for items whose label is not plain text. */
+    textValue?: string | null;
+    /** Extra terms that also find the item. */
+    keywords?: readonly string[] | null;
+    /** The item's value, searched last. */
+    value?: string | number | null;
+};
+/** Decides whether `item` matches the search `query`. */
+export type ItemMatcher<Item extends MatchableItem = MatchableItem> = (item: Item, query: string) => boolean;
+export type ItemMatcherOptions = ListFilterOptions & {
+    /**
+     * `contains` (default) finds the query anywhere in the item's text, label, keywords and value
+     * read as one string. `startsWith` matches when the label, a keyword or the value starts
+     * with the query.
+     */
+    mode?: 'contains' | 'startsWith';
+};
+/** The fields of `item` that searches read, in order: label (or `textValue`), keywords, value. */
+export declare const getItemSearchTexts: (item: MatchableItem) => string[];
+/** Builds a matcher for `options`; the locale and collator options decide case and accents. */
+export declare const createItemMatcher: <Item extends MatchableItem = MatchableItem>(options?: ItemMatcherOptions) => ItemMatcher<Item>;
+/**
+ * The default matcher: case- and accent-insensitive `contains` over label (or `textValue`),
+ * keywords and value, in the runtime locale. Command uses it when no `filter` is given.
+ */
+export declare const matchItem: ItemMatcher;

package/dist/utils/match.js

@@ -0,0 +1,36 @@
+/**
+ * The default search matcher for Command, filterable menus and lists: an item matches when the
+ * query appears in its text, ignoring case and accents in the given locale.
+ */
+import { createListFilter } from './listFilter.js';
+/** The fields of `item` that searches read, in order: label (or `textValue`), keywords, value. */
+export const getItemSearchTexts = (item) => {
+    const texts = [];
+    const label = item.textValue ?? item.label;
+    if (label)
+        texts.push(label);
+    for (const keyword of item.keywords ?? [])
+        if (keyword)
+            texts.push(keyword);
+    if (item.value != null && item.value !== '')
+        texts.push(String(item.value));
+    return texts;
+};
+/** Builds a matcher for `options`; the locale and collator options decide case and accents. */
+export const createItemMatcher = (options = {}) => {
+    const { mode = 'contains', ...filterOptions } = options;
+    const filter = createListFilter(filterOptions);
+    if (mode === 'startsWith') {
+        return (item, query) => query === '' || getItemSearchTexts(item).some((text) => filter.startsWith(text, query));
+    }
+    return (item, query) => query === '' || filter.contains(getItemSearchTexts(item).join(' '), query);
+};
+let defaultMatcher;
+/**
+ * The default matcher: case- and accent-insensitive `contains` over label (or `textValue`),
+ * keywords and value, in the runtime locale. Command uses it when no `filter` is given.
+ */
+export const matchItem = (item, query) => {
+    defaultMatcher ??= createItemMatcher();
+    return defaultMatcher(item, query);
+};

package/dist/utils/number.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Locale-aware number text: digit normalization, parsing, formatting and commit rounding.
+ *
+ * Number entry (NumberInput, PinInput), range displays (Meter, Progress) and charts share these so
+ * a value typed as `1 234,5`, `١٢٣٫٤` or `１２３` reads the same everywhere. Every function is pure
+ * and SSR-safe; `Intl.NumberFormat` instances are cached by locale and options because building
+ * one is far more expensive than formatting with it.
+ */
+/** Anything `Intl.NumberFormat` accepts as a locale. */
+export type NumberLocale = Intl.LocalesArgument;
+type NumberFormatOptions = Intl.NumberFormatOptions & {
+    roundingIncrement?: number;
+    roundingMode?: string;
+    roundingPriority?: string;
+};
+/**
+ * A cached `Intl.NumberFormat` for `locale` and `options`. The cache is keyed by the locale string
+ * and the serialized options, and keeps the most recent entries only.
+ */
+export declare const getNumberFormatter: (locale?: NumberLocale, options?: Intl.NumberFormatOptions) => Intl.NumberFormat;
+/** Formats `value` with the cached formatter; `null` and `undefined` format as `''`. */
+export declare const formatNumber: (value: number | bigint | null | undefined, locale?: NumberLocale, options?: Intl.NumberFormatOptions) => string;
+/**
+ * Replaces Arabic-Indic, Persian, Devanagari, Bengali, Thai, full-width and Han digits with ASCII
+ * digits (`١٢٣` → `123`, `１２３` → `123`, `二〇二六` → `2026`). Han numerals are read digit by
+ * digit, so positional characters such as `十` are left as they are.
+ */
+export declare const normalizeDigits: (text: string) => string;
+/** Whether `char` is a single digit in ASCII or any numeral system `normalizeDigits` reads. */
+export declare const isDigitCharacter: (char: string) => boolean;
+/**
+ * Removes Unicode format controls (`\p{Cf}`): the left-to-right and right-to-left marks, the
+ * Arabic letter mark and the isolates that right-to-left locales put around signs, currencies
+ * and exponents, plus zero-width joiners.
+ */
+export declare const stripBidiMarks: (text: string) => string;
+/** Minus signs a user may type or paste: hyphen-minus, minus, full-width, dashes. */
+export declare const MINUS_SIGNS: readonly ["-", "−", "－", "‒", "–", "—", "﹣"];
+/** Plus signs a user may type or paste. */
+export declare const PLUS_SIGNS: readonly ["+", "＋", "﹢"];
+/** Percent signs: ASCII, Arabic, full-width and small. */
+export declare const PERCENT_SIGNS: readonly ["%", "٪", "％", "﹪"];
+/** Per-mille signs: ASCII and Arabic. */
+export declare const PERMILLE_SIGNS: readonly ["‰", "؉"];
+/** The symbols a locale and format use around the digits. */
+export type NumberSymbols = {
+    /** Decimal separator of the locale, even for integer formats. */
+    decimal: string;
+    /** Grouping separator, when the format groups digits. */
+    group?: string;
+    /**
+     * Currency symbol, code or name, for currency formats: one entry per plural form of a name
+     * (`US dollar`, `US dollars`).
+     */
+    currencies: string[];
+    /** Unit labels (`km/h`, `°C`), one entry per plural form (`day`, `days`), for unit formats. */
+    units: string[];
+    /** Exponent separator (`E`), for scientific and engineering notation. */
+    exponentSeparator?: string;
+    /** Percent sign the format renders, if any. */
+    percentSign?: string;
+    /** Other literal text the format renders (spaces, parentheses). */
+    literals: string[];
+    /**
+     * Whole texts the format renders without digits, with the value each spells out: Arabic and
+     * Hebrew write one or two of a unit as the word alone (`يومان`, two days).
+     */
+    spelledValues: ReadonlyMap<string, number>;
+};
+/**
+ * The separators and decorations `locale` renders with `options`, read from `formatToParts`.
+ * Cached like the formatters.
+ */
+export declare const getNumberSymbols: (locale?: NumberLocale, options?: Intl.NumberFormatOptions) => NumberSymbols;
+/**
+ * Parses number text written in `locale` with `options`, or returns `null` when the text is not a
+ * complete number (`''`, `-`, `1e`, `abc`, `Infinity`).
+ *
+ * - Bidi marks are stripped and every supported numeral system reads as ASCII digits.
+ * - Group separators are dropped; for space-grouping locales any space counts, so `1 234,5`
+ *   typed with a plain space parses in `fr`.
+ * - The locale's decimal separator, the full-width period and the Arabic decimal separator read as
+ *   the decimal point. When several points remain, the last one is the decimal point.
+ * - Currency symbols, unit labels (in every plural form) and literals of the format are ignored;
+ *   Unicode minus signs, a trailing minus (`5-`) and accounting parentheses (`(5)`) read as
+ *   negative. A plural form the format writes without digits (Arabic `يومان`, two days) reads as
+ *   the value it spells out.
+ * - Percent text (a percent sign, or `style: 'percent'`) is divided by 100, per-mille by 1000.
+ *
+ * Without a `locale`, Arabic-script digits read with `ar` separators and Han digits with `zh`.
+ */
+export declare const parseNumber: (text: string | null | undefined, locale?: NumberLocale, options?: Intl.NumberFormatOptions) => number | null;
+export type NumberCharacterOptions = {
+    /** Accept minus signs. @default true */
+    allowNegative?: boolean;
+};
+/**
+ * The non-digit characters number text in `locale` and `options` may contain, read per character
+ * from `formatToParts` of positive, negative and plural sample values: separators, currency and
+ * unit characters in every plural form, signs, accounting parentheses, percent and per-mille
+ * variants, every space separator when the format renders a space, and both apostrophes when it
+ * groups with one. Digits of every supported numeral system are accepted separately by
+ * `isNumberText`.
+ */
+export declare const getNumberCharacters: (locale?: NumberLocale, options?: Intl.NumberFormatOptions, { allowNegative }?: NumberCharacterOptions) => ReadonlySet<string>;
+/**
+ * Whether every character of `text` can belong to number text in `locale`: a digit of a supported
+ * numeral system, a character from `getNumberCharacters`, or a format control. Use it to reject a
+ * keystroke or paste before parsing; partial text such as `-` or `1,` passes.
+ */
+export declare const isNumberText: (text: string, locale?: NumberLocale, options?: Intl.NumberFormatOptions, characterOptions?: NumberCharacterOptions) => boolean;
+/** Whether `options` set any Intl rounding option. */
+export declare const hasRoundingOptions: (options?: NumberFormatOptions) => boolean;
+/**
+ * Removes binary floating-point noise from arithmetic results (`0.1 + 0.2` → `0.3`) without
+ * discarding real precision: the value moves by at most one ulp-scaled epsilon, capped at 1e-10.
+ */
+export declare const cleanFloatingPoint: (value: number) => number;
+/**
+ * The value to commit for `value` displayed with `options`: rounded exactly as Intl rounds it for
+ * display (`maximumFractionDigits`, significant digits, increments, rounding mode), so the committed
+ * number matches the text the user sees after blur. Without rounding options the value is returned
+ * as it is, keeping its full precision.
+ */
+export declare const roundToFormat: (value: number, options?: Intl.NumberFormatOptions) => number;
+export {};