@samline/autocomplete 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@samline/autocomplete` are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - Unreleased
+
+Sources beyond HTTP, caching, highlighting, a stricter listbox and the registry shared by the other `@samline` packages.
+
+### Breaking
+
+- The browser registry follows the shared `@samline` shape: `newAutocomplete({ id, options })`, `getAutocomplete(id)`, `getAutocompletes()`, `destroyAutocomplete(idOrInput)` and `destroyAutocompletes()` replace `create(target, options)` and `destroy(id)`. `newAutocomplete` logs and returns `null` instead of throwing when the id or input is missing.
+- `@samline/autocomplete/browser` is now the registry as an ESM/CommonJS module. The standalone script moved to `@samline/autocomplete/browser/global` (the file is still `dist/browser/global.global.js`).
+- Options are `<div role="option">` elements instead of `<button>`, so they are no longer Tab stops. `renderOption` receives an `HTMLElement` and a third `context` argument.
+- The listbox now sits inside `[data-autocomplete-popup]`, which carries the positioning styles. Loading, empty and error messages render in `[data-autocomplete-status]` outside the listbox, instead of inside it with `role="status"` / `role="alert"`; a separate polite live region announces them. Update selectors that targeted `[data-autocomplete-list]` for positioning.
+- Labels are highlighted by default. Set `highlight: false` for plain text.
+- Function and endpoint results are cached per query for five minutes by default. Set `cache: false` for the previous behavior.
+- `createAutocompleteController` is removed; use `createAutocomplete` or `autocomplete`.
+- The default label and value also read a `name` field.
+
+### Added
+
+- `source`: a local array filtered in the browser, or `(query, { signal, input }) => items`, as an alternative to `endpoint`. Array sources default to `minLength: 1` and `debounce: 0`.
+- `filter` and `normalize` options; matching ignores case and accents by default.
+- `cache` (`true`, `false` or `{ max, ttl }`) and `controller.clearCache()`. `autocomplete:load` reports `cached`.
+- `highlight` option and `<mark data-autocomplete-highlight>` rendering. `renderOption` context `{ query, index, label, highlight }`.
+- `messages.results` and message functions of `{ query, count }` for translations and plurals.
+- Controller `popupElement`, `statusElement` and `liveElement`. The listbox is labelled by the input's `<label>`.
+- Helpers `fromEndpoint`, `filterSuggestions`, `normalizeText`, `highlight`, `renderHighlight`, `createCache` and `DEFAULT_MESSAGES`.
+- Entrypoints `@samline/autocomplete/core`, `@samline/autocomplete/vanilla` and the `style.css` alias.
+- Stylesheet: highlight custom properties and a forced-colors outline for the active option.
+- A "Local data" example.
+
 ## [1.0.0] - 2026-11-13
 
 First public release.
@@ -20,4 +48,5 @@ First public release.
 - Escape, Tab, clicking outside, selecting a suggestion and `close()` cancel the pending debounced search and abort the request in flight. Before, a late response reopened the list after it was dismissed.
 - The standalone script defines `window.Autocomplete` with its documented members. Before, the global was wrapped as `{ default }`.
 
+[2.0.0]: https://github.com/samline/autocomplete/compare/v1.0.0...HEAD
 [1.0.0]: https://github.com/samline/autocomplete/releases/tag/v1.0.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 samline
+Copyright (c) 2026 Samuel Olvera (samline)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # @samline/autocomplete
 
-An accessible, framework-agnostic remote autocomplete (combobox) for vanilla JavaScript, TypeScript and plain HTML. Point an input at your endpoint; debounce, cancellation, keyboard navigation, events and cleanup are handled for you.
+An accessible, framework-agnostic autocomplete (combobox) for vanilla JavaScript, TypeScript and plain HTML. Point an input at an endpoint, an async function or a local array; debounce, cancellation, caching, accent-insensitive matching, highlighting, keyboard navigation, screen reader announcements, events and cleanup are handled for you.
 
 [Demo](https://samline.github.io/autocomplete/) · [Examples](https://samline.github.io/autocomplete/examples/) · [Documentation](https://samline.github.io/autocomplete/docs/) · [Changelog](CHANGELOG.md)
 
@@ -30,7 +30,13 @@ pnpm add @samline/autocomplete
 bun add @samline/autocomplete
 ```
 
