material-web-evo 10002.10001.10000

package/labs/behaviors/constraint-validation.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LitElement } from 'lit';
+import { WithElementInternals } from './element-internals.js';
+import { FormAssociated } from './form-associated.js';
+import { MixinBase, MixinReturn } from './mixin.js';
+import { Validator } from './validators/validator.js';
+/**
+ * A form associated element that provides constraint validation APIs.
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
+ */
+export interface ConstraintValidation extends FormAssociated {
+    /**
+     * Returns a ValidityState object that represents the validity states of the
+     * element.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
+     */
+    readonly validity: ValidityState;
+    /**
+     * Returns a validation error message or an empty string if the element is
+     * valid.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
+     */
+    readonly validationMessage: string;
+    /**
+     * Returns whether an element will successfully validate based on forms
+     * validation rules and constraints.
+     *
+     * Disabled and readonly elements will not validate.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate
+     */
+    readonly willValidate: boolean;
+    /**
+     * Checks the element's constraint validation and returns true if the element
+     * is valid or false if not.
+     *
+     * If invalid, this method will dispatch an `invalid` event.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
+     *
+     * @return true if the element is valid, or false if not.
+     */
+    checkValidity(): boolean;
+    /**
+     * Checks the element's constraint validation and returns true if the element
+     * is valid or false if not.
+     *
+     * If invalid, this method will dispatch a cancelable `invalid` event. If not
+     * canceled, a the current `validationMessage` will be reported to the user.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
+     *
+     * @return true if the element is valid, or false if not.
+     */
+    reportValidity(): boolean;
+    /**
+     * Sets the element's constraint validation error message. When set to a
+     * non-empty string, `validity.customError` will be true and
+     * `validationMessage` will display the provided error.
+     *
+     * Use this method to customize error messages reported.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
+     *
+     * @param error The error message to display, or an empty string.
+     */
+    setCustomValidity(error: string): void;
+    /**
+     * Creates and returns a `Validator` that is used to compute and cache
+     * validity for the element.
+     *
+     * A validator that caches validity is important since constraint validation
+     * must be computed synchronously and frequently in response to constraint
+     * validation property changes.
+     */
+    [createValidator](): Validator<unknown>;
+    /**
+     * Returns shadow DOM child that is used as the anchor for the platform
+     * `reportValidity()` popup. This is often the root element or the inner
+     * focus-delegated element.
+     */
+    [getValidityAnchor](): HTMLElement | null;
+}
+/**
+ * A symbol property used to create a constraint validation `Validator`.
+ * Required for all `mixinConstraintValidation()` elements.
+ */
+export declare const createValidator: unique symbol;
+/**
+ * A symbol property used to return an anchor for constraint validation popups.
+ * Required for all `mixinConstraintValidation()` elements.
+ */
+export declare const getValidityAnchor: unique symbol;
+/**
+ * Mixes in constraint validation APIs for an element.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
+ * for more details.
+ *
+ * Implementations must provide a validator to cache and compute its validity,
+ * along with a shadow root element to anchor validation popups to.
+ *
+ * @example
+ * ```ts
+ * const baseClass = mixinConstraintValidation(
+ *   mixinFormAssociated(mixinElementInternals(LitElement))
+ * );
+ *
+ * class MyCheckbox extends baseClass {
+ *   \@property({type: Boolean}) checked = false;
+ *   \@property({type: Boolean}) required = false;
+ *
+ *   [createValidator]() {
+ *     return new CheckboxValidator(() => this);
+ *   }
+ *
+ *   [getValidityAnchor]() {
+ *     return this.renderRoot.querySelector('.root');
+ *   }
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `ConstraintValidation` mixed in.
+ */
+export declare function mixinConstraintValidation<T extends MixinBase<LitElement & FormAssociated & WithElementInternals>>(base: T): MixinReturn<T, ConstraintValidation>;

