@skdx/web-components 0.26.0

package/dist/combobox/Combobox.d.cts

@@ -0,0 +1,238 @@
+import { LitElement } from 'lit';
+/** @internal Selector for a non-disabled option, mirrored from the React combobox util. */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** Default `getResultCountLabel`: `"1 result available"` / `"3 results available"`. */
+export declare function defaultGetResultCountLabel(count: number): string;
+/** What an `<skdx-combobox-item>` registers about itself, so Enter can commit it by id. */
+export interface SkdxComboboxItemEntry {
+    /** The value committed to the root when this item is selected. */
+    value: string;
+    /** The item's `textValue`, or its rendered text — matched by `filter`, written back into the input. */
+    text: string;
+}
+/**
+ * How Items are filtered against the draft text: `'manual'` filters nothing
+ * (the consumer renders only the matching Items), a predicate moves filtering
+ * inside the component.
+ */
+export type SkdxComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean);
+declare const SkdxCombobox_base: typeof LitElement & (new (...args: any[]) => import("../internal/form-associated.cjs").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
+/**
+ * `<skdx-combobox>` — the Web Components implementation of the shared
+ * Combobox contract (see `@skdx/shared`'s `comboboxContract`). A WAI-ARIA
+ * 1.2 "combobox with list autocomplete": real DOM focus always stays on
+ * `<skdx-combobox-input>`; the highlighted option is tracked as virtual focus
+ * via `aria-activedescendant`. Filtering the item list is the consumer's
+ * responsibility (headless). Renders no visible box of its own (`display:
+ * contents`) — it only owns value/inputValue/open/activeId state and
+ * exposes it to descendant parts via `closest('skdx-combobox')`, like
+ * `<skdx-dialog>`/`<skdx-select>`.
+ *
+ * Form-associated via `ElementInternals`: with a `name`, the selected option's
+ * `value` (not the draft `inputValue`) is submitted by the surrounding
+ * `<form>`, and a `required` combobox with no selection is `valueMissing`.
+ *
+ * @example
+ * ```html
+ * <skdx-combobox id="fruit">
+ *   <skdx-combobox-input placeholder="Search a fruit…"></skdx-combobox-input>
+ *   <skdx-combobox-content>
+ *     <skdx-combobox-item value="Apple">Apple</skdx-combobox-item>
+ *     <skdx-combobox-empty>No results</skdx-combobox-empty>
+ *   </skdx-combobox-content>
+ * </skdx-combobox>
+ * ```
+ *
+ * @fires value-change - Fired with the new selection — a string, or `string[]` when `multiple` — whenever an option is committed.
+ * @fires input-value-change - Fired with the new draft text (string) on every keystroke, and whenever a commit rewrites the field.
+ * @fires open-change - Fired with the new open state whenever the option listbox opens or closes.
+ * @fires open-change-complete - Fired with the new open state after `<skdx-combobox-content>`'s enter or exit animation has finished — as soon as the listbox has settled, when it declares no animation at all. Not cancelable: the change has already happened.
+ */
+export declare class SkdxCombobox extends SkdxCombobox_base {
+    static styles: import("lit").CSSResult;
+    /**
+     * Selected option value — a `string[]` when {@link multiple}, a `string`
+     * otherwise. The `value` *attribute* can only carry a single string; a
+     * multi-selection is a property-only assignment (`el.value = ['a','b']`).
+     * Listen for `value-change` to observe or override changes.
+     */
+    value: string | string[];
+    /**
+     * Allows more than one option to be selected: `value` becomes a `string[]`,
+     * Content gets `aria-multiselectable`, and committing an option toggles it,
+     * clears the draft text, and leaves the listbox open.
+     */
+    multiple: boolean;
+    /**
+     * Lets Enter commit the draft text itself when no option is highlighted, so
+     * the combobox can create values that are not in the list ("creatable").
+     */
+    allowCustomValue: boolean;
+    /**
+     * How Items are filtered against the draft text. `'manual'` — the default —
+     * filters nothing: the consumer renders only the Items that match, which is
+     * what an async or server-side search needs. A predicate instead moves
+     * filtering inside the component, and a rejected Item stops being an option
+     * entirely rather than merely hiding. Property only.
+     * @default 'manual'
+     */
+    filter: SkdxComboboxFilter;
+    /**
+     * Keeps the first option highlighted whenever the (filtered) list changes
+     * while open, so Enter always has an obvious target.
+     */
+    autoHighlight: boolean;
+    /**
+     * Marks results as in flight: `aria-busy="true"` plus `data-loading` on
+     * Input and Content, and the result-count announcement is suppressed (a
+     * count measured mid-fetch would announce "0 results available" per request).
+     */
+    loading: boolean;
+    /** The input's draft text, typically used to drive filtering of Item entries. */
+    inputValue: string;
+    /** Whether the listbox popup is open. Listen for `open-change`. */
+    open: boolean;
+    /** Marks the combobox as invalid, exposed as aria-invalid/data-invalid on the input. */
+    invalid: boolean;
+    /** Makes the input read-only, still focusable but not editable. */
+    readOnly: boolean;
+    /** Disables the input, excluding the combobox from the tab order and from form submission. */
+    disabled: boolean;
+    /** Marks the combobox required for native form validation, until an option is selected. @default false */
+    required: boolean;
+    /** Name used as the `FormData` entry key when the combobox is inside a `<form>`. @default undefined */
+    name?: string;
+    /**
+     * Replaces the message the browser shows when a `required` combobox is
+     * submitted with nothing selected. Sealed inside the shadow root otherwise,
+     * so this is the only way to translate it or to say what the list holds
+     * ("Pick a repository.").
+     * @default undefined — keeps `'Please select an item in the list.'`
+     */
+    requiredMessage?: string;
+    /**
+     * Formats the message announced (through the shared live announcer) each
+     * time the number of rendered `<skdx-combobox-item>`s changes while the
+     * listbox is open — filtering is silent for screen-reader users otherwise.
+     * Return an empty string to announce nothing. Set as a property, not an
+     * attribute.
+     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     */
+    getResultCountLabel: (count: number) => string;
+    readonly contentId: string;
+    /** Id of the virtually-focused (`aria-activedescendant`) option, or null. */
+    activeId: string | null;
+    /** The `<skdx-combobox-input>` descendant — the floating-ui anchor for the popup. @internal */
+    inputHost: HTMLElement | null;
+    /**
+     * @internal The mounted `<skdx-combobox-content>`. Registered rather than
+     * looked up, because it is also what tells `<skdx-combobox-input>` that
+     * something else owns Escape.
+     */
+    contentEl: HTMLElement | null;
+    /** Sets `value` and dispatches `value-change` (whose `detail` *is* the new value). A selection equal to the current one is a no-op. */
+    setValue(value: string | string[]): void;
+    /** Every selected value as an array, whatever shape `value` currently holds. */
+    get selectedValues(): string[];
+    /** Whether one option value is currently selected. */
+    isSelected(value: string): boolean;
+    /**
+     * Commits an option: single-select replaces the value, writes `text` into
+     * the draft, and closes; `multiple` toggles the value within the array,
+     * clears the draft (it was the search that found this option — keeping it
+     * would leave the list filtered down to the item just picked), and leaves
+     * the listbox open.
+     */
+    selectItem(value: string, text: string): void;
+    /**
+     * Whether an item's text survives the current `filter` predicate.
+     *
+     * 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;
+    private readonly itemRegistry;
+    /** @internal Called by each rendered `<skdx-combobox-item>` so Enter can commit it by id. */
+    registerItem(id: string, entry: SkdxComboboxItemEntry): void;
+    /** @internal Called when an item unmounts or is filtered out; a gone item can't stay highlighted. */
+    unregisterItem(id: string): void;
+    private reseedFrame?;
+    /**
+     * Virtual focus has to keep naming an option that is actually rendered, and
+     * the item the user is on is exactly the one ordinary typing removes: narrow
+     * the search and the highlighted option drops its `role="option"` from under
+     * it. Dropping the highlight there would leave the input with no
+     * aria-activedescendant while matches are still on screen, so a screen reader
+     * would announce nothing for the rest of the search — it is re-pointed at the
+     * first surviving option instead. Only an empty result set clears it:
+     * aria-activedescendant 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;
+    /**
+     * The registered entry for an option 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): SkdxComboboxItemEntry | undefined;
+    /** 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;
+    /** Opens the popup and highlights the first or last option once it mounts. */
+    openWithHighlight(edge: 'first' | 'last'): void;
+    /**
+     * Sets the virtually-focused option 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 emit;
+    private notify;
+    private defaultValue?;
+    /**
+     * Filtering happens in *our light DOM*, which doesn't trigger a Lit update —
+     * so the option count is watched with a MutationObserver rather than derived
+     * from a property. `announce` debounces, so a whole re-render's worth of
+     * mutations produces one announcement.
+     *
+     * Deliberately writes nothing back to the DOM: re-broadcasting from here
+     * would make every part's attribute writes loop-bearing (re-setting an
+     * attribute to the value it already has still produces a record).
+     * `<skdx-combobox-empty>` watches the same mutations itself instead.
+     */
+    private readonly itemObserver;
+    private announceResultCount;
+    /**
+     * Re-seeds the highlight whenever filtering leaves it with nothing, so Enter
+     * always has a target. Deferred a frame because the new item set has to be
+     * in the DOM before "first" means anything — same reason as
+     * {@link openWithHighlight}.
+     */
+    private maybeAutoHighlight;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private hasUpdatedOnce;
+    private teardownOpenChangeComplete?;
+    protected updated(changed: Map<string, unknown>): void;
+    private syncFormState;
+    /** Restores the selection and draft text the element was connected with. A reset fires no `value-change`. */
+    formResetCallback(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-combobox': SkdxCombobox;
+    }
+}
+export {};

package/dist/combobox/Combobox.d.ts

@@ -0,0 +1,238 @@
+import { LitElement } from 'lit';
+/** @internal Selector for a non-disabled option, mirrored from the React combobox util. */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** Default `getResultCountLabel`: `"1 result available"` / `"3 results available"`. */
+export declare function defaultGetResultCountLabel(count: number): string;
+/** What an `<skdx-combobox-item>` registers about itself, so Enter can commit it by id. */
+export interface SkdxComboboxItemEntry {
+    /** The value committed to the root when this item is selected. */
+    value: string;
+    /** The item's `textValue`, or its rendered text — matched by `filter`, written back into the input. */
+    text: string;
+}
+/**
+ * How Items are filtered against the draft text: `'manual'` filters nothing
+ * (the consumer renders only the matching Items), a predicate moves filtering
+ * inside the component.
+ */
+export type SkdxComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean);
+declare const SkdxCombobox_base: typeof LitElement & (new (...args: any[]) => import("../internal/form-associated.js").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
+/**
+ * `<skdx-combobox>` — the Web Components implementation of the shared
+ * Combobox contract (see `@skdx/shared`'s `comboboxContract`). A WAI-ARIA
+ * 1.2 "combobox with list autocomplete": real DOM focus always stays on
+ * `<skdx-combobox-input>`; the highlighted option is tracked as virtual focus
+ * via `aria-activedescendant`. Filtering the item list is the consumer's
+ * responsibility (headless). Renders no visible box of its own (`display:
+ * contents`) — it only owns value/inputValue/open/activeId state and
+ * exposes it to descendant parts via `closest('skdx-combobox')`, like
+ * `<skdx-dialog>`/`<skdx-select>`.
+ *
+ * Form-associated via `ElementInternals`: with a `name`, the selected option's
+ * `value` (not the draft `inputValue`) is submitted by the surrounding
+ * `<form>`, and a `required` combobox with no selection is `valueMissing`.
+ *
+ * @example
+ * ```html
+ * <skdx-combobox id="fruit">
+ *   <skdx-combobox-input placeholder="Search a fruit…"></skdx-combobox-input>
+ *   <skdx-combobox-content>
+ *     <skdx-combobox-item value="Apple">Apple</skdx-combobox-item>
+ *     <skdx-combobox-empty>No results</skdx-combobox-empty>
+ *   </skdx-combobox-content>
+ * </skdx-combobox>
+ * ```
+ *
+ * @fires value-change - Fired with the new selection — a string, or `string[]` when `multiple` — whenever an option is committed.
+ * @fires input-value-change - Fired with the new draft text (string) on every keystroke, and whenever a commit rewrites the field.
+ * @fires open-change - Fired with the new open state whenever the option listbox opens or closes.
+ * @fires open-change-complete - Fired with the new open state after `<skdx-combobox-content>`'s enter or exit animation has finished — as soon as the listbox has settled, when it declares no animation at all. Not cancelable: the change has already happened.
+ */
+export declare class SkdxCombobox extends SkdxCombobox_base {
+    static styles: import("lit").CSSResult;
+    /**
+     * Selected option value — a `string[]` when {@link multiple}, a `string`
+     * otherwise. The `value` *attribute* can only carry a single string; a
+     * multi-selection is a property-only assignment (`el.value = ['a','b']`).
+     * Listen for `value-change` to observe or override changes.
+     */
+    value: string | string[];
+    /**
+     * Allows more than one option to be selected: `value` becomes a `string[]`,
+     * Content gets `aria-multiselectable`, and committing an option toggles it,
+     * clears the draft text, and leaves the listbox open.
+     */
+    multiple: boolean;
+    /**
+     * Lets Enter commit the draft text itself when no option is highlighted, so
+     * the combobox can create values that are not in the list ("creatable").
+     */
+    allowCustomValue: boolean;
+    /**
+     * How Items are filtered against the draft text. `'manual'` — the default —
+     * filters nothing: the consumer renders only the Items that match, which is
+     * what an async or server-side search needs. A predicate instead moves
+     * filtering inside the component, and a rejected Item stops being an option
+     * entirely rather than merely hiding. Property only.
+     * @default 'manual'
+     */
+    filter: SkdxComboboxFilter;
+    /**
+     * Keeps the first option highlighted whenever the (filtered) list changes
+     * while open, so Enter always has an obvious target.
+     */
+    autoHighlight: boolean;
+    /**
+     * Marks results as in flight: `aria-busy="true"` plus `data-loading` on
+     * Input and Content, and the result-count announcement is suppressed (a
+     * count measured mid-fetch would announce "0 results available" per request).
+     */
+    loading: boolean;
+    /** The input's draft text, typically used to drive filtering of Item entries. */
+    inputValue: string;
+    /** Whether the listbox popup is open. Listen for `open-change`. */
+    open: boolean;
+    /** Marks the combobox as invalid, exposed as aria-invalid/data-invalid on the input. */
+    invalid: boolean;
+    /** Makes the input read-only, still focusable but not editable. */
+    readOnly: boolean;
+    /** Disables the input, excluding the combobox from the tab order and from form submission. */
+    disabled: boolean;
+    /** Marks the combobox required for native form validation, until an option is selected. @default false */
+    required: boolean;
+    /** Name used as the `FormData` entry key when the combobox is inside a `<form>`. @default undefined */
+    name?: string;
+    /**
+     * Replaces the message the browser shows when a `required` combobox is
+     * submitted with nothing selected. Sealed inside the shadow root otherwise,
+     * so this is the only way to translate it or to say what the list holds
+     * ("Pick a repository.").
+     * @default undefined — keeps `'Please select an item in the list.'`
+     */
+    requiredMessage?: string;
+    /**
+     * Formats the message announced (through the shared live announcer) each
+     * time the number of rendered `<skdx-combobox-item>`s changes while the
+     * listbox is open — filtering is silent for screen-reader users otherwise.
+     * Return an empty string to announce nothing. Set as a property, not an
+     * attribute.
+     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     */
+    getResultCountLabel: (count: number) => string;
+    readonly contentId: string;
+    /** Id of the virtually-focused (`aria-activedescendant`) option, or null. */
+    activeId: string | null;
+    /** The `<skdx-combobox-input>` descendant — the floating-ui anchor for the popup. @internal */
+    inputHost: HTMLElement | null;
+    /**
+     * @internal The mounted `<skdx-combobox-content>`. Registered rather than
+     * looked up, because it is also what tells `<skdx-combobox-input>` that
+     * something else owns Escape.
+     */
+    contentEl: HTMLElement | null;
+    /** Sets `value` and dispatches `value-change` (whose `detail` *is* the new value). A selection equal to the current one is a no-op. */
+    setValue(value: string | string[]): void;
+    /** Every selected value as an array, whatever shape `value` currently holds. */
+    get selectedValues(): string[];
+    /** Whether one option value is currently selected. */
+    isSelected(value: string): boolean;
+    /**
+     * Commits an option: single-select replaces the value, writes `text` into
+     * the draft, and closes; `multiple` toggles the value within the array,
+     * clears the draft (it was the search that found this option — keeping it
+     * would leave the list filtered down to the item just picked), and leaves
+     * the listbox open.
+     */
+    selectItem(value: string, text: string): void;
+    /**
+     * Whether an item's text survives the current `filter` predicate.
+     *
+     * 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;
+    private readonly itemRegistry;
+    /** @internal Called by each rendered `<skdx-combobox-item>` so Enter can commit it by id. */
+    registerItem(id: string, entry: SkdxComboboxItemEntry): void;
+    /** @internal Called when an item unmounts or is filtered out; a gone item can't stay highlighted. */
+    unregisterItem(id: string): void;
+    private reseedFrame?;
+    /**
+     * Virtual focus has to keep naming an option that is actually rendered, and
+     * the item the user is on is exactly the one ordinary typing removes: narrow
+     * the search and the highlighted option drops its `role="option"` from under
+     * it. Dropping the highlight there would leave the input with no
+     * aria-activedescendant while matches are still on screen, so a screen reader
+     * would announce nothing for the rest of the search — it is re-pointed at the
+     * first surviving option instead. Only an empty result set clears it:
+     * aria-activedescendant 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;
+    /**
+     * The registered entry for an option 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): SkdxComboboxItemEntry | undefined;
+    /** 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;
+    /** Opens the popup and highlights the first or last option once it mounts. */
+    openWithHighlight(edge: 'first' | 'last'): void;
+    /**
+     * Sets the virtually-focused option 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 emit;
+    private notify;
+    private defaultValue?;
+    /**
+     * Filtering happens in *our light DOM*, which doesn't trigger a Lit update —
+     * so the option count is watched with a MutationObserver rather than derived
+     * from a property. `announce` debounces, so a whole re-render's worth of
+     * mutations produces one announcement.
+     *
+     * Deliberately writes nothing back to the DOM: re-broadcasting from here
+     * would make every part's attribute writes loop-bearing (re-setting an
+     * attribute to the value it already has still produces a record).
+     * `<skdx-combobox-empty>` watches the same mutations itself instead.
+     */
+    private readonly itemObserver;
+    private announceResultCount;
+    /**
+     * Re-seeds the highlight whenever filtering leaves it with nothing, so Enter
+     * always has a target. Deferred a frame because the new item set has to be
+     * in the DOM before "first" means anything — same reason as
+     * {@link openWithHighlight}.
+     */
+    private maybeAutoHighlight;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private hasUpdatedOnce;
+    private teardownOpenChangeComplete?;
+    protected updated(changed: Map<string, unknown>): void;
+    private syncFormState;
+    /** Restores the selection and draft text the element was connected with. A reset fires no `value-change`. */
+    formResetCallback(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-combobox': SkdxCombobox;
+    }
+}
+export {};

package/dist/combobox/Combobox.js

@@ -0,0 +1,5 @@
+var d=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var s=(r,l,e,t)=>{for(var a=t>1?void 0:t?c(l,e):l,o=r.length-1,h;o>=0;o--)(h=r[o])&&(a=(t?h(l,e,a):h(a))||a);return t&&a&&d(l,e,a),a};import{css as p,html as m,LitElement as g}from"lit";import{property as n}from"lit/decorators.js";import{customElement as f}from"../internal/define.js";import{FormAssociated as v}from"../internal/form-associated.js";import{nextId as y}from"../internal/ids.js";import{notifyOpenChangeComplete as b}from"../internal/open-change-complete.js";import{nextSelection as A,toValues as I}from"../internal/selection.js";import{announce as V}from"../utils/live-announcer.js";var u='[role="option"]:not([data-disabled])';function E(r){return`${r} result${r===1?"":"s"} available`}var F={fromAttribute:r=>r??"",toAttribute:r=>Array.isArray(r)?null:r};function O(r,l){return Array.isArray(r)!==Array.isArray(l)?!1:!Array.isArray(r)||!Array.isArray(l)?r===l:r.length===l.length&&r.every((e,t)=>e===l[t])}var i=class extends v(g){constructor(){super(...arguments);this.value="";this.multiple=!1;this.allowCustomValue=!1;this.filter="manual";this.autoHighlight=!1;this.loading=!1;this.inputValue="";this.open=!1;this.invalid=!1;this.readOnly=!1;this.disabled=!1;this.required=!1;this.getResultCountLabel=E;this.contentId=y("skdx-combobox-content");this.activeId=null;this.inputHost=null;this.contentEl=null;this.itemRegistry=new Map;this.itemObserver=new MutationObserver(()=>this.announceResultCount());this.hasUpdatedOnce=!1}setValue(e){O(this.value,e)||(this.value=e,this.emit("value-change",e))}get selectedValues(){return I(this.value)}isSelected(e){return this.selectedValues.includes(e)}selectItem(e,t){if(!this.multiple){this.setValue(e),this.setInputValue(t),this.setOpen(!1);return}this.setValue(A(this.selectedValues,e,this.multiple)),this.setInputValue("")}matchesFilter(e){return this.filter==="manual"||this.filter(e,this.inputValue)}registerItem(e,t){this.itemRegistry.set(e,t)}unregisterItem(e){this.itemRegistry.delete(e),this.activeId===e&&this.scheduleReseed()}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(u));t.some(a=>a.id===e)||this.setActiveId(t[0]?.id??null)}))}getItem(e){return this.itemRegistry.get(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))}openWithHighlight(e){this.setOpen(!0),requestAnimationFrame(()=>{let t=Array.from(this.querySelectorAll(u));t.length!==0&&this.setActiveId((e==="last"?t[t.length-1]:t[0]).id)})}setActiveId(e){this.activeId=e,this.notify()}emit(e,t){this.dispatchEvent(new CustomEvent(e,{detail:t,bubbles:!0,composed:!0})),this.notify()}notify(){this.dispatchEvent(new CustomEvent("skdx-combobox-internal-update",{bubbles:!0,composed:!0})),this.requestUpdate()}announceResultCount(){!this.open||this.loading||V(this.getResultCountLabel(this.querySelectorAll(u).length))}maybeAutoHighlight(){!this.autoHighlight||!this.open||this.activeId!==null||requestAnimationFrame(()=>{if(!this.autoHighlight||!this.open||this.activeId!==null)return;let e=this.querySelector(u);e&&this.setActiveId(e.id)})}connectedCallback(){super.connectedCallback(),this.defaultValue??(this.defaultValue=this.value),this.itemObserver.observe(this,{childList:!0,subtree:!0,attributeFilter:["data-disabled","role"]})}disconnectedCallback(){this.itemObserver.disconnect(),this.reseedFrame!==void 0&&cancelAnimationFrame(this.reseedFrame),this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(e){let t=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,(e.has("value")||e.has("required")||e.has("multiple"))&&this.syncFormState(),e.has("open")&&this.open&&this.announceResultCount(),this.maybeAutoHighlight(),e.size>0&&this.dispatchEvent(new CustomEvent("skdx-combobox-internal-update",{bubbles:!0,composed:!0})),e.has("open")&&!t&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=b(()=>this.contentEl,this.open,a=>this.dispatchEvent(new CustomEvent("open-change-complete",{detail:a,bubbles:!0,composed:!0}))))}syncFormState(){this.setFormValue(this.multiple?this.multiFormValue(this.selectedValues):this.value),this.setValueMissing(this.required&&this.selectedValues.length===0,"Please select an item in the list.",this.inputHost?.shadowRoot?.querySelector("input"))}formResetCallback(){this.value=this.defaultValue??"",this.inputValue=this.getAttribute("input-value")??""}render(){return m`<slot></slot>`}};i.styles=p`
+    :host {
+      display: contents;
+    }
+  `,s([n({converter:F,reflect:!0})],i.prototype,"value",2),s([n({type:Boolean,reflect:!0})],i.prototype,"multiple",2),s([n({type:Boolean,attribute:"allow-custom-value",reflect:!0})],i.prototype,"allowCustomValue",2),s([n({attribute:!1})],i.prototype,"filter",2),s([n({type:Boolean,attribute:"auto-highlight",reflect:!0})],i.prototype,"autoHighlight",2),s([n({type:Boolean,reflect:!0})],i.prototype,"loading",2),s([n({type:String,attribute:"input-value"})],i.prototype,"inputValue",2),s([n({type:Boolean,reflect:!0})],i.prototype,"open",2),s([n({type:Boolean,reflect:!0})],i.prototype,"invalid",2),s([n({type:Boolean,attribute:"read-only",reflect:!0})],i.prototype,"readOnly",2),s([n({type:Boolean,reflect:!0})],i.prototype,"disabled",2),s([n({type:Boolean,reflect:!0})],i.prototype,"required",2),s([n({type:String,reflect:!0})],i.prototype,"name",2),s([n({attribute:"required-message"})],i.prototype,"requiredMessage",2),s([n({attribute:!1})],i.prototype,"getResultCountLabel",2),i=s([f("skdx-combobox")],i);export{u as OPTION_SELECTOR,i as SkdxCombobox,E as defaultGetResultCountLabel};

