@fluentui/web-components 3.0.0-beta.9 → 3.0.0-beta.91

package/dist/dts/dropdown/define.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/dropdown/dropdown.base.d.ts

@@ -0,0 +1,479 @@
+import { FASTElement } from '@microsoft/fast-element';
+import type { Listbox } from '../listbox/listbox.js';
+import type { DropdownOption } from '../option/option.js';
+import { DropdownType } from './dropdown.options.js';
+/**
+ * A Dropdown Custom HTML Element.
+ * Implements the {@link https://w3c.github.io/aria/#combobox | ARIA combobox } role.
+ *
+ * @remarks
+ * The Dropdown element does not provide a form association value. Instead, the slotted Option elements handle form
+ * association the same way as {@link (Checkbox:class)} elements. See the {@link (DropdownOption:class)} element for
+ * more details.
+ *
+ * @slot - The default slot. Accepts a {@link (Listbox:class)} element.
+ * @slot indicator - The indicator slot.
+ * @slot control - The control slot. This slot is automatically populated and should not be manually manipulated.
+ *
+ * @public
+ */
+export declare class BaseDropdown extends FASTElement {
+    /**
+     * Static property for the anchor positioning fallback observer. The observer is used to flip the listbox when it is
+     * out of view.
+     * @remarks This is only used when the browser does not support CSS anchor positioning.
+     * @internal
+     */
+    private static AnchorPositionFallbackObserver;
+    /**
+     * The ID of the current active descendant.
+     *
+     * @public
+     */
+    get activeDescendant(): string | undefined;
+    /**
+     * The index of the currently active option.
+     *
+     * @internal
+     */
+    activeIndex: number;
+    /**
+     * Sets the active index when the active index property changes.
+     *
+     * @param prev - the previous active index
+     * @param next - the current active index
+     * @internal
+     */
+    activeIndexChanged(prev: number | undefined, next: number | undefined): void;
+    /**
+     * The `aria-labelledby` attribute value of the dropdown.
+     *
+     * @public
+     */
+    ariaLabelledBy: string;
+    /**
+     * Reference to the control element.
+     * @internal
+     */
+    control: HTMLInputElement;
+    /**
+     * Updates properties on the control element when the control slot changes.
+     *
+     * @param prev - the previous control element
+     * @param next - the current control element
+     * @internal
+     * @remarks
+     * The control element is assigned to the dropdown via the control slot with manual slot assignment.
+     */
+    controlChanged(prev: HTMLInputElement | undefined, next: HTMLInputElement | undefined): void;
+    /**
+     * The disabled state of the dropdown.
+     * @public
+     */
+    disabled?: boolean;
+    /**
+     * Updates the disabled state of the options when the disabled property changes.
+     *
+     * @param prev - the previous disabled state
+     * @param next - the current disabled state
+     */
+    disabledChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The display value for the control.
+     *
+     * @public
+     */
+    get displayValue(): string;
+    /**
+     * Sets the listbox ID to a unique value if one is not provided.
+     *
+     * @override
+     * @public
+     * @remarks
+     * HTML Attribute: `id`
+     */
+    id: string;
+    /**
+     * Reference to the indicator button element.
+     *
+     * @internal
+     */
+    indicator: HTMLDivElement;
+    /**
+     * Reference to the indicator slot element.
+     *
+     * @internal
+     */
+    indicatorSlot?: HTMLSlotElement;
+    /**
+     * The value of the selected option.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `value`
+     */
+    initialValue?: string;
+    /**
+     * Reference to the slotted listbox element.
+     *
+     * @internal
+     */
+    listbox: Listbox;
+    /**
+     * Updates properties on the listbox element when the listbox reference changes.
+     *
+     * @param prev - the previous listbox element
+     * @param next - the current listbox element
+     * @internal
+     *
+     * @remarks
+     * The listbox element is assigned to the dropdown via the default slot with manual slot assignment.
+     */
+    listboxChanged(prev: Listbox | undefined, next: Listbox | undefined): void;
+    /**
+     * Reference to the listbox slot element.
+     *
+     * @internal
+     */
+    listboxSlot: HTMLSlotElement;
+    /**
+     * Indicates whether the dropdown allows multiple options to be selected.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `multiple`
+     */
+    multiple?: boolean;
+    /**
+     * Toggles between single and multiple selection modes when the `multiple` property changes.
+     *
+     * @param prev - the previous multiple state
+     * @param next - the next multiple state
+     * @internal
+     */
+    protected multipleChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The name of the dropdown.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `name`
+     */
+    name: string;
+    /**
+     * Updates the name of the options when the name property changes.
+     *
+     * @param prev - the previous name
+     * @param next - the current name
+     */
+    nameChanged(prev: string, next: string): void;
+    /**
+     * Indicates whether the dropdown is open.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `open`
+     */
+    open: boolean;
+    /**
+     * Handles the open state of the dropdown.
+     *
+     * @param prev - the previous open state
+     * @param next - the current open state
+     *
+     * @internal
+     */
+    openChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The placeholder text of the dropdown.
+     *
+     * @public
+     */
+    placeholder: string;
+    /**
+     * The required state of the dropdown.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `required`
+     */
+    required: boolean;
+    /**
+     * The dropdown type.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `type`
+     */
+    type: DropdownType;
+    /**
+     * Changes the slotted control element based on the dropdown type.
+     *
+     * @param prev - the previous dropdown type
+     * @param next - the current dropdown type
+     * @internal
+     */
+    typeChanged(prev: DropdownType | undefined, next: DropdownType | undefined): void;
+    /**
+     * The initial value of the control. When the control is a combobox, this value is used to set the value of the
+     * control when the dropdown is initialized.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `value`
+     */
+    valueAttribute: string;
+    /**
+     * The slot element for the control.
+     * @internal
+     */
+    controlSlot: HTMLSlotElement;
+    /**
+     * The internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    elementInternals: ElementInternals;
+    /**
+     * The collection of enabled options.
+     * @public
+     */
+    get enabledOptions(): DropdownOption[];
+    /**
+     * The form-associated flag.
+     * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example | Form-associated custom elements}
+     *
+     * @public
+     */
+    static formAssociated: boolean;
+    /**
+     * Resets the form value to its initial value when the form is reset.
+     *
+     * @internal
+     */
+    formResetCallback(): void;
+    /**
+     * A reference to the first freeform option, if present.
+     *
+     * @internal
+     */
+    private get freeformOption();
+    /**
+     * Indicates whether the dropdown is a combobox.
+     *
+     * @internal
+     */
+    private get isCombobox();
+    /**
+     * A reference to all associated label elements.
+     *
+     * @public
+     */
+    get labels(): ReadonlyArray<Node>;
+    /**
+     * The list formatter for the dropdown. Used to format the display value when the dropdown is in multiple selection mode.
+     *
+     * @internal
+     */
+    private listFormatter?;
+    /**
+     * The list collator for the dropdown. Used to filter options based on the input value.
+     *
+     * @internal
+     */
+    private listCollator?;
+    /**
+     * The collection of all child options.
+     *
+     * @public
+     */
+    get options(): DropdownOption[];
+    /**
+     * The index of the first selected option, scoped to the enabled options.
+     *
+     * @internal
+     * @remarks
+     * This property is a reflection of {@link Listbox.selectedIndex}.
+     */
+    get selectedIndex(): number;
+    /**
+     * The collection of selected options.
+     *
+     * @public
+     * @remarks
+     * This property is a reflection of {@link Listbox.selectedOptions}.
+     */
+    get selectedOptions(): DropdownOption[];
+    /**
+     * The fallback validation message, taken from a native `<input>` element.
+     *
+     * @internal
+     */
+    private _validationFallbackMessage;
+    /**
+     * The validation message. Uses the browser's default validation message for native checkboxes if not otherwise
+     * specified (e.g., via `setCustomValidity`).
+     *
+     * @internal
+     */
+    get validationMessage(): string;
+    /**
+     * The element's validity state.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/validity | `ElementInternals.validity`} property.
+     */
+    get validity(): ValidityState;
+    /**
+     * The current value of the selected option.
+     *
+     * @public
+     */
+    get value(): string | null;
+    set value(next: string | null);
+    /**
+     * Determines if the control can be submitted for constraint validation.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/willValidate | `ElementInternals.willValidate`} property.
+     */
+    get willValidate(): boolean;
+    /**
+     * Handles the change events for the dropdown.
+     *
+     * @param e - the event object
+     *
+     * @public
+     */
+    changeHandler(e: Event): boolean | void;
+    /**
+     * Checks the validity of the element and returns the result.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/checkValidity | `HTMLInputElement.checkValidity()`} method.
+     */
+    checkValidity(): boolean;
+    /**
+     * Handles the click events for the dropdown.
+     *
+     * @param e - the event object
+     *
+     * @public
+     */
+    clickHandler(e: PointerEvent): boolean | void;
+    constructor();
+    /**
+     * Filters the options based on the input value.
+     *
+     * @param value - the input value to filter the options by
+     * @param collection - the collection of options to filter
+     * @returns the filtered options
+     * @internal
+     */
+    filterOptions(value: string, collection?: DropdownOption[]): DropdownOption[];
+    /**
+     * Focuses the control when the dropdown receives focus.
+     *
+     * @internal
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * Toggles the listbox when the control element loses focus.
+     *
+     * @param e - the focus event
+     * @internal
+     */
+    focusoutHandler(e: FocusEvent): boolean | void;
+    /**
+     * Ensures the active index is within bounds of the enabled options. Out-of-bounds indices are wrapped to the opposite
+     * end of the range.
+     *
+     * @param index - the desired index
+     * @param upperBound - the upper bound of the range
+     * @returns the index in bounds
+     * @internal
+     */
+    private getEnabledIndexInBounds;
+    /**
+     * Handles the input events for the dropdown from the control element.
+     *
+     * @param e - the input event
+     * @public
+     */
+    inputHandler(e: InputEvent): boolean | void;
+    /**
+     * Inserts the control element based on the dropdown type.
+     *
+     * @public
+     * @remarks
+     * This method can be overridden in derived classes to provide custom control elements, though this is not recommended.
+     */
+    protected insertControl(): void;
+    /**
+     * Handles the keydown events for the dropdown.
+     *
+     * @param e - the keyboard event
+     * @public
+     */
+    keydownHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Prevents the default behavior of the mousedown event. This is necessary to prevent the input from losing focus
+     * when the dropdown is open.
+     *
+     * @param e - the mouse event
+     *
+     * @internal
+     */
+    mousedownHandler(e: MouseEvent): boolean | void;
+    /**
+     * Reports the validity of the element.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/reportValidity | `HTMLInputElement.reportValidity()`} method.
+     */
+    reportValidity(): boolean;
+    /**
+     * Selects an option by index.
+     *
+     * @param index - The index of the option to select.
+     * @public
+     */
+    selectOption(index?: number, shouldEmit?: boolean): void;
+    /**
+     * Sets the validity of the element.
+     *
+     * @param flags - Validity flags to set.
+     * @param message - Optional message to supply. If not provided, the element's `validationMessage` will be used.
+     * @param anchor - Optional anchor to use for the validation message.
+     *
+     * @internal
+     */
+    setValidity(flags?: Partial<ValidityState>, message?: string, anchor?: HTMLElement): void;
+    /**
+     * Updates the freeform option with the provided value.
+     *
+     * @param value - the value to update the freeform option with
+     * @internal
+     */
+    protected updateFreeformOption(value?: string): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Handles the connected event for the listbox.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    private listboxConnectedHandler;
+    /**
+     * When anchor positioning isn't supported, an intersection observer is used to flip the listbox when it hits the
+     * viewport bounds. One static observer is used for all dropdowns.
+     *
+     * @internal
+     */
+    private anchorPositionFallback;
+}

