phlex_kit 0.9.1 → 0.11.0

data/app/components/phlex_kit/codeblock/codeblock.rb

@@ -12,7 +12,13 @@ module PhlexKit
       # tabindex=0 + role=region: the block scrolls (overflow:auto), so it must
       # be keyboard-focusable (WCAG 2.1.1 scrollable-region-focusable). Pass
       # `aria: { label: ... }` to name the region for AT.
-      div(**mix({ class: "pk-codeblock", tabindex: "0", role: "region", data: { syntax: @syntax } }, @attrs)) do
+      base = { class: "pk-codeblock", tabindex: "0", role: "region", data: { syntax: @syntax } }
+      # A region landmark without a name is an axe violation — default one
+      # from the syntax; a caller aria: { label: } replaces it (never fused).
+      unless aria_labelled?
+        base[:aria] = { label: @syntax ? "#{@syntax} code" : "Code" }
+      end
+      div(**mix(base, @attrs)) do
         pre do
           if block
             code(&block)

data/app/components/phlex_kit/collapsible/collapsible.rb

@@ -7,7 +7,10 @@ module PhlexKit
       @attrs = attrs
     end
     def view_template(&)
-      div(**mix({ class: "pk-collapsible", data: { controller: "phlex-kit--collapsible", phlex_kit__collapsible_open_value: @open } }, @attrs), &)
+      # data-state is the CSS styling hook (chevron rotation) — it must be
+      # server-rendered or an open: true collapsible renders a closed-pointing
+      # chevron until Stimulus connects (and always, with JS off).
+      div(**mix({ class: "pk-collapsible", data: { controller: "phlex-kit--collapsible", phlex_kit__collapsible_open_value: @open, state: @open ? "open" : "closed" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/collapsible/collapsible_controller.js

@@ -6,10 +6,19 @@ export default class extends Controller {
   static values = { open: { type: Boolean, default: false } }
 
   connect() {
-    // The trigger renders aria-expanded from its own `open:` kwarg but can't
-    // know the content's id at render time — wire aria-controls here.
-    if (this.hasTriggerTarget && this.hasContentTarget && this.contentTarget.id) {
-      this.triggerTarget.setAttribute("aria-controls", this.contentTarget.id)
+    // aria-expanded must live on the element AT reads state from — the
+    // focused control, not the plain wrapper div. The trigger wrapper renders
+    // aria-expanded server-side (it can't reach into its block), so resolve
+    // the nested focusable control here, relocate the state onto it, and keep
+    // toggling there. Wrapper-only triggers keep the wrapper as carrier.
+    if (this.hasTriggerTarget) {
+      this.control = this.triggerTarget.querySelector("button, [role='button'], a[href], input") || this.triggerTarget
+      if (this.control !== this.triggerTarget) this.triggerTarget.removeAttribute("aria-expanded")
+      // The trigger can't know the content's id at render time — wire
+      // aria-controls here.
+      if (this.hasContentTarget && this.contentTarget.id) {
+        this.control.setAttribute("aria-controls", this.contentTarget.id)
+      }
     }
     this.openValue ? this.open() : this.close()
   }
@@ -18,13 +27,13 @@ export default class extends Controller {
 
   open() {
     if (this.hasContentTarget) { this.contentTarget.classList.remove("pk-hidden"); this.openValue = true }
-    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true")
+    if (this.control) this.control.setAttribute("aria-expanded", "true")
     this.element.dataset.state = "open";
   }
 
   close() {
     if (this.hasContentTarget) { this.contentTarget.classList.add("pk-hidden"); this.openValue = false }
-    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false")
+    if (this.control) this.control.setAttribute("aria-expanded", "false")
     this.element.dataset.state = "closed";
   }
 }

data/app/components/phlex_kit/collapsible/collapsible_trigger.rb

@@ -4,8 +4,11 @@ module PhlexKit
   # control (a <button>, e.g. PhlexKit::Button) inside it for keyboard
   # operability and semantics, the same composition pattern as
   # AttachmentTrigger. Pass `open:` matching the parent Collapsible's so
-  # aria-expanded is correct before JS; the controller keeps it in sync and
-  # wires aria-controls to the content's id in connect().
+  # aria-expanded is correct before JS. The wrapper carries the server-rendered
+  # aria-expanded only because the component can't reach into its block; on
+  # connect the controller relocates it (plus aria-controls) onto the nested
+  # focusable control — AT reads state from the focused element, not the
+  # wrapper — falling back to the wrapper when no control is nested.
   class CollapsibleTrigger < BaseComponent
     def initialize(open: false, **attrs)
       @open = open

data/app/components/phlex_kit/combobox/combobox.css

@@ -152,7 +152,7 @@
   margin: 0;
   accent-color: var(--pk-brand);
 }
-.pk-combobox-checkbox { border-radius: .125rem; }
+.pk-combobox-checkbox { border-radius: calc(var(--pk-radius) - 8px); }
 .pk-combobox-checkbox:disabled, .pk-combobox-radio:disabled { cursor: not-allowed; opacity: .5; }
 .pk-combobox-checkbox:focus-visible, .pk-combobox-radio:focus-visible {
   outline: none;
@@ -296,7 +296,7 @@
   width: .875rem;
   height: .875rem;
   border: 0;
-  border-radius: .125rem;
+  border-radius: calc(var(--pk-radius) - 8px);
   padding: 0;
   background: transparent;
   color: var(--pk-muted);
@@ -318,7 +318,7 @@
   flex: none;
   margin-inline-start: auto;
   border: 0;
-  border-radius: .125rem;
+  border-radius: calc(var(--pk-radius) - 8px);
   padding: 0;
   background: transparent;
   color: var(--pk-muted);

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

@@ -5,9 +5,9 @@ module PhlexKit
   # toggle-all live in the phlex-kit--combobox controller. Like PhlexKit::Select, the
   # @floating-ui/dom + native-popover positioning is replaced with CSS (panel
   # anchored below the trigger, click-outside via window action). Compose
-  # Combobox(term:) > trigger + Popover(SearchInput + List(ListGroup >
-  # Item(Checkbox|Radio + text + ItemIndicator)) + EmptyState [+
-  # ToggleAllCheckbox]). Three trigger flavours: ComboboxTrigger (button +
+  # Combobox(term:) > trigger + Popover(SearchInput + List([Item(
+  # ToggleAllCheckbox) first +] ListGroup > Item(Checkbox|Radio + text +
+  # ItemIndicator) + EmptyState)). Three trigger flavours: ComboboxTrigger (button +
   # popover search), ComboboxInputTrigger (the field is the filter), and
   # ComboboxBadgeTrigger (multi-select chips + ComboboxClearButton) — the
   # latter two shipped unfinished in ruby_ui (no controller support) and are

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

@@ -30,7 +30,8 @@ module PhlexKit
             "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"
+            # no :prevent — closePopover only swallows Escape while open.
+            "keydown.esc->phlex-kit--combobox#closePopover"
           ].join(" ")
         }
       }, @attrs)) do
@@ -49,7 +50,10 @@ module PhlexKit
             action: [
               "keyup->phlex-kit--combobox#filterItems",
               "input->phlex-kit--combobox#filterItems",
-              "keydown.backspace->phlex-kit--combobox#handleBadgeInputBackspace"
+              # plain keydown — "backspace" is not a Stimulus key filter
+              # (using it throws "unknown key filter" on every keystroke and
+              # the handler never ran); the method guards on e.key itself.
+              "keydown->phlex-kit--combobox#handleBadgeInputBackspace"
             ].join(" ")
           }
         )

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

