@ni/fast-foundation 0.0.2

package/dist/dts/listbox/listbox.d.ts

@@ -0,0 +1,314 @@
+import { FoundationElement } from "../foundation-element/foundation-element.js";
+import { ListboxOption } from "../listbox-option/listbox-option.js";
+import { ARIAGlobalStatesAndProperties } from "../patterns/aria-global.js";
+/**
+ * A Listbox Custom HTML Element.
+ * Implements the {@link https://www.w3.org/TR/wai-aria-1.1/#listbox | ARIA listbox }.
+ *
+ * @slot - The default slot for the listbox options
+ *
+ * @public
+ */
+export declare abstract class Listbox extends FoundationElement {
+    /**
+     * The internal unfiltered list of selectable options.
+     *
+     * @internal
+     */
+    protected _options: ListboxOption[];
+    /**
+     * The first selected option.
+     *
+     * @internal
+     */
+    get firstSelectedOption(): ListboxOption;
+    /**
+     * Returns true if there is one or more selectable option.
+     *
+     * @internal
+     */
+    protected get hasSelectableOptions(): boolean;
+    /**
+     * The number of options.
+     *
+     * @public
+     */
+    get length(): number;
+    /**
+     * The list of options.
+     *
+     * @public
+     */
+    get options(): ListboxOption[];
+    set options(value: ListboxOption[]);
+    /**
+     * Flag for the typeahead timeout expiration.
+     *
+     * @deprecated use `Listbox.typeaheadExpired`
+     * @internal
+     */
+    protected get typeAheadExpired(): boolean;
+    protected set typeAheadExpired(value: boolean);
+    /**
+     * The disabled state of the listbox.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `disabled`
+     */
+    disabled: boolean;
+    /**
+     * The index of the selected option.
+     *
+     * @public
+     */
+    selectedIndex: number;
+    /**
+     * A collection of the selected options.
+     *
+     * @public
+     */
+    selectedOptions: ListboxOption[];
+    /**
+     * A standard `click` event creates a `focus` event before firing, so a
+     * `mousedown` event is used to skip that initial focus.
+     *
+     * @internal
+     */
+    protected shouldSkipFocus: boolean;
+    /**
+     * A static filter to include only selectable options.
+     *
+     * @param n - element to filter
+     * @public
+     */
+    static slottedOptionFilter: (n: HTMLElement) => boolean;
+    /**
+     * The default slotted elements.
+     *
+     * @internal
+     */
+    slottedOptions: Element[];
+    /**
+     * Typeahead timeout in milliseconds.
+     *
+     * @internal
+     */
+    protected static readonly TYPE_AHEAD_TIMEOUT_MS = 1000;
+    /**
+     * The current typeahead buffer string.
+     *
+     * @internal
+     */
+    protected typeaheadBuffer: string;
+    /**
+     * Flag for the typeahead timeout expiration.
+     *
+     * @internal
+     */
+    protected typeaheadExpired: boolean;
+    /**
+     * The timeout ID for the typeahead handler.
+     *
+     * @internal
+     */
+    protected typeaheadTimeout: number;
+    /**
+     * Handle click events for listbox options.
+     *
+     * @internal
+     */
+    clickHandler(e: MouseEvent): boolean | void;
+    /**
+     * Ensures that the provided option is focused and scrolled into view.
+     *
+     * @param optionToFocus - The option to focus
+     * @internal
+     */
+    protected focusAndScrollOptionIntoView(optionToFocus?: ListboxOption | null): void;
+    /**
+     * Handles `focusin` actions for the component. When the component receives focus,
+     * the list of selected options is refreshed and the first selected option is scrolled
+     * into view.
+     *
+     * @internal
+     */
+    focusinHandler(e: FocusEvent): void;
+    /**
+     * Returns the options which match the current typeahead buffer.
+     *
+     * @internal
+     */
+    protected getTypeaheadMatches(): ListboxOption[];
+    /**
+     * Determines the index of the next option which is selectable, if any.
+     *
+     * @param prev - the previous selected index
+     * @param next - the next index to select
+     *
+     * @internal
+     */
+    protected getSelectableIndex(prev: number | undefined, next: number): number;
+    /**
+     * Handles external changes to child options.
+     *
+     * @param source - the source object
+     * @param propertyName - the property
+     *
+     * @internal
+     */
+    handleChange(source: any, propertyName: string): void;
+    /**
+     * Moves focus to an option whose label matches characters typed by the user.
+     * Consecutive keystrokes are batched into a buffer of search text used
+     * to match against the set of options.  If `TYPE_AHEAD_TIMEOUT_MS` passes
+     * between consecutive keystrokes, the search restarts.
+     *
+     * @param key - the key to be evaluated
+     *
+     * @internal
+     */
+    handleTypeAhead(key: string): void;
+    /**
+     * Handles `keydown` actions for listbox navigation and typeahead.
+     *
+     * @internal
+     */
+    keydownHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Prevents `focusin` events from firing before `click` events when the
+     * element is unfocused.
+     *
+     * @internal
+     */
+    mousedownHandler(e: MouseEvent): boolean | void;
+    /**
+     * Switches between single-selection and multi-selection mode.
+     *
+     * @param prev - the previous value of the `multiple` attribute
+     * @param next - the next value of the `multiple` attribute
+     *
+     * @internal
+     */
+    multipleChanged(prev: boolean | undefined, next: boolean): void;
+    /**
+     * Updates the list of selected options when the `selectedIndex` changes.
+     *
+     * @param prev - the previous selected index value
+     * @param next - the current selected index value
+     *
+     * @internal
+     */
+    selectedIndexChanged(prev: number | undefined, next: number): void;
+    /**
+     * Updates the selectedness of each option when the list of selected options changes.
+     *
+     * @param prev - the previous list of selected options
+     * @param next - the current list of selected options
+     *
+     * @internal
+     */
+    protected selectedOptionsChanged(prev: ListboxOption[] | undefined, next: ListboxOption[]): void;
+    /**
+     * Moves focus to the first selectable option.
+     *
+     * @public
+     */
+    selectFirstOption(): void;
+    /**
+     * Moves focus to the last selectable option.
+     *
+     * @internal
+     */
+    selectLastOption(): void;
+    /**
+     * Moves focus to the next selectable option.
+     *
+     * @internal
+     */
+    selectNextOption(): void;
+    /**
+     * Moves focus to the previous selectable option.
+     *
+     * @internal
+     */
+    selectPreviousOption(): void;
+    /**
+     * Updates the selected index to match the first selected option.
+     *
+     * @internal
+     */
+    protected setDefaultSelectedOption(): void;
+    /**
+     * Sets an option as selected and gives it focus.
+     *
+     * @public
+     */
+    protected setSelectedOptions(): void;
+    /**
+     * Updates the list of options and resets the selected option when the slotted option content changes.
+     *
+     * @param prev - the previous list of slotted options
+     * @param next - the current list of slotted options
+     *
+     * @internal
+     */
+    slottedOptionsChanged(prev: Element[] | undefined, next: Element[]): void;
+    /**
+     * Updates the filtered list of options when the typeahead buffer changes.
+     *
+     * @param prev - the previous typeahead buffer value
+     * @param next - the current typeahead buffer value
+     *
+     * @internal
+     */
+    typeaheadBufferChanged(prev: string, next: string): void;
+}
+/**
+ * Includes ARIA states and properties relating to the ARIA listbox role
+ *
+ * @public
+ */
+export declare class DelegatesARIAListbox {
+    /**
+     * See {@link https://www.w3.org/TR/wai-aria-1.2/#listbox} for more information
+     * @public
+     * @remarks
+     * HTML Attribute: `aria-activedescendant`
+     */
+    ariaActiveDescendant: string | null;
+    /**
+     * See {@link https://www.w3.org/TR/wai-aria-1.2/#listbox} for more information
+     * @public
+     * @remarks
+     * HTML Attribute: `aria-disabled`
+     */
+    ariaDisabled: "true" | "false" | string | null;
+    /**
+     * See {@link https://www.w3.org/TR/wai-aria-1.2/#listbox} for more information
+     * @public
+     * @remarks
+     * HTML Attribute: `aria-expanded`
+     */
+    ariaExpanded: "true" | "false" | string | null;
+    /**
+     * See {@link https://w3c.github.io/aria/#listbox} for more information
+     * @public
+     * @remarks
+     * HTML Attribute: `aria-multiselectable`
+     */
+    ariaMultiSelectable: "true" | "false" | string | null;
+}
+/**
+ * Mark internal because exporting class and interface of the same name
+ * confuses API documenter.
+ * TODO: https://github.com/microsoft/fast/issues/3317
+ * @internal
+ */
+export interface DelegatesARIAListbox extends ARIAGlobalStatesAndProperties {
+}
+/**
+ * @internal
+ */
+export interface Listbox extends DelegatesARIAListbox {
+}

