@fluentui/web-components 3.0.0-beta.24 → 3.0.0-beta.26

package/dist/web-components.d.ts

@@ -1064,6 +1064,288 @@ export declare const BadgeStyles: ElementStyles;
 
 export declare const BadgeTemplate: ElementViewTemplate<Badge>;
 
+/**
+ * A Checkbox Custom HTML Element.
+ * Implements the {@link https://www.w3.org/TR/wai-aria-1.1/#checkbox | ARIA checkbox }.
+ *
+ * @slot checked-indicator - The checked indicator
+ * @slot indeterminate-indicator - The indeterminate indicator
+ * @fires change - Emits a custom change event when the checked state changes
+ * @fires input - Emits a custom input event when the checked state changes
+ *
+ * @public
+ */
+declare class BaseCheckbox extends FASTElement {
+    /**
+     * 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: `autofocus`
+     */
+    autofocus: boolean;
+    /**
+     * The element's current checked state.
+     *
+     * @public
+     */
+    get checked(): boolean;
+    set checked(state: boolean);
+    /**
+     * The element's disabled state.
+     * @public
+     * @remarks
+     * HTML Attribute: `disabled`
+     */
+    disabled: boolean;
+    /**
+     * 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 element is in an indeterminate or mixed state.
+     *
+     * @public
+     */
+    indeterminate?: boolean;
+    /**
+     * Synchronizes the element's indeterminate state with the internal ElementInternals state.
+     *
+     * @internal
+     */
+    indeterminateChanged(prev: boolean, next: boolean): void;
+    /**
+     * The element's checked state.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `checked`
+     */
+    initialChecked?: boolean;
+    /**
+     * Updates the form value when the checked state changes.
+     *
+     * @internal
+     */
+    initialCheckedChanged(prev: boolean | undefined, next: boolean): void;
+    /**
+     * The initial value of the input.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `value`
+     */
+    initialValue: string;
+    /**
+     * Sets the value of the input when the value attribute changes.
+     *
+     * @param prev - The previous value
+     * @param next - The current value
+     * @internal
+     */
+    initialValueChanged(prev: string, next: string): void;
+    /**
+     * 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;
+    /**
+     * The element's required state.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `required`
+     */
+    required: boolean;
+    /**
+     * Sets the validity of the control when the required state changes.
+     *
+     * @param prev - The previous required state
+     * @param next - The current required state
+     * @internal
+     */
+    requiredChanged(prev: boolean, next: boolean): void;
+    /**
+     * The internal checked state of the control.
+     *
+     * @internal
+     */
+    private _checked;
+    /**
+     * Indicates that the checked state has been changed by the user.
+     *
+     * @internal
+     */
+    private dirtyChecked;
+    /**
+     * 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 internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    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 formAssociated: boolean;
+    /**
+     * A reference to all associated `<label>` elements.
+     *
+     * @public
+     */
+    get labels(): ReadonlyArray<Node>;
+    /**
+     * The fallback validation message, taken from a native checkbox `<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`).
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/validationMessage | `ElementInternals.validationMessage`} property.
+     */
+    get validationMessage(): string;
+    /**
+     * 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 internal value of the input.
+     *
+     * @internal
+     */
+    private _value;
+    /**
+     * 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;
+    /**
+     * Sets the `elementInternals.ariaChecked` value based on the checked state.
+     *
+     * @internal
+     */
+    private setAriaChecked;
+    /**
+     * Checks the validity of the element and returns the result.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/checkValidity | `HTMLInputElement.checkValidity()`} method.
+     */
+    checkValidity(): boolean;
+    /**
+     * Toggles the checked state when the user clicks the element.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    clickHandler(e: MouseEvent): boolean | void;
+    connectedCallback(): void;
+    constructor();
+    /**
+     * Updates the form value when a user changes the `checked` state.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    inputHandler(e: Event): boolean | void;
+    /**
+     * Prevents scrolling when the user presses the space key.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    keydownHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Toggles the checked state when the user releases the space key.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    keyupHandler(e: KeyboardEvent): boolean | void;
+    /**
+     * Resets the form value to its initial value when the form is reset.
+     *
+     * @internal
+     */
+    formResetCallback(): void;
+    /**
+     * Reports the validity of the element.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/reportValidity | `HTMLInputElement.reportValidity()`} method.
+     */
+    reportValidity(): boolean;
+    /**
+     * 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;
+    /**
+     * Sets a custom validity message.
+     *
+     * @param message - The message to set
+     * @public
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * Sets the validity of the control.
+     *
+     * @param flags - Validity flags to set.
+     * @param message - Optional message to supply. If not provided, the control'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;
+    /**
+     * Toggles the checked state of the control.
+     *
+     * @public
+     */
+    private toggleChecked;
+}
+
 /**
  * A base class for progress components.
  * @public
@@ -1635,75 +1917,23 @@ declare interface CheckableFormAssociated extends FormAssociated {
     checkedChanged(oldValue: boolean | undefined, newValue: boolean): void;
 }
 
-/**
- * A Checkbox Custom HTML Element.
- * Implements the {@link https://www.w3.org/TR/wai-aria-1.1/#checkbox | ARIA checkbox }.
- *
- * @slot checked-indicator - The checked indicator
- * @slot indeterminate-indicator - The indeterminate indicator
- * @slot - The default slot for the label
- * @csspart control - The element representing the visual checkbox control
- * @csspart label - The label
- * @fires change - Emits a custom change event when the checked state changes
- *
- * @public
- */
-export declare class Checkbox extends FormAssociatedCheckbox {
+export declare class Checkbox extends BaseCheckbox {
     /**
-     * Sets shape of the checkbox.
+     * Indicates the shape of the checkbox.
      *
      * @public
      * @remarks
-     * HTML Attribute: shape
+     * HTML Attribute: `shape`
      */
-    shape?: CheckboxShape;
+    shape: CheckboxShape;
     /**
-     * Sets size of the checkbox.
+     * Indicates the size of the checkbox.
      *
      * @public
      * @remarks
-     * HTML Attribute: size
+     * HTML Attribute: `size`
      */
     size?: CheckboxSize;
-    /**
-     * Sets position of the label relative to the input
-     *
-     * @public
-     * @remarks
-     * HTML Attribute: label-position
-     */
-    labelPosition?: CheckboxLabelPosition;
-    /**
-     * The element's value to be included in form submission when checked.
-     * Default to "on" to reach parity with input[type="checkbox"]
-     *
-     * @internal
-     */
-    initialValue: string;
-    /**
-     * @internal
-     */
-    defaultSlottedNodes: Node[];
-    /**
-     * The indeterminate state of the control
-     */
-    indeterminate: boolean;
-    constructor();
-    private toggleChecked;
-    /**
-     * @internal
-     */
-    keypressHandler: (e: KeyboardEvent) => void;
-    /**
-     * @internal
-     */
-    clickHandler: (e: MouseEvent) => void;
-}
-
-declare class _Checkbox extends FASTElement {
-}
-
-declare interface _Checkbox extends CheckableFormAssociated {
 }
 
 /**
@@ -1715,17 +1945,6 @@ declare interface _Checkbox extends CheckableFormAssociated {
  */
 export declare const CheckboxDefinition: FASTElementDefinition<typeof Checkbox>;
 
-/**
- * Checkbox label position
- * @public
- */
-declare const CheckboxLabelPosition: {
-    readonly before: "before";
-    readonly after: "after";
-};
-
-declare type CheckboxLabelPosition = ValuesOf<typeof CheckboxLabelPosition>;
-
 /**
  * Checkbox configuration options
  * @public
@@ -1744,6 +1963,7 @@ export declare const CheckboxShape: {
     readonly square: "square";
 };
 
+/** @public */
 export declare type CheckboxShape = ValuesOf<typeof CheckboxShape>;
 
 /**
@@ -1755,6 +1975,7 @@ export declare const CheckboxSize: {
     readonly large: "large";
 };
 
+/** @public */
 export declare type CheckboxSize = ValuesOf<typeof CheckboxSize>;
 
 /** Checkbox styles
@@ -4529,6 +4750,139 @@ declare type EndOptions<TSource = any, TParent = any> = {
     end?: StaticallyComposableHTML<TSource, TParent>;
 };
 
+/**
+ * A Field Custom HTML Element.
+ *
+ * @public
+ */
+export declare class Field extends FASTElement {
+    /**
+     * The position of the label relative to the input.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `label-position`
+     */
+    labelPosition: FieldLabelPosition;
+    /**
+     * The slotted message elements. Filtered to only include elements with a `flag` attribute.
+     *
+     * @internal
+     */
+    messageSlot: Element[];
+    /**
+     * Adds or removes the `invalid` event listener based on the presence of slotted message elements.
+     *
+     * @param prev - the previous list of slotted message elements
+     * @param next - the current list of slotted message elements
+     * @internal
+     */
+    messageSlotChanged(prev: Element[], next: Element[]): void;
+    /**
+     * The slotted inputs.
+     *
+     * @internal
+     * @privateRemarks
+     * This field is populated with the `children` directive in the template rather than `slotted`.
+     */
+    slottedInputs: SlottableInput[];
+    /**
+     * Sets the `input` property to the first slotted input.
+     *
+     * @param prev - The previous collection of inputs.
+     * @param next - The current collection of inputs.
+     * @internal
+     */
+    slottedInputsChanged(prev: SlottableInput[] | undefined, next: SlottableInput[] | undefined): void;
+    /**
+     * The internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    elementInternals: ElementInternals;
+    /**
+     * Reference to the first slotted input.
+     *
+     * @public
+     */
+    input: SlottableInput;
+    /**
+     * Calls the `setStates` method when a `change` event is emitted from the slotted input.
+     *
+     * @param e - the event object
+     * @internal
+     */
+    changeHandler(e: Event): void;
+    /**
+     * Redirects `click` events to the slotted input.
+     *
+     * @internal
+     */
+    clickHandler(e: MouseEvent): boolean | void;
+    /**
+     * Applies the `focus-visible` state to the element when the slotted input receives visible focus.
+     *
+     * @param e - the focus event
+     * @internal
+     */
+    focusinHandler(e: FocusEvent): boolean | void;
+    /**
+     * Removes the `focus-visible` state from the field when a slotted input loses focus.
+     *
+     * @param e - the focus event
+     * @internal
+     */
+    focusoutHandler(e: FocusEvent): boolean | void;
+    /**
+     * Toggles validity state flags on the element when the slotted input emits an `invalid` event (if slotted validation messages are present).
+     *
+     * @param e - the event object
+     * @internal
+     */
+    invalidHandler(e: Event): boolean | void;
+    /**
+     * Toggles the field's states based on the slotted input.
+     *
+     * @internal
+     */
+    setStates(): void;
+}
+
+/**
+ * The Fluent Field Element
+ *
+ * @public
+ * @remarks
+ * HTML Element: `<fluent-field>`
+ */
+export declare const FieldDefinition: FASTElementDefinition<typeof Field>;
+
+/**
+ * Label position values
+ * @public
+ */
+export declare const FieldLabelPosition: {
+    readonly above: "above";
+    readonly after: "after";
+    readonly before: "before";
+};
+
+/** @public */
+export declare type FieldLabelPosition = ValuesOf<typeof FieldLabelPosition>;
+
+/**
+ * The styles for the {@link Field} component.
+ *
+ * @public
+ */
+export declare const FieldStyles: ElementStyles;
+
+/**
+ * Template for the Field component
+ * @public
+ */
+export declare const FieldTemplate: ElementViewTemplate;
+
 export declare const FluentDesignSystem: Readonly<{
     prefix: "fluent";
     shadowRootMode: "open";
@@ -4685,15 +5039,6 @@ declare interface FormAssociated extends Omit<ElementInternals, 'labels'> {
     valueChanged(previous: string, next: string): void;
 }
 
-/**
- * @beta
- */
-declare class FormAssociatedCheckbox extends FormAssociatedCheckbox_base {
-    proxy: HTMLInputElement;
-}
-
-declare const FormAssociatedCheckbox_base: typeof _Checkbox;
-
 /**
  * @beta
  */
@@ -4712,15 +5057,6 @@ declare class FormAssociatedSlider extends FormAssociatedSlider_base {
 
 declare const FormAssociatedSlider_base: typeof _Slider;
 
-/**
- * @beta
- */
-declare class FormAssociatedSwitch extends FormAssociatedSwitch_base {
-    proxy: HTMLInputElement;
-}
-
-declare const FormAssociatedSwitch_base: typeof _Switch;
-
 /**
  * Determines the current localization direction of an element.
  *
@@ -6381,6 +6717,17 @@ export declare const SliderStyles: ElementStyles;
 
 export declare const SliderTemplate: ElementViewTemplate<Slider>;
 
+/**
+ * Synthetic type for slotted input elements
+ * @public
+ */
+export declare type SlottableInput = HTMLElement & ElementInternals & {
+    elementInternals?: ElementInternals;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+};
+
 /**
  * CSS custom property value for the {@link @fluentui/tokens#spacingHorizontalL | `spacingHorizontalL`} design token.
  * @public
@@ -6655,49 +7002,7 @@ declare const styles: ElementStyles;
 export { styles as ButtonStyles }
 export { styles as MenuButtonStyles }
 
-export declare class Switch extends FormAssociatedSwitch {
-    /**
-     * The label position of the switch
-     *
-     * @public
-     * @remarks
-     * HTML Attribute: labelposition
-     */
-    labelPosition: SwitchLabelPosition | undefined;
-    /**
-     * 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.
-     * @public
-     * @remarks
-     * HTML Attribute: readonly
-     */
-    readOnly: boolean;
-    protected readOnlyChanged(): void;
-    /**
-     * The element's value to be included in form submission when checked.
-     * Default to "on" to reach parity with input[type="checkbox"]
-     *
-     * @internal
-     */
-    initialValue: string;
-    /**
-     * @internal
-     */
-    defaultSlottedNodes: Node[];
-    constructor();
-    /**
-     * @internal
-     */
-    keypressHandler: (e: KeyboardEvent) => void;
-    /**
-     * @internal
-     */
-    clickHandler: (e: MouseEvent) => void;
-}
-
-declare class _Switch extends FASTElement {
-}
-
-declare interface _Switch extends CheckableFormAssociated {
+export declare class Switch extends BaseCheckbox {
 }
 
 /**
@@ -7205,13 +7510,13 @@ export declare class TextInput extends FASTElement {
      * @remarks
      * HTML Attribute: `readonly`
      */
-    readonly?: boolean;
+    readOnly?: boolean;
     /**
      * Syncs the `ElementInternals.ariaReadOnly` property when the `readonly` property changes.
      *
      * @internal
      */
-    readonlyChanged(): void;
+    readOnlyChanged(): void;
     /**
      * The element's required attribute.
      *
@@ -7283,7 +7588,7 @@ export declare class TextInput extends FASTElement {
      *
      * @internal
      */
-    protected elementInternals: ElementInternals;
+    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}
@@ -7329,6 +7634,12 @@ export declare class TextInput extends FASTElement {
      * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/form | `ElementInternals.form`} property.
      */
     get form(): HTMLFormElement | null;
+    /**
+     * Handles the internal control's `keypress` event.
+     *
+     * @internal
+     */
+    beforeinputHandler(e: InputEvent): boolean | void;
     /**
      * Change event handler for inner control.
      *
@@ -7337,9 +7648,29 @@ export declare class TextInput extends FASTElement {
      * "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;
+    changeHandler(e: InputEvent): boolean | void;
+    /**
+     * Checks the validity of the element and returns the result.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/checkValidity | `HTMLInputElement.checkValidity()`} method.
+     */
+    checkValidity(): boolean;
+    /**
+     * Clicks the inner control when the component is clicked.
+     *
+     * @param e - the event object
+     */
+    clickHandler(e: MouseEvent): boolean | void;
     connectedCallback(): void;
-    disconnectedCallback(): void;
+    /**
+     * Focuses the inner control when the component is focused.
+     *
+     * @param e - the event object
+     * @public
+     */
+    focusinHandler(e: FocusEvent): boolean | void;
     /**
      * Resets the value to its initial value when the form is reset.
      *
@@ -7359,11 +7690,12 @@ export declare class TextInput extends FASTElement {
      */
     inputHandler(e: InputEvent): boolean | void;
     /**
-     * Handles the internal control's `keypress` event.
+     * Handles the internal control's `keydown` event.
      *
+     * @param e - the event object
      * @internal
      */
-    keypressHandler(e: KeyboardEvent): boolean | void;
+    keydownHandler(e: KeyboardEvent): boolean | void;
     /**
      * Selects all the text in the text field.
      *
@@ -7374,6 +7706,21 @@ export declare class TextInput extends FASTElement {
      *
      */
     select(): void;
+    /**
+     * Sets the custom validity message.
+     * @param message - The message to set
+     *
+     * @public
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * Reports the validity of the element.
+     *
+     * @public
+     * @remarks
+     * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/reportValidity | `HTMLInputElement.reportValidity()`} method.
+     */
+    reportValidity(): boolean;
     /**
      * Reflects the {@link https://developer.mozilla.org/docs/Web/API/ElementInternals/setFormValue | `ElementInternals.setFormValue()`} method.
      *
@@ -7389,7 +7736,7 @@ export declare class TextInput extends FASTElement {
      *
      * @internal
      */
-    setValidity(flags?: ValidityStateFlags, message?: string, anchor?: HTMLElement): void;
+    setValidity(flags?: Partial<ValidityState>, message?: string, anchor?: HTMLElement): void;
 }
 
 /**
@@ -7681,6 +8028,27 @@ export declare const typographyTitle2Styles: CSSDirective;
 
 export declare const typographyTitle3Styles: CSSDirective;
 
+/**
+ * Synthetic type for slotted message elements
+ * @public
+ */
+export declare const ValidationFlags: {
+    readonly badInput: "bad-input";
+    readonly customError: "custom-error";
+    readonly patternMismatch: "pattern-mismatch";
+    readonly rangeOverflow: "range-overflow";
+    readonly rangeUnderflow: "range-underflow";
+    readonly stepMismatch: "step-mismatch";
+    readonly tooLong: "too-long";
+    readonly tooShort: "too-short";
+    readonly typeMismatch: "type-mismatch";
+    readonly valueMissing: "value-missing";
+    readonly valid: "valid";
+};
+
+/** @public */
+export declare type ValidationFlags = ValuesOf<typeof ValidationFlags>;
+
 /**
  * Helper for enumerating a type from a const object
  * Example: export type Foo = ValuesOf\<typeof Foo\>