@fluentui/web-components 3.0.0-beta.1 → 3.0.0-beta.11

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

@@ -1,15 +1,39 @@
-import { DividerOrientation, DividerRole } from '@microsoft/fast-foundation/divider.js';
-import type { ValuesOf } from '@microsoft/fast-foundation/utilities.js';
+import type { ValuesOf } from '../utils/index.js';
 /**
- * Fast Foundation DividerRole property
+ * Divider roles
  * @public
  */
-export { DividerRole };
+export declare const DividerRole: {
+    /**
+     * The divider semantically separates content
+     */
+    readonly separator: "separator";
+    /**
+     * The divider has no semantic value and is for visual presentation only.
+     */
+    readonly presentation: "presentation";
+};
+/**
+ * The types for Divider roles
+ * @public
+ */
+export declare type DividerRole = ValuesOf<typeof DividerRole>;
+/**
+ * Divider orientation
+ * @public
+ */
+export declare const DividerOrientation: {
+    readonly horizontal: "horizontal"; /**
+     * Divider roles
+     * @public
+     */
+    readonly vertical: "vertical";
+};
 /**
- * Fast Foundation Orientation property
+ * The types for Divider orientation
  * @public
  */
-export { DividerOrientation };
+export declare type DividerOrientation = ValuesOf<typeof DividerOrientation>;
 /**
  * Align content within divider
  * @public

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

@@ -1,5 +1,6 @@
 import { ElementViewTemplate } from '@microsoft/fast-element';
 import type { Divider } from './divider.js';
+export declare function dividerTemplate<T extends Divider>(): ElementViewTemplate<T>;
 /**
  * Template for the Divider component
  * @public

package/dist/dts/form-associated/form-associated.d.ts

@@ -0,0 +1,178 @@
+import type { Constructable, FASTElement } from '@microsoft/fast-element';
+/**
+ * This file enables typing support for ElementInternals APIs.
+ * It is largely taken from https://github.com/microsoft/TSJS-lib-generator/pull/818/files.
+ *
+ * When TypeScript adds support for these APIs we can delete this file.
+ */
+interface ValidityStateFlags {
+    badInput?: boolean;
+    customError?: boolean;
+    patternMismatch?: boolean;
+    rangeOverflow?: boolean;
+    rangeUnderflow?: boolean;
+    stepMismatch?: boolean;
+    tooLong?: boolean;
+    tooShort?: boolean;
+    typeMismatch?: boolean;
+    valueMissing?: boolean;
+}
+/**
+ * Source:
+ * https://html.spec.whatwg.org/multipage/custom-elements.html#elementinternals
+ */
+interface ElementInternals {
+    /**
+     * Returns the form owner of internals target element.
+     */
+    readonly form: HTMLFormElement | null;
+    /**
+     * Returns a NodeList of all the label elements that internals target element is associated with.
+     */
+    readonly labels: NodeList;
+    /**
+     * Returns the error message that would be shown to the user if internals target element was to be checked for validity.
+     */
+    readonly validationMessage: string;
+    /**
+     * Returns the ValidityState object for internals target element.
+     */
+    readonly validity: ValidityState;
+    /**
+     * Returns true if internals target element will be validated when the form is submitted; false otherwise.
+     */
+    readonly willValidate: boolean;
+    /**
+     * Returns true if internals target element has no validity problems; false otherwise. Fires an invalid event at the element in the latter case.
+     */
+    checkValidity(): boolean;
+    /**
+     * Returns true if internals target element has no validity problems; otherwise,
+     * returns false, fires an invalid event at the element, and (if the event isn't canceled) reports the problem to the user.
+     */
+    reportValidity(): boolean;
+    /**
+     * Sets both the state and submission value of internals target element to value.
+     *
+     * While "null" isn't enumerated as a argument type (here)[https://html.spec.whatwg.org/multipage/custom-elements.html#the-elementinternals-interface],
+     * In practice it appears to remove the value from the form data on submission. Adding it as a valid type here
+     * becuase that capability is required for checkbox and radio types
+     */
+    setFormValue(value: File | string | FormData | null, state?: File | string | FormData | null): void;
+    /**
+     * Marks internals target element as suffering from the constraints indicated by the flags argument,
+     * and sets the element's validation message to message.
+     * If anchor is specified, the user agent might use
+     * it to indicate problems with the constraints of internals target
+     * element when the form owner is validated interactively or reportValidity() is called.
+     */
+    setValidity(flags: ValidityStateFlags, message?: string, anchor?: HTMLElement): void;
+}
+declare let ElementInternals: {
+    prototype: ElementInternals;
+    new (): ElementInternals;
+};
+/**
+ * @alpha
+ */
+export declare const supportsElementInternals: boolean;
+/**
+ * Base class for providing Custom Element Form Association.
+ *
+ * @beta
+ */
+export interface FormAssociated extends Omit<ElementInternals, 'labels'> {
+    dirtyValue: boolean;
+    disabled: boolean;
+    readonly elementInternals: ElementInternals | null;
+    readonly formAssociated: boolean;
+    initialValue: string;
+    readonly labels: ReadonlyArray<Node[]>;
+    name: string;
+    required: boolean;
+    value: string;
+    currentValue: string;
+    attachProxy(): void;
+    detachProxy(): void;
+    disabledChanged?(previous: boolean, next: boolean): void;
+    formDisabledCallback?(disabled: boolean): void;
+    formResetCallback(): void;
+    initialValueChanged?(previous: string, next: string): void;
+    nameChanged?(previous: string, next: string): void;
+    requiredChanged(prev: boolean, next: boolean): void;
+    stopPropagation(e: Event): void;
+    /**
+     * Sets the validity of the custom element. By default this uses the proxy element to determine
+     * validity, but this can be extended or replaced in implementation.
+     *
+     * @param anchor - The anchor element to provide to ElementInternals.setValidity for surfacing the browser's constraint validation UI
+     */
+    validate(anchor?: HTMLElement): void;
+    valueChanged(previous: string, next: string): void;
+}
+/**
+ * Base class for providing Custom Element Form Association with checkable features.
+ *
+ * @beta
+ */
+export interface CheckableFormAssociated extends FormAssociated {
+    currentChecked: boolean;
+    dirtyChecked: boolean;
+    checkedAttribute: boolean;
+    defaultChecked: boolean;
+    defaultCheckedChanged(oldValue: boolean | undefined, newValue: boolean): void;
+    checked: boolean;
+    checkedChanged(oldValue: boolean | undefined, newValue: boolean): void;
+}
+/**
+ * Avaiable types for the `proxy` property.
+ * @beta
+ */
+export declare type ProxyElement = HTMLSelectElement | HTMLTextAreaElement | HTMLInputElement;
+/**
+ * Identifies a class as having a proxy element and optional submethods related
+ * to the proxy element.
+ *
+ * @beta
+ */
+export interface FormAssociatedProxy {
+    proxy: ProxyElement;
+    disabledChanged?(previous: boolean, next: boolean): void;
+    formDisabledCallback?(disabled: boolean): void;
+    formResetCallback?(): void;
+    initialValueChanged?(previous: string, next: string): void;
+    valueChanged?(previous: string, next: string): void;
+    nameChanged?(previous: string, next: string): void;
+}
+/**
+ * Combined type to describe a Form-associated element.
+ *
+ * @beta
+ */
+export declare type FormAssociatedElement = FormAssociated & FASTElement & HTMLElement & FormAssociatedProxy;
+/**
+ * Combined type to describe a checkable Form-associated element.
+ *
+ * @beta
+ */
+export declare type CheckableFormAssociatedElement = FormAssociatedElement & CheckableFormAssociated & {
+    proxy: HTMLInputElement;
+};
+/**
+ * Combined type to describe a Constructable Form-Associated type.
+ *
+ * @beta
+ */
+export declare type ConstructableFormAssociated = Constructable<HTMLElement & FASTElement>;
+/**
+ * Base function for providing Custom Element Form Association.
+ *
+ * @beta
+ */
+export declare function FormAssociated<T extends ConstructableFormAssociated>(BaseCtor: T): T;
+/**
+ * Creates a checkable form associated component.
+ * @beta
+ */
+export declare function CheckableFormAssociated<T extends ConstructableFormAssociated>(BaseCtor: T): T;
+export {};

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

