phlex_kit 0.12.0 → 0.14.0

data/app/components/phlex_kit/chart/chart.rb

@@ -31,7 +31,7 @@ module PhlexKit
       # Canvas content is invisible to AT — announce it as an image with at
       # least a generic name; pass aria: { label: "…" } (or block fallback
       # content) to describe the actual data.
-      base[:role] = "img" unless @attrs.key?(:role) || @attrs.key?("role")
+      base[:role] = "img" unless attr_set?(:role)
       base[:aria] = { label: "Chart" } unless aria_labelled?
       canvas(**mix(base, @attrs), &)
     end

data/app/components/phlex_kit/chart/chart_controller.js

@@ -29,7 +29,11 @@ export default class extends Controller {
     this.disconnectThemeObservers()
     this.chart?.destroy()
     if (!this.chart) {
-      this.dispatch("disconnect", { detail: { canvas: this.element } })
+      // Dispatch on document, not this.element: disconnect() runs AFTER the
+      // canvas has left the DOM, so an event fired on it neither bubbles nor
+      // reaches document/window — delegated host listeners would never see it.
+      // The canvas rides the detail so the host can still match its instance.
+      this.dispatch("disconnect", { target: document, detail: { canvas: this.element } })
     }
   }
 

data/app/components/phlex_kit/checkbox/checkbox.css

@@ -48,6 +48,22 @@
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 40%, transparent);
 }
 .pk-checkbox[aria-invalid="true"]:checked { border-color: var(--pk-brand); }
