@material/web 1.0.0-pre.8 → 1.0.0

package/internal/aria/delegate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReactiveElement } from 'lit';
+/**
+ * Sets up a `ReactiveElement` constructor to enable updates when delegating
+ * aria attributes. Elements may bind `this.aria*` properties to `aria-*`
+ * attributes in their render functions.
+ *
+ * This function will:
+ * - Call `requestUpdate()` when an aria attribute changes.
+ * - Add `role="presentation"` to the host.
+ *
+ * NOTE: The following features are not currently supported:
+ * - Delegating IDREF attributes (ex: `aria-labelledby`, `aria-controls`)
+ * - Delegating the `role` attribute
+ *
+ * @example
+ * class XButton extends LitElement {
+ *   static {
+ *     requestUpdateOnAriaChange(XButton);
+ *   }
+ *
+ *   protected override render() {
+ *     return html`
+ *       <button aria-label=${this.ariaLabel || nothing}>
+ *         <slot></slot>
+ *       </button>
+ *     `;
+ *   }
+ * }
+ *
+ * @param ctor The `ReactiveElement` constructor to patch.
+ */
+export declare function requestUpdateOnAriaChange(ctor: typeof ReactiveElement): void;

package/internal/aria/delegate.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ARIA_PROPERTIES, ariaPropertyToAttribute } from './aria.js';
+/**
+ * Sets up a `ReactiveElement` constructor to enable updates when delegating
+ * aria attributes. Elements may bind `this.aria*` properties to `aria-*`
+ * attributes in their render functions.
+ *
+ * This function will:
+ * - Call `requestUpdate()` when an aria attribute changes.
+ * - Add `role="presentation"` to the host.
+ *
+ * NOTE: The following features are not currently supported:
+ * - Delegating IDREF attributes (ex: `aria-labelledby`, `aria-controls`)
+ * - Delegating the `role` attribute
+ *
+ * @example
+ * class XButton extends LitElement {
+ *   static {
+ *     requestUpdateOnAriaChange(XButton);
+ *   }
+ *
+ *   protected override render() {
+ *     return html`
+ *       <button aria-label=${this.ariaLabel || nothing}>
+ *         <slot></slot>
+ *       </button>
+ *     `;
+ *   }
+ * }
+ *
+ * @param ctor The `ReactiveElement` constructor to patch.
+ */
+export function requestUpdateOnAriaChange(ctor) {
+    for (const ariaProperty of ARIA_PROPERTIES) {
+        ctor.createProperty(ariaProperty, {
+            attribute: ariaPropertyToAttribute(ariaProperty),
+            reflect: true,
+        });
+    }
+    ctor.addInitializer(element => {
+        const controller = {
+            hostConnected() {
+                element.setAttribute('role', 'presentation');
+            }
+        };
+        element.addController(controller);
+    });
+}
+//# sourceMappingURL=delegate.js.map

