@nxgt/material-core 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @nxgt/material-core
 
+## 0.8.0
+
+### Minor Changes
+
+- [#521](https://github.com/softistx/nxgt-material/pull/521) [`b76cd9a`](https://github.com/softistx/nxgt-material/commit/b76cd9ae3cc4f4d0f1b20cec31c9471819ffcd3c) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `Autocomplete` can search a server (softistx/nxgt-material#514). Fixes [#514](https://github.com/softistx/nxgt-material/issues/514).
+  
+  - **Server search.** `onSearch(query, { signal })` (Vue: the function prop `on-search`, so `@search="fn"` binds it too) is called once typing pauses and its results become the list. Each search aborts the previous one (pass `signal` to `fetch`), and a response that lands after a newer one is dropped, even from an API that ignores the signal. `minQueryLength` (Vue: `min-query-length`, default 1) is how many characters it waits for; below it the list says "Type at least N characters to search." A rejected search is shown and announced ("The search failed. Try again.") and reported to `onSearchError` (Vue: `@search-error`). `options` is now optional: with `onSearch` it is the list before a search and the selected options' labels, and a picked option keeps its chip once a new search no longer returns it.
+  - **Controlled mode.** `loading` and `searchError` (Vue: `search-error`), beside `onQueryChange` (Vue: `@query-change`), for an app that fetches `options` itself.
+  - **A configurable debounce.** `debounceMs` (Vue: `debounce-ms`), 250 ms by default, sets the pause before `onSearch` and `onQueryChange`.
+  - **Accent-insensitive matching.** `filter`: `'accent-insensitive'` (the default without `onSearch`), `'none'` (the default with `onSearch`) or `(option, query) => boolean`. The default compares the label or value with the query lowercased in the provider's language and stripped of accents, so "e" finds "École" and "orle" finds "Orléans". Vue's exported `filterAutocompleteOptions` matches the same way and takes an optional `locale`.
+  - **Accessibility.** A polite live region announces "Loading…", then "N results" / "No results" (or the failure) once the search answers or typing pauses, not on every keystroke; the list is `aria-busy` while loading. New strings: `material.autocomplete.loading`, `.results`, `.search-error`, `.min-query` (en, fr). The keyboard works as before.
+  - React: clearing a single `Autocomplete`'s input no longer throws (`Cannot read properties of null (reading 'value')`).
+  - `@nxgt/material-core` adds `/debounce` (the `debounce` both libraries' `SearchField` kept a copy of, still exported by both, Vue now with its `Debounced` type), `/text-match` (`foldText`, `matchesText`) and `/async-search` (`createAsyncSearch`, `searchAnnouncement`).
+  
+  Apps that built their own search field and result list while waiting for this (marked `Temporary, until material [#514](https://github.com/softistx/nxgt-material/issues/514)`) can replace it with `onSearch` and remove the workaround.
+  
+  **Behaviour changes, no API removed.**
+  
+  - Local matching ignores accents by default, so a query can keep more options than before. To match as before, pass your own `filter`, for example `filter={(option, query) => option.label.toLowerCase().includes(query.toLowerCase())}`; to show `options` exactly as given (filtered on your server), pass `filter="none"`.
+  - `onQueryChange` (`@query-change`) now runs 250 ms after typing pauses; it was a fixed 1 s in `@nxgt/material` and 300 ms in `@nxgt/material-vue`. Search for `onQueryChange` / `@query-change`, and add `debounceMs={1000}` (`:debounce-ms="300"`) where the old pause mattered — or move the fetch to `onSearch`.
+  - React: the list's empty text is no longer a live region of its own (Base UI's `ComboboxEmpty` had `role="status"`); the field's one status region (`[data-slot="autocomplete-status"]`) says "No results" instead. A test that found the empty text by `role="status"` finds it by its text.
+
+### Patch Changes
+
+- [#519](https://github.com/softistx/nxgt-material/pull/519) [`18f30c1`](https://github.com/softistx/nxgt-material/commit/18f30c1cc6cc41c2b73a43fad2501b7db2bbc016) Thanks [@SteveGT96](https://github.com/SteveGT96)! - package.json names its repository, so issue reports route to it. Each package now has a `repository` field (`git+https://github.com/softistx/nxgt-material.git`, with its `directory` under `packages/`).
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -6,7 +6,7 @@ The framework-free core that [`@nxgt/material`](https://www.npmjs.com/package/@n
 the print formatters, the PDF file helpers, the PDF viewer's framework-free
 half (page geometry, scroll spy, text search), the currency field's decimals,
 the file-size formatter, the slider's tick marks, the emoji list's groups,
-the date range presets, the file preview's kind detection, the fields' blur
+the date range presets, a debounce, accent-insensitive text matching and a race-free async search (`/debounce`, `/text-match`, `/async-search`), the file preview's kind detection, the fields' blur
 rule, a field's first reachable control (`/focus-control`) and its `aria-describedby`
 (`/described-by`), the page behind a modal layer made inert
 (`/inert-others`), Escape pressed while an overlay closes
@@ -93,6 +93,9 @@ built-in.
 | `/slider-ticks` | `tickValues` — where a slider's tick marks sit |
 | `/emoji-groups` | `groupKey`, `groupEmojis`, `searchEmojis`, `groupName`, `GROUP_NAMES` and the type `EmojiItem` — how the emoji list groups, searches and names its emojis |
 | `/date-range` | `DATE_RANGE_PRESET_IDS`, `presetRange`, `resolvePresetRange`, `isSameDayRange`, `isRangeDisabled`, `withTimeOf`, `endOfDayTime`, `clampRangeEnd`, `keepRangeTimes` and the types `DayRange`, `PartialDayRange`, `DateRangePreset`, `DateRangePresetId`, `DateRangePresetOption`, `DateRangeRules` — `DateRangeField`'s presets and times |
+| `/debounce` | `debounce`, the type `Debounced` — a function called once calls pause, with `cancel` and `flush` (`SearchField`'s `debounceMs`) |
+| `/text-match` | `foldText`, `matchesText` — case- and accent-insensitive matching (`'e'` finds "École"), lowercased for a locale |
+| `/async-search` | `createAsyncSearch`, `searchAnnouncement`, `DEFAULT_SEARCH_DEBOUNCE_MS`, `DEFAULT_MIN_QUERY_LENGTH` and the types `AsyncSearch`, `AsyncSearchConfig`, `AsyncSearchState`, `AsyncSearchStatus`, `SearchFn`, `SearchContext`, `SearchAnnouncement` — `Autocomplete`'s server search: debounced, each run aborting the last, a stale response dropped |
 | `/file-preview` | `fileKind`, `describeFile`, `safePreviewUrl`, `readTextPreview`, `FilePreviewHttpError`, `FilePreviewUnsafeUrlError`, `TEXT_PREVIEW_MAX_BYTES`, `fileExtension`, `fileNameFromUrl`, `dataUrlType`, `kindOfMimeType`, `normaliseMimeType`, `isTextFileKind`, `TEXT_FILE_KINDS` and the types `FileKind`, `FileKindInput`, `DescribedFile`, `FilePreviewSource`, `TextPreview` — `FilePreview`'s kind detection, URL allow-list and text reader |
 | `/vite` | `pdfkitStandardFonts()` — see below |
 | `/pdfkit-fonts` | **Node only.** `pdfkitStandardFontDirs`, `pdfkitStandardFontFiles`, `PDFKIT_STANDARD_FONTS`, the types `PdfkitStandardFont` and `PdfkitFontsWarn` — where the app's pdfkit keeps its standard fonts, for a server tracer |
@@ -375,6 +378,81 @@ tickValues(0, 100, true, 1).length; // 21 — capped
 tickValues(5, 5, true); // [5] — min === max
 ```
 
+### A debounced call: `/debounce`
+
+The debounce both libraries' `SearchField` (`debounceMs`) and `Autocomplete`
+use: the wrapped function runs `ms` after the last call, with the last
+arguments. `cancel()` drops a pending call, `flush()` runs it now.
+
+```ts
+import { debounce } from '@nxgt/material-core/debounce';
+
+const save = debounce((text: string) => console.log('save', text), 300);
+save('a');
+save('ab'); // 300 ms later: "save ab", once
+save.flush(); // or now
+```
+
+### Matching text as the user types: `/text-match`
+
+`foldText(text, locale?)` lowercases `text` for `locale` (the runtime's when
+omitted; an invalid tag falls back to it), then strips its diacritics
+(`normalize('NFD')`, combining marks removed). `matchesText(text, query,
+locale?)` says whether the folded, trimmed query occurs in the folded text;
+a blank query matches everything. Both libraries' `Autocomplete` filters its
+local options with it, in the provider's language.
+
+```ts
+import { foldText, matchesText } from '@nxgt/material-core/text-match';
+
+foldText('Élève'); // 'eleve'
+foldText('İSTANBUL', 'tr'); // 'istanbul'
+matchesText('Orléans', 'orle'); // true
+matchesText('Cafe', 'café'); // true — both ways
+matchesText('Lyon', '   '); // true — a blank query keeps everything
+```
+
+Letters that are not a base letter plus a mark stay as they are: `ß`, `ø`
+and `æ` do not fold to `ss`, `o` or `ae`.
+
+### A search that never answers out of order: `/async-search`
+
+`createAsyncSearch(config, onChange)` runs `config.search(query, { signal })`
+once `request(query)` calls pause for `debounceMs` (250 by default). Each run
+aborts the one before it, and a response that still lands for an older run
+is dropped, so a slow first query never overwrites a faster second one; an
+abort is never reported as an error. A query shorter than `minQueryLength`
+(1 by default, trimmed) searches nothing and resets the state to `idle`.
+`onChange` receives each state: `{ status: 'idle' | 'loading' | 'success' |
+'error', query, results, error? }`, the last results kept while the next
+query loads.
+
+```ts
+import { createAsyncSearch } from '@nxgt/material-core/async-search';
+
+type City = { value: string; label: string };
+
+const search = createAsyncSearch<City>(
+	{
+		search: (query, { signal }) =>
+			fetch(`/api/cities?q=${encodeURIComponent(query)}`, { signal }).then((r) => r.json()),
+		minQueryLength: 2,
+	},
+	(state) => render(state),
+);
+
+input.addEventListener('input', () => search.request(input.value));
+// On teardown: search.cancel() drops the pending search and aborts the one in flight.
+```
+
+`configure(partial)` swaps the search, the debounce or the minimum length
+(React re-reads the latest props through it), `flush()` runs the pending
+search now, and requesting the query the state already holds (or is loading)
+does nothing. `searchAnnouncement({ loading, failed, settled, count })` is
+what a combobox's polite live region says: the failure, else "loading",
+else the count once the query has settled — `null` while the user is still
+typing.
+
 ### The emoji list's groups: `/emoji-groups`
 
 How both libraries' `EmojiList` groups, searches and names its emojis:

package/dist/chunks/index-f24x24a8.js

@@ -0,0 +1,37 @@
+// src/lib/debounce.ts
+function debounce2(fn, ms) {
+  let timer;
+  let lastArgs;
+  const run = () => {
+    timer = undefined;
+    const pending = lastArgs;
+    lastArgs = undefined;
+    if (pending)
+      fn(...pending);
+  };
+  const wrapped = (...args) => {
+    lastArgs = args;
+    if (timer !== undefined)
+      clearTimeout(timer);
+    timer = setTimeout(run, ms);
+  };
+  wrapped.cancel = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    lastArgs = undefined;
+  };
+  wrapped.flush = () => {
+    if (timer === undefined)
+      return;
+    clearTimeout(timer);
+    run();
+  };
+  return wrapped;
+}
+
+export { debounce2 };
+
+//# debugId=863EA47559EC981164756E2164756E21
+//# sourceMappingURL=index-f24x24a8.js.map

package/dist/chunks/index-f24x24a8.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/debounce.ts"],
+  "sourcesContent": [
+    "export type Debounced<Args extends unknown[]> = ((...args: Args) => void) & {\n\tcancel: () => void;\n\tflush: () => void;\n};\n\nexport function debounce<Args extends unknown[]>(\n\tfn: (...args: Args) => void,\n\tms: number,\n): Debounced<Args> {\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet lastArgs: Args | undefined;\n\n\tconst run = () => {\n\t\ttimer = undefined;\n\t\tconst pending = lastArgs;\n\t\tlastArgs = undefined;\n\t\tif (pending) fn(...pending);\n\t};\n\n\tconst wrapped = ((...args: Args) => {\n\t\tlastArgs = args;\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = setTimeout(run, ms);\n\t}) as Debounced<Args>;\n\n\twrapped.cancel = () => {\n\t\tif (timer !== undefined) {\n\t\t\tclearTimeout(timer);\n\t\t\ttimer = undefined;\n\t\t}\n\t\tlastArgs = undefined;\n\t};\n\n\twrapped.flush = () => {\n\t\tif (timer === undefined) return;\n\t\tclearTimeout(timer);\n\t\trun();\n\t};\n\n\treturn wrapped;\n}\n"
+  ],
+  "mappings": ";AAKO,SAAS,SAAgC,CAC/C,IACA,IACkB;AAAA,EAClB,IAAI;AAAA,EACJ,IAAI;AAAA,EAEJ,MAAM,MAAM,MAAM;AAAA,IACjB,QAAQ;AAAA,IACR,MAAM,UAAU;AAAA,IAChB,WAAW;AAAA,IACX,IAAI;AAAA,MAAS,GAAG,GAAG,OAAO;AAAA;AAAA,EAG3B,MAAM,UAAW,IAAI,SAAe;AAAA,IACnC,WAAW;AAAA,IACX,IAAI,UAAU;AAAA,MAAW,aAAa,KAAK;AAAA,IAC3C,QAAQ,WAAW,KAAK,EAAE;AAAA;AAAA,EAG3B,QAAQ,SAAS,MAAM;AAAA,IACtB,IAAI,UAAU,WAAW;AAAA,MACxB,aAAa,KAAK;AAAA,MAClB,QAAQ;AAAA,IACT;AAAA,IACA,WAAW;AAAA;AAAA,EAGZ,QAAQ,QAAQ,MAAM;AAAA,IACrB,IAAI,UAAU;AAAA,MAAW;AAAA,IACzB,aAAa,KAAK;AAAA,IAClB,IAAI;AAAA;AAAA,EAGL,OAAO;AAAA;",
+  "debugId": "863EA47559EC981164756E2164756E21",
+  "names": []
+}

package/dist/lib/async-search.d.ts

@@ -0,0 +1,46 @@
+export { type SearchAnnouncement, searchAnnouncement, } from './search-announcement';
+/** What a search is handed besides the query: aborted once it is stale. */
+export type SearchContext = {
+    signal: AbortSignal;
+};
+/** A server search: the options for `query`. Pass `signal` on to `fetch`. */
+export type SearchFn<T> = (query: string, context: SearchContext) => Promise<T[]>;
+export type AsyncSearchStatus = 'idle' | 'loading' | 'success' | 'error';
+export type AsyncSearchState<T> = {
+    status: AsyncSearchStatus;
+    /** The query being searched (loading) or the one `results` answer. */
+    query: string;
+    /** The last results. Kept while the next query loads; `[]` when idle. */
+    results: T[];
+    /** What the search rejected with (`status: 'error'`). */
+    error?: unknown;
+};
+export type AsyncSearchConfig<T> = {
+    search: SearchFn<T>;
+    /** How long typing must pause before a search runs. Default 250. */
+    debounceMs?: number;
+    /** Below this many characters (trimmed) nothing is searched. Default 1. */
+    minQueryLength?: number;
+};
+export type AsyncSearch<T> = {
+    /** The current state; `onChange` receives each new one. */
+    readonly state: AsyncSearchState<T>;
+    /** Search `query` (trimmed) once typing pauses; a short one resets to idle at once. */
+    request: (query: string) => void;
+    /** Run the pending search now. */
+    flush: () => void;
+    /** Drop the pending search and abort the one in flight. */
+    cancel: () => void;
+    /** Swap the search, the debounce or the minimum length. */
+    configure: (config: Partial<AsyncSearchConfig<T>>) => void;
+};
+export declare const DEFAULT_SEARCH_DEBOUNCE_MS = 250;
+export declare const DEFAULT_MIN_QUERY_LENGTH = 1;
+/**
+ * A debounced search whose responses can never arrive out of order: each run
+ * aborts the one before it (its `signal`), and a response that still lands
+ * for an older run is dropped, so a slow first query never overwrites the
+ * results of a faster second one. An abort is not an error.
+ */
+export declare function createAsyncSearch<T>(config: AsyncSearchConfig<T>, onChange: (state: AsyncSearchState<T>) => void): AsyncSearch<T>;
+//# sourceMappingURL=async-search.d.ts.map

package/dist/lib/async-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-search.d.ts","sourceRoot":"","sources":["../../src/lib/async-search.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,kBAAkB,EACvB,kBAAkB,GAClB,MAAM,uBAAuB,CAAC;AAE/B,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAEpD,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CACzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,KAClB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzE,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IAClC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACpC,uFAAuF;IACvF,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,kCAAkC;IAClC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,2DAA2D;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC3D,CAAC;AAEF,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAQ1C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAClC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC5B,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC5C,WAAW,CAAC,CAAC,CAAC,CAEhB"}

package/dist/lib/async-search.js

@@ -0,0 +1,116 @@
+import {
+  debounce2
+} from "../chunks/index-f24x24a8.js";
+
+// src/lib/search-announcement.ts
+function searchAnnouncement(list) {
+  if (list.failed)
+    return { kind: "error" };
+  if (list.loading)
+    return { kind: "loading" };
+  return list.settled ? { kind: "results", count: list.count } : null;
+}
+
+// src/lib/async-search.ts
+var DEFAULT_SEARCH_DEBOUNCE_MS = 250;
+var DEFAULT_MIN_QUERY_LENGTH = 1;
+var idle = () => ({
+  status: "idle",
+  query: "",
+  results: []
+});
+function createAsyncSearch(config, onChange) {
+  return new AsyncSearchRunner(config, onChange);
+}
+
+class AsyncSearchRunner {
+  #config;
+  #onChange;
+  #state;
+  #controller;
+  #ticket;
+  #pending;
+  #pendingMs;
+  constructor(config, onChange) {
+    this.#state = idle();
+    this.#ticket = 0;
+    this.#config = config;
+    this.#onChange = onChange;
+  }
+  get state() {
+    return this.#state;
+  }
+  request(text) {
+    const query = text.trim();
+    const min = this.#config.minQueryLength ?? DEFAULT_MIN_QUERY_LENGTH;
+    if (query.length < min) {
+      this.cancel();
+      if (this.#state.status !== "idle")
+        this.#set(idle());
+      return;
+    }
+    const { status } = this.#state;
+    if ((status === "loading" || status === "success") && this.#state.query === query) {
+      this.#pending?.cancel();
+      return;
+    }
+    this.#debounced()(query);
+  }
+  flush() {
+    this.#pending?.flush();
+  }
+  cancel() {
+    this.#pending?.cancel();
+    this.#abort();
+    if (this.#state.status === "loading")
+      this.#set(idle());
+  }
+  configure(config) {
+    this.#config = { ...this.#config, ...config };
+  }
+  #set(next) {
+    this.#state = next;
+    this.#onChange(next);
+  }
+  #abort() {
+    this.#ticket += 1;
+    this.#controller?.abort();
+    this.#controller = undefined;
+  }
+  #debounced() {
+    const ms = this.#config.debounceMs ?? DEFAULT_SEARCH_DEBOUNCE_MS;
+    if (!this.#pending || this.#pendingMs !== ms) {
+      this.#pending?.cancel();
+      this.#pending = debounce2((query) => void this.#run(query), ms);
+      this.#pendingMs = ms;
+    }
+    return this.#pending;
+  }
+  async#run(query) {
+    this.#abort();
+    const own = new AbortController;
+    this.#controller = own;
+    const ticket = this.#ticket;
+    this.#set({ status: "loading", query, results: this.#state.results });
+    try {
+      const results = await this.#config.search(query, { signal: own.signal });
+      if (ticket === this.#ticket)
+        this.#set({ status: "success", query, results });
+    } catch (error) {
+      if (ticket === this.#ticket && !own.signal.aborted)
+        this.#set({ status: "error", query, results: [], error });
+    } finally {
+      if (this.#controller === own)
+        this.#controller = undefined;
+    }
+  }
+}
+export {
+  DEFAULT_MIN_QUERY_LENGTH,
+  DEFAULT_SEARCH_DEBOUNCE_MS,
+  createAsyncSearch,
+  searchAnnouncement
+};
+
+//# debugId=DF9F6FB2BDDD168C64756E2164756E21
+//# sourceMappingURL=async-search.js.map

package/dist/lib/async-search.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/search-announcement.ts", "../src/lib/async-search.ts"],
+  "sourcesContent": [
+    "/** What a combobox's polite live region says about its list, if anything. */\nexport type SearchAnnouncement =\n\t| { kind: 'loading' }\n\t| { kind: 'error' }\n\t| { kind: 'results'; count: number };\n\n/**\n * The announcement for a list: its failure, else that it is loading, else\n * its count once the query has `settled` (searched, or typing paused) —\n * `null` while the user is still typing, so a screen reader is not told\n * about every keystroke.\n */\nexport function searchAnnouncement(list: {\n\tloading: boolean;\n\tfailed: boolean;\n\tsettled: boolean;\n\tcount: number;\n}): SearchAnnouncement | null {\n\tif (list.failed) return { kind: 'error' };\n\tif (list.loading) return { kind: 'loading' };\n\treturn list.settled ? { kind: 'results', count: list.count } : null;\n}\n",
+    "import { type Debounced, debounce } from './debounce';\n\nexport {\n\ttype SearchAnnouncement,\n\tsearchAnnouncement,\n} from './search-announcement';\n\n/** What a search is handed besides the query: aborted once it is stale. */\nexport type SearchContext = { signal: AbortSignal };\n\n/** A server search: the options for `query`. Pass `signal` on to `fetch`. */\nexport type SearchFn<T> = (\n\tquery: string,\n\tcontext: SearchContext,\n) => Promise<T[]>;\n\nexport type AsyncSearchStatus = 'idle' | 'loading' | 'success' | 'error';\n\nexport type AsyncSearchState<T> = {\n\tstatus: AsyncSearchStatus;\n\t/** The query being searched (loading) or the one `results` answer. */\n\tquery: string;\n\t/** The last results. Kept while the next query loads; `[]` when idle. */\n\tresults: T[];\n\t/** What the search rejected with (`status: 'error'`). */\n\terror?: unknown;\n};\n\nexport type AsyncSearchConfig<T> = {\n\tsearch: SearchFn<T>;\n\t/** How long typing must pause before a search runs. Default 250. */\n\tdebounceMs?: number;\n\t/** Below this many characters (trimmed) nothing is searched. Default 1. */\n\tminQueryLength?: number;\n};\n\nexport type AsyncSearch<T> = {\n\t/** The current state; `onChange` receives each new one. */\n\treadonly state: AsyncSearchState<T>;\n\t/** Search `query` (trimmed) once typing pauses; a short one resets to idle at once. */\n\trequest: (query: string) => void;\n\t/** Run the pending search now. */\n\tflush: () => void;\n\t/** Drop the pending search and abort the one in flight. */\n\tcancel: () => void;\n\t/** Swap the search, the debounce or the minimum length. */\n\tconfigure: (config: Partial<AsyncSearchConfig<T>>) => void;\n};\n\nexport const DEFAULT_SEARCH_DEBOUNCE_MS = 250;\nexport const DEFAULT_MIN_QUERY_LENGTH = 1;\n\nconst idle = <T>(): AsyncSearchState<T> => ({\n\tstatus: 'idle',\n\tquery: '',\n\tresults: [],\n});\n\n/**\n * A debounced search whose responses can never arrive out of order: each run\n * aborts the one before it (its `signal`), and a response that still lands\n * for an older run is dropped, so a slow first query never overwrites the\n * results of a faster second one. An abort is not an error.\n */\nexport function createAsyncSearch<T>(\n\tconfig: AsyncSearchConfig<T>,\n\tonChange: (state: AsyncSearchState<T>) => void,\n): AsyncSearch<T> {\n\treturn new AsyncSearchRunner(config, onChange);\n}\n\nclass AsyncSearchRunner<T> implements AsyncSearch<T> {\n\t#config: AsyncSearchConfig<T>;\n\t#onChange: (state: AsyncSearchState<T>) => void;\n\t#state: AsyncSearchState<T> = idle();\n\t#controller: AbortController | undefined;\n\t/** Bumped by every run and every abort: a response for an older one is stale. */\n\t#ticket = 0;\n\t#pending: Debounced<[string]> | undefined;\n\t#pendingMs: number | undefined;\n\n\tconstructor(\n\t\tconfig: AsyncSearchConfig<T>,\n\t\tonChange: (state: AsyncSearchState<T>) => void,\n\t) {\n\t\tthis.#config = config;\n\t\tthis.#onChange = onChange;\n\t}\n\n\tget state() {\n\t\treturn this.#state;\n\t}\n\n\trequest(text: string) {\n\t\t// \"pa\" and \"pa \" are one search, and the server never sees the space.\n\t\tconst query = text.trim();\n\t\tconst min = this.#config.minQueryLength ?? DEFAULT_MIN_QUERY_LENGTH;\n\t\tif (query.length < min) {\n\t\t\tthis.cancel();\n\t\t\tif (this.#state.status !== 'idle') this.#set(idle());\n\t\t\treturn;\n\t\t}\n\t\tconst { status } = this.#state;\n\t\tif (\n\t\t\t(status === 'loading' || status === 'success') &&\n\t\t\tthis.#state.query === query\n\t\t) {\n\t\t\tthis.#pending?.cancel();\n\t\t\treturn;\n\t\t}\n\t\tthis.#debounced()(query);\n\t}\n\n\tflush() {\n\t\tthis.#pending?.flush();\n\t}\n\n\tcancel() {\n\t\tthis.#pending?.cancel();\n\t\tthis.#abort();\n\t\tif (this.#state.status === 'loading') this.#set(idle());\n\t}\n\n\tconfigure(config: Partial<AsyncSearchConfig<T>>) {\n\t\tthis.#config = { ...this.#config, ...config };\n\t}\n\n\t#set(next: AsyncSearchState<T>) {\n\t\tthis.#state = next;\n\t\tthis.#onChange(next);\n\t}\n\n\t#abort() {\n\t\tthis.#ticket += 1;\n\t\tthis.#controller?.abort();\n\t\tthis.#controller = undefined;\n\t}\n\n\t#debounced() {\n\t\tconst ms = this.#config.debounceMs ?? DEFAULT_SEARCH_DEBOUNCE_MS;\n\t\tif (!this.#pending || this.#pendingMs !== ms) {\n\t\t\tthis.#pending?.cancel();\n\t\t\tthis.#pending = debounce((query: string) => void this.#run(query), ms);\n\t\t\tthis.#pendingMs = ms;\n\t\t}\n\t\treturn this.#pending;\n\t}\n\n\tasync #run(query: string) {\n\t\tthis.#abort();\n\t\tconst own = new AbortController();\n\t\tthis.#controller = own;\n\t\tconst ticket = this.#ticket;\n\t\tthis.#set({ status: 'loading', query, results: this.#state.results });\n\t\ttry {\n\t\t\tconst results = await this.#config.search(query, { signal: own.signal });\n\t\t\tif (ticket === this.#ticket)\n\t\t\t\tthis.#set({ status: 'success', query, results });\n\t\t} catch (error) {\n\t\t\tif (ticket === this.#ticket && !own.signal.aborted)\n\t\t\t\tthis.#set({ status: 'error', query, results: [], error });\n\t\t} finally {\n\t\t\tif (this.#controller === own) this.#controller = undefined;\n\t\t}\n\t}\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "DF9F6FB2BDDD168C64756E2164756E21",
+  "names": []
+}

package/dist/lib/debounce.d.ts

@@ -0,0 +1,6 @@
+export type Debounced<Args extends unknown[]> = ((...args: Args) => void) & {
+    cancel: () => void;
+    flush: () => void;
+};
+export declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, ms: number): Debounced<Args>;
+//# sourceMappingURL=debounce.d.ts.map

package/dist/lib/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/lib/debounce.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG;IAC3E,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,SAAS,OAAO,EAAE,EAC9C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,EAAE,EAAE,MAAM,GACR,SAAS,CAAC,IAAI,CAAC,CAgCjB"}

package/dist/lib/debounce.js

@@ -0,0 +1,9 @@
+import {
+  debounce2
+} from "../chunks/index-f24x24a8.js";
+export {
+  debounce2 as debounce
+};
+
+//# debugId=D4F68C57810F89B764756E2164756E21
+//# sourceMappingURL=debounce.js.map

package/dist/lib/debounce.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "D4F68C57810F89B764756E2164756E21",
+  "names": []
+}

package/dist/lib/search-announcement.d.ts

@@ -0,0 +1,22 @@
+/** What a combobox's polite live region says about its list, if anything. */
+export type SearchAnnouncement = {
+    kind: 'loading';
+} | {
+    kind: 'error';
+} | {
+    kind: 'results';
+    count: number;
+};
+/**
+ * The announcement for a list: its failure, else that it is loading, else
+ * its count once the query has `settled` (searched, or typing paused) —
+ * `null` while the user is still typing, so a screen reader is not told
+ * about every keystroke.
+ */
+export declare function searchAnnouncement(list: {
+    loading: boolean;
+    failed: boolean;
+    settled: boolean;
+    count: number;
+}): SearchAnnouncement | null;
+//# sourceMappingURL=search-announcement.d.ts.map

package/dist/lib/search-announcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-announcement.d.ts","sourceRoot":"","sources":["../../src/lib/search-announcement.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACd,GAAG,kBAAkB,GAAG,IAAI,CAI5B"}

package/dist/lib/text-match.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Accent- and case-insensitive text matching, for a list filtered as the user
+ * types: `'e'` finds "École", `'ecole'` finds "ÉCOLE".
+ */
+/**
+ * `text` lowercased for `locale` (the runtime's when omitted), then without
+ * its diacritics: `foldText('Élève')` is `'eleve'`. Lowercasing comes first,
+ * so a Turkish `'İ'` (`'tr'`) folds to `'i'` rather than keeping a dot.
+ */
+export declare function foldText(text: string, locale?: string): string;
+/**
+ * Whether `query` occurs in `text`, ignoring case and accents. A query of
+ * spaces only matches everything, as an empty one does.
+ */
+export declare function matchesText(text: string, query: string, locale?: string): boolean;
+//# sourceMappingURL=text-match.d.ts.map

package/dist/lib/text-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-match.d.ts","sourceRoot":"","sources":["../../src/lib/text-match.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9D;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAIT"}

package/dist/lib/text-match.js

@@ -0,0 +1,25 @@
+// src/lib/text-match.ts
+var DIACRITICS = /[̀-ͯ]/g;
+function foldText(text, locale) {
+  return lowercase(text, locale).normalize("NFD").replace(DIACRITICS, "");
+}
+function lowercase(text, locale) {
+  try {
+    return text.toLocaleLowerCase(locale);
+  } catch {
+    return text.toLocaleLowerCase();
+  }
+}
+function matchesText(text, query, locale) {
+  const needle = foldText(query.trim(), locale);
+  if (!needle)
+    return true;
+  return foldText(text, locale).includes(needle);
+}
+export {
+  foldText,
+  matchesText
+};
+
+//# debugId=FCBE43FC1537D3D864756E2164756E21
+//# sourceMappingURL=text-match.js.map

package/dist/lib/text-match.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/text-match.ts"],
+  "sourcesContent": [
+    "/**\n * Accent- and case-insensitive text matching, for a list filtered as the user\n * types: `'e'` finds \"École\", `'ecole'` finds \"ÉCOLE\".\n */\n\n/** Combining diacritical marks, which `normalize('NFD')` splits from their letter. */\nconst DIACRITICS = /[̀-ͯ]/g;\n\n/**\n * `text` lowercased for `locale` (the runtime's when omitted), then without\n * its diacritics: `foldText('Élève')` is `'eleve'`. Lowercasing comes first,\n * so a Turkish `'İ'` (`'tr'`) folds to `'i'` rather than keeping a dot.\n */\nexport function foldText(text: string, locale?: string): string {\n\treturn lowercase(text, locale).normalize('NFD').replace(DIACRITICS, '');\n}\n\nfunction lowercase(text: string, locale?: string): string {\n\ttry {\n\t\treturn text.toLocaleLowerCase(locale);\n\t} catch {\n\t\t// An invalid language tag: the runtime's own rules, never a throw.\n\t\treturn text.toLocaleLowerCase();\n\t}\n}\n\n/**\n * Whether `query` occurs in `text`, ignoring case and accents. A query of\n * spaces only matches everything, as an empty one does.\n */\nexport function matchesText(\n\ttext: string,\n\tquery: string,\n\tlocale?: string,\n): boolean {\n\tconst needle = foldText(query.trim(), locale);\n\tif (!needle) return true;\n\treturn foldText(text, locale).includes(needle);\n}\n"
+  ],
+  "mappings": ";AAMA,IAAM,aAAa;AAOZ,SAAS,QAAQ,CAAC,MAAc,QAAyB;AAAA,EAC/D,OAAO,UAAU,MAAM,MAAM,EAAE,UAAU,KAAK,EAAE,QAAQ,YAAY,EAAE;AAAA;AAGvE,SAAS,SAAS,CAAC,MAAc,QAAyB;AAAA,EACzD,IAAI;AAAA,IACH,OAAO,KAAK,kBAAkB,MAAM;AAAA,IACnC,MAAM;AAAA,IAEP,OAAO,KAAK,kBAAkB;AAAA;AAAA;AAQzB,SAAS,WAAW,CAC1B,MACA,OACA,QACU;AAAA,EACV,MAAM,SAAS,SAAS,MAAM,KAAK,GAAG,MAAM;AAAA,EAC5C,IAAI,CAAC;AAAA,IAAQ,OAAO;AAAA,EACpB,OAAO,SAAS,MAAM,MAAM,EAAE,SAAS,MAAM;AAAA;",
+  "debugId": "FCBE43FC1537D3D864756E2164756E21",
+  "names": []
+}

package/docs/roadmap.md

@@ -51,6 +51,11 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **Debounce, text matching and the async search** (`/debounce`,
+  `/text-match`, `/async-search`) — the debounce both libraries'
+  `SearchField` kept a copy of each, accent- and case-insensitive matching,
+  and a debounced search that aborts the previous run and drops a stale
+  response, behind both libraries' `Autocomplete` server search. 0.8.0.
 - **The focus a toast's action hands back** (`/toast-focus`) — where the
   focus was before it entered a toast, given back before the action runs, so
   a dialog the action opens keeps the focus in both libraries. 0.7.0.

package/package.json

@@ -1,11 +1,16 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.7.1",
-	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard and its focus hand-back, the zod issue messages, the date range presets, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
+	"version": "0.8.0",
+	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard and its focus hand-back, the zod issue messages, the date range presets, the debounce, accent-insensitive text matching and the race-free async search behind Autocomplete and SearchField, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
 	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-material.git",
+		"directory": "packages/core"
+	},
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -153,6 +158,21 @@
 			"import": "./dist/lib/date-range.js",
 			"default": "./dist/lib/date-range.js"
 		},
+		"./debounce": {
+			"types": "./dist/lib/debounce.d.ts",
+			"import": "./dist/lib/debounce.js",
+			"default": "./dist/lib/debounce.js"
+		},
+		"./text-match": {
+			"types": "./dist/lib/text-match.d.ts",
+			"import": "./dist/lib/text-match.js",
+			"default": "./dist/lib/text-match.js"
+		},
+		"./async-search": {
+			"types": "./dist/lib/async-search.d.ts",
+			"import": "./dist/lib/async-search.js",
+			"default": "./dist/lib/async-search.js"
+		},
 		"./file-preview": {
 			"types": "./dist/file-preview/index.d.ts",
 			"import": "./dist/file-preview/index.js",
@@ -229,6 +249,9 @@
 			"src/lib/slider-ticks.ts",
 			"src/lib/emoji-groups.ts",
 			"src/lib/date-range.ts",
+			"src/lib/debounce.ts",
+			"src/lib/text-match.ts",
+			"src/lib/async-search.ts",
 			"src/file-preview/index.ts",
 			"src/pdf-viewer/index.ts",
 			"src/vite/index.ts",