@skdx/web-components 0.26.0

package/dist/autocomplete/Autocomplete.cjs

@@ -0,0 +1,5 @@
+"use strict";var o=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var C=Object.prototype.hasOwnProperty;var E=(l,r)=>{for(var e in r)o(l,e,{get:r[e],enumerable:!0})},T=(l,r,e,t)=>{if(r&&typeof r=="object"||typeof r=="function")for(let s of O(r))!C.call(l,s)&&s!==e&&o(l,s,{get:()=>r[s],enumerable:!(t=c(r,s))||t.enumerable});return l};var F=l=>T(o({},"__esModule",{value:!0}),l),n=(l,r,e,t)=>{for(var s=t>1?void 0:t?c(r,e):r,d=l.length-1,p;d>=0;d--)(p=l[d])&&(s=(t?p(r,e,s):p(s))||s);return t&&s&&o(r,e,s),s};var w={};E(w,{AUTOCOMPLETE_UPDATE_EVENT:()=>m,OPTION_SELECTOR:()=>h,SkdxAutocomplete:()=>i,defaultGetSuggestionCountLabel:()=>I});module.exports=F(w);var u=require("lit"),a=require("lit/decorators.js"),f=require("../internal/define.cjs"),v=require("../internal/form-associated.cjs"),g=require("../internal/ids.cjs"),b=require("../internal/open-change-complete.cjs"),y=require("../internal/positioning.cjs"),V=require("../utils/live-announcer.cjs");var h='[role="option"]:not([data-disabled])',m="skdx-autocomplete-internal-update";function I(l){return`${l} suggestion${l===1?"":"s"} available`}var i=class extends(0,v.FormAssociated)(u.LitElement){constructor(){super(...arguments);this.value="";this.defaultValue="";this.inputValue="";this.open=!1;this.defaultOpen=!1;this.allowCustomValue=!0;this.openOnFocus=!1;this.disabled=!1;this.readOnly=!1;this.invalid=!1;this.getSuggestionCountLabel=I;this.listId=(0,g.nextId)("skdx-autocomplete-list");this.activeId=null;this.inputHost=null;this.contentEl=null;this.committedText="";this.seeded=!1;this.itemRegistry=new Map;this.itemObserver=new MutationObserver(()=>this.announceSuggestionCount());this.hasUpdatedOnce=!1}setValue(e){this.value!==e&&(this.value=e,this.emit("value-change",e))}setInputValue(e){this.inputValue!==e&&(this.inputValue=e,this.emit("input-value-change",e))}setOpen(e){this.open!==e&&(this.open=e,e||(this.activeId=null),this.emit("open-change",e))}isSelected(e){return e!==""&&e===this.value}matchesFilter(e){return this.filter===void 0||this.filter(e,this.inputValue)}commitItem(e,t){this.disabled||this.readOnly||(this.setValue(e),this.setInputValue(t),this.committedText=t,this.setOpen(!1))}commitInputValue(){if(!(this.disabled||this.readOnly)){if(!this.allowCustomValue){this.setInputValue(this.committedText),this.setOpen(!1);return}this.setValue(this.inputValue),this.committedText=this.inputValue,this.setOpen(!1)}}revert(){this.setInputValue(this.committedText),this.setOpen(!1)}openWithHighlight(e){this.setOpen(!0),requestAnimationFrame(()=>{let t=Array.from(this.querySelectorAll(h));t.length!==0&&this.setActiveId((e==="last"?t[t.length-1]:t[0]).id)})}setActiveId(e){this.activeId=e,this.notify()}registerItem(e,t){this.itemRegistry.set(e,t)}unregisterItem(e){this.itemRegistry.delete(e),this.activeId===e&&this.scheduleReseed()}getItem(e){return this.itemRegistry.get(e)}scheduleReseed(){this.reseedFrame===void 0&&(this.reseedFrame=requestAnimationFrame(()=>{this.reseedFrame=void 0;let e=this.activeId;if(e===null)return;let t=Array.from(this.querySelectorAll(h));t.some(s=>s.id===e)||this.setActiveId(t[0]?.id??null)}))}emit(e,t){this.dispatchEvent(new CustomEvent(e,{detail:t,bubbles:!0,composed:!0})),this.notify()}notify(){this.dispatchEvent(new CustomEvent(m,{bubbles:!0,composed:!0})),this.requestUpdate()}announceSuggestionCount(){this.open&&(0,V.announce)(this.getSuggestionCountLabel(this.querySelectorAll(h).length))}connectedCallback(){super.connectedCallback(),this.seeded||(this.seeded=!0,this.hasAttribute("value")||(this.value=this.defaultValue),this.hasAttribute("input-value")||(this.inputValue=this.defaultInputValue??this.value),this.hasAttribute("open")||(this.open=this.defaultOpen),this.committedText=this.inputValue,this.initialValue=this.value,this.initialInputValue=this.inputValue),this.itemObserver.observe(this,{childList:!0,subtree:!0,attributeFilter:["data-disabled","role"]})}disconnectedCallback(){this.itemObserver.disconnect(),this.reseedFrame!==void 0&&cancelAnimationFrame(this.reseedFrame),this.reseedFrame=void 0,this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(e){let t=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,(e.has("inputValue")||e.has("name"))&&this.setFormValue(this.inputValue),e.has("open")&&this.open&&this.announceSuggestionCount(),e.size>0&&this.dispatchEvent(new CustomEvent(m,{bubbles:!0,composed:!0})),e.has("open")&&!t&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=(0,b.notifyOpenChangeComplete)(()=>this.contentEl,this.open,s=>this.dispatchEvent(new CustomEvent("open-change-complete",{detail:s,bubbles:!0,composed:!0}))))}formResetCallback(){this.value=this.initialValue??"",this.inputValue=this.initialInputValue??"",this.committedText=this.inputValue}render(){return u.html`<slot></slot>`}};i.styles=u.css`
+    :host {
+      display: contents;
+    }
+  `,n([(0,a.property)({type:String,reflect:!0})],i.prototype,"value",2),n([(0,a.property)({type:String,attribute:"default-value"})],i.prototype,"defaultValue",2),n([(0,a.property)({type:String,attribute:"input-value"})],i.prototype,"inputValue",2),n([(0,a.property)({type:String,attribute:"default-input-value"})],i.prototype,"defaultInputValue",2),n([(0,a.property)({type:Boolean,reflect:!0})],i.prototype,"open",2),n([(0,a.property)({type:Boolean,attribute:"default-open"})],i.prototype,"defaultOpen",2),n([(0,a.property)({converter:y.optOutBoolean,attribute:"allow-custom-value"})],i.prototype,"allowCustomValue",2),n([(0,a.property)({type:Boolean,attribute:"open-on-focus",reflect:!0})],i.prototype,"openOnFocus",2),n([(0,a.property)({attribute:!1})],i.prototype,"filter",2),n([(0,a.property)({type:Boolean,reflect:!0})],i.prototype,"disabled",2),n([(0,a.property)({type:Boolean,attribute:"read-only",reflect:!0})],i.prototype,"readOnly",2),n([(0,a.property)({type:Boolean,reflect:!0})],i.prototype,"invalid",2),n([(0,a.property)({type:String,reflect:!0})],i.prototype,"name",2),n([(0,a.property)({attribute:!1})],i.prototype,"getSuggestionCountLabel",2),i=n([(0,f.customElement)("skdx-autocomplete")],i);0&&(module.exports={AUTOCOMPLETE_UPDATE_EVENT,OPTION_SELECTOR,SkdxAutocomplete,defaultGetSuggestionCountLabel});

