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

package/dist/web-components.d.ts

@@ -1218,171 +1218,276 @@ export declare const borderRadiusXLarge = "var(--borderRadiusXLarge)";
 
 /**
  * A Button Custom HTML Element.
- * Based largely on the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element }.
+ * Based largely on the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | `<button>`} element.
  *
  * @slot start - Content which can be provided before the button content
  * @slot end - Content which can be provided after the button content
  * @slot - The default slot for button content
- * @csspart control - The button element
- * @csspart content - The element wrapping button content
+ * @csspart content - The button content container
  *
  * @public
  */
-export declare class Button extends FormAssociatedButton {
+export declare class Button extends FASTElement {
     /**
-     * Determines if the element should receive document focus on page load.
+     * Indicates the styled appearance of the button.
      *
      * @public
      * @remarks
-     * HTML Attribute: autofocus
+     * HTML Attribute: `appearance`
+     */
+    appearance?: ButtonAppearance;
+    /**
+     * Indicates the button should be focused when the page is loaded.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#autofocus | `autofocus`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `autofocus`
      */
     autofocus: boolean;
     /**
-     * The id of a form to associate the element to.
+     * Default slotted content.
+     *
+     * @public
+     */
+    defaultSlottedContent: HTMLElement[];
+    /**
+     * Sets the element's disabled state.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#disabled | `disabled`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: form
+     * HTML Attribute: `disabled`
      */
-    formId: string;
+    disabled?: boolean;
     /**
-     * See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element} for more details.
+     * Indicates that the button is focusable while disabled.
      *
      * @public
      * @remarks
-     * HTML Attribute: formaction
+     * HTML Attribute: `disabled-focusable`
      */
-    formaction: string;
-    protected formactionChanged(): void;
+    disabledFocusable: boolean;
     /**
-     * See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element} for more details.
+     * Sets the element's internal disabled state when the element is focusable while disabled.
+     *
+     * @param previous - the previous disabledFocusable value
+     * @param next - the current disabledFocusable value
+     * @internal
+     */
+    disabledFocusableChanged(previous: boolean, next: boolean): void;
+    /**
+     * The internal {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    protected elementInternals: ElementInternals;
+    /**
+     * The associated form element.
+     *
+     * @public
+     */
+    get form(): HTMLFormElement | null;
+    /**
+     * The URL that processes the form submission.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formaction | `formaction`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: formenctype
+     * HTML Attribute: `formaction`
+     */
+    formAction?: string;
+    /**
+     * The form-associated flag.
+     * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example | Form-associated custom elements}
+     *
+     * @public
      */
-    formenctype: string;
-    protected formenctypeChanged(): void;
+    static readonly formAssociated = true;
     /**
-     * See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element} for more details.
+     * The id of a form to associate the element to.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#form | `form`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: formmethod
+     * HTML Attribute: `form`
      */
-    formmethod: string;
-    protected formmethodChanged(): void;
+    formAttribute?: string;
     /**
-     * See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element} for more details.
+     * The encoding type for the form submission.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formenctype | `formenctype`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: formnovalidate
+     * HTML Attribute: `formenctype`
      */
-    formnovalidate: boolean;
-    protected formnovalidateChanged(): void;
+    formEnctype?: string;
     /**
-     * See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element} for more details.
+     * The HTTP method that the browser uses to submit the form.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formmethod | `formmethod`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: formtarget
+     * HTML Attribute: `formmethod`
      */
-    formtarget: '_self' | '_blank' | '_parent' | '_top';
-    protected formtargetChanged(): void;
+    formMethod?: string;
     /**
-     * The button type.
+     * Indicates that the form will not be validated when submitted.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formnovalidate | `formnovalidate`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: type
+     * HTML Attribute: `formnovalidate`
      */
-    type: ButtonType;
-    protected typeChanged(previous: ButtonType | undefined, next: ButtonType): void;
+    formNoValidate?: boolean;
+    /**
+     * The internal form submission fallback control.
+     *
+     * @internal
+     */
+    private formSubmissionFallbackControl?;
+    /**
+     * The internal slot for the form submission fallback control.
+     *
+     * @internal
+     */
+    private formSubmissionFallbackControlSlot?;
     /**
-     * The appearance the button should have.
+     * The target frame or window to open the form submission in.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formtarget | `formtarget`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: appearance
+     * HTML Attribute: `formtarget`
      */
-    appearance?: ButtonAppearance | undefined;
+    formTarget?: ButtonFormTarget;
     /**
-     * The shape the button should have.
+     * Indicates that the button should only display as an icon with no text content.
      *
      * @public
      * @remarks
-     * HTML Attribute: shape
+     * HTML Attribute: `icon-only`
      */
-    shape?: ButtonShape | undefined;
+    iconOnly: boolean;
     /**
-     * The size the button should have.
+     * A reference to all associated label elements.
+     *
+     * @public
+     */
+    get labels(): ReadonlyArray<Node>;
+    /**
+     * The name of the element. This element's value will be surfaced during form submission under the provided name.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#name | `name`} attribute
      *
      * @public
      * @remarks
-     * HTML Attribute: size
+     * HTML Attribute: `name`
      */
-    size?: ButtonSize;
+    name?: string;
     /**
-     * The button has an icon only, no text content
+     * The shape of the button.
      *
      * @public
      * @remarks
-     * HTML Attribute: icon-only
+     * HTML Attribute: `shape`
      */
-    iconOnly: boolean;
+    shape?: ButtonShape;
     /**
-     * The button is disabled but focusable
+     * The size of the button.
      *
      * @public
      * @remarks
-     * HTML Attribute: disabled-focusable
+     * HTML Attribute: `size`
      */
-    disabledFocusable?: boolean;
-    protected disabledFocusableChanged(prev: boolean, next: boolean): void;
+    size?: ButtonSize;
     /**
-     * Prevents disabledFocusable click events
+     * The button type.
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#type | `type`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `type`
      */
-    private handleDisabledFocusableClick;
+    type: ButtonType;
     /**
+     * Removes the form submission fallback control when the type changes.
      *
-     * Default slotted content
+     * @param previous - the previous type value
+     * @param next - the new type value
+     * @internal
+     */
+    typeChanged(previous: ButtonType, next: ButtonType): void;
+    /**
+     * The value attribute.
+     *
+     * @see The {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#value | `value`} attribute
      *
      * @public
      * @remarks
+     * HTML Attribute: `value`
      */
-    defaultSlottedContent: HTMLElement[];
-    /** {@inheritDoc (FormAssociated:interface).validate} */
-    validate(): void;
+    value?: string;
     /**
+     * Handles the button click event.
+     *
+     * @param e - The event object
      * @internal
      */
+    clickHandler(e: Event): boolean | void;
     connectedCallback(): void;
-    disconnectedCallback(): void;
+    constructor();
+    /**
+     * This fallback creates a new slot, then creates a submit button to mirror the custom element's
+     * properties. The submit button is then appended to the slot and the form is submitted.
+     *
+     * @internal
+     * @privateRemarks
+     * This is a workaround until {@link https://github.com/WICG/webcomponents/issues/814 | WICG/webcomponents/issues/814} is resolved.
+     */
+    private createAndInsertFormSubmissionFallbackControl;
     /**
-     * Submits the parent form
+     * Invoked when a connected component's form or fieldset has its disabled state changed.
+     *
+     * @param disabled - the disabled value of the form / fieldset
+     *
+     * @internal
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /**
+     * Handles keypress events for the button.
+     *
+     * @param e - the keyboard event
+     * @returns - the return value of the click handler
+     * @public
+     */
+    keypressHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Presses the button.
+     *
+     * @public
+     */
+    protected press(): void;
+    /**
+     * Resets the associated form.
+     *
+     * @public
      */
-    private handleSubmission;
+    resetForm(): void;
     /**
-     * Resets the parent form
+     * Submits the associated form.
+     *
+     * @internal
      */
-    private handleFormReset;
-    control: HTMLButtonElement;
+    private submitForm;
 }
 
 /**
- * Mark internal because exporting class and interface of the same name
- * confuses API documenter.
- * TODO: https://github.com/microsoft/fast/issues/3317
  * @internal
+ * @privateRemarks
+ * Mark internal because exporting class and interface of the same name confuses API documenter.
+ * TODO: https://github.com/microsoft/fast/issues/3317
  */
-export declare interface Button extends StartEnd, DelegatesARIAButton {
-}
-
-declare class _Button extends FASTElement {
-}
-
-declare interface _Button extends FormAssociated {
+export declare interface Button extends StartEnd {
 }
 
 /**
@@ -1404,14 +1509,33 @@ export declare const ButtonAppearance: {
 export declare type ButtonAppearance = ValuesOf<typeof ButtonAppearance>;
 
 /**
+ * The definition for the Fluent Button component.
+ *
  * @public
  * @remarks
- * HTML Element: \<fluent-button\>
+ * HTML Element: `<fluent-button>`
  */
 export declare const ButtonDefinition: FASTElementDefinition<typeof Button>;
 
 /**
- * Button configuration options
+ * Button `formtarget` attribute values.
+ * @public
+ */
+export declare const ButtonFormTarget: {
+    readonly blank: "_blank";
+    readonly self: "_self";
+    readonly parent: "_parent";
+    readonly top: "_top";
+};
+
+/**
+ * Types for the `formtarget` attribute values.
+ * @public
+ */
+export declare type ButtonFormTarget = ValuesOf<typeof ButtonFormTarget>;
+
+/**
+ * Button configuration options.
  * @public
  */
 declare type ButtonOptions = StartEndOptions<Button>;
@@ -1452,6 +1576,11 @@ export declare const ButtonSize: {
  */
 export declare type ButtonSize = ValuesOf<typeof ButtonSize>;
 
+/**
+ * The template for the Button component.
+ *
+ * @public
+ */
 export declare const ButtonTemplate: ElementViewTemplate<Button>;
 
 /**
@@ -2520,37 +2649,6 @@ export declare const curveLinear = "var(--curveLinear)";
  */
 export declare const darkModeStylesheetBehavior: (styles: ElementStyles) => MatchMediaStyleSheetBehavior;
 
-/**
- * Includes ARIA states and properties relating to the ARIA button role
- *
- * @public
- */
-export declare class DelegatesARIAButton {
-    /**
-     * See {@link https://www.w3.org/WAI/PF/aria/roles#button} for more information
-     * @public
-     * @remarks
-     * HTML Attribute: aria-expanded
-     */
-    ariaExpanded: 'true' | 'false' | string | null;
-    /**
-     * See {@link https://www.w3.org/WAI/PF/aria/roles#button} for more information
-     * @public
-     * @remarks
-     * HTML Attribute: aria-pressed
-     */
-    ariaPressed: 'true' | 'false' | 'mixed' | 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 declare interface DelegatesARIAButton extends ARIAGlobalStatesAndProperties {
-}
-
 /**
  * Includes ARIA states and properties relating to the ARIA link role
  *
@@ -2968,63 +3066,6 @@ export declare const durationUltraFast = "var(--durationUltraFast)";
 
 export declare const durationUltraSlow = "var(--durationUltraSlow)";
 
-/**
- * Source:
- * https://html.spec.whatwg.org/multipage/custom-elements.html#elementinternals
- */
-declare interface ElementInternals_2 {
-    /**
-     * 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_2: {
-    prototype: ElementInternals_2;
-    new (): ElementInternals_2;
-};
-
 /**
  * End configuration options
  * @public
@@ -3091,10 +3132,10 @@ declare function FormAssociated<T extends ConstructableFormAssociated>(BaseCtor:
  *
  * @beta
  */
-declare interface FormAssociated extends Omit<ElementInternals_2, 'labels'> {
+declare interface FormAssociated extends Omit<ElementInternals, 'labels'> {
     dirtyValue: boolean;
     disabled: boolean;
-    readonly elementInternals: ElementInternals_2 | null;
+    readonly elementInternals: ElementInternals | null;
     readonly formAssociated: boolean;
     initialValue: string;
     readonly labels: ReadonlyArray<Node[]>;
@@ -3121,15 +3162,6 @@ declare interface FormAssociated extends Omit<ElementInternals_2, 'labels'> {
     valueChanged(previous: string, next: string): void;
 }
 
-/**
- * @beta
- */
-declare class FormAssociatedButton extends FormAssociatedButton_base {
-    proxy: HTMLInputElement;
-}
-
-declare const FormAssociatedButton_base: typeof _Button;
-
 /**
  * @beta
  */
@@ -4097,7 +4129,7 @@ export declare const MenuTemplate: ElementViewTemplate<Menu>;
  *
  * @public
  */
-declare class ProgressBar_2 extends BaseProgress {
+export declare class ProgressBar extends BaseProgress {
     /**
      * The thickness of the progress bar
      *
@@ -4121,7 +4153,6 @@ declare class ProgressBar_2 extends BaseProgress {
      */
     validationState: ProgressBarValidationState | null;
 }
-export { ProgressBar_2 as ProgressBar }
 
 /**
  * The Fluent ProgressBar Element.
@@ -4131,7 +4162,7 @@ export { ProgressBar_2 as ProgressBar }
  * @remarks
  * HTML Element: \<fluent-progress-bar\>
  */
-export declare const ProgressBarDefinition: FASTElementDefinition<typeof ProgressBar_2>;
+export declare const ProgressBarDefinition: FASTElementDefinition<typeof ProgressBar>;
 
 /**
  * ProgressBarShape Constants
@@ -4153,7 +4184,7 @@ export declare type ProgressBarShape = ValuesOf<typeof ProgressBarShape>;
  */
 export declare const ProgressBarStyles: ElementStyles;
 
-export declare const ProgressBarTemplate: ElementViewTemplate<ProgressBar_2>;
+export declare const ProgressBarTemplate: ElementViewTemplate<ProgressBar>;
 
 /**
  * ProgressBarThickness Constants
@@ -4191,8 +4222,8 @@ export declare type ProgressBarValidationState = ValuesOf<typeof ProgressBarVali
  * @public
  */
 export declare type ProgressOptions = {
-    indeterminateIndicator1?: StaticallyComposableHTML<ProgressBar_2>;
-    indeterminateIndicator2?: StaticallyComposableHTML<ProgressBar_2>;
+    indeterminateIndicator1?: StaticallyComposableHTML<ProgressBar>;
+    indeterminateIndicator2?: StaticallyComposableHTML<ProgressBar>;
 };
 
 /**
@@ -4921,6 +4952,11 @@ export declare const strokeWidthThickest = "var(--strokeWidthThickest)";
 
 export declare const strokeWidthThin = "var(--strokeWidthThin)";
 
+/**
+ * The styles for the Button component.
+ *
+ * @public
+ */
 declare const styles: ElementStyles;
 export { styles as ButtonStyles }
 export { styles as MenuButtonStyles }
@@ -5590,51 +5626,54 @@ export declare const TextWeight: {
 export declare type TextWeight = ValuesOf<typeof TextWeight>;
 
 /**
- * The base class used for constructing a fluent-toggle-button custom element
+ * The base class used for constructing a `<fluent-toggle-button>` custom element.
+ *
  * @public
  */
 export declare class ToggleButton extends Button {
     /**
-     * Tracks whether the "checked" property has been changed.
-     * This is necessary to provide consistent behavior with
-     * normal input checkboxes
+     * Indicates the pressed state of the control.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `pressed`
      */
-    protected dirtyChecked: boolean;
+    pressed: boolean;
     /**
-     * Provides the default checkedness of the input element
-     * Passed down to proxy
+     * Updates the pressed state when the `pressed` property changes.
+     *
+     * @internal
+     */
+    protected pressedChanged(): void;
+    /**
+     * Indicates the mixed state of the control. This property takes precedence over `pressed`.
      *
      * @public
      * @remarks
-     * HTML Attribute: checked
+     * HTML Attribute: `mixed`
      */
-    checkedAttribute: boolean;
-    protected checkedAttributeChanged(): void;
-    defaultChecked: boolean;
-    protected defaultCheckedChanged(): void;
+    mixed?: boolean;
     /**
-     * The checked state of the control.
+     * Updates the pressed state when the `mixed` property changes.
      *
-     * @public
+     * @param previous - the previous mixed state
+     * @param next - the current mixed state
+     * @internal
      */
-    checked: boolean;
-    protected checkedChanged(prev: boolean | undefined, next: boolean): void;
+    protected mixedChanged(): void;
     /**
-     * The current checkedness of the element. This property serves as a mechanism
-     * to set the `checked` property through both property assignment and the
-     * .setAttribute() method. This is useful for setting the field's checkedness
-     * in UI libraries that bind data through the .setAttribute() API
-     * and don't support IDL attribute binding.
+     * Toggles the pressed state of the button.
+     *
+     * @override
      */
-    currentChecked: boolean;
-    currentCheckedChanged(prev: boolean | undefined, next: boolean): void;
-    constructor();
+    protected press(): void;
     connectedCallback(): void;
-    disconnectedCallback(): void;
     /**
+     * Sets the `aria-pressed` attribute based on the `pressed` and `mixed` properties.
+     *
      * @internal
      */
-    protected handleToggleButtonClick: (e: MouseEvent) => void;
+    private setPressedState;
 }
 
 /**
@@ -5695,6 +5734,13 @@ export declare const ToggleButtonSize: {
  */
 export declare type ToggleButtonSize = ValuesOf<typeof ToggleButtonSize>;
 
+/**
+ * The styles for the ToggleButton component.
+ *
+ * @public
+ * @privateRemarks
+ * TODO: Need to support icon hover styles
+ */
 export declare const ToggleButtonStyles: ElementStyles;
 
 /**
@@ -5703,25 +5749,6 @@ export declare const ToggleButtonStyles: ElementStyles;
  */
 export declare const ToggleButtonTemplate: ElementViewTemplate<ToggleButton>;
 
-/**
- * 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.
- */
-declare interface ValidityStateFlags {
-    badInput?: boolean;
-    customError?: boolean;
-    patternMismatch?: boolean;
-    rangeOverflow?: boolean;
-    rangeUnderflow?: boolean;
-    stepMismatch?: boolean;
-    tooLong?: boolean;
-    tooShort?: boolean;
-    typeMismatch?: boolean;
-    valueMissing?: boolean;
-}
-
 /**
  * Helper for enumerating a type from a const object
  * Example: export type Foo = ValuesOf\<typeof Foo\>