phlex_kit 0.8.1 → 0.9.0

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

@@ -41,7 +41,7 @@
 .pk-combobox-trigger:disabled,
 .pk-combobox-trigger[aria-disabled="true"] { pointer-events: none; opacity: .5; }
 .pk-combobox-trigger-content { overflow: hidden; text-overflow: ellipsis; }
-.pk-combobox-trigger-icon { flex: none; width: 1rem; height: 1rem; margin-left: .5rem; opacity: .5; }
+.pk-combobox-trigger-icon { flex: none; width: 1rem; height: 1rem; margin-inline-start: .5rem; opacity: .5; }
 
 /* Dropdown panel — anchored below the combobox, flips above at the viewport
    bottom. Width: trigger width with a 15rem floor (was JS
@@ -58,7 +58,7 @@
   border-radius: var(--pk-radius);
   background: var(--pk-surface);
   color: var(--pk-text);
-  box-shadow: 0 4px 16px rgba(0, 0, 0, .4);
+  box-shadow: 0 4px 16px color-mix(in srgb, var(--pk-shadow-color) 40%, transparent);
 }
 
 /* Search row. */
@@ -69,7 +69,7 @@
   border-bottom: 1px solid var(--pk-border);
   color: var(--pk-muted);
 }
-.pk-combobox-search-icon { flex: none; width: 1rem; height: 1rem; margin-right: .5rem; opacity: .5; }
+.pk-combobox-search-icon { flex: none; width: 1rem; height: 1rem; margin-inline-end: .5rem; opacity: .5; }
 .pk-combobox-search-input {
   width: 100%;
   height: 2rem;
@@ -95,8 +95,10 @@
   color: var(--pk-text);
 }
 
