feat(core): add optional setItems callback to listbox and combobox controller

Author: adamjohnson

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

@@ -140,6 +140,17 @@ export interface ComboboxControllerOptions<Item extends HTMLElement> extends
    * By default, toggles the `hidden` attribute on the item
    */
   setItemHidden?(item: Item, hidden: boolean): void;
+  /**
+   * Optional. When provided, passed to ListboxController so it does not set
+   * aria-setsize/aria-posinset on items.
+   */
+  setItems?(items: Item[]): void;
+  /**
+   * Optional. Returns position-in-set and set size for the focused item when
+   * building the Safari VoiceOver live-region announcement ("N of M").
+   * When not provided, the controller reads aria-posinset/aria-setsize from the item.
+   */
+  getItemPosition?(item: Item, items: Item[]): { posInSet: number; setSize: number } | null;
 }
 
 /**
@@ -352,6 +363,7 @@ export class ComboboxController<
       getATFocusedItem: () => this.items[this.#fc?.atFocusedItemIndex ?? -1] ?? null,
       isItemDisabled: this.options.isItemDisabled,
       setItemSelected: this.options.setItemSelected,
+      setItems: this.options.setItems,
     });
     ComboboxController.instances.set(host, this);
     ComboboxController.hosts.add(host);
@@ -551,11 +563,21 @@ export class ComboboxController<
     if (this.#lb.isSelected(item)) {
       text += `, (${this.#translate('selected', langKey)})`;
     }
-    if (item.hasAttribute('aria-setsize') && item.hasAttribute('aria-posinset')) {
+    const position =
+    typeof this.options.getItemPosition === 'function' ?
+      this.options.getItemPosition(item, this.items)
+      : null;
+    const posInSet =
+      position?.posInSet
+      ?? (item.hasAttribute('aria-posinset') ? item.getAttribute('aria-posinset') : null);
+    const setSize =
+      position?.setSize
+      ?? (item.hasAttribute('aria-setsize') ? item.getAttribute('aria-setsize') : null);
+    if (posInSet != null && setSize != null) {
       if (langKey === 'ja') {
-        text += `, (${item.getAttribute('aria-setsize')} 件中 ${item.getAttribute('aria-posinset')} 件目)`;
+        text += `, (${setSize} 件中 ${posInSet} 件目)`;
       } else {
-        text += `, (${item.getAttribute('aria-posinset')} ${this.#translate('of', langKey)} ${item.getAttribute('aria-setsize')})`;
+        text += `, (${posInSet} ${this.#translate('of', langKey)} ${setSize})`;
       }
     }
     ComboboxController.#alert.lang = lang;

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

@@ -59,6 +59,12 @@ export interface ListboxControllerOptions<Item extends HTMLElement> {
    * a combobox input.
    */
   getControlsElements?(): HTMLElement[];
+  /**
+  * Optional callback when items are set. When provided, the controller does **not**
+  * set aria-setsize/aria-posinset on each item; the caller is responsible for list
+  * semantics (e.g. via ElementInternals).
+  */
+  setItems?(items: Item[]): void;
 }
 
 /**
@@ -192,16 +198,22 @@ export class ListboxController<Item extends HTMLElement> implements ReactiveCont
   }
 
   /**
-   * register's the host's Item elements as listbox controller items
-   * sets aria-setsize and aria-posinset on items
-   * @param items items
+   * Registers the host's Item elements as listbox controller items.
+   * If options provides a setItems function, that function is called with the items.
+   * Otherwise, sets aria-setsize and aria-posinset on each item.
+   * @param items - The Item elements to register
    */
   set items(items: Item[]) {
     this.#items = items;
-    this.#items.forEach((item, index, _items) => {
-      item.ariaSetSize = _items.length.toString();
-      item.ariaPosInSet = (index + 1).toString();
-    });
+    const { setItems } = this.#options;
+    if (typeof setItems === 'function') {
+      setItems(items);
+    } else {
+      this.#items.forEach((item, index, _items) => {
+        item.ariaSetSize = _items.length.toString();
+        item.ariaPosInSet = (index + 1).toString();
+      });
+    }
   }
 
   /**