@material/web 1.0.1 → 1.0.2-nightly.8eb1f30.0

package/labs/behaviors/form-associated.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LitElement } from 'lit';
+import { WithElementInternals } from './element-internals.js';
+import { MixinBase, MixinReturn } from './mixin.js';
+/**
+ * A form-associated element.
+ *
+ * IMPORTANT: Requires declares for lit-analyzer
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ * class MyControl extends base {
+ *   // Writable mixin properties for lit-html binding, needed for lit-analyzer
+ *   declare disabled: boolean;
+ *   declare name: string;
+ * }
+ * ```
+ */
+export interface FormAssociated {
+    /**
+     * The associated form element with which this element's value will submit.
+     */
+    readonly form: HTMLFormElement | null;
+    /**
+     * The labels this element is associated with.
+     */
+    readonly labels: NodeList;
+    /**
+     * The HTML name to use in form submission.
+     */
+    name: string;
+    /**
+     * Whether or not the element is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Gets the current form value of a component.
+     *
+     * @return The current form value.
+     */
+    [getFormValue](): FormValue | null;
+    /**
+     * Gets the current form state of a component. Defaults to the component's
+     * `[formValue]`.
+     *
+     * Use this when the state of an element is different from its value, such as
+     * checkboxes (internal boolean state and a user string value).
+     *
+     * @return The current form state, defaults to the form value.
+     */
+    [getFormState](): FormValue | null;
+    /**
+     * A callback for when a form component should be disabled or enabled. This
+     * can be called in a variety of situations, such as disabled `<fieldset>`s.
+     *
+     * @param disabled Whether or not the form control should be disabled.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /**
+     * A callback for when the form requests to reset its value. Typically, the
+     * default value that is reset is represented in the attribute of an element.
+     *
+     * This means the attribute used for the value should not update as the value
+     * changes. For example, a checkbox should not change its default `checked`
+     * attribute when selected. Ensure form values do not reflect.
+     */
+    formResetCallback(): void;
+    /**
+     * A callback for when the form restores the state of a component. For
+     * example, when a page is reloaded or forms are autofilled.
+     *
+     * @param state The state to restore, or null to reset the form control's
+     *     value.
+     * @param reason The reason state was restored, either `'restore'` or
+     *   `'autocomplete'`.
+     */
+    formStateRestoreCallback(state: FormRestoreState | null, reason: FormRestoreReason): void;
+    /**
+     * An optional callback for when the associated form changes.
+     *
+     * @param form The new associated form, or `null` if there is none.
+     */
+    formAssociatedCallback?(form: HTMLFormElement | null): void;
+}
+/**
+ * The constructor of a `FormAssociated` element.
+ */
+export interface FormAssociatedConstructor {
+    /**
+     * Indicates that an element is participating in form association.
+     */
+    readonly formAssociated: true;
+}
+/**
+ * A symbol property to retrieve the form value for an element.
+ */
+export declare const getFormValue: unique symbol;
+/**
+ * A symbol property to retrieve the form state for an element.
+ */
+export declare const getFormState: unique symbol;
+/**
+ * Mixes in form-associated behavior for a class. This allows an element to add
+ * values to `<form>` elements.
+ *
+ * Implementing classes should provide a `[formValue]` to return the current
+ * value of the element, as well as reset and restore callbacks.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ *
+ * class MyControl extends base {
+ *   \@property()
+ *   value = '';
+ *
+ *   override [getFormValue]() {
+ *     return this.value;
+ *   }
+ *
+ *   override formResetCallback() {
+ *     const defaultValue = this.getAttribute('value');
+ *     this.value = defaultValue;
+ *   }
+ *
+ *   override formStateRestoreCallback(state: string) {
+ *     this.value = state;
+ *   }
+ * }
+ * ```
+ *
+ * Elements may optionally provide a `[formState]` if their values do not
+ * represent the state of the component.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ *
+ * class MyCheckbox extends base {
+ *   \@property()
+ *   value = 'on';
+ *
+ *   \@property({type: Boolean})
+ *   checked = false;
+ *
+ *   override [getFormValue]() {
+ *     return this.checked ? this.value : null;
+ *   }
+ *
+ *   override [getFormState]() {
+ *     return String(this.checked);
+ *   }
+ *
+ *   override formResetCallback() {
+ *     const defaultValue = this.hasAttribute('checked');
+ *     this.checked = defaultValue;
+ *   }
+ *
+ *   override formStateRestoreCallback(state: string) {
+ *     this.checked = Boolean(state);
+ *   }
+ * }
+ * ```
+ *
+ * IMPORTANT: Requires declares for lit-analyzer
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ * class MyControl extends base {
+ *   // Writable mixin properties for lit-html binding, needed for lit-analyzer
+ *   declare disabled: boolean;
+ *   declare name: string;
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into. The base class must use
+ *     `mixinElementInternals()`.
+ * @return The provided class with `FormAssociated` mixed in.
+ */
+export declare function mixinFormAssociated<T extends MixinBase<LitElement & WithElementInternals>>(base: T): MixinReturn<T & FormAssociatedConstructor, FormAssociated>;
+/**
+ * A value that can be provided for form submission and state.
+ */
+export type FormValue = File | string | FormData;
+/**
+ * A value to be restored for a component's form value. If a component's form
+ * state is a `FormData` object, its entry list of name and values will be
+ * provided.
+ */
+export type FormRestoreState = File | string | Array<[string, FormDataEntryValue]>;
+/**
+ * The reason a form component is being restored for, either `'restore'` for
+ * browser restoration or `'autocomplete'` for restoring user values.
+ */
+export type FormRestoreReason = 'restore' | 'autocomplete';