package/labs/behaviors/constraint-validation.js

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isServer } from 'lit';
+import { internals } from './element-internals.js';
+/**
+ * A symbol property used to create a constraint validation `Validator`.
+ * Required for all `mixinConstraintValidation()` elements.
+ */
+export const createValidator = Symbol('createValidator');
+/**
+ * A symbol property used to return an anchor for constraint validation popups.
+ * Required for all `mixinConstraintValidation()` elements.
+ */
+export const getValidityAnchor = Symbol('getValidityAnchor');
+// Private symbol members, used to avoid name clashing.
+const privateValidator = Symbol('privateValidator');
+const privateSyncValidity = Symbol('privateSyncValidity');
+const privateCustomValidationMessage = Symbol('privateCustomValidationMessage');
+/**
+ * Mixes in constraint validation APIs for an element.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
+ * for more details.
+ *
+ * Implementations must provide a validator to cache and compute its validity,
+ * along with a shadow root element to anchor validation popups to.
+ *
+ * @example
+ * ```ts
+ * const baseClass = mixinConstraintValidation(
+ *   mixinFormAssociated(mixinElementInternals(LitElement))
+ * );
+ *
+ * class MyCheckbox extends baseClass {
+ *   \@property({type: Boolean}) checked = false;
+ *   \@property({type: Boolean}) required = false;
+ *
+ *   [createValidator]() {
+ *     return new CheckboxValidator(() => this);
+ *   }
+ *
+ *   [getValidityAnchor]() {
+ *     return this.renderRoot.querySelector('.root');
+ *   }
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `ConstraintValidation` mixed in.
+ */
+export function mixinConstraintValidation(base) {
+    var _a;
+    class ConstraintValidationElement extends base {
+        constructor() {
+            super(...arguments);
+            /**
+             * Needed for Safari, see https://bugs.webkit.org/show_bug.cgi?id=261432
+             * Replace with this[internals].validity.customError when resolved.
+             */
+            this[_a] = '';
+        }
+        get validity() {
+            this[privateSyncValidity]();
+            return this[internals].validity;
+        }
+        get validationMessage() {
+            this[privateSyncValidity]();
+            return this[internals].validationMessage;
+        }
+        get willValidate() {
+            this[privateSyncValidity]();
+            return this[internals].willValidate;
+        }
+        checkValidity() {
+            this[privateSyncValidity]();
+            return this[internals].checkValidity();
+        }
+        reportValidity() {
+            this[privateSyncValidity]();
+            return this[internals].reportValidity();
+        }
+        setCustomValidity(error) {
+            this[privateCustomValidationMessage] = error;
+            this[privateSyncValidity]();
+        }
+        requestUpdate(name, oldValue, options) {
+            super.requestUpdate(name, oldValue, options);
+            this[privateSyncValidity]();
+        }
+        firstUpdated(changed) {
+            super.firstUpdated(changed);
+            // Sync the validity again when the element first renders, since the
+            // validity anchor is now available.
+            //
+            // Elements that `delegatesFocus: true` to an `<input>` will throw an
+            // error in Chrome and Safari when a form tries to submit or call
+            // `form.reportValidity()`:
+            // "An invalid form control with name='' is not focusable"
+            //
+            // The validity anchor MUST be provided in `internals.setValidity()` and
+            // MUST be the `<input>` element rendered.
+            //
+            // See https://lit.dev/playground/#gist=6c26e418e0010f7a5aac15005cde8bde
+            // for a reproduction.
+            this[privateSyncValidity]();
+        }
+        [(_a = privateCustomValidationMessage, privateSyncValidity)]() {
+            if (isServer) {
+                return;
+            }
+            if (!this[privateValidator]) {
+                this[privateValidator] = this[createValidator]();
+            }
+            const { validity, validationMessage: nonCustomValidationMessage } = this[privateValidator].getValidity();
+            const customError = !!this[privateCustomValidationMessage];
+            const validationMessage = this[privateCustomValidationMessage] || nonCustomValidationMessage;
+            this[internals].setValidity({ ...validity, customError }, validationMessage, this[getValidityAnchor]() ?? undefined);
+        }
+        [createValidator]() {
+            throw new Error('Implement [createValidator]');
+        }
+        [getValidityAnchor]() {
+            throw new Error('Implement [getValidityAnchor]');
+        }
+    }
+    return ConstraintValidationElement;
+}
+//# sourceMappingURL=constraint-validation.js.map