package/dist/autocomplete/Autocomplete.d.cts

@@ -0,0 +1,293 @@
+import { LitElement } from 'lit';
+/** @internal Selector for a suggestion that is still an option and still live, mirrored from the React autocomplete util. */
+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. */
+export declare const AUTOCOMPLETE_UPDATE_EVENT = "skdx-autocomplete-internal-update";
+/** Default `getSuggestionCountLabel`: `"1 suggestion available"` / `"3 suggestions available"`. */
+export declare function defaultGetSuggestionCountLabel(count: number): string;
+/** 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. */
+    value: string;
+    /** 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) & {
+    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.
+ *
+ * @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-content>
+ *     <skdx-autocomplete-list 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>
+ *   </skdx-autocomplete-content>
+ * </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 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.
+ */
+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.
+     * @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.
+     * @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`.
+     * @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.
+     */
+    defaultInputValue?: string;
+    /**
+     * Whether the suggestion popup is open. Listen for `open-change`.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+     */
+    filter?: SkdxAutocompleteFilter;
+    /**
+     * Blocks all interaction: the input is natively `disabled`, so it is not
+     * focusable and the popup can never open.
+     * @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.
+     * @default false
+     */
+    readOnly: boolean;
+    /**
+     * Marks the field invalid, exposed as `aria-invalid`/`data-invalid` on
+     * `<skdx-autocomplete-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.
+     */
+    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.
+     * @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;
+    /**
+     * @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.
+     */
+    contentEl: HTMLElement | null;
+    /**
+     * 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.
+     */
+    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. */
+    setInputValue(value: string): void;
+    /** Sets `open` and dispatches `open-change`. Clears the virtual highlight on close; an unchanged state is a no-op. */
+    setOpen(open: boolean): void;
+    /** 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
+     */
+    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). */
+    revert(): void;
+    /** 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
+     */
+    setActiveId(id: string | null): void;
+    private readonly itemRegistry;
+    /** @internal Called by each rendered `<skdx-autocomplete-item>` so Enter can commit it 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. */
+    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
+     */
+    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}.
+     */
+    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.
+     */
+    private readonly itemObserver;
+    private announceSuggestionCount;
+    connectedCallback(): void;
+    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. */
+    formResetCallback(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-autocomplete': SkdxAutocomplete;
+    }
+}
+export {};