-/* Labelled group — the label renders from the `label` attribute, and the group
-   hides itself (pure CSS) when filtering leaves no visible item inside. */
+/* Labelled group — the label renders from the `data-label` attribute (the
+   invalid bare `label` attribute was dropped; aria-label carries it for AT),
+   and the group hides itself (pure CSS) when filtering leaves no visible item
+   inside. */
 .pk-combobox-group { display: none; }
 .pk-combobox-group:has(label:not(.pk-hidden)) {
   display: flex;
@@ -106,7 +108,7 @@
   border-bottom: 1px solid var(--pk-border);
 }
 .pk-combobox-group::before {
-  content: attr(label);
+  content: attr(data-label);
   padding: .375rem .5rem;
   font-size: .75rem;
   font-weight: 500;
@@ -159,7 +161,7 @@
 
 /* Trailing ✓, visible while the row's input is checked. */
 .pk-combobox-item-indicator {
-  margin-left: auto;
+  margin-inline-start: auto;
   width: 1rem;
   height: 1rem;
   flex: none;
@@ -314,7 +316,7 @@
   align-items: center;
   justify-content: center;
   flex: none;
-  margin-left: auto;
+  margin-inline-start: auto;
   border: 0;
   border-radius: .125rem;
   padding: 0;

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

@@ -37,23 +37,37 @@ export default class extends Controller {
 
   selectedItemIndex = null
 
+  initialize() {
+    // Stimulus fires [target]Connected before connect(): anything
+    // itemTargetConnected uses must be initialized here.
+    this.itemIdCounter = 0
+    this.refocusing = false
+  }
+
   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).
+  // ARIA plumbing: aria-controls is wired to the listbox (mirrors
+  // select_controller.js); the per-option ids come from itemTargetConnected.
   generateItemIds() {
+    this.ariaExpandedElements().forEach((el) => el.setAttribute("aria-controls", this.listId()))
+  }
+
+  listId() {
     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)}`
+    return list.id
+  }
 
-    this.itemTargets.forEach((item, index) => {
-      if (!item.id) item.id = `${list.id}-${index}`
-    })
-
-    this.ariaExpandedElements().forEach((el) => el.setAttribute("aria-controls", list.id))
+  // Every option gets an id derived from the listbox id so the combobox
+  // element can point aria-activedescendant at the keyboard highlight. A
+  // target callback (not a connect() loop) so options added after connect —
+  // e.g. rendered in by the host — get ids too. Counter-based, so a removed
+  // option's id is never reissued to a later arrival.
+  itemTargetConnected(item) {
+    if (!item.id) item.id = `${this.listId()}-${this.itemIdCounter++}`
   }
 
   // The elements carrying the open/closed combobox state: the trigger button
@@ -233,6 +247,14 @@ export default class extends Controller {
   }
 
   openPopover(event) {
+    // The remove-× on a chip and the clear-all button live inside the badge
+    // trigger, whose focusin (and click) actions open the popover — clicking
+    // them must not reopen it (stopPropagation covers click but focusin still
+    // fires when the button takes focus).
+    if (event?.target?.closest?.(".pk-combobox-badge-remove, .pk-combobox-clear-button")) return
+    // closePopover's focus restore fires the input/badge wrapper's
+    // focusin->openPopover action synchronously — don't bounce straight back open.
+    if (this.refocusing) return
     if (event) event.preventDefault()
     if (this.isOpen()) return
 
@@ -252,12 +274,31 @@ export default class extends Controller {
   }
 
   closePopover() {
+    // 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
+    // page (onClickOutside) must not have its focus stolen.
+    const focusWasInside = this.hasPopoverTarget && this.popoverTarget.contains(document.activeElement)
+
     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
+
+    if (focusWasInside) {
+      const field = this.filterField()
+      // Input/badge layouts: back to the filter field (it lives outside the
+      // popover). Button layout: back to the trigger button (its search input
+      // is inside the popover, now hidden).
+      const anchor = (field && !this.popoverTarget.contains(field)) ? field : (this.hasTriggerTarget ? this.triggerTarget : null)
+      // focus() dispatches focusin synchronously; the flag stops the
+      // wrapper's focusin->openPopover action from reopening the panel.
+      this.refocusing = true
+      anchor?.focus()
+      this.refocusing = false
+    }
   }
 
   onClickOutside(event) {
@@ -277,7 +318,9 @@ export default class extends Controller {
   }
 
   filterItems(e) {
-    if (["ArrowDown", "ArrowUp", "Tab", "Enter"].includes(e.key)) {
+    // Escape's keyup arrives after keydown.esc already closed the popover —
+    // re-running the filter then would wipe the highlight state for nothing.
+    if (["ArrowDown", "ArrowUp", "Tab", "Enter", "Escape"].includes(e.key)) {
       return
     }
 

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

@@ -1,14 +1,22 @@
 module PhlexKit
-  # Labelled option group. Pass `label:` as a plain attribute — CSS renders it via
-  # ::before content(attr(label)), and the group auto-hides (pure CSS :has) when
-  # filtering leaves it with no visible items. See combobox.rb.
+  # Labelled option group. Pass `label:` — it renders as aria-label (a bare
+  # `label` attribute is invalid on <div> and silent to AT) plus data-label,
+  # which CSS renders via ::before content(attr(data-label)). The group
+  # auto-hides (pure CSS :has) when filtering leaves it with no visible items.
+  # See combobox.rb.
   class ComboboxListGroup < BaseComponent
-    def initialize(**attrs)
+    def initialize(label: nil, **attrs)
+      @label = label
       @attrs = attrs
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-combobox-group", role: "group" }, @attrs), &)
+      div(**mix({
+        class: "pk-combobox-group",
+        role: "group",
+        aria: { label: @label },
+        data: { label: @label }
+      }, @attrs), &)
     end
   end
 end

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

@@ -19,7 +19,7 @@
   inset: 0;
   z-index: 50;
   pointer-events: auto;
-  background: rgb(0 0 0 / .1);
+  background: color-mix(in srgb, var(--pk-overlay) 10%, transparent);
   backdrop-filter: blur(4px);
 }
 
@@ -37,7 +37,7 @@
   border-radius: .75rem;
   background: var(--pk-surface);
   color: var(--pk-text);
-  box-shadow: 0 10px 30px rgb(0 0 0 / .35);
+  box-shadow: 0 10px 30px color-mix(in srgb, var(--pk-shadow-color) 35%, transparent);
 }
 .pk-command-dialog.xs { max-width: 24rem; }
 .pk-command-dialog.sm { max-width: 28rem; }
@@ -121,7 +121,7 @@
 .pk-command-item[data-disabled] { pointer-events: none; opacity: .5; }
 
 .pk-command-shortcut {
-  margin-left: auto;
+  margin-inline-start: auto;
   font-size: .75rem;
   letter-spacing: .1em;
   color: var(--pk-muted);
@@ -136,5 +136,5 @@
   font-size: .875rem;
 }
 @supports not (backdrop-filter: blur(1px)) {
-  .pk-command-overlay { background: rgb(0 0 0 / .5); }
+  .pk-command-overlay { background: color-mix(in srgb, var(--pk-overlay) 50%, transparent); }
 }

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

@@ -47,11 +47,19 @@ export default class extends Controller {
     }
 
     this.generateItemIds();
-    this.inputTarget.focus();
+    // 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);
   }
 
+  // The command-dialog controller clones its <template> content into <body>;
+  // the clone's wrapper carries this marker (CommandDialogContent renders it).
+  isDialogClone() {
+    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).
@@ -67,15 +75,37 @@ export default class extends Controller {
   }
 
   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();
+    // Cloned dialog overlay: tear the clone down and hand focus back.
+    if (this.isDialogClone()) {
+      // 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();
+      }
+      return;
     }
+
+    // Inline palette: removing the element would delete it permanently.
+    // Reset the query instead and let the host react via the dispatched
+    // phlex-kit--command:dismiss event.
+    if (this.hasInputTarget && this.inputTarget.value !== "") {
+      this.inputTarget.value = "";
+      this.deselectAll();
+      this.resetVisibility();
+      this.announceResultCount(null);
+    }
+    this.dispatch("dismiss");
+  }
+
+  // Guards the items' default href="#": without it an Enter-synthesized
+  // click() or a mouse click scrolls to top and appends # to the URL
+  // (mirrors dropdown_menu_controller's close() guard).
+  onItemClick(event) {
+    if (event?.target?.closest?.('a[href="#"]')) event.preventDefault();
   }
 
   // Focus trap for the cloned dialog overlay: Tab / Shift+Tab cycle among the
@@ -173,16 +203,25 @@ export default class extends Controller {
 
   // 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) => ({ item, score: fuzzyScore(q, item.value) }))
+          .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);
       },
@@ -225,6 +264,8 @@ export default class extends Controller {
     }
 
     this.toggleAriaSelected(visibleItems[this.selectedIndex], true);
+    // Keep the highlight visible inside the max-height scrollable list.
+    visibleItems[this.selectedIndex].scrollIntoView({ block: "nearest" });
 
     // Focus stays in the input; the highlighted option is exposed via
     // aria-activedescendant (result ids come from generateItemIds).

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

@@ -1,7 +1,9 @@
 module PhlexKit
   # Wrapper wiring a CommandDialogTrigger to its CommandDialogContent. The
-  # outlet selector finds the live palette instance (if already open) so a
-  # second trigger press just refocuses the input. See command.rb.
+  # controller tracks its own live clone (sheet pattern) so a second trigger
+  # press just refocuses the input — per instance, unlike the old
+  # document-scoped outlet selector, which let one dialog adopt another's
+  # open palette. See command.rb.
   class CommandDialog < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
@@ -9,10 +11,7 @@ module PhlexKit
 
     def view_template(&)
       div(**mix({
-        data: {
-          controller: "phlex-kit--command-dialog",
-          phlex_kit__command_dialog_phlex_kit__command_outlet: "[data-phlex-kit--command-dialog-instance]"
-        }
+        data: { controller: "phlex-kit--command-dialog" }
       }, @attrs), &)
     end
   end

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

@@ -2,18 +2,33 @@ import { Controller } from "@hotwired/stimulus";
 
 // Ported from ruby_ui's command-dialog controller (Stimulus-only upstream),
 // identifiers renamed ruby-ui → phlex-kit and the Tailwind body scroll-lock
-// class swapped for inline overflow (matching the shipped dialog).
+// class swapped for inline overflow (matching the shipped dialog). Unlike
+// 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.
 // Connects to data-controller="phlex-kit--command-dialog"
 export default class extends Controller {
   static targets = ["content"];
-  static outlets = ["phlex-kit--command"];
 
-  phlexKitCommandOutletConnected(controller) {
-    this.openOutlet = controller;
+  initialize() {
+    this.overlay = null;
+    this.clearOverlay = () => {
+      if (this.overlay?.isConnected) {
+        this.overlay.remove();
+        document.body.style.removeProperty("overflow");
+      }
+      this.overlay = null;
+    };
   }
 
-  phlexKitCommandOutletDisconnected() {
-    this.openOutlet = null;
+  connect() {
+    document.addEventListener("turbo:before-cache", this.clearOverlay);
+  }
+
+  disconnect() {
+    document.removeEventListener("turbo:before-cache", this.clearOverlay);
+    this.clearOverlay();
   }
 
   open(e) {
@@ -25,12 +40,15 @@ export default class extends Controller {
       return;
     }
 
-    if (this.openOutlet) {
-      this.openOutlet.focusInput();
+    // Already open (the command controller's dismiss may have removed the
+    // clone behind our back — isConnected catches that): just refocus.
+    if (this.overlay?.isConnected) {
+      this.overlay.querySelector("[data-phlex-kit--command-target='input']")?.focus();
       return;
     }
 
     document.body.insertAdjacentHTML("beforeend", this.contentTarget.innerHTML);
+    this.overlay = document.body.lastElementChild;
     // prevent scroll on body
     document.body.style.overflow = "hidden";
   }

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

@@ -8,9 +8,13 @@ module PhlexKit
   # 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...", list_id: nil, **attrs)
+    # `autofocus:` defaults off so an inline palette doesn't steal page focus
+    # on load; the dialog clone needs no autofocus either — the command
+    # controller's connect() focuses the input when the clone is inserted.
+    def initialize(placeholder: "Type a command or search...", list_id: nil, autofocus: false, **attrs)
       @placeholder = placeholder
       @list_id = list_id
+      @autofocus = autofocus
       @attrs = attrs
     end
 
@@ -25,7 +29,7 @@ module PhlexKit
             autocomplete: "off",
             autocorrect: "off",
             spellcheck: "false",
-            autofocus: true,
+            autofocus: @autofocus,
             role: "combobox",
             value: "",
             aria: { autocomplete: "list", expanded: "true", controls: @list_id },

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

@@ -23,7 +23,10 @@ module PhlexKit
           phlex_kit__command_target: "item",
           value: @value,
           text: @text,
-          disabled: (@disabled ? "true" : nil)
+          disabled: (@disabled ? "true" : nil),
+          # Guards the default href="#": without it a mouse click (or the
+          # Enter-synthesized click()) scrolls to top and appends # to the URL.
+          action: "click->phlex-kit--command#onItemClick"
         }
       }, @attrs), &)
     end

data/app/components/phlex_kit/context_menu/context_menu.css

@@ -9,7 +9,7 @@
 .pk-context-menu-content {
   position: fixed; inset: auto; margin: 0; min-width: 8rem; overflow: visible;
   border: 1px solid var(--pk-border); border-radius: calc(var(--pk-radius) - 2px); background: var(--pk-surface);
-  color: var(--pk-text); padding: .25rem; box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
+  color: var(--pk-text); padding: .25rem; box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent); outline: none;
 }
 .pk-context-menu-item {
   position: relative; display: flex; align-items: center; gap: .5rem;
@@ -20,15 +20,15 @@
 .pk-context-menu-item > svg { flex: none; width: 1rem; height: 1rem; color: var(--pk-muted); }
 .pk-context-menu-item:hover, .pk-context-menu-item:focus { background: var(--pk-accent); color: var(--pk-text); }
 .pk-context-menu-item[data-disabled="true"] { pointer-events: none; opacity: .5; }
-.pk-context-menu-item.inset { padding-left: 2rem; }
+.pk-context-menu-item.inset { padding-inline-start: 2rem; }
 .pk-context-menu-check {
   display: inline-flex; align-items: center; justify-content: center;
   flex: none; width: 1rem; height: 1rem;
 }
 .pk-context-menu-check svg { width: .875rem; height: .875rem; }
-.pk-context-menu-shortcut { margin-left: auto; font-size: .75rem; letter-spacing: .1em; color: var(--pk-muted); }
+.pk-context-menu-shortcut { margin-inline-start: auto; font-size: .75rem; letter-spacing: .1em; color: var(--pk-muted); }
 .pk-context-menu-label { padding: .375rem .5rem; font-size: .875rem; font-weight: 600; color: var(--pk-text); }
-.pk-context-menu-label.inset { padding-left: 2rem; }
+.pk-context-menu-label.inset { padding-inline-start: 2rem; }
 .pk-context-menu-separator { height: 1px; margin: .25rem -.25rem; background: var(--pk-border); }
 .pk-context-menu-group { display: contents; }
 
@@ -71,7 +71,7 @@
    The row is its own scoped anchor; the panel flips to the other side at
    the viewport right edge. */
 .pk-context-menu-sub { anchor-name: --pk-context-menu-sub; anchor-scope: --pk-context-menu-sub; }
-.pk-context-menu-sub-chevron { margin-left: auto; width: 1rem; height: 1rem; }
+.pk-context-menu-sub-chevron { margin-inline-start: auto; width: 1rem; height: 1rem; }
 .pk-context-menu-sub-content {
   position: fixed;
   position-anchor: --pk-context-menu-sub;
@@ -92,7 +92,7 @@
   background: var(--pk-surface);
   color: var(--pk-text);
   padding: .25rem;
-  box-shadow: 0 8px 24px rgb(0 0 0 / .3);
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent);
 }
 .pk-context-menu-sub:hover > .pk-context-menu-sub-content,
 .pk-context-menu-sub:focus-within > .pk-context-menu-sub-content { display: block; }

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

@@ -12,12 +12,22 @@ export default class extends Controller {
   static targets = ["content", "trigger", "menuItem"]
 
   connect() {
-    this.onDoc = (e) => { if (!this.contentTarget.contains(e.target)) this.close() }
+    this.onDoc = (e) => {
+      if (this.contentTarget.contains(e.target)) return
+      // The opening right-click bubbles to document AFTER open() adds this
+      // listener — a contextmenu inside our own element must not close what
+      // it just opened (it repositions instead). A contextmenu anywhere
+      // else closes us, which also covers opening a second kit context
+      // menu: its trigger's contextmenu is "outside" for this instance.
+      if (e.type === "contextmenu" && this.element.contains(e.target)) return
+      this.close()
+    }
     this.onKey = (e) => this.keydown(e)
   }
 
   disconnect() {
     document.removeEventListener("click", this.onDoc)
+    document.removeEventListener("contextmenu", this.onDoc)
     document.removeEventListener("keydown", this.onKey)
   }
 
@@ -38,14 +48,21 @@ export default class extends Controller {
     c.style.top = `${y}px`
     c.dataset.state = "open"
     document.addEventListener("click", this.onDoc)
+    document.addEventListener("contextmenu", this.onDoc)
     document.addEventListener("keydown", this.onKey)
     this.items()[0]?.focus()
   }
 
   close(opts = {}) {
+    // Menu rows default to href="#"; without this an Enter/click on a
+    // non-link row scrolls to top and appends # to the URL. (`opts` is the
+    // click event when close runs as the item's data-action; Enter/Space
+    // arrive here too, via keydown()'s synthesized click.)
+    if (opts?.target?.closest?.('a[href="#"]')) opts.preventDefault()
     if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover()
     this.contentTarget.dataset.state = "closed"
     document.removeEventListener("click", this.onDoc)
+    document.removeEventListener("contextmenu", this.onDoc)
     document.removeEventListener("keydown", this.onKey)
     if (opts.refocus === true) this.anchor().focus()
   }

data/app/components/phlex_kit/data_table/data_table.css

@@ -22,7 +22,7 @@
 
 /* "Columns" dropdown rows. */
 .pk-data-table-column-toggle { position: relative; }
-.pk-data-table-column-toggle-icon { width: 1rem; height: 1rem; margin-left: .25rem; }
+.pk-data-table-column-toggle-icon { width: 1rem; height: 1rem; margin-inline-start: .25rem; }
 .pk-data-table-column-option {
   display: flex;
   align-items: center;

data/app/components/phlex_kit/data_table/data_table_column_toggle.rb

@@ -22,18 +22,17 @@ module PhlexKit
           end
           render DropdownMenuContent.new do
             @columns.each do |col|
-              label(class: "pk-data-table-column-option") do
-                input(
-                  type: :checkbox,
-                  checked: true,
-                  class: "pk-checkbox",
-                  data: {
-                    column_key: col[:key].to_s,
-                    action: "change->phlex-kit--data-table-column-visibility#toggle"
-                  }
-                )
-                span { plain col[:label] }
-              end
+              # A real menu row (role="menuitemcheckbox" + aria-checked, arrow-
+              # navigable) — plain <label>s directly inside role="menu" are
+              # invalid ARIA. The change event bubbles from the hidden checkbox
+              # to this row, where our toggle action picks it up.
+              render DropdownMenuCheckboxItem.new(
+                checked: true,
+                data: {
+                  column_key: col[:key].to_s,
+                  action: "change->phlex-kit--data-table-column-visibility#toggle"
+                }
+              ) { plain col[:label] }
             end
           end
         end

data/app/components/phlex_kit/data_table/data_table_column_visibility_controller.js

@@ -7,8 +7,11 @@ import { Controller } from "@hotwired/stimulus";
 // Connects to data-controller="phlex-kit--data-table-column-visibility"
 export default class extends Controller {
   toggle(event) {
-    const key = event.target.dataset.columnKey;
+    // The change event originates on the checkbox, but data-column-key lives
+    // on the menu row (DropdownMenuCheckboxItem) — look up through ancestors.
+    const key = event.target.closest("[data-column-key]")?.dataset.columnKey;
     const visible = event.target.checked;
+    if (!key) return;
     const root = this.element.closest('[data-controller~="phlex-kit--data-table"]');
     if (!root) return;
     root

data/app/components/phlex_kit/data_table/data_table_pagy_adapter.rb

@@ -12,6 +12,7 @@ module PhlexKit
 
     def total_count = @pagy.count
 
-    def per_page = @pagy.items
+    # Pagy 9 renamed #items to #limit (and removed #items) — support both.
+    def per_page = @pagy.respond_to?(:limit) ? @pagy.limit : @pagy.items
   end
 end