@material/web 1.0.0-pre.1 → 1.0.0-pre.11

package/internal/aria/aria.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Accessibility Object Model reflective aria property name types.
+ */
+export type ARIAProperty = Exclude<keyof ARIAMixin, 'role'>;
+/**
+ * Accessibility Object Model reflective aria properties.
+ */
+export declare const ARIA_PROPERTIES: ARIAProperty[];
+/**
+ * Accessibility Object Model aria attribute name types.
+ */
+export type ARIAAttribute = ARIAPropertyToAttribute<ARIAProperty>;
+/**
+ * Accessibility Object Model aria attributes.
+ */
+export declare const ARIA_ATTRIBUTES: ("aria-atomic" | "aria-autocomplete" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colindextext" | "aria-colspan" | "aria-current" | "aria-disabled" | "aria-expanded" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-label" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowindextext" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext")[];
+/**
+ * Checks if an attribute is one of the AOM aria attributes.
+ *
+ * @example
+ * isAriaAttribute('aria-label'); // true
+ *
+ * @param attribute The attribute to check.
+ * @return True if the attribute is an aria attribute, or false if not.
+ */
+export declare function isAriaAttribute(attribute: string): attribute is ARIAAttribute;
+/**
+ * Converts an AOM aria property into its corresponding attribute.
+ *
+ * @example
+ * ariaPropertyToAttribute('ariaLabel'); // 'aria-label'
+ *
+ * @param property The aria property.
+ * @return The aria attribute.
+ */
+export declare function ariaPropertyToAttribute<K extends ARIAProperty | 'role'>(property: K): ARIAPropertyToAttribute<K>;
+type ARIAPropertyToAttribute<K extends string> = K extends `aria${infer Suffix}Element${infer OptS}` ? `aria-${Lowercase<Suffix>}` : K extends `aria${infer Suffix}` ? `aria-${Lowercase<Suffix>}` : K;
+/**
+ * An extension of `ARIAMixin` that enforces strict value types for aria
+ * properties.
+ *
+ * This is needed for correct typing in render functions with lit analyzer.
+ *
+ * @example
+ * render() {
+ *   const {ariaLabel} = this as ARIAMixinStrict;
+ *   return html`
+ *     <button aria-label=${ariaLabel || nothing}>
+ *       <slot></slot>
+ *     </button>
+ *   `;
+ * }
+ */
+export interface ARIAMixinStrict extends ARIAMixin {
+    ariaAtomic: 'true' | 'false' | null;
+    ariaAutoComplete: 'none' | 'inline' | 'list' | 'both' | null;
+    ariaBusy: 'true' | 'false' | null;
+    ariaChecked: 'true' | 'false' | null;
+    ariaColCount: `${number}` | null;
+    ariaColIndex: `${number}` | null;
+    ariaColSpan: `${number}` | null;
+    ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' | null;
+    ariaDisabled: 'true' | 'false' | null;
+    ariaExpanded: 'true' | 'false' | null;
+    ariaHasPopup: 'false' | 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | null;
+    ariaHidden: 'true' | 'false' | null;
+    ariaInvalid: 'true' | 'false' | null;
+    ariaKeyShortcuts: string | null;
+    ariaLabel: string | null;
+    ariaLevel: `${number}` | null;
+    ariaLive: 'assertive' | 'off' | 'polite' | null;
+    ariaModal: 'true' | 'false' | null;
+    ariaMultiLine: 'true' | 'false' | null;
+    ariaMultiSelectable: 'true' | 'false' | null;
+    ariaOrientation: 'horizontal' | 'vertical' | 'undefined' | null;
+    ariaPlaceholder: string | null;
+    ariaPosInSet: `${number}` | null;
+    ariaPressed: 'true' | 'false' | null;
+    ariaReadOnly: 'true' | 'false' | null;
+    ariaRequired: 'true' | 'false' | null;
+    ariaRoleDescription: string | null;
+    ariaRowCount: `${number}` | null;
+    ariaRowIndex: `${number}` | null;
+    ariaRowSpan: `${number}` | null;
+    ariaSelected: 'true' | 'false' | null;
+    ariaSetSize: `${number}` | null;
+    ariaSort: 'ascending' | 'descending' | 'none' | 'other' | null;
+    ariaValueMax: `${number}` | null;
+    ariaValueMin: `${number}` | null;
+    ariaValueNow: `${number}` | null;
+    ariaValueText: string | null;
+    role: ARIARole | null;
+}
+/**
+ * Valid values for `role`.
+ */
+export type ARIARole = 'alert' | 'alertdialog' | 'button' | 'checkbox' | 'dialog' | 'gridcell' | 'link' | 'log' | 'marquee' | 'menuitem' | 'menuitemcheckbox' | 'menuitemradio' | 'option' | 'progressbar' | 'radio' | 'scrollbar' | 'searchbox' | 'slider' | 'spinbutton' | 'status' | 'switch' | 'tab' | 'tabpanel' | 'textbox' | 'timer' | 'tooltip' | 'treeitem' | 'combobox' | 'grid' | 'listbox' | 'menu' | 'menubar' | 'radiogroup' | 'tablist' | 'tree' | 'treegrid' | 'application' | 'article' | 'cell' | 'columnheader' | 'definition' | 'directory' | 'document' | 'feed' | 'figure' | 'group' | 'heading' | 'img' | 'list' | 'listitem' | 'math' | 'none' | 'note' | 'presentation' | 'region' | 'row' | 'rowgroup' | 'rowheader' | 'separator' | 'table' | 'term' | 'text' | 'toolbar' | 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search' | 'doc-abstract' | 'doc-acknowledgments' | 'doc-afterword' | 'doc-appendix' | 'doc-backlink' | 'doc-biblioentry' | 'doc-bibliography' | 'doc-biblioref' | 'doc-chapter' | 'doc-colophon' | 'doc-conclusion' | 'doc-cover' | 'doc-credit' | 'doc-credits' | 'doc-dedication' | 'doc-endnote' | 'doc-endnotes' | 'doc-epigraph' | 'doc-epilogue' | 'doc-errata' | 'doc-example' | 'doc-footnote' | 'doc-foreword' | 'doc-glossary' | 'doc-glossref' | 'doc-index' | 'doc-introduction' | 'doc-noteref' | 'doc-notice' | 'doc-pagebreak' | 'doc-pagelist' | 'doc-part' | 'doc-preface' | 'doc-prologue' | 'doc-pullquote' | 'doc-qna' | 'doc-subtitle' | 'doc-tip' | 'doc-toc';
+export {};