@@ -45,6 +45,11 @@ export default class extends Controller {
   }
 
   connect() {
+    // A Turbo snapshot serializes aria-expanded / aria-activedescendant even
+    // though :popover-open does not survive the restore — normalize here so
+    // a restored page doesn't announce an open listbox over a closed combobox.
+    this.setExpanded(false)
+    this.clearActiveDescendant()
     this.generateItemIds()
     this.updateTriggerContent()
   }
@@ -174,6 +179,11 @@ export default class extends Controller {
     this.inputTargets.forEach((input) => {
       input.parentElement.setAttribute("aria-selected", input.checked ? "true" : "false")
     })
+    // The toggle-all row is an option too (first row inside the listbox) —
+    // keep its aria-selected in step with its checkbox.
+    if (this.hasToggleAllTarget && this.toggleAllTarget.parentElement.getAttribute("role") === "option") {
+      this.toggleAllTarget.parentElement.setAttribute("aria-selected", this.toggleAllTarget.checked ? "true" : "false")
+    }
   }
 
   renderBadges(checked) {
@@ -212,6 +222,8 @@ export default class extends Controller {
   }
 
   handleBadgeInputBackspace(e) {
+    // Bound as a bare keydown: "backspace" is not a Stimulus key filter.
+    if (e.key !== "Backspace") return
     if (this.badgeInputTarget.value !== "") return
 
     const checked = this.checkedInputs()
@@ -273,7 +285,14 @@ export default class extends Controller {
     }
   }
 
-  closePopover() {
+  closePopover(e) {
+    // Escape must keep its browser default (e.g. cancelling an enclosing
+    // <dialog>) when the popover is already closed — only swallow the key
+    // when this close actually consumes it.
+    if (e?.type === "keydown") {
+      if (!this.isOpen()) return
+      e.preventDefault()
+    }
     // Hiding the popover while focus is inside it (search input, option) drops
     // focus to <body>; hand it back to the trigger. Checked BEFORE hiding, and
     // only when focus would actually be orphaned — a click elsewhere on the
@@ -284,7 +303,7 @@ export default class extends Controller {
     // 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()
+    if (this.hasPopoverTarget && this.popoverTarget.matches(":popover-open")) this.popoverTarget.hidePopover()
     this.updateTriggerContent() // reflect the selection into an input trigger
 
     if (focusWasInside) {
@@ -398,20 +417,23 @@ export default class extends Controller {
   }
 
   focusSelectedInput() {
-    const visibleInputs = this.inputTargets.filter(input => !input.parentElement.classList.contains("pk-hidden"))
-    if (visibleInputs.length === 0) return
+    // Walk the option rows themselves, not the inner selection inputs: the
+    // toggle-all row is an option without an "input" target and must be
+    // arrow-reachable like any other option.
+    const visibleItems = this.itemTargets.filter(item => !item.classList.contains("pk-hidden"))
+    if (visibleItems.length === 0) return
 
-    this.wrapSelectedInputIndex(visibleInputs.length)
+    this.wrapSelectedInputIndex(visibleItems.length)
 
-    visibleInputs.forEach((input, index) => {
+    visibleItems.forEach((item, index) => {
       if (index == this.selectedItemIndex) {
-        input.parentElement.ariaCurrent = "true"
+        item.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' })
+        this.setActiveDescendant(item.id)
+        item.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' })
       } else {
-        input.parentElement.ariaCurrent = "false"
+        item.ariaCurrent = "false"
       }
     })
   }

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

@@ -36,7 +36,10 @@ module PhlexKit
             "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"
+            # no :prevent — closePopover only swallows Escape while the
+            # popover is open, so a closed field keeps the key's default
+            # (e.g. cancelling an enclosing <dialog>).
+            "keydown.esc->phlex-kit--combobox#closePopover"
           ].join(" ")
         }
       }, @attrs)) do

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

@@ -3,13 +3,17 @@ module PhlexKit
   # 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)
+    # id: is a named kwarg (not left in **attrs) because `mix` would *merge* a
+    # caller id with the generated one into an invalid two-token id, breaking
+    # aria-controls (the documented list_id: wiring) and derived option ids.
+    def initialize(id: nil, **attrs)
+      @id = id || "pk-combobox-list-#{SecureRandom.hex(4)}"
       @attrs = attrs
     end
 
     def view_template(&)
       div(**mix({
-        id: "pk-combobox-list-#{SecureRandom.hex(4)}",
+        id: @id,
         class: "pk-combobox-list",
         role: "listbox",
         data: { phlex_kit__combobox_target: "list" }

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

@@ -26,7 +26,9 @@ module PhlexKit
           class: "pk-combobox-search-input",
           data: {
             phlex_kit__combobox_target: "searchInput",
-            action: "keyup->phlex-kit--combobox#filterItems search->phlex-kit--combobox#filterItems"
+            # `input` covers context-menu paste and IME composition, which
+            # fire no keyup/search (mirrors ComboboxInputTrigger).
+            action: "keyup->phlex-kit--combobox#filterItems input->phlex-kit--combobox#filterItems search->phlex-kit--combobox#filterItems"
           }
         }, @attrs))
       end

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

@@ -1,6 +1,8 @@
 module PhlexKit
   # "Select all" checkbox for a multi-select combobox — wrap it in a
-  # PhlexKit::ComboboxItem above the list. Hidden while a filter term is active.
+  # PhlexKit::ComboboxItem as the FIRST row inside the ComboboxList (the item
+  # carries role="option", which is only valid inside the listbox, and arrow-key
+  # nav walks the list's rows). Hidden while a filter term is active.
   # See combobox.rb.
   class ComboboxToggleAllCheckbox < BaseComponent
     def initialize(**attrs)
@@ -11,6 +13,10 @@ module PhlexKit
       input(**mix({
         type: :checkbox,
         class: "pk-combobox-checkbox",
+        # The option label is the interactive surface (ARIA option); the real
+        # input must not be a second tab stop inside it — same as
+        # ComboboxCheckbox/ComboboxRadio.
+        tabindex: "-1",
         data: {
           phlex_kit__combobox_target: "toggleAll",
           action: "change->phlex-kit--combobox#toggleAllItems"

data/app/components/phlex_kit/command/command.css

@@ -8,7 +8,7 @@
 .pk-command {
   background: var(--pk-surface);
   color: var(--pk-text);
-  border-radius: .75rem;
+  border-radius: calc(var(--pk-radius) + 2px);
   padding: .25rem;
 }
 .pk-command-dialog-trigger { display: inline-block; }
@@ -34,7 +34,7 @@
   width: 100%;
   max-width: 32rem;
   border: 1px solid var(--pk-border);
-  border-radius: .75rem;
+  border-radius: calc(var(--pk-radius) + 2px);
   background: var(--pk-surface);
   color: var(--pk-text);
   box-shadow: 0 10px 30px color-mix(in srgb, var(--pk-shadow-color) 35%, transparent);

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

@@ -35,8 +35,16 @@ function fuzzyScore(query, value) {
 export default class extends Controller {
   static targets = ["input", "group", "item", "empty", "separator", "list", "liveRegion"];
 
-  connect() {
+  initialize() {
+    // Stimulus fires [target]Connected before connect(): anything
+    // itemTargetConnected uses must be initialized here (mirrors
+    // combobox_controller.js).
+    this.itemIdCounter = 0;
+    this.searchEntries = [];
     this.selectedIndex = -1;
+  }
+
+  connect() {
     // 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>.
@@ -50,7 +58,6 @@ export default class extends Controller {
     // Only the cloned dialog overlay grabs focus on connect — an inline
     // palette connecting at page load must not steal it.
     if (this.isDialogClone()) this.inputTarget.focus();
-    this.searchIndex = this.buildSearchIndex();
     this.toggleVisibility(this.emptyTargets, false);
   }
 
@@ -60,23 +67,49 @@ export default class extends Controller {
     return this.element.hasAttribute("data-phlex-kit--command-dialog-instance");
   }
 
-  // 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).
+  // ARIA plumbing: aria-controls is wired to the listbox (mirrors
+  // select_controller.js); the per-result ids come from itemTargetConnected.
   generateItemIds() {
+    this.inputTarget.setAttribute("aria-controls", this.listId());
+  }
+
+  listId() {
     const list = this.hasListTarget ? this.listTarget : this.element;
     if (!list.id) list.id = `pk-command-list-${Math.random().toString(36).slice(2, 10)}`;
+    return list.id;
+  }
 
-    this.itemTargets.forEach((item, index) => {
-      if (!item.id) item.id = `${list.id}-${index}`;
+  // Every result gets an id derived from the listbox id so the input can
+  // point aria-activedescendant at the keyboard highlight, and a search-index
+  // entry so filtering can find it. A target callback (not a connect() loop)
+  // so items rendered in by the host after load are id'd and findable too.
+  // Counter-based, so a removed item's id is never reissued to a later
+  // arrival (mirrors combobox_controller.js).
+  itemTargetConnected(item) {
+    if (!item.id) item.id = `${this.listId()}-${this.itemIdCounter++}`;
+    this.searchEntries.push({
+      value: (item.dataset.value || "").toLowerCase(),
+      text: (item.dataset.text || "").toLowerCase(),
+      element: item,
     });
+  }
 
-    this.inputTarget.setAttribute("aria-controls", list.id);
+  itemTargetDisconnected(item) {
+    this.searchEntries = this.searchEntries.filter(
+      (entry) => entry.element !== item,
+    );
+    // The highlight index is positional — after a removal it points at the
+    // wrong (or a missing) row, so Enter would activate the wrong item.
+    this.selectedIndex = -1;
   }
 
   dismiss() {
     // Cloned dialog overlay: tear the clone down and hand focus back.
     if (this.isDialogClone()) {
+      // Dispatched BEFORE teardown: the command-dialog controller listens on
+      // the overlay and un-inerts the page here — focus() below would be a
+      // silent no-op while previouslyFocused sits under an inert ancestor.
+      this.dispatch("dismiss");
       // allow scroll on body
       document.body.style.removeProperty("overflow");
       const previous = this.previouslyFocused;
@@ -157,7 +190,7 @@ export default class extends Controller {
 
     this.toggleVisibility(this.itemTargets, false);
 
-    const results = this.searchIndex.search(query);
+    const results = this.searchItems(query);
     results.forEach((result) =>
       this.toggleVisibility([result.item.element], true),
     );
@@ -201,31 +234,24 @@ export default class extends Controller {
     this.toggleVisibility(this.emptyTargets, false);
   }
 
-  // Upstream builds a Fuse index here; this keeps the same search() shape —
-  // [{ item }] sorted best-match-first — using the fuzzy scorer above.
-  // Both data-value and data-text are searchable (an item's `text:` was
-  // rendered but never indexed); the better of the two scores wins.
-  buildSearchIndex() {
-    const items = this.itemTargets.map((el) => ({
-      value: (el.dataset.value || "").toLowerCase(),
-      text: (el.dataset.text || "").toLowerCase(),
-      element: el,
-    }));
-    return {
-      search(query) {
-        const q = query.toLowerCase();
-        return items
-          .map((item) => {
-            const scores = [item.value, item.text]
-              .filter(Boolean)
-              .map((field) => fuzzyScore(q, field))
-              .filter((score) => score !== null);
-            return { item, score: scores.length ? Math.max(...scores) : null };
-          })
-          .filter((result) => result.score !== null)
-          .sort((a, b) => b.score - a.score);
-      },
-    };
+  // Upstream builds a Fuse index here; this keeps the same result shape —
+  // [{ item }] sorted best-match-first — using the fuzzy scorer above over
+  // the live searchEntries (maintained by itemTargetConnected/Disconnected,
+  // so host-rendered items are searchable). Both data-value and data-text are
+  // searchable (an item's `text:` was rendered but never indexed); the better
+  // of the two scores wins.
+  searchItems(query) {
+    const q = query.toLowerCase();
+    return this.searchEntries
+      .map((item) => {
+        const scores = [item.value, item.text]
+          .filter(Boolean)
+          .map((field) => fuzzyScore(q, field))
+          .filter((score) => score !== null);
+        return { item, score: scores.length ? Math.max(...scores) : null };
+      })
+      .filter((result) => result.score !== null)
+      .sort((a, b) => b.score - a.score);
   }
 
   handleKeydown(e) {
@@ -243,7 +269,9 @@ export default class extends Controller {
       this.updateSelectedItem(visibleItems, -1);
     } else if (e.key === "Enter" && this.selectedIndex !== -1) {
       e.preventDefault();
-      visibleItems[this.selectedIndex].click();
+      // Optional-chained: a stale selectedIndex after dynamic item removal
+      // (turbo stream re-render) must not throw.
+      visibleItems[this.selectedIndex]?.click();
     }
   }
 

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

@@ -6,14 +6,27 @@ import { Controller } from "@hotwired/stimulus";
 // upstream's document-scoped outlet (which let one dialog adopt another's
 // open palette), each instance tracks its own clone — sheet_controller's
 // pattern — and clears it on turbo:before-cache so a cached page never
-// restores a stale overlay + scroll lock.
+// restores a stale overlay + scroll lock. While the overlay is up, the page
+// behind it is inert-ed per element with prior state saved (the same modal
+// contract as alert_dialog/sheet/sidebar — the helper is duplicated per
+// controller by design); restore runs on dismiss (via the overlay's
+// phlex-kit--command:dismiss event), disconnect, AND turbo:before-cache.
 // Connects to data-controller="phlex-kit--command-dialog"
 export default class extends Controller {
   static targets = ["content"];
 
   initialize() {
     this.overlay = null;
+    this.inerted = null;
+    // The command controller's dismiss() dispatches this on the overlay
+    // BEFORE it removes the clone / restores focus — un-inert first so the
+    // opener is focusable again.
+    this.restoreInert = () => {
+      for (const [el, wasInert] of this.inerted || []) el.inert = wasInert;
+      this.inerted = null;
+    };
     this.clearOverlay = () => {
+      this.restoreInert();
       if (this.overlay?.isConnected) {
         this.overlay.remove();
         document.body.style.removeProperty("overflow");
@@ -49,7 +62,23 @@ export default class extends Controller {
 
     document.body.insertAdjacentHTML("beforeend", this.contentTarget.innerHTML);
     this.overlay = document.body.lastElementChild;
+    this.overlay.addEventListener("phlex-kit--command:dismiss", this.restoreInert);
     // prevent scroll on body
     document.body.style.overflow = "hidden";
+    this.#inertOthers();
+  }
+
+  // Make everything behind the overlay inert (the clone is <body>'s last
+  // child, so its siblings are the whole page). Prior inert state is saved
+  // per element and restored by restoreInert. The command controller's Tab
+  // trap on the clone stays as belt and braces.
+  #inertOthers() {
+    this.inerted = [];
+    for (const el of document.body.children) {
+      if (el === this.overlay) continue;
+      if (["SCRIPT", "STYLE", "LINK", "TEMPLATE"].includes(el.tagName)) continue;
+      this.inerted.push([el, el.inert]);
+      el.inert = true;
+    }
   }
 }

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

@@ -5,6 +5,9 @@ module PhlexKit
   class CommandGroup < BaseComponent
     def initialize(title: nil, **attrs)
       @title = title
+      # Names the role="group" items wrapper via aria-labelledby → heading id
+      # (matches cmdk/shadcn; id pattern mirrors CommandList).
+      @heading_id = "pk-command-group-heading-#{SecureRandom.hex(4)}" if title
       @attrs = attrs
     end
 
@@ -22,11 +25,11 @@ module PhlexKit
     private
 
     def render_header
-      div(group_heading: @title) { @title }
+      div(id: @heading_id, group_heading: @title) { @title }
     end
 
     def render_items(&)
-      div(group_items: "", role: "group", &)
+      div(group_items: "", role: "group", aria_labelledby: @heading_id, &)
     end
   end
 end

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

@@ -18,6 +18,10 @@ module PhlexKit
         class: "pk-command-item",
         href: @href,
         role: "option",
+        # Options in an aria-activedescendant listbox are not tab stops —
+        # keyboard access is arrows/Enter from the input (cmdk parity); a
+        # tabbable anchor per row also made disabled items focusable.
+        tabindex: "-1",
         aria: { disabled: (@disabled ? "true" : nil) },
         data: {
           phlex_kit__command_target: "item",

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

@@ -3,13 +3,17 @@ module PhlexKit
   # 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)
+    # id: is a named kwarg (not left in **attrs) because `mix` would *merge* a
+    # caller id with the generated one into an invalid two-token id, breaking
+    # aria-controls (the documented list_id: wiring) and derived result ids.
+    def initialize(id: nil, **attrs)
+      @id = id || "pk-command-list-#{SecureRandom.hex(4)}"
       @attrs = attrs
     end
 
     def view_template(&)
       div(**mix({
-        id: "pk-command-list-#{SecureRandom.hex(4)}",
+        id: @id,
         class: "pk-command-list",
         role: "listbox",
         data: { phlex_kit__command_target: "list" }

data/app/components/phlex_kit/context_menu/context_menu_controller.js

@@ -23,12 +23,37 @@ export default class extends Controller {
       this.close()
     }
     this.onKey = (e) => this.keydown(e)
+    // Turbo snapshots BEFORE disconnect — close now or the snapshot keeps a
+    // stale data-state="open" (the panel itself can't resurrect, but host
+    // CSS keyed on the state hook would misfire after a restore).
+    this.onBeforeCache = () => {
+      if (this.contentTarget.matches(":popover-open")) this.close()
+    }
+    document.addEventListener("turbo:before-cache", this.onBeforeCache)
+    // Outstanding syncSub rAF handles — cancelled on disconnect (menubar's
+    // pattern).
+    this.subFrames = new Set()
   }
 
   disconnect() {
     document.removeEventListener("click", this.onDoc)
     document.removeEventListener("contextmenu", this.onDoc)
     document.removeEventListener("keydown", this.onKey)
+    document.removeEventListener("turbo:before-cache", this.onBeforeCache)
+    this.subFrames.forEach((id) => cancelAnimationFrame(id))
+    this.subFrames.clear()
+  }
+
+  // Mirrors the CSS-driven submenu state (:hover / :focus-within) onto the
+  // sub trigger's aria-expanded — same wiring as dropdown_menu/menubar.
+  syncSub(e) {
+    const sub = e.currentTarget
+    const id = requestAnimationFrame(() => {
+      this.subFrames.delete(id)
+      sub.querySelector(":scope > [aria-haspopup]")
+        ?.setAttribute("aria-expanded", sub.matches(":hover, :focus-within"))
+    })
+    this.subFrames.add(id)
   }
 
   open(e) {

data/app/components/phlex_kit/context_menu/context_menu_sub.rb

@@ -5,7 +5,9 @@ module PhlexKit
   class ContextMenuSub < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-context-menu-sub" }, @attrs), &)
+      # syncSub mirrors the CSS-driven reveal state onto the sub trigger's
+      # aria-expanded (same wiring as DropdownMenuSub / MenubarSub).
+      div(**mix({ class: "pk-context-menu-sub", data: { action: "mouseenter->phlex-kit--context-menu#syncSub mouseleave->phlex-kit--context-menu#syncSub focusin->phlex-kit--context-menu#syncSub focusout->phlex-kit--context-menu#syncSub" } }, @attrs), &)
     end
   end
 end