phlex_kit 0.10.0 → 0.12.0

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

@@ -26,7 +26,7 @@ export default class extends Controller {
   }
 
   disconnect() {
-    this.themeObserver?.disconnect()
+    this.disconnectThemeObservers()
     this.chart?.destroy()
     if (!this.chart) {
       this.dispatch("disconnect", { detail: { canvas: this.element } })
@@ -44,9 +44,14 @@ export default class extends Controller {
   }
 
   // Kit tokens are plain color values (hex / color-mix results), not the hsl
-  // triplets ruby_ui reads — return them as-is.
+  // triplets ruby_ui reads — return them as-is. Resolved from this.element,
+  // not document.documentElement: a .pk-dark island (_tokens.css:123-129)
+  // sets the --pk-* custom properties at the SUBTREE root, and per-element
+  // getComputedStyle correctly picks up the nearest ancestor's values —
+  // reading from the document root would ignore the island and always
+  // return the page-level theme.
   getThemeColor(name) {
-    return getComputedStyle(document.documentElement).getPropertyValue(`--${name}`).trim()
+    return getComputedStyle(this.element).getPropertyValue(`--${name}`).trim()
   }
 
   // shadcn-style series colors: dataset N takes --pk-chart-(N%5 + 1). Line/area
@@ -80,6 +85,13 @@ export default class extends Controller {
 
   setDefaultColorsForChart() {
     const Chart = this.chartLibrary()
+    // Chart.defaults is a library-wide singleton (chart.js has no per-instance
+    // defaults object), so it can only ever reflect ONE theme — the
+    // documented caveat. It's resolved from the document root, not
+    // this.element: a chart inside a .pk-dark island still gets per-dataset
+    // colors from the island (getThemeColor/seriesColor, above), just not
+    // these library-global defaults (grid/tooltip/legend chrome).
+    //
     // One computed-style resolve for all nine tokens (this runs on every
     // connect; assigning identical values to Chart.defaults is free — charts
     // read defaults at construction — so the style resolves are the only cost
@@ -122,20 +134,37 @@ export default class extends Controller {
   // unrelated class flip is the expensive path.
   initThemeObserver() {
     this._themeKey = this.currentThemeKey()
-    this.themeObserver = new MutationObserver(() => {
+    const onMutate = () => {
       const key = this.currentThemeKey()
       if (key === this._themeKey) return
       this._themeKey = key
       this.refreshChart()
-    })
+    }
+    this.themeObserver = new MutationObserver(onMutate)
     this.themeObserver.observe(document.documentElement, { attributeFilter: ["data-theme", "class"] })
+
+    // A .pk-dark island (_tokens.css:123-129) re-themes a subtree without
+    // touching the document root, so the root-only observer above misses it.
+    // Watch the nearest island ancestor too, if this chart lives inside one.
+    const island = this.element.closest(".pk-dark")
+    if (island && island !== document.documentElement) {
+      this.islandObserver = new MutationObserver(onMutate)
+      this.islandObserver.observe(island, { attributeFilter: ["data-theme", "class"] })
+    }
+  }
+
+  disconnectThemeObservers() {
+    this.themeObserver?.disconnect()
+    this.islandObserver?.disconnect()
   }
 
   // Cheap fingerprint of the resolved theme: two tokens that differ between
-  // every light/dark pair. One style resolve per mutation vs a full chart
-  // rebuild.
+  // every light/dark pair. Resolved from this.element (island-aware, see
+  // getThemeColor) so a mutation on an ancestor .pk-dark island is detected
+  // even though the document root never changes. One style resolve per
+  // mutation vs a full chart rebuild.
   currentThemeKey() {
-    const styles = getComputedStyle(document.documentElement)
+    const styles = getComputedStyle(this.element)
     return `${styles.getPropertyValue("--pk-bg")}|${styles.getPropertyValue("--pk-text")}`
   }
 

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

@@ -3,7 +3,8 @@ import { Controller } from "@hotwired/stimulus"
 // Connects to data-controller="phlex-kit--clipboard". Copies the source text and
 // flashes a success/error popover (CSS-positioned, no @floating-ui). Ported from ruby_ui.
 export default class extends Controller {
-  static targets = ["trigger", "source", "successPopover", "errorPopover"]
+  // No "trigger" target: the click->#copy action alone wires the trigger.
+  static targets = ["source", "successPopover", "errorPopover"]
 
   connect() {
     // Turbo snapshots at turbo:before-cache, BEFORE disconnect — hide the
@@ -28,10 +29,16 @@ export default class extends Controller {
     // A source usually wraps one element (input/code/…), but bare text is
     // legal too — fall back to the source's own text instead of erroring.
     const el = this.sourceTarget.children[0]
+    // TEXTAREA reads .value like INPUT — innerText would return the initial
+    // content, not the user-edited value.
     const text = el
-      ? (el.tagName === "INPUT" ? el.value : el.innerText)
+      ? (["INPUT", "TEXTAREA"].includes(el.tagName) ? el.value : el.innerText)
       : this.sourceTarget.textContent.trim()
     if (!text) { this.show(this.errorPopoverTarget); return }
+    // navigator.clipboard is undefined in insecure contexts (plain-HTTP
+    // hosts, some webviews) — that's the error popover's job, not an
+    // unhandled TypeError's.
+    if (!navigator.clipboard) { this.show(this.errorPopoverTarget); return }
     navigator.clipboard.writeText(text)
       .then(() => this.show(this.successPopoverTarget))
       .catch(() => this.show(this.errorPopoverTarget))

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

@@ -1,6 +1,6 @@
 module PhlexKit
   class ClipboardTrigger < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
-    def view_template(&) = div(**mix({ class: "pk-clipboard-trigger", data: { phlex_kit__clipboard_target: "trigger", action: "click->phlex-kit--clipboard#copy" } }, @attrs), &)
+    def view_template(&) = div(**mix({ class: "pk-clipboard-trigger", data: { action: "click->phlex-kit--clipboard#copy" } }, @attrs), &)
   end
 end

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

@@ -12,7 +12,17 @@ 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
+      # 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")
+      # 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/combobox/combobox.css

@@ -107,7 +107,7 @@
   padding: .25rem 0;
   border-bottom: 1px solid var(--pk-border);
 }
-.pk-combobox-group::before {
+.pk-combobox-group[data-label]::before {
   content: attr(data-label);
   padding: .375rem .5rem;
   font-size: .75rem;

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,15 @@ 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()
+    // Mirrors select_controller.js's connect(): a Turbo snapshot also
+    // serializes the keyboard-highlighted item's aria-current even though
+    // the popover itself does not survive the restore.
+    this.itemTargets.forEach((item) => item.removeAttribute("aria-current"))
     this.generateItemIds()
     this.updateTriggerContent()
   }
@@ -203,7 +212,19 @@ export default class extends Controller {
     remove.textContent = "×"
     remove.addEventListener("click", (e) => {
       e.stopPropagation() // don't reopen the popover via the trigger's click action
+      // Removing a focused chip drops focus with it (the remove button is
+      // torn out of the DOM by the renderBadges() rebuild below) — hand
+      // focus to the badge input instead of stranding it on <body>.
+      const wasFocused = document.activeElement === remove
       this.uncheck(input)
+      // badgeInput sits inside the trigger wrapper, so focusing it bubbles a
+      // focusin the trigger's own focusin->openPopover action would otherwise
+      // reopen — same guard closePopover() uses for its own focus restore.
+      if (wasFocused && this.hasBadgeInputTarget) {
+        this.refocusing = true
+        this.badgeInputTarget.focus()
+        this.refocusing = false
+      }
     })
 
     badge.append(remove)
@@ -217,6 +238,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()
@@ -228,6 +251,10 @@ export default class extends Controller {
   }
 
   clearAll(e) {
+    // The clear button hides itself once nothing is checked (updateTriggerContent
+    // below) — if it held focus, hand focus to the badge input rather than
+    // stranding it on a now-hidden element.
+    const wasFocused = this.hasClearButtonTarget && document.activeElement === this.clearButtonTarget
     if (e) {
       e.preventDefault()
       e.stopPropagation() // the button sits inside the trigger's click-to-open area
@@ -239,6 +266,11 @@ export default class extends Controller {
     })
     if (this.hasToggleAllTarget) this.toggleAllTarget.checked = false
     this.updateTriggerContent()
+    if (wasFocused && this.hasBadgeInputTarget) {
+      this.refocusing = true
+      this.badgeInputTarget.focus()
+      this.refocusing = false
+    }
   }
 
   togglePopover(event) {
@@ -278,7 +310,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
@@ -289,6 +328,11 @@ 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()
+    // Also drop the highlight itself — otherwise a closed combobox still
+    // exposes an aria-current="true" option that Enter would go on to
+    // activate (APG: Enter on a closed combobox must be a no-op).
+    this.selectedItemIndex = null
+    this.itemTargets.forEach(item => item.ariaCurrent = "false")
     if (this.hasPopoverTarget && this.popoverTarget.matches(":popover-open")) this.popoverTarget.hidePopover()
     this.updateTriggerContent() // reflect the selection into an input trigger
 
@@ -335,6 +379,12 @@ export default class extends Controller {
     this.applyFilter(field.value.toLowerCase())
   }
 
+  // Strips combining diacritical marks after an NFD decomposition, so "é"
+  // (query or candidate) matches "e" instead of never comparing equal.
+  normalizeDiacritics(s) {
+    return s.normalize("NFD").replace(/[̀-ͯ]/g, "")
+  }
+
   applyFilter(filterTerm) {
     if (this.hasToggleAllTarget) {
       if (filterTerm) this.toggleAllTarget.parentElement.classList.add("pk-hidden")
@@ -349,10 +399,12 @@ export default class extends Controller {
     // aria-current="true" stayed the Enter target while invisible.
     this.itemTargets.forEach(item => item.ariaCurrent = "false")
 
+    const normalizedFilterTerm = this.normalizeDiacritics(filterTerm)
+
     this.inputTargets.forEach((input) => {
-      const text = this.inputContent(input).toLowerCase()
+      const text = this.normalizeDiacritics(this.inputContent(input).toLowerCase())
 
-      if (text.indexOf(filterTerm) > -1) {
+      if (text.indexOf(normalizedFilterTerm) > -1) {
         input.parentElement.classList.remove("pk-hidden")
         resultCount++
       } else {
@@ -381,6 +433,12 @@ export default class extends Controller {
   keyDownPressed(e) {
     if (e) e.preventDefault()
 
+    // APG: ArrowDown on a closed combobox opens it and highlights the first
+    // option, rather than walking aria-current through invisible options.
+    // openPopover() resets selectedItemIndex to null, so the branch below
+    // still lands on 0.
+    if (!this.isOpen()) this.openPopover()
+
     if (this.selectedItemIndex !== null) {
       this.selectedItemIndex++
     } else {
@@ -393,6 +451,11 @@ export default class extends Controller {
   keyUpPressed(e) {
     if (e) e.preventDefault()
 
+    // Same as keyDownPressed: ArrowUp on a closed combobox opens it and
+    // highlights the last option (wrapSelectedInputIndex turns -1 into the
+    // final index).
+    if (!this.isOpen()) this.openPopover()
+
     if (this.selectedItemIndex !== null) {
       this.selectedItemIndex--
     } else {
@@ -425,6 +488,12 @@ export default class extends Controller {
   }
 
   keyEnterPressed(event) {
+    // APG: Enter on a CLOSED combobox is a no-op — it must not activate
+    // whatever option happened to keep aria-current="true" from before the
+    // popover closed. Bail before preventDefault so a closed field keeps
+    // Enter's ordinary default behaviour.
+    if (!this.isOpen()) return
+
     event.preventDefault()
     const option = this.itemTargets.find(item => item.ariaCurrent === "true")
 

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_toggle_all_checkbox.rb

@@ -13,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_controller.js

@@ -1,5 +1,12 @@
 import { Controller } from "@hotwired/stimulus";
 
+// Strips combining diacritical marks after an NFD decomposition, so "é"
+// (query or candidate) matches "e" — the scorer otherwise treats accented
+// characters as never equal to their bare ASCII counterparts.
+function normalizeDiacritics(s) {
+  return s.normalize("NFD").replace(/[̀-ͯ]/g, "");
+}
+
 // Fuzzy subsequence score: every query character must appear in order in the
 // value (else null = no match). Consecutive runs compound, word-starts score
 // extra, and a verbatim substring outranks scattered hits — so "set" beats
@@ -7,6 +14,8 @@ import { Controller } from "@hotwired/stimulus";
 // what fuse.js gave ruby_ui.
 function fuzzyScore(query, value) {
   if (!query) return 0;
+  query = normalizeDiacritics(query);
+  value = normalizeDiacritics(value);
   let qi = 0;
   let score = 0;
   let streak = 0;
@@ -50,10 +59,17 @@ export default class extends Controller {
     // dismiss() can hand focus back instead of dropping it on <body>.
     this.previouslyFocused = document.activeElement;
 
+    // A Turbo snapshot serializes stale aria-selected on rows / aria-
+    // activedescendant on the input even though the live JS highlight state
+    // doesn't survive restore — normalize here so a restored page doesn't
+    // announce a stale highlight (mirrors select_controller.js's connect()).
+    this.itemTargets.forEach((item) => item.removeAttribute("aria-selected"));
+
     if (!this.hasInputTarget) {
       return;
     }
 
+    this.inputTarget.removeAttribute("aria-activedescendant");
     this.generateItemIds();
     // Only the cloned dialog overlay grabs focus on connect — an inline
     // palette connecting at page load must not steal it.
@@ -98,6 +114,9 @@ export default class extends Controller {
     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() {
@@ -171,7 +190,7 @@ export default class extends Controller {
   }
 
   focusInput() {
-    this.inputTarget?.focus();
+    if (this.hasInputTarget) this.inputTarget.focus();
   }
 
   filter(e) {
@@ -266,7 +285,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_input.rb

@@ -11,10 +11,11 @@ module PhlexKit
     # `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)
+    def initialize(placeholder: "Type a command or search...", list_id: nil, autofocus: false, value: "", **attrs)
       @placeholder = placeholder
       @list_id = list_id
       @autofocus = autofocus
+      @value = value
       @attrs = attrs
     end
 
@@ -31,7 +32,7 @@ module PhlexKit
             spellcheck: "false",
             autofocus: @autofocus,
             role: "combobox",
-            value: "",
+            value: @value,
             aria: { autocomplete: "list", expanded: "true", controls: @list_id },
             data: {
               phlex_kit__command_target: "input",

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.css

@@ -72,6 +72,9 @@
    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-inline-start: auto; width: 1rem; height: 1rem; }
+/* Mirror the chevron in RTL (submenu opens visually LEFT). Ancestor
+   [dir="rtl"] (not :dir()) so Chrome re-styles it on a dynamic dir flip too. */
+[dir="rtl"] .pk-context-menu-sub-chevron { transform: scaleX(-1); }
 .pk-context-menu-sub-content {
   position: fixed;
   position-anchor: --pk-context-menu-sub;

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

@@ -5,7 +5,15 @@ module PhlexKit
   class ContextMenu < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-context-menu", data: { controller: "phlex-kit--context-menu" } }, @attrs), &)
+      div(**mix({
+        class: "pk-context-menu",
+        data: {
+          controller: "phlex-kit--context-menu",
+          # focusout: tabbing (or otherwise moving real focus) out of the
+          # menu closes the open [popover=manual] panel (menubar's pattern).
+          action: "focusout->phlex-kit--context-menu#onFocusout"
+        }
+      }, @attrs), &)
     end
   end
 end

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

@@ -23,12 +23,60 @@ 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()
+    // A Turbo snapshot (or a detach/reattach that mimics one) serializes
+    // aria-expanded="true" on sub triggers even though no submenu can be
+    // open at connect time — sweep every stale marker back to false
+    // (menubar's pattern).
+    this.element.querySelectorAll("[aria-expanded='true']").forEach((el) => el.setAttribute("aria-expanded", "false"))
+    // Same shape for checkbox/radio rows: their `checked` DOM property
+    // survives a reconnect but a hand-edited/replayed aria-checked can drift
+    // from it — resync every row from its live input.
+    this.element.querySelectorAll('input[type="checkbox"], input[type="radio"]').forEach((i) => {
+      i.closest('[role^="menuitem"]')?.setAttribute("aria-checked", i.checked)
+    })
   }
 
   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)
+  }
+
+  // Tabbing (or otherwise moving real focus) out of the menu closes it —
+  // menubar's onFocusout pattern (menubar_controller.js). relatedTarget is
+  // null when the window itself blurs — leave the menu alone then. The
+  // trigger + content are both DOM children of this.element even though the
+  // content is a top-layer popover, so one containment check covers both.
+  onFocusout(e) {
+    if (!this.contentTarget.matches(":popover-open")) return
+    const to = e.relatedTarget
+    if (!to || this.element.contains(to)) return
+    this.close()
   }
 
   open(e) {
@@ -68,6 +116,13 @@ export default class extends Controller {
   }
 
   keydown(e) {
+    // This listener stays attached document-wide while the menu is open (see
+    // open()/close()) so it keeps receiving events even once real focus has
+    // left the menu — scope the roving-nav keys to when focus is actually
+    // within the widget (this.element, not just contentTarget, so a focused
+    // trigger still counts). Escape stays global while the menu is open (APG).
+    if (e.key !== "Escape" && !this.element.contains(document.activeElement)) return
+
     const items = this.items()
     const index = items.indexOf(document.activeElement)
     switch (e.key) {
@@ -101,19 +156,26 @@ export default class extends Controller {
         }
         break
       case "ArrowRight":
-        // On a sub trigger, enter the submenu (focus reveals it via
-        // :focus-within, making its rows visible to the roving nav).
-        if (document.activeElement?.matches(".pk-context-menu-sub-trigger")) {
-          e.preventDefault()
-          this.enterSub(document.activeElement)
-        }
-        break
       case "ArrowLeft": {
-        // Inside a submenu, step back to its trigger (closes it on focus-out).
-        const sub = document.activeElement?.closest(".pk-context-menu-sub-content")
-        if (sub) {
-          e.preventDefault()
-          sub.closest(".pk-context-menu-sub")?.querySelector(".pk-context-menu-sub-trigger")?.focus()
+        // Submenus open inline-end — visually LEFT in RTL — so the enter key
+        // follows visual direction: ArrowLeft enters / ArrowRight exits in RTL
+        // (and the reverse in LTR). Runtime dir check is reliable after a flip.
+        const rtl = getComputedStyle(this.element).direction === "rtl"
+        const enterKey = rtl ? "ArrowLeft" : "ArrowRight"
+        if (e.key === enterKey) {
+          // On a sub trigger, enter the submenu (focus reveals it via
+          // :focus-within, making its rows visible to the roving nav).
+          if (document.activeElement?.matches(".pk-context-menu-sub-trigger")) {
+            e.preventDefault()
+            this.enterSub(document.activeElement)
+          }
+        } else {
+          // Inside a submenu, step back to its trigger (closes it on focus-out).
+          const sub = document.activeElement?.closest(".pk-context-menu-sub-content")
+          if (sub) {
+            e.preventDefault()
+            sub.closest(".pk-context-menu-sub")?.querySelector(".pk-context-menu-sub-trigger")?.focus()
+          }
         }
         break
       }