igniteui-webcomponents 7.3.1 → 7.4.0

package/internals/controllers/aria-projection.d.ts

@@ -2,14 +2,12 @@ import { type LitElement, type ReactiveController, type ReactiveControllerHost }
 import { Directive, type DirectiveParameters, type ElementPart, type PartInfo } from 'lit/directive.js';
 type ControllerHost = ReactiveControllerHost & LitElement;
 /**
- * ARIA semantics a composite host projects onto the native editor of an
- * input-shaped component.
+ * The ARIA semantics that a composite host projects onto the native editor.
  *
- * The host cannot publish these itself: it delegates focus, so the native
- * editor inside the input component's shadow root is what assistive technology
- * lands on and reports. All relations travel as element references - an IDREF
- * cannot cross a shadow boundary, while ARIA element reflection resolves into
- * ancestor tree scopes.
+ * @remarks
+ * The host delegates focus, so assistive technology lands on the editor of
+ * the input-shaped component and reports it. Every relation travels as an
+ * element reference, because an IDREF does not cross a shadow boundary.
  */
 export type ProjectedARIA = {
     role?: string;
@@ -22,21 +20,17 @@ export type ProjectedARIA = {
     labelledBy?: ReadonlyArray<Element> | null;
     activeDescendant?: Element | null;
 };
-/** Configuration for the {@link AriaTargetController}. */
 type AriaTargetConfig = {
     /** Resolves the component's own `ElementInternals` labels. */
     labels: () => ReadonlyArray<Element> | null;
-    /**
-     * Resolves the component's own description element (its helper-text
-     * container), or `null` when it currently renders no description content.
-     */
+    /** Resolves the helper-text container, or `null` when there is none. */
     description: () => Element | null;
 };
 /**
- * Binding values for a native editor element, resolved from the projected
- * state merged with the editor's own ARIA. Applied onto the editor with the
- * {@link ariaBindings} directive: scalars bind as attributes, relations bind
- * through the ARIA element-reflection properties.
+ * The binding values for a native editor element, resolved from the projected
+ * state and the own ARIA of the editor, and applied by the
+ * {@link ariaBindings} directive. A scalar binds as an attribute, a relation
+ * through an ARIA element-reflection property.
  */
 export type ResolvedARIABindings = {
     role?: string;
@@ -45,9 +39,9 @@ export type ResolvedARIABindings = {
     disabled?: string;
     label?: string;
     /**
-     * Same-root IDREF for the editor's own description, applied while no
-     * description is projected. Unlike element reflection, a content attribute
-     * stays visible to tooling that only reads attributes (e.g. axe).
+     * The same-root IDREF for the own description of the editor. It applies
+     * while the host projects no description, so tooling that reads attributes
+     * only, for example axe, still sees a content attribute.
      */
     describedByRef?: string;
     labelledBy: ReadonlyArray<Element> | null;
@@ -56,47 +50,56 @@ export type ResolvedARIABindings = {
     activeDescendant: Element | null;
 };
 /**
- * The receiving end of an ARIA projection, added by every input-shaped
- * component. Holds the state a composite host currently projects and resolves
- * it against the component's own ARIA when the native editor is rendered.
+ * The receiving end of an ARIA projection. Every input-shaped component adds
+ * it to hold the state that a composite host projects, and resolves that
+ * state against its own ARIA.
  *
- * Not a reactive controller - it needs no lifecycle hooks, only a render
- * scheduled on the host when the projected state changes.
+ * @remarks
+ * Not a reactive controller: it needs only a host render when the projected
+ * state changes.
  */
 declare class AriaTargetController {
     private readonly _host;
     private readonly _config;
     private _projected;
+    /** The bindings last resolved for the native editor. */
+    private _resolved?;
     constructor(host: ControllerHost, config: AriaTargetConfig);
     /**
-     * Replaces the projected state, scheduling a host render only when it
-     * actually changed so projecting on every host update stays cheap.
+     * Replaces the projected state.
+     *
+     * @remarks
+     * A host render happens only when the resolved bindings change, so a
+     * projection on every host update stays inexpensive. The comparison uses
+     * the resolved bindings, so it also catches a change to the own labels or
+     * description, which the component cannot observe.
      */
     setProjected(state: ProjectedARIA): void;
     /**
-     * Mirrors the projected `role`/`hasPopup` as `data-role`/`data-haspopup`
-     * attributes on the component itself. The input themes style anchors of
-     * composite widgets differently and key off these; the ARIA itself lives on
-     * the native editor inside the shadow root, where `:host()` selectors
-     * cannot observe it.
+     * Mirrors the projected `role` and `hasPopup` onto `data-role` and
+     * `data-haspopup`.
+     *
+     * @remarks
+     * The input themes style the anchor of a composite widget from these
+     * attributes. The ARIA itself stays on the editor in the shadow root, where
+     * a `:host()` selector cannot observe it.
      */
     private _reflectStylingHooks;
     /**
-     * Resolves the binding values for the native editor element by merging the
-     * projected state with the editor's own ARIA.
+     * Resolves the binding values for the native editor element.
      *
-     * Projected labels take precedence over the component's own. The editor's
-     * description stays a same-root IDREF ({@link ResolvedARIABindings.describedByRef})
-     * while nothing is projected; once a host projects a description, the whole
-     * relation switches to element references - attribute and reflection cannot
-     * coexist - with the editor's own description element joining the projected
-     * ones.
+     * @remarks
+     * A projected label wins over the own label of the component. The
+     * description stays a same-root IDREF while the host projects none, and the
+     * whole relation switches to element references afterwards, because an
+     * attribute and a reflection cannot coexist. See
+     * {@link ResolvedARIABindings.describedByRef}.
      */
     resolveBindings(): ResolvedARIABindings;
 }
 /**
- * Applies {@link ResolvedARIABindings} onto the native editor element -
- * relations on every render, scalar attributes only when they changed.
+ * Applies {@link ResolvedARIABindings} onto the native editor element. It
+ * applies a relation on every render, and a scalar only on a change.
  */
 declare class AriaBindingsDirective extends Directive {
     private _previous?;
@@ -105,21 +108,20 @@ declare class AriaBindingsDirective extends Directive {
     update(part: ElementPart, [bindings]: DirectiveParameters<this>): unknown;
 }
 /**
- * Binds resolved ARIA state onto a native editor element as a single element
- * expression, e.g. `<input ${ariaBindings(aria)} />`.
+ * Binds the resolved ARIA state onto a native editor element as one element
+ * expression, for example `<input ${ariaBindings(aria)} />`.
  */
 export declare const ariaBindings: (_: ResolvedARIABindings) => import("lit-html/directive.js").DirectiveResult<typeof AriaBindingsDirective>;
-/** Configuration for the {@link AriaProjectorController}. */
 type AriaProjectorConfig = {
-    /** Resolves the input-shaped component the ARIA state is projected onto. */
+    /** Resolves the input-shaped component that receives the ARIA state. */
     target: () => Element | null | undefined;
-    /** Computes the ARIA state to project. Invoked after every host update. */
+    /** Computes the ARIA state to project, after every host update. */
     state: () => ProjectedARIA;
 };
 /**
- * The sending end of an ARIA projection, added by composite hosts
- * (e.g. `igc-select`). After every host update it pushes the computed ARIA
- * state onto the target component's {@link AriaTargetController}.
+ * The sending end of an ARIA projection. A composite host such as
+ * `igc-select` adds it to push the computed ARIA state onto the
+ * {@link AriaTargetController} of the target after every host update.
  */
 declare class AriaProjectorController implements ReactiveController {
     private readonly _host;
@@ -130,15 +132,14 @@ declare class AriaProjectorController implements ReactiveController {
     hostUpdated(): void;
 }
 /**
- * Creates and adds an {@link AriaTargetController} to an input-shaped
- * component, making its native editor a valid target for
- * {@link addAriaProjector} - the editor is what assistive technology lands on
- * and reports once the component's host delegates focus to it.
+ * Creates an {@link AriaTargetController} and adds it to an input-shaped
+ * component. It makes the native editor of the component a valid target for
+ * {@link addAriaProjector}.
  */
 export declare function addAriaTarget(host: ControllerHost, config: AriaTargetConfig): AriaTargetController;
 /**
- * Creates and adds an {@link AriaProjectorController} to a composite host,
- * projecting ARIA semantics onto the native editor of the target component.
+ * Creates an {@link AriaProjectorController} and adds it to a composite host.
+ * It projects ARIA onto the native editor of the target component.
  */
 export declare function addAriaProjector(host: ControllerHost, config: AriaProjectorConfig): AriaProjectorController;
 export type { AriaProjectorController, AriaTargetController };

package/internals/controllers/aria-projection.js

@@ -1,22 +1,19 @@
 import { noChange, } from 'lit';
 import { Directive, directive, PartType, } from 'lit/directive.js';
+import { sameItems } from '../utils/arrays.js';
 const targets = new WeakMap();
-function elementsEqual(a, b) {
-    if (a == null || b == null) {
-        return a == null && b == null;
-    }
-    return a.length === b.length && a.every((element, i) => element === b[i]);
-}
-function projectionsEqual(a, b) {
-    return (a.role === b.role &&
+function bindingsEqual(a, b) {
+    return (a !== undefined &&
+        a.role === b.role &&
         a.hasPopup === b.hasPopup &&
         a.expanded === b.expanded &&
         a.disabled === b.disabled &&
         a.label === b.label &&
-        (a.activeDescendant ?? null) === (b.activeDescendant ?? null) &&
-        elementsEqual(a.controls, b.controls) &&
-        elementsEqual(a.describedBy, b.describedBy) &&
-        elementsEqual(a.labelledBy, b.labelledBy));
+        a.describedByRef === b.describedByRef &&
+        a.activeDescendant === b.activeDescendant &&
+        sameItems(a.controls, b.controls) &&
+        sameItems(a.describedBy, b.describedBy) &&
+        sameItems(a.labelledBy, b.labelledBy));
 }
 class AriaTargetController {
     constructor(host, config) {
@@ -26,8 +23,9 @@ class AriaTargetController {
         targets.set(host, this);
     }
     setProjected(state) {
-        if (!projectionsEqual(this._projected, state)) {
-            this._projected = state;
+        const previous = this._resolved;
+        this._projected = state;
+        if (!bindingsEqual(previous, this.resolveBindings())) {
             this._reflectStylingHooks();
             this._host.requestUpdate();
         }
@@ -45,7 +43,7 @@ class AriaTargetController {
     resolveBindings() {
         const projected = this._projected;
         const description = this._config.description();
-        return {
+        this._resolved = {
             role: projected.role,
             hasPopup: projected.hasPopup,
             expanded: projected.expanded,
@@ -63,6 +61,7 @@ class AriaTargetController {
                 : description?.id || undefined,
             activeDescendant: projected.activeDescendant ?? null,
         };
+        return this._resolved;
     }
 }
 const scalarBindings = [

package/internals/controllers/aria-projection.js.map

@@ -1 +1 @@
-{"version":3,"file":"aria-projection.js","sourceRoot":"","sources":["../../../src/internals/controllers/aria-projection.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type LitElement,\n  noChange,\n  type ReactiveController,\n  type ReactiveControllerHost,\n} from 'lit';\nimport {\n  Directive,\n  type DirectiveParameters,\n  directive,\n  type ElementPart,\n  type PartInfo,\n  PartType,\n} from 'lit/directive.js';\n\ntype ControllerHost = ReactiveControllerHost & LitElement;\n\n/**\n * ARIA semantics a composite host projects onto the native editor of an\n * input-shaped component.\n *\n * The host cannot publish these itself: it delegates focus, so the native\n * editor inside the input component's shadow root is what assistive technology\n * lands on and reports. All relations travel as element references - an IDREF\n * cannot cross a shadow boundary, while ARIA element reflection resolves into\n * ancestor tree scopes.\n */\nexport type ProjectedARIA = {\n  role?: string;\n  hasPopup?: string;\n  expanded?: string;\n  disabled?: string;\n  label?: string;\n  controls?: ReadonlyArray<Element> | null;\n  describedBy?: ReadonlyArray<Element> | null;\n  labelledBy?: ReadonlyArray<Element> | null;\n  activeDescendant?: Element | null;\n};\n\n/** Configuration for the {@link AriaTargetController}. */\ntype AriaTargetConfig = {\n  /** Resolves the component's own `ElementInternals` labels. */\n  labels: () => ReadonlyArray<Element> | null;\n  /**\n   * Resolves the component's own description element (its helper-text\n   * container), or `null` when it currently renders no description content.\n   */\n  description: () => Element | null;\n};\n\n/**\n * Binding values for a native editor element, resolved from the projected\n * state merged with the editor's own ARIA. Applied onto the editor with the\n * {@link ariaBindings} directive: scalars bind as attributes, relations bind\n * through the ARIA element-reflection properties.\n */\nexport type ResolvedARIABindings = {\n  role?: string;\n  hasPopup?: string;\n  expanded?: string;\n  disabled?: string;\n  label?: string;\n  /**\n   * Same-root IDREF for the editor's own description, applied while no\n   * description is projected. Unlike element reflection, a content attribute\n   * stays visible to tooling that only reads attributes (e.g. axe).\n   */\n  describedByRef?: string;\n  labelledBy: ReadonlyArray<Element> | null;\n  controls: ReadonlyArray<Element> | null;\n  describedBy: ReadonlyArray<Element> | null;\n  activeDescendant: Element | null;\n};\n\n/**\n * Internal registry resolving an input-shaped component to its ARIA target\n * controller, so composite hosts can project state without the component\n * exposing a public member for it.\n */\nconst targets = new WeakMap<Element, AriaTargetController>();\n\nfunction elementsEqual(\n  a: ReadonlyArray<Element> | null | undefined,\n  b: ReadonlyArray<Element> | null | undefined\n): boolean {\n  if (a == null || b == null) {\n    return a == null && b == null;\n  }\n\n  return a.length === b.length && a.every((element, i) => element === b[i]);\n}\n\nfunction projectionsEqual(a: ProjectedARIA, b: ProjectedARIA): boolean {\n  return (\n    a.role === b.role &&\n    a.hasPopup === b.hasPopup &&\n    a.expanded === b.expanded &&\n    a.disabled === b.disabled &&\n    a.label === b.label &&\n    (a.activeDescendant ?? null) === (b.activeDescendant ?? null) &&\n    elementsEqual(a.controls, b.controls) &&\n    elementsEqual(a.describedBy, b.describedBy) &&\n    elementsEqual(a.labelledBy, b.labelledBy)\n  );\n}\n\n/**\n * The receiving end of an ARIA projection, added by every input-shaped\n * component. Holds the state a composite host currently projects and resolves\n * it against the component's own ARIA when the native editor is rendered.\n *\n * Not a reactive controller - it needs no lifecycle hooks, only a render\n * scheduled on the host when the projected state changes.\n */\nclass AriaTargetController {\n  private readonly _host: ControllerHost;\n  private readonly _config: AriaTargetConfig;\n  private _projected: ProjectedARIA = {};\n\n  constructor(host: ControllerHost, config: AriaTargetConfig) {\n    this._host = host;\n    this._config = config;\n    targets.set(host, this);\n  }\n\n  /**\n   * Replaces the projected state, scheduling a host render only when it\n   * actually changed so projecting on every host update stays cheap.\n   */\n  public setProjected(state: ProjectedARIA): void {\n    if (!projectionsEqual(this._projected, state)) {\n      this._projected = state;\n      this._reflectStylingHooks();\n      this._host.requestUpdate();\n    }\n  }\n\n  /**\n   * Mirrors the projected `role`/`hasPopup` as `data-role`/`data-haspopup`\n   * attributes on the component itself. The input themes style anchors of\n   * composite widgets differently and key off these; the ARIA itself lives on\n   * the native editor inside the shadow root, where `:host()` selectors\n   * cannot observe it.\n   */\n  private _reflectStylingHooks(): void {\n    const host = this._host;\n    const { role, hasPopup } = this._projected;\n\n    role\n      ? host.setAttribute('data-role', role)\n      : host.removeAttribute('data-role');\n    hasPopup\n      ? host.setAttribute('data-haspopup', hasPopup)\n      : host.removeAttribute('data-haspopup');\n  }\n\n  /**\n   * Resolves the binding values for the native editor element by merging the\n   * projected state with the editor's own ARIA.\n   *\n   * Projected labels take precedence over the component's own. The editor's\n   * description stays a same-root IDREF ({@link ResolvedARIABindings.describedByRef})\n   * while nothing is projected; once a host projects a description, the whole\n   * relation switches to element references - attribute and reflection cannot\n   * coexist - with the editor's own description element joining the projected\n   * ones.\n   */\n  public resolveBindings(): ResolvedARIABindings {\n    const projected = this._projected;\n    const description = this._config.description();\n\n    return {\n      role: projected.role,\n      hasPopup: projected.hasPopup,\n      expanded: projected.expanded,\n      disabled: projected.disabled,\n      label: projected.label,\n      labelledBy: projected.labelledBy ?? this._config.labels(),\n      controls: projected.controls ?? null,\n      describedBy: projected.describedBy\n        ? description\n          ? [description, ...projected.describedBy]\n          : projected.describedBy\n        : null,\n      describedByRef: projected.describedBy\n        ? undefined\n        : description?.id || undefined,\n      activeDescendant: projected.activeDescendant ?? null,\n    };\n  }\n}\n\nconst scalarBindings = [\n  ['role', 'role'],\n  ['hasPopup', 'aria-haspopup'],\n  ['expanded', 'aria-expanded'],\n  ['disabled', 'aria-disabled'],\n  ['label', 'aria-label'],\n  ['describedByRef', 'aria-describedby'],\n] as const;\n\n/**\n * Applies {@link ResolvedARIABindings} onto the native editor element -\n * relations on every render, scalar attributes only when they changed.\n */\nclass AriaBindingsDirective extends Directive {\n  private _previous?: ResolvedARIABindings;\n\n  constructor(partInfo: PartInfo) {\n    super(partInfo);\n\n    if (partInfo.type !== PartType.ELEMENT) {\n      throw new Error(\n        '`ariaBindings()` can only be used as an element expression.'\n      );\n    }\n  }\n\n  public override render(_: ResolvedARIABindings): unknown {\n    return noChange;\n  }\n\n  public override update(\n    part: ElementPart,\n    [bindings]: DirectiveParameters<this>\n  ): unknown {\n    const element = part.element;\n    const previous = this._previous;\n    this._previous = bindings;\n\n    // Relations are re-asserted on every render: element references assigned\n    // while the editor is detached (its first render commits inside the\n    // template fragment) are dropped by the browser, so memoizing them here\n    // would leave the associations permanently missing.\n    // Assigning them first also means the scalar pass below always observes\n    // the final state, since a reflection property detaches the corresponding\n    // content attribute.\n    element.ariaLabelledByElements = bindings.labelledBy;\n    element.ariaControlsElements = bindings.controls;\n    element.ariaDescribedByElements = bindings.describedBy;\n    element.ariaActiveDescendantElement = bindings.activeDescendant;\n\n    for (const [key, attribute] of scalarBindings) {\n      const value = bindings[key];\n\n      if (!previous || previous[key] !== value) {\n        value != null\n          ? element.setAttribute(attribute, value)\n          : element.removeAttribute(attribute);\n      }\n    }\n\n    return noChange;\n  }\n}\n\n/**\n * Binds resolved ARIA state onto a native editor element as a single element\n * expression, e.g. `<input ${ariaBindings(aria)} />`.\n */\nexport const ariaBindings = directive(AriaBindingsDirective);\n\n/** Configuration for the {@link AriaProjectorController}. */\ntype AriaProjectorConfig = {\n  /** Resolves the input-shaped component the ARIA state is projected onto. */\n  target: () => Element | null | undefined;\n  /** Computes the ARIA state to project. Invoked after every host update. */\n  state: () => ProjectedARIA;\n};\n\n/**\n * The sending end of an ARIA projection, added by composite hosts\n * (e.g. `igc-select`). After every host update it pushes the computed ARIA\n * state onto the target component's {@link AriaTargetController}.\n */\nclass AriaProjectorController implements ReactiveController {\n  private readonly _host: ControllerHost;\n  private readonly _config: AriaProjectorConfig;\n  private _retryScheduled = false;\n\n  constructor(host: ControllerHost, config: AriaProjectorConfig) {\n    this._host = host;\n    this._config = config;\n    host.addController(this);\n  }\n\n  /** @internal */\n  public hostUpdated(): void {\n    const element = this._config.target();\n\n    if (!element) {\n      return;\n    }\n\n    const target = targets.get(element);\n\n    if (target) {\n      target.setProjected(this._config.state());\n      return;\n    }\n\n    // The target exists but has no controller yet - it is not upgraded on the\n    // host's first render when definitions register late. Re-project once its\n    // definition resolves.\n    if (!this._retryScheduled) {\n      this._retryScheduled = true;\n\n      customElements.whenDefined(element.localName).then(() => {\n        this._retryScheduled = false;\n        this._host.requestUpdate();\n      });\n    }\n  }\n}\n\n/**\n * Creates and adds an {@link AriaTargetController} to an input-shaped\n * component, making its native editor a valid target for\n * {@link addAriaProjector} - the editor is what assistive technology lands on\n * and reports once the component's host delegates focus to it.\n */\nexport function addAriaTarget(\n  host: ControllerHost,\n  config: AriaTargetConfig\n): AriaTargetController {\n  return new AriaTargetController(host, config);\n}\n\n/**\n * Creates and adds an {@link AriaProjectorController} to a composite host,\n * projecting ARIA semantics onto the native editor of the target component.\n */\nexport function addAriaProjector(\n  host: ControllerHost,\n  config: AriaProjectorConfig\n): AriaProjectorController {\n  return new AriaProjectorController(host, config);\n}\n\nexport type { AriaProjectorController, AriaTargetController };\n"]}
+{"version":3,"file":"aria-projection.js","sourceRoot":"","sources":["../../../src/internals/controllers/aria-projection.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type LitElement,\n  noChange,\n  type ReactiveController,\n  type ReactiveControllerHost,\n} from 'lit';\nimport {\n  Directive,\n  type DirectiveParameters,\n  directive,\n  type ElementPart,\n  type PartInfo,\n  PartType,\n} from 'lit/directive.js';\nimport { sameItems } from '../utils/arrays.js';\n\ntype ControllerHost = ReactiveControllerHost & LitElement;\n\n/**\n * The ARIA semantics that a composite host projects onto the native editor.\n *\n * @remarks\n * The host delegates focus, so assistive technology lands on the editor of\n * the input-shaped component and reports it. Every relation travels as an\n * element reference, because an IDREF does not cross a shadow boundary.\n */\nexport type ProjectedARIA = {\n  role?: string;\n  hasPopup?: string;\n  expanded?: string;\n  disabled?: string;\n  label?: string;\n  controls?: ReadonlyArray<Element> | null;\n  describedBy?: ReadonlyArray<Element> | null;\n  labelledBy?: ReadonlyArray<Element> | null;\n  activeDescendant?: Element | null;\n};\n\ntype AriaTargetConfig = {\n  /** Resolves the component's own `ElementInternals` labels. */\n  labels: () => ReadonlyArray<Element> | null;\n  /** Resolves the helper-text container, or `null` when there is none. */\n  description: () => Element | null;\n};\n\n/**\n * The binding values for a native editor element, resolved from the projected\n * state and the own ARIA of the editor, and applied by the\n * {@link ariaBindings} directive. A scalar binds as an attribute, a relation\n * through an ARIA element-reflection property.\n */\nexport type ResolvedARIABindings = {\n  role?: string;\n  hasPopup?: string;\n  expanded?: string;\n  disabled?: string;\n  label?: string;\n  /**\n   * The same-root IDREF for the own description of the editor. It applies\n   * while the host projects no description, so tooling that reads attributes\n   * only, for example axe, still sees a content attribute.\n   */\n  describedByRef?: string;\n  labelledBy: ReadonlyArray<Element> | null;\n  controls: ReadonlyArray<Element> | null;\n  describedBy: ReadonlyArray<Element> | null;\n  activeDescendant: Element | null;\n};\n\n/**\n * Resolves an input-shaped component to its ARIA target controller, so the\n * component needs no public member for the projection.\n */\nconst targets = new WeakMap<Element, AriaTargetController>();\n\nfunction bindingsEqual(\n  a: ResolvedARIABindings | undefined,\n  b: ResolvedARIABindings\n): boolean {\n  return (\n    a !== undefined &&\n    a.role === b.role &&\n    a.hasPopup === b.hasPopup &&\n    a.expanded === b.expanded &&\n    a.disabled === b.disabled &&\n    a.label === b.label &&\n    a.describedByRef === b.describedByRef &&\n    a.activeDescendant === b.activeDescendant &&\n    sameItems(a.controls, b.controls) &&\n    sameItems(a.describedBy, b.describedBy) &&\n    sameItems(a.labelledBy, b.labelledBy)\n  );\n}\n\n/**\n * The receiving end of an ARIA projection. Every input-shaped component adds\n * it to hold the state that a composite host projects, and resolves that\n * state against its own ARIA.\n *\n * @remarks\n * Not a reactive controller: it needs only a host render when the projected\n * state changes.\n */\nclass AriaTargetController {\n  private readonly _host: ControllerHost;\n  private readonly _config: AriaTargetConfig;\n  private _projected: ProjectedARIA = {};\n  /** The bindings last resolved for the native editor. */\n  private _resolved?: ResolvedARIABindings;\n\n  constructor(host: ControllerHost, config: AriaTargetConfig) {\n    this._host = host;\n    this._config = config;\n    targets.set(host, this);\n  }\n\n  /**\n   * Replaces the projected state.\n   *\n   * @remarks\n   * A host render happens only when the resolved bindings change, so a\n   * projection on every host update stays inexpensive. The comparison uses\n   * the resolved bindings, so it also catches a change to the own labels or\n   * description, which the component cannot observe.\n   */\n  public setProjected(state: ProjectedARIA): void {\n    const previous = this._resolved;\n    this._projected = state;\n\n    if (!bindingsEqual(previous, this.resolveBindings())) {\n      this._reflectStylingHooks();\n      this._host.requestUpdate();\n    }\n  }\n\n  /**\n   * Mirrors the projected `role` and `hasPopup` onto `data-role` and\n   * `data-haspopup`.\n   *\n   * @remarks\n   * The input themes style the anchor of a composite widget from these\n   * attributes. The ARIA itself stays on the editor in the shadow root, where\n   * a `:host()` selector cannot observe it.\n   */\n  private _reflectStylingHooks(): void {\n    const host = this._host;\n    const { role, hasPopup } = this._projected;\n\n    role\n      ? host.setAttribute('data-role', role)\n      : host.removeAttribute('data-role');\n    hasPopup\n      ? host.setAttribute('data-haspopup', hasPopup)\n      : host.removeAttribute('data-haspopup');\n  }\n\n  /**\n   * Resolves the binding values for the native editor element.\n   *\n   * @remarks\n   * A projected label wins over the own label of the component. The\n   * description stays a same-root IDREF while the host projects none, and the\n   * whole relation switches to element references afterwards, because an\n   * attribute and a reflection cannot coexist. See\n   * {@link ResolvedARIABindings.describedByRef}.\n   */\n  public resolveBindings(): ResolvedARIABindings {\n    const projected = this._projected;\n    const description = this._config.description();\n\n    this._resolved = {\n      role: projected.role,\n      hasPopup: projected.hasPopup,\n      expanded: projected.expanded,\n      disabled: projected.disabled,\n      label: projected.label,\n      labelledBy: projected.labelledBy ?? this._config.labels(),\n      controls: projected.controls ?? null,\n      describedBy: projected.describedBy\n        ? description\n          ? [description, ...projected.describedBy]\n          : projected.describedBy\n        : null,\n      describedByRef: projected.describedBy\n        ? undefined\n        : description?.id || undefined,\n      activeDescendant: projected.activeDescendant ?? null,\n    };\n\n    return this._resolved;\n  }\n}\n\nconst scalarBindings = [\n  ['role', 'role'],\n  ['hasPopup', 'aria-haspopup'],\n  ['expanded', 'aria-expanded'],\n  ['disabled', 'aria-disabled'],\n  ['label', 'aria-label'],\n  ['describedByRef', 'aria-describedby'],\n] as const;\n\n/**\n * Applies {@link ResolvedARIABindings} onto the native editor element. It\n * applies a relation on every render, and a scalar only on a change.\n */\nclass AriaBindingsDirective extends Directive {\n  private _previous?: ResolvedARIABindings;\n\n  constructor(partInfo: PartInfo) {\n    super(partInfo);\n\n    if (partInfo.type !== PartType.ELEMENT) {\n      throw new Error(\n        '`ariaBindings()` can only be used as an element expression.'\n      );\n    }\n  }\n\n  public override render(_: ResolvedARIABindings): unknown {\n    return noChange;\n  }\n\n  public override update(\n    part: ElementPart,\n    [bindings]: DirectiveParameters<this>\n  ): unknown {\n    const element = part.element;\n    const previous = this._previous;\n    this._previous = bindings;\n\n    // The relations run on every render: the browser drops an element\n    // reference assigned while the editor is outside the document, and the\n    // first render commits inside the template fragment. They come first, so\n    // the scalar pass sees the attributes that a reflection property removed.\n    element.ariaLabelledByElements = bindings.labelledBy;\n    element.ariaControlsElements = bindings.controls;\n    element.ariaDescribedByElements = bindings.describedBy;\n    element.ariaActiveDescendantElement = bindings.activeDescendant;\n\n    for (const [key, attribute] of scalarBindings) {\n      const value = bindings[key];\n\n      if (!previous || previous[key] !== value) {\n        value != null\n          ? element.setAttribute(attribute, value)\n          : element.removeAttribute(attribute);\n      }\n    }\n\n    return noChange;\n  }\n}\n\n/**\n * Binds the resolved ARIA state onto a native editor element as one element\n * expression, for example `<input ${ariaBindings(aria)} />`.\n */\nexport const ariaBindings = directive(AriaBindingsDirective);\n\ntype AriaProjectorConfig = {\n  /** Resolves the input-shaped component that receives the ARIA state. */\n  target: () => Element | null | undefined;\n  /** Computes the ARIA state to project, after every host update. */\n  state: () => ProjectedARIA;\n};\n\n/**\n * The sending end of an ARIA projection. A composite host such as\n * `igc-select` adds it to push the computed ARIA state onto the\n * {@link AriaTargetController} of the target after every host update.\n */\nclass AriaProjectorController implements ReactiveController {\n  private readonly _host: ControllerHost;\n  private readonly _config: AriaProjectorConfig;\n  private _retryScheduled = false;\n\n  constructor(host: ControllerHost, config: AriaProjectorConfig) {\n    this._host = host;\n    this._config = config;\n    host.addController(this);\n  }\n\n  /** @internal */\n  public hostUpdated(): void {\n    const element = this._config.target();\n\n    if (!element) {\n      return;\n    }\n\n    const target = targets.get(element);\n\n    if (target) {\n      target.setProjected(this._config.state());\n      return;\n    }\n\n    // The target exists but is not upgraded yet, because its definition\n    // registered late. Project again once that definition resolves.\n    if (!this._retryScheduled) {\n      this._retryScheduled = true;\n\n      customElements.whenDefined(element.localName).then(() => {\n        this._retryScheduled = false;\n        this._host.requestUpdate();\n      });\n    }\n  }\n}\n\n/**\n * Creates an {@link AriaTargetController} and adds it to an input-shaped\n * component. It makes the native editor of the component a valid target for\n * {@link addAriaProjector}.\n */\nexport function addAriaTarget(\n  host: ControllerHost,\n  config: AriaTargetConfig\n): AriaTargetController {\n  return new AriaTargetController(host, config);\n}\n\n/**\n * Creates an {@link AriaProjectorController} and adds it to a composite host.\n * It projects ARIA onto the native editor of the target component.\n */\nexport function addAriaProjector(\n  host: ControllerHost,\n  config: AriaProjectorConfig\n): AriaProjectorController {\n  return new AriaProjectorController(host, config);\n}\n\nexport type { AriaProjectorController, AriaTargetController };\n"]}

package/internals/controllers/async-consumer.js.map

@@ -1 +1 @@
-{"version":3,"file":"async-consumer.js","sourceRoot":"","sources":["../../../src/internals/controllers/async-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,eAAe,EAAoB,MAAM,cAAc,CAAC;AAc/E,MAAM,OAAO,oBAAoB;IAQ/B,YAAY,IAAU,EAAE,OAA+B;QACrD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QAExB,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;IAC/B,CAAC;IAKM,KAAK,CAAC,aAAa;QACxB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC;QAEhC,IAAI,CAAC,SAAS,KAAK,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE;YACjD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;YAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAChC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS;SACnC,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAIhC,IAAU,EACV,OAAU,EACV,QAAgE;IAEhE,OAAO,IAAI,oBAAoB,CAAC,IAAI,EAAE;QACpC,OAAO;QACP,QAAQ;QACR,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { type Context, ContextConsumer, type ContextType } from '@lit/context';\nimport type {\n  LitElement,\n  ReactiveController,\n  ReactiveControllerHost,\n} from 'lit';\n\ntype AsyncContextOptions<T extends Context<unknown, unknown>> = {\n  context: T;\n  callback?: (value: ContextType<T>, dispose?: () => void) => void;\n  subscribe?: boolean;\n};\n\n/* blazorSuppress */\nexport class AsyncContextConsumer<\n  T extends Context<unknown, unknown>,\n  Host extends ReactiveControllerHost & HTMLElement,\n> implements ReactiveController {\n  protected _host: Host;\n  protected _options: AsyncContextOptions<T>;\n  protected _consumer?: ContextConsumer<T, Host>;\n\n  constructor(host: Host, options: AsyncContextOptions<T>) {\n    this._host = host;\n    this._options = options;\n\n    this._host.addController(this);\n  }\n\n  public get value(): ContextType<T> | undefined {\n    return this._consumer?.value;\n  }\n\n  // If there is already an instance of a consumer (because of an attach/detach cycle),\n  // skip creating a new instance for this host - checked both before and after the\n  // await, since a reconnect can land in between.\n  public async hostConnected(): Promise<void> {\n    if (this._consumer) {\n      return;\n    }\n\n    await this._host.updateComplete;\n\n    this._consumer ??= new ContextConsumer(this._host, {\n      context: this._options.context,\n      callback: this._options.callback,\n      subscribe: this._options.subscribe,\n    });\n  }\n}\n\nexport function createAsyncContext<\n  T extends Context<unknown, unknown>,\n  Host extends ReactiveControllerHost & LitElement,\n>(\n  host: Host,\n  context: T,\n  callback?: (value: ContextType<T>, dispose?: () => void) => void\n): AsyncContextConsumer<T, Host> {\n  return new AsyncContextConsumer(host, {\n    context,\n    callback,\n    subscribe: true,\n  });\n}\n"]}
+{"version":3,"file":"async-consumer.js","sourceRoot":"","sources":["../../../src/internals/controllers/async-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,eAAe,EAAoB,MAAM,cAAc,CAAC;AAc/E,MAAM,OAAO,oBAAoB;IAQ/B,YAAY,IAAU,EAAE,OAA+B;QACrD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QAExB,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;IAC/B,CAAC;IAIM,KAAK,CAAC,aAAa;QACxB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC;QAEhC,IAAI,CAAC,SAAS,KAAK,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE;YACjD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;YAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAChC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS;SACnC,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAIhC,IAAU,EACV,OAAU,EACV,QAAgE;IAEhE,OAAO,IAAI,oBAAoB,CAAC,IAAI,EAAE;QACpC,OAAO;QACP,QAAQ;QACR,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { type Context, ContextConsumer, type ContextType } from '@lit/context';\nimport type {\n  LitElement,\n  ReactiveController,\n  ReactiveControllerHost,\n} from 'lit';\n\ntype AsyncContextOptions<T extends Context<unknown, unknown>> = {\n  context: T;\n  callback?: (value: ContextType<T>, dispose?: () => void) => void;\n  subscribe?: boolean;\n};\n\n/* blazorSuppress */\nexport class AsyncContextConsumer<\n  T extends Context<unknown, unknown>,\n  Host extends ReactiveControllerHost & HTMLElement,\n> implements ReactiveController {\n  protected _host: Host;\n  protected _options: AsyncContextOptions<T>;\n  protected _consumer?: ContextConsumer<T, Host>;\n\n  constructor(host: Host, options: AsyncContextOptions<T>) {\n    this._host = host;\n    this._options = options;\n\n    this._host.addController(this);\n  }\n\n  public get value(): ContextType<T> | undefined {\n    return this._consumer?.value;\n  }\n\n  // The consumer survives a disconnect, and a reconnect can land during the\n  // await, so the guard runs on both sides of it.\n  public async hostConnected(): Promise<void> {\n    if (this._consumer) {\n      return;\n    }\n\n    await this._host.updateComplete;\n\n    this._consumer ??= new ContextConsumer(this._host, {\n      context: this._options.context,\n      callback: this._options.callback,\n      subscribe: this._options.subscribe,\n    });\n  }\n}\n\nexport function createAsyncContext<\n  T extends Context<unknown, unknown>,\n  Host extends ReactiveControllerHost & LitElement,\n>(\n  host: Host,\n  context: T,\n  callback?: (value: ContextType<T>, dispose?: () => void) => void\n): AsyncContextConsumer<T, Host> {\n  return new AsyncContextConsumer(host, {\n    context,\n    callback,\n    subscribe: true,\n  });\n}\n"]}

package/internals/controllers/command.d.ts

@@ -1,14 +1,13 @@
-import type { LitElement, ReactiveController } from 'lit';
+import type { LitElement } from 'lit';
 /**
- * A Lit reactive controller that bridges the native
+ * Connects the native
  * [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API)
- * with a component's programmatic API.
+ * to the programmatic API of a component.
  *
- * When an `igc-button` (or any element using the `command` / `commandfor`
- * attributes) invokes a command on the host, the browser dispatches a
- * `CommandEvent` on the target element. This controller listens for that
- * event and forwards it to the registered callback for the given command
- * string.
+ * @remarks
+ * An element with the `command` and `commandfor` attributes makes the browser
+ * send a `CommandEvent` to the host, and the controller runs the callback of
+ * that command string.
  *
  * @example
  * ```ts
@@ -20,43 +19,29 @@ import type { LitElement, ReactiveController } from 'lit';
  * }
  * ```
  *
- * With the above setup, a button in the document can control the dialog
- * declaratively:
+ * A button in the document then controls the dialog declaratively:
  *
  * ```html
  * <igc-button command="open" commandfor="my-dialog">Open</igc-button>
  * <igc-dialog id="my-dialog"></igc-dialog>
  * ```
  */
-declare class CommandController implements ReactiveController {
+declare class CommandController {
     private readonly _host;
     private readonly _commandMap;
     constructor(host: LitElement);
     /**
-     * Registers a command string and its corresponding handler callback.
+     * Registers a command string and its handler callback.
      *
-     * Returns `this` to allow chained calls:
-     * ```ts
-     * addCommandController(this)
-     *   .set('open', this.show)
-     *   .set('close', this.hide);
-     * ```
-     *
-     * @param command - The command string to listen for (e.g. `'open'`,
-     *   `'toggle-popover'`, or a custom `'--my-command'`).
-     * @param callback - The method to invoke when the command is received.
-     *   Called with the host as `this`.
+     * @param command - The command string to listen for, for example `'open'`,
+     *   `'toggle-popover'`, or a custom `'--my-command'`.
+     * @param callback - The method that runs when the command arrives. The
+     *   controller calls it with the host as `this`.
      */
     set(command: string, callback: () => unknown): this;
     /** @internal */
-    hostConnected(): void;
-    /** @internal */
-    hostDisconnected(): void;
-    /** @internal */
     handleEvent(event: Event): void;
 }
-/**
- * Creates a {@link CommandController} and attaches it to the given host.
- */
+/** Creates a {@link CommandController} and adds it to the given host. */
 export declare function addCommandController(host: LitElement): CommandController;
 export type { CommandController };

package/internals/controllers/command.js

@@ -1,19 +1,14 @@
+import { addHostListeners } from './host-listeners.js';
 class CommandController {
     constructor(host) {
         this._commandMap = new Map();
         this._host = host;
-        host.addController(this);
+        addHostListeners(host, { events: ['command'], listener: this });
     }
     set(command, callback) {
         this._commandMap.set(command, callback);
         return this;
     }
-    hostConnected() {
-        this._host.addEventListener('command', this);
-    }
-    hostDisconnected() {
-        this._host.removeEventListener('command', this);
-    }
     handleEvent(event) {
         const commandEvent = event;
         this._commandMap.get(commandEvent.command)?.call(this._host);

package/internals/controllers/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../src/internals/controllers/command.ts"],"names":[],"mappings":"AA+BA,MAAM,iBAAiB;IAIrB,YAAY,IAAgB;QAFX,gBAAW,GAAG,IAAI,GAAG,EAAyB,CAAC;QAG9D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAiBM,GAAG,CAAC,OAAe,EAAE,QAAuB;QACjD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAGM,aAAa;QAClB,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;IAGM,gBAAgB;QACrB,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IAGM,WAAW,CAAC,KAAY;QAC7B,MAAM,YAAY,GAAG,KAAqB,CAAC;QAC3C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;CACF;AAKD,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACnD,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC","sourcesContent":["import type { LitElement, ReactiveController } from 'lit';\n\n/**\n * A Lit reactive controller that bridges the native\n * [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API)\n * with a component's programmatic API.\n *\n * When an `igc-button` (or any element using the `command` / `commandfor`\n * attributes) invokes a command on the host, the browser dispatches a\n * `CommandEvent` on the target element. This controller listens for that\n * event and forwards it to the registered callback for the given command\n * string.\n *\n * @example\n * ```ts\n * class IgcDialogComponent extends LitElement {\n *   private readonly _commands = addCommandController(this)\n *     .set('open', this.show)\n *     .set('close', this.hide)\n *     .set('toggle-popover', this.toggle);\n * }\n * ```\n *\n * With the above setup, a button in the document can control the dialog\n * declaratively:\n *\n * ```html\n * <igc-button command=\"open\" commandfor=\"my-dialog\">Open</igc-button>\n * <igc-dialog id=\"my-dialog\"></igc-dialog>\n * ```\n */\nclass CommandController implements ReactiveController {\n  private readonly _host: LitElement;\n  private readonly _commandMap = new Map<string, () => unknown>();\n\n  constructor(host: LitElement) {\n    this._host = host;\n    host.addController(this);\n  }\n\n  /**\n   * Registers a command string and its corresponding handler callback.\n   *\n   * Returns `this` to allow chained calls:\n   * ```ts\n   * addCommandController(this)\n   *   .set('open', this.show)\n   *   .set('close', this.hide);\n   * ```\n   *\n   * @param command - The command string to listen for (e.g. `'open'`,\n   *   `'toggle-popover'`, or a custom `'--my-command'`).\n   * @param callback - The method to invoke when the command is received.\n   *   Called with the host as `this`.\n   */\n  public set(command: string, callback: () => unknown): this {\n    this._commandMap.set(command, callback);\n    return this;\n  }\n\n  /** @internal */\n  public hostConnected(): void {\n    this._host.addEventListener('command', this);\n  }\n\n  /** @internal */\n  public hostDisconnected(): void {\n    this._host.removeEventListener('command', this);\n  }\n\n  /** @internal */\n  public handleEvent(event: Event): void {\n    const commandEvent = event as CommandEvent;\n    this._commandMap.get(commandEvent.command)?.call(this._host);\n  }\n}\n\n/**\n * Creates a {@link CommandController} and attaches it to the given host.\n */\nexport function addCommandController(host: LitElement): CommandController {\n  return new CommandController(host);\n}\n\nexport type { CommandController };\n"]}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../src/internals/controllers/command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA6BvD,MAAM,iBAAiB;IAIrB,YAAY,IAAgB;QAFX,gBAAW,GAAG,IAAI,GAAG,EAAyB,CAAC;QAG9D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAElB,gBAAgB,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAUM,GAAG,CAAC,OAAe,EAAE,QAAuB;QACjD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAGM,WAAW,CAAC,KAAY;QAC7B,MAAM,YAAY,GAAG,KAAqB,CAAC;QAC3C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;CACF;AAGD,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACnD,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC","sourcesContent":["import type { LitElement } from 'lit';\nimport { addHostListeners } from './host-listeners.js';\n\n/**\n * Connects the native\n * [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API)\n * to the programmatic API of a component.\n *\n * @remarks\n * An element with the `command` and `commandfor` attributes makes the browser\n * send a `CommandEvent` to the host, and the controller runs the callback of\n * that command string.\n *\n * @example\n * ```ts\n * class IgcDialogComponent extends LitElement {\n *   private readonly _commands = addCommandController(this)\n *     .set('open', this.show)\n *     .set('close', this.hide)\n *     .set('toggle-popover', this.toggle);\n * }\n * ```\n *\n * A button in the document then controls the dialog declaratively:\n *\n * ```html\n * <igc-button command=\"open\" commandfor=\"my-dialog\">Open</igc-button>\n * <igc-dialog id=\"my-dialog\"></igc-dialog>\n * ```\n */\nclass CommandController {\n  private readonly _host: LitElement;\n  private readonly _commandMap = new Map<string, () => unknown>();\n\n  constructor(host: LitElement) {\n    this._host = host;\n\n    addHostListeners(host, { events: ['command'], listener: this });\n  }\n\n  /**\n   * Registers a command string and its handler callback.\n   *\n   * @param command - The command string to listen for, for example `'open'`,\n   *   `'toggle-popover'`, or a custom `'--my-command'`.\n   * @param callback - The method that runs when the command arrives. The\n   *   controller calls it with the host as `this`.\n   */\n  public set(command: string, callback: () => unknown): this {\n    this._commandMap.set(command, callback);\n    return this;\n  }\n\n  /** @internal */\n  public handleEvent(event: Event): void {\n    const commandEvent = event as CommandEvent;\n    this._commandMap.get(commandEvent.command)?.call(this._host);\n  }\n}\n\n/** Creates a {@link CommandController} and adds it to the given host. */\nexport function addCommandController(host: LitElement): CommandController {\n  return new CommandController(host);\n}\n\nexport type { CommandController };\n"]}

package/internals/controllers/context-provider.d.ts

@@ -2,24 +2,19 @@ import { type Context, type ContextType } from '@lit/context';
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
 type ProviderHost = ReactiveControllerHost & HTMLElement;
 type ContextProviderControllerOptions<C extends Context<unknown, unknown>, H extends ProviderHost> = {
-    /** The context to provide. */
     context: C;
-    /** Computes the context value published to subscribers. */
+    /** Computes the published context value. */
     value: () => ContextType<C>;
-    /**
-     * Host properties whose changes republish the context. Anything else that must
-     * republish calls {@link ContextProviderController.publish}.
-     */
+    /** The host properties that republish the context when they change. */
     watch?: readonly (keyof H)[];
 };
 /**
- * Provides a context from the host and keeps subscribers current: the value
- * is published when the host connects, republished before an update whenever
- * one of the watched host properties has changed, and on demand via
- * {@link ContextProviderController.publish}.
+ * Gives a context from the host, and keeps the subscribers current.
  *
- * Every publish notifies subscribers, also when the value keeps its identity -
- * hosts that share one mutable context object still propagate their changes.
+ * @remarks
+ * Every publish notifies the subscribers, also when the value keeps its
+ * identity, so a host that shares one mutable context object still
+ * propagates its changes.
  *
  * @example
  * ```typescript
@@ -40,7 +35,6 @@ declare class ContextProviderController<C extends Context<unknown, unknown>, H e
     hostConnected(): void;
     /** @internal */
     hostUpdate(): void;
-    /** Publishes the current value to the subscribers. */
     publish(): void;
 }
 /** Creates and adds a {@link ContextProviderController} to the given host. */

package/internals/controllers/context-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-provider.js","sourceRoot":"","sources":["../../../src/internals/controllers/context-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,eAAe,EAAoB,MAAM,cAAc,CAAC;AAsC/E,MAAM,yBAAyB;IAS7B,YAAY,IAAO,EAAE,OAA+C;QAFnD,cAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;QAGvD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAEzE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAGM,aAAa;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAGM,UAAU;QACf,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAEpC,IAAI,OAAO,EAAE,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACxE,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAGM,OAAO;QACZ,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;CACF;AAGD,MAAM,UAAU,kBAAkB,CAIhC,IAAO,EACP,OAA+C;IAE/C,OAAO,IAAI,yBAAyB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC","sourcesContent":["import { type Context, ContextProvider, type ContextType } from '@lit/context';\nimport type { ReactiveController, ReactiveControllerHost } from 'lit';\n\ntype ProviderHost = ReactiveControllerHost & HTMLElement;\n\ntype ContextProviderControllerOptions<\n  C extends Context<unknown, unknown>,\n  H extends ProviderHost,\n> = {\n  /** The context to provide. */\n  context: C;\n  /** Computes the context value published to subscribers. */\n  value: () => ContextType<C>;\n  /**\n   * Host properties whose changes republish the context. Anything else that must\n   * republish calls {@link ContextProviderController.publish}.\n   */\n  watch?: readonly (keyof H)[];\n};\n\n/**\n * Provides a context from the host and keeps subscribers current: the value\n * is published when the host connects, republished before an update whenever\n * one of the watched host properties has changed, and on demand via\n * {@link ContextProviderController.publish}.\n *\n * Every publish notifies subscribers, also when the value keeps its identity -\n * hosts that share one mutable context object still propagate their changes.\n *\n * @example\n * ```typescript\n * private readonly _provider = addContextProvider(this, {\n *   context: themeContext,\n *   watch: ['theme', 'variant'],\n *   value: () => ({ theme: this.theme, variant: this.variant }),\n * });\n * ```\n */\nclass ContextProviderController<\n  C extends Context<unknown, unknown>,\n  H extends ProviderHost,\n> implements ReactiveController {\n  private readonly _host: H;\n  private readonly _options: ContextProviderControllerOptions<C, H>;\n  private readonly _provider: ContextProvider<C, H>;\n  private readonly _snapshot = new Map<keyof H, unknown>();\n\n  constructor(host: H, options: ContextProviderControllerOptions<C, H>) {\n    this._host = host;\n    this._options = options;\n    this._provider = new ContextProvider(host, { context: options.context });\n\n    host.addController(this);\n  }\n\n  /** @internal */\n  public hostConnected(): void {\n    this.publish();\n  }\n\n  /** @internal */\n  public hostUpdate(): void {\n    const watched = this._options.watch;\n\n    if (watched?.some((key) => this._host[key] !== this._snapshot.get(key))) {\n      this.publish();\n    }\n  }\n\n  /** Publishes the current value to the subscribers. */\n  public publish(): void {\n    for (const key of this._options.watch ?? []) {\n      this._snapshot.set(key, this._host[key]);\n    }\n\n    this._provider.setValue(this._options.value.call(this._host), true);\n  }\n}\n\n/** Creates and adds a {@link ContextProviderController} to the given host. */\nexport function addContextProvider<\n  C extends Context<unknown, unknown>,\n  H extends ProviderHost,\n>(\n  host: H,\n  options: ContextProviderControllerOptions<C, H>\n): ContextProviderController<C, H> {\n  return new ContextProviderController(host, options);\n}\n\nexport type { ContextProviderController, ContextProviderControllerOptions };\n"]}
+{"version":3,"file":"context-provider.js","sourceRoot":"","sources":["../../../src/internals/controllers/context-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,eAAe,EAAoB,MAAM,cAAc,CAAC;AAiC/E,MAAM,yBAAyB;IAS7B,YAAY,IAAO,EAAE,OAA+C;QAFnD,cAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;QAGvD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAEzE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAGM,aAAa;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAGM,UAAU;QACf,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAEpC,IAAI,OAAO,EAAE,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACxE,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAEM,OAAO;QACZ,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;CACF;AAGD,MAAM,UAAU,kBAAkB,CAIhC,IAAO,EACP,OAA+C;IAE/C,OAAO,IAAI,yBAAyB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC","sourcesContent":["import { type Context, ContextProvider, type ContextType } from '@lit/context';\nimport type { ReactiveController, ReactiveControllerHost } from 'lit';\n\ntype ProviderHost = ReactiveControllerHost & HTMLElement;\n\ntype ContextProviderControllerOptions<\n  C extends Context<unknown, unknown>,\n  H extends ProviderHost,\n> = {\n  context: C;\n  /** Computes the published context value. */\n  value: () => ContextType<C>;\n  /** The host properties that republish the context when they change. */\n  watch?: readonly (keyof H)[];\n};\n\n/**\n * Gives a context from the host, and keeps the subscribers current.\n *\n * @remarks\n * Every publish notifies the subscribers, also when the value keeps its\n * identity, so a host that shares one mutable context object still\n * propagates its changes.\n *\n * @example\n * ```typescript\n * private readonly _provider = addContextProvider(this, {\n *   context: themeContext,\n *   watch: ['theme', 'variant'],\n *   value: () => ({ theme: this.theme, variant: this.variant }),\n * });\n * ```\n */\nclass ContextProviderController<\n  C extends Context<unknown, unknown>,\n  H extends ProviderHost,\n> implements ReactiveController {\n  private readonly _host: H;\n  private readonly _options: ContextProviderControllerOptions<C, H>;\n  private readonly _provider: ContextProvider<C, H>;\n  private readonly _snapshot = new Map<keyof H, unknown>();\n\n  constructor(host: H, options: ContextProviderControllerOptions<C, H>) {\n    this._host = host;\n    this._options = options;\n    this._provider = new ContextProvider(host, { context: options.context });\n\n    host.addController(this);\n  }\n\n  /** @internal */\n  public hostConnected(): void {\n    this.publish();\n  }\n\n  /** @internal */\n  public hostUpdate(): void {\n    const watched = this._options.watch;\n\n    if (watched?.some((key) => this._host[key] !== this._snapshot.get(key))) {\n      this.publish();\n    }\n  }\n\n  public publish(): void {\n    for (const key of this._options.watch ?? []) {\n      this._snapshot.set(key, this._host[key]);\n    }\n\n    this._provider.setValue(this._options.value.call(this._host), true);\n  }\n}\n\n/** Creates and adds a {@link ContextProviderController} to the given host. */\nexport function addContextProvider<\n  C extends Context<unknown, unknown>,\n  H extends ProviderHost,\n>(\n  host: H,\n  options: ContextProviderControllerOptions<C, H>\n): ContextProviderController<C, H> {\n  return new ContextProviderController(host, options);\n}\n\nexport type { ContextProviderController, ContextProviderControllerOptions };\n"]}

package/internals/controllers/focus-ring.d.ts

@@ -1,43 +1,23 @@
-import type { ReactiveController, ReactiveControllerHost } from 'lit';
-/**
- * A controller class which determines whether a focus ring should be shown to indicate keyboard focus.
- * Focus rings are visible only when the user is interacting with a keyboard, not with a mouse, touch, or other input methods.
- *
- * By default the class attaches a keyup event handler on the component host and will update its keyboard focus
- * state based on it.
- *
- * **Important Note:** This controller is designed for use with **atomic web components** that represent single,
- * interactive elements (e.g., buttons, form fields, interactive icons). It helps these components correctly
- * display a focus indicator *only* when keyboard navigation is occurring, improving accessibility without
- * visual clutter during mouse or touch interactions.
- *
- * **Do not use this controller as a general-purpose shortcut for managing focus state in complex components or layouts.**
- * Misusing it in this way can lead to incorrect focus ring behavior, accessibility issues, and make your
- * application harder to maintain. For managing focus within larger, composite components, consider alternative
- * strategies like ARIA attributes, managing `tabindex`, or a bespoke implementation if needed.
- */
-declare class KeyboardFocusRingController implements ReactiveController {
+import type { ReactiveControllerHost } from 'lit';
+/** Tracks the keyboard focus state. See {@link addKeyboardFocusRing}. */
+declare class KeyboardFocusRingController {
     private static readonly _events;
     private readonly _host;
-    private readonly _abortHandle;
     private _isKeyboardFocused;
-    /**
-     * Gets whether the current focus state is activated through a keyboard interaction.
-     */
+    /** Whether a keyboard interaction activated the current focus state. */
     get focused(): boolean;
     constructor(host: ReactiveControllerHost & HTMLElement);
     /** @internal */
-    hostConnected(): void;
-    /** @internal */
-    hostDisconnected(): void;
-    /** @internal */
     handleEvent(event: Event): void;
 }
 export type { KeyboardFocusRingController };
 /**
- * Adds a {@link KeyboardFocusRingController} responsible for managing keyboard focus state.
+ * Adds a controller that reports whether the host has focus from the
+ * keyboard. A component shows its focus ring only in that condition.
  *
- * This utility function is intended for use with **atomic web components** that require
- * dynamic focus ring visibility based on keyboard interaction.
+ * @remarks
+ * Use it for an atomic component, such as a button or a form field. A
+ * composite component or a layout needs ARIA attributes, a managed
+ * `tabindex`, or an implementation of its own.
  */
 export declare function addKeyboardFocusRing(host: ReactiveControllerHost & HTMLElement): KeyboardFocusRingController;

package/internals/controllers/focus-ring.js

@@ -1,23 +1,17 @@
-import { createAbortHandle } from '../abort-handler.js';
+import { addHostListeners } from './host-listeners.js';
 class KeyboardFocusRingController {
     static { this._events = ['keyup', 'focusout', 'pointerup']; }
     get focused() {
         return this._isKeyboardFocused;
     }
     constructor(host) {
-        this._abortHandle = createAbortHandle();
         this._isKeyboardFocused = false;
         this._host = host;
-        host.addController(this);
-    }
-    hostConnected() {
-        const { signal } = this._abortHandle;
-        for (const event of KeyboardFocusRingController._events) {
-            this._host.addEventListener(event, this, { passive: true, signal });
-        }
-    }
-    hostDisconnected() {
-        this._abortHandle.abort();
+        addHostListeners(host, {
+            events: KeyboardFocusRingController._events,
+            listener: this,
+            options: { passive: true },
+        });
     }
     handleEvent(event) {
         const focused = event.type === 'keyup';