@fluentui/web-components 3.0.0-beta.77 → 3.0.0-beta.78

package/CHANGELOG.md

@@ -1,12 +1,22 @@
 # Change Log - @fluentui/web-components
 
-This log was last generated on Fri, 17 Jan 2025 04:07:28 GMT and should not be manually modified.
+This log was last generated on Tue, 04 Feb 2025 04:07:07 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## [3.0.0-beta.78](https://github.com/microsoft/fluentui/tree/@fluentui/web-components_v3.0.0-beta.78)
+
+Tue, 04 Feb 2025 04:07:07 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/web-components_v3.0.0-beta.77..@fluentui/web-components_v3.0.0-beta.78)
+
+### Changes
+
+- add Dropdown, Listbox, and Option components ([PR #32116](https://github.com/microsoft/fluentui/pull/32116) by 863023+radium-v@users.noreply.github.com)
+- fix: dropdown opens then closes on space key ([PR #33767](https://github.com/microsoft/fluentui/pull/33767) by 863023+radium-v@users.noreply.github.com)
+
 ## [3.0.0-beta.77](https://github.com/microsoft/fluentui/tree/@fluentui/web-components_v3.0.0-beta.77)
 
-Fri, 17 Jan 2025 04:07:28 GMT 
+Fri, 17 Jan 2025 04:07:40 GMT 
 [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/web-components_v3.0.0-beta.76..@fluentui/web-components_v3.0.0-beta.77)
 
 ### Changes

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

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

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

@@ -0,0 +1,492 @@
+import { FASTElement } from '@microsoft/fast-element';
+import type { Listbox } from '../listbox/listbox.js';
+import type { DropdownOption } from '../option/option.js';
+import { DropdownAppearance, DropdownSize, 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 {
+    /**
+     * 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();
+    /**
+     * 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 current value of the selected option.
+     *
+     * @public
+     */
+    get value(): string | null;
+    set value(next: string | null);
+    /**
+     * Handles the change events for the dropdown.
+     *
+     * @param e - the event object
+     *
+     * @public
+     */
+    changeHandler(e: Event): boolean | void;
+    /**
+     * 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;
+    /**
+     * Selects an option by index.
+     *
+     * @param index - The index of the option to select.
+     * @public
+     */
+    selectOption(index?: number): 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;
+}
+/**
+ * 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 {
+    /**
+     * 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 appearance of the dropdown.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `appearance`
+     */
+    appearance: DropdownAppearance;
+    /**
+     * Swaps appearance states when the appearance property changes.
+     *
+     * @param prev - the previous appearance state
+     * @param next - the current appearance state
+     * @internal
+     */
+    appearanceChanged(prev: DropdownAppearance | undefined, next: DropdownAppearance | undefined): void;
+    /**
+     * The size of the dropdown.
+     * @public
+     * @remarks
+     * HTML Attribute: `size`
+     */
+    size?: DropdownSize;
+    /**
+     * Swaps size states when the size property changes.
+     *
+     * @param prev - the previous size state
+     * @param next - the current size state
+     * @internal
+     */
+    sizeChanged(prev: DropdownSize | undefined, next: DropdownSize | undefined): void;
+    connectedCallback(): void;
+    constructor();
+    disconnectedCallback(): void;
+    /**
+     * Handles the connected event for the listbox.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    private listboxConnectedHandler;
+    /**
+     * Adds or removes the window event listener based on the open state.
+     *
+     * @param prev - the previous open state
+     * @param next - the current open state
+     * @internal
+     */
+    openChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * 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.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.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.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,5 @@
+export { definition as DropdownDefinition } from './dropdown.definition.js';
+export { BaseDropdown, 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/index-rollup.d.ts

@@ -12,15 +12,18 @@ import './dialog-body/define.js';
 import './divider/define.js';
 import './drawer/define.js';
 import './drawer-body/define.js';
+import './dropdown/define.js';
 import './field/define.js';
 import './image/define.js';
 import './label/define.js';
 import './link/define.js';
+import './listbox/define.js';
 import './menu-button/define.js';
 import './menu-item/define.js';
 import './menu-list/define.js';
 import './menu/define.js';
 import './message-bar/define.js';
+import './option/define.js';
 import './progress-bar/define.js';
 import './radio-group/define.js';
 import './radio/define.js';

package/dist/dts/index.d.ts

@@ -15,6 +15,8 @@ export { DialogBody, DialogBodyDefinition, DialogBodyTemplate, DialogBodyStyles
 export { BaseDivider, Divider, DividerAlignContent, DividerAppearance, DividerDefinition, DividerOrientation, DividerRole, DividerStyles, DividerTemplate, } from './divider/index.js';
 export { Drawer, DrawerDefinition, DrawerPosition, DrawerSize, DrawerType, DrawerTemplate, DrawerStyles, } from './drawer/index.js';
 export { DrawerBody, DrawerBodyDefinition, DrawerBodyTemplate, DrawerBodyStyles } from './drawer-body/index.js';
+export { DropdownDefinition, BaseDropdown, Dropdown, DropdownAppearance, DropdownSize, DropdownType, isDropdown, type DropdownOptions, DropdownStyles, dropdownButtonTemplate, dropdownInputTemplate, DropdownTemplate, } from './dropdown/index.js';
+export { ListboxDefinition, Listbox, isListbox, ListboxStyles, ListboxTemplate, listboxTemplate, } from './listbox/index.js';
 export { BaseField, Field, FieldLabelPosition, ValidationFlags, FieldDefinition, FieldStyles, FieldTemplate, } from './field/index.js';
 export type { SlottableInput } from './field/index.js';
 export { FluentDesignSystem } from './fluent-design-system.js';
@@ -28,6 +30,7 @@ export { MenuItem, MenuItemDefinition, MenuItemRole, MenuItemStyles, MenuItemTem
 export type { MenuItemColumnCount, MenuItemOptions } from './menu-item/index.js';
 export { MenuList, MenuListDefinition, MenuListStyles, MenuListTemplate } from './menu-list/index.js';
 export { Menu, MenuDefinition, MenuStyles, MenuTemplate } from './menu/index.js';
+export { DropdownOption, DropdownOptionDefinition, DropdownOptionStyles, DropdownOptionTemplate, isDropdownOption, type DropdownOptionOptions, } from './option/index.js';
 export { StartEnd, endSlotTemplate, startSlotTemplate } from './patterns/start-end.js';
 export type { StartOptions, EndOptions, StartEndOptions } from './patterns/start-end.js';
 export { BaseProgressBar, ProgressBar, ProgressBarDefinition, ProgressBarShape, ProgressBarStyles, ProgressBarTemplate, ProgressBarThickness, ProgressBarValidationState, } from './progress-bar/index.js';

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

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

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

@@ -0,0 +1,5 @@
+export { definition as ListboxDefinition } from './listbox.definition.js';
+export { Listbox } from './listbox.js';
+export { isListbox } from './listbox.options.js';
+export { styles as ListboxStyles } from './listbox.styles.js';
+export { template as ListboxTemplate, listboxTemplate } from './listbox.template.js';