package/internal/aria/delegate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.js","sourceRoot":"","sources":["delegate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAC,eAAe,EAAE,uBAAuB,EAAC,MAAM,WAAW,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAA4B;IACpE,KAAK,MAAM,YAAY,IAAI,eAAe,EAAE;QAC1C,IAAI,CAAC,cAAc,CAAC,YAAY,EAAE;YAChC,SAAS,EAAE,uBAAuB,CAAC,YAAY,CAAC;YAChD,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;KACJ;IAED,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE;QAC5B,MAAM,UAAU,GAAG;YACjB,aAAa;gBACX,OAAO,CAAC,YAAY,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YAC/C,CAAC;SACF,CAAC;QAEF,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {ReactiveElement} from 'lit';\n\nimport {ARIA_PROPERTIES, ariaPropertyToAttribute} from './aria.js';\n\n/**\n * Sets up a `ReactiveElement` constructor to enable updates when delegating\n * aria attributes. Elements may bind `this.aria*` properties to `aria-*`\n * attributes in their render functions.\n *\n * This function will:\n * - Call `requestUpdate()` when an aria attribute changes.\n * - Add `role=\"presentation\"` to the host.\n *\n * NOTE: The following features are not currently supported:\n * - Delegating IDREF attributes (ex: `aria-labelledby`, `aria-controls`)\n * - Delegating the `role` attribute\n *\n * @example\n * class XButton extends LitElement {\n *   static {\n *     requestUpdateOnAriaChange(XButton);\n *   }\n *\n *   protected override render() {\n *     return html`\n *       <button aria-label=${this.ariaLabel || nothing}>\n *         <slot></slot>\n *       </button>\n *     `;\n *   }\n * }\n *\n * @param ctor The `ReactiveElement` constructor to patch.\n */\nexport function requestUpdateOnAriaChange(ctor: typeof ReactiveElement) {\n  for (const ariaProperty of ARIA_PROPERTIES) {\n    ctor.createProperty(ariaProperty, {\n      attribute: ariaPropertyToAttribute(ariaProperty),\n      reflect: true,\n    });\n  }\n\n  ctor.addInitializer(element => {\n    const controller = {\n      hostConnected() {\n        element.setAttribute('role', 'presentation');\n      }\n    };\n\n    element.addController(controller);\n  });\n}\n"]}

package/internal/controller/attachable-controller.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * An element that can be attached to an associated controlling element.
+ */
+export interface Attachable {
+    /**
+     * Reflects the value of the `for` attribute, which is the ID of the element's
+     * associated control.
+     *
+     * Use this when the elements's associated control is not its parent.
+     *
+     * To manually control an element, set its `for` attribute to `""`.
+     *
+     * @example
+     * ```html
+     * <div class="container">
+     *   <md-attachable for="interactive"></md-attachable>
+     *   <button id="interactive">Action</button>
+     * </div>
+     * ```
+     *
+     * @example
+     * ```html
+     * <button class="manually-controlled">
+     *   <md-attachable for=""></md-attachable>
+     * </button>
+     * ```
+     */
+    htmlFor: string | null;
+    /**
+     * Gets or sets the element that controls the visibility of the attachable
+     * element. It is one of:
+     *
+     * - The control referenced by the `for` attribute.
+     * - The control provided to `element.attach(control)`
+     * - The element's parent.
+     * - `null` if the element is not controlled.
+     */
+    control: HTMLElement | null;
+    /**
+     * Attaches the element to an interactive control.
+     *
+     * @param control The element that controls the attachable element.
+     */
+    attach(control: HTMLElement): void;
+    /**
+     * Detaches the element from its current control.
+     */
+    detach(): void;
+}
+/**
+ * A key to retrieve an `Attachable` element's `AttachableController` from a
+ * global `MutationObserver`.
+ */
+declare const ATTACHABLE_CONTROLLER: unique symbol;
+/**
+ * The host of an `AttachableController`. The controller will add itself to
+ * the host so it can be retrieved in a global `MutationObserver`.
+ */
+interface AttachableControllerHost extends ReactiveControllerHost, HTMLElement {
+    [ATTACHABLE_CONTROLLER]?: AttachableController;
+}
+/**
+ * A controller that provides an implementation for `Attachable` elements.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends LitElement implements Attachable {
+ *   get control() { return this.attachableController.control; }
+ *
+ *   private readonly attachableController = new AttachableController(
+ *     this,
+ *     (previousControl, newControl) => {
+ *       previousControl?.removeEventListener('click', this.handleClick);
+ *       newControl?.addEventListener('click', this.handleClick);
+ *     }
+ *   );
+ *
+ *   // Implement remaining `Attachable` properties/methods that call the
+ *   // controller's properties/methods.
+ * }
+ * ```
+ */
+export declare class AttachableController implements ReactiveController, Attachable {
+    private readonly host;
+    private readonly onControlChange;
+    get htmlFor(): string | null;
+    set htmlFor(htmlFor: string | null);
+    get control(): HTMLElement | null;
+    set control(control: HTMLElement | null);
+    private currentControl;
+    /**
+     * Creates a new controller for an `Attachable` element.
+     *
+     * @param host The `Attachable` element.
+     * @param onControlChange A callback with two parameters for the previous and
+     *     next control. An `Attachable` element may perform setup or teardown
+     *     logic whenever the control changes.
+     */
+    constructor(host: AttachableControllerHost, onControlChange: (prev: HTMLElement | null, next: HTMLElement | null) => void);
+    attach(control: HTMLElement): void;
+    detach(): void;
+    /** @private */
+    hostConnected(): void;
+    /** @private */
+    hostDisconnected(): void;
+    private setCurrentControl;
+}
+export {};

