Merge 46442ed into aca9130

.changeset/a11y-controller-opts.md

@@ -0,0 +1,6 @@
+---
+"@patternfly/pfe-core": major
+---
+`RovingTabindexController`, `ListboxController`: constructor options were changed
+
+TODO: elaborate, give before-and-after cases

.changeset/a11y-snapshot-chai.md

@@ -0,0 +1,32 @@
+---
+"@patternfly/pfe-tools": minor
+---
+`a11ySnapshot`: Added chai assertions for various accessibility-tree scenarios
+
+Examples:
+```ts
+describe('<pf-accordion>', function() {
+  beforeEach(() => fixture(html`
+    <pf-accordion>
+      <pf-accordion-header id="header1">header-1</pf-accordion-header>
+      <pf-accordion-panel>panel-1</pf-accordion-panel>
+    </pf-accordion>
+  `))
+  describe('clicking the first heading', function() {
+    beforeEach(clickFirstHeading);
+    it('expands the first panel', async function() {
+      expect(await a11ySnapshot())
+        .to.axContainName('panel-1');
+    });
+    it('focuses the first panel', async function() {
+      expect(await a11ySnapshot())
+        .to.have.axTreeFocusOn(document.getElementById('header1'));
+    });
+    it('shows the collapse all button', async function() {
+      expect(await a11ySnapshot())
+        .to.axContainRole('button');
+    });
+  })
+})
+
+```

core/pfe-core/controllers/activedescendant-controller.ts