package/dist/dts/listbox/listbox.element.d.ts

@@ -0,0 +1,223 @@
+import type { ListboxOption } from "../listbox-option/listbox-option.js";
+import { Listbox } from "./listbox.js";
+/**
+ * A Listbox Custom HTML Element.
+ * Implements the {@link https://w3c.github.io/aria/#listbox | ARIA listbox }.
+ *
+ * @public
+ */
+export declare class ListboxElement extends Listbox {
+    /**
+     * The index of the most recently checked option.
+     *
+     * @internal
+     * @remarks
+     * Multiple-selection mode only.
+     */
+    protected activeIndex: number;
+    /**
+     * Returns the last checked option.
+     *
+     * @internal
+     */
+    get activeOption(): ListboxOption | null;
+    /**
+     * Returns the list of checked options.
+     *
+     * @internal
+     */
+    protected get checkedOptions(): ListboxOption[];
+    /**
+     * Returns the index of the first selected option.
+     *
+     * @internal
+     */
+    get firstSelectedOptionIndex(): number;
+    /**
+     * Indicates if the listbox is in multi-selection mode.
+     *
+     * @remarks
+     * HTML Attribute: `multiple`
+     *
+     * @public
+     */
+    multiple: boolean;
+    /**
+     * The start index when checking a range of options.
+     *
+     * @internal
+     */
+    protected rangeStartIndex: number;
+    /**
+     * The maximum number of options to display.
+     *
+     * @remarks
+     * HTML Attribute: `size`.
+     *
+     * @public
+     */
+    size: number;
+    /**
+     * Updates the `ariaActiveDescendant` property when the active index changes.
+     *
+     * @param prev - the previous active index
+     * @param next - the next active index
+     *
+     * @internal
+     */
+    protected activeIndexChanged(prev: number | undefined, next: number): void;
+    /**
+     * Toggles the checked state for the currently active option.
+     *
+     * @remarks
+     * Multiple-selection mode only.
+     *
+     * @internal
+     */
+    protected checkActiveIndex(): void;
+    /**
+     * Sets the active index to the first option and marks it as checked.
+     *
+     * @remarks
+     * Multi-selection mode only.
+     *
+     * @param preserveChecked - mark all options unchecked before changing the active index
+     *
+     * @internal
+     */
+    protected checkFirstOption(preserveChecked?: boolean): void;
+    /**
+     * Decrements the active index and sets the matching option as checked.
+     *
+     * @remarks
+     * Multi-selection mode only.
+     *
+     * @param preserveChecked - mark all options unchecked before changing the active index
+     *
+     * @internal
+     */
+    protected checkLastOption(preserveChecked?: boolean): void;
+    /**
+     * @override
+     * @internal
+     */
+    connectedCallback(): void;
+    /**
+     * @override
+     * @internal
+     */
+    disconnectedCallback(): void;
+    /**
+     * Increments the active index and marks the matching option as checked.
+     *
+     * @remarks
+     * Multiple-selection mode only.
+     *
+     * @param preserveChecked - mark all options unchecked before changing the active index
+     *
+     * @internal
+     */
+    protected checkNextOption(preserveChecked?: boolean): void;
+    /**
+     * Decrements the active index and marks the matching option as checked.
+     *
+     * @remarks
+     * Multiple-selection mode only.
+     *
+     * @param preserveChecked - mark all options unchecked before changing the active index
+     *
+     * @internal
+     */
+    protected checkPreviousOption(preserveChecked?: boolean): void;
+    /**
+     * Handles click events for listbox options.
+     *
+     * @param e - the event object
+     *
+     * @override
+     * @internal
+     */
+    clickHandler(e: MouseEvent): boolean | void;
+    /**
+     * @override
+     * @internal
+     */
+    protected focusAndScrollOptionIntoView(): void;
+    /**
+     * In multiple-selection mode:
+     * If any options are selected, the first selected option is checked when
+     * the listbox receives focus. If no options are selected, the first
+     * selectable option is checked.
+     *
+     * @override
+     * @internal
+     */
+    focusinHandler(e: FocusEvent): boolean | void;
+    /**
+     * Unchecks all options when the listbox loses focus.
+     *
+     * @internal
+     */
+    focusoutHandler(e: FocusEvent): void;
+    /**
+     * Handles keydown actions for listbox navigation and typeahead
+     *
+     * @override
+     * @internal
+     */
+    keydownHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Prevents `focusin` events from firing before `click` events when the
+     * element is unfocused.
+     *
+     * @override
+     * @internal
+     */
+    mousedownHandler(e: MouseEvent): boolean | void;
+    /**
+     * Switches between single-selection and multi-selection mode.
+     *
+     * @internal
+     */
+    multipleChanged(prev: boolean | undefined, next: boolean): void;
+    /**
+     * Sets an option as selected and gives it focus.
+     *
+     * @override
+     * @public
+     */
+    protected setSelectedOptions(): void;
+    /**
+     * Ensures the size is a positive integer when the property is updated.
+     *
+     * @param prev - the previous size value
+     * @param next - the current size value
+     *
+     * @internal
+     */
+    protected sizeChanged(prev: number | unknown, next: number): void;
+    /**
+     * Toggles the selected state of the provided options. If any provided items
+     * are in an unselected state, all items are set to selected. If every
+     * provided item is selected, they are all unselected.
+     *
+     * @internal
+     */
+    toggleSelectedForAllCheckedOptions(): void;
+    /**
+     * @override
+     * @internal
+     */
+    typeaheadBufferChanged(prev: string, next: string): void;
+    /**
+     * Unchecks all options.
+     *
+     * @remarks
+     * Multiple-selection mode only.
+     *
+     * @param preserveChecked - reset the rangeStartIndex
+     *
+     * @internal
+     */
+    protected uncheckAllOptions(preserveChecked?: boolean): void;
+}

package/dist/dts/listbox/listbox.template.d.ts

@@ -0,0 +1,8 @@
+import type { ViewTemplate } from "@ni/fast-element";
+import type { FoundationElementTemplate } from "../foundation-element/foundation-element.js";
+import { ListboxElement } from "./listbox.element.js";
+/**
+ * The template for the {@link @ni/fast-foundation#(Listbox:class)} component.
+ * @public
+ */
+export declare const listboxTemplate: FoundationElementTemplate<ViewTemplate<ListboxElement>>;

package/dist/dts/listbox-option/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./listbox-option.js";
+export * from "./listbox-option.template.js";