package/internal/controller/attachable-controller.js

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isServer } from 'lit';
+/**
+ * A key to retrieve an `Attachable` element's `AttachableController` from a
+ * global `MutationObserver`.
+ */
+const ATTACHABLE_CONTROLLER = Symbol('attachableController');
+let FOR_ATTRIBUTE_OBSERVER;
+if (!isServer) {
+    /**
+     * A global `MutationObserver` that reacts to `for` attribute changes on
+     * `Attachable` elements. If the `for` attribute changes, the controller will
+     * re-attach to the new referenced element.
+     */
+    FOR_ATTRIBUTE_OBSERVER = new MutationObserver(records => {
+        for (const record of records) {
+            // When a control's `for` attribute changes, inform its
+            // `AttachableController` to update to a new control.
+            record.target[ATTACHABLE_CONTROLLER]
+                ?.hostConnected();
+        }
+    });
+}
+/**
+ * A controller that provides an implementation for `Attachable` elements.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends LitElement implements Attachable {
+ *   get control() { return this.attachableController.control; }
+ *
+ *   private readonly attachableController = new AttachableController(
+ *     this,
+ *     (previousControl, newControl) => {
+ *       previousControl?.removeEventListener('click', this.handleClick);
+ *       newControl?.addEventListener('click', this.handleClick);
+ *     }
+ *   );
+ *
+ *   // Implement remaining `Attachable` properties/methods that call the
+ *   // controller's properties/methods.
+ * }
+ * ```
+ */
+export class AttachableController {
+    get htmlFor() {
+        return this.host.getAttribute('for');
+    }
+    set htmlFor(htmlFor) {
+        if (htmlFor === null) {
+            this.host.removeAttribute('for');
+        }
+        else {
+            this.host.setAttribute('for', htmlFor);
+        }
+    }
+    get control() {
+        if (this.host.hasAttribute('for')) {
+            if (!this.htmlFor || !this.host.isConnected) {
+                return null;
+            }
+            return this.host.getRootNode()
+                .querySelector(`#${this.htmlFor}`);
+        }
+        return this.currentControl || this.host.parentElement;
+    }
+    set control(control) {
+        if (control) {
+            this.attach(control);
+        }
+        else {
+            this.detach();
+        }
+    }
+    /**
+     * Creates a new controller for an `Attachable` element.
+     *
+     * @param host The `Attachable` element.
+     * @param onControlChange A callback with two parameters for the previous and
+     *     next control. An `Attachable` element may perform setup or teardown
+     *     logic whenever the control changes.
+     */
+    constructor(host, onControlChange) {
+        this.host = host;
+        this.onControlChange = onControlChange;
+        this.currentControl = null;
+        host.addController(this);
+        host[ATTACHABLE_CONTROLLER] = this;
+        FOR_ATTRIBUTE_OBSERVER?.observe(host, { attributeFilter: ['for'] });
+    }
+    attach(control) {
+        if (control === this.currentControl) {
+            return;
+        }
+        this.setCurrentControl(control);
+        // When imperatively attaching, remove the `for` attribute so
+        // that the attached control is used instead of a referenced one.
+        this.host.removeAttribute('for');
+    }
+    detach() {
+        this.setCurrentControl(null);
+        // When imperatively detaching, add an empty `for=""` attribute. This will
+        // ensure the control is `null` rather than the `parentElement`.
+        this.host.setAttribute('for', '');
+    }
+    /** @private */
+    hostConnected() {
+        this.setCurrentControl(this.control);
+    }
+    /** @private */
+    hostDisconnected() {
+        this.setCurrentControl(null);
+    }
+    setCurrentControl(control) {
+        this.onControlChange(this.currentControl, control);
+        this.currentControl = control;
+    }
+}
+//# sourceMappingURL=attachable-controller.js.map

