@fluentui/web-components 3.0.0-beta.20 → 3.0.0-beta.21

package/dist/web-components.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="web" />
+
 import type { Constructable } from '@microsoft/fast-element';
 import { CSSDirective } from '@microsoft/fast-element';
 import { Direction } from '@microsoft/fast-web-utilities';
@@ -2761,17 +2763,6 @@ declare class DelegatesARIALink {
 declare interface DelegatesARIALink extends ARIAGlobalStatesAndProperties {
 }
 
-/**
- * Includes ARIA states and properties relating to the ARIA textbox role
- *
- * @public
- */
-declare class DelegatesARIATextbox {
-}
-
-declare interface DelegatesARIATextbox extends ARIAGlobalStatesAndProperties {
-}
-
 /**
  * Dialog component that extends the FASTElement class.
  *
@@ -3288,15 +3279,6 @@ declare class FormAssociatedSwitch extends FormAssociatedSwitch_base {
 
 declare const FormAssociatedSwitch_base: typeof _Switch;
 
-/**
- * @beta
- */
-declare class FormAssociatedTextField extends FormAssociatedTextField_base {
-    proxy: HTMLInputElement;
-}
-
-declare const FormAssociatedTextField_base: typeof _TextField;
-
 /**
  * Determines the current localization direction of an element.
  *
@@ -5399,12 +5381,6 @@ export declare type TextAlign = ValuesOf<typeof TextAlign>;
  */
 export declare const TextDefinition: FASTElementDefinition<typeof Text_2>;
 
-declare class _TextField extends FASTElement {
-}
-
-declare interface _TextField extends FormAssociated {
-}
-
 /**
  * TextFont Constants
  * @public
@@ -5421,149 +5397,377 @@ export declare const TextFont: {
  */
 export declare type TextFont = ValuesOf<typeof TextFont>;
 
-export declare class TextInput extends FormAssociatedTextField {
+/**
+ * A Text Input Custom HTML Element.
+ * Based largely on the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | `<input>`} element.
+ *
+ * @slot start - Content which can be provided before the input
+ * @slot end - Content which can be provided after the input
+ * @slot - The default slot for button content
+ * @csspart label - The internal `<label>` element
+ * @csspart root - the root container for the internal control
+ * @csspart control - The internal `<input>` control
+ * @public
+ */
+export declare class TextInput extends FASTElement {
     /**
-     * Defines TextInput control size
+     * Indicates the styled appearance of the element.
      *
      * @public
-     * @default 'medium'
+     * @default 'outline'
      * @remarks
-     * HTML Attribute: control-size
+     * HTML Attribute: `appearance`
      */
-    controlSize?: TextInputControlSize;
+    appearance?: TextInputAppearance;
     /**
-     * Defines TextInput appearance.
+     * Indicates the element's autocomplete state.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/autocomplete | `autocomplete`} attribute
      *
      * @public
-     * @default 'outline'
      * @remarks
-     * HTML Attribute: appearance
+     * HTML Attribute: `autocomplete`
      */
-    appearance?: TextInputAppearance;
+    autocomplete?: string;
     /**
-     * When true, the control will be immutable by user interaction. See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly | readonly HTML attribute} for more information.
+     * Indicates that the element should get focus after the page finishes loading.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Element/input#autofocus | `autofocus`} attribute
+     *
      * @public
      * @remarks
-     * HTML Attribute: readonly
+     * HTML Attribute: `autofocus`
      */
-    readOnly: boolean;
-    protected readOnlyChanged(): void;
+    autofocus: boolean;
     /**
-     * Indicates that this element should get focus after the page finishes loading. See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautofocus | autofocus HTML attribute} for more information.
+     * Sets the size of the control.
+     *
      * @public
+     * @default 'medium'
      * @remarks
-     * HTML Attribute: autofocus
+     * HTML Attribute: `control-size`
      */
-    autofocus: boolean;
-    protected autofocusChanged(): void;
+    controlSize?: TextInputControlSize;
     /**
-     * Sets the placeholder value of the element, generally used to provide a hint to the user.
+     * The default slotted content. This is the content that appears in the text field label.
+     *
+     * @internal
+     */
+    defaultSlottedNodes: Node[];
+    /**
+     * Updates the control label visibility based on the presence of default slotted content.
+     *
+     * @internal
+     */
+    defaultSlottedNodesChanged(prev: Node[] | undefined, next: Node[] | undefined): void;
+    /**
+     * Sets the directionality of the element to be submitted with form data.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/dirname | `dirname`} attribute
+     *
      * @public
      * @remarks
-     * HTML Attribute: placeholder
-     * Using this attribute does is not a valid substitute for a labeling element.
+     * HTML Attribute: `dirname`
      */
-    placeholder: string;
-    protected placeholderChanged(): void;
+    dirname?: string;
     /**
-     * Allows setting a type or mode of text.
+     * Sets the element's disabled state.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/disabled | `disabled`} attribute
+     *
      * @public
      * @remarks
-     * HTML Attribute: type
+     * HTML Attribute: `disabled`
      */
-    type: TextInputType;
-    private typeChanged;
+    disabled?: boolean;
     /**
-     * Allows associating a {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist | datalist} to the element by {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/id}.
+     * 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;
+    /**
+     * The initial value of the input.
+     *
      * @public
      * @remarks
-     * HTML Attribute: list
+     * HTML Attribute: `value`
+     */
+    initialValue: string;
+    /**
+     * Sets the value of the element to the initial value.
+     *
+     * @internal
+     */
+    initialValueChanged(): void;
+    /**
+     * Allows associating a `<datalist>` to the element by ID.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Element/input#list | `list`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `list`
      */
     list: string;
-    protected listChanged(): void;
     /**
      * The maximum number of characters a user can enter.
+     *
      * @public
      * @remarks
-     * HTMLAttribute: maxlength
+     * HTML Attribute: `maxlength`
      */
     maxlength: number;
-    protected maxlengthChanged(): void;
     /**
      * The minimum number of characters a user can enter.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/minlength | `minlength`} attribute
+     *
      * @public
      * @remarks
-     * HTMLAttribute: minlength
+     * HTML Attribute: `minlength`
      */
     minlength: number;
-    protected minlengthChanged(): void;
+    /**
+     * Indicates that a comma-separated list of email addresses can be entered. This attribute is only valid when `type="email"`.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/multiple | `multiple`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `multiple`
+     */
+    multiple: boolean;
+    /**
+     * The name of the element. This element's value will be surfaced during form submission under the provided name.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `name`
+     */
+    name: string;
     /**
      * A regular expression that the value must match to pass validation.
+     *
      * @public
      * @remarks
-     * HTMLAttribute: pattern
+     * HTML Attribute: `pattern`
      */
     pattern: string;
-    protected patternChanged(): void;
+    /**
+     * Sets the placeholder value of the element, generally used to provide a hint to the user.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/placeholder | `placeholder`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `placeholder`
+     * This attribute is not a valid substitute for a label.
+     */
+    placeholder: string;
+    /**
+     * When true, the control will be immutable by user interaction.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Attributes/readonly | `readonly`} attribute
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `readonly`
+     */
+    readonly?: boolean;
+    /**
+     * Syncs the `ElementInternals.ariaReadOnly` property when the `readonly` property changes.
+     *
+     * @internal
+     */
+    readonlyChanged(): void;
+    /**
+     * The element's required attribute.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `required`
+     */
+    required: boolean;
+    /**
+     * Syncs the element's internal `aria-required` state with the `required` attribute.
+     *
+     * @param previous - the previous required state
+     * @param next - the current required state
+     *
+     * @internal
+     */
+    requiredChanged(previous: boolean, next: boolean): void;
     /**
      * Sets the width of the element to a specified number of characters.
+     *
      * @public
      * @remarks
-     * HTMLAttribute: size
+     * HTML Attribute: `size`
      */
     size: number;
-    protected sizeChanged(): void;
     /**
      * Controls whether or not to enable spell checking for the input field, or if the default spell checking configuration should be used.
+     * @see The {@link https://developer.mozilla.org/docs/Web/HTML/Global_attributes/spellcheck | `spellcheck`} attribute
+     *
      * @public
      * @remarks
-     * HTMLAttribute: size
+     * HTML Attribute: `spellcheck`
      */
     spellcheck: boolean;
-    protected spellcheckChanged(): void;
     /**
+     * Allows setting a type or mode of text.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `type`
+     */
+    type: TextInputType;
+    /**
+     * The current value of the input.
+     *
      * @internal
      */
-    defaultSlottedNodes: Node[];
+    private _value;
     /**
-     * A reference to the internal input element
+     * A reference to the internal input element.
+     *
      * @internal
      */
     control: HTMLInputElement;
     /**
+     * A reference to the internal label element.
+     *
+     * @internal
+     */
+    controlLabel: HTMLLabelElement;
+    /**
+     * Indicates that the value has been changed by the user.
+     *
+     * @internal
+     */
+    private dirtyValue;
+    /**
+     * The internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    protected elementInternals: ElementInternals;
+    /**
+     * 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 readonly formAssociated = true;
+    /**
+     * The element's validity state.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/validity | `ElementInternals.validity`} property.
+     */
+    get validity(): ValidityState;
+    /**
+     * The validation message.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/validationMessage | `ElementInternals.validationMessage`} property.
+     */
+    get validationMessage(): string;
+    /**
+     * The current value of the input.
+     * @public
+     */
+    get value(): string;
+    set value(value: string);
+    /**
+     * Determines if the control can be submitted for constraint validation.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/willValidate | `ElementInternals.willValidate`} property.
+     */
+    get willValidate(): boolean;
+    /**
+     * 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;
+    /**
+     * Change event handler for inner control.
+     *
      * @internal
+     * @privateRemarks
+     * "Change" events are not `composable` so they will not permeate the shadow DOM boundary. This function effectively
+     * proxies the change event, emitting a `change` event whenever the internal control emits a `change` event.
      */
+    changeHandler(e: InputEvent): void;
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Resets the value to its initial value when the form is reset.
+     *
+     * @internal
+     */
+    formResetCallback(): void;
+    /**
+     * Handles implicit form submission when the user presses the "Enter" key.
+     *
+     * @internal
+     */
+    private implicitSubmit;
+    /**
+     * Handles the internal control's `input` event.
+     *
+     * @internal
+     */
+    inputHandler(e: InputEvent): boolean | void;
     /**
-     * Selects all the text in the text field
+     * Handles the internal control's `keypress` event.
+     *
+     * @internal
+     */
+    keypressHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Selects all the text in the text field.
      *
      * @public
+     * @privateRemarks
+     * The `select` event does not permeate the shadow DOM boundary. This function effectively proxies the event,
+     * emitting a `select` event whenever the internal control emits a `select` event
+     *
      */
     select(): void;
     /**
-     * Handles the internal control's `input` event
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/setFormValue | `ElementInternals.setFormValue()`} method.
+     *
      * @internal
      */
-    handleTextInput(): void;
+    setFormValue(value: File | string | FormData | null, state?: File | string | FormData | null): void;
     /**
-     * Change event handler for inner control.
-     * @remarks
-     * "Change" events are not `composable` so they will not
-     * permeate the shadow DOM boundary. This fn effectively proxies
-     * the change event, emitting a `change` event whenever the internal
-     * control emits a `change` event
+     * Sets the validity of the control.
+     *
+     * @param flags - Validity flags. If not provided, the control's `validity` will be used.
+     * @param message - Optional message to supply. If not provided, the control's `validationMessage` will be used. If the control does not have a `validationMessage`, the message will be empty.
+     * @param anchor - Optional anchor to use for the validation message. If not provided, the control will be used.
+     *
      * @internal
      */
-    handleChange(): void;
-    /** {@inheritDoc (FormAssociated:interface).validate} */
-    validate(): void;
+    setValidity(flags?: ValidityStateFlags, message?: string, anchor?: HTMLElement): void;
 }
 
-export declare interface TextInput extends StartEnd, DelegatesARIATextbox {
+/**
+ * @internal
+ * @privateRemarks
+ * Mark internal because exporting class and interface of the same name
+ * confuses API documenter.
+ * TODO: https://github.com/microsoft/rushstack/issues/1308
+ */
+export declare interface TextInput extends StartEnd {
 }
 
 /**
- * TextInput appearance constants
+ * Values for the `appearance` attribute on TextInput elements.
+ *
  * @public
  */
 export declare const TextInputAppearance: {
@@ -5573,14 +5777,11 @@ export declare const TextInputAppearance: {
     readonly filledDarker: "filled-darker";
 };
 
-/**
- * Applies appearance styling to TextInput
- * @public
- */
 export declare type TextInputAppearance = ValuesOf<typeof TextInputAppearance>;
 
 /**
- * TextInput size constants
+ * Values for the `control-size` attribute on TextInput elements.
+ *
  * @public
  */
 export declare const TextInputControlSize: {
@@ -5589,25 +5790,27 @@ export declare const TextInputControlSize: {
     readonly large: "large";
 };
 
-/**
- * Applies size styling to TextInput
- * @public
- */
 export declare type TextInputControlSize = ValuesOf<typeof TextInputControlSize>;
 
 /**
- * The Fluent TextInput Element.
- *
+ * The Fluent TextInput Element definition.
  *
  * @public
  * @remarks
- * HTML Element: \<fluent-text-input\>
+ * HTML Element: `<fluent-text-input>`
  */
 export declare const TextInputDefinition: FASTElementDefinition<typeof TextInput>;
 
+/**
+ * TextInput configuration options.
+ *
+ * @public
+ */
 export declare type TextInputOptions = StartEndOptions<TextInput>;
 
-/** TextInput styles
+/**
+ * Styles for the TextInput component.
+ *
  * @public
  */
 export declare const TextInputStyles: ElementStyles;
@@ -5618,36 +5821,18 @@ export declare const TextInputStyles: ElementStyles;
 export declare const TextInputTemplate: ElementViewTemplate<TextInput>;
 
 /**
- * Text field sub-types
+ * Values for the `type` attribute on TextInput elements.
+ *
  * @public
  */
 export declare const TextInputType: {
-    /**
-     * An email TextInput
-     */
     readonly email: "email";
-    /**
-     * A password TextInput
-     */
     readonly password: "password";
-    /**
-     * A telephone TextInput
-     */
     readonly tel: "tel";
-    /**
-     * A text TextInput
-     */
     readonly text: "text";
-    /**
-     * A URL TextInput
-     */
     readonly url: "url";
 };
 
-/**
- * Types for the text field sub-types
- * @public
- */
 export declare type TextInputType = ValuesOf<typeof TextInputType>;
 
 /**