package/dist/autocomplete/Autocomplete.d.ts

@@ -0,0 +1,293 @@
+import { LitElement } from 'lit';
+/** @internal Selector for a suggestion that is still an option and still live, mirrored from the React autocomplete util. */
+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. */
+export declare const AUTOCOMPLETE_UPDATE_EVENT = "skdx-autocomplete-internal-update";
+/** Default `getSuggestionCountLabel`: `"1 suggestion available"` / `"3 suggestions available"`. */
+export declare function defaultGetSuggestionCountLabel(count: number): string;
+/** 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. */
+    value: string;
+    /** 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.js").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.
+ *
+ * @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-content>
+ *     <skdx-autocomplete-list 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>
+ *   </skdx-autocomplete-content>
+ * </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 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.
+ */
+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.
+     * @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.
+     * @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`.
+     * @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.
+     */
+    defaultInputValue?: string;
+    /**
+     * Whether the suggestion popup is open. Listen for `open-change`.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+     */
+    filter?: SkdxAutocompleteFilter;
+    /**
+     * Blocks all interaction: the input is natively `disabled`, so it is not
+     * focusable and the popup can never open.
+     * @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.
+     * @default false
+     */
+    readOnly: boolean;
+    /**
+     * Marks the field invalid, exposed as `aria-invalid`/`data-invalid` on
+     * `<skdx-autocomplete-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.
+     */
+    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.
+     * @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;
+    /**
+     * @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.
+     */
+    contentEl: HTMLElement | null;
+    /**
+     * 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.
+     */
+    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. */
+    setInputValue(value: string): void;
+    /** Sets `open` and dispatches `open-change`. Clears the virtual highlight on close; an unchanged state is a no-op. */
+    setOpen(open: boolean): void;
+    /** 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
+     */
+    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). */
+    revert(): void;
+    /** 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
+     */
+    setActiveId(id: string | null): void;
+    private readonly itemRegistry;
+    /** @internal Called by each rendered `<skdx-autocomplete-item>` so Enter can commit it 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. */
+    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
+     */
+    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}.
+     */
+    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.
+     */
+    private readonly itemObserver;
+    private announceSuggestionCount;
+    connectedCallback(): void;
+    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. */
+    formResetCallback(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-autocomplete': SkdxAutocomplete;
+    }
+}
+export {};