-Works in modern browsers with `fetch` and `AbortController`, and imports in Node 20 or newer. No runtime dependencies; the stylesheet is optional.
+Requires Node 20+ when bundling. Runs in modern browsers with `fetch` and `AbortController`. No runtime dependencies.
+
+Import the optional stylesheet once in your application entrypoint:
+
+```js
+import '@samline/autocomplete/styles.css'
+```
 
 ## Quick start
 
@@ -52,69 +58,239 @@ const controller = createAutocomplete('#city', {
   onSelect: city => console.log('Selected', city),
 })
 
-controller.destroy() // removes the list and restores the input
+// When the owning component or page leaves:
+controller.destroy()
 ```
 
+What this does:
+
+- Turns the existing input into an ARIA combobox and renders a popup with a listbox right after it.
+- Searches once the query reaches two characters, 250 ms after typing stops, and caches each query's results for five minutes.
+- Reads a root array, or a `suggestions`, `items` or `data` array, from the JSON response.
+- Highlights the typed words in each label and announces the result count to screen readers.
+- Writes the chosen suggestion into the input, dispatches `autocomplete:select` and calls `onSelect`.
+- Restores the input attributes it changed and removes the list when `destroy()` runs.
+
+The wrapper needs `position: relative` because the default popup is absolutely positioned under the input.
+
 ## HTML / CDN
 
-For Shopify, WordPress or plain HTML pages without a build step, load the stylesheet and the browser bundle. Pin the version in production.
+Choose **Package / ESM** when installing with npm, pnpm or bun and importing Autocomplete in your application. Choose **HTML / CDN** for Shopify, WordPress or plain HTML pages without a build step. Both use the same options and controller.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/autocomplete@1.0.0/dist/styles.css" />
-<script src="https://cdn.jsdelivr.net/npm/@samline/autocomplete@1.0.0/dist/browser/global.global.js"></script>
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@samline/autocomplete@2.0.0/dist/styles.css"
+/>
+<script src="https://cdn.jsdelivr.net/npm/@samline/autocomplete@2.0.0/dist/browser/global.global.js"></script>
+```
+
+> Pin the version in production, or self-host the same files.
+
+The standalone script (an IIFE) defines `window.Autocomplete`:
+
+```html
+<div class="field" style="position: relative">
+  <label for="city">City</label>
+  <input id="city" type="text" />
+</div>
+
 <script>
-  window.Autocomplete.create('#city', { endpoint: '/api/cities' })
+  const city = window.Autocomplete.newAutocomplete({
+    id: 'city',
+    options: { endpoint: '/api/cities' },
+  })
 </script>
 ```
 
-`window.Autocomplete` has `create(target, options)` (requires an input id and registers the controller), `destroy(id)`, `available` and `autocomplete(target, options)`.
+The global follows the same registry shape as the other `@samline` packages:
+
+| Member                                   | Purpose                                                            |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| `newAutocomplete({ id, options })`       | Enhances the input with that id; replaces a previous registration. |
+| `getAutocomplete(id)`                    | The registered controller, or `null`.                              |
+| `getAutocompletes()`                     | A copy of every registered controller by id.                       |
+| `destroyAutocomplete(idOrInput)`         | Destroys one registered controller.                                |
+| `destroyAutocompletes()`                 | Destroys them all.                                                 |
+| `available`, `autocomplete(input, opts)` | The live registry, and a factory that bypasses it.                 |
+
+`newAutocomplete` logs and returns `null` when the id is empty or no input has it.
 
 ## Capabilities
 