package/labs/behaviors/form-associated.js

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { __decorate } from "tslib";
+import { property } from 'lit/decorators.js';
+import { internals } from './element-internals.js';
+/**
+ * A symbol property to retrieve the form value for an element.
+ */
+export const getFormValue = Symbol('getFormValue');
+/**
+ * A symbol property to retrieve the form state for an element.
+ */
+export const getFormState = Symbol('getFormState');
+/**
+ * Mixes in form-associated behavior for a class. This allows an element to add
+ * values to `<form>` elements.
+ *
+ * Implementing classes should provide a `[formValue]` to return the current
+ * value of the element, as well as reset and restore callbacks.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ *
+ * class MyControl extends base {
+ *   \@property()
+ *   value = '';
+ *
+ *   override [getFormValue]() {
+ *     return this.value;
+ *   }
+ *
+ *   override formResetCallback() {
+ *     const defaultValue = this.getAttribute('value');
+ *     this.value = defaultValue;
+ *   }
+ *
+ *   override formStateRestoreCallback(state: string) {
+ *     this.value = state;
+ *   }
+ * }
+ * ```
+ *
+ * Elements may optionally provide a `[formState]` if their values do not
+ * represent the state of the component.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ *
+ * class MyCheckbox extends base {
+ *   \@property()
+ *   value = 'on';
+ *
+ *   \@property({type: Boolean})
+ *   checked = false;
+ *
+ *   override [getFormValue]() {
+ *     return this.checked ? this.value : null;
+ *   }
+ *
+ *   override [getFormState]() {
+ *     return String(this.checked);
+ *   }
+ *
+ *   override formResetCallback() {
+ *     const defaultValue = this.hasAttribute('checked');
+ *     this.checked = defaultValue;
+ *   }
+ *
+ *   override formStateRestoreCallback(state: string) {
+ *     this.checked = Boolean(state);
+ *   }
+ * }
+ * ```
+ *
+ * IMPORTANT: Requires declares for lit-analyzer
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ * class MyControl extends base {
+ *   // Writable mixin properties for lit-html binding, needed for lit-analyzer
+ *   declare disabled: boolean;
+ *   declare name: string;
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into. The base class must use
+ *     `mixinElementInternals()`.
+ * @return The provided class with `FormAssociated` mixed in.
+ */
+export function mixinFormAssociated(base) {
+    class FormAssociatedElement extends base {
+        get form() {
+            return this[internals].form;
+        }
+        get labels() {
+            return this[internals].labels;
+        }
+        // name attribute must be set synchronously
+        get name() {
+            return this.getAttribute('name') ?? '';
+        }
+        set name(name) {
+            const prev = this.name;
+            // Setting name to null or empty string does not remove the attribute.
+            this.setAttribute('name', name);
+            // Explicit requestUpdate needed for Lit 2.0
+            this.requestUpdate('name', prev);
+        }
+        // disabled attribute must be set synchronously
+        get disabled() {
+            return this.hasAttribute('disabled');
+        }
+        set disabled(disabled) {
+            const prev = this.disabled;
+            this.toggleAttribute('disabled', disabled);
+            // Explicit requestUpdate needed for Lit 2.0
+            this.requestUpdate('disabled', prev);
+        }
+        requestUpdate(name, oldValue, options) {
+            super.requestUpdate(name, oldValue, options);
+            // If any properties change, update the form value, which may have changed
+            // as well.
+            // Update the form value synchronously in `requestUpdate()` rather than
+            // `update()` or `updated()`, which are async. This is necessary to ensure
+            // that form data is updated in time for synchronous event listeners.
+            this[internals].setFormValue(this[getFormValue](), this[getFormState]());
+        }
+        [getFormValue]() {
+            // Closure does not allow abstract symbol members, so a default
+            // implementation is needed.
+            throw new Error('Implement [getFormValue]');
+        }
+        [getFormState]() {
+            return this[getFormValue]();
+        }
+        formDisabledCallback(disabled) {
+            this.disabled = disabled;
+        }
+    }
+    /** @nocollapse */
+    FormAssociatedElement.formAssociated = true;
+    __decorate([
+        property({ reflect: true })
+    ], FormAssociatedElement.prototype, "name", null);
+    __decorate([
+        property({ type: Boolean, reflect: true })
+    ], FormAssociatedElement.prototype, "disabled", null);
+    return FormAssociatedElement;
+}
+//# sourceMappingURL=form-associated.js.map