package/dist/combobox/ComboboxContent.cjs

@@ -0,0 +1,5 @@
+"use strict";var c=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var O=(n,i)=>{for(var t in i)c(n,t,{get:i[t],enumerable:!0})},E=(n,i,t,o)=>{if(i&&typeof i=="object"||typeof i=="function")for(let e of y(i))!g.call(n,e)&&e!==t&&c(n,e,{get:()=>i[e],enumerable:!(o=f(i,e))||o.enumerable});return n};var P=n=>E(c({},"__esModule",{value:!0}),n),r=(n,i,t,o)=>{for(var e=o>1?void 0:o?f(i,t):i,u=n.length-1,p;u>=0;u--)(p=n[u])&&(e=(o?p(i,t,e):p(e))||e);return o&&e&&c(i,t,e),e};var w={};O(w,{SkdxComboboxContent:()=>s});module.exports=P(w);var d=require("lit"),a=require("lit/decorators.js"),v=require("../internal/closest.cjs"),m=require("../internal/define.cjs"),l=require("../internal/dismiss.cjs"),h=require("../internal/positioning.cjs"),b=require("../internal/styles.cjs");var s=class extends d.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,l.dispatchEscapeKeyDown)(this,t)&&this.root.setOpen(!1))};this.handleOutsidePointerDown=t=>{!this.root?.open||this.isInside(t.target)||(0,l.dispatchOutside)(this,"pointer-down-outside",t)&&this.root.setOpen(!1)};this.handleOutsideFocus=t=>{if(!this.root?.open)return;let o=(0,l.focusOutsideTarget)(t);o===null||this.isInside(o)||(0,l.dispatchOutside)(this,"focus-outside",t)&&this.root.setOpen(!1)}}connectedCallback(){super.connectedCallback(),this.setAttribute("role","listbox"),this.root=(0,v.closestThroughPortal)(this,"skdx-combobox"),this.root&&(this.root.contentEl=this),this.root?.addEventListener("skdx-combobox-internal-update",this.onRootUpdate),this.addEventListener("mousedown",this.preventFocusSteal),document.addEventListener("keydown",this.handleDocumentKeyDown,!0),document.addEventListener("pointerdown",this.handleOutsidePointerDown),document.addEventListener("focusin",this.handleOutsideFocus),this.root&&(this.id=this.root.contentId),this.syncHostState()}disconnectedCallback(){this.root?.removeEventListener("skdx-combobox-internal-update",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?.(),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");for(let[o,e,u]of[["aria-multiselectable","data-multiple",this.root?.multiple],["aria-busy","data-loading",this.root?.loading]])u?(this.setAttribute(o,"true"),this.setAttribute(e,"")):(this.removeAttribute(o),this.removeAttribute(e));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:"combobox"}))}deactivate(){this.cleanupPosition?.(),this.cleanupPosition=void 0}render(){return d.html`<slot></slot>`}};s.styles=[b.hiddenHostStyles,d.css`
+      :host {
+        display: block;
+      }
+    `],r([(0,a.property)({type:String})],s.prototype,"side",2),r([(0,a.property)({type:String})],s.prototype,"align",2),r([(0,a.property)({type:Number,attribute:"side-offset"})],s.prototype,"sideOffset",2),r([(0,a.property)({type:Number,attribute:"align-offset"})],s.prototype,"alignOffset",2),r([(0,a.property)({converter:h.optOutBoolean,attribute:"avoid-collisions"})],s.prototype,"avoidCollisions",2),r([(0,a.property)({type:Number,attribute:"collision-padding"})],s.prototype,"collisionPadding",2),r([(0,a.property)({attribute:!1})],s.prototype,"collisionBoundary",2),s=r([(0,m.customElement)("skdx-combobox-content","combobox","content")],s);0&&(module.exports={SkdxComboboxContent});

package/dist/combobox/ComboboxContent.d.cts

@@ -0,0 +1,82 @@
+import { LitElement } from 'lit';
+import { type PositionOptions } from '../internal/positioning.cjs';
+/**
+ * `<skdx-combobox-content>` — the listbox popup for the closest ancestor
+ * `<skdx-combobox>`, positioned relative to `<skdx-combobox-input>` via
+ * `@floating-ui/dom` (`strategy: 'fixed'`). `role`, `id`, `data-state`, and
+ * the `data-side`/`data-align` placement hooks (seeded from the configured
+ * `side`/`align`, then rewritten by `positionFloating` with floating-ui's
+ * resolved placement) are set directly on this host element (not inside shadow DOM) for the
+ * same reason as `<skdx-select-content>`: `aria-controls` targets this
+ * element's id, and light-DOM `querySelectorAll` is how descendant items are
+ * found. Prevents `mousedown` from stealing focus off the input.
+ *
+ * `positionFloating` also writes the measurement custom properties
+ * `--skdx-combobox-available-width` / `-available-height` / `-trigger-width` /
+ * `-transform-origin` onto this element on every reposition, so the listbox
+ * can be sized (`max-height: var(--skdx-combobox-available-height)`) and
+ * animated from CSS without measuring anything by hand.
+ *
+ * Closes on Escape or on an outside interaction — pointer-down outside, or
+ * focus moving outside — each announced first as `interact-outside` and then as
+ * the specific event, so one `preventDefault()` vetoes either path. Escape is
+ * owned here rather than by `<skdx-combobox-input>`'s keydown handler: the
+ * document-level listener runs in the capture phase, i.e. *before* the input's,
+ * which is the only ordering in which a listener can still veto the close.
+ *
+ * @fires escape-key-down - Escape was pressed while open. Preventable.
+ * @fires pointer-down-outside - A pointer-down landed outside the combobox while open. Preventable.
+ * @fires focus-outside - Focus moved outside the combobox while open (detail: the original focusin). Preventable.
+ * @fires interact-outside - Either kind of outside interaction, fired immediately before the specific event so one handler can veto both. Preventable.
+ */
+export declare class SkdxComboboxContent extends LitElement {
+    static styles: import("lit").CSSResult[];
+    /** Preferred edge of the input to place the listbox against. */
+    side: PositionOptions['side'];
+    /** Preferred alignment along that edge relative to the input. */
+    align: PositionOptions['align'];
+    /** Pixel gap between the listbox and the input's edge. */
+    sideOffset: number;
+    /** Pixel offset along the alignment axis. */
+    alignOffset: number;
+    /** Flip/shift to stay within the viewport instead of overflowing it. */
+    avoidCollisions: boolean;
+    /**
+     * Minimum pixel distance to keep from the collision boundary when avoiding
+     * collisions. The `collision-padding` attribute sets a single number for
+     * every side; the per-side `{ top, right, bottom, left }` form is
+     * property-only, since an attribute cannot carry an object.
+     */
+    collisionPadding: NonNullable<PositionOptions['collisionPadding']>;
+    /**
+     * Element (or elements) collisions are measured against instead of this
+     * listbox's clipping ancestors — keeps it inside a scroll container or one
+     * pane of a split layout rather than the whole viewport. Property-only: an
+     * `Element` cannot come from an attribute string.
+     */
+    collisionBoundary?: PositionOptions['collisionBoundary'];
+    private root;
+    private readonly onRootUpdate;
+    private cleanupPosition?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private readonly preventFocusSteal;
+    /**
+     * The layer is the whole control, not just this panel: real focus lives on
+     * `<skdx-combobox-input>` for the entire interaction, so a target inside the
+     * root is never "outside".
+     */
+    private isInside;
+    private readonly handleDocumentKeyDown;
+    private readonly handleOutsidePointerDown;
+    private readonly handleOutsideFocus;
+    private syncHostState;
+    private activate;
+    private deactivate;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-combobox-content': SkdxComboboxContent;
+    }
+}