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

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

@@ -0,0 +1,116 @@
+import { FASTElement } from '@microsoft/fast-element';
+import type { BaseDropdown } from '../dropdown/dropdown.js';
+import type { DropdownOption } from '../option/option.js';
+/**
+ * A Listbox Custom HTML Element.
+ * Implements the {@link https://w3c.github.io/aria/#listbox | ARIA listbox } role.
+ *
+ * @slot - The default slot for the options.
+ * @emits connected - Dispatched when the element is connected to the DOM.
+ *
+ * @remarks
+ * The listbox component represents a list of options that can be selected.
+ * It is intended to be used in conjunction with the {@link BaseDropdown | Dropdown} component.
+ *
+ * @public
+ */
+export declare class Listbox extends FASTElement {
+    /**
+     * Sets the listbox ID to a unique value if one is not provided.
+     *
+     * @override
+     * @public
+     * @remarks
+     * HTML Attribute: `id`
+     */
+    id: string;
+    /**
+     * Indicates whether the listbox allows multiple selection.
+     *
+     * @public
+     */
+    multiple?: boolean;
+    /**
+     * Updates the multiple selection state of the listbox and its options.
+     *
+     * @param prev - the previous multiple value
+     * @param next - the current multiple value
+     */
+    multipleChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The collection of all child options.
+     *
+     * @public
+     */
+    options: DropdownOption[];
+    /**
+     * Updates the enabled options collection when properties on the child options change.
+     *
+     * @param prev - the previous options
+     * @param next - the current options
+     *
+     * @internal
+     */
+    optionsChanged(prev: DropdownOption[] | undefined, next: DropdownOption[] | undefined): void;
+    /**
+     * The index of the first selected and enabled option.
+     * @internal
+     */
+    selectedIndex: number;
+    /**
+     * Reference to the parent dropdown element.
+     * @internal
+     */
+    dropdown?: BaseDropdown;
+    /**
+     * Handles the `beforetoggle` event on the listbox.
+     *
+     * @param e - the toggle event
+     * @returns true to allow the default popover behavior, undefined to prevent it
+     * @internal
+     */
+    beforetoggleHandler(e: ToggleEvent): boolean | undefined;
+    /**
+     * The internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    elementInternals: ElementInternals;
+    /**
+     * The collection of child options that are not disabled.
+     *
+     * @internal
+     */
+    get enabledOptions(): DropdownOption[];
+    /**
+     * The collection of child options that are selected.
+     *
+     * @public
+     */
+    get selectedOptions(): DropdownOption[];
+    /**
+     * Sets the `selected` state on a target option when clicked.
+     *
+     * @param e - The pointer event
+     * @public
+     */
+    clickHandler(e: PointerEvent): boolean | void;
+    constructor();
+    connectedCallback(): void;
+    /**
+     * Handles observable subscriptions for the listbox.
+     *
+     * @param source - The source of the observed change
+     * @param propertyName - The name of the property that changed
+     *
+     * @internal
+     */
+    handleChange(source: any, propertyName?: string): void;
+    /**
+     * Selects an option by index.
+     *
+     * @param index - The index of the option to select.
+     * @public
+     */
+    selectOption(index?: number): void;
+}

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

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

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

@@ -0,0 +1,10 @@
+import type { Listbox } from './listbox.js';
+/**
+ * Predicate function that determines if the element should be considered a listbox.
+ *
+ * @param element - The element to check.
+ * @param tagName - The tag name to check.
+ * @returns true if the element is a listbox.
+ * @public
+ */
+export declare function isListbox(element?: Node | null, tagName?: string): element is Listbox;

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

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

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

@@ -0,0 +1,17 @@
+import { ElementViewTemplate } from '@microsoft/fast-element';
+import type { Listbox } from './listbox.js';
+/**
+ * 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 listboxTemplate<T extends Listbox>(): ElementViewTemplate<T>;
+/**
+ * Template for the Listbox component.
+ *
+ * @public
+ */
+export declare const template: ElementViewTemplate<Listbox>;

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

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

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

@@ -0,0 +1,5 @@
+export { definition as DropdownOptionDefinition } from './option.definition.js';
+export { DropdownOption } from './option.js';
+export { isDropdownOption, type DropdownOptionOptions } from './option.options.js';
+export { styles as DropdownOptionStyles } from './option.styles.js';
+export { template as DropdownOptionTemplate } from './option.template.js';

package/dist/dts/option/option.d.ts