@@ -1,4 +1,4 @@
-import type { ValuesOf } from '@microsoft/fast-foundation/utilities.js';
+import type { ValuesOf } from '../utils/index.js';
 /**
  * Image fit
  * @public

package/dist/dts/index.d.ts

@@ -7,9 +7,11 @@ export * from './button/index.js';
 export * from './checkbox/index.js';
 export * from './compound-button/index.js';
 export * from './counter-badge/index.js';
+export * from './dialog/index.js';
 export * from './divider/index.js';
 export * from './image/index.js';
 export * from './label/index.js';
+export * from './menu/index.js';
 export * from './menu-button/index.js';
 export * from './menu-item/index.js';
 export * from './menu-list/index.js';
@@ -27,3 +29,6 @@ export * from './text-input/index.js';
 export * from './toggle-button/index.js';
 export * from './fluent-design-system.js';
 export * from './theme/index.js';
+export * from './utils/direction.js';
+export * from './utils/display.js';
+export * from './utils/behaviors/match-media-stylesheet-behavior.js';

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

@@ -1,4 +1,4 @@
-import type { ValuesOf } from '@microsoft/fast-foundation/utilities.js';
+import type { ValuesOf } from '../utils/index.js';
 /**
  * A Labels font size can be small, medium, or large
  */

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

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

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