package/dist/dts/dropdown/dropdown.d.ts

@@ -0,0 +1,28 @@
+import { BaseDropdown } from './dropdown.base.js';
+import { DropdownAppearance, DropdownSize } from './dropdown.options.js';
+/**
+ * The Fluent Dropdown Element. Implements {@link @microsoft/fast-foundation#BaseDropdown}.
+ *
+ * @slot - The default slot. Accepts a {@link (Listbox:class)} element.
+ * @slot indicator - The indicator slot.
+ * @slot control - The control slot. This slot is automatically populated and should not be manually manipulated.
+ *
+ * @public
+ */
+export declare class Dropdown extends BaseDropdown {
+    /**
+     * The appearance of the dropdown.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `appearance`
+     */
+    appearance: DropdownAppearance;
+    /**
+     * The size of the dropdown.
+     * @public
+     * @remarks
+     * HTML Attribute: `size`
+     */
+    size?: DropdownSize;
+}

package/dist/dts/dropdown/dropdown.definition.d.ts

@@ -0,0 +1,9 @@
+import { Dropdown } from './dropdown.js';
+/**
+ * The Fluent Dropdown Element.
+ *
+ * @public
+ * @remarks
+ * HTML Element: `<fluent-dropdown>`
+ */
+export declare const definition: import("@microsoft/fast-element").FASTElementDefinition<typeof Dropdown>;