package/internal/aria/aria.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Accessibility Object Model reflective aria properties.
+ */
+export const ARIA_PROPERTIES = [
+    'ariaAtomic',
+    'ariaAutoComplete',
+    'ariaBusy',
+    'ariaChecked',
+    'ariaColCount',
+    'ariaColIndex',
+    'ariaColSpan',
+    'ariaCurrent',
+    'ariaDisabled',
+    'ariaExpanded',
+    'ariaHasPopup',
+    'ariaHidden',
+    'ariaInvalid',
+    'ariaKeyShortcuts',
+    'ariaLabel',
+    'ariaLevel',
+    'ariaLive',
+    'ariaModal',
+    'ariaMultiLine',
+    'ariaMultiSelectable',
+    'ariaOrientation',
+    'ariaPlaceholder',
+    'ariaPosInSet',
+    'ariaPressed',
+    'ariaReadOnly',
+    'ariaRequired',
+    'ariaRoleDescription',
+    'ariaRowCount',
+    'ariaRowIndex',
+    'ariaRowSpan',
+    'ariaSelected',
+    'ariaSetSize',
+    'ariaSort',
+    'ariaValueMax',
+    'ariaValueMin',
+    'ariaValueNow',
+    'ariaValueText',
+];
+/**
+ * Accessibility Object Model aria attributes.
+ */
+export const ARIA_ATTRIBUTES = ARIA_PROPERTIES.map(ariaPropertyToAttribute);
+/**
+ * Checks if an attribute is one of the AOM aria attributes.
+ *
+ * @example
+ * isAriaAttribute('aria-label'); // true
+ *
+ * @param attribute The attribute to check.
+ * @return True if the attribute is an aria attribute, or false if not.
+ */
+export function isAriaAttribute(attribute) {
+    return attribute.startsWith('aria-');
+}
+/**
+ * Converts an AOM aria property into its corresponding attribute.
+ *
+ * @example
+ * ariaPropertyToAttribute('ariaLabel'); // 'aria-label'
+ *
+ * @param property The aria property.
+ * @return The aria attribute.
+ */
+export function ariaPropertyToAttribute(property) {
+    return property
+        .replace('aria', 'aria-')
+        // IDREF attributes also include an "Element" or "Elements" suffix
+        .replace(/Elements?/g, '')
+        .toLowerCase();
+}
+//# sourceMappingURL=aria.js.map