+/* Invalid + keyboard focus: the always-on invalid ring above would otherwise
+   swallow the equal-specificity :focus-visible rule, leaving no visible focus
+   change. Keep the red border (invalid stays legible) but switch the ring to
+   the standard focus color — the theme-scoped arms outweigh the theme-scoped
+   invalid copies below. */
+.pk-checkbox[aria-invalid="true"]:focus-visible,
+:root[data-theme="light"] .pk-checkbox[aria-invalid="true"]:focus-visible {
+  border-color: var(--pk-red);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
+}
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] .pk-checkbox[aria-invalid="true"]:focus-visible {
+    border-color: var(--pk-red);
+    box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
+  }
+}
 .pk-checkbox:disabled { cursor: not-allowed; opacity: .5; }
 :root[data-theme="light"] .pk-checkbox:not(:checked):not(:indeterminate) { background: transparent; }
 :root[data-theme="light"] .pk-checkbox[aria-invalid="true"] {

data/app/components/phlex_kit/checkbox/checkbox.rb

@@ -8,11 +8,29 @@ module PhlexKit
   # `name:`/`value:`/`checked:`/`**on(...)` pass through via `mix`. Styled by
   # `.pk-checkbox` (checkbox.css).
   class Checkbox < BaseComponent
-    def initialize(**attrs)
+    # include_hidden mirrors Rails' check_box (and PhlexKit::Switch): an
+    # unchecked box posts nothing, so a paired hidden field carries the
+    # unchecked value. Emitted only when a `name:` is present — and never for
+    # array-style names ("ids[]"), where an unchecked "0" would inject a
+    # bogus element into the collection param (use a single blank hidden for
+    # the whole collection instead, as Rails' collection helpers do).
+    def initialize(include_hidden: true, unchecked_value: "0", **attrs)
+      @include_hidden = include_hidden
+      @unchecked_value = unchecked_value
       @attrs = attrs
     end
 
     def view_template
+      if @include_hidden && @attrs[:name] && !@attrs[:name].to_s.end_with?("[]")
+        # Disabled in lockstep with the checkbox (Rails' check_box idiom) —
+        # a disabled checkbox must not still post its unchecked value.
+        # form: rides along too (Rails' check_box slices name/disabled/form
+        # onto the hidden field) — a form-attributed checkbox outside its
+        # <form> must post the unchecked value to the same form.
+        input(type: "hidden", name: @attrs[:name], value: @unchecked_value,
+          disabled: @attrs[:disabled] ? true : nil,
+          form: @attrs[:form] || @attrs["form"])
+      end
       input(**mix({
         type: :checkbox,
         class: "pk-checkbox",

data/app/components/phlex_kit/clipboard/clipboard.rb

@@ -13,6 +13,13 @@ module PhlexKit
         div(&block)
         render PhlexKit::ClipboardPopover.new(type: :success) { @success }
         render PhlexKit::ClipboardPopover.new(type: :error) { @error }
+        # A persistent (never display:none) sr-only live region: the visual
+        # popovers are shown by removing display:none, which re-inserts them
+        # into the a11y tree with pre-existing content — a change AT does not
+        # announce. This region stays in the tree; the controller writes the
+        # confirmation text into it on copy, and THAT mutation announces.
+        div(class: "pk-sr-only", role: "status", aria: { live: "polite" },
+            data: { phlex_kit__clipboard_target: "liveRegion" })
       end
     end
   end

data/app/components/phlex_kit/clipboard/clipboard_controller.js

@@ -4,7 +4,7 @@ import { Controller } from "@hotwired/stimulus"
 // flashes a success/error popover (CSS-positioned, no @floating-ui). Ported from ruby_ui.
 export default class extends Controller {
   // No "trigger" target: the click->#copy action alone wires the trigger.
-  static targets = ["source", "successPopover", "errorPopover"]
+  static targets = ["source", "successPopover", "errorPopover", "liveRegion"]
 
   connect() {
     // Turbo snapshots at turbo:before-cache, BEFORE disconnect — hide the
@@ -49,6 +49,17 @@ export default class extends Controller {
   show(target) {
     this.hideAll()
     target.classList.remove("pk-hidden")
+    // Announce via the persistent live region (not the visual popover, which
+    // display:none keeps out of the a11y tree). Clear then re-assert on the
+    // next frame so an identical consecutive message still reads as a content
+    // change — aria-live announces changes, not the current state.
+    if (this.hasLiveRegionTarget) {
+      const message = target.textContent.trim()
+      this.liveRegionTarget.textContent = ""
+      requestAnimationFrame(() => {
+        if (this.hasLiveRegionTarget) this.liveRegionTarget.textContent = message
+      })
+    }
     clearTimeout(this.timer)
     this.timer = setTimeout(() => target.classList.add("pk-hidden"), 1500)
   }

data/app/components/phlex_kit/clipboard/clipboard_popover.rb

@@ -6,9 +6,11 @@ module PhlexKit
       @attrs = attrs
     end
     def view_template(&block)
-      # role="status": the shown/hidden confirmation is a live region, so
-      # screen readers announce "Copied!" instead of a silent visual flash.
-      div(class: "pk-clipboard-popover pk-hidden", role: "status", data: { phlex_kit__clipboard_target: fetch_option(TARGETS, @type, :target) }) do
+      # Visual-only now (aria-hidden): the announcement rides Clipboard's
+      # persistent sr-only role="status" live region — toggling display:none
+      # on this element never announced, since AT ignores content that was
+      # already present when a region re-enters the tree.
+      div(class: "pk-clipboard-popover pk-hidden", aria: { hidden: "true" }, data: { phlex_kit__clipboard_target: fetch_option(TARGETS, @type, :target) }) do
         div(**mix({ class: "pk-clipboard-popover-inner" }, @attrs), &block)
       end
     end

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

@@ -15,8 +15,8 @@ module PhlexKit
       # Defaults only when the caller didn't supply their own — `mix` would
       # fuse tabindex="0 -1" / role="region article" instead of overriding.
       base = { class: "pk-codeblock", data: { syntax: @syntax } }
-      base[:tabindex] = "0" unless @attrs.key?(:tabindex) || @attrs.key?("tabindex")
-      base[:role] = "region" unless @attrs.key?(:role) || @attrs.key?("role")
+      base[:tabindex] = "0" unless attr_set?(:tabindex)
+      base[:role] = "region" unless attr_set?(:role)
       # 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?

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

@@ -28,7 +28,7 @@ module PhlexKit
           controller: "phlex-kit--combobox",
           phlex_kit__combobox_term_value: @term,
           phlex_kit__combobox_auto_highlight_value: (@auto_highlight ? "true" : nil),
-          action: "turbo:morph@window->phlex-kit--combobox#updateTriggerContent click@window->phlex-kit--combobox#onClickOutside"
+          action: "turbo:morph@window->phlex-kit--combobox#updateTriggerContent click@window->phlex-kit--combobox#onClickOutside focusout->phlex-kit--combobox#onFocusout"
         }
       }, @attrs)) do
         live_region

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

@@ -9,15 +9,17 @@ module PhlexKit
     end
 
     def view_template
-      button(**mix({
+      base = {
         type: :button,
         class: "pk-combobox-clear-button pk-hidden",
-        aria: { label: "Clear selection" },
         data: {
           phlex_kit__combobox_target: "clearButton",
           action: "phlex-kit--combobox#clearAll"
         }
-      }, @attrs)) do
+      }
+      # Default only when the caller didn't supply their own — `mix` fuses.
+      base[:aria] = { label: "Clear selection" } unless aria_labelled?
+      button(**mix(base, @attrs)) do
         render Icon.new(:x, size: 24)
       end
     end

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

@@ -42,6 +42,10 @@ export default class extends Controller {
     // itemTargetConnected uses must be initialized here.
     this.itemIdCounter = 0
     this.refocusing = false
+    // The query the list is currently filtered by. Initialized to "" so a
+    // caret/modifier keyup on an empty, unfiltered field reads as unchanged
+    // and filterItems skips re-running (which would wipe the highlight).
+    this._lastFilter = ""
   }
 
   connect() {
@@ -109,16 +113,20 @@ export default class extends Controller {
   }
 
   inputChanged(e) {
+    // Uncheck "select all" BEFORE updateTriggerContent: syncAriaSelected reads
+    // the toggle-all checkbox to set its row's aria-selected, so syncing first
+    // left the row marked aria-selected="true" while its checkbox showed
+    // unchecked.
+    if (this.hasToggleAllTarget && !e.target.checked) {
+      this.toggleAllTarget.checked = false
+    }
+
     this.updateTriggerContent()
 
     if (e.target.type == "radio") {
       this.closePopover()
     }
 
-    if (this.hasToggleAllTarget && !e.target.checked) {
-      this.toggleAllTarget.checked = false
-    }
-
     // Selecting from a chip trigger consumes the query: clear it and reshow
     // the full list for the next pick.
     if (this.hasBadgeInputTarget && this.badgeInputTarget.value !== "") {
@@ -336,6 +344,15 @@ export default class extends Controller {
     if (this.hasPopoverTarget && this.popoverTarget.matches(":popover-open")) this.popoverTarget.hidePopover()
     this.updateTriggerContent() // reflect the selection into an input trigger
 
+    // Reset the filter so a REOPEN shows the full list, not the last query's
+    // leftover pk-hidden classes. The input trigger keeps showing the
+    // selection label (updateTriggerContent, above) but that's display-only —
+    // the active query is empty until the user types again; an in-popover or
+    // badge search field is cleared to match.
+    if (this.hasSearchInputTarget) this.searchInputTarget.value = ""
+    if (this.hasBadgeInputTarget) this.badgeInputTarget.value = ""
+    this.applyFilter("")
+
     if (focusWasInside) {
       const field = this.filterField()
       // Input/badge layouts: back to the filter field (it lives outside the
@@ -350,10 +367,26 @@ export default class extends Controller {
     }
   }
 
+  // APG (combobox): Tab out of an open combobox closes the popup —
+  // dropdown_menu's onFocusout pattern. relatedTarget is null when the
+  // window itself blurs; leave the popup alone then. closePopover's
+  // focus-restore is a no-op here (focus has already left the popover, so
+  // focusWasInside is false — the user's Tab target keeps focus).
+  onFocusout(event) {
+    if (!this.isOpen()) return
+    const to = event.relatedTarget
+    if (!to || this.element.contains(to)) return
+    this.closePopover()
+  }
+
   onClickOutside(event) {
     if (!this.isOpen()) return
     if (this.element.contains(event.target)) return
 
+    // Kit-wide dismiss contract: the combobox is POPOVER-family (shadcn
+    // builds it on Popover light-dismiss), so the dismissing outside click
+    // deliberately clicks through — no preventDefault. Only the MENU
+    // overlays (dropdown/context/menubar/select) swallow theirs.
     this.closePopover()
   }
 
@@ -376,7 +409,25 @@ export default class extends Controller {
     const field = (e.target instanceof HTMLInputElement) ? e.target : this.filterField()
     if (!field) return
 
-    this.applyFilter(field.value.toLowerCase())
+    const term = field.value.toLowerCase()
+    // Only re-filter when the query text actually changed. filterItems runs on
+    // every keyup, so caret/modifier keys the exclusion list above misses
+    // (ArrowLeft/Right/Home/End, releasing Shift) would otherwise re-run
+    // applyFilter on the unchanged query and wipe the keyboard highlight
+    // (selectedItemIndex, aria-current, aria-activedescendant).
+    if (term === this._lastFilter) return
+
+    // Typing into a CLOSED input/badge trigger must reveal the results — the
+    // filtering is otherwise invisible (only click/focusin/Arrow keys opened
+    // it). Open without openPopover()'s field.select(), which would select the
+    // just-typed text so the next keystroke replaced it. The button layout's
+    // search field lives inside the popover, so it can't be typed while closed.
+    if (!this.isOpen() && term && (this.hasInputTriggerTarget || this.hasBadgeInputTarget)) {
+      this.setExpanded(true)
+      this.popoverTarget.showPopover()
+    }
+
+    this.applyFilter(term)
   }
 
   // Strips combining diacritical marks after an NFD decomposition, so "é"
@@ -386,6 +437,10 @@ export default class extends Controller {
   }
 
   applyFilter(filterTerm) {
+    // The query the list is currently filtered by — filterItems reads this to
+    // skip re-filtering (and re-wiping the highlight) on caret/modifier keys.
+    this._lastFilter = filterTerm
+
     if (this.hasToggleAllTarget) {
       if (filterTerm) this.toggleAllTarget.parentElement.classList.add("pk-hidden")
       else this.toggleAllTarget.parentElement.classList.remove("pk-hidden")

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

@@ -11,12 +11,15 @@ module PhlexKit
     end
 
     def view_template(&)
-      label(**mix({
+      base = {
         class: "pk-combobox-item",
-        role: "option",
-        aria: { selected: "false" },
         data: { phlex_kit__combobox_target: "item" }
-      }, @attrs), &)
+      }
+      # Defaults only when the caller didn't supply their own — `mix` fuses
+      # (a server-rendered initially-selected option sets its own selected).
+      base[:role] = "option" unless attr_set?(:role)
+      base[:aria] = { selected: "false" } unless aria_key_set?(:selected)
+      label(**mix(base, @attrs), &)
     end
   end
 end

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

@@ -49,6 +49,7 @@ export default class extends Controller {
     // itemTargetConnected uses must be initialized here (mirrors
     // combobox_controller.js).
     this.itemIdCounter = 0;
+    this.orderCounter = 0;
     this.searchEntries = [];
     this.selectedIndex = -1;
   }
@@ -74,7 +75,15 @@ 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.toggleVisibility(this.emptyTargets, false);
+    // Re-derive item + empty-state visibility from the LIVE input value, not an
+    // unconditional hide: a Turbo cache restore of an inline palette can
+    // reconnect with an active no-match query still in the input — hiding the
+    // empty row then showed the query with neither items NOR a "No results".
+    if (this.inputTarget.value) {
+      this.filter({ target: this.inputTarget });
+    } else {
+      this.toggleVisibility(this.emptyTargets, false);
+    }
   }
 
   // The command-dialog controller clones its <template> content into <body>;
@@ -83,6 +92,13 @@ export default class extends Controller {
     return this.element.hasAttribute("data-phlex-kit--command-dialog-instance");
   }
 
+  // Clones are appended as direct <body> children; the last stamped clone is
+  // the visually topmost overlay across all clone-based overlay families.
+  isTopmostClone() {
+    const clones = document.body.querySelectorAll(":scope > [data-pk-overlay-clone]");
+    return clones.length > 0 && clones[clones.length - 1] === this.element;
+  }
+
   // ARIA plumbing: aria-controls is wired to the listbox (mirrors
   // select_controller.js); the per-result ids come from itemTargetConnected.
   generateItemIds() {
@@ -103,6 +119,10 @@ export default class extends Controller {
   // arrival (mirrors combobox_controller.js).
   itemTargetConnected(item) {
     if (!item.id) item.id = `${this.listId()}-${this.itemIdCounter++}`;
+    // Original position, stamped once — filter() reorders rows by fuzzy
+    // score and resetVisibility() restores this order. Survives the
+    // disconnect/reconnect a DOM move itself triggers.
+    if (!item.dataset.pkOrder) item.dataset.pkOrder = String(this.orderCounter++);
     this.searchEntries.push({
       value: (item.dataset.value || "").toLowerCase(),
       text: (item.dataset.text || "").toLowerCase(),
@@ -119,7 +139,22 @@ export default class extends Controller {
     this.selectedIndex = -1;
   }
 
-  dismiss() {
+  dismiss(e) {
+    if (e?.type === "keydown" && this.isDialogClone()) {
+      // The backdrop's Escape binding is window-scoped, so it fires even
+      // with another overlay (alert dialog, sheet) stacked ON TOP of the
+      // palette — those clones are later <body> siblings carrying the same
+      // [data-pk-overlay-clone] marker. Only the topmost clone may act on
+      // Escape (mirrors alert_dialog_controller.js#topmost).
+      if (!this.isTopmostClone()) return;
+      // The input's Escape binding is element-scoped and fires BEFORE lower
+      // overlays' document/window listeners — stop the keydown here, or by
+      // the time they run this clone (and its marker) is already removed and
+      // their own topmost check would wrongly elect them (mirrors
+      // sheet_content_controller.js's Escape guard).
+      e.stopPropagation();
+    }
+
     // Cloned dialog overlay: tear the clone down and hand focus back.
     if (this.isDialogClone()) {
       // Dispatched BEFORE teardown: the command-dialog controller listens on
@@ -210,6 +245,9 @@ export default class extends Controller {
     results.forEach((result) =>
       this.toggleVisibility([result.item.element], true),
     );
+    // cmdk parity: the best match lists first. Within each parent only —
+    // groups keep their identity, matches never jump between them.
+    this.reorderWithinParents(results.map((r) => r.item.element));
 
     this.announceResultCount(results.length);
     this.toggleVisibility(this.emptyTargets, results.length === 0);
@@ -248,6 +286,35 @@ export default class extends Controller {
     this.toggleVisibility(this.groupTargets, true);
     this.toggleVisibility(this.separatorTargets, true);
     this.toggleVisibility(this.emptyTargets, false);
+    // Undo any fuzzy-score reordering: back to server-rendered order.
+    this.reorderWithinParents(
+      [...this.itemTargets].sort((a, b) => Number(a.dataset.pkOrder) - Number(b.dataset.pkOrder)),
+    );
+  }
+
+  // Re-inserts `orderedItems` in the given sequence, each within its own
+  // parent, at the position of that parent's first item row — headings,
+  // separators and empty-state siblings keep their places. (Items are
+  // assumed contiguous within a parent; a separator BETWEEN items of one
+  // parent would drift below them.) The moves retrigger item target
+  // disconnect/connect, which is safe: ids and pkOrder are stamped once,
+  // and filter()/dismiss() have already reset the highlight.
+  reorderWithinParents(orderedItems) {
+    const itemSet = new Set(this.itemTargets);
+    const byParent = new Map();
+    orderedItems.forEach((el) => {
+      const parent = el.parentElement;
+      if (!parent) return;
+      if (!byParent.has(parent)) byParent.set(parent, []);
+      byParent.get(parent).push(el);
+    });
+    byParent.forEach((els, parent) => {
+      const firstItem = [...parent.children].find((c) => itemSet.has(c));
+      const placeholder = document.createComment("");
+      parent.insertBefore(placeholder, firstItem || null);
+      els.forEach((el) => parent.insertBefore(el, placeholder));
+      placeholder.remove();
+    });
   }
 
   // Upstream builds a Fuse index here; this keeps the same result shape —

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

@@ -17,18 +17,27 @@ module PhlexKit
       template(data: { phlex_kit__command_dialog_target: "content" }) do
         # The keydown action is the focus trap: Tab cycles within the cloned
         # overlay instead of escaping to the page underneath.
+        # data-pk-overlay-clone is the common marker stamped by every
+        # clone-based overlay family (see alert_dialog_controller.js#topmost):
+        # it lets stacked overlays of DIFFERENT types resolve which one is
+        # topmost, so one Escape never closes both layers at once.
         div(data: {
           controller: "phlex-kit--command",
           phlex_kit__command_dialog_instance: true,
+          pk_overlay_clone: "",
           action: "keydown->phlex-kit--command#trapFocus"
         }) do
           backdrop
-          div(**mix({
-            class: panel_classes,
-            role: "dialog",
-            aria: { modal: "true", label: @aria_label },
-            data: { state: "open" }
-          }, @attrs), &block)
+          panel_attrs = { class: panel_classes, data: { state: "open" } }
+          # Defaults only when the caller didn't supply their own — `mix`
+          # would fuse role="dialog x" / aria-modal="true false" (same guard
+          # as AlertDialogContent/SheetContent/DrawerContent, round 7).
+          panel_attrs[:role] = "dialog" unless attr_set?(:role)
+          aria = {}
+          aria[:modal] = "true" unless aria_key_set?(:modal)
+          aria[:label] = @aria_label unless aria_labelled?
+          panel_attrs[:aria] = aria unless aria.empty?
+          div(**mix(panel_attrs, @attrs), &block)
         end
       end
     end

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

@@ -1,6 +1,8 @@
 module PhlexKit
-  # "No results" row — hidden by the controller until a filter matches nothing.
-  # See command.rb.
+  # "No results" row — revealed by the controller only when a filter matches
+  # nothing. Server-rendered with pk-hidden so an inline palette doesn't flash
+  # "No results" under its items before Stimulus connects, and doesn't show it
+  # permanently with JS disabled. See command.rb.
   class CommandEmpty < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
@@ -8,7 +10,7 @@ module PhlexKit
 
     def view_template(&)
       div(**mix({
-        class: "pk-command-empty",
+        class: "pk-command-empty pk-hidden",
         role: "presentation",
         data: { phlex_kit__command_target: "empty" }
       }, @attrs), &)

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

@@ -10,7 +10,7 @@ module PhlexKit
       div(**mix({
         class: "pk-command-separator",
         role: "separator",
-        aria: { hidden: true },
+        aria: { hidden: "true" },
         data: { phlex_kit__command_target: "separator" }
       }, @attrs))
     end

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

@@ -12,13 +12,15 @@ module PhlexKit
     end
 
     def view_template(&block)
-      label(**mix({
+      base = {
         class: "pk-context-menu-item pk-context-menu-checkbox-item",
-        role: "menuitemcheckbox",
-        tabindex: "-1",
-        aria: { checked: @checked ? "true" : "false" },
         data: { phlex_kit__context_menu_target: "menuItem" }
-      }, @attrs)) do
+      }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:role] = "menuitemcheckbox" unless attr_set?(:role)
+      base[:tabindex] = "-1" unless attr_set?(:tabindex)
+      base[:"aria-checked"] = (@checked ? "true" : "false") unless aria_key_set?(:checked)
+      label(**mix(base, @attrs)) do
         input(type: :checkbox, class: "pk-context-menu-item-input", name: @name, value: @value, checked: @checked,
               tabindex: "-1", data: { action: "change->phlex-kit--context-menu#syncChecked" })
         span(class: "pk-context-menu-item-indicator", aria: { hidden: "true" }) do

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

@@ -2,7 +2,13 @@ module PhlexKit
   class ContextMenuContent < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-context-menu-content", popover: "manual", role: "menu", tabindex: "-1", aria: { orientation: "vertical" }, data: { phlex_kit__context_menu_target: "content", state: "closed" } }, @attrs), &)
+      base = { class: "pk-context-menu-content", data: { phlex_kit__context_menu_target: "content", state: "closed" } }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:popover] = "manual" unless attr_set?(:popover)
+      base[:role] = "menu" unless attr_set?(:role)
+      base[:tabindex] = "-1" unless attr_set?(:tabindex)
+      base[:aria] = { orientation: "vertical" } unless aria_key_set?(:orientation)
+      div(**mix(base, @attrs), &)
     end
   end
 end

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

@@ -8,12 +8,39 @@ import { Controller } from "@hotwired/stimulus"
 // native [popover=manual] in the top layer (context_menu.css); it is placed
 // in viewport coordinates after showPopover() — a hidden popover has no
 // size — and clamped so it never overflows the viewport (no floating-ui).
+
+// One-shot capture listener swallowing the click an outside mousedown is
+// about to produce (see onDocMousedown; same helper in dropdown/menubar —
+// duplicated per controller by design). {once} self-removes; the DOM
+// dedupes re-arming with the same fn. If the gesture's click never fires
+// (e.g. suppressed after a selection drag) the armed swallow eats the next
+// one — rare enough to accept.
+const swallowClick = (ev) => {
+  // preventDefault alone suppresses only native default actions; the
+  // dismissing outside click would still fire addEventListener handlers on
+  // whatever sits under the pointer. stopPropagation (this listener is
+  // capture-phase on window, the outermost node, so it runs before any deeper
+  // handler) starves those too — the modal-menu contract is that an outside
+  // click ONLY dismisses.
+  ev.preventDefault()
+  ev.stopPropagation()
+}
+function armSwallowClick() {
+  window.addEventListener("click", swallowClick, { once: true, capture: true })
+}
+
 export default class extends Controller {
   static targets = ["content", "trigger", "menuItem"]
 
   connect() {
     this.onDoc = (e) => {
-      if (this.contentTarget.contains(e.target)) return
+      if (this.contentTarget.contains(e.target)) {
+        // A right-click ON the open menu must not pop the NATIVE context menu
+        // on top of it — native menus swallow their own contextmenu. Suppress
+        // it and leave the kit menu open (no reposition for an inside click).
+        if (e.type === "contextmenu") e.preventDefault()
+        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
@@ -22,6 +49,17 @@ export default class extends Controller {
       if (e.type === "contextmenu" && this.element.contains(e.target)) return
       this.close()
     }
+    // Kit-wide dismiss contract (Radix modal-menu parity): a plain click
+    // outside only dismisses — swallowed, like dropdown/menubar/select.
+    // Armed at MOUSEDOWN: the gesture's focusout close() removes onDoc
+    // before the click even fires. Right-button mousedowns are ignored so a
+    // contextmenu elsewhere stays click-through (that's how a second kit —
+    // or the native — context menu opens in the same gesture).
+    this.onDocMousedown = (e) => {
+      if (this.contentTarget.contains(e.target)) return
+      if (e.button !== 0) return
+      armSwallowClick()
+    }
     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
@@ -47,6 +85,7 @@ export default class extends Controller {
   }
 
   disconnect() {
+    document.removeEventListener("mousedown", this.onDocMousedown)
     document.removeEventListener("click", this.onDoc)
     document.removeEventListener("contextmenu", this.onDoc)
     document.removeEventListener("keydown", this.onKey)
@@ -95,6 +134,7 @@ export default class extends Controller {
     c.style.left = `${x}px`
     c.style.top = `${y}px`
     c.dataset.state = "open"
+    document.addEventListener("mousedown", this.onDocMousedown)
     document.addEventListener("click", this.onDoc)
     document.addEventListener("contextmenu", this.onDoc)
     document.addEventListener("keydown", this.onKey)
@@ -109,6 +149,7 @@ export default class extends Controller {
     if (opts?.target?.closest?.('a[href="#"]')) opts.preventDefault()
     if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover()
     this.contentTarget.dataset.state = "closed"
+    document.removeEventListener("mousedown", this.onDocMousedown)
     document.removeEventListener("click", this.onDoc)
     document.removeEventListener("contextmenu", this.onDoc)
     document.removeEventListener("keydown", this.onKey)

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

@@ -4,7 +4,10 @@ module PhlexKit
   class ContextMenuGroup < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-context-menu-group", role: "group" }, @attrs), &)
+      base = { class: "pk-context-menu-group" }
+      # Default only when the caller didn't supply their own — `mix` fuses.
+      base[:role] = "group" unless attr_set?(:role)
+      div(**mix(base, @attrs), &)
     end
   end
 end