@@ -0,0 +1,260 @@
+import { FASTElement } from '@microsoft/fast-element';
+import type { Start } from '../patterns/start-end.js';
+/**
+ * A DropdownOption Custom HTML Element.
+ * Implements the {@link https://w3c.github.io/aria/#option | ARIA option } role.
+ *
+ * @slot - The default slot for the option's content.
+ * @slot checked-indicator - The checked indicator.
+ * @slot description - Optional description content.
+ *
+ * @remarks
+ * To support single and multiple selection modes with the {@link (BaseDropdown:class)} element, the Option element
+ * itself handles form association and value submission, rather than its parent Dropdown element. In this way, the
+ * Option element is a variation of the Checkbox element that is specifically designed for use in the Dropdown element.
+ *
+ * This class is named `DropdownOption` to avoid conflicts with the native `Option` global. Related constructs are also
+ * titled with `DropdownOption` to maintain consistency.
+ *
+ * @public
+ */
+export declare class DropdownOption extends FASTElement implements Start {
+    /**
+     * Indicates that the option is active.
+     *
+     * @public
+     */
+    active: boolean;
+    /**
+     * Changes the active state of the option when the active property changes.
+     *
+     * @param prev - the previous active state
+     * @param next - the current active state
+     * @internal
+     */
+    protected activeChanged(prev: boolean, next: boolean): void;
+    /**
+     * The current selected state of the option.
+     *
+     * @internal
+     */
+    currentSelected?: boolean;
+    /**
+     * Sets the selected property to match the currentSelected state.
+     *
+     * @param prev - the previous selected state
+     * @param next - the current selected state
+     * @internal
+     */
+    currentSelectedChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The initial selected state of the option.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `checked`
+     */
+    defaultSelected?: boolean;
+    /**
+     * Updates the selected state when the `selected` attribute is changed, unless the selected state has been changed by the user.
+     *
+     * @param prev - The previous initial selected state
+     * @param next - The current initial selected state
+     * @internal
+     */
+    protected defaultSelectedChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The collection of slotted description elements.
+     *
+     * @internal
+     */
+    descriptionSlot: Node[];
+    /**
+     * Changes the description state of the option when the description slot changes.
+     *
+     * @param prev - the previous collection of description elements
+     * @param next - the current collection of description elements
+     * @internal
+     */
+    descriptionSlotChanged(prev: Node[] | undefined, next: Node[] | undefined): void;
+    /**
+     * The current disabled state of the option.
+     *
+     * @public
+     */
+    disabled?: boolean;
+    /**
+     * Toggles the disabled state when the user changes the `disabled` property.
+     *
+     * @internal
+     */
+    protected disabledChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The initial disabled state of the option.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `disabled`
+     */
+    disabledAttribute?: boolean;
+    /**
+     * Sets the disabled state when the `disabled` attribute changes.
+     *
+     * @param prev - the previous value
+     * @param next - the current value
+     * @internal
+     */
+    protected disabledAttributeChanged(prev: boolean | undefined, next: boolean | undefined): void;
+    /**
+     * The id of a form to associate the element to.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Element/input#form | `form`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `form`
+     */
+    formAttribute?: string;
+    /**
+     * Indicates that the option value should sync with the value of the dropdown's control.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `freeform`
+     */
+    freeform?: boolean;
+    /**
+     * The id of the option. If not provided, a unique id will be assigned.
+     *
+     * @override
+     * @public
+     * @remarks
+     * HTML Attribute: `id`
+     */
+    id: string;
+    /**
+     * The initial value of the option.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `value`
+     */
+    initialValue: string;
+    /**
+     * Sets the value of the option when the `value` attribute changes.
+     *
+     * @param prev - The previous initial value
+     * @param next - The current initial value
+     * @internal
+     */
+    protected initialValueChanged(prev: string, next: string): void;
+    /**
+     * Indicates that the option is in a multiple selection mode context.
+     * @public
+     */
+    multiple: boolean;
+    /**
+     * Updates the multiple state of the option when the multiple property changes.
+     *
+     * @param prev - the previous multiple state
+     * @param next - the current multiple state
+     */
+    multipleChanged(prev: boolean, next: boolean): void;
+    /**
+     * The name of the option. This option's value will be surfaced during form submission under the provided name.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `name`
+     */
+    name: string;
+    /**
+     * Reference to the start slot element.
+     *
+     * @internal
+     */
+    start: HTMLSlotElement;
+    /**
+     * The text to display in the dropdown control when the option is selected.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `text`
+     */
+    textAttribute?: string;
+    /**
+     * The internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    elementInternals: ElementInternals;
+    /**
+     * The associated `<form>` element.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/form | `ElementInternals.form`} property.
+     */
+    get form(): HTMLFormElement | null;
+    /**
+     * The collection of slotted `output` elements, used to display the value when the option is freeform.
+     *
+     * @internal
+     */
+    freeformOutputs?: HTMLOutputElement[];
+    /**
+     * 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;
+    /**
+     * A reference to all associated `<label>` elements.
+     *
+     * @public
+     */
+    get labels(): ReadonlyArray<HTMLLabelElement>;
+    /**
+     * The option's current selected state.
+     *
+     * @public
+     */
+    get selected(): boolean;
+    set selected(next: boolean);
+    /**
+     * The display text of the option.
+     *
+     * @public
+     * @remarks
+     * When the option is freeform, the text is the value of the option.
+     */
+    get text(): string;
+    /**
+     * The internal value of the option.
+     *
+     * @internal
+     */
+    private _value;
+    /**
+     * The current value of the option.
+     *
+     * @public
+     */
+    get value(): string;
+    set value(value: string);
+    connectedCallback(): void;
+    constructor();
+    /**
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/setFormValue | `ElementInternals.setFormValue()`} method.
+     *
+     * @internal
+     */
+    setFormValue(value: File | string | FormData | null, state?: File | string | FormData | null): void;
+    /**
+     * Toggles the selected state of the control.
+     *
+     * @param force - Forces the element to be checked or unchecked
+     * @public
+     */
+    toggleSelected(force?: boolean): void;
+}

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

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

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

