@material/web 1.0.0 → 1.0.2-nightly.33c1afe.0

package/labs/behaviors/focusable.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LitElement } from 'lit';
+import { MixinBase, MixinReturn } from './mixin.js';
+/**
+ * An element that can enable and disable `tabindex` focusability.
+ */
+export interface Focusable {
+    /**
+     * Whether or not the element can be focused. Defaults to true. Set to false
+     * to disable focusing (unless a user has set a `tabindex`).
+     */
+    [isFocusable]: boolean;
+}
+/**
+ * A property symbol that indicates whether or not a `Focusable` element can be
+ * focused.
+ */
+export declare const isFocusable: unique symbol;
+/**
+ * Mixes in focusable functionality for a class.
+ *
+ * Elements can enable and disable their focusability with the `isFocusable`
+ * symbol property. Changing `tabIndex` will trigger a lit render, meaning
+ * `this.tabIndex` can be used in template expressions.
+ *
+ * This mixin will preserve externally-set tabindices. If an element turns off
+ * focusability, but a user sets `tabindex="0"`, it will still be focusable.
+ *
+ * To remove user overrides and restore focusability control to the element,
+ * remove the `tabindex` attribute.
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `Focusable` mixed in.
+ */
+export declare function mixinFocusable<T extends MixinBase<LitElement>>(base: T): MixinReturn<T, Focusable>;

package/labs/behaviors/focusable.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { __decorate } from "tslib";
+import { property } from 'lit/decorators.js';
+/**
+ * A property symbol that indicates whether or not a `Focusable` element can be
+ * focused.
+ */
+export const isFocusable = Symbol('isFocusable');
+const privateIsFocusable = Symbol('privateIsFocusable');
+const externalTabIndex = Symbol('externalTabIndex');
+const isUpdatingTabIndex = Symbol('isUpdatingTabIndex');
+const updateTabIndex = Symbol('updateTabIndex');
+/**
+ * Mixes in focusable functionality for a class.
+ *
+ * Elements can enable and disable their focusability with the `isFocusable`
+ * symbol property. Changing `tabIndex` will trigger a lit render, meaning
+ * `this.tabIndex` can be used in template expressions.
+ *
+ * This mixin will preserve externally-set tabindices. If an element turns off
+ * focusability, but a user sets `tabindex="0"`, it will still be focusable.
+ *
+ * To remove user overrides and restore focusability control to the element,
+ * remove the `tabindex` attribute.
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `Focusable` mixed in.
+ */
+export function mixinFocusable(base) {
+    var _a, _b, _c;
+    class FocusableElement extends base {
+        get [isFocusable]() {
+            return this[privateIsFocusable];
+        }
+        set [isFocusable](value) {
+            if (this[isFocusable] === value) {
+                return;
+            }
+            this[privateIsFocusable] = value;
+            this[updateTabIndex]();
+        }
+        // tslint:disable-next-line:no-any
+        constructor(...args) {
+            super(...args);
+            this[_a] = false;
+            this[_b] = null;
+            this[_c] = false;
+            this[isFocusable] = true;
+        }
+        attributeChangedCallback(name, old, value) {
+            super.attributeChangedCallback(name, old, value);
+            if (name !== 'tabindex' || this[isUpdatingTabIndex]) {
+                return;
+            }
+            if (!this.hasAttribute('tabindex')) {
+                // User removed the attribute, can now use internal tabIndex
+                this[externalTabIndex] = null;
+                this[updateTabIndex]();
+                return;
+            }
+            this[externalTabIndex] = this.tabIndex;
+        }
+        async [(_a = privateIsFocusable, _b = externalTabIndex, _c = isUpdatingTabIndex, updateTabIndex)]() {
+            const internalTabIndex = this[isFocusable] ? 0 : -1;
+            const computedTabIndex = this[externalTabIndex] ?? internalTabIndex;
+            this[isUpdatingTabIndex] = true;
+            this.tabIndex = computedTabIndex;
+            this.requestUpdate();
+            await this.updateComplete;
+            this[isUpdatingTabIndex] = false;
+        }
+    }
+    __decorate([
+        property({ reflect: true })
+    ], FocusableElement.prototype, "tabIndex", void 0);
+    return FocusableElement;
+}
+//# sourceMappingURL=focusable.js.map

