phlex_kit 0.10.0 → 0.12.0

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

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

@@ -9,7 +9,9 @@ module PhlexKit
         # -1: roving focus reaches it via arrows (focus-within opens the sub);
         # tabindex 0 made it a stray tab stop inside the menu.
         tabindex: "-1",
-        aria: { haspopup: "menu" },
+        # expanded starts false and is mirrored live by the controller's
+        # syncSub (the reveal itself is pure CSS :hover/:focus-within).
+        aria: { haspopup: "menu", expanded: "false" },
         data: { phlex_kit__context_menu_target: "menuItem" }
       }, @attrs)) do
         block&.call

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

@@ -23,16 +23,6 @@
 /* "Columns" dropdown rows. */
 .pk-data-table-column-toggle { position: relative; }
 .pk-data-table-column-toggle-icon { width: 1rem; height: 1rem; margin-inline-start: .25rem; }
-.pk-data-table-column-option {
-  display: flex;
-  align-items: center;
-  gap: .5rem;
-  border-radius: calc(var(--pk-radius) - 4px);
-  padding: .375rem .5rem;
-  font-size: .875rem;
-  cursor: pointer;
-}
-.pk-data-table-column-option:hover { background: var(--pk-accent); }
 
 /* Sortable header link. */
 .pk-data-table-sort-head { color: var(--pk-text); white-space: nowrap; }