@@ -0,0 +1,4 @@
+export * from './menu.js';
+export { template as MenuTemplate } from './menu.template.js';
+export { styles as MenuStyles } from './menu.styles.js';
+export { definition as MenuDefinition } from './menu.definition.js';

package/dist/dts/menu/menu.d.ts

@@ -0,0 +1,194 @@
+import { FASTElement } from '@microsoft/fast-element';
+import { MenuList } from '../menu-list/menu-list.js';
+/**
+ * The Menu class represents a menu component.
+ * @public
+ */
+export declare class Menu extends FASTElement {
+    /**
+     * Determines if the menu should open on hover.
+     * @public
+     */
+    openOnHover?: boolean;
+    /**
+     * Determines if the menu should open on right click.
+     * @public
+     */
+    openOnContext?: boolean;
+    /**
+     * Determines if the menu should close on scroll.
+     * @public
+     */
+    closeOnScroll?: boolean;
+    /**
+     * Determines if the menu open state should persis on click of menu item
+     * @public
+     */
+    persistOnItemClick?: boolean;
+    /**
+     * Defines whether the menu is open or not.
+     * @public
+     */
+    open: boolean;
+    /**
+     * Holds the slotted menu list.
+     * @public
+     */
+    slottedMenuList: MenuList[];
+    /**
+     * Holds the slotted triggers.
+     * @public
+     */
+    slottedTriggers: HTMLElement[];
+    /**
+     * The positioning container of the menu.
+     * @internal
+     */
+    positioningContainer?: HTMLElement;
+    /**
+     * The trigger element of the menu.
+     * @private
+     */
+    private _trigger?;
+    /**
+     * The menu list element of the menu.
+     * @private
+     */
+    private _menuList?;
+    /**
+     * Holds a reference to a function that is used to cleanup resources.
+     * @public
+     */
+    cleanup?: () => void;
+    /**
+     * Called when the element is connected to the DOM.
+     * Sets up the component.
+     * @public
+     */
+    connectedCallback(): void;
+    /**
+     * Called when the element is disconnected from the DOM.
+     * Removes event listeners.
+     * @public
+     */
+    disconnectedCallback(): void;
+    /**
+     * Sets the component.
+     * Sets the trigger and menu list elements and adds event listeners.
+     * @public
+     */
+    setComponent(): void;
+    /**
+     * Toggles the open state of the menu.
+     * @public
+     */
+    toggleMenu: () => void;
+    /**
+     * Closes the menu.
+     * @public
+     */
+    closeMenu: () => void;
+    /**
+     * Opens the menu.
+     * @public
+     */
+    openMenu: (e?: Event) => void;
+    /**
+     * Focuses on the menu list.
+     * @public
+     */
+    focusMenuList(): void;
+    /**
+     * Focuses on the menu trigger.
+     * @public
+     */
+    focusTrigger(): void;
+    /**
+     * Called whenever the open state changes.
+     * Updates the 'aria-expanded' attribute and sets the positioning of the menu.
+     * Sets menu list position
+     * emits openChanged event
+     * @public
+     * @param {boolean} oldValue - The previous value of 'open'.
+     * @param {boolean} newValue - The new value of 'open'.
+     */
+    openChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * Called whenever the 'openOnHover' property changes.
+     * Adds or removes a 'mouseover' event listener to the trigger based on the new value.
+     * @public
+     * @param {boolean} oldValue - The previous value of 'openOnHover'.
+     * @param {boolean} newValue - The new value of 'openOnHover'.
+     */
+    openOnHoverChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * Called whenever the 'persistOnItemClick' property changes.
+     * Adds or removes a 'click' event listener to the menu list based on the new value.
+     * @public
+     * @param {boolean} oldValue - The previous value of 'persistOnItemClick'.
+     * @param {boolean} newValue - The new value of 'persistOnItemClick'.
+     */
+    persistOnItemClickChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * Called whenever the 'openOnContext' property changes.
+     * Adds or removes a 'contextmenu' event listener to the trigger based on the new value.
+     * @public
+     * @param {boolean} oldValue - The previous value of 'openOnContext'.
+     * @param {boolean} newValue - The new value of 'openOnContext'.
+     */
+    openOnContextChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * Called whenever the 'closeOnScroll' property changes.
+     * Adds or removes a 'closeOnScroll' event listener to the trigger based on the new value.
+     * @public
+     * @param {boolean} oldValue - The previous value of 'closeOnScroll'.
+     * @param {boolean} newValue - The new value of 'closeOnScroll'.
+     */
+    closeOnScrollChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * The task to set the positioning of the menu.
+     * @protected
+     */
+    protected setPositioningTask: () => void;
+    /**
+     * Sets the positioning of the menu.
+     * @protected
+     */
+    protected setPositioning(): void;
+    /**
+     * Adds event listeners.
+     * Adds click and keydown event listeners to the trigger and a click event listener to the document.
+     * If 'openOnHover' is true, adds a 'mouseover' event listener to the trigger.
+     * @public
+     */
+    private addListeners;
+    /**
+     * Removes event listeners.
+     * Removes click and keydown event listeners from the trigger and a click event listener from the document.
+     * Also removes 'mouseover' event listeners from the trigger.
+     * @private
+     */
+    private removeListeners;
+    /**
+     * Handles keyboard interaction for the menu.
+     * Closes the menu and focuses on the trigger when the Escape key is pressed.
+     * Closes the menu when the Tab key is pressed.
+     * @public
+     * @param {KeyboardEvent} e - the keyboard event
+     */
+    handleMenuKeydown(e: KeyboardEvent): boolean | void;
+    /**
+     * Handles keyboard interaction for the trigger.
+     * Toggles the menu when the Space or Enter key is pressed.
+     * If the menu is open, focuses on the menu list.
+     * @public
+     * @param {KeyboardEvent} e - the keyboard event
+     */
+    handleTriggerKeydown: (e: KeyboardEvent) => boolean | void;
+    /**
+     * Handles document click events to close the menu when a click occurs outside of the menu or the trigger.
+     * @private
+     * @param {Event} e - The event triggered on document click.
+     */
+    private handleDocumentClick;
+}

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

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

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

@@ -0,0 +1,4 @@
+/** Menu styles
+ * @public
+ */
+export declare const styles: import("@microsoft/fast-element").ElementStyles;

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

@@ -0,0 +1,4 @@
+import { ElementViewTemplate } from '@microsoft/fast-element';
+import type { Menu } from './menu.js';
+export declare function menuTemplate<T extends Menu>(): ElementViewTemplate<T>;
+export declare const template: ElementViewTemplate<Menu>;

package/dist/dts/menu-button/menu-button.definition.d.ts

@@ -1,8 +1,5 @@
 import { MenuButton } from './menu-button.js';
 /**
- * The Fluent Menu Button Element. Implements {@link @microsoft/fast-foundation#Button },
- * {@link @microsoft/fast-foundation#buttonTemplate}
- *
  * @public
  * @remarks
  * HTML Element: \<fluent-button\>

package/dist/dts/menu-button/menu-button.options.d.ts

@@ -1,5 +1,5 @@
-import type { ButtonOptions } from '@microsoft/fast-foundation/button.js';
-import type { ValuesOf } from '@microsoft/fast-foundation/utilities.js';
+import type { ButtonOptions } from '../button/index.js';
+import type { ValuesOf } from '../utils/index.js';
 /**
  * Menu Button Appearance constants
  * @public

package/dist/dts/menu-item/menu-item.d.ts

@@ -1,9 +1,166 @@
-import { FASTMenuItem, MenuItemRole } from '@microsoft/fast-foundation/menu-item.js';
+import { FASTElement } from '@microsoft/fast-element';
+import type { StaticallyComposableHTML } from '../utils/template-helpers.js';
+import type { StartEndOptions } from '../patterns/start-end.js';
+import { StartEnd } from '../patterns/start-end.js';
+import { MenuItemRole, roleForMenuItem } from './menu-item.options.js';
 export declare type MenuItemColumnCount = 0 | 1 | 2;
-export { MenuItemRole };
+export { MenuItemRole, roleForMenuItem };
 /**
- * The base class used for constructing a fluent-menu-item custom element
+ * Menu Item configuration options
  * @public
  */