package/labs/behaviors/focusable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable.js","sourceRoot":"","sources":["focusable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;AAGH,OAAO,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAe3C;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AAEjD,MAAM,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACxD,MAAM,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AACpD,MAAM,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACxD,MAAM,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAO;;IAEP,MAAe,gBAAiB,SAAQ,IAAI;QAG1C,IAAI,CAAC,WAAW,CAAC;YACf,OAAO,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,CAAC,KAAc;YAC9B,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,KAAK,EAAE;gBAC/B,OAAO;aACR;YAED,IAAI,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC;YACjC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACzB,CAAC;QAMD,kCAAkC;QAClC,YAAY,GAAG,IAAW;YACxB,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YANjB,QAAoB,GAAG,KAAK,CAAC;YAC7B,QAAkB,GAAkB,IAAI,CAAC;YACzC,QAAoB,GAAG,KAAK,CAAC;YAK3B,IAAI,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;QAC3B,CAAC;QAEQ,wBAAwB,CAC/B,IAAY,EACZ,GAAkB,EAClB,KAAoB;YAEpB,KAAK,CAAC,wBAAwB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YACjD,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,kBAAkB,CAAC,EAAE;gBACnD,OAAO;aACR;YAED,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE;gBAClC,4DAA4D;gBAC5D,IAAI,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;gBAC9B,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;gBACvB,OAAO;aACR;YAED,IAAI,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QACzC,CAAC;QAED,KAAK,CAAC,OA9BL,kBAAkB,OAClB,gBAAgB,OAChB,kBAAkB,EA4BZ,cAAc,EAAC;YACpB,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACpD,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,CAAC;YAEpE,IAAI,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;YAChC,IAAI,CAAC,QAAQ,GAAG,gBAAgB,CAAC;YACjC,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,cAAc,CAAC;YAC1B,IAAI,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC;QACnC,CAAC;KACF;IAvDoC;QAAlC,QAAQ,CAAC,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC;sDAA0B;IAyDtD,OAAO,gBAAgB,CAAC;AAC1B,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {LitElement} from 'lit';\nimport {property} from 'lit/decorators.js';\n\nimport {MixinBase, MixinReturn} from './mixin.js';\n\n/**\n * An element that can enable and disable `tabindex` focusability.\n */\nexport interface Focusable {\n  /**\n   * Whether or not the element can be focused. Defaults to true. Set to false\n   * to disable focusing (unless a user has set a `tabindex`).\n   */\n  [isFocusable]: boolean;\n}\n\n/**\n * A property symbol that indicates whether or not a `Focusable` element can be\n * focused.\n */\nexport const isFocusable = Symbol('isFocusable');\n\nconst privateIsFocusable = Symbol('privateIsFocusable');\nconst externalTabIndex = Symbol('externalTabIndex');\nconst isUpdatingTabIndex = Symbol('isUpdatingTabIndex');\nconst updateTabIndex = Symbol('updateTabIndex');\n\n/**\n * Mixes in focusable functionality for a class.\n *\n * Elements can enable and disable their focusability with the `isFocusable`\n * symbol property. Changing `tabIndex` will trigger a lit render, meaning\n * `this.tabIndex` can be used in template expressions.\n *\n * This mixin will preserve externally-set tabindices. If an element turns off\n * focusability, but a user sets `tabindex=\"0\"`, it will still be focusable.\n *\n * To remove user overrides and restore focusability control to the element,\n * remove the `tabindex` attribute.\n *\n * @param base The class to mix functionality into.\n * @return The provided class with `Focusable` mixed in.\n */\nexport function mixinFocusable<T extends MixinBase<LitElement>>(\n  base: T,\n): MixinReturn<T, Focusable> {\n  abstract class FocusableElement extends base implements Focusable {\n    @property({reflect: true}) declare tabIndex: number;\n\n    get [isFocusable]() {\n      return this[privateIsFocusable];\n    }\n\n    set [isFocusable](value: boolean) {\n      if (this[isFocusable] === value) {\n        return;\n      }\n\n      this[privateIsFocusable] = value;\n      this[updateTabIndex]();\n    }\n\n    [privateIsFocusable] = false;\n    [externalTabIndex]: number | null = null;\n    [isUpdatingTabIndex] = false;\n\n    // tslint:disable-next-line:no-any\n    constructor(...args: any[]) {\n      super(...args);\n      this[isFocusable] = true;\n    }\n\n    override attributeChangedCallback(\n      name: string,\n      old: string | null,\n      value: string | null,\n    ) {\n      super.attributeChangedCallback(name, old, value);\n      if (name !== 'tabindex' || this[isUpdatingTabIndex]) {\n        return;\n      }\n\n      if (!this.hasAttribute('tabindex')) {\n        // User removed the attribute, can now use internal tabIndex\n        this[externalTabIndex] = null;\n        this[updateTabIndex]();\n        return;\n      }\n\n      this[externalTabIndex] = this.tabIndex;\n    }\n\n    async [updateTabIndex]() {\n      const internalTabIndex = this[isFocusable] ? 0 : -1;\n      const computedTabIndex = this[externalTabIndex] ?? internalTabIndex;\n\n      this[isUpdatingTabIndex] = true;\n      this.tabIndex = computedTabIndex;\n      this.requestUpdate();\n      await this.updateComplete;\n      this[isUpdatingTabIndex] = false;\n    }\n  }\n\n  return FocusableElement;\n}\n"]}

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/on-report-validity.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LitElement } from 'lit';
+import { ConstraintValidation } from './constraint-validation.js';
+import { MixinBase, MixinReturn } from './mixin.js';
+/**
+ * A constraint validation element that has a callback for when the element
+ * should report validity styles and error messages to the user.
+ *
+ * This is commonly used in text-field-like controls that display error styles
+ * and error messages.
+ */
+export interface OnReportValidity extends ConstraintValidation {
+    /**
+     * A callback that is invoked when validity should be reported. Components
+     * that can display their own error state can use this and update their
+     * styles.
+     *
+     * If an invalid event is provided, the element is invalid. If `null`, the
+     * element is valid.
+     *
+     * The invalid event's `preventDefault()` may be called to stop the platform
+     * popup from displaying.
+     *
+     * @param invalidEvent The `invalid` event dispatched when an element is
+     *     invalid, or `null` if the element is valid.
+     */
+    [onReportValidity](invalidEvent: Event | null): void;
+    formAssociatedCallback(form: HTMLFormElement | null): void;
+}
+/**
+ * A symbol property used for a callback when validity has been reported.
+ */
+export declare const onReportValidity: unique symbol;
+/**
+ * Mixes in a callback for constraint validation when validity should be
+ * styled and reported to the user.
+ *
+ * This is commonly used in text-field-like controls that display error styles
+ * and error messages.
+ *
+ * @example
+ * ```ts
+ * const baseClass = mixinOnReportValidity(
+ *   mixinConstraintValidation(
+ *     mixinFormAssociated(mixinElementInternals(LitElement)),
+ *   ),
+ * );
+ *
+ * class MyField extends baseClass {
+ *   \@property({type: Boolean}) error = false;
+ *   \@property() errorMessage = '';
+ *
+ *   [onReportValidity](invalidEvent: Event | null) {
+ *     this.error = !!invalidEvent;
+ *     this.errorMessage = this.validationMessage;
+ *
+ *     // Optionally prevent platform popup from displaying
+ *     invalidEvent?.preventDefault();
+ *   }
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `OnReportValidity` mixed in.
+ */
+export declare function mixinOnReportValidity<T extends MixinBase<LitElement & ConstraintValidation>>(base: T): MixinReturn<T, OnReportValidity>;