@@ -102,7 +92,7 @@
 .pk-data-table-page-disabled {
   display: inline-flex;
   align-items: center;
-  height: 2.25rem;
+  height: 2rem;
   padding: 0 .75rem;
   font-size: .875rem;
   opacity: .5;

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

@@ -27,7 +27,10 @@ module PhlexKit
               # 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,
+                # visible: false starts the menu row unchecked for a column
+                # the host server-renders hidden (pk-hidden on its cells) —
+                # checked: true hardcoded meant the two could never agree.
+                checked: col.fetch(:visible, true),
                 data: {
                   column_key: col[:key].to_s,
                   action: "change->phlex-kit--data-table-column-visibility#toggle"

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

@@ -20,7 +20,11 @@ export default class extends Controller {
   toggleAll(event) {
     const checked = event.target.checked;
     this.rowCheckboxTargets.forEach((cb) => {
+      if (cb.checked === checked) return;
       cb.checked = checked;
+      // Programmatic .checked flips fire no event — hosts (and the
+      // form-field wiring on PhlexKit::Checkbox) must still hear select-all.
+      cb.dispatchEvent(new Event("change", { bubbles: true }));
     });
     this.updateState();
   }

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

@@ -70,7 +70,10 @@ module PhlexKit
     def edge_item(disabled:, href:, label:, name:)
       if disabled
         li do
-          span(class: "pk-data-table-page-disabled", aria: { disabled: "true", label: name }) { label }
+          # role-less span + aria-label is invalid ARIA (aria-label on a
+          # role-less element is not perceivable) — role + aria-disabled
+          # mirrors BreadcrumbPage's disabled-control pattern.
+          span(class: "pk-data-table-page-disabled", role: "link", aria: { disabled: "true", label: name }) { label }
         end
       else
         render PaginationItem.new(href: href, aria: { label: name }) { label }

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

@@ -4,21 +4,26 @@ module PhlexKit
   # (search/sort/direction/...) survive via `preserved_params:` hidden inputs,
   # mirroring DataTableSearch. See data_table.rb.
   class DataTablePerPageSelect < BaseComponent
-    def initialize(path:, name: "per_page", value: nil, frame_id: nil, options: [ 5, 10, 25, 50 ], preserved_params: {}, **attrs)
+    # method:/action: are kit-owned (a GET form targeting `path:`) — named
+    # kwargs so a caller override lands in @method/@action directly instead
+    # of fusing with the generated defaults via `mix` ("get post").
+    def initialize(path:, name: "per_page", value: nil, frame_id: nil, options: [ 5, 10, 25, 50 ], preserved_params: {}, method: "get", action: nil, **attrs)
       @path = path
       @name = name
       @value = value
       @frame_id = frame_id
       @options = options
       @preserved_params = preserved_params
+      @method = method
+      @action = action || @path
       @attrs = attrs
     end
 
     def view_template
       form_attrs = {
         class: "pk-data-table-per-page",
-        action: @path,
-        method: "get",
+        action: @action,
+        method: @method,
         # Reuse the search controller for its CSP-safe #submitNow action.
         data: { controller: "phlex-kit--data-table-search" }
       }

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

@@ -3,7 +3,10 @@ module PhlexKit
   # params survive via `preserved_params:` hidden inputs; focus/caret survive the
   # frame swap (see the search controller). See data_table.rb.
   class DataTableSearch < BaseComponent
-    def initialize(path:, name: "search", value: nil, frame_id: nil, placeholder: "Search...", debounce: 300, preserved_params: {}, **attrs)
+    # method:/action: are kit-owned (a GET form targeting `path:`) — named
+    # kwargs so a caller override lands in @method/@action directly instead
+    # of fusing with the generated defaults via `mix` ("get post").
+    def initialize(path:, name: "search", value: nil, frame_id: nil, placeholder: "Search...", debounce: 300, preserved_params: {}, method: "get", action: nil, **attrs)
       @path = path
       @name = name
       @value = value
@@ -11,11 +14,13 @@ module PhlexKit
       @placeholder = placeholder
       @debounce = debounce
       @preserved_params = preserved_params
+      @method = method
+      @action = action || @path
       @attrs = attrs
     end
 
     def view_template
-      form(**mix({ class: "pk-data-table-search", method: "get", action: @path, data: form_data }, @attrs)) do
+      form(**mix({ class: "pk-data-table-search", method: @method, action: @action, data: form_data }, @attrs)) do
         render Input.new(
           type: :search,
           name: @name,

data/app/components/phlex_kit/date_picker/date_picker.rb

@@ -5,7 +5,12 @@ module PhlexKit
   # controller and the calendar's outlet points at its id, so picking a day
   # writes the formatted date into the field. Upstream's popover_options
   # (hover trigger via @floating-ui) are gone — the kit popover is click-only,
-  # CSS-positioned. Tailwind → vanilla `.pk-date-picker*` (date_picker.css).
+  # CSS-positioned. The phlex-kit--date-picker controller on the root div
+  # listens for the calendar's change event and closes the popover once a
+  # selection is COMPLETE (single: any pick; range: the second end only;
+  # multiple: never), returning focus to the input — see
+  # date_picker_controller.js and popover_controller.js#close.
+  # Tailwind → vanilla `.pk-date-picker*` (date_picker.css).
   class DatePicker < BaseComponent
     def initialize(
       id: nil,
@@ -31,6 +36,12 @@ module PhlexKit
       # until the first interaction.
       @value = value || format_selected_date
       @placeholder = placeholder
+      # An id smuggled through input_attrs would MERGE with the generated one
+      # (mix fuses duplicate string attrs), breaking label[for] and the
+      # calendar outlet selector — the top-level id: kwarg is the one path.
+      if input_attrs.key?(:id) || input_attrs.key?("id")
+        raise ArgumentError, "DatePicker: pass id: as the top-level kwarg, not input_attrs[:id]"
+      end
       @input_attrs = input_attrs
       @calendar_attrs = calendar_attrs
       @trigger_attrs = trigger_attrs
@@ -39,7 +50,13 @@ module PhlexKit
     end
 
     def view_template
-      div(**mix({ class: "pk-date-picker" }, @attrs)) do
+      div(**mix({
+        class: "pk-date-picker",
+        data: {
+          controller: "phlex-kit--date-picker",
+          action: "phlex-kit--calendar:change->phlex-kit--date-picker#onCalendarChange"
+        }
+      }, @attrs)) do
         render Popover.new do
           render PopoverTrigger.new(**trigger_attrs) do
             div(class: "pk-date-picker-field") do

data/app/components/phlex_kit/date_picker/date_picker_controller.js

@@ -0,0 +1,28 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Bridges the nested Calendar's change event to the wrapping Popover's
+// close(), so picking a date collapses the panel instead of leaving the
+// user to click outside/Escape after every pick (shadcn's DatePicker
+// behavior). Only closes on a COMPLETE selection: single mode closes on
+// any pick, range mode only once the second end (rangeEnd) is set — closing
+// on the first end would strand the user before they can pick the second —
+// and multiple mode never auto-closes since picking more than one date is
+// the entire point. See date_picker.rb for the data-action wiring and
+// popover_controller.js for close()/focusTrigger().
+export default class extends Controller {
+  onCalendarChange(e) {
+    const { mode, rangeEnd } = e.detail
+    if (mode === "multiple") return
+    // calendar_controller.js clears rangeEnd via `this.rangeEndValue = null`,
+    // which goes through Element#setAttribute — the DOM stringifies a null
+    // argument to the literal "null", so a genuinely-unset rangeEnd reads
+    // back as that string, not JS null/undefined/"".
+    if (mode === "range" && (!rangeEnd || rangeEnd === "null")) return
+    this.popoverController()?.close()
+  }
+
+  popoverController() {
+    const popoverEl = this.element.querySelector(".pk-popover")
+    return popoverEl && this.application.getControllerForElementAndIdentifier(popoverEl, "phlex-kit--popover")
+  }
+}

data/app/components/phlex_kit/dialog/dialog.css

@@ -11,7 +11,9 @@
   --pk-dialog-spacing: 1rem;
   position: fixed; z-index: 50; width: 100%;
   max-width: min(24rem, calc(100% - 2rem));
-  max-height: 100vh;
+  /* Breathing room like the horizontal inset — 100vh touched the screen
+     edges and overflowed behind mobile browser chrome (dvh tracks it). */
+  max-height: calc(100dvh - 2rem);
   overflow-y: auto; gap: 1rem;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: calc(var(--pk-radius) + 2px); background: var(--pk-surface); color: var(--pk-text);

data/app/components/phlex_kit/dialog/dialog_content.rb

@@ -21,7 +21,7 @@ module PhlexKit
       aria = {}
       aria[:labelledby] = @labelledby if @labelledby
       aria[:describedby] = @describedby if @describedby
-      dialog(**mix({ class: cls, aria: aria, data: { phlex_kit__dialog_target: "dialog", action: "click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
+      dialog(**mix({ class: cls, aria: aria, data: { phlex_kit__dialog_target: "dialog", action: "pointerdown->phlex-kit--dialog#backdropPointerdown click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
         yield
         if @show_close_button
           button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--dialog#dismiss" }) do

data/app/components/phlex_kit/dialog/dialog_controller.js

@@ -37,6 +37,9 @@ export default class extends Controller {
   }
   open(e) {
     e?.preventDefault()
+    // open: is one-shot — the reflected value sits in the Turbo snapshot, so
+    // a cache-restored reconnect would re-open a dismissed dialog.
+    this.openValue = false
     this.dialogTarget.showModal()
     // Save/restore rather than removeProperty: a host page (or another
     // component) may have set body overflow itself.
@@ -44,15 +47,26 @@ export default class extends Controller {
     document.body.style.overflow = "hidden"
   }
   dismiss() { this.dialogTarget.close() }
+  // Only a press that STARTED on the backdrop may dismiss: a drag-select
+  // beginning inside the panel and released over the backdrop fires the
+  // click on <dialog> with outside coordinates — that must not close it
+  // (Radix guards on pointerdown origin the same way).
+  backdropPointerdown(e) {
+    this.pressStartedOutside = e.target === this.dialogTarget && !this.#insideBox(e)
+  }
   // Only a click on the ::backdrop dismisses. e.target is the <dialog> for
   // backdrop clicks, but ALSO for clicks on the dialog's own padding/flex
   // gaps — disambiguate by testing the click point against the dialog's box.
   backdropClick(e) {
     if (e.target !== this.dialogTarget) return
     if (e.detail === 0) return // synthetic/keyboard click — no coordinates
+    if (!this.pressStartedOutside) return
+    this.pressStartedOutside = false
+    if (!this.#insideBox(e)) this.dismiss()
+  }
+  #insideBox(e) {
     const r = this.dialogTarget.getBoundingClientRect()
-    const inside = e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom
-    if (!inside) this.dismiss()
+    return e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom
   }
   handleClose = () => { document.body.style.overflow = this.previousOverflow ?? "" }
 }

data/app/components/phlex_kit/drawer/drawer.rb

@@ -12,7 +12,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      div(**mix({ data: { controller: "phlex-kit--sheet", phlex_kit__sheet_open_value: @open } }, @attrs), &)
+      div(**mix({ data: { controller: "phlex-kit--sheet", phlex_kit__sheet_open_value: @open.to_s } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/drawer/drawer_content.rb

@@ -12,9 +12,16 @@ module PhlexKit
 
     def view_template(&block)
       template(data: { phlex_kit__sheet_target: "content" }) do
-        div(data: { controller: "phlex-kit--sheet-content", action: "keydown->phlex-kit--sheet-content#keydown" }) do
-          div(class: "pk-drawer-overlay", data: { action: "click->phlex-kit--sheet-content#close" })
-          div(**mix({ class: "pk-drawer #{fetch_option(SIDES, @side, :side)}", role: "dialog", aria: { modal: "true" }, tabindex: "-1", data: { phlex_kit__sheet_content_target: "panel" } }, @attrs)) do
+        div(data: { controller: "phlex-kit--sheet-content", action: "keydown->phlex-kit--sheet-content#keydown", pk_overlay_clone: "" }) do
+          div(class: "pk-drawer-overlay", data: { action: "click->phlex-kit--sheet-content#close mousedown->phlex-kit--sheet-content#overlayMousedown" })
+          panel_attrs = { class: "pk-drawer #{fetch_option(SIDES, @side, :side)}", data: { phlex_kit__sheet_content_target: "panel" } }
+          # Defaults only when the caller didn't supply their own — `mix`
+          # would fuse role="dialog region" / aria-modal="true false" /
+          # tabindex="-1 0" instead of overriding.
+          panel_attrs[:role] = "dialog" unless @attrs.key?(:role) || @attrs.key?("role")
+          panel_attrs[:aria] = { modal: "true" } unless aria_key_set?(:modal)
+          panel_attrs[:tabindex] = "-1" unless @attrs.key?(:tabindex) || @attrs.key?("tabindex")
+          div(**mix(panel_attrs, @attrs)) do
             div(class: "pk-drawer-handle", aria: { hidden: "true" })
             yield if block
           end

data/app/components/phlex_kit/dropdown_menu/dropdown_menu.css

@@ -20,14 +20,17 @@
   position-try-fallbacks: flip-block;
 }
 .pk-dropdown-menu-content-up { position-area: block-start span-inline-end; margin: 0 0 4px; }
+/* Gap margins are logical to match the logical position-area — physical
+   margins landed on the wrong side in RTL (and flip-inline flips logical
+   margins along with the placement). */
 .pk-dropdown-menu-content-right {
   position-area: inline-end span-block-end;
-  margin: 0 0 0 4px;
+  margin: 0; margin-inline-start: 4px;
   position-try-fallbacks: flip-inline;
 }
 .pk-dropdown-menu-content-left {
   position-area: inline-start span-block-end;
-  margin: 0 4px 0 0;
+  margin: 0; margin-inline-end: 4px;
   position-try-fallbacks: flip-inline;
 }
 .pk-dropdown-menu-viewport {
@@ -113,6 +116,10 @@
    the viewport right edge. */
 .pk-dropdown-menu-sub { anchor-name: --pk-dropdown-menu-sub; anchor-scope: --pk-dropdown-menu-sub; }
 .pk-dropdown-menu-sub-chevron { margin-inline-start: auto; width: 1rem; height: 1rem; }
+/* The chevron points toward where the submenu opens (inline-end). In RTL that
+   is visually LEFT — mirror it. Ancestor [dir="rtl"] (not :dir()) so Chrome
+   re-styles it on a dynamic dir flip too. */
+[dir="rtl"] .pk-dropdown-menu-sub-chevron { transform: scaleX(-1); }
 .pk-dropdown-menu-sub-content {
   position: fixed;
   position-anchor: --pk-dropdown-menu-sub;

data/app/components/phlex_kit/dropdown_menu/dropdown_menu.rb

@@ -18,7 +18,9 @@ module PhlexKit
         data: {
           controller: "phlex-kit--dropdown-menu",
           phlex_kit__dropdown_menu_open_value: @open,
-          action: "click@window->phlex-kit--dropdown-menu#onClickOutside"
+          # focusout: tabbing (or otherwise moving real focus) out of the
+          # menu closes the open [popover=manual] panel (menubar's pattern).
+          action: "click@window->phlex-kit--dropdown-menu#onClickOutside focusout->phlex-kit--dropdown-menu#onFocusout"
         }
       }, @attrs), &block)
     end

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_controller.js

@@ -16,20 +16,59 @@ export default class extends Controller {
 
   connect() {
     this.boundHandleKeydown = this.#handleKeydown.bind(this);
+    // Outstanding syncSub rAF handles — cancelled on disconnect so a queued
+    // frame never touches a torn-down menu (menubar's pattern).
+    this.subFrames = new Set();
     // The visible control is the caller's button/link inside the trigger
     // wrapper — that's what AT reads, so the popup wiring belongs on it.
     this.invoker = this.triggerTarget.querySelector("button, a, [tabindex]") || this.triggerTarget;
+    // 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). Runs before the invoker's own reset below so
+    // both are covered by one mental model.
+    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);
+    });
     this.invoker.setAttribute("aria-haspopup", "menu");
     this.invoker.setAttribute("aria-expanded", "false");
+    // Associate trigger and menu for AT (the dialog controller wires its
+    // ids the same way).
+    if (!this.contentTarget.id) this.contentTarget.id = `pk-dropdown-menu-${Math.random().toString(36).slice(2, 8)}`;
+    this.invoker.setAttribute("aria-controls", this.contentTarget.id);
+    // Turbo snapshots BEFORE disconnect — an open menu (reflected in the
+    // open value) would be resurrected from the page cache on restore.
+    this.boundBeforeCache = () => this.close();
+    document.addEventListener("turbo:before-cache", this.boundBeforeCache);
     // `open:` on the Ruby side renders the value — start open (same
     // kwarg -> value -> connect flow as Collapsible).
     if (this.openValue) this.#open();
   }
 
   disconnect() {
+    document.removeEventListener("turbo:before-cache", this.boundBeforeCache);
+    this.subFrames.forEach((id) => cancelAnimationFrame(id));
+    this.subFrames.clear();
     this.#removeEventListeners();
   }
 
+  // Mirrors the CSS-driven submenu state (:hover / :focus-within) onto the
+  // sub trigger's aria-expanded. rAF: on mouseleave/focusout the pseudo-class
+  // state isn't settled until the event finishes dispatching.
+  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);
+  }
+
   onClickOutside(event) {
     // Gate on the live :popover-open state, not the stored flag — a stale
     // flag is how a close on an already-closed panel becomes an open.
@@ -47,6 +86,18 @@ export default class extends Controller {
     this.contentTarget.matches(":popover-open") ? this.close() : this.#open();
   }
 
+  // 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() {
     this.openValue = true;
     this.#addEventListeners();
@@ -75,6 +126,16 @@ export default class extends Controller {
   }
 
   #handleKeydown(e) {
+    // This listener is document-level (see #addEventListeners) so it keeps
+    // receiving events even once real focus has left the menu (e.g. a click
+    // into an unrelated text field the onFocusout listener didn't catch) —
+    // scope the roving-nav keys to when focus is actually within the widget.
+    // this.element (not just contentTarget) so ArrowDown still works right
+    // after a mouse-driven open, when focus is still on the invoker button
+    // (#open() doesn't force focus into the first row). Escape stays global
+    // while the menu is open (APG).
+    if (e.key !== "Escape" && !this.element.contains(document.activeElement)) return;
+
     const items = this.#items();
     if (items.length === 0) return;
     const index = items.indexOf(document.activeElement);
@@ -111,20 +172,27 @@ export default class extends Controller {
         this.invoker.focus();
         break;
       case "ArrowRight":
-        // On a sub trigger, enter the submenu (focus reveals it via
-        // :focus-within, making its rows visible to the roving nav).
-        // Same keyboard grammar as context_menu.
-        if (document.activeElement?.matches(".pk-dropdown-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-dropdown-menu-sub-content");
-        if (sub) {
-          e.preventDefault();
-          sub.closest(".pk-dropdown-menu-sub")?.querySelector(".pk-dropdown-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). Same keyboard grammar as context_menu.
+        // Runtime dir check is reliable after a dynamic 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-dropdown-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-dropdown-menu-sub-content");
+          if (sub) {
+            e.preventDefault();
+            sub.closest(".pk-dropdown-menu-sub")?.querySelector(".pk-dropdown-menu-sub-trigger")?.focus();
+          }
         }
         break;
       }

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_sub.rb

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

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_sub_trigger.rb

@@ -10,7 +10,9 @@ module PhlexKit
         # -1: roving focus reaches it via arrows (focus-within opens the sub);
         # tabindex 0 made it a stray tab stop inside the menu.
         tabindex: "-1",
-        aria: { haspopup: "menu" },
+        # expanded starts false and is mirrored live by the controller's
+        # syncSub (the reveal itself is pure CSS :hover/:focus-within).
+        aria: { haspopup: "menu", expanded: "false" },
         data: { phlex_kit__dropdown_menu_target: "menuItem" }
       }, @attrs)) do
         block&.call

data/app/components/phlex_kit/field/field_separator.rb

@@ -6,7 +6,7 @@ module PhlexKit
     def initialize(**attrs) = (@attrs = attrs)
 
     def view_template(&block)
-      div(**mix({ class: "pk-field-separator", data: { content: block ? "true" : "false" } }, @attrs)) do
+      div(**mix({ class: "pk-field-separator" }, @attrs)) do
         render Separator.new(class: "pk-field-separator-line")
         span(class: "pk-field-separator-content", &block) if block
       end

data/app/components/phlex_kit/form_field/form_field_controller.js

@@ -9,10 +9,21 @@ import { Controller } from "@hotwired/stimulus";
 // back to the browser's validationMessage.
 // Connects to data-controller="phlex-kit--form-field"
 export default class extends Controller {
-  static targets = ["input", "error"];
+  static targets = ["input", "error", "hint"];
   static values = { shouldValidate: false };
 
   connect() {
+    // Hints are static description text — wire them onto every control's
+    // aria-describedby up front (errors join/leave dynamically via
+    // #describeBy, which preserves foreign tokens like these).
+    this.hintTargets.forEach((hint) => {
+      if (!hint.id) return;
+      this.inputTargets.forEach((input) => {
+        const tokens = (input.getAttribute("aria-describedby") || "").split(/\s+/).filter(Boolean);
+        if (!tokens.includes(hint.id)) tokens.push(hint.id);
+        input.setAttribute("aria-describedby", tokens.join(" "));
+      });
+    });
     if (this.hasErrorTarget) {
       if (this.errorTarget.textContent.trim()) {
         this.shouldValidateValue = true;
@@ -37,43 +48,61 @@ export default class extends Controller {
     if (!this.hasErrorTarget) return;
     error.preventDefault();
 
-    this.shouldValidateValue = true;
-    this.#setErrorMessage(error);
-  }
+    // preventDefault also cancels the browser's focus-first-invalid — restore
+    // it for the first invalid control of the submit pass (all invalid events
+    // fire in the same task, so the microtask reset scopes "first" correctly).
+    if (!this._focusedInvalid) {
+      this._focusedInvalid = true;
+      queueMicrotask(() => { this._focusedInvalid = false; });
+      error.target.focus({ preventScroll: true });
+      error.target.scrollIntoView({ block: "nearest" });
+    }
 
-  onInput(event) {
-    this.#setErrorMessage(event);
+    this.shouldValidateValue = true;
+    this.#setErrorMessage();
   }
 
-  onChange(event) {
-    this.#setErrorMessage(event);
+  onInput(_event) {
+    this.#setErrorMessage();
   }
 
-  // The event's own control, when it's one of ours — radio/checkbox groups
-  // register several input targets and validity/aria-invalid must land on
-  // the control that fired, not always the first.
-  #inputFor(event) {
-    if (event && this.inputTargets.includes(event.target)) return event.target;
-    return this.inputTarget;
+  onChange(_event) {
+    this.#setErrorMessage();
   }
 
-  #setErrorMessage(event) {
+  // A FormField can carry several input targets (radio/checkbox groups, or
+  // independent controls like two required checkboxes sharing one error).
+  // Recompute across ALL of them on every validity event — deciding from the
+  // event's own target alone left a shared error stuck on/off based on
+  // whichever control happened to fire last, out of step with the others'
+  // own (correctly-updated) aria-invalid.
+  #setErrorMessage() {
     if (!this.shouldValidateValue || !this.hasErrorTarget) return;
 
-    const input = this.#inputFor(event);
     // aria-invalid drives the red ring for LIVE validation too (input.css
-    // only matched server-rendered attrs); aria-describedby ties the message
-    // to the control for AT.
-    if (input.validity.valid) {
-      input.removeAttribute("aria-invalid");
+    // only matched server-rendered attrs); each control reflects its own
+    // validity regardless of which one fired the event. Radio buttons
+    // sharing a `name` share native validity, so they naturally agree here.
+    let firstInvalid = null;
+    this.inputTargets.forEach((input) => {
+      if (input.validity.valid) {
+        input.removeAttribute("aria-invalid");
+      } else {
+        input.setAttribute("aria-invalid", "true");
+        firstInvalid ||= input;
+      }
+      // Clear the shared error's id everywhere first — it's re-added below,
+      // only on the one control whose message is currently shown.
       this.#describeBy(input, false);
+    });
+
+    if (firstInvalid) {
+      this.#describeBy(firstInvalid, true);
+      this.errorTarget.textContent = this.#getValidationMessage(firstInvalid);
+      this.errorTarget.classList.remove("pk-hidden");
+    } else {
       this.errorTarget.textContent = "";
       this.errorTarget.classList.add("pk-hidden");
-    } else {
-      input.setAttribute("aria-invalid", "true");
-      this.#describeBy(input, true);
-      this.errorTarget.textContent = this.#getValidationMessage(input);
-      this.errorTarget.classList.remove("pk-hidden");
     }
   }