@@ -0,0 +1,20 @@
+import type { StartOptions } from '../patterns/start-end.js';
+import type { StaticallyComposableHTML } from '../utils/template-helpers.js';
+import type { DropdownOption } from './option.js';
+/**
+ * Predicate function that determines if the element should be considered an option.
+ *
+ * @param element - The element to check.
+ * @param tagName - The tag name to check.
+ * @returns true if the element is an option.
+ * @public
+ */
+export declare function isDropdownOption(value: Node | null, tagName?: string): value is DropdownOption;
+/**
+ * The options for the {@link DropdownOption} component.
+ *
+ * @public
+ */
+export type DropdownOptionOptions = StartOptions<DropdownOption> & {
+    checkedIndicator?: StaticallyComposableHTML<DropdownOption>;
+};

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

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

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

@@ -0,0 +1,16 @@
+import type { ElementViewTemplate } from '@microsoft/fast-element';
+import type { DropdownOption } from './option.js';
+import type { DropdownOptionOptions } from './option.options.js';
+/**
+ * Generates a template for the {@link (Option:class)} component.
+ *
+ * @param options - The {@link (OptionOptions:interface)} to use for generating the template.
+ * @returns The template object.
+ * @public
+ */
+export declare function dropdownOptionTemplate<T extends DropdownOption>(options?: DropdownOptionOptions): ElementViewTemplate<T>;
+/**
+ * Template for the Option component.
+ * @public
+ */
+export declare const template: ElementViewTemplate<DropdownOption>;

package/dist/dts/patterns/start-end.d.ts