+- Three kinds of source: an HTTP endpoint, an async function (SDKs, GraphQL, workers) or a local array.
+- Any response shape through `parseResponse`, `mapResponse`, `getId`, `getLabel` and `getValue`.
+- Accent- and case-insensitive matching: `merida` finds `Mérida`.
+- Highlighted matches rendered as `<mark>` elements, never HTML strings.
+- A per-query LRU cache with expiry for function and endpoint sources.
+- WAI-ARIA combobox and listbox with full keyboard operation and a polite live region.
+- Debounced searches, aborted superseded requests and ignored late responses.
+- Bubbling DOM events that keep hidden fields and other UI in sync.
+- An optional stylesheet themed with `--autocomplete-*` custom properties.
+- React, Vue, Svelte, Shopify and WordPress through the same API, with no adapter.
+
+[Working examples](https://samline.github.io/autocomplete/examples/) cover remote search, custom options, events and local data, each with copyable files.
+
+### Any source
+
+Pass exactly one of `source` or `endpoint`.
+
+```js
+// A local array, filtered in the browser (minLength 1, no debounce by default).
+createAutocomplete('#state', { source: ['Michoacán', 'Nuevo León', 'Querétaro'] })
+
+// Any async function. Pass the signal on so dismissed searches abort.
+createAutocomplete('#user', {
+  source: (query, { signal }) => api.users.search(query, { signal }),
+  getLabel: user => user.name,
+})
+```
+
+`filter(item, query)` replaces the local match, and `normalize(text)` replaces the accent- and case-insensitive comparison used by the filter and the highlighting.
+
 ### Any endpoint, any response
 
-`endpoint` is a URL or a function of the query. `requestInit` adds headers or credentials, `parseResponse` replaces JSON parsing, and `mapResponse`, `getId`, `getLabel` and `getValue` adapt whatever your API returns.
+`endpoint` is a URL or a function of the query. `queryParam` names the query-string key (`q` by default; `null` when the function builds the complete URL). `requestInit` adds headers or credentials, `parseResponse` replaces JSON parsing, and `mapResponse` returns the suggestion array.
+
+```js
+createAutocomplete('#city', {
+  endpoint: query => `/api/search?term=${encodeURIComponent(query)}`,
+  queryParam: null,
+  requestInit: { headers: { Authorization: `Bearer ${token}` } },
+  mapResponse: payload => payload.data.items,
+  getLabel: item => item.title,
+})
+```
+
+### Caching
+
+Function and endpoint results are cached per query: up to 50 queries for five minutes, least recently used first out. Failures are never cached.
+
+```js
+createAutocomplete('#city', { endpoint: '/api/cities', cache: { max: 100, ttl: 60_000 } })
+createAutocomplete('#stock', { endpoint: '/api/stock', cache: false })
+```
+
+Call `controller.clearCache()` after the data changes. `autocomplete:load` reports `cached: true` for cache hits.
+
+### Highlighting and custom options
+
+Each label is split into matching and non-matching parts and rendered with `<mark data-autocomplete-highlight>`; set `highlight: false` to render plain text. `renderOption(element, item, context)` receives `{ query, index, label, highlight }` to append your own DOM nodes, never HTML strings.
+
+```js
+import { createAutocomplete, renderHighlight } from '@samline/autocomplete'
+
+createAutocomplete('#city', {
+  endpoint: '/api/cities',
+  renderOption: (option, city, { highlight }) => {
+    option.replaceChildren()
+    const name = document.createElement('strong')
+    renderHighlight(name, highlight)
+    const country = document.createElement('small')
+    country.textContent = city.country
+    option.append(name, country)
+  },
+})
+```
+
+`highlight(text, query)`, `filterSuggestions(items, query, { getText })` and `normalizeText(text)` are exported for your own rendering and filtering.
 
 ### An accessible combobox
 
-ARIA `combobox` and `listbox` roles, `aria-expanded` and `aria-activedescendant`, status and error messages, and ArrowUp, ArrowDown, Home, End, Enter, Escape and Tab. Searches wait for IME composition to finish.
+ARIA `combobox` and `listbox` roles, `aria-expanded`, `aria-activedescendant` and a labelled listbox, and ArrowUp, ArrowDown, Home, End, Enter, Escape and Tab. Options are non-focusable `role="option"` elements. Loading, empty and error states are shown outside the listbox, and results, empty and error messages are announced through a polite live region. Searches wait for IME composition to finish.
 
-### No stale results
+Every message is a string or a function of `{ query, count }`:
 
-Searches are debounced, superseded requests are aborted and late responses ignored. Closing the list (Escape, Tab, clicking outside, selecting or `close()`) cancels the pending search.
+```js
+createAutocomplete('#ciudad', {
+  endpoint: '/api/ciudades',
+  messages: {
+    loading: 'Buscando…',
+    empty: ({ query }) => `Sin resultados para «${query}»`,
+    error: 'La búsqueda falló',
+    results: ({ count }) => (count === 1 ? '1 resultado' : `${count} resultados`),
+  },
+})
+```
 
-### Events and styling
+### No stale results
 
-`autocomplete:select`, `autocomplete:clear`, `autocomplete:load`, `autocomplete:loadstart` and `autocomplete:error` bubble from the input. The optional stylesheet is themed with `--autocomplete-*` custom properties, and `renderOption` adds your own content to each option.
+Searches are debounced, superseded requests are aborted and late responses ignored. Closing the list (Escape, Tab, clicking outside, selecting or `close()`) cancels the pending search.
 
 ## API at a glance
 
-| API | Purpose |
-| --- | --- |
-| `createAutocomplete(input, options)` | Attach the combobox and return a controller (`autocomplete` is an alias). |
-| `controller.search(query?)` / `close()` / `clear()` / `cancel()` | Run a search now, close the list, clear everything or cancel pending work. |
-| `controller.getSelected()` / `destroy()` | Read the selected suggestion or remove the combobox. |
-| `mapCommonResponse`, `parseJsonResponse` | The default response mapper and parser. |
+| API                                      | Purpose                                                |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `createAutocomplete(input, options)`     | Controller factory (`autocomplete` is an alias).       |
+| `search(query?)`, `close()`, `cancel()`  | Run a search now, close the list, cancel pending work. |
+| `clear()`, `getSelected()`               | Clear input and selection, or read the selected item.  |
+| `clearCache()`                           | Forget cached results.                                 |
+| `destroy()`                              | Cleanup.                                               |
+| `fromEndpoint(options)`                  | Build a reusable endpoint source function.             |
+| `highlight`, `renderHighlight`           | Split a label into matches, and render the parts.      |
+| `filterSuggestions`, `normalizeText`     | The default local filter and text normalizer.          |
+| `createCache(options?)`                  | The LRU cache used per instance.                       |
+| `mapCommonResponse`, `parseJsonResponse` | The default response mapper and parser.                |
+| `Autocomplete`, `browser`                | Importable equivalent of `window.Autocomplete`.        |
+
+The controller also exposes `element` (the input), `popupElement`, `listElement` (the listbox), `statusElement`, `liveElement` and `options`.
 
 ### Entrypoints
 
-| Entrypoint | When to use |
-| --- | --- |
-| `@samline/autocomplete` | ESM or CommonJS: `createAutocomplete`, helpers, `browser` registry and types. |
-| `@samline/autocomplete/browser` | Classic script that defines `window.Autocomplete`. |
-| `@samline/autocomplete/styles.css` | Optional base stylesheet. |
+| Entrypoint                             | When to use                                                   |
+| -------------------------------------- | ------------------------------------------------------------- |
+| `@samline/autocomplete`                | ESM or CommonJS: everything below, side-effect free.          |
+| `@samline/autocomplete/core`           | DOM-free helpers: sources, cache, filtering, highlighting.    |
+| `@samline/autocomplete/vanilla`        | The DOM factory and `renderHighlight`.                        |
+| `@samline/autocomplete/browser`        | The registry as a module (`Autocomplete`, `newAutocomplete`). |
+| `@samline/autocomplete/browser/global` | Standalone script (IIFE) that defines `window.Autocomplete`.  |
+| `@samline/autocomplete/styles.css`     | Optional base stylesheet (also `style.css`).                  |
+
+### Events
+
+All events bubble from the input.
+
+| Event                    | `detail`                         |
+| ------------------------ | -------------------------------- |
+| `autocomplete:loadstart` | `{ query }`                      |
+| `autocomplete:load`      | `{ query, suggestions, cached }` |
+| `autocomplete:error`     | `{ query, error }`               |
+| `autocomplete:select`    | `{ suggestion, label, value }`   |
+| `autocomplete:clear`     | `{ query }`                      |
+
+```js
+const input = document.querySelector('#city')
+const hidden = document.querySelector('#city-id')
+
+input.addEventListener('autocomplete:select', event => {
+  hidden.value = event.detail.suggestion.id
+})
+input.addEventListener('autocomplete:clear', () => (hidden.value = ''))
+```
+
+### One lifecycle
+
+- Each `createAutocomplete()` call owns one input. Keep the returned controller.
+- `close()` and `cancel()` keep the controller usable; `clear()` also empties the input and dispatches `autocomplete:clear` when something was selected.
+- `destroy()` aborts pending work, removes the list and listeners, and restores the input attributes. Repeated calls are harmless.
+- With the registry, `newAutocomplete()` on an id that is already registered destroys the previous controller first, and a direct `destroy()` also unregisters it.
+
+### TypeScript
+
+The package includes declarations. Pass your suggestion type to `createAutocomplete<T>()` to type `getLabel`, `onSelect`, `renderOption` and `getSelected()`. `AutocompleteOptions<T>`, `AutocompleteController<T>` and the event detail types are exported; see the [API reference](https://samline.github.io/autocomplete/docs/reference/api/#types).
 
 ## Documentation
 
 Read the [documentation](https://samline.github.io/autocomplete/docs/) for the full guides and API contracts, and explore [working examples](https://samline.github.io/autocomplete/examples/) with complete and separate source files.
 
-| Guide | What it covers |
-| --- | --- |
-| [Installation](https://samline.github.io/autocomplete/docs/getting-started/) | Package / ESM, HTML / CDN and working starter files. |
-| [Options](https://samline.github.io/autocomplete/docs/reference/configuration/) | Every option and its default. |
-| [API reference](https://samline.github.io/autocomplete/docs/reference/api/) | The controller, helpers, browser global and events. |
-| [Accessibility](https://samline.github.io/autocomplete/docs/guides/accessibility/) | What the combobox provides and what your page provides. |
-| [Styling](https://samline.github.io/autocomplete/docs/guides/styling/) | The DOM contract and the custom properties. |
+| Guide                                                                              | What it covers                                           |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [Installation](https://samline.github.io/autocomplete/docs/getting-started/)       | Package / ESM, HTML / CDN, frameworks and starter files. |
+| [Examples](https://samline.github.io/autocomplete/docs/guides/examples/)           | Live previews with their complete, copyable source.      |
+| [Options](https://samline.github.io/autocomplete/docs/reference/configuration/)    | Every option and its default.                            |
+| [API reference](https://samline.github.io/autocomplete/docs/reference/api/)        | The controller, helpers, browser global, events, types.  |
+| [Accessibility](https://samline.github.io/autocomplete/docs/guides/accessibility/) | What the combobox provides and what your page provides.  |
+| [Styling](https://samline.github.io/autocomplete/docs/guides/styling/)             | The DOM contract and the custom properties.              |
 
 ## Changelog