package/dist/autocomplete/Autocomplete.js

@@ -0,0 +1,5 @@
+var p=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var s=(a,l,e,t)=>{for(var r=t>1?void 0:t?m(l,e):l,u=a.length-1,o;u>=0;u--)(o=a[u])&&(r=(t?o(l,e,r):o(r))||r);return t&&r&&p(l,e,r),r};import{css as c,html as f,LitElement as v}from"lit";import{property as n}from"lit/decorators.js";import{customElement as g}from"../internal/define.js";import{FormAssociated as b}from"../internal/form-associated.js";import{nextId as y}from"../internal/ids.js";import{notifyOpenChangeComplete as V}from"../internal/open-change-complete.js";import{optOutBoolean as I}from"../internal/positioning.js";import{announce as O}from"../utils/live-announcer.js";var h='[role="option"]:not([data-disabled])',d="skdx-autocomplete-internal-update";function C(a){return`${a} suggestion${a===1?"":"s"} available`}var i=class extends b(v){constructor(){super(...arguments);this.value="";this.defaultValue="";this.inputValue="";this.open=!1;this.defaultOpen=!1;this.allowCustomValue=!0;this.openOnFocus=!1;this.disabled=!1;this.readOnly=!1;this.invalid=!1;this.getSuggestionCountLabel=C;this.listId=y("skdx-autocomplete-list");this.activeId=null;this.inputHost=null;this.contentEl=null;this.committedText="";this.seeded=!1;this.itemRegistry=new Map;this.itemObserver=new MutationObserver(()=>this.announceSuggestionCount());this.hasUpdatedOnce=!1}setValue(e){this.value!==e&&(this.value=e,this.emit("value-change",e))}setInputValue(e){this.inputValue!==e&&(this.inputValue=e,this.emit("input-value-change",e))}setOpen(e){this.open!==e&&(this.open=e,e||(this.activeId=null),this.emit("open-change",e))}isSelected(e){return e!==""&&e===this.value}matchesFilter(e){return this.filter===void 0||this.filter(e,this.inputValue)}commitItem(e,t){this.disabled||this.readOnly||(this.setValue(e),this.setInputValue(t),this.committedText=t,this.setOpen(!1))}commitInputValue(){if(!(this.disabled||this.readOnly)){if(!this.allowCustomValue){this.setInputValue(this.committedText),this.setOpen(!1);return}this.setValue(this.inputValue),this.committedText=this.inputValue,this.setOpen(!1)}}revert(){this.setInputValue(this.committedText),this.setOpen(!1)}openWithHighlight(e){this.setOpen(!0),requestAnimationFrame(()=>{let t=Array.from(this.querySelectorAll(h));t.length!==0&&this.setActiveId((e==="last"?t[t.length-1]:t[0]).id)})}setActiveId(e){this.activeId=e,this.notify()}registerItem(e,t){this.itemRegistry.set(e,t)}unregisterItem(e){this.itemRegistry.delete(e),this.activeId===e&&this.scheduleReseed()}getItem(e){return this.itemRegistry.get(e)}scheduleReseed(){this.reseedFrame===void 0&&(this.reseedFrame=requestAnimationFrame(()=>{this.reseedFrame=void 0;let e=this.activeId;if(e===null)return;let t=Array.from(this.querySelectorAll(h));t.some(r=>r.id===e)||this.setActiveId(t[0]?.id??null)}))}emit(e,t){this.dispatchEvent(new CustomEvent(e,{detail:t,bubbles:!0,composed:!0})),this.notify()}notify(){this.dispatchEvent(new CustomEvent(d,{bubbles:!0,composed:!0})),this.requestUpdate()}announceSuggestionCount(){this.open&&O(this.getSuggestionCountLabel(this.querySelectorAll(h).length))}connectedCallback(){super.connectedCallback(),this.seeded||(this.seeded=!0,this.hasAttribute("value")||(this.value=this.defaultValue),this.hasAttribute("input-value")||(this.inputValue=this.defaultInputValue??this.value),this.hasAttribute("open")||(this.open=this.defaultOpen),this.committedText=this.inputValue,this.initialValue=this.value,this.initialInputValue=this.inputValue),this.itemObserver.observe(this,{childList:!0,subtree:!0,attributeFilter:["data-disabled","role"]})}disconnectedCallback(){this.itemObserver.disconnect(),this.reseedFrame!==void 0&&cancelAnimationFrame(this.reseedFrame),this.reseedFrame=void 0,this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(e){let t=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,(e.has("inputValue")||e.has("name"))&&this.setFormValue(this.inputValue),e.has("open")&&this.open&&this.announceSuggestionCount(),e.size>0&&this.dispatchEvent(new CustomEvent(d,{bubbles:!0,composed:!0})),e.has("open")&&!t&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=V(()=>this.contentEl,this.open,r=>this.dispatchEvent(new CustomEvent("open-change-complete",{detail:r,bubbles:!0,composed:!0}))))}formResetCallback(){this.value=this.initialValue??"",this.inputValue=this.initialInputValue??"",this.committedText=this.inputValue}render(){return f`<slot></slot>`}};i.styles=c`
+    :host {
+      display: contents;
+    }
+  `,s([n({type:String,reflect:!0})],i.prototype,"value",2),s([n({type:String,attribute:"default-value"})],i.prototype,"defaultValue",2),s([n({type:String,attribute:"input-value"})],i.prototype,"inputValue",2),s([n({type:String,attribute:"default-input-value"})],i.prototype,"defaultInputValue",2),s([n({type:Boolean,reflect:!0})],i.prototype,"open",2),s([n({type:Boolean,attribute:"default-open"})],i.prototype,"defaultOpen",2),s([n({converter:I,attribute:"allow-custom-value"})],i.prototype,"allowCustomValue",2),s([n({type:Boolean,attribute:"open-on-focus",reflect:!0})],i.prototype,"openOnFocus",2),s([n({attribute:!1})],i.prototype,"filter",2),s([n({type:Boolean,reflect:!0})],i.prototype,"disabled",2),s([n({type:Boolean,attribute:"read-only",reflect:!0})],i.prototype,"readOnly",2),s([n({type:Boolean,reflect:!0})],i.prototype,"invalid",2),s([n({type:String,reflect:!0})],i.prototype,"name",2),s([n({attribute:!1})],i.prototype,"getSuggestionCountLabel",2),i=s([g("skdx-autocomplete")],i);export{d as AUTOCOMPLETE_UPDATE_EVENT,h as OPTION_SELECTOR,i as SkdxAutocomplete,C as defaultGetSuggestionCountLabel};