package/dist/dts/dropdown/dropdown.options.d.ts

@@ -0,0 +1,53 @@
+import type { StaticallyComposableHTML } from '../utils/template-helpers.js';
+import type { ValuesOf } from '../utils/typings.js';
+import type { BaseDropdown } from './dropdown.base.js';
+/**
+ * Predicate function that determines if the element should be considered a dropdown.
+ *
+ * @param element - The element to check.
+ * @param tagName - The tag name to check.
+ * @returns true if the element is a dropdown.
+ * @public
+ */
+export declare function isDropdown(element?: Node | null, tagName?: string): element is BaseDropdown;
+/**
+ * Values for the `appearance` attribute of the {@link (Dropdown:class)} component.
+ * @public
+ */
+export declare const DropdownAppearance: {
+    filledDarker: string;
+    filledLighter: string;
+    outline: string;
+    transparent: string;
+};
+/** @public */
+export type DropdownAppearance = ValuesOf<typeof DropdownAppearance>;
+/**
+ * Template options for the {@link (Dropdown:class)} component.
+ * @public
+ */
+export type DropdownOptions = {
+    indicator?: StaticallyComposableHTML<BaseDropdown>;
+};
+/**
+ * Values for the `size` attribute of the {@link (Dropdown:class)} component.
+ * @public
+ */
+export declare const DropdownSize: {
+    readonly small: "small";
+    readonly medium: "medium";
+    readonly large: "large";
+};
+/** @public */
+export type DropdownSize = ValuesOf<typeof DropdownSize>;
+/**
+ * Values  for the `type` attribute of the {@link (Dropdown:class)} component.
+ * @public
+ */
+export declare const DropdownType: {
+    readonly combobox: "combobox";
+    readonly dropdown: "dropdown";
+    readonly select: "select";
+};
+/** @public */
+export type DropdownType = ValuesOf<typeof DropdownType>;