package/internal/aria/aria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria.js","sourceRoot":"","sources":["aria.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,YAAY;IACZ,kBAAkB;IAClB,UAAU;IACV,aAAa;IACb,cAAc;IACd,cAAc;IACd,aAAa;IACb,aAAa;IACb,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,aAAa;IACb,kBAAkB;IAClB,WAAW;IACX,WAAW;IACX,UAAU;IACV,WAAW;IACX,eAAe;IACf,qBAAqB;IACrB,iBAAiB;IACjB,iBAAiB;IACjB,cAAc;IACd,aAAa;IACb,cAAc;IACd,cAAc;IACd,qBAAqB;IACrB,cAAc;IACd,cAAc;IACd,aAAa;IACb,cAAc;IACd,aAAa;IACb,UAAU;IACV,cAAc;IACd,cAAc;IACd,cAAc;IACd,eAAe;CAChB,CAAC;AAOF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACnC,QAAW;IACb,OAAO,QAAQ;SACH,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,kEAAkE;SACjE,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;SACzB,WAAW,EAAgC,CAAC;AAC1D,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/**\n * Accessibility Object Model reflective aria property name types.\n */\nexport type ARIAProperty = Exclude<keyof ARIAMixin, 'role'>;\n\n/**\n * Accessibility Object Model reflective aria properties.\n */\nexport const ARIA_PROPERTIES: ARIAProperty[] = [\n  'ariaAtomic',\n  'ariaAutoComplete',\n  'ariaBusy',\n  'ariaChecked',\n  'ariaColCount',\n  'ariaColIndex',\n  'ariaColSpan',\n  'ariaCurrent',\n  'ariaDisabled',\n  'ariaExpanded',\n  'ariaHasPopup',\n  'ariaHidden',\n  'ariaInvalid',\n  'ariaKeyShortcuts',\n  'ariaLabel',\n  'ariaLevel',\n  'ariaLive',\n  'ariaModal',\n  'ariaMultiLine',\n  'ariaMultiSelectable',\n  'ariaOrientation',\n  'ariaPlaceholder',\n  'ariaPosInSet',\n  'ariaPressed',\n  'ariaReadOnly',\n  'ariaRequired',\n  'ariaRoleDescription',\n  'ariaRowCount',\n  'ariaRowIndex',\n  'ariaRowSpan',\n  'ariaSelected',\n  'ariaSetSize',\n  'ariaSort',\n  'ariaValueMax',\n  'ariaValueMin',\n  'ariaValueNow',\n  'ariaValueText',\n];\n\n/**\n * Accessibility Object Model aria attribute name types.\n */\nexport type ARIAAttribute = ARIAPropertyToAttribute<ARIAProperty>;\n\n/**\n * Accessibility Object Model aria attributes.\n */\nexport const ARIA_ATTRIBUTES = ARIA_PROPERTIES.map(ariaPropertyToAttribute);\n\n/**\n * Checks if an attribute is one of the AOM aria attributes.\n *\n * @example\n * isAriaAttribute('aria-label'); // true\n *\n * @param attribute The attribute to check.\n * @return True if the attribute is an aria attribute, or false if not.\n */\nexport function isAriaAttribute(attribute: string): attribute is ARIAAttribute {\n  return attribute.startsWith('aria-');\n}\n\n/**\n * Converts an AOM aria property into its corresponding attribute.\n *\n * @example\n * ariaPropertyToAttribute('ariaLabel'); // 'aria-label'\n *\n * @param property The aria property.\n * @return The aria attribute.\n */\nexport function ariaPropertyToAttribute<K extends ARIAProperty|'role'>(\n    property: K) {\n  return property\n             .replace('aria', 'aria-')\n             // IDREF attributes also include an \"Element\" or \"Elements\" suffix\n             .replace(/Elements?/g, '')\n             .toLowerCase() as ARIAPropertyToAttribute<K>;\n}\n\n// Converts an `ariaFoo` string type to an `aria-foo` string type.\ntype ARIAPropertyToAttribute<K extends string> =\n    K extends `aria${infer Suffix}Element${infer OptS}` ?\n    `aria-${Lowercase < Suffix >}` :\n    K extends `aria${infer Suffix}` ? `aria-${Lowercase < Suffix >}` : K;\n\n/**\n * An extension of `ARIAMixin` that enforces strict value types for aria\n * properties.\n *\n * This is needed for correct typing in render functions with lit analyzer.\n *\n * @example\n * render() {\n *   const {ariaLabel} = this as ARIAMixinStrict;\n *   return html`\n *     <button aria-label=${ariaLabel || nothing}>\n *       <slot></slot>\n *     </button>\n *   `;\n * }\n */\nexport interface ARIAMixinStrict extends ARIAMixin {\n  ariaAtomic: 'true'|'false'|null;\n  ariaAutoComplete: 'none'|'inline'|'list'|'both'|null;\n  ariaBusy: 'true'|'false'|null;\n  ariaChecked: 'true'|'false'|null;\n  ariaColCount: `${number}`|null;\n  ariaColIndex: `${number}`|null;\n  ariaColSpan: `${number}`|null;\n  ariaCurrent: 'page'|'step'|'location'|'date'|'time'|'true'|'false'|null;\n  ariaDisabled: 'true'|'false'|null;\n  ariaExpanded: 'true'|'false'|null;\n  ariaHasPopup: 'false'|'true'|'menu'|'listbox'|'tree'|'grid'|'dialog'|null;\n  ariaHidden: 'true'|'false'|null;\n  ariaInvalid: 'true'|'false'|null;\n  ariaKeyShortcuts: string|null;\n  ariaLabel: string|null;\n  ariaLevel: `${number}`|null;\n  ariaLive: 'assertive'|'off'|'polite'|null;\n  ariaModal: 'true'|'false'|null;\n  ariaMultiLine: 'true'|'false'|null;\n  ariaMultiSelectable: 'true'|'false'|null;\n  ariaOrientation: 'horizontal'|'vertical'|'undefined'|null;\n  ariaPlaceholder: string|null;\n  ariaPosInSet: `${number}`|null;\n  ariaPressed: 'true'|'false'|null;\n  ariaReadOnly: 'true'|'false'|null;\n  ariaRequired: 'true'|'false'|null;\n  ariaRoleDescription: string|null;\n  ariaRowCount: `${number}`|null;\n  ariaRowIndex: `${number}`|null;\n  ariaRowSpan: `${number}`|null;\n  ariaSelected: 'true'|'false'|null;\n  ariaSetSize: `${number}`|null;\n  ariaSort: 'ascending'|'descending'|'none'|'other'|null;\n  ariaValueMax: `${number}`|null;\n  ariaValueMin: `${number}`|null;\n  ariaValueNow: `${number}`|null;\n  ariaValueText: string|null;\n  role: ARIARole|null;\n}\n\n/**\n * Valid values for `role`.\n */\nexport type ARIARole =\n    'alert'|'alertdialog'|'button'|'checkbox'|'dialog'|'gridcell'|'link'|'log'|\n    'marquee'|'menuitem'|'menuitemcheckbox'|'menuitemradio'|'option'|\n    'progressbar'|'radio'|'scrollbar'|'searchbox'|'slider'|'spinbutton'|\n    'status'|'switch'|'tab'|'tabpanel'|'textbox'|'timer'|'tooltip'|'treeitem'|\n    'combobox'|'grid'|'listbox'|'menu'|'menubar'|'radiogroup'|'tablist'|'tree'|\n    'treegrid'|'application'|'article'|'cell'|'columnheader'|'definition'|\n    'directory'|'document'|'feed'|'figure'|'group'|'heading'|'img'|'list'|\n    'listitem'|'math'|'none'|'note'|'presentation'|'region'|'row'|'rowgroup'|\n    'rowheader'|'separator'|'table'|'term'|'text'|'toolbar'|'banner'|\n    'complementary'|'contentinfo'|'form'|'main'|'navigation'|'region'|'search'|\n    'doc-abstract'|'doc-acknowledgments'|'doc-afterword'|'doc-appendix'|\n    'doc-backlink'|'doc-biblioentry'|'doc-bibliography'|'doc-biblioref'|\n    'doc-chapter'|'doc-colophon'|'doc-conclusion'|'doc-cover'|'doc-credit'|\n    'doc-credits'|'doc-dedication'|'doc-endnote'|'doc-endnotes'|'doc-epigraph'|\n    'doc-epilogue'|'doc-errata'|'doc-example'|'doc-footnote'|'doc-foreword'|\n    'doc-glossary'|'doc-glossref'|'doc-index'|'doc-introduction'|'doc-noteref'|\n    'doc-notice'|'doc-pagebreak'|'doc-pagelist'|'doc-part'|'doc-preface'|\n    'doc-prologue'|'doc-pullquote'|'doc-qna'|'doc-subtitle'|'doc-tip'|'doc-toc';\n"]}

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(this);
+ *   }
+ *
+ *   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(this);
+ *   }
+ *
+ *   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(this);\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,113 @@
+/**
+ * @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;
+    /**
+     * 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.
+     */
+    readonly 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;
+    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,115 @@
+/**
+ * @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;
+    }
+    /**
+     * 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 {ReactiveController, ReactiveControllerHost, isServer} 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   * The element that controls the visibility of the attachable element. It is\n   * 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  readonly 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\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"]}