@fluentui/web-components 3.0.0-beta.8 → 3.0.0-beta.80

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

@@ -1,30 +1,44 @@
-import { CaptureType } from '@microsoft/fast-element';
+import { type CaptureType } from '@microsoft/fast-element';
 import type { StaticallyComposableHTML } from '../utils/index.js';
 /**
  * Start configuration options
  * @public
  */
-export declare type StartOptions<TSource = any, TParent = any> = {
+export type StartOptions<TSource = any, TParent = any> = {
     start?: StaticallyComposableHTML<TSource, TParent>;
 };
 /**
  * End configuration options
  * @public
  */
-export declare type EndOptions<TSource = any, TParent = any> = {
+export type EndOptions<TSource = any, TParent = any> = {
     end?: StaticallyComposableHTML<TSource, TParent>;
 };
 /**
  * Start/End configuration options
  * @public
  */
-export declare type StartEndOptions<TSource = any, TParent = any> = StartOptions<TSource, TParent> & EndOptions<TSource, TParent>;
+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/progress-bar/index.d.ts

@@ -1,5 +1,5 @@
-export * from './progress-bar.js';
-export * from './progress-bar.options.js';
 export { definition as ProgressBarDefinition } from './progress-bar.definition.js';
+export { BaseProgressBar, ProgressBar } from './progress-bar.js';
+export { ProgressBarShape, ProgressBarThickness, ProgressBarValidationState } from './progress-bar.options.js';
 export { styles as ProgressBarStyles } from './progress-bar.styles.js';
 export { template as ProgressBarTemplate } from './progress-bar.template.js';

package/dist/dts/progress-bar/progress-bar.bench.d.ts

@@ -0,0 +1,3 @@
+declare const itemRenderer: () => HTMLElement;
+export default itemRenderer;
+export { tests } from '../utils/benchmark-wrapper.js';

package/dist/dts/progress-bar/progress-bar.d.ts

@@ -1,37 +1,106 @@
-import { BaseProgress } from './base-progress.js';
+import { FASTElement } from '@microsoft/fast-element';
 import { ProgressBarShape, ProgressBarThickness, ProgressBarValidationState } from './progress-bar.options.js';
 /**
- * An Progress HTML Element.
+ * A Progress HTML Element.
  * Implements the {@link https://www.w3.org/TR/wai-aria-1.1/#progressbar | ARIA progressbar }.
  *
- * @slot indeterminate - The slot for a custom indeterminate indicator
- * @csspart progress - Represents the progress element
- * @csspart determinate - The determinate indicator
- * @csspart indeterminate - The indeterminate indicator
+ * @public
+ */
+export declare class BaseProgressBar extends FASTElement {
+    /**
+     * The internal {@link https://developer.mozilla.org/docs/Web/API/ElementInternals | `ElementInternals`} instance for the component.
+     *
+     * @internal
+     */
+    elementInternals: ElementInternals;
+    /**
+     * The validation state of the progress bar
+     * @public
+     * HTML Attribute: `validation-state`
+     */
+    validationState: ProgressBarValidationState | null;
+    /**
+     * Handles changes to validation-state attribute custom states
+     * @param prev - the previous state
+     * @param next - the next state
+     */
+    validationStateChanged(prev: ProgressBarValidationState | undefined, next: ProgressBarValidationState | undefined): void;
+    /**
+     * The value of the progress
+     * @internal
+     * HTML Attribute: `value`
+     */
+    value?: number;
+    /**
+     * Updates the percent complete when the `value` property changes.
+     *
+     * @internal
+     */
+    protected valueChanged(prev: number | undefined, next: number | undefined): void;
+    /**
+     * The minimum value
+     * @internal
+     * HTML Attribute: `min`
+     */
+    min?: number;
+    /**
+     * Updates the percent complete when the `min` property changes.
+     *
+     * @param prev - The previous min value
+     * @param next - The current min value
+     */
+    protected minChanged(prev: number | undefined, next: number | undefined): void;
+    /**
+     * The maximum value
+     * @internal
+     * HTML Attribute: `max`
+     */
+    max?: number;
+    /**
+     * Updates the percent complete when the `max` property changes.
+     *
+     * @param prev - The previous max value
+     * @param next - The current max value
+     * @internal
+     */
+    protected maxChanged(prev: number | undefined, next: number | undefined): void;
+    /**
+     * Indicates progress in %
+     * @internal
+     */
+    get percentComplete(): number;
+    constructor();
+}
+/**
+ * A Progress HTML Element.
+ * Based on BaseProgressBar and includes style and layout specific attributes
  *
  * @public
  */
-export declare class ProgressBar extends BaseProgress {
+export declare class ProgressBar extends BaseProgressBar {
     /**
      * The thickness of the progress bar
      *
      * @public
-     * @remarks
-     * HTML Attribute: thickness
+     * HTML Attribute: `thickness`
      */
     thickness?: ProgressBarThickness;
+    /**
+     * Handles changes to thickness attribute custom states
+     * @param prev - the previous state
+     * @param next - the next state
+     */
+    thicknessChanged(prev: ProgressBarThickness | undefined, next: ProgressBarThickness | undefined): void;
     /**
      * The shape of the progress bar
      * @public
-     * @remarks
-     * HTML Attribute: shape
+     * HTML Attribute: `shape`
      */
     shape?: ProgressBarShape;
     /**
-     * The validation state of the progress bar
-     * @public
-     * @remarks
-     * HTML Attribute: validation-state
+     * Handles changes to shape attribute custom states
+     * @param prev - the previous state
+     * @param next - the next state
      */
-    validationState: ProgressBarValidationState | null;
+    shapeChanged(prev: ProgressBarShape | undefined, next: ProgressBarShape | undefined): void;
 }

package/dist/dts/progress-bar/progress-bar.options.d.ts

@@ -1,5 +1,4 @@
-import type { StaticallyComposableHTML, ValuesOf } from '../utils/index.js';
-import { ProgressBar } from './progress-bar.js';
+import type { ValuesOf } from '../utils/index.js';
 /**
  * ProgressBarThickness Constants
  * @public
@@ -12,7 +11,7 @@ export declare const ProgressBarThickness: {
  * Applies bar thickness to the content
  * @public
  */
-export declare type ProgressBarThickness = ValuesOf<typeof ProgressBarThickness>;
+export type ProgressBarThickness = ValuesOf<typeof ProgressBarThickness>;
 /**
  * ProgressBarShape Constants
  * @public
@@ -25,7 +24,7 @@ export declare const ProgressBarShape: {
  * Applies bar shape to the content
  * @public
  */
-export declare type ProgressBarShape = ValuesOf<typeof ProgressBarShape>;
+export type ProgressBarShape = ValuesOf<typeof ProgressBarShape>;
 /**
  * ProgressBarValidationState Constants
  * @public
@@ -39,12 +38,4 @@ export declare const ProgressBarValidationState: {
  * Applies validation state to the content
  * @public
  */
-export declare type ProgressBarValidationState = ValuesOf<typeof ProgressBarValidationState>;
-/**
- * Progress configuration options
- * @public
- */
-export declare type ProgressOptions = {
-    indeterminateIndicator1?: StaticallyComposableHTML<ProgressBar>;
-    indeterminateIndicator2?: StaticallyComposableHTML<ProgressBar>;
-};
+export type ProgressBarValidationState = ValuesOf<typeof ProgressBarValidationState>;

package/dist/dts/progress-bar/progress-bar.template.d.ts

@@ -1,5 +1,4 @@
 import type { ElementViewTemplate } from '@microsoft/fast-element';
-import type { ProgressOptions } from './progress-bar.options.js';
 import type { ProgressBar } from './progress-bar.js';
-export declare function progressTemplate<T extends ProgressBar>(options?: ProgressOptions): ElementViewTemplate<T>;
+export declare function progressTemplate<T extends ProgressBar>(): ElementViewTemplate<T>;
 export declare const template: ElementViewTemplate<ProgressBar>;

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

@@ -1,4 +1,5 @@
-export * from './radio.js';
 export { definition as RadioDefinition } from './radio.definition.js';
+export { Radio } from './radio.js';
+export type { RadioControl, RadioOptions } from './radio.options.js';
 export { styles as RadioStyles } from './radio.styles.js';
 export { template as RadioTemplate } from './radio.template.js';

package/dist/dts/radio/radio.bench.d.ts

@@ -0,0 +1,3 @@
+declare const itemRenderer: () => HTMLElement;
+export default itemRenderer;
+export { tests } from '../utils/benchmark-wrapper.js';

package/dist/dts/radio/radio.d.ts

@@ -1,58 +1,61 @@
-import type { StaticallyComposableHTML } from '../utils/template-helpers.js';
-import { FormAssociatedRadio } from './radio.form-associated.js';
-/**
- * @public
- */
-export declare type RadioControl = Pick<HTMLInputElement, 'checked' | 'disabled' | 'focus' | 'setAttribute' | 'getAttribute'>;
-/**
- * Radio configuration options
- * @public
- */
-export declare type RadioOptions = {
-    checkedIndicator?: StaticallyComposableHTML<Radio>;
-};
+import { BaseCheckbox } from '../checkbox/checkbox.js';
 /**
  * A Radio Custom HTML Element.
- * Implements the {@link https://www.w3.org/TR/wai-aria-1.1/#radio | ARIA radio }.
+ * Implements the {@link https://w3c.github.io/aria/#radio | ARIA `radio` role}.
  *
- * @slot checked-indicator - The checked indicator
- * @slot - The default slot for the label
- * @csspart control - The element representing the visual radio control
- * @csspart label - The label
+ * @slot checked-indicator - The checked indicator slot
  * @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
  */
-export declare class Radio extends FormAssociatedRadio implements RadioControl {
-    /**
-     * The name of the radio. See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname | name attribute} for more info.
-     */
-    name: string;
+export declare class Radio extends BaseCheckbox {
+    connectedCallback(): void;
+    constructor();
     /**
-     * The element's value to be included in form submission when checked.
-     * Default to "on" to reach parity with input[type="radio"]
+     * Toggles the disabled state when the user changes the `disabled` property.
      *
+     * @param prev - the previous value of the `disabled` property
+     * @param next - the current value of the `disabled` property
      * @internal
+     * @override
      */
-    initialValue: string;
+    protected disabledChanged(prev: boolean | undefined, next: boolean | undefined): void;
     /**
+     * This method is a no-op for the radio component.
+     *
      * @internal
+     * @override
+     * @remarks
+     * To make a group of radio controls required, see {@link RadioGroup.required}.
      */
-    defaultSlottedNodes: Node[];
-    private get radioGroup();
+    protected requiredChanged(): void;
     /**
+     * This method is a no-op for the radio component.
+     *
      * @internal
+     * @override
+     * @remarks
+     * The radio form value is controlled by the `RadioGroup` component.
      */
-    defaultCheckedChanged(): void;
-    constructor();
+    setFormValue(): void;
     /**
+     * Sets the validity of the control.
+     *
      * @internal
+     * @override
+     * @remarks
+     * The radio component does not have a `required` attribute, so this method always sets the validity to `true`.
      */
-    connectedCallback(): void;
-    private isInsideRadioGroup;
+    setValidity(): void;
     /**
-     * Handles key presses on the radio.
-     * @beta
+     * Toggles the checked state of the control.
+     *
+     * @param force - Forces the element to be checked or unchecked
+     * @public
+     * @override
+     * @remarks
+     * The radio checked state is controlled by the `RadioGroup` component, so the `force` parameter defaults to `true`.
      */
-    keypressHandler(e: KeyboardEvent): boolean | void;
+    toggleChecked(force?: boolean): void;
 }

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

@@ -0,0 +1,14 @@
+import type { StaticallyComposableHTML } from '../utils/template-helpers.js';
+import type { Radio } from './radio.js';
+/**
+ * @public
+ */
+export type RadioControl = Pick<HTMLInputElement, 'checked' | 'disabled' | 'focus' | 'setAttribute' | 'getAttribute'>;
+/**
+ * Radio configuration options
+ * @public
+ */
+export type RadioOptions = {
+    checkedIndicator?: StaticallyComposableHTML<Radio>;
+};
+export type { CheckboxSize as RadioSize } from '../checkbox/checkbox.options.js';