@@ -19,12 +19,26 @@ export type EndOptions<TSource = any, TParent = any> = {
  * @public
  */
 export type StartEndOptions<TSource = any, TParent = any> = StartOptions<TSource, TParent> & EndOptions<TSource, TParent>;
+/**
+ * A mixin class implementing start slots.
+ * @public
+ */
+export declare class Start {
+    start: HTMLSlotElement;
+}
+/**
+ * A mixin class implementing end slots.
+ * @public
+ */
+export declare class End {
+    end: HTMLSlotElement;
+}
 /**
  * A mixin class implementing start and end slots.
  * These are generally used to decorate text elements with icons or other visual indicators.
  * @public
  */
-export declare class StartEnd {
+export declare class StartEnd implements Start, End {
     start: HTMLSlotElement;
     end: HTMLSlotElement;
 }
@@ -41,4 +55,4 @@ export declare function endSlotTemplate<TSource extends StartEnd = StartEnd, TPa
  *
  * @public
  */
-export declare function startSlotTemplate<TSource extends StartEnd = StartEnd, TParent = any>(options: StartOptions<TSource, TParent>): CaptureType<TSource, TParent>;
+export declare function startSlotTemplate<TSource extends Pick<StartEnd, 'start'> = StartEnd, TParent = any>(options: StartOptions<TSource, TParent>): CaptureType<TSource, TParent>;

package/dist/dts/styles/states/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Selector for the `active` state.
+ * @public
+ */
+export declare const activeState: ":state(active)" | "[state--active]";
 /**
  * Selector for the `align-end` state.
  * @public
@@ -108,6 +113,10 @@ export declare const darkGreenState: ":state(dark-green)" | "[state--dark-green]
  * @public
  */
 export declare const darkRedState: ":state(dark-red)" | "[state--dark-red]";
+/**
+ * Selector for the `description` state.
+ */
+export declare const descriptionState: ":state(description)" | "[state--description]";
 /**
  * Selector for the `disabled` state.
  * @public
@@ -178,6 +187,11 @@ export declare const fitCoverState: ":state(fit-cover)" | "[state--fit-cover]";
  * @public
  */
 export declare const fitNoneState: ":state(fit-none)" | "[state--fit-none]";
+/**
+ * Selector for the `flip-block` state.
+ * @public
+ */
+export declare const flipBlockState: ":state(flip-block)" | "[state--flip-block]";
 /**
  * Selector for the `focus-visible` state.
  * @public
@@ -308,6 +322,11 @@ export declare const monospaceState: ":state(monospace)" | "[state--monospace]";
  * @public
  */
 export declare const multiLineState: ":state(multiline)" | "[state--multiline]";
+/**
+ * Selector for the `multiselect` state.
+ * @public
+ */
+export declare const multipleState: ":state(multiple)" | "[state--multiple]";
 /**
  * Selector for the `navy` state.
  * @public
@@ -328,6 +347,11 @@ export declare const nowrapState: ":state(nowrap)" | "[state--nowrap]";
  * @public
  */
 export declare const numericState: ":state(numeric)" | "[state--numeric]";
+/**
+ * Selector for the `open` state.
+ * @public
+ */
+export declare const openState: ":state(open)" | "[state--open]";
 /**
  * Selector for the `outline` state.
  * @public
@@ -348,6 +372,11 @@ export declare const peachState: ":state(peach)" | "[state--peach]";
  * @public
  */
 export declare const pinkState: ":state(pink)" | "[state--pink]";
+/**
+ * Selector for the `placeholder-shown` state.
+ * @public
+ */
+export declare const placeholderShownState: ":state(placeholder-shown)" | "[state--placeholder-shown]";
 /**
  * Selector for the `platinum` state.
  * @public
@@ -423,6 +452,11 @@ export declare const royalBlueState: ":state(royal-blue)" | "[state--royal-blue]
  * @public
  */
 export declare const seafoamState: ":state(seafoam)" | "[state--seafoam]";
+/**
+ * Selector for the `selected` state.
+ * @public
+ */
+export declare const selectedState: ":state(selected)" | "[state--selected]";
 /**
  * Selector for the `semibold` state.
  * @public

package/dist/dts/utils/element-internals.d.ts

@@ -1,13 +1,10 @@
+import { CustomStatesSetSupported } from './support.js';
 /**
  * Inference type for a CSS custom state selector.
  * @public
  */
 export type StateSelector<S> = S extends string ? `:state(${S})` | `[state--${S}]` : never;
-/**
- * Check if the browser supports Custom States.
- * @public
- */
-export declare const CustomStatesSetSupported: boolean;
+export { CustomStatesSetSupported };
 /**
  * Returns a string that represents a CSS custom state selector.
  *
@@ -32,7 +29,7 @@ export declare function stateSelector<S extends string>(state: S): StateSelector
  * @param force - force the state to be toggled on or off
  * @internal
  */
-export declare function toggleState(elementInternals: ElementInternals, state: string | undefined, force?: boolean): void;
+export declare function toggleState(elementInternals: ElementInternals | undefined, state: string | undefined, force?: boolean): void;
 /**
  * Check if a given attribute value is a valid state. Attribute values are often kebab-cased, so this function converts
  * the kebab-cased `state` to camelCase and checks if it exists in as a key in the `States` object.

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

@@ -5,3 +5,4 @@ export * from './template-helpers.js';
 export * from './whitespace-filter.js';
 export * from './display.js';
 export * from './behaviors/match-media-stylesheet-behavior.js';
+export * from './support.js';

package/dist/dts/utils/language.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Determines the current language code of an element.
+ *
+ * @param rootNode - the HTMLElement to begin the query from, usually "this" when used in a component controller
+ * @returns the language code of the element
+ *
+ * @public
+ */
+export declare function getLanguage(rootNode: HTMLElement): Intl.BCP47LanguageTag;

package/dist/dts/utils/support.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Check if the browser supports CSS Anchor Positioning.
+ * @public
+ */
+export declare const AnchorPositioningCSSSupported: boolean;
+/**
+ * Check if the browser supports HTML Anchor Positioning.
+ * @public
+ */
+export declare const AnchorPositioningHTMLSupported: boolean;
+/**
+ * Check if the browser supports Custom States.
+ * @public
+ */
+export declare const CustomStatesSetSupported: boolean;

package/dist/dts/utils/unique-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates a unique element id.
+ *
+ * @param prefix - The prefix to use for the unique id.
+ * @returns A unique id.
+ *
+ * @public
+ */
+export declare function uniqueId(prefix?: string): string;