-export declare class MenuItem extends FASTMenuItem {
+export declare type MenuItemOptions = StartEndOptions<MenuItem> & {
+    checkboxIndicator?: StaticallyComposableHTML<MenuItem>;
+    expandCollapseGlyph?: StaticallyComposableHTML<MenuItem>;
+    radioIndicator?: StaticallyComposableHTML<MenuItem>;
+};
+/**
+ * A Switch Custom HTML Element.
+ * Implements {@link https://www.w3.org/TR/wai-aria-1.1/#menuitem | ARIA menuitem }, {@link https://www.w3.org/TR/wai-aria-1.1/#menuitemcheckbox | ARIA menuitemcheckbox}, or {@link https://www.w3.org/TR/wai-aria-1.1/#menuitemradio | ARIA menuitemradio }.
+ *
+ * @slot checked-indicator - The checked indicator
+ * @slot radio-indicator - The radio indicator
+ * @slot start - Content which can be provided before the menu item content
+ * @slot end - Content which can be provided after the menu item content
+ * @slot - The default slot for menu item content
+ * @slot expand-collapse-indicator - The expand/collapse indicator
+ * @slot submenu - Used to nest menu's within menu items
+ * @csspart input-container - The element representing the visual checked or radio indicator
+ * @csspart checkbox - The element wrapping the `menuitemcheckbox` indicator
+ * @csspart radio - The element wrapping the `menuitemradio` indicator
+ * @csspart content - The element wrapping the menu item content
+ * @csspart expand-collapse-glyph-container - The element wrapping the expand collapse element
+ * @csspart expand-collapse - The expand/collapse element
+ * @csspart submenu-region - The container for the submenu, used for positioning
+ * @fires expanded-change - Fires a custom 'expanded-change' event when the expanded state changes
+ * @fires change - Fires a custom 'change' event when a non-submenu item with a role of `menuitemcheckbox`, `menuitemradio`, or `menuitem` is invoked
+ *
+ * @public
+ */
+export declare class MenuItem extends FASTElement {
+    /**
+     * The disabled state of the element.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: disabled
+     */
+    disabled: boolean;
+    /**
+     * The expanded state of the element.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: expanded
+     */
+    expanded: boolean;
+    protected expandedChanged(prev: boolean | undefined, next: boolean): void;
+    /**
+     * The role of the element.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: role
+     */
+    role: MenuItemRole;
+    /**
+     * Cleanup function for the submenu positioner.
+     *
+     * @public
+     */
+    cleanup: () => void;
+    /**
+     * The checked value of the element.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: checked
+     */
+    checked: boolean;
+    protected checkedChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * The hidden attribute.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: hidden
+     */
+    hidden: boolean;
+    /**
+     * The submenu slotted content.
+     *
+     * @internal
+     */
+    slottedSubmenu: HTMLElement[];
+    /**
+     * @internal
+     */
+    get hasSubmenu(): boolean;
+    /**
+     * Sets the submenu and updates its position.
+     *
+     * @internal
+     */
+    protected slottedSubmenuChanged(prev: HTMLElement[] | undefined, next: HTMLElement[]): void;
+    /**
+     * The container for the submenu.
+     *
+     * @internal
+     */
+    submenuContainer: HTMLDivElement;
+    /**
+     * @internal
+     */
+    submenu: HTMLElement | undefined;
+    private focusSubmenuOnLoad;
+    /**
+     * @internal
+     */
+    disconnectedCallback(): void;
+    /**
+     * @internal
+     */
+    handleMenuItemKeyDown: (e: KeyboardEvent) => boolean;
+    /**
+     * @internal
+     */
+    handleMenuItemClick: (e: MouseEvent) => boolean;
+    /**
+     * @internal
+     */
+    submenuLoaded: () => void;
+    /**
+     * @internal
+     */
+    handleMouseOver: (e: MouseEvent) => boolean;
+    /**
+     * @internal
+     */
+    handleMouseOut: (e: MouseEvent) => boolean;
+    /**
+     * @internal
+     */
+    private closeSubMenu;
+    /**
+     * @internal
+     */
+    private expandAndFocus;
+    /**
+     * @internal
+     */
+    private invoke;
+    /**
+     * Calculate and apply submenu positioning.
+     *
+     * @public
+     */
+    updateSubmenu(): void;
+}
+/**
+ * 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 MenuItem extends StartEnd {
 }