package/dist/autocomplete/AutocompleteContent.cjs

@@ -0,0 +1,5 @@
+"use strict";var u=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var P=Object.prototype.hasOwnProperty;var b=(s,i)=>{for(var t in i)u(s,t,{get:i[t],enumerable:!0})},g=(s,i,t,n)=>{if(i&&typeof i=="object"||typeof i=="function")for(let e of O(i))!P.call(s,e)&&e!==t&&u(s,e,{get:()=>i[e],enumerable:!(n=f(i,e))||n.enumerable});return s};var w=s=>g(u({},"__esModule",{value:!0}),s),r=(s,i,t,n)=>{for(var e=n>1?void 0:n?f(i,t):i,c=s.length-1,p;c>=0;c--)(p=s[c])&&(e=(n?p(i,t,e):p(e))||e);return n&&e&&u(i,t,e),e};var D={};b(D,{SkdxAutocompleteContent:()=>o});module.exports=w(D);var l=require("lit"),a=require("lit/decorators.js"),m=require("../internal/closest.cjs"),y=require("../internal/define.cjs"),d=require("../internal/dismiss.cjs"),h=require("../internal/positioning.cjs"),E=require("../internal/styles.cjs"),v=require("./Autocomplete.cjs");var o=class extends l.LitElement{constructor(){super(...arguments);this.side="bottom";this.align="start";this.sideOffset=4;this.alignOffset=0;this.avoidCollisions=!0;this.collisionPadding=8;this.root=null;this.onRootUpdate=()=>this.syncHostState();this.preventFocusSteal=t=>t.preventDefault();this.handleDocumentKeyDown=t=>{t.key!=="Escape"||!this.root?.open||(t.preventDefault(),(0,d.dispatchEscapeKeyDown)(this,t)&&this.root.revert())};this.handleOutsidePointerDown=t=>{!this.root?.open||this.isInside(t.target)||(0,d.dispatchOutside)(this,"pointer-down-outside",t)&&this.root.setOpen(!1)};this.handleOutsideFocus=t=>{if(!this.root?.open)return;let n=(0,d.focusOutsideTarget)(t);n===null||this.isInside(n)||(0,d.dispatchOutside)(this,"focus-outside",t)&&this.root.setOpen(!1)}}connectedCallback(){super.connectedCallback(),this.root=(0,m.closestThroughPortal)(this,"skdx-autocomplete"),this.root&&(this.root.contentEl=this),this.root?.addEventListener(v.AUTOCOMPLETE_UPDATE_EVENT,this.onRootUpdate),this.addEventListener("mousedown",this.preventFocusSteal),document.addEventListener("keydown",this.handleDocumentKeyDown,!0),document.addEventListener("pointerdown",this.handleOutsidePointerDown),document.addEventListener("focusin",this.handleOutsideFocus),this.syncHostState()}disconnectedCallback(){this.root?.removeEventListener(v.AUTOCOMPLETE_UPDATE_EVENT,this.onRootUpdate),this.root?.contentEl===this&&(this.root.contentEl=null),this.removeEventListener("mousedown",this.preventFocusSteal),document.removeEventListener("keydown",this.handleDocumentKeyDown,!0),document.removeEventListener("pointerdown",this.handleOutsidePointerDown),document.removeEventListener("focusin",this.handleOutsideFocus),this.cleanupPosition?.(),this.cleanupPosition=void 0,super.disconnectedCallback()}isInside(t){return t?this.contains(t)||this.root?.contains(t)===!0:!1}syncHostState(){let t=this.root?.open??!1;this.setAttribute("data-state",t?"open":"closed"),this.setAttribute("data-side",this.side??"bottom"),this.setAttribute("data-align",this.align??"start"),this.hidden=!t,t?this.activate():this.deactivate()}activate(){this.cleanupPosition||!this.root?.inputHost||(this.cleanupPosition=(0,h.positionFloating)(this.root.inputHost,this,{side:this.side,align:this.align,sideOffset:this.sideOffset,alignOffset:this.alignOffset,avoidCollisions:this.avoidCollisions,collisionPadding:this.collisionPadding,collisionBoundary:this.collisionBoundary,component:"autocomplete"}))}deactivate(){this.cleanupPosition?.(),this.cleanupPosition=void 0}render(){return l.html`<slot></slot>`}};o.styles=[E.hiddenHostStyles,l.css`
+      :host {
+        display: block;
+      }
+    `],r([(0,a.property)({type:String})],o.prototype,"side",2),r([(0,a.property)({type:String})],o.prototype,"align",2),r([(0,a.property)({type:Number,attribute:"side-offset"})],o.prototype,"sideOffset",2),r([(0,a.property)({type:Number,attribute:"align-offset"})],o.prototype,"alignOffset",2),r([(0,a.property)({converter:h.optOutBoolean,attribute:"avoid-collisions"})],o.prototype,"avoidCollisions",2),r([(0,a.property)({type:Number,attribute:"collision-padding"})],o.prototype,"collisionPadding",2),r([(0,a.property)({attribute:!1})],o.prototype,"collisionBoundary",2),o=r([(0,y.customElement)("skdx-autocomplete-content","autocomplete","content")],o);0&&(module.exports={SkdxAutocompleteContent});