package/labs/behaviors/constraint-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-validation.js","sourceRoot":"","sources":["constraint-validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {isServer, LitElement, PropertyDeclaration, PropertyValues} from 'lit';\n\nimport {internals, WithElementInternals} from './element-internals.js';\nimport {FormAssociated} from './form-associated.js';\nimport {MixinBase, MixinReturn} from './mixin.js';\nimport {Validator} from './validators/validator.js';\n\n/**\n * A form associated element that provides constraint validation APIs.\n *\n * https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation\n */\nexport interface ConstraintValidation extends FormAssociated {\n  /**\n   * Returns a ValidityState object that represents the validity states of the\n   * element.\n   *\n   * https://developer.mozilla.org/en-US/docs/Web/API/ValidityState\n   */\n  readonly validity: ValidityState;\n\n  /**\n   * Returns a validation error message or an empty string if the element is\n   * valid.\n   *\n   * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage\n   */\n  readonly validationMessage: string;\n\n  /**\n   * Returns whether an element will successfully validate based on forms\n   * validation rules and constraints.\n   *\n   * Disabled and readonly elements will not validate.\n   *\n   * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate\n   */\n  readonly willValidate: boolean;\n\n  /**\n   * Checks the element's constraint validation and returns true if the element\n   * is valid or false if not.\n   *\n   * If invalid, this method will dispatch an `invalid` event.\n   *\n   * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity\n   *\n   * @return true if the element is valid, or false if not.\n   */\n  checkValidity(): boolean;\n\n  /**\n   * Checks the element's constraint validation and returns true if the element\n   * is valid or false if not.\n   *\n   * If invalid, this method will dispatch a cancelable `invalid` event. If not\n   * canceled, a the current `validationMessage` will be reported to the user.\n   *\n   * https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity\n   *\n   * @return true if the element is valid, or false if not.\n   */\n  reportValidity(): boolean;\n\n  /**\n   * Sets the element's constraint validation error message. When set to a\n   * non-empty string, `validity.customError` will be true and\n   * `validationMessage` will display the provided error.\n   *\n   * Use this method to customize error messages reported.\n   *\n   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity\n   *\n   * @param error The error message to display, or an empty string.\n   */\n  setCustomValidity(error: string): void;\n\n  /**\n   * Creates and returns a `Validator` that is used to compute and cache\n   * validity for the element.\n   *\n   * A validator that caches validity is important since constraint validation\n   * must be computed synchronously and frequently in response to constraint\n   * validation property changes.\n   */\n  [createValidator](): Validator<unknown>;\n\n  /**\n   * Returns shadow DOM child that is used as the anchor for the platform\n   * `reportValidity()` popup. This is often the root element or the inner\n   * focus-delegated element.\n   */\n  [getValidityAnchor](): HTMLElement | null;\n}\n\n/**\n * A symbol property used to create a constraint validation `Validator`.\n * Required for all `mixinConstraintValidation()` elements.\n */\nexport const createValidator = Symbol('createValidator');\n\n/**\n * A symbol property used to return an anchor for constraint validation popups.\n * Required for all `mixinConstraintValidation()` elements.\n */\nexport const getValidityAnchor = Symbol('getValidityAnchor');\n\n// Private symbol members, used to avoid name clashing.\nconst privateValidator = Symbol('privateValidator');\nconst privateSyncValidity = Symbol('privateSyncValidity');\nconst privateCustomValidationMessage = Symbol('privateCustomValidationMessage');\n\n/**\n * Mixes in constraint validation APIs for an element.\n *\n * See https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation\n * for more details.\n *\n * Implementations must provide a validator to cache and compute its validity,\n * along with a shadow root element to anchor validation popups to.\n *\n * @example\n * ```ts\n * const baseClass = mixinConstraintValidation(\n *   mixinFormAssociated(mixinElementInternals(LitElement))\n * );\n *\n * class MyCheckbox extends baseClass {\n *   \\@property({type: Boolean}) checked = false;\n *   \\@property({type: Boolean}) required = false;\n *\n *   [createValidator]() {\n *     return new CheckboxValidator(() => this);\n *   }\n *\n *   [getValidityAnchor]() {\n *     return this.renderRoot.querySelector('.root');\n *   }\n * }\n * ```\n *\n * @param base The class to mix functionality into.\n * @return The provided class with `ConstraintValidation` mixed in.\n */\nexport function mixinConstraintValidation<\n  T extends MixinBase<LitElement & FormAssociated & WithElementInternals>,\n>(base: T): MixinReturn<T, ConstraintValidation> {\n  abstract class ConstraintValidationElement\n    extends base\n    implements ConstraintValidation\n  {\n    get validity() {\n      this[privateSyncValidity]();\n      return this[internals].validity;\n    }\n\n    get validationMessage() {\n      this[privateSyncValidity]();\n      return this[internals].validationMessage;\n    }\n\n    get willValidate() {\n      this[privateSyncValidity]();\n      return this[internals].willValidate;\n    }\n\n    /**\n     * A validator instance created from `[createValidator]()`.\n     */\n    [privateValidator]?: Validator<unknown>;\n\n    /**\n     * Needed for Safari, see https://bugs.webkit.org/show_bug.cgi?id=261432\n     * Replace with this[internals].validity.customError when resolved.\n     */\n    [privateCustomValidationMessage] = '';\n\n    checkValidity() {\n      this[privateSyncValidity]();\n      return this[internals].checkValidity();\n    }\n\n    reportValidity() {\n      this[privateSyncValidity]();\n      return this[internals].reportValidity();\n    }\n\n    setCustomValidity(error: string) {\n      this[privateCustomValidationMessage] = error;\n      this[privateSyncValidity]();\n    }\n\n    override requestUpdate(\n      name?: PropertyKey,\n      oldValue?: unknown,\n      options?: PropertyDeclaration,\n    ) {\n      super.requestUpdate(name, oldValue, options);\n      this[privateSyncValidity]();\n    }\n\n    override firstUpdated(changed: PropertyValues) {\n      super.firstUpdated(changed);\n      // Sync the validity again when the element first renders, since the\n      // validity anchor is now available.\n      //\n      // Elements that `delegatesFocus: true` to an `<input>` will throw an\n      // error in Chrome and Safari when a form tries to submit or call\n      // `form.reportValidity()`:\n      // \"An invalid form control with name='' is not focusable\"\n      //\n      // The validity anchor MUST be provided in `internals.setValidity()` and\n      // MUST be the `<input>` element rendered.\n      //\n      // See https://lit.dev/playground/#gist=6c26e418e0010f7a5aac15005cde8bde\n      // for a reproduction.\n      this[privateSyncValidity]();\n    }\n\n    [privateSyncValidity]() {\n      if (isServer) {\n        return;\n      }\n\n      if (!this[privateValidator]) {\n        this[privateValidator] = this[createValidator]();\n      }\n\n      const {validity, validationMessage: nonCustomValidationMessage} =\n        this[privateValidator].getValidity();\n\n      const customError = !!this[privateCustomValidationMessage];\n      const validationMessage =\n        this[privateCustomValidationMessage] || nonCustomValidationMessage;\n\n      this[internals].setValidity(\n        {...validity, customError},\n        validationMessage,\n        this[getValidityAnchor]() ?? undefined,\n      );\n    }\n\n    [createValidator](): Validator<unknown> {\n      throw new Error('Implement [createValidator]');\n    }\n\n    [getValidityAnchor](): HTMLElement | null {\n      throw new Error('Implement [getValidityAnchor]');\n    }\n  }\n\n  return ConstraintValidationElement;\n}\n"]}