package/labs/behaviors/form-associated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-associated.js","sourceRoot":"","sources":["form-associated.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;AAGH,OAAO,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EAAC,SAAS,EAAuB,MAAM,wBAAwB,CAAC;AA0GvE;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,MAAM,UAAU,mBAAmB,CAEjC,IAAO;IACP,MAAe,qBAAsB,SAAQ,IAAI;QAI/C,IAAI,IAAI;YACN,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC;QAC9B,CAAC;QAED,IAAI,MAAM;YACR,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;QAChC,CAAC;QAED,2CAA2C;QAE3C,IAAI,IAAI;YACN,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACzC,CAAC;QACD,IAAI,IAAI,CAAC,IAAY;YACnB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,sEAAsE;YACtE,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAChC,4CAA4C;YAC5C,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QAED,+CAA+C;QAE/C,IAAI,QAAQ;YACV,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,QAAQ,CAAC,QAAiB;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC3B,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC3C,4CAA4C;YAC5C,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACvC,CAAC;QAEQ,aAAa,CACpB,IAAkB,EAClB,QAAkB,EAClB,OAA6B;YAE7B,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC7C,0EAA0E;YAC1E,WAAW;YACX,uEAAuE;YACvE,0EAA0E;YAC1E,qEAAqE;YACrE,IAAI,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;QAED,CAAC,YAAY,CAAC;YACZ,+DAA+D;YAC/D,4BAA4B;YAC5B,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC9C,CAAC;QAED,CAAC,YAAY,CAAC;YACZ,OAAO,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,CAAC;QAED,oBAAoB,CAAC,QAAiB;YACpC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC3B,CAAC;;IA9DD,kBAAkB;IACF,oCAAc,GAAG,IAAI,CAAC;IAYtC;QADC,QAAQ,CAAC,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC;qDAGzB;IAWD;QADC,QAAQ,CAAC,EAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAC,CAAC;yDAGxC;IA4CH,OAAO,qBAAqB,CAAC;AAC/B,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {LitElement, PropertyDeclaration} from 'lit';\nimport {property} from 'lit/decorators.js';\n\nimport {internals, WithElementInternals} from './element-internals.js';\nimport {MixinBase, MixinReturn} from './mixin.js';\n\n/**\n * A form-associated element.\n *\n * IMPORTANT: Requires declares for lit-analyzer\n * @example\n * ```ts\n * const base = mixinFormAssociated(mixinElementInternals(LitElement));\n * class MyControl extends base {\n *   // Writable mixin properties for lit-html binding, needed for lit-analyzer\n *   declare disabled: boolean;\n *   declare name: string;\n * }\n * ```\n */\nexport interface FormAssociated {\n  /**\n   * The associated form element with which this element's value will submit.\n   */\n  readonly form: HTMLFormElement | null;\n\n  /**\n   * The labels this element is associated with.\n   */\n  readonly labels: NodeList;\n\n  /**\n   * The HTML name to use in form submission.\n   */\n  name: string;\n\n  /**\n   * Whether or not the element is disabled.\n   */\n  disabled: boolean;\n\n  /**\n   * Gets the current form value of a component.\n   *\n   * @return The current form value.\n   */\n  [getFormValue](): FormValue | null;\n\n  /**\n   * Gets the current form state of a component. Defaults to the component's\n   * `[formValue]`.\n   *\n   * Use this when the state of an element is different from its value, such as\n   * checkboxes (internal boolean state and a user string value).\n   *\n   * @return The current form state, defaults to the form value.\n   */\n  [getFormState](): FormValue | null;\n\n  /**\n   * A callback for when a form component should be disabled or enabled. This\n   * can be called in a variety of situations, such as disabled `<fieldset>`s.\n   *\n   * @param disabled Whether or not the form control should be disabled.\n   */\n  formDisabledCallback(disabled: boolean): void;\n\n  /**\n   * A callback for when the form requests to reset its value. Typically, the\n   * default value that is reset is represented in the attribute of an element.\n   *\n   * This means the attribute used for the value should not update as the value\n   * changes. For example, a checkbox should not change its default `checked`\n   * attribute when selected. Ensure form values do not reflect.\n   */\n  formResetCallback(): void;\n\n  /**\n   * A callback for when the form restores the state of a component. For\n   * example, when a page is reloaded or forms are autofilled.\n   *\n   * @param state The state to restore, or null to reset the form control's\n   *     value.\n   * @param reason The reason state was restored, either `'restore'` or\n   *   `'autocomplete'`.\n   */\n  formStateRestoreCallback(\n    state: FormRestoreState | null,\n    reason: FormRestoreReason,\n  ): void;\n\n  /**\n   * An optional callback for when the associated form changes.\n   *\n   * @param form The new associated form, or `null` if there is none.\n   */\n  formAssociatedCallback?(form: HTMLFormElement | null): void;\n}\n\n/**\n * The constructor of a `FormAssociated` element.\n */\nexport interface FormAssociatedConstructor {\n  /**\n   * Indicates that an element is participating in form association.\n   */\n  readonly formAssociated: true;\n}\n\n/**\n * A symbol property to retrieve the form value for an element.\n */\nexport const getFormValue = Symbol('getFormValue');\n\n/**\n * A symbol property to retrieve the form state for an element.\n */\nexport const getFormState = Symbol('getFormState');\n\n/**\n * Mixes in form-associated behavior for a class. This allows an element to add\n * values to `<form>` elements.\n *\n * Implementing classes should provide a `[formValue]` to return the current\n * value of the element, as well as reset and restore callbacks.\n *\n * @example\n * ```ts\n * const base = mixinFormAssociated(mixinElementInternals(LitElement));\n *\n * class MyControl extends base {\n *   \\@property()\n *   value = '';\n *\n *   override [getFormValue]() {\n *     return this.value;\n *   }\n *\n *   override formResetCallback() {\n *     const defaultValue = this.getAttribute('value');\n *     this.value = defaultValue;\n *   }\n *\n *   override formStateRestoreCallback(state: string) {\n *     this.value = state;\n *   }\n * }\n * ```\n *\n * Elements may optionally provide a `[formState]` if their values do not\n * represent the state of the component.\n *\n * @example\n * ```ts\n * const base = mixinFormAssociated(mixinElementInternals(LitElement));\n *\n * class MyCheckbox extends base {\n *   \\@property()\n *   value = 'on';\n *\n *   \\@property({type: Boolean})\n *   checked = false;\n *\n *   override [getFormValue]() {\n *     return this.checked ? this.value : null;\n *   }\n *\n *   override [getFormState]() {\n *     return String(this.checked);\n *   }\n *\n *   override formResetCallback() {\n *     const defaultValue = this.hasAttribute('checked');\n *     this.checked = defaultValue;\n *   }\n *\n *   override formStateRestoreCallback(state: string) {\n *     this.checked = Boolean(state);\n *   }\n * }\n * ```\n *\n * IMPORTANT: Requires declares for lit-analyzer\n * @example\n * ```ts\n * const base = mixinFormAssociated(mixinElementInternals(LitElement));\n * class MyControl extends base {\n *   // Writable mixin properties for lit-html binding, needed for lit-analyzer\n *   declare disabled: boolean;\n *   declare name: string;\n * }\n * ```\n *\n * @param base The class to mix functionality into. The base class must use\n *     `mixinElementInternals()`.\n * @return The provided class with `FormAssociated` mixed in.\n */\nexport function mixinFormAssociated<\n  T extends MixinBase<LitElement & WithElementInternals>,\n>(base: T): MixinReturn<T & FormAssociatedConstructor, FormAssociated> {\n  abstract class FormAssociatedElement extends base implements FormAssociated {\n    /** @nocollapse */\n    static readonly formAssociated = true;\n\n    get form() {\n      return this[internals].form;\n    }\n\n    get labels() {\n      return this[internals].labels;\n    }\n\n    // name attribute must be set synchronously\n    @property({reflect: true})\n    get name() {\n      return this.getAttribute('name') ?? '';\n    }\n    set name(name: string) {\n      const prev = this.name;\n      // Setting name to null or empty string does not remove the attribute.\n      this.setAttribute('name', name);\n      // Explicit requestUpdate needed for Lit 2.0\n      this.requestUpdate('name', prev);\n    }\n\n    // disabled attribute must be set synchronously\n    @property({type: Boolean, reflect: true})\n    get disabled() {\n      return this.hasAttribute('disabled');\n    }\n    set disabled(disabled: boolean) {\n      const prev = this.disabled;\n      this.toggleAttribute('disabled', disabled);\n      // Explicit requestUpdate needed for Lit 2.0\n      this.requestUpdate('disabled', prev);\n    }\n\n    override requestUpdate(\n      name?: PropertyKey,\n      oldValue?: unknown,\n      options?: PropertyDeclaration,\n    ) {\n      super.requestUpdate(name, oldValue, options);\n      // If any properties change, update the form value, which may have changed\n      // as well.\n      // Update the form value synchronously in `requestUpdate()` rather than\n      // `update()` or `updated()`, which are async. This is necessary to ensure\n      // that form data is updated in time for synchronous event listeners.\n      this[internals].setFormValue(this[getFormValue](), this[getFormState]());\n    }\n\n    [getFormValue](): FormValue | null {\n      // Closure does not allow abstract symbol members, so a default\n      // implementation is needed.\n      throw new Error('Implement [getFormValue]');\n    }\n\n    [getFormState](): FormValue | null {\n      return this[getFormValue]();\n    }\n\n    formDisabledCallback(disabled: boolean) {\n      this.disabled = disabled;\n    }\n\n    abstract formResetCallback(): void;\n\n    abstract formStateRestoreCallback(\n      state: FormRestoreState | null,\n      reason: FormRestoreReason,\n    ): void;\n  }\n\n  return FormAssociatedElement;\n}\n\n/**\n * A value that can be provided for form submission and state.\n */\nexport type FormValue = File | string | FormData;\n\n/**\n * A value to be restored for a component's form value. If a component's form\n * state is a `FormData` object, its entry list of name and values will be\n * provided.\n */\nexport type FormRestoreState =\n  | File\n  | string\n  | Array<[string, FormDataEntryValue]>;\n\n/**\n * The reason a form component is being restored for, either `'restore'` for\n * browser restoration or `'autocomplete'` for restoring user values.\n */\nexport type FormRestoreReason = 'restore' | 'autocomplete';\n"]}

package/labs/behaviors/mixin.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The base class for a mixin with an optional expected base class type.
+ *
+ * @template ExpectedBase Optional expected base class type, such as
+ *     `LitElement`.
+ *
+ * @example
+ * ```ts
+ * interface Foo {
+ *   isFoo: boolean;
+ * }
+ *
+ * function mixinFoo<T extends MixinBase>(base: T): MixinReturn<T, Foo> {
+ *   // Mixins must be `abstract`
+ *   abstract class FooImpl extends base implements Foo {
+ *     isFoo = true;
+ *   }
+ *
+ *   return FooImpl;
+ * }
+ * ```
+ */
+export type MixinBase<ExpectedBase = object> = abstract new (...args: any[]) => ExpectedBase;
+/**
+ * The return value of a mixin.
+ *
+ * @template MixinBase The generic that extends `MixinBase` used for the mixin's
+ *     base class argument.
+ * @template MixinClass Optional interface of fuctionality that was mixed in.
+ *     Omit if no additional APIs were added (such as purely overriding base
+ *     class functionality).
+ *
+ * @example
+ * ```ts
+ * interface Foo {
+ *   isFoo: boolean;
+ * }
+ *
+ * // Mixins must be `abstract`
+ * function mixinFoo<T extends MixinBase>(base: T): MixinReturn<T, Foo> {
+ *   abstract class FooImpl extends base implements Foo {
+ *     isFoo = true;
+ *   }
+ *
+ *   return FooImpl;
+ * }
+ * ```
+ */
+export type MixinReturn<MixinBase, MixinClass = object> = (abstract new (...args: any[]) => MixinClass) & MixinBase;

package/labs/behaviors/mixin.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=mixin.js.map

package/labs/behaviors/mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixin.js","sourceRoot":"","sources":["mixin.ts"],"names":[],"mappings":"AAAA;;;;GAIG","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/**\n * The base class for a mixin with an optional expected base class type.\n *\n * @template ExpectedBase Optional expected base class type, such as\n *     `LitElement`.\n *\n * @example\n * ```ts\n * interface Foo {\n *   isFoo: boolean;\n * }\n *\n * function mixinFoo<T extends MixinBase>(base: T): MixinReturn<T, Foo> {\n *   // Mixins must be `abstract`\n *   abstract class FooImpl extends base implements Foo {\n *     isFoo = true;\n *   }\n *\n *   return FooImpl;\n * }\n * ```\n */\nexport type MixinBase<ExpectedBase = object> = abstract new (\n  // Mixins must have a constructor with `...args: any[]`\n  // tslint:disable-next-line:no-any\n  ...args: any[]\n) => ExpectedBase;\n\n/**\n * The return value of a mixin.\n *\n * @template MixinBase The generic that extends `MixinBase` used for the mixin's\n *     base class argument.\n * @template MixinClass Optional interface of fuctionality that was mixed in.\n *     Omit if no additional APIs were added (such as purely overriding base\n *     class functionality).\n *\n * @example\n * ```ts\n * interface Foo {\n *   isFoo: boolean;\n * }\n *\n * // Mixins must be `abstract`\n * function mixinFoo<T extends MixinBase>(base: T): MixinReturn<T, Foo> {\n *   abstract class FooImpl extends base implements Foo {\n *     isFoo = true;\n *   }\n *\n *   return FooImpl;\n * }\n * ```\n */\nexport type MixinReturn<MixinBase, MixinClass = object> =\n  // Mixins must have a constructor with `...args: any[]`\n  // tslint:disable-next-line:no-any\n  (abstract new (...args: any[]) => MixinClass) & MixinBase;\n"]}

package/labs/behaviors/validators/checkbox-validator.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Validator } from './validator.js';
+/**
+ * Constraint validation properties for a checkbox.
+ */
+export interface CheckboxState {
+    /**
+     * Whether the checkbox is checked.
+     */
+    checked: boolean;
+    /**
+     * Whether the checkbox is required.
+     */
+    required: boolean;
+}
+/**
+ * A validator that provides constraint validation that emulates
+ * `<input type="checkbox">` validation.
+ */
+export declare class CheckboxValidator extends Validator<CheckboxState> {
+    private checkboxControl?;
+    protected computeValidity(state: CheckboxState): {
+        validity: ValidityState;
+        validationMessage: string;
+    };
+    protected equals(prev: CheckboxState, next: CheckboxState): boolean;
+    protected copy({ checked, required }: CheckboxState): CheckboxState;
+}

package/labs/behaviors/validators/checkbox-validator.js

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Validator } from './validator.js';
+/**
+ * A validator that provides constraint validation that emulates
+ * `<input type="checkbox">` validation.
+ */
+export class CheckboxValidator extends Validator {
+    computeValidity(state) {
+        if (!this.checkboxControl) {
+            // Lazily create the platform input
+            this.checkboxControl = document.createElement('input');
+            this.checkboxControl.type = 'checkbox';
+        }
+        this.checkboxControl.checked = state.checked;
+        this.checkboxControl.required = state.required;
+        return {
+            validity: this.checkboxControl.validity,
+            validationMessage: this.checkboxControl.validationMessage,
+        };
+    }
+    equals(prev, next) {
+        return prev.checked === next.checked && prev.required === next.required;
+    }
+    copy({ checked, required }) {
+        return { checked, required };
+    }
+}
+//# sourceMappingURL=checkbox-validator.js.map

package/labs/behaviors/validators/checkbox-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkbox-validator.js","sourceRoot":"","sources":["checkbox-validator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAiBzC;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,SAAwB;IAG1C,eAAe,CAAC,KAAoB;QACrD,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACzB,mCAAmC;YACnC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACvD,IAAI,CAAC,eAAe,CAAC,IAAI,GAAG,UAAU,CAAC;SACxC;QAED,IAAI,CAAC,eAAe,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC7C,IAAI,CAAC,eAAe,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/C,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,QAAQ;YACvC,iBAAiB,EAAE,IAAI,CAAC,eAAe,CAAC,iBAAiB;SAC1D,CAAC;IACJ,CAAC;IAEkB,MAAM,CAAC,IAAmB,EAAE,IAAmB;QAChE,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC;IAC1E,CAAC;IAEkB,IAAI,CAAC,EAAC,OAAO,EAAE,QAAQ,EAAgB;QACxD,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAC,CAAC;IAC7B,CAAC;CACF","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {Validator} from './validator.js';\n\n/**\n * Constraint validation properties for a checkbox.\n */\nexport interface CheckboxState {\n  /**\n   * Whether the checkbox is checked.\n   */\n  checked: boolean;\n\n  /**\n   * Whether the checkbox is required.\n   */\n  required: boolean;\n}\n\n/**\n * A validator that provides constraint validation that emulates\n * `<input type=\"checkbox\">` validation.\n */\nexport class CheckboxValidator extends Validator<CheckboxState> {\n  private checkboxControl?: HTMLInputElement;\n\n  protected override computeValidity(state: CheckboxState) {\n    if (!this.checkboxControl) {\n      // Lazily create the platform input\n      this.checkboxControl = document.createElement('input');\n      this.checkboxControl.type = 'checkbox';\n    }\n\n    this.checkboxControl.checked = state.checked;\n    this.checkboxControl.required = state.required;\n    return {\n      validity: this.checkboxControl.validity,\n      validationMessage: this.checkboxControl.validationMessage,\n    };\n  }\n\n  protected override equals(prev: CheckboxState, next: CheckboxState) {\n    return prev.checked === next.checked && prev.required === next.required;\n  }\n\n  protected override copy({checked, required}: CheckboxState): CheckboxState {\n    return {checked, required};\n  }\n}\n"]}

package/labs/behaviors/validators/validator.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A class that computes and caches `ValidityStateFlags` for a component with
+ * a given `State` interface.
+ *
+ * Cached performance before computing validity is important since constraint
+ * validation must be checked frequently and synchronously when properties
+ * change.
+ *
+ * @template State The expected interface of properties relevant to constraint
+ *     validation.
+ */
+export declare abstract class Validator<State> {
+    private readonly getCurrentState;
+    /**
+     * The previous state, used to determine if state changed and validation needs
+     * to be re-computed.
+     */
+    private prevState?;
+    /**
+     * The current validity state and message. This is cached and returns if
+     * constraint validation state does not change.
+     */
+    private currentValidity;
+    /**
+     * Creates a new validator.
+     *
+     * @param getCurrentState A callback that returns the current state of
+     *     constraint validation-related properties.
+     */
+    constructor(getCurrentState: () => State);
+    /**
+     * Returns the current `ValidityStateFlags` and validation message for the
+     * validator.
+     *
+     * If the constraint validation state has not changed, this will return a
+     * cached result. This is important since `getValidity()` can be called
+     * frequently in response to synchronous property changes.
+     *
+     * @return The current validity and validation message.
+     */
+    getValidity(): ValidityAndMessage;
+    /**
+     * Computes the `ValidityStateFlags` and validation message for a given set
+     * of constraint validation properties.
+     *
+     * Implementations can use platform elements like `<input>` and `<select>` to
+     * sync state and compute validation along with i18n'd messages. This function
+     * may be expensive, and is only called when state changes.
+     *
+     * @param state The new state of constraint validation properties.
+     * @return An object containing a `validity` property with
+     *     `ValidityStateFlags` and a `validationMessage` property.
+     */
+    protected abstract computeValidity(state: State): ValidityAndMessage;
+    /**
+     * Checks if two states are equal. This is used to check against cached state
+     * to see if validity needs to be re-computed.
+     *
+     * @param prev The previous state.
+     * @param next The next state.
+     * @return True if the states are equal, or false if not.
+     */
+    protected abstract equals(prev: State, next: State): boolean;
+    /**
+     * Creates a copy of a state. This is used to cache state and check if it
+     * changes.
+     *
+     * @param state The state to copy.
+     * @return A copy of the state.
+     */
+    protected abstract copy(state: State): State;
+}
+/**
+ * An object containing `ValidityStateFlags` and a corresponding validation
+ * message.
+ */
+export interface ValidityAndMessage {
+    /**
+     * Validity flags.
+     */
+    validity: ValidityStateFlags;
+    /**
+     * The validation message for the associated flags. It may not be an empty
+     * string if any of the validity flags are `true`.
+     */
+    validationMessage: string;
+}

package/labs/behaviors/validators/validator.js

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A class that computes and caches `ValidityStateFlags` for a component with
+ * a given `State` interface.
+ *
+ * Cached performance before computing validity is important since constraint
+ * validation must be checked frequently and synchronously when properties
+ * change.
+ *
+ * @template State The expected interface of properties relevant to constraint
+ *     validation.
+ */
+export class Validator {
+    /**
+     * Creates a new validator.
+     *
+     * @param getCurrentState A callback that returns the current state of
+     *     constraint validation-related properties.
+     */
+    constructor(getCurrentState) {
+        this.getCurrentState = getCurrentState;
+        /**
+         * The current validity state and message. This is cached and returns if
+         * constraint validation state does not change.
+         */
+        this.currentValidity = {
+            validity: {},
+            validationMessage: '',
+        };
+    }
+    /**
+     * Returns the current `ValidityStateFlags` and validation message for the
+     * validator.
+     *
+     * If the constraint validation state has not changed, this will return a
+     * cached result. This is important since `getValidity()` can be called
+     * frequently in response to synchronous property changes.
+     *
+     * @return The current validity and validation message.
+     */
+    getValidity() {
+        const state = this.getCurrentState();
+        const hasStateChanged = !this.prevState || !this.equals(this.prevState, state);
+        if (!hasStateChanged) {
+            return this.currentValidity;
+        }
+        const { validity, validationMessage } = this.computeValidity(state);
+        this.prevState = this.copy(state);
+        this.currentValidity = {
+            validationMessage,
+            validity: {
+                // Change any `ValidityState` instances into `ValidityStateFlags` since
+                // `ValidityState` cannot be easily `{...spread}`.
+                badInput: validity.badInput,
+                customError: validity.customError,
+                patternMismatch: validity.patternMismatch,
+                rangeOverflow: validity.rangeOverflow,
+                rangeUnderflow: validity.rangeUnderflow,
+                stepMismatch: validity.stepMismatch,
+                tooLong: validity.tooLong,
+                tooShort: validity.tooShort,
+                typeMismatch: validity.typeMismatch,
+                valueMissing: validity.valueMissing,
+            },
+        };
+        return this.currentValidity;
+    }
+}
+//# sourceMappingURL=validator.js.map