package/dist/dts/dropdown/dropdown.styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Styles for the {@link (Dropdown:class)} component.
+ *
+ * @public
+ */
+export declare const styles: import("@microsoft/fast-element").ElementStyles;

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

@@ -0,0 +1,38 @@
+import { type ElementViewTemplate } from '@microsoft/fast-element';
+import type { BaseDropdown } from './dropdown.base.js';
+import type { DropdownOptions } from './dropdown.options.js';
+/**
+ * The template partial for the dropdown input element. This template is used when the `type` property is set to "combobox".
+ *
+ * @public
+ * @remarks
+ * Since the input element must be present in the light DOM for ARIA to function correctly, this template should not be
+ * overridden.
+ * @see {@link BaseDropdown.insertControl}
+ */
+export declare const dropdownInputTemplate: import("@microsoft/fast-element").ViewTemplate<BaseDropdown, any>;
+/**
+ * The template partial for the dropdown button element. This template is used when the `type` property is set to "dropdown".
+ *
+ * @public
+ * @remarks
+ * Since the button element must be present in the light DOM for ARIA to function correctly, this template should not be
+ * overridden.
+ * @see {@link BaseDropdown.insertControl}
+ */
+export declare const dropdownButtonTemplate: import("@microsoft/fast-element").ViewTemplate<BaseDropdown, any>;
+/**
+ * Generates a template for the {@link (Dropdown:class)} component.
+ *
+ * @param options - The {@link (DropdownOptions:interface)} to use for generating the template.
+ * @returns The template object.
+ *
+ * @public
+ */
+export declare function dropdownTemplate<T extends BaseDropdown>(options?: DropdownOptions): ElementViewTemplate<T>;
+/**
+ * Template for the Dropdown component.
+ *
+ * @public
+ */
+export declare const template: ElementViewTemplate<BaseDropdown>;

package/dist/dts/dropdown/index.d.ts

@@ -0,0 +1,6 @@
+export { definition as DropdownDefinition } from './dropdown.definition.js';
+export { BaseDropdown } from './dropdown.base.js';
+export { Dropdown } from './dropdown.js';
+export { DropdownAppearance, DropdownSize, DropdownType, isDropdown, type DropdownOptions, } from './dropdown.options.js';
+export { styles as DropdownStyles } from './dropdown.styles.js';
+export { dropdownButtonTemplate, dropdownInputTemplate, template as DropdownTemplate, dropdownTemplate, } from './dropdown.template.js';

package/dist/dts/field/define.d.ts

@@ -0,0 +1 @@
+export {};