@@ -0,0 +1,273 @@
+import type { ReactiveControllerHost } from 'lit';
+
+import { type ATFocusControllerOptions, ATFocusController } from './at-focus-controller.js';
+
+import { isServer, nothing } from 'lit';
+import { getRandomId } from '../functions/random.js';
+import { bound } from '../decorators/bound.js';
+
+export interface ActivedescendantControllerOptions<
+  Item extends HTMLElement
+> extends ATFocusControllerOptions<Item> {
+  /**
+   * Returns a reference to the element which acts as the assistive technology container for
+   * the items. In the case of a combobox, this is the input element.
+   */
+  getActiveDescendantContainer(): HTMLElement | null;
+  /**
+   * Optional callback to control the assistive technology focus behavior of items.
+   * By default, ActivedescendantController will not do anything special to items when they receive
+   * assistive technology focus, and will only set the `activedescendant` property on the container.
+   * If you provide this callback, ActivedescendantController will call it on your item with the
+   * active state. You may use this to set active styles.
+   */
+  setItemActive?(item: Item, active: boolean): void;
+  /**
+   * Optional callback to retrieve the value from an option element.
+   * By default, retrieves the `value` attribute, or the text content.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionElement
+   */
+  getItemValue?(item: Item): string;
+}
+
+/**
+ * Implements activedescendant pattern, as described in WAI-ARIA practices,
+ * [Managing Focus in Composites Using aria-activedescendant][ad]
+ *
+ * The steps for using the aria-activedescendant method of managing focus are as follows.
+ *
+ *  - When the container element that has a role that supports aria-activedescendant is loaded
+ *    or created, ensure that:
+ *    - The container element is included in the tab sequence as described in
+ *      Keyboard Navigation Between Components or is a focusable element of a composite
+ *      that implements a roving tabindex.
+ *    - It has aria-activedescendant="IDREF" where IDREF is the ID of the element within
+ *      the container that should be identified as active when the widget receives focus.
+ *      The referenced element needs to meet the DOM relationship requirements described below.
+ *  - When the container element receives DOM focus, draw a visual focus indicator on the active
+ *    element and ensure the active element is scrolled into view.
+ *  - When the composite widget contains focus and the user presses a navigation key that moves
+ *    focus within the widget, such as an arrow key:
+ *    - Change the value of aria-activedescendant on the container to refer to the element
+ *      that should be reported to assistive technologies as active.
+ *    - Move the visual focus indicator and, if necessary, scrolled the active element into view.
+ *  - If the design calls for a specific element to be focused the next time a user moves focus
+ *    into the composite with Tab or Shift+Tab, check if aria-activedescendant is referring to
+ *    that target element when the container loses focus. If it is not, set aria-activedescendant
+ *    to refer to the target element.
+ *
+ * The specification for aria-activedescendant places important restrictions on the
+ * DOM relationship between the focused element that has the aria-activedescendant attribute
+ * and the element referenced as active by the value of the attribute.
+ * One of the following three conditions must be met.
+ *
+ * 1. The element referenced as active is a DOM descendant of the focused referencing element.
+ * 2. The focused referencing element has a value specified for the aria-owns property that
+ *    includes the ID of the element referenced as active.
+ * 3. The focused referencing element has role of combobox, textbox, or searchbox
+ *    and has aria-controls property referring to an element with a role that supports
+ *    aria-activedescendant and either:
+ *   1. The element referenced as active is a descendant of the controlled element.
+ *   2. The controlled element has a value specified for the aria-owns property that includes
+ *      the ID of the element referenced as active.
+ *
+ * [ad]: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant
+ */
+export class ActivedescendantController<
+  Item extends HTMLElement = HTMLElement
+> extends ATFocusController<Item> {
+  /**
+   * When true, the browser supports cross-root ARIA such that the controller does not need
+   * to copy item nodes into the controlling nodes' root
+   */
+  public static get supportsCrossRootActiveDescendant(): boolean {
+    return !isServer && 'ariaActiveDescendantElement' in HTMLElement.prototype;
+  }
+
+  static of<Item extends HTMLElement>(
+    host: ReactiveControllerHost,
+    options: ActivedescendantControllerOptions<Item>,
+  ): ActivedescendantController<Item> {
+    return new ActivedescendantController(host, options);
+  }
+
+  /** Maps from original element to shadow DOM clone */
+  #lightToShadowMap = new WeakMap<Item, Item>();
+
+  /** Maps from shadow DOM clone to original element */
+  #shadowToLightMap = new WeakMap<Item, Item>();
+
+  /** Set of item which should not be cloned */
+  #noCloneSet = new WeakSet<Item>();
+
+  /** Element which controls the list i.e. combobox */
+  #controlsElements: HTMLElement[] = [];
+
+  #observing = false;
+
+  #listMO = new MutationObserver(records => this.#onItemsDOMChange(records));
+
+  #attrMO = new MutationObserver(records => this.#onItemAttributeChange(records));
+
+  #syncAttr(attributeName: string, fromNode: Item) {
+    const toNode = this.#shadowToLightMap.get(fromNode as Item)
+                ?? this.#lightToShadowMap.get(fromNode as Item);
+    const newVal = fromNode.getAttribute(attributeName);
+    const oldVal = toNode?.getAttribute(attributeName);
+    if (!fromNode.hasAttribute(attributeName)) {
+      toNode?.removeAttribute(attributeName);
+    } else if (oldVal !== newVal) {
+      toNode?.setAttribute(attributeName, newVal!);
+    }
+  }
+
+  get atFocusedItemIndex(): number {
+    return super.atFocusedItemIndex;
+  }
+
+  /**
+   * Rather than setting DOM focus, applies the `aria-activedescendant` attribute,
+   * using AriaIDLAttributes for cross-root aria, if supported by the browser
+   * @param item item
+   */
+  set atFocusedItemIndex(index: number) {
+    super.atFocusedItemIndex = index;
+    const item = this._items.at(this.atFocusedItemIndex);
+    for (const _item of this.items) {
+      this.options.setItemActive?.(_item, _item === item);
+    }
+    const container = this.options.getActiveDescendantContainer();
+    if (!ActivedescendantController.supportsCrossRootActiveDescendant) {
+      container?.setAttribute('aria-activedescendant', item?.id ?? '');
+    } else if (container) {
+      container.ariaActiveDescendantElement = item ?? null;
+    }
+    this.host.requestUpdate();
+  }
+
+  protected get controlsElements(): HTMLElement[] {
+    return this.#controlsElements;
+  }
+
+  protected set controlsElements(elements: HTMLElement[]) {
+    for (const old of this.#controlsElements) {
+      old?.removeEventListener('keydown', this.onKeydown);
+    }
+    this.#controlsElements = elements;
+    for (const element of this.#controlsElements) {
+      element.addEventListener('keydown', this.onKeydown);
+    }
+  }
+
+  /** All items */
+  get items() {
+    return this._items;
+  }
+
+  /**
+   * Sets the list of items and activates the next activatable item after the current one
+   * @param items tabindex items
+   */
+  override set items(items: Item[]) {
+    const container = this.options.getItemsContainer?.() ?? this.host;
+    if (!(container instanceof HTMLElement)) {
+      throw new Error('items container must be an HTMLElement');
+    }
+    this.itemsContainerElement = container;
+    const { supportsCrossRootActiveDescendant } = ActivedescendantController;
+    if (supportsCrossRootActiveDescendant
+        || [container] // all nodes are in the same root
+            .concat(this.controlsElements)
+            .concat(items)
+            .every((node, _, a) => node.getRootNode() === a[0].getRootNode())) {
+      this._items = items.map(x => {
+        if (!supportsCrossRootActiveDescendant) {
+          x.id ||= getRandomId();
+        }
+        return x;
+      });
+    } else {
+      this._items = items?.map((item: Item) => {
+        item.removeAttribute('tabindex');
+        if (container.contains(item)) {
+          item.id ||= getRandomId();
+          this.#noCloneSet.add(item);
+          this.#shadowToLightMap.set(item, item);
+          return item;
+        } else {
+          const clone = item.cloneNode(true) as Item;
+          clone.id = getRandomId();
+          this.#lightToShadowMap.set(item, clone);
+          this.#shadowToLightMap.set(clone, item);
+          // Though efforts were taken to disconnect
+          // this observer, it may still be a memory leak
+          this.#attrMO.observe(clone, { attributes: true });
+          this.#attrMO.observe(item, { attributes: true });
+          return clone;
+        }
+      });
+    }
+  }
+
+  private constructor(
+    public host: ReactiveControllerHost,
+    protected options: ActivedescendantControllerOptions<Item>,
+  ) {
+    super(host, options);
+    this.options.getItemValue ??= function(this: Item) {
+      return (this as unknown as HTMLOptionElement).value;
+    };
+  }
+
+  #onItemsDOMChange(records: MutationRecord[]) {
+    for (const { removedNodes } of records) {
+      for (const removed of removedNodes as NodeListOf<Item>) {
+        this.#lightToShadowMap.get(removed)?.remove();
+        this.#lightToShadowMap.delete(removed);
+      }
+    }
+  };
+
+  #onItemAttributeChange(records: MutationRecord[]) {
+    for (const { target, attributeName } of records) {
+      if (attributeName) {
+        this.#syncAttr(attributeName, target as Item);
+      }
+    }
+  };
+
+  protected override initItems(): void {
+    this.#attrMO.disconnect();
+    super.initItems();
+    this.controlsElements = this.options.getControlsElements?.() ?? [];
+    if (!this.#observing && this.itemsContainerElement && this.itemsContainerElement.isConnected) {
+      this.#listMO.observe(this.itemsContainerElement, { childList: true });
+      this.#observing = true;
+    }
+  }
+
+  hostDisconnected(): void {
+    this.controlsElements = [];
+    this.#observing = false;
+    this.#listMO.disconnect();
+    this.#attrMO.disconnect();
+  }
+
+  @bound
+  protected override onKeydown(event: KeyboardEvent): void {
+    if (!event.ctrlKey
+        && !event.altKey
+        && !event.metaKey
+        && !!this.atFocusableItems.length) {
+      super.onKeydown(event);
+    };
+  }
+
+  public renderItemsToShadowRoot(): typeof nothing | Node[] {
+    if (ActivedescendantController.supportsCrossRootActiveDescendant) {
+      return nothing;
+    } else {
+      return this.items?.filter(x => !this.#noCloneSet.has(x));
+    }
+  }
+}