package/internal/controller/attachable-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachable-controller.js","sourceRoot":"","sources":["attachable-controller.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, ReactiveController, ReactiveControllerHost} from 'lit';\n\n/**\n * An element that can be attached to an associated controlling element.\n */\nexport interface Attachable {\n  /**\n   * Reflects the value of the `for` attribute, which is the ID of the element's\n   * associated control.\n   *\n   * Use this when the elements's associated control is not its parent.\n   *\n   * To manually control an element, set its `for` attribute to `\"\"`.\n   *\n   * @example\n   * ```html\n   * <div class=\"container\">\n   *   <md-attachable for=\"interactive\"></md-attachable>\n   *   <button id=\"interactive\">Action</button>\n   * </div>\n   * ```\n   *\n   * @example\n   * ```html\n   * <button class=\"manually-controlled\">\n   *   <md-attachable for=\"\"></md-attachable>\n   * </button>\n   * ```\n   */\n  htmlFor: string|null;\n\n  /**\n   * Gets or sets the element that controls the visibility of the attachable\n   * element. It is one of:\n   *\n   * - The control referenced by the `for` attribute.\n   * - The control provided to `element.attach(control)`\n   * - The element's parent.\n   * - `null` if the element is not controlled.\n   */\n  control: HTMLElement|null;\n\n  /**\n   * Attaches the element to an interactive control.\n   *\n   * @param control The element that controls the attachable element.\n   */\n  attach(control: HTMLElement): void;\n\n  /**\n   * Detaches the element from its current control.\n   */\n  detach(): void;\n}\n\n/**\n * A key to retrieve an `Attachable` element's `AttachableController` from a\n * global `MutationObserver`.\n */\nconst ATTACHABLE_CONTROLLER = Symbol('attachableController');\n\n/**\n * The host of an `AttachableController`. The controller will add itself to\n * the host so it can be retrieved in a global `MutationObserver`.\n */\ninterface AttachableControllerHost extends ReactiveControllerHost, HTMLElement {\n  [ATTACHABLE_CONTROLLER]?: AttachableController;\n}\n\nlet FOR_ATTRIBUTE_OBSERVER: MutationObserver|undefined;\n\nif (!isServer) {\n  /**\n   * A global `MutationObserver` that reacts to `for` attribute changes on\n   * `Attachable` elements. If the `for` attribute changes, the controller will\n   * re-attach to the new referenced element.\n   */\n  FOR_ATTRIBUTE_OBSERVER = new MutationObserver(records => {\n    for (const record of records) {\n      // When a control's `for` attribute changes, inform its\n      // `AttachableController` to update to a new control.\n      (record.target as AttachableControllerHost)[ATTACHABLE_CONTROLLER]\n          ?.hostConnected();\n    }\n  });\n}\n\n/**\n * A controller that provides an implementation for `Attachable` elements.\n *\n * @example\n * ```ts\n * class MyElement extends LitElement implements Attachable {\n *   get control() { return this.attachableController.control; }\n *\n *   private readonly attachableController = new AttachableController(\n *     this,\n *     (previousControl, newControl) => {\n *       previousControl?.removeEventListener('click', this.handleClick);\n *       newControl?.addEventListener('click', this.handleClick);\n *     }\n *   );\n *\n *   // Implement remaining `Attachable` properties/methods that call the\n *   // controller's properties/methods.\n * }\n * ```\n */\nexport class AttachableController implements ReactiveController, Attachable {\n  get htmlFor() {\n    return this.host.getAttribute('for');\n  }\n\n  set htmlFor(htmlFor: string|null) {\n    if (htmlFor === null) {\n      this.host.removeAttribute('for');\n    } else {\n      this.host.setAttribute('for', htmlFor);\n    }\n  }\n\n  get control() {\n    if (this.host.hasAttribute('for')) {\n      if (!this.htmlFor || !this.host.isConnected) {\n        return null;\n      }\n\n      return (this.host.getRootNode() as Document | ShadowRoot)\n          .querySelector<HTMLElement>(`#${this.htmlFor}`);\n    }\n\n    return this.currentControl || this.host.parentElement;\n  }\n  set control(control: HTMLElement|null) {\n    if (control) {\n      this.attach(control);\n    } else {\n      this.detach();\n    }\n  }\n\n  private currentControl: HTMLElement|null = null;\n\n  /**\n   * Creates a new controller for an `Attachable` element.\n   *\n   * @param host The `Attachable` element.\n   * @param onControlChange A callback with two parameters for the previous and\n   *     next control. An `Attachable` element may perform setup or teardown\n   *     logic whenever the control changes.\n   */\n  constructor(\n      private readonly host: AttachableControllerHost,\n      private readonly onControlChange:\n          (prev: HTMLElement|null, next: HTMLElement|null) => void) {\n    host.addController(this);\n    host[ATTACHABLE_CONTROLLER] = this;\n    FOR_ATTRIBUTE_OBSERVER?.observe(host, {attributeFilter: ['for']});\n  }\n\n  attach(control: HTMLElement) {\n    if (control === this.currentControl) {\n      return;\n    }\n\n    this.setCurrentControl(control);\n    // When imperatively attaching, remove the `for` attribute so\n    // that the attached control is used instead of a referenced one.\n    this.host.removeAttribute('for');\n  }\n\n  detach() {\n    this.setCurrentControl(null);\n    // When imperatively detaching, add an empty `for=\"\"` attribute. This will\n    // ensure the control is `null` rather than the `parentElement`.\n    this.host.setAttribute('for', '');\n  }\n\n  /** @private */\n  hostConnected() {\n    this.setCurrentControl(this.control);\n  }\n\n  /** @private */\n  hostDisconnected() {\n    this.setCurrentControl(null);\n  }\n\n  private setCurrentControl(control: HTMLElement|null) {\n    this.onControlChange(this.currentControl, control);\n    this.currentControl = control;\n  }\n}\n"]}

package/internal/controller/element-internals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 LitElement {
+ *   static formAssociated = true;
+ *
+ *   [internals] = this.attachInternals();
+ * }
+ *
+ * function getForm(element: MyElement) {
+ *   return element[internals].form;
+ * }
+ * ```
+ */
+export declare const internals: unique symbol;
+/**
+ * An instance with `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 WithInternals {
+    /**
+     * An instance's `ElementInternals`.
+     */
+    [internals]: ElementInternals;
+}

package/internal/controller/element-internals.js

@@ -0,0 +1,24 @@
+/**
+ * @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 LitElement {
+ *   static formAssociated = true;
+ *
+ *   [internals] = this.attachInternals();
+ * }
+ *
+ * function getForm(element: MyElement) {
+ *   return element[internals].form;
+ * }
+ * ```
+ */
+export const internals = Symbol('internals');
+//# sourceMappingURL=element-internals.js.map

package/internal/controller/element-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-internals.js","sourceRoot":"","sources":["element-internals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\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 LitElement {\n *   static formAssociated = true;\n *\n *   [internals] = this.attachInternals();\n * }\n *\n * function getForm(element: MyElement) {\n *   return element[internals].form;\n * }\n * ```\n */\nexport const internals = Symbol('internals');\n\n/**\n * An instance with `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 WithInternals {\n  /**\n   * An instance's `ElementInternals`.\n   */\n  [internals]: ElementInternals;\n}\n"]}

package/internal/controller/form-submitter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReactiveElement } from 'lit';
+import { WithInternals } from './element-internals.js';
+/**
+ * A string indicating the form submission behavior of the element.
+ *
+ * - submit: The element submits the form. This is the default value if the
+ * attribute is not specified, or if it is dynamically changed to an empty or
+ * invalid value.
+ * - reset: The element resets the form.
+ * - button: The element does nothing.
+ */
+export type FormSubmitterType = 'button' | 'submit' | 'reset';
+/**
+ * An element that can submit or reset a `<form>`, similar to
+ * `<button type="submit">`.
+ */
+export interface FormSubmitter extends ReactiveElement, WithInternals {
+    /**
+     * A string indicating the form submission behavior of the element.
+     *
+     * - submit: The element submits the form. This is the default value if the
+     * attribute is not specified, or if it is dynamically changed to an empty or
+     * invalid value.
+     * - reset: The element resets the form.
+     * - button: The element does nothing.
+     */
+    type: FormSubmitterType;
+    /**
+     * The HTML name to use in form submission. When combined with a `value`, the
+     * submitting button's name/value will be added to the form.
+     *
+     * Names must reflect to a `name` attribute for form integration.
+     */
+    name: string;
+    /**
+     * The value of the button. When combined with a `name`, the submitting
+     * button's name/value will be added to the form.
+     */
+    value: string;
+}
+type FormSubmitterConstructor = (new () => FormSubmitter) | (abstract new () => FormSubmitter);
+/**
+ * Sets up an element's constructor to enable form submission. The element
+ * instance should be form associated and have a `type` property.
+ *
+ * A click listener is added to each element instance. If the click is not
+ * default prevented, it will submit the element's form, if any.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends LitElement {
+ *   static {
+ *     setupFormSubmitter(MyElement);
+ *   }
+ *
+ *   static formAssociated = true;
+ *
+ *   type: FormSubmitterType = 'submit';
+ *
+ *   [internals] = this.attachInternals();
+ * }
+ * ```
+ *
+ * @param ctor The form submitter element's constructor.
+ */
+export declare function setupFormSubmitter(ctor: FormSubmitterConstructor): void;
+export {};

package/internal/controller/form-submitter.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isServer } from 'lit';
+import { internals } from './element-internals.js';
+/**
+ * Sets up an element's constructor to enable form submission. The element
+ * instance should be form associated and have a `type` property.
+ *
+ * A click listener is added to each element instance. If the click is not
+ * default prevented, it will submit the element's form, if any.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends LitElement {
+ *   static {
+ *     setupFormSubmitter(MyElement);
+ *   }
+ *
+ *   static formAssociated = true;
+ *
+ *   type: FormSubmitterType = 'submit';
+ *
+ *   [internals] = this.attachInternals();
+ * }
+ * ```
+ *
+ * @param ctor The form submitter element's constructor.
+ */
+export function setupFormSubmitter(ctor) {
+    if (isServer) {
+        return;
+    }
+    ctor.addInitializer(instance => {
+        const submitter = instance;
+        submitter.addEventListener('click', async (event) => {
+            const { type, [internals]: elementInternals } = submitter;
+            const { form } = elementInternals;
+            if (!form || type === 'button') {
+                return;
+            }
+            // Wait a microtask for event bubbling to complete.
+            await new Promise(resolve => {
+                resolve();
+            });
+            if (event.defaultPrevented) {
+                return;
+            }
+            if (type === 'reset') {
+                form.reset();
+                return;
+            }
+            // form.requestSubmit(submitter) does not work with form associated custom
+            // elements. This patches the dispatched submit event to add the correct
+            // `submitter`.
+            // See https://github.com/WICG/webcomponents/issues/814
+            form.addEventListener('submit', submitEvent => {
+                Object.defineProperty(submitEvent, 'submitter', {
+                    configurable: true,
+                    enumerable: true,
+                    get: () => submitter,
+                });
+            }, { capture: true, once: true });
+            elementInternals.setFormValue(submitter.value);
+            form.requestSubmit();
+        });
+    });
+}
+//# sourceMappingURL=form-submitter.js.map

package/internal/controller/form-submitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-submitter.js","sourceRoot":"","sources":["form-submitter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,QAAQ,EAAkB,MAAM,KAAK,CAAC;AAE9C,OAAO,EAAC,SAAS,EAAgB,MAAM,wBAAwB,CAAC;AA+ChE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA8B;IAC/D,IAAI,QAAQ,EAAE;QACZ,OAAO;KACR;IAEA,IAA0C,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE;QACpE,MAAM,SAAS,GAAG,QAAyB,CAAC;QAC5C,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAChD,MAAM,EAAC,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,gBAAgB,EAAC,GAAG,SAAS,CAAC;YACxD,MAAM,EAAC,IAAI,EAAC,GAAG,gBAAgB,CAAC;YAChC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,EAAE;gBAC9B,OAAO;aACR;YAED,mDAAmD;YACnD,MAAM,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;gBAChC,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC,CAAC;YAEH,IAAI,KAAK,CAAC,gBAAgB,EAAE;gBAC1B,OAAO;aACR;YAED,IAAI,IAAI,KAAK,OAAO,EAAE;gBACpB,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO;aACR;YAED,0EAA0E;YAC1E,wEAAwE;YACxE,eAAe;YACf,uDAAuD;YACvD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE;gBAC5C,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,WAAW,EAAE;oBAC9C,YAAY,EAAE,IAAI;oBAClB,UAAU,EAAE,IAAI;oBAChB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;iBACrB,CAAC,CAAC;YACL,CAAC,EAAE,EAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAC,CAAC,CAAC;YAEhC,gBAAgB,CAAC,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC/C,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {isServer, ReactiveElement} from 'lit';\n\nimport {internals, WithInternals} from './element-internals.js';\n\n/**\n * A string indicating the form submission behavior of the element.\n *\n * - submit: The element submits the form. This is the default value if the\n * attribute is not specified, or if it is dynamically changed to an empty or\n * invalid value.\n * - reset: The element resets the form.\n * - button: The element does nothing.\n */\nexport type FormSubmitterType = 'button'|'submit'|'reset';\n\n/**\n * An element that can submit or reset a `<form>`, similar to\n * `<button type=\"submit\">`.\n */\nexport interface FormSubmitter extends ReactiveElement, WithInternals {\n  /**\n   * A string indicating the form submission behavior of the element.\n   *\n   * - submit: The element submits the form. This is the default value if the\n   * attribute is not specified, or if it is dynamically changed to an empty or\n   * invalid value.\n   * - reset: The element resets the form.\n   * - button: The element does nothing.\n   */\n  type: FormSubmitterType;\n\n  /**\n   * The HTML name to use in form submission. When combined with a `value`, the\n   * submitting button's name/value will be added to the form.\n   *\n   * Names must reflect to a `name` attribute for form integration.\n   */\n  name: string;\n\n  /**\n   * The value of the button. When combined with a `name`, the submitting\n   * button's name/value will be added to the form.\n   */\n  value: string;\n}\n\ntype FormSubmitterConstructor =\n    (new () => FormSubmitter)|(abstract new () => FormSubmitter);\n\n/**\n * Sets up an element's constructor to enable form submission. The element\n * instance should be form associated and have a `type` property.\n *\n * A click listener is added to each element instance. If the click is not\n * default prevented, it will submit the element's form, if any.\n *\n * @example\n * ```ts\n * class MyElement extends LitElement {\n *   static {\n *     setupFormSubmitter(MyElement);\n *   }\n *\n *   static formAssociated = true;\n *\n *   type: FormSubmitterType = 'submit';\n *\n *   [internals] = this.attachInternals();\n * }\n * ```\n *\n * @param ctor The form submitter element's constructor.\n */\nexport function setupFormSubmitter(ctor: FormSubmitterConstructor) {\n  if (isServer) {\n    return;\n  }\n\n  (ctor as unknown as typeof ReactiveElement).addInitializer(instance => {\n    const submitter = instance as FormSubmitter;\n    submitter.addEventListener('click', async event => {\n      const {type, [internals]: elementInternals} = submitter;\n      const {form} = elementInternals;\n      if (!form || type === 'button') {\n        return;\n      }\n\n      // Wait a microtask for event bubbling to complete.\n      await new Promise<void>(resolve => {\n        resolve();\n      });\n\n      if (event.defaultPrevented) {\n        return;\n      }\n\n      if (type === 'reset') {\n        form.reset();\n        return;\n      }\n\n      // form.requestSubmit(submitter) does not work with form associated custom\n      // elements. This patches the dispatched submit event to add the correct\n      // `submitter`.\n      // See https://github.com/WICG/webcomponents/issues/814\n      form.addEventListener('submit', submitEvent => {\n        Object.defineProperty(submitEvent, 'submitter', {\n          configurable: true,\n          enumerable: true,\n          get: () => submitter,\n        });\n      }, {capture: true, once: true});\n\n      elementInternals.setFormValue(submitter.value);\n      form.requestSubmit();\n    });\n  });\n}\n"]}

package/internal/motion/animation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Easing functions to use for web animations.
+ *
+ * **NOTE:** `EASING.EMPHASIZED` is approximated with unknown accuracy.
+ *
+ * TODO(b/241113345): replace with tokens
+ */
+export declare const EASING: {
+    readonly STANDARD: "cubic-bezier(0.2, 0, 0, 1)";
+    readonly STANDARD_ACCELERATE: "cubic-bezier(.3,0,1,1)";
+    readonly STANDARD_DECELERATE: "cubic-bezier(0,0,0,1)";
+    readonly EMPHASIZED: "cubic-bezier(.3,0,0,1)";
+    readonly EMPHASIZED_ACCELERATE: "cubic-bezier(.3,0,.8,.15)";
+    readonly EMPHASIZED_DECELERATE: "cubic-bezier(.05,.7,.1,1)";
+};
+/**
+ * A signal that is used for abortable tasks.
+ */
+export interface AnimationSignal {
+    /**
+     * Starts the abortable task. Any previous tasks started with this instance
+     * will be aborted.
+     *
+     * @return An `AbortSignal` for the current task.
+     */
+    start(): AbortSignal;
+    /**
+     * Complete the current task.
+     */
+    finish(): void;
+}
+/**
+ * Creates an `AnimationSignal` that can be used to cancel a previous task.
+ *
+ * @example
+ * class MyClass {
+ *   private labelAnimationSignal = createAnimationSignal();
+ *
+ *   private async animateLabel() {
+ *     // Start of the task. Previous tasks will be canceled.
+ *     const signal = this.labelAnimationSignal.start();
+ *
+ *     // Do async work...
+ *     if (signal.aborted) {
+ *       // Use AbortSignal to check if a request was made to abort after some
+ *       // asynchronous work.
+ *       return;
+ *     }
+ *
+ *     const animation = this.animate(...);
+ *     // Add event listeners to be notified when the task should be canceled.
+ *     signal.addEventListener('abort', () => {
+ *       animation.cancel();
+ *     });
+ *
+ *     animation.addEventListener('finish', () => {
+ *       // Tell the signal that the current task is finished.
+ *       this.labelAnimationSignal.finish();
+ *     });
+ *   }
+ * }
+ *
+ * @return An `AnimationSignal`.
+ */
+export declare function createAnimationSignal(): AnimationSignal;
+/**
+ * Returns a function which can be used to throttle function calls
+ * mapped to a key via a given function that should produce a promise that
+ * determines the throttle amount (defaults to requestAnimationFrame).
+ */
+export declare function createThrottle(): (key: string, cb: (...args: unknown[]) => unknown, timeout?: () => Promise<void>) => Promise<void>;
+/**
+ * Parses an number in milliseconds from a css time value
+ */
+export declare function msFromTimeCSSValue(value: string): number;