package/labs/behaviors/element-internals.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LitElement } from 'lit';
+import { MixinBase, MixinReturn } from './mixin.js';
+/**
+ * A unique symbol used for protected access to an instance's
+ * `ElementInternals`.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends mixinElementInternals(LitElement) {
+ *   constructor() {
+ *     super();
+ *     this[internals].role = 'button';
+ *   }
+ * }
+ * ```
+ */
+export declare const internals: unique symbol;
+/**
+ * An instance with an `internals` symbol property for the component's
+ * `ElementInternals`.
+ *
+ * Use this when protected access is needed for an instance's `ElementInternals`
+ * from other files. A unique symbol is used to access the internals.
+ */
+export interface WithElementInternals {
+    /**
+     * An instance's `ElementInternals`.
+     */
+    [internals]: ElementInternals;
+}
+/**
+ * Mixes in an attached `ElementInternals` instance.
+ *
+ * This mixin is only needed when other shared code needs access to a
+ * component's `ElementInternals`, such as form-associated mixins.
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `WithElementInternals` mixed in.
+ */
+export declare function mixinElementInternals<T extends MixinBase<LitElement>>(base: T): MixinReturn<T, WithElementInternals>;

package/labs/behaviors/element-internals.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A unique symbol used for protected access to an instance's
+ * `ElementInternals`.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends mixinElementInternals(LitElement) {
+ *   constructor() {
+ *     super();
+ *     this[internals].role = 'button';
+ *   }
+ * }
+ * ```
+ */
+export const internals = Symbol('internals');
+// Private symbols
+const privateInternals = Symbol('privateInternals');
+/**
+ * Mixes in an attached `ElementInternals` instance.
+ *
+ * This mixin is only needed when other shared code needs access to a
+ * component's `ElementInternals`, such as form-associated mixins.
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `WithElementInternals` mixed in.
+ */
+export function mixinElementInternals(base) {
+    class WithElementInternalsElement extends base {
+        get [internals]() {
+            // Create internals in getter so that it can be used in methods called on
+            // construction in `ReactiveElement`, such as `requestUpdate()`.
+            if (!this[privateInternals]) {
+                // Cast needed for closure
+                this[privateInternals] = this.attachInternals();
+            }
+            return this[privateInternals];
+        }
+    }
+    return WithElementInternalsElement;
+}
+//# sourceMappingURL=element-internals.js.map

package/labs/behaviors/element-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-internals.js","sourceRoot":"","sources":["element-internals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAgB7C,kBAAkB;AAClB,MAAM,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAO;IAEP,MAAe,2BACb,SAAQ,IAAI;QAGZ,IAAI,CAAC,SAAS,CAAC;YACb,yEAAyE;YACzE,gEAAgE;YAChE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE;gBAC3B,0BAA0B;gBAC1B,IAAI,CAAC,gBAAgB,CAAC,GAAI,IAAoB,CAAC,eAAe,EAAE,CAAC;aAClE;YAED,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAChC,CAAC;KAGF;IAED,OAAO,2BAA2B,CAAC;AACrC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {LitElement} from 'lit';\n\nimport {MixinBase, MixinReturn} from './mixin.js';\n\n/**\n * A unique symbol used for protected access to an instance's\n * `ElementInternals`.\n *\n * @example\n * ```ts\n * class MyElement extends mixinElementInternals(LitElement) {\n *   constructor() {\n *     super();\n *     this[internals].role = 'button';\n *   }\n * }\n * ```\n */\nexport const internals = Symbol('internals');\n\n/**\n * An instance with an `internals` symbol property for the component's\n * `ElementInternals`.\n *\n * Use this when protected access is needed for an instance's `ElementInternals`\n * from other files. A unique symbol is used to access the internals.\n */\nexport interface WithElementInternals {\n  /**\n   * An instance's `ElementInternals`.\n   */\n  [internals]: ElementInternals;\n}\n\n// Private symbols\nconst privateInternals = Symbol('privateInternals');\n\n/**\n * Mixes in an attached `ElementInternals` instance.\n *\n * This mixin is only needed when other shared code needs access to a\n * component's `ElementInternals`, such as form-associated mixins.\n *\n * @param base The class to mix functionality into.\n * @return The provided class with `WithElementInternals` mixed in.\n */\nexport function mixinElementInternals<T extends MixinBase<LitElement>>(\n  base: T,\n): MixinReturn<T, WithElementInternals> {\n  abstract class WithElementInternalsElement\n    extends base\n    implements WithElementInternals\n  {\n    get [internals]() {\n      // Create internals in getter so that it can be used in methods called on\n      // construction in `ReactiveElement`, such as `requestUpdate()`.\n      if (!this[privateInternals]) {\n        // Cast needed for closure\n        this[privateInternals] = (this as HTMLElement).attachInternals();\n      }\n\n      return this[privateInternals];\n    }\n\n    [privateInternals]?: ElementInternals;\n  }\n\n  return WithElementInternalsElement;\n}\n"]}

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,87 @@
+/**
+ * @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 {
+        constructor() {
+            super(...arguments);
+            this[_a] = true;
+            this[_b] = null;
+            this[_c] = false;
+        }
+        get [isFocusable]() {
+            return this[privateIsFocusable];
+        }
+        set [isFocusable](value) {
+            if (this[isFocusable] === value) {
+                return;
+            }
+            this[privateIsFocusable] = value;
+            this[updateTabIndex]();
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this[updateTabIndex]();
+        }
+        attributeChangedCallback(name, old, value) {
+            if (name !== 'tabindex') {
+                super.attributeChangedCallback(name, old, value);
+                return;
+            }
+            this.requestUpdate('tabIndex', Number(old ?? -1));
+            if (this[isUpdatingTabIndex]) {
+                // Not an externally-initiated update.
+                return;
+            }
+            if (!this.hasAttribute('tabindex')) {
+                // User removed the attribute, can now use internal tabIndex
+                this[externalTabIndex] = null;
+                this[updateTabIndex]();
+                return;
+            }
+            this[externalTabIndex] = this.tabIndex;
+        }
+        [(_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[isUpdatingTabIndex] = false;
+        }
+    }
+    __decorate([
+        property({ noAccessor: 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;QAA5C;;YAiBE,QAAoB,GAAG,IAAI,CAAC;YAC5B,QAAkB,GAAkB,IAAI,CAAC;YACzC,QAAoB,GAAG,KAAK,CAAC;QAyC/B,CAAC;QAxDC,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;QAMQ,iBAAiB;YACxB,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC1B,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACzB,CAAC;QAEQ,wBAAwB,CAC/B,IAAY,EACZ,GAAkB,EAClB,KAAoB;YAEpB,IAAI,IAAI,KAAK,UAAU,EAAE;gBACvB,KAAK,CAAC,wBAAwB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;gBACjD,OAAO;aACR;YAED,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,IAAI,CAAC,kBAAkB,CAAC,EAAE;gBAC5B,sCAAsC;gBACtC,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,OAnCC,kBAAkB,OAClB,gBAAgB,OAChB,kBAAkB,EAiClB,cAAc,EAAC;YACd,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,kBAAkB,CAAC,GAAG,KAAK,CAAC;QACnC,CAAC;KACF;IA1DS;QADP,QAAQ,CAAC,EAAC,UAAU,EAAE,IAAI,EAAC,CAAC;sDACJ;IA4D3B,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({noAccessor: true})\n    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] = true;\n    [externalTabIndex]: number | null = null;\n    [isUpdatingTabIndex] = false;\n\n    override connectedCallback() {\n      super.connectedCallback();\n      this[updateTabIndex]();\n    }\n\n    override attributeChangedCallback(\n      name: string,\n      old: string | null,\n      value: string | null,\n    ) {\n      if (name !== 'tabindex') {\n        super.attributeChangedCallback(name, old, value);\n        return;\n      }\n\n      this.requestUpdate('tabIndex', Number(old ?? -1));\n      if (this[isUpdatingTabIndex]) {\n        // Not an externally-initiated update.\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    [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[isUpdatingTabIndex] = false;\n    }\n  }\n\n  return FocusableElement;\n}\n"]}