phlex_kit 0.5.1 → 0.6.1

data/app/components/phlex_kit/combobox/combobox_controller.js

@@ -1,10 +1,11 @@
 import { Controller } from "@hotwired/stimulus";
 
-// Ported from ruby_ui's combobox controller. TWO changes from upstream: the
-// @floating-ui/dom dependency and the native Popover API are removed — the panel
-// is a CSS-positioned child of the combobox (.pk-combobox-popover, toggled with
-// .pk-hidden) with click-outside handled by a window action, so only
-// @hotwired/stimulus is needed. PhlexKit also COMPLETES upstream's unfinished
+// Ported from ruby_ui's combobox controller, minus the @floating-ui/dom
+// dependency: like upstream, the panel is a native popover (manual — this
+// controller owns open/close and click-outside via a window action), and CSS
+// anchor positioning replaces computePosition (combobox.css: trigger-width
+// floor via anchor-size(), viewport-edge flip via position-try-fallbacks),
+// so only @hotwired/stimulus is needed. PhlexKit also COMPLETES upstream's unfinished
 // input/badge trigger variants: the inputTrigger / badgeContainer / badgeInput /
 // clearButton targets, filtering from whichever field fired, chip rendering
 // with per-chip remove, backspace removal, and clearAll all had no upstream
@@ -14,7 +15,6 @@ import { Controller } from "@hotwired/stimulus";
 export default class extends Controller {
   static values = {
     term: String,
-    minPopoverWidth: { type: Number, default: 240 },
     autoHighlight: { type: Boolean, default: false }
   }
 
@@ -30,15 +30,61 @@ export default class extends Controller {
     "inputTrigger",
     "badgeContainer",
     "badgeInput",
-    "clearButton"
+    "clearButton",
+    "list",
+    "liveRegion"
   ]
 
   selectedItemIndex = null
 
   connect() {
+    this.generateItemIds()
     this.updateTriggerContent()
   }
 
+  // ARIA plumbing: every option gets an id derived from the listbox id so the
+  // combobox element can point aria-activedescendant at the keyboard highlight,
+  // and aria-controls is wired to the listbox (mirrors select_controller.js).
+  generateItemIds() {
+    const list = this.hasListTarget ? this.listTarget : (this.hasPopoverTarget ? this.popoverTarget : this.element)
+    if (!list.id) list.id = `pk-combobox-list-${Math.random().toString(36).slice(2, 10)}`
+
+    this.itemTargets.forEach((item, index) => {
+      if (!item.id) item.id = `${list.id}-${index}`
+    })
+
+    this.ariaExpandedElements().forEach((el) => el.setAttribute("aria-controls", list.id))
+  }
+
+  // The elements carrying the open/closed combobox state: the trigger button
+  // (button layout) and/or whichever filter field the layout has.
+  ariaExpandedElements() {
+    const els = []
+    if (this.hasInputTriggerTarget) els.push(this.inputTriggerTarget)
+    if (this.hasBadgeInputTarget) els.push(this.badgeInputTarget)
+    if (els.length === 0 && this.hasTriggerTarget) els.push(this.triggerTarget)
+    if (this.hasSearchInputTarget) els.push(this.searchInputTarget)
+    return els
+  }
+
+  isOpen() {
+    return this.hasPopoverTarget && this.popoverTarget.matches(":popover-open")
+  }
+
+  setExpanded(expanded) {
+    this.ariaExpandedElements().forEach((el) => el.setAttribute("aria-expanded", expanded ? "true" : "false"))
+  }
+
+  setActiveDescendant(id) {
+    const field = this.filterField()
+    if (field) field.setAttribute("aria-activedescendant", id)
+  }
+
+  clearActiveDescendant() {
+    const field = this.filterField()
+    if (field) field.removeAttribute("aria-activedescendant")
+  }
+
   inputChanged(e) {
     this.updateTriggerContent()
 
@@ -81,13 +127,15 @@ export default class extends Controller {
   updateTriggerContent() {
     const checked = this.checkedInputs()
 
+    this.syncAriaSelected()
+
     if (this.hasTriggerContentTarget) {
       this.triggerContentTarget.innerText = this.selectionLabel(checked) || this.triggerTarget.dataset.placeholder
     }
 
     // Input trigger: the field is also the filter, so only reflect the
     // selection while the popover is closed — never stomp a query mid-typing.
-    if (this.hasInputTriggerTarget && this.triggerTarget.ariaExpanded !== "true") {
+    if (this.hasInputTriggerTarget && !this.isOpen()) {
       this.inputTriggerTarget.value = this.selectionLabel(checked)
     }
 
@@ -100,6 +148,14 @@ export default class extends Controller {
     }
   }
 
+  // The chosen option(s) carry aria-selected; the option label is the ARIA
+  // option, its inner input holds the real checked state.
+  syncAriaSelected() {
+    this.inputTargets.forEach((input) => {
+      input.parentElement.setAttribute("aria-selected", input.checked ? "true" : "false")
+    })
+  }
+
   renderBadges(checked) {
     this.badgeContainerTarget.replaceChildren(...checked.map((input) => this.buildBadge(input)))
     this.badgeContainerTarget.classList.toggle("pk-hidden", checked.length === 0)
@@ -159,7 +215,7 @@ export default class extends Controller {
   togglePopover(event) {
     event.preventDefault()
 
-    if (this.triggerTarget.ariaExpanded === "true") {
+    if (this.isOpen()) {
       this.closePopover()
     } else {
       this.openPopover(event)
@@ -168,13 +224,13 @@ export default class extends Controller {
 
   openPopover(event) {
     if (event) event.preventDefault()
-    if (this.triggerTarget.ariaExpanded === "true") return
+    if (this.isOpen()) return
 
-    this.updatePopoverWidth()
-    this.triggerTarget.ariaExpanded = "true"
+    this.setExpanded(true)
     this.selectedItemIndex = null
     this.itemTargets.forEach(item => item.ariaCurrent = "false")
-    this.popoverTarget.classList.remove("pk-hidden")
+    this.clearActiveDescendant()
+    this.popoverTarget.showPopover()
 
     const field = this.filterField()
     if (field) {
@@ -186,13 +242,16 @@ export default class extends Controller {
   }
 
   closePopover() {
-    this.triggerTarget.ariaExpanded = "false"
-    this.popoverTarget.classList.add("pk-hidden")
+    this.setExpanded(false)
+    // aria-activedescendant holds an element id; on close it must be removed,
+    // not left pointing at a hidden option.
+    this.clearActiveDescendant()
+    if (this.popoverTarget.matches(":popover-open")) this.popoverTarget.hidePopover()
     this.updateTriggerContent() // reflect the selection into an input trigger
   }
 
   onClickOutside(event) {
-    if (this.triggerTarget.ariaExpanded !== "true") return
+    if (!this.isOpen()) return
     if (this.element.contains(event.target)) return
 
     this.closePopover()
@@ -227,6 +286,7 @@ export default class extends Controller {
     let resultCount = 0
 
     this.selectedItemIndex = null
+    this.clearActiveDescendant()
 
     this.inputTargets.forEach((input) => {
       const text = this.inputContent(input).toLowerCase()
@@ -243,6 +303,12 @@ export default class extends Controller {
       this.emptyStateTarget.classList.toggle("pk-hidden", resultCount !== 0)
     }
 
+    // Announce the filtered result count to screen readers.
+    if (this.hasLiveRegionTarget) {
+      this.liveRegionTarget.textContent =
+        resultCount === 0 ? "No results" : `${resultCount} result${resultCount === 1 ? "" : "s"}`
+    }
+
     // autoHighlight: keep the first visible option marked while typing so
     // Enter picks it immediately (their autoHighlight prop).
     if (this.autoHighlightValue && filterTerm && resultCount > 0) {
@@ -284,6 +350,9 @@ export default class extends Controller {
     visibleInputs.forEach((input, index) => {
       if (index == this.selectedItemIndex) {
         input.parentElement.ariaCurrent = "true"
+        // Focus stays in the filter field; the highlighted option is exposed
+        // via aria-activedescendant (option ids come from generateItemIds).
+        this.setActiveDescendant(input.parentElement.id)
         input.parentElement.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' })
       } else {
         input.parentElement.ariaCurrent = "false"
@@ -304,8 +373,4 @@ export default class extends Controller {
     this.selectedItemIndex = ((this.selectedItemIndex % length) + length) % length
   }
 
-  updatePopoverWidth() {
-    const width = Math.max(this.triggerTarget.offsetWidth, this.minPopoverWidthValue)
-    this.popoverTarget.style.width = `${width}px`
-  }
 }

data/app/components/phlex_kit/combobox/combobox_input_trigger.rb

@@ -9,15 +9,20 @@ module PhlexKit
   # popover's own bindings only fire for the button+search layout.
   # See combobox.rb.
   class ComboboxInputTrigger < BaseComponent
-    def initialize(placeholder: "", disabled: false, invalid: false, **attrs)
+    def initialize(placeholder: "", disabled: false, invalid: false, list_id: nil, **attrs)
       @placeholder = placeholder
       @disabled = disabled
       @invalid = invalid
+      @list_id = list_id
       @attrs = attrs
     end
 
     def view_template
-      wrapper_aria = { haspopup: "listbox", expanded: "false" }
+      # The ARIA combobox role sits on the field itself (the interactive
+      # element); the wrapper keeps aria-invalid only because the invalid
+      # styling targets it. Pass `list_id:` matching the ComboboxList id to
+      # wire aria-controls statically — otherwise the controller wires it.
+      wrapper_aria = {}
       wrapper_aria[:invalid] = "true" if @invalid
       div(**mix({
         class: "pk-combobox-input-trigger",
@@ -35,8 +40,12 @@ module PhlexKit
           ].join(" ")
         }
       }, @attrs)) do
+        field_aria = { haspopup: "listbox", expanded: "false", autocomplete: "list", controls: @list_id }
+        field_aria[:invalid] = "true" if @invalid
         input(
           type: :text,
+          role: "combobox",
+          aria: field_aria,
           placeholder: @placeholder,
           disabled: @disabled,
           autocomplete: "off",

data/app/components/phlex_kit/combobox/combobox_item.rb

@@ -2,7 +2,9 @@ module PhlexKit
   # One option row — a <label> wrapping a ComboboxCheckbox/ComboboxRadio, the
   # option text, and optionally a ComboboxItemIndicator. Being a label, clicking
   # anywhere toggles the input; the controller hides it (.pk-hidden) when
-  # filtered out. See combobox.rb.
+  # filtered out, assigns each option an id (for the combobox element's
+  # aria-activedescendant), and keeps aria-selected in sync with the inner
+  # input's checked state. See combobox.rb.
   class ComboboxItem < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
@@ -12,6 +14,7 @@ module PhlexKit
       label(**mix({
         class: "pk-combobox-item",
         role: "option",
+        aria: { selected: "false" },
         data: { phlex_kit__combobox_target: "item" }
       }, @attrs), &)
     end

data/app/components/phlex_kit/combobox/combobox_list.rb

@@ -1,12 +1,19 @@
 module PhlexKit
-  # Scrollable option list in a PhlexKit::ComboboxPopover. See combobox.rb.
+  # Scrollable option list in a PhlexKit::ComboboxPopover. Carries the listbox
+  # role and an id the controller points the combobox element's aria-controls
+  # at (and derives option ids from). See combobox.rb.
   class ComboboxList < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-combobox-list", role: "listbox" }, @attrs), &)
+      div(**mix({
+        id: "pk-combobox-list-#{SecureRandom.hex(4)}",
+        class: "pk-combobox-list",
+        role: "listbox",
+        data: { phlex_kit__combobox_target: "list" }
+      }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/combobox/combobox_popover.rb

@@ -1,8 +1,9 @@
 module PhlexKit
-  # The combobox dropdown panel. Upstream uses the native Popover API +
-  # @floating-ui; here it's a CSS-positioned panel toggled with .pk-hidden (the
-  # keyboard nav actions ride on it, since focus sits in the search input
-  # inside). See combobox.rb.
+  # The combobox dropdown panel — like upstream, a native [popover] (manual:
+  # the controller owns open/close and click-outside), anchor-positioned to
+  # the combobox with viewport-edge flipping (combobox.css). The keyboard nav
+  # actions ride on it, since focus sits in the search input inside. See
+  # combobox.rb.
   class ComboboxPopover < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
@@ -10,15 +11,15 @@ module PhlexKit
 
     def view_template(&)
       div(**mix({
-        class: "pk-combobox-popover pk-hidden",
+        class: "pk-combobox-popover",
+        popover: "manual",
         data: {
           phlex_kit__combobox_target: "popover",
           action: [
             "keydown.down->phlex-kit--combobox#keyDownPressed",
             "keydown.up->phlex-kit--combobox#keyUpPressed",
             "keydown.enter->phlex-kit--combobox#keyEnterPressed",
-            "keydown.esc->phlex-kit--combobox#closePopover:prevent",
-            "resize@window->phlex-kit--combobox#updatePopoverWidth"
+            "keydown.esc->phlex-kit--combobox#closePopover:prevent"
           ].join(" ")
         }
       }, @attrs), &)

data/app/components/phlex_kit/combobox/combobox_radio.rb

@@ -10,6 +10,9 @@ module PhlexKit
     def view_template
       input(**mix({
         type: :radio,
+        # The option label is the interactive surface (ARIA option); the real
+        # input must not be a second tab stop inside it.
+        tabindex: "-1",
         class: "pk-combobox-radio",
         data: {
           phlex_kit__combobox_target: "input",

data/app/components/phlex_kit/combobox/combobox_search_input.rb

@@ -1,10 +1,14 @@
 module PhlexKit
   # Filter input at the top of a PhlexKit::ComboboxPopover (magnifier icon +
   # borderless search field). Filtering happens client-side against each item's
-  # text (or data-text). See combobox.rb.
+  # text (or data-text). The field carries the ARIA combobox role (keyboard nav
+  # highlights options via aria-activedescendant while focus stays here); pass
+  # `list_id:` matching the ComboboxList id to wire aria-controls statically —
+  # otherwise the controller wires it on connect. See combobox.rb.
   class ComboboxSearchInput < BaseComponent
-    def initialize(placeholder:, **attrs)
+    def initialize(placeholder:, list_id: nil, **attrs)
       @placeholder = placeholder
+      @list_id = list_id
       @attrs = attrs
     end
 
@@ -13,7 +17,8 @@ module PhlexKit
         icon
         input(**mix({
           type: :search,
-          role: "searchbox",
+          role: "combobox",
+          aria: { autocomplete: "list", expanded: "false", controls: @list_id },
           autocorrect: "off",
           autocomplete: "off",
           spellcheck: "false",

data/app/components/phlex_kit/command/command.rb

@@ -11,8 +11,23 @@ module PhlexKit
       @attrs = attrs
     end
 
-    def view_template(&)
-      div(**mix({ class: "pk-command" }, @attrs), &)
+    def view_template
+      div(**mix({ class: "pk-command" }, @attrs)) do
+        live_region
+        yield
+      end
+    end
+
+    private
+
+    # Screen-reader announcement of the filtered result count — the controller
+    # writes "N results" / "No results" into it from filter().
+    def live_region
+      div(
+        class: "pk-sr-only",
+        aria: { live: "polite" },
+        data: { phlex_kit__command_target: "liveRegion" }
+      )
     end
   end
 end

data/app/components/phlex_kit/command/command_controller.js

@@ -33,25 +33,81 @@ function fuzzyScore(query, value) {
 // nav, dismiss) is unchanged.
 // Connects to data-controller="phlex-kit--command"
 export default class extends Controller {
-  static targets = ["input", "group", "item", "empty", "separator"];
+  static targets = ["input", "group", "item", "empty", "separator", "list", "liveRegion"];
 
   connect() {
     this.selectedIndex = -1;
+    // Remember what had focus before the palette grabbed it (for a cloned
+    // dialog this is the element focused when the overlay was inserted), so
+    // dismiss() can hand focus back instead of dropping it on <body>.
+    this.previouslyFocused = document.activeElement;
 
     if (!this.hasInputTarget) {
       return;
     }
 
+    this.generateItemIds();
     this.inputTarget.focus();
     this.searchIndex = this.buildSearchIndex();
     this.toggleVisibility(this.emptyTargets, false);
   }
 
+  // ARIA plumbing: every result gets an id derived from the listbox id so the
+  // input can point aria-activedescendant at the keyboard highlight, and
+  // aria-controls is wired to the listbox (mirrors select_controller.js).
+  generateItemIds() {
+    const list = this.hasListTarget ? this.listTarget : this.element;
+    if (!list.id) list.id = `pk-command-list-${Math.random().toString(36).slice(2, 10)}`;
+
+    this.itemTargets.forEach((item, index) => {
+      if (!item.id) item.id = `${list.id}-${index}`;
+    });
+
+    this.inputTarget.setAttribute("aria-controls", list.id);
+  }
+
   dismiss() {
     // allow scroll on body
     document.body.style.removeProperty("overflow");
+    const previous = this.previouslyFocused;
     // remove the element
     this.element.remove();
+    // restore focus to wherever it was before the palette opened
+    if (previous instanceof HTMLElement && document.contains(previous)) {
+      previous.focus();
+    }
+  }
+
+  // Focus trap for the cloned dialog overlay: Tab / Shift+Tab cycle among the
+  // overlay's own focusable elements instead of escaping to the page beneath.
+  trapFocus(e) {
+    if (e.key !== "Tab") return;
+
+    const focusables = Array.from(
+      this.element.querySelectorAll(
+        'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      ),
+    ).filter((el) => !el.closest(".pk-hidden"));
+
+    if (focusables.length === 0) {
+      e.preventDefault();
+      return;
+    }
+
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = document.activeElement;
+
+    if (e.shiftKey && active === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && active === last) {
+      e.preventDefault();
+      first.focus();
+    } else if (!this.element.contains(active)) {
+      e.preventDefault();
+      first.focus();
+    }
   }
 
   focusInput() {
@@ -65,6 +121,7 @@ export default class extends Controller {
     const query = e.target.value.toLowerCase();
     if (query.length === 0) {
       this.resetVisibility();
+      this.announceResultCount(null);
       return;
     }
 
@@ -75,11 +132,24 @@ export default class extends Controller {
       this.toggleVisibility([result.item.element], true),
     );
 
+    this.announceResultCount(results.length);
     this.toggleVisibility(this.emptyTargets, results.length === 0);
     this.toggleVisibility(this.separatorTargets, false);
     this.updateGroupVisibility();
   }
 
+  // Announce the filtered result count to screen readers (null = no query).
+  announceResultCount(count) {
+    if (!this.hasLiveRegionTarget) return;
+
+    if (count === null) {
+      this.liveRegionTarget.textContent = "";
+    } else {
+      this.liveRegionTarget.textContent =
+        count === 0 ? "No results" : `${count} result${count === 1 ? "" : "s"}`;
+    }
+  }
+
   toggleVisibility(elements, isVisible) {
     elements.forEach((el) => el.classList.toggle("pk-hidden", !isVisible));
   }
@@ -120,8 +190,11 @@ export default class extends Controller {
   }
 
   handleKeydown(e) {
+    // Disabled items stay visible (dimmed via [data-disabled]) but are
+    // skipped by keyboard selection.
     const visibleItems = this.itemTargets.filter(
-      (item) => !item.classList.contains("pk-hidden"),
+      (item) =>
+        !item.classList.contains("pk-hidden") && !item.dataset.disabled,
     );
     if (e.key === "ArrowDown") {
       e.preventDefault();
@@ -136,7 +209,9 @@ export default class extends Controller {
   }
 
   updateSelectedItem(visibleItems, direction) {
-    if (this.selectedIndex >= 0) {
+    if (visibleItems.length === 0) return;
+
+    if (this.selectedIndex >= 0 && visibleItems[this.selectedIndex]) {
       this.toggleAriaSelected(visibleItems[this.selectedIndex], false);
     }
 
@@ -150,6 +225,15 @@ export default class extends Controller {
     }
 
     this.toggleAriaSelected(visibleItems[this.selectedIndex], true);
+
+    // Focus stays in the input; the highlighted option is exposed via
+    // aria-activedescendant (result ids come from generateItemIds).
+    if (this.hasInputTarget) {
+      this.inputTarget.setAttribute(
+        "aria-activedescendant",
+        visibleItems[this.selectedIndex].id,
+      );
+    }
   }
 
   toggleAriaSelected(element, isSelected) {
@@ -159,5 +243,11 @@ export default class extends Controller {
   deselectAll() {
     this.itemTargets.forEach((item) => this.toggleAriaSelected(item, false));
     this.selectedIndex = -1;
+
+    // aria-activedescendant holds an element id; with nothing highlighted it
+    // must be removed, not left pointing at a stale option.
+    if (this.hasInputTarget) {
+      this.inputTarget.removeAttribute("aria-activedescendant");
+    }
   }
 }

data/app/components/phlex_kit/command/command_dialog_content.rb

@@ -7,16 +7,28 @@ module PhlexKit
   class CommandDialogContent < BaseComponent
     SIZES = { xs: "xs", sm: "sm", md: nil, lg: "lg", xl: "xl", full: "full" }.freeze
 
-    def initialize(size: :md, **attrs)
+    def initialize(size: :md, aria_label: "Command palette", **attrs)
       @size = size.to_sym
+      @aria_label = aria_label
       @attrs = attrs
     end
 
     def view_template(&block)
       template(data: { phlex_kit__command_dialog_target: "content" }) do
-        div(data: { controller: "phlex-kit--command", phlex_kit__command_dialog_instance: true }) do
+        # The keydown action is the focus trap: Tab cycles within the cloned
+        # overlay instead of escaping to the page underneath.
+        div(data: {
+          controller: "phlex-kit--command",
+          phlex_kit__command_dialog_instance: true,
+          action: "keydown->phlex-kit--command#trapFocus"
+        }) do
           backdrop
-          div(**mix({ class: panel_classes, data: { state: "open" } }, @attrs), &block)
+          div(**mix({
+            class: panel_classes,
+            role: "dialog",
+            aria: { modal: "true", label: @aria_label },
+            data: { state: "open" }
+          }, @attrs), &block)
         end
       end
     end
@@ -24,7 +36,7 @@ module PhlexKit
     private
 
     def panel_classes
-      [ "pk-command-dialog", SIZES.fetch(@size) ].compact.join(" ")
+      [ "pk-command-dialog", fetch_option(SIZES, @size, :size) ].compact.join(" ")
     end
 
     def backdrop

data/app/components/phlex_kit/command/command_input.rb

@@ -3,9 +3,14 @@ module PhlexKit
   # type, arrows/enter drive selection, esc dismisses. Renders as shadcn's
   # current bordered pill inside the padded palette (input-wrapper >
   # input-group). See command.rb.
+  # Pass `list_id:` matching the CommandList id to wire aria-controls
+  # statically — otherwise the controller wires it on connect. aria-expanded
+  # stays "true" because the list is always visible (filtering hides items,
+  # never the listbox itself).
   class CommandInput < BaseComponent
-    def initialize(placeholder: "Type a command or search...", **attrs)
+    def initialize(placeholder: "Type a command or search...", list_id: nil, **attrs)
       @placeholder = placeholder
+      @list_id = list_id
       @attrs = attrs
     end
 
@@ -23,7 +28,7 @@ module PhlexKit
             autofocus: true,
             role: "combobox",
             value: "",
-            aria: { autocomplete: "list", expanded: "true" },
+            aria: { autocomplete: "list", expanded: "true", controls: @list_id },
             data: {
               phlex_kit__command_target: "input",
               action: [

data/app/components/phlex_kit/command/command_item.rb

@@ -1,12 +1,15 @@
 module PhlexKit
   # One palette result — an <a> (pass `href:`) filtered by `value:`, activated
   # by click or enter. aria-selected is toggled by keyboard navigation.
-  # See command.rb.
+  # `disabled: true` renders the [data-disabled] styling + aria-disabled and
+  # the controller skips it during keyboard navigation (matches
+  # ContextMenuItem's pattern). See command.rb.
   class CommandItem < BaseComponent
-    def initialize(value:, text: "", href: "#", **attrs)
+    def initialize(value:, text: "", href: "#", disabled: false, **attrs)
       @value = value
       @text = text
       @href = href
+      @disabled = disabled
       @attrs = attrs
     end
 
@@ -15,7 +18,13 @@ module PhlexKit
         class: "pk-command-item",
         href: @href,
         role: "option",
-        data: { phlex_kit__command_target: "item", value: @value, text: @text }
+        aria: { disabled: (@disabled ? "true" : nil) },
+        data: {
+          phlex_kit__command_target: "item",
+          value: @value,
+          text: @text,
+          disabled: (@disabled ? "true" : nil)
+        }
       }, @attrs), &)
     end
   end

data/app/components/phlex_kit/command/command_list.rb

@@ -1,12 +1,19 @@
 module PhlexKit
-  # Container for CommandGroups, with dividers between them. See command.rb.
+  # Container for CommandGroups, with dividers between them. Carries the
+  # listbox role and an id the controller points the input's aria-controls at
+  # (and derives result ids from, for aria-activedescendant). See command.rb.
   class CommandList < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-command-list" }, @attrs), &)
+      div(**mix({
+        id: "pk-command-list-#{SecureRandom.hex(4)}",
+        class: "pk-command-list",
+        role: "listbox",
+        data: { phlex_kit__command_target: "list" }
+      }, @attrs), &)
     end
   end
 end