import { t as SigveloListboxItem } from "./listbox-item-DVJxOQBA.js"; import { CSSResultGroup, PropertyValues } from "lit"; import { SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element"; //#region src/components/listbox/listbox.d.ts /** * * * @summary Displays a list of options, allowing users to select one or more items from the available choices. * @tag sigvelo-listbox * @documentation https://design-system.sigvelo.com/docs/components/listbox * @status stable * @since 1.0 * * @dependency listbox-item * * @slot - Listbox items to show in the listbox. * @slot label - The listbox's label. For plain-text labels, you can use the `label` attribute instead. * @slot description - The listbox's description. For plain-text descriptions, you can use the `description` attribute * instead. * * @event sigvelo-blur - Emitted when the list box loses focus. This event does not bubble. * @event sigvelo-change - Emitted when the user commits changes to the list box's selection. In single select mode, it * occurs when a change is made and the listbox loses focus. In multiselect mode, it occurs whenever an option is * toggled even while the listbox has focus. * @event sigvelo-focus - Emitted when the list box receives focus. This event does not bubble. * @event sigvelo-input - Emitted when the list box's selection changes from user input. * * @csspart label - The element that contains the text field's label. * @csspart description - The element that contains the text field's description. * @csspart listbox - The internal listbox container that holds listbox items. * * @cssstate disabled - Applied when the text field is disabled. * @cssstate blank - Applied when the text field has a blank value. * @cssstate focused - Applied when the text field has focus. * @cssstate user-valid - Applied when the text field is valid and the user has sufficiently interacted with it. * @cssstate user-invalid - Applied when the text field is invalid and the user has sufficiently interacted with it. * * @example Default * Listboxes follow the ARIA APG listbox pattern for accessibility. The listbox is labeled for assistive devices and listbox items are announced as options. To function more like native listboxes, the alternate selection model is used for keyboard interaction. * * ```html * * Bella * Luna * Meowy McGee * Milo * Mittens * Oliver * Pepper * Shadow * Simba * Whiskers * * ``` * * @example Labels and descriptions * You can use the `label` and `description` attributes to provide plain text labels and descriptions for the listbox. If you want to provide HTML, use the `label` and `description` slots instead. * * ```html * * Feline Friends * * For adoption information, visit our cat sanctuary. * * Whiskers (3 years old) * Mittens (2 years old) * Shadow (5 years old) * * ``` * * @example Providing options * Create listbox options by adding `` elements inside the listbox. Each item should have a `value` attribute that will be submitted with the form. * * ```html * * Feather Wand * Laser Pointer * Catnip Mouse * Crinkle Tunnel * Cardboard Box * * ``` * * Listbox items can have structured content, too. * * ```html * * *

Feather Wand

* * * *

Laser Pointer

* * * *

Catnip Mouse

* * * *

Crinkle Tunnel

* * * *

Cardboard Box

* * * * * * ``` * * **Warning:** Avoid placing interactive elements such as buttons and links inside the listbox item, as this will hinder accessibility and can lead to unexpected behaviors. * * @example Providing an initial value * Add the `selected` attribute to the listbox item you want to select initially. When using `multiple`, you can apply `selected` to more than one option. * * ```html * * Sunny Windowsill * Human's Lap * Middle of the Bed * Computer Keyboard * * ``` * * @example Getting and setting the selection * Listboxes provide several properties for interacting with their selection state programmatically. Use the `value` property for getting/setting a single value. Use the `selectedValues` property for multiple values. If you need to get or set a list of selected `` elements, use the `selectedItems` property. * * #### Getting the selection * * Use `value` to get a single value. To get all selected values, use `selectedValues`. If you need to get an array of DOM elements, use `selectedItems`. * * ```js * // Get the first selected value * const value = listbox.value; * * // Get an array of all selected values * const values = listbox.selectedValues; * * // Get an array of all selected listbox item elements * const items = listbox.selectedItems; * ``` * * #### Setting the selection * * Use `value` to set a single value. To set multiple values, use `selectedValues`. If you need to get or set the selection via DOM elements, use `selectedItems`. * * ```js * // Set a single value * listbox.value = 'a'; * * // Set multiple values * listbox.selectedValues = ['a', 'b', 'c']; * * // Set using DOM elements * const itemA = document.querySelector('sigvelo-listbox-item#a'); * const itemB = document.querySelector('sigvelo-listbox-item#b'); * const itemC = document.querySelector('sigvelo-listbox-item#c'); * * listbox.selectedItems = [itemA, itemB, itemC]; * ``` * * #### Convenience methods * * Use `selectAll()` and `deselectAll()` as a quick way to select all or no items. * * ```js * // Select all items * listbox.selectAll(); * * // Deselect all items * listbox.deselectAll(); * ``` * * @example Disabling items * Add the `disabled` attribute to individual listbox items to make them non-selectable. * * ```html * * Morning (7am) * Noon (12pm) * Night (10pm) - Currently unavailable * * ``` * * @example Multiple selection * Use the `multiple` attribute to enable multi-selection mode. Users can select multiple items using or + click, + click for ranges, or to select all. For coarse pointers, such as touch, tapping an item will toggle the selection. * * ```html * * Midnight Zoomies * Knocking Things Off Tables * Ignoring Expensive Toys * Sitting on Open Books * Watching Birds Through Windows * Following You to the Bathroom * Demanding Pets Then Biting * Sleeping in Weird Positions * Hiding in Paper Bags * Sudden Grooming Sessions * * ``` * * @example Changing the size * Use the `size` attribute to change the listbox's size. * * ```html * * * * * * * * * * Cat Tree * Food Bowl * Scratching Post * Toy Mouse * * * * ``` * * @example Disabling * Add the `disabled` attribute to disable the entire listbox. * * ```html * * Tuna Treats * Chicken Bites * Salmon Flakes * Cheese Nibbles * Catnip Crisps * * ``` * * @example Showing labels on the side * With the `sigvelo-side-label` utility, you can show labels on the side instead of on top of the listbox. You can control the width of the label by setting the `--label-width` custom property. * * ```html * * Short-haired * Long-haired * Curly-coated * *
* * Green * Blue * Amber * * ``` * * @example Validation * The `required` attribute can be used to enable validation using the Constraint Validation API. * * ```html * * ``` * * @example Using custom validation * Use the `setCustomValidity()` method to make the listbox invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, call the method with an empty string. * * ```html * * * * ``` * * @example Styling validation * You can style valid and invalid listboxes using the `:valid` and `:invalid` pseudo classes. * * ```html * * * * ``` * * However, these selectors will match even before the user has had a chance to interact with the form. More often than not, you'll want to use the `user-valid` and `user-invalid` custom states instead. This way, validation styles are only shown _after_ the user interacts with the form control or when the form is submitted. * * ```html * * * * ``` * * @example Styling listboxes * Listboxes are styled like form controls for consistency, but feel free to customize them to your liking. Here's an example you might see in an email client. * * ```html * * * *

Sir Fluffington III

* 2:45 PM * * * * * * *

Captain Whiskers

* 1:37 PM * * * * * * *

Lady Purrlington

* 11:15 AM * * * * * *

Meowy McGee

* 10:22 AM * * * * * * *

Chairman Meow

* 9:30 AM * * * * * * ``` * * **Note:** Note the use of `aria-hidden` on summaries, which reduces verbosity when used with screen readers. */ declare class SigveloListbox extends SigveloFormControlElement { static formAssociated: boolean; static observeSlots: boolean; static styles: CSSResultGroup; private localize; private firstSelectedValue; private listbox; protected hadUserInteraction: boolean; protected isInvalid: boolean; private lastSelectedIndex; private previousValue; private typeaheadBuffer; private typeaheadTimeout; private wasChanged; protected wasSubmitted: boolean; /** The listbox's label. If you need to provide HTML in the label, use the `label` slot instead. */ label: string; /** The listbox's description. If you need to provide HTML in the description, use the `description` slot instead. */ description: string; /** The name of the listbox. This will be submitted with the form as a name/value pair. */ name: string; /** Enables multiple selection mode. */ multiple: boolean; /** Disables the listbox. */ disabled: boolean; /** Makes the text field a read-only field. */ readonly: boolean; /** The text field's size. */ size: "xs" | "sm" | "md" | "lg" | "xl"; /** * The form to associate this control with. If omitted, the closest containing `

` will be used. The value of * this attribute must be an ID of a form in the same document or shadow root. */ form: string; /** Makes the listbox required. Form submission will not be allowed when this is set and the listbox is blank. */ required: boolean; /** The listbox's value. For multiple selection, this will be the value of the first selected item. */ get value(): string; set value(newValue: string); /** * Gets or sets the currently selected values as an array. This property provides a consistent way to access or modify * the selection state regardless of whether the listbox is in single or multiple selection mode. * * In single selection mode, it returns an array with either zero or one value. In multiple selection mode, it returns * an array of all selected values. * * When setting this property in single mode, the first value in the array (if any) becomes the selected value. In * multiple mode, all values in the array become selected. */ get selectedValues(): string[]; set selectedValues(values: string[]); /** Gets or sets an array of selected listbox items. */ get selectedItems(): SigveloListboxItem[]; set selectedItems(items: SigveloListboxItem[]); protected get focusableAnchor(): HTMLInputElement; connectedCallback(): void; disconnectedCallback(): void; firstUpdated(changedProperties: PropertyValues): void; updated(changedProperties: PropertyValues): void; formResetCallback(): void; private clearTypeaheadTimeout; private getItems; private getSelectedItems; private initializeValueFromSelectedItems; private initializeItems; private updateItemSelectionFromValue; private updateFormValue; private updateSelectedItems; /** * Updates the current value to align with selected items. We track user interaction to allow us to dispatch events * when human changes are made and suppress them for programmatic changes. */ private updateValueFromSelectedItems; private handleFocus; private handleBlur; private handleLabelClick; private handleListboxPointerDown; private handleItemClick; private handleItemSelection; private handleKeyDown; /** * Moves the active item, applying the selection semantics implied by the * modifier keys. * * Takes only the modifier flags rather than the `KeyboardEvent`, because two * call sites synthesise a modifier combination that did not happen (Ctrl is * forced on for Ctrl+Shift+Home/End). Spreading a real event to fake that * produced a plain object with none of the event prototype's accessors. */ private navigateToItem; private updateListboxAttributesOnItems; private selectWithKeyboard; private handleSlotChange; private selectSingleItem; private handleTypeahead; private findTypeaheadMatch; private setActiveItem; private scrollItemIntoView; private updateValidity; /** * @internal Manage tab order and focus tracking for keyboard navigation */ resetRovingTabIndex(): void; /** Returns an array of all selected values. */ getSelectedValues(): string[]; /** * Sets the selected items by value(s) without triggering events. * Works for both single and multiple selection modes. * @param {string|string[]} values - Value(s) to select */ setSelectedValues(values: string | string[]): void; /** Convenience method for selecting all items. */ selectAll(): void; /** Convenience method for deselecting all items. */ deselectAll(): void; /** Sets focus to the listbox. */ focus(): void; /** Removes focus from the listbox. */ blur(): void; render(): import("lit-html").TemplateResult<1>; } declare global { interface HTMLElementTagNameMap { "sigvelo-listbox": SigveloListbox; } } //#endregion export { SigveloListbox as t };