@skdx/web-components 0.27.0 → 0.29.0

package/dist/autocomplete/Autocomplete.d.cts

@@ -1,10 +1,26 @@
-import { LitElement } from 'lit';
-/** @internal Selector for a suggestion that is still an option and still live, mirrored from the React autocomplete util. */
+import { LitElement, type TemplateResult } from 'lit';
+import { type SkdxOptionsInput } from '../internal/options.cjs';
+/** @internal Selector for a suggestion that is still an option and still live. */
 export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
-/** @internal Event the root dispatches whenever its state moves, so every part can re-render off state it owns no attribute for. */
+/** @internal Root state change event for part re-rendering. */
 export declare const AUTOCOMPLETE_UPDATE_EVENT = "skdx-autocomplete-internal-update";
-/** Default `getSuggestionCountLabel`: `"1 suggestion available"` / `"3 suggestions available"`. */
+/**
+ * @internal Scrolls an option into view inside the popup rather than the page.
+ */
+export declare function scrollIntoPopup(content: HTMLElement, option: HTMLElement): void;
+/** Default `getResultCountLabel`: `"1 suggestion available"` / `"3 suggestions available"`. */
 export declare function defaultGetSuggestionCountLabel(count: number): string;
+/** The `detail` a `value-change` CustomEvent carries; `reason` distinguishes the trigger. */
+export interface SkdxAutocompleteValueChangeDetail {
+    /** The newly committed value. */
+    value: string;
+    /** The value held before this commit, or `null` when there was none. */
+    previousValue: string | null;
+    /** What drove the change. */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+    /** Whether the committed value was the draft text itself rather than an existing suggestion. */
+    created: boolean;
+}
 /** What an `<skdx-autocomplete-item>` registers about itself, so Enter can commit it by id. */
 export interface SkdxAutocompleteItemEntry {
     /** The value committed to the root when this suggestion is chosen. */
@@ -12,50 +28,21 @@ export interface SkdxAutocompleteItemEntry {
     /** The item's `text-value`, or its rendered text — matched by `filter`, written back into the input. */
     text: string;
 }
-/**
- * Decides which `<skdx-autocomplete-item>`s survive the current draft text.
- * `undefined` filters nothing — the consumer renders only the suggestions that
- * match, which is what an async or server-side search needs.
- */
-export type SkdxAutocompleteFilter = (itemText: string, inputValue: string) => boolean;
-declare const SkdxAutocomplete_base: typeof LitElement & (new (...args: any[]) => import("../internal/form-associated.cjs").SkdxFormAssociated) & {
+/** Filter predicate or `'manual'` (default). Predicate returning a number also ranks matches by score. */
+export type SkdxAutocompleteFilter = 'manual' | ((itemText: string, inputValue: string) => boolean | number);
+declare const SkdxAutocomplete_base: typeof LitElement & (new (...args: any[]) => import("../index.cjs").SkdxFormAssociated) & {
     formAssociated: boolean;
 };
 /**
- * `<skdx-autocomplete>` — the Web Components implementation of the shared
- * Autocomplete contract (see `@skdx/shared`'s `autocompleteContract`). A
- * WAI-ARIA 1.2 "combobox with list autocomplete" with one deliberate
- * difference from `<skdx-combobox>`: **the committed value does not have to
- * come from the list**. Type "foo", tab away, and "foo" is the answer.
- *
- * The root owns **two separate** pieces of state — the draft text in the input
- * (`input-value`) and the committed value (`value`) — plus the popup's open
- * state, and hands all three down to every other `<skdx-autocomplete-*>` part,
- * which look it up with `closest('skdx-autocomplete')`. Renders no visible box
- * of its own (`display: contents`).
- *
- * Real DOM focus never leaves `<skdx-autocomplete-input>`; the highlighted
- * suggestion is *virtual*, named by `aria-activedescendant`. Arrow Down/Up move
- * the highlight, Enter commits it, Escape closes and puts the last committed
- * text back, Tab commits the raw draft.
- *
- * Filtering is the consumer's job by default: render only the items that match
- * the draft text, which is what an async or server-side search needs. Set the
- * `filter` *property* to a predicate to move filtering inside the component
- * instead.
- *
- * Form-associated via `ElementInternals`: with a `name`, the field submits the
- * text currently in the input — which, after any commit, is the committed
- * value — exactly as React's real `<input>` does, and a form reset restores
- * the text and value it was connected with.
+ * `<skdx-autocomplete>` is a WAI-ARIA 1.2 combobox with list autocomplete whose committed value doesn't have to come from the list.
  *
  * @example
  * ```html
  * <skdx-autocomplete id="city">
- *   <skdx-autocomplete-input label="City" placeholder="Where to?"></skdx-autocomplete-input>
- *   <skdx-autocomplete-trigger label="Show suggestions">▾</skdx-autocomplete-trigger>
+ *   <skdx-autocomplete-input aria-label="City" placeholder="Where to?"></skdx-autocomplete-input>
+ *   <skdx-autocomplete-trigger aria-label="Show suggestions">▾</skdx-autocomplete-trigger>
  *   <skdx-autocomplete-content>
- *     <skdx-autocomplete-list label="Cities">
+ *     <skdx-autocomplete-list aria-label="Cities">
  *       <skdx-autocomplete-item value="Oslo">Oslo</skdx-autocomplete-item>
  *     </skdx-autocomplete-list>
  *     <skdx-autocomplete-empty>No matches — we'll use what you typed</skdx-autocomplete-empty>
@@ -63,227 +50,185 @@ declare const SkdxAutocomplete_base: typeof LitElement & (new (...args: any[]) =
  * </skdx-autocomplete>
  * ```
  *
- * @fires value-change - Fires with the new committed value (string) — on Enter, on a suggestion click, on Tab, and on blur. Never on a keystroke, and never when the value is unchanged.
+ * @fires value-change - Fires with `{ value, previousValue, reason, created }` — on Enter, on a suggestion click, on Tab, and on blur. Never on a keystroke, and never when the value is unchanged. `created` is `true` when the committed value is the draft text itself rather than an existing suggestion.
  * @fires input-value-change - Fires with the new draft text (string) on every keystroke, and whenever a commit or a revert rewrites the field.
  * @fires open-change - Fires with the new open state (boolean) whenever the suggestion popup opens or closes.
  * @fires open-change-complete - Fires with the new open state after `<skdx-autocomplete-content>`'s enter or exit animation has finished — as soon as the popup has settled, when it declares no animation at all. Not cancelable: the change has already happened.
+ *
+ * @slot option - Per-suggestion content for the derived anatomy, addressed by `data-value` — this package's form of the `renderOption` hook the other four ports take as a function. Stamped into the matching `<skdx-autocomplete-item>` in place of its plain label text.
  */
 export declare class SkdxAutocomplete extends SkdxAutocomplete_base {
     static styles: import("lit").CSSResult;
     /**
-     * The committed value — the answer the form takes, which need not be one of
-     * the suggestions. A *separate* state from {@link inputValue}: the draft
-     * text moves on every keystroke, this only when something is committed.
-     * Listen for `value-change` to observe or override changes.
+     * Committed value — the form's answer, separate from inputValue and only changing on explicit commit.
      * @default '' — nothing committed, so blurring an untouched field commits nothing.
      */
     value: string;
     /**
-     * Initial committed value, applied once on connect and only if `value` was
-     * not authored. It also seeds {@link inputValue}, so an autocomplete
-     * restored from saved state shows the text it committed rather than an empty
-     * field, and it is the value a form reset restores.
+     * Initial committed value and seed for inputValue; restored on form reset.
      * @default '' — the field starts committed to nothing.
      */
     defaultValue: string;
     /**
-     * The draft text currently in the input, typically used to drive filtering
-     * of the suggestion list. Listen for `input-value-change`.
+     * Draft text in the input; with no `filter` predicate, render only matching items.
      * @default '' — an empty field, so an unfiltered list.
      */
     inputValue: string;
     /**
-     * Initial draft text, applied once on connect and only if `input-value` was
-     * not authored.
-     * @default undefined — falls back to whatever value the field starts committed to, so the box never silently disagrees with its own value.
+     * Initial draft text, applied once on connect if `input-value` was not authored.
+     * @default undefined — falls back to the committed value.
      */
     defaultInputValue?: string;
     /**
-     * Whether the suggestion popup is open. Listen for `open-change`.
+     * Whether the suggestion popup is open; opens on first keystroke or with openOnFocus.
      * @default false — the popup opens on the first keystroke, or on focus with {@link openOnFocus}.
      */
     open: boolean;
     /**
-     * Initial open state, applied once on connect and only if `open` was not
-     * authored.
+     * Initial open state, applied once on connect if `open` was not authored.
      * @default false
      */
     defaultOpen: boolean;
     /**
-     * Lets the committed value be text that is not in the suggestion list — Tab,
-     * Enter with nothing highlighted, and blur all commit the raw draft. This is
-     * the whole point of the family: an autocomplete *suggests*, it does not
-     * constrain. Turn it off and an unmatched draft is discarded on blur with the
-     * last committed text put back, which makes this a `<skdx-combobox>` with
-     * extra steps — reach for that instead.
-     *
-     * Defaulting to `true` means the attribute has to be switched off by *value*
-     * (`allow-custom-value="false"`), not by absence.
+     * Allows committing text that is not in the suggestion list via Tab, Enter, or blur.
      * @default true
      */
     allowCustomValue: boolean;
     /**
-     * Opens the suggestion popup as soon as the input takes focus, instead of
-     * waiting for the first keystroke. Off by default: an empty field usually
-     * means an unfiltered list, and dropping the entire dataset over the page on
-     * focus is rarely what the user asked for.
+     * Opens the suggestion popup on focus instead of waiting for first keystroke.
      * @default false
      */
     openOnFocus: boolean;
     /**
-     * Predicate deciding which `<skdx-autocomplete-item>`s survive the current
-     * draft text. Every item is measured by its `text-value`, or its rendered
-     * text, and a rejected one stops being an option entirely — so it leaves the
-     * suggestion count, the highlight order, and `<skdx-autocomplete-empty>`
-     * exactly as if the consumer had never rendered it. Property only: an
-     * attribute cannot carry a function.
-     * @default undefined — nothing is filtered; the consumer renders only the matching items, which is what an async or server-side search needs.
+     * Keeps first suggestion highlighted when the list changes.
+     * @default false
+     */
+    autoHighlight: boolean;
+    /**
+     * Wraps arrow navigation around the ends of the suggestion list; Arrow Down from the last item highlights the first.
+     * @default true
+     */
+    loop: boolean;
+    /**
+     * Predicate deciding which items survive the current draft text; measured by text-value or rendered text.
+     * @default undefined — nothing filtered; consumer renders matching items.
      */
     filter?: SkdxAutocompleteFilter;
     /**
-     * Blocks all interaction: the input is natively `disabled`, so it is not
-     * focusable and the popup can never open.
+     * Blocks all interaction; the input is natively `disabled` and unfocusable.
      * @default false
      */
     disabled: boolean;
     /**
-     * Shows the committed text but blocks any change to it — the input is
-     * natively `readonly` and still focusable (unlike `disabled`), and no
-     * keystroke, Tab or blur commits anything.
+     * Shows committed text but blocks changes; the input is natively `readonly` and focusable.
      * @default false
      */
     readOnly: boolean;
     /**
-     * Marks the field invalid, exposed as `aria-invalid`/`data-invalid` on
-     * `<skdx-autocomplete-input>`.
+     * Marks the field invalid; exposed as `aria-invalid` and `data-invalid` on the input.
      * @default false
      */
     invalid: boolean;
     /**
-     * Name used as the `FormData` entry key when the autocomplete is inside a
-     * `<form>`. What is submitted is the text in the field, which after any
-     * commit is the committed value.
-     * @default undefined — the field submits nothing at all.
+     * Marks suggestions in flight, publishing `aria-busy` and `data-loading`, and suppresses the count announcement.
+     * @default false
+     */
+    loading: boolean;
+    /**
+     * Name used as the `FormData` entry key; submits the text in the field.
+     * @default undefined — the field submits nothing.
      */
     name?: string;
     /**
-     * Formats the message announced (through the shared live announcer) each
-     * time the number of rendered suggestions changes while the popup is open.
-     * Filtering changes nothing `aria-expanded` or `aria-activedescendant`
-     * reports, so this count is the only signal a screen-reader user gets that
-     * typing narrowed anything. Return an empty string to announce nothing.
-     * Property only.
+     * Id of the form this submits into, allowing it to live outside its form element.
+     * @default undefined — submits into nearest ancestor form.
+     */
+    formId?: string;
+    /**
+     * Formats the suggestion count announcement; return an empty string to announce nothing.
      * @default defaultGetSuggestionCountLabel — e.g. `"3 suggestions available"`
      */
-    getSuggestionCountLabel: (count: number) => string;
-    /** Id `<skdx-autocomplete-list>` takes, and the input's `aria-controls` points at. */
-    readonly listId: string;
-    /** Id of the virtually-focused (`aria-activedescendant`) suggestion, or `null`. */
-    activeId: string | null;
-    /** @internal The `<skdx-autocomplete-input>` descendant — the floating-ui anchor for the popup. */
-    inputHost: HTMLElement | null;
+    getResultCountLabel: (count: number) => string;
     /**
-     * @internal The mounted `<skdx-autocomplete-content>`. Registered rather than
-     * looked up, because it is also what tells `<skdx-autocomplete-input>` that
-     * something else owns Escape.
+     * Suggestion collection for data-driven rendering that auto-derives Input, Trigger, and the popup.
+     * @default undefined — author parts by hand.
      */
-    contentEl: HTMLElement | null;
+    options?: SkdxOptionsInput;
+    /**
+     * Placeholder for the derived anatomy's input; ignored if anatomy is authored.
+     * @default undefined — no placeholder is derived.
+     */
+    placeholder?: string;
     /**
-     * The text Escape restores. Held whether or not `value` is driven from
-     * outside, because Escape has to put the last committed text back either
-     * way.
+     * Whether the derived anatomy renders a Clear button that empties draft text and committed value.
+     * @default false — no Clear button is derived.
      */
+    clearable: boolean;
+    /** Id for `<skdx-autocomplete-list>` and input's `aria-controls`. */
+    listId: string;
+    /** Id of virtually-focused suggestion or `null`. */
+    activeId: string | null;
+    /** @internal The autocomplete-input descendant — floating-ui anchor. */
+    inputHost: HTMLElement | null;
+    /** @internal Mounted autocomplete-content, registered to own Escape. */
+    contentEl: HTMLElement | null;
     private committedText;
-    /** Snapshot of the state the element was connected with, for `formResetCallback`. */
     private initialValue?;
     private initialInputValue?;
     private seeded;
-    /** Sets `value` and dispatches `value-change`. A value equal to the current one is a no-op. */
-    setValue(value: string): void;
-    /** Sets `inputValue` and dispatches `input-value-change`. Unchanged text is a no-op. */
+    /** @internal Sets `value` and dispatches `value-change`; a no-op if unchanged. */
+    setValue(value: string, reason?: SkdxAutocompleteValueChangeDetail['reason'], created?: boolean): void;
+    /** @internal Sets `inputValue` and dispatches `input-value-change`; a no-op if unchanged. */
     setInputValue(value: string): void;
-    /** Sets `open` and dispatches `open-change`. Clears the virtual highlight on close; an unchanged state is a no-op. */
+    /** @internal Sets `open` and dispatches `open-change`; clears virtual highlight on close. */
     setOpen(open: boolean): void;
-    /** Whether a suggestion's value is the committed one, for `aria-selected`. */
+    /** @internal Whether a suggestion's value is the committed one; for `aria-selected`. */
     isSelected(value: string): boolean;
-    /**
-     * Whether an item's text survives the current `filter` predicate and draft text.
-     *
-     * A call the family's `*-item` element makes on its root to decide its own visibility, not consumer API. It stays `public` to the compiler because the item is an instance of a different class, which `protected` cannot express.
-     *
-     * @internal
-     */
+    /** @internal Whether item text survives the current filter and draft text. */
     matchesFilter(itemText: string): boolean;
-    /**
-     * Commits a suggestion: writes its text into the input, its value into
-     * `value`, and closes.
-     *
-     * A locked root already makes every `<skdx-autocomplete-item>` inert — pointer
-     * and keyboard both stop there — so this guard is the root's own invariant,
-     * not a path a real interaction reaches. {@link commitInputValue} is
-     * different: a read-only input is still focusable, so Tab and blur do reach
-     * it.
-     */
-    commitItem(value: string, text: string): void;
-    /** Commits the raw draft text as the value (Enter with nothing highlighted, Tab, blur) — or restores the last committed text when `allowCustomValue` is off. */
-    commitInputValue(): void;
-    /** Closes and puts the last committed text back in the input (Escape). */
+    /** @internal Visible suggestions, ranked by numeric filter predicate via inline CSS `order`. */
+    visibleOptions(): HTMLElement[];
+    /** @internal Commits a suggestion: writes text to input, value to `value`, and closes. */
+    commitItem(value: string, text: string, reason?: SkdxAutocompleteValueChangeDetail['reason']): void;
+    /** @internal Commits raw draft as value, or restores the last committed text if `allowCustomValue` is off. */
+    commitInputValue(reason?: SkdxAutocompleteValueChangeDetail['reason']): void;
+    /** @internal Closes and puts the last committed text back in the input (Escape). */
     revert(): void;
-    /** Opens the popup and highlights the first or last suggestion once it mounts. */
+    /** @internal Empties draft text, committed value, and remembered text together. */
+    clear(): void;
+    /** @internal Opens the popup and highlights the first or last suggestion once it mounts. */
     openWithHighlight(edge: 'first' | 'last'): void;
-    /**
-     * Sets the virtually-focused suggestion id.
-     *
-     * Keyed on an id this element mints for its own options, so a consumer has nothing meaningful to pass — it is the `aria-activedescendant` wiring the input and item parts share with their root, not consumer API. It stays `public` to the compiler because those parts are instances of different classes, which `protected` cannot express.
-     *
-     * @internal
-     */
+    /** @internal Sets the virtually-focused suggestion id. */
     setActiveId(id: string | null): void;
     private readonly itemRegistry;
-    /** @internal Called by each rendered `<skdx-autocomplete-item>` so Enter can commit it by id. */
+    /** @internal Called by rendered items so Enter can commit by id. */
     registerItem(id: string, entry: SkdxAutocompleteItemEntry): void;
-    /** @internal Called when an item unmounts or is filtered out; a gone suggestion can't stay highlighted. */
+    /** @internal Called when item unmounts or is filtered out. */
     unregisterItem(id: string): void;
-    /**
-     * The registered entry for a suggestion id, or `undefined` when it is no longer rendered.
-     *
-     * Keyed on an id this element mints for its own options, so a consumer has nothing meaningful to pass — it is the `aria-activedescendant` wiring the input and item parts share with their root, not consumer API. It stays `public` to the compiler because those parts are instances of different classes, which `protected` cannot express.
-     *
-     * @internal
-     */
+    /** @internal The registered entry for a suggestion id, or `undefined` if no longer rendered. */
     getItem(id: string): SkdxAutocompleteItemEntry | undefined;
     private reseedFrame?;
-    /**
-     * Virtual focus has to keep naming a suggestion that is actually rendered,
-     * and the item the user is on is exactly the one ordinary typing removes.
-     * Dropping the highlight there would leave the input with no
-     * `aria-activedescendant` while matches are still on screen, so it is
-     * re-pointed at the first surviving suggestion instead. Only an empty result
-     * set clears it: naming an element that is not an option is worse than naming
-     * none, and axe flags it.
-     *
-     * Deferred a frame because the new option set has to be in the DOM before
-     * "first" means anything — same reason as {@link openWithHighlight}.
-     */
+    /** Re-points virtual focus; deferred a frame so new options land in the DOM. */
     private scheduleReseed;
     private emit;
     private notify;
-    /**
-     * Filtering happens in *our light DOM*, which doesn't trigger a Lit update —
-     * so the suggestion count is watched with a MutationObserver rather than
-     * derived from a property. `announce` debounces, so typing a word produces
-     * one announcement rather than one per keystroke.
-     */
+    /** Watch light DOM mutations; light DOM filtering doesn't trigger Lit updates. */
     private readonly itemObserver;
     private announceSuggestionCount;
+    private _anatomyOptionsRef?;
+    private _anatomyClearableRef?;
     connectedCallback(): void;
+    private observeOptions;
+    /** Draws canonical anatomy when no consumer-authored parts exist; rebuilds tear down suggestions. */
+    private readonly fillAnatomy;
     disconnectedCallback(): void;
     private hasUpdatedOnce;
     private teardownOpenChangeComplete?;
     protected updated(changed: Map<string, unknown>): void;
-    /** Restores the committed value and draft text the element was connected with. A reset fires no change event. */
+    private syncOpenState;
+    /** Restores committed value and draft text from connection; fires no change event. */
     formResetCallback(): void;
-    render(): import("lit").TemplateResult<1>;
+    render(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {