phlex_kit 0.13.0 → 0.14.1

data/app/components/phlex_kit/menubar/menubar_sub_trigger.rb

@@ -3,17 +3,18 @@ module PhlexKit
   class MenubarSubTrigger < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&block)
-      div(**mix({
-        class: "pk-menubar-item pk-menubar-sub-trigger",
-        role: "menuitem",
-        # -1: the roving focus reaches it via arrows (focus-within opens the
-        # sub); tabindex 0 made it a stray tab stop inside the open panel.
-        tabindex: "-1",
-        # expanded starts false; the sub is revealed by CSS (:hover /
-        # :focus-within), so MenubarSub's syncSub actions mirror that state
-        # onto this attribute.
-        aria: { haspopup: "menu", expanded: "false" }
-      }, @attrs)) do
+      base = { class: "pk-menubar-item pk-menubar-sub-trigger" }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:role] = "menuitem" unless attr_set?(:role)
+      # -1: the roving focus reaches it via arrows (focus-within opens the
+      # sub); tabindex 0 made it a stray tab stop inside the open panel.
+      base[:tabindex] = "-1" unless attr_set?(:tabindex)
+      base[:"aria-haspopup"] = "menu" unless aria_key_set?(:haspopup)
+      # expanded starts false; the sub is revealed by CSS (:hover /
+      # :focus-within), so MenubarSub's syncSub actions mirror that state
+      # onto this attribute.
+      base[:"aria-expanded"] = "false" unless aria_key_set?(:expanded)
+      div(**mix(base, @attrs)) do
         block&.call
         render Icon.new(:chevron_right, size: nil, class: "pk-menubar-sub-chevron")
       end

data/app/components/phlex_kit/menubar/menubar_trigger.rb

@@ -3,13 +3,16 @@ module PhlexKit
   class MenubarTrigger < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      button(**mix({
+      base = {
         type: :button,
         class: "pk-menubar-trigger",
-        role: "menuitem",
-        aria: { haspopup: "menu", expanded: "false" },
         data: { action: "click->phlex-kit--menubar#toggle mouseenter->phlex-kit--menubar#switch" }
-      }, @attrs), &)
+      }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:role] = "menuitem" unless attr_set?(:role)
+      base[:"aria-haspopup"] = "menu" unless aria_key_set?(:haspopup)
+      base[:"aria-expanded"] = "false" unless aria_key_set?(:expanded)
+      button(**mix(base, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/message_scroller/message_scroller_controller.js

@@ -30,6 +30,11 @@ export default class extends Controller {
   };
 
   connect() {
+    // connect() re-derives reflected state: a Turbo snapshot serializes a
+    // mid-flight data-autoscrolling marker; no programmatic scroll is in
+    // flight on a fresh connect.
+    this.element.removeAttribute("data-autoscrolling");
+    if (this.hasViewportTarget) this.viewportTarget.removeAttribute("data-autoscrolling");
     // Reader is considered "following" the live edge until they move away.
     this.following = true;
     // True only while a programmatic scroll is in flight, so reader-intent

data/app/components/phlex_kit/pagination/pagination.css

@@ -10,3 +10,7 @@
 .pk-button.pk-pagination-next { padding-inline-end: .375rem; }
 .pk-pagination-label { display: none; }
 @media (min-width: 640px) { .pk-pagination-label { display: block; } }
+
+/* RTL: Previous/Next chevrons follow the reading direction. */
+[dir="rtl"] .pk-pagination-previous svg,
+[dir="rtl"] .pk-pagination-next svg { transform: scaleX(-1); }

data/app/components/phlex_kit/popover/popover_content.rb

@@ -13,7 +13,14 @@ module PhlexKit
 
     def view_template(&)
       classes = [ "pk-popover-content", fetch_option(ALIGNS, @align, :align) ].compact.join(" ")
-      div(**mix({ class: classes, popover: "auto", data: { phlex_kit__popover_target: "content", state: "closed" } }, @attrs), &)
+      # `popover:` is a named default, not a merged attr: `mix` joins duplicate
+      # attrs (a caller's `popover: "manual"` would fuse into "auto manual",
+      # which the browser normalizes to manual — killing the native light
+      # dismiss/Escape this controller relies on). Skip the default when the
+      # caller sets it (mirrors MenubarContent).
+      base = { class: classes, data: { phlex_kit__popover_target: "content", state: "closed" } }
+      base[:popover] = "auto" unless attr_set?(:popover)
+      div(**mix(base, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/popover/popover_controller.js

@@ -16,6 +16,10 @@ export default class extends Controller {
     const invoker = this.triggerTarget.querySelector("button")
     if (invoker) {
       invoker.popoverTargetElement = this.contentTarget
+      // popoverTargetElement gives native aria-expanded but not haspopup —
+      // shadcn/Radix Popover.Trigger ships aria-haspopup="dialog", so add it
+      // (leave a caller-set value alone) to match the button-less path below.
+      if (!invoker.hasAttribute("aria-haspopup")) invoker.setAttribute("aria-haspopup", "dialog")
     } else {
       // Button-less fallback: keyboard toggling and popup semantics don't
       // come for free like they do with popoverTargetElement — wire Enter

data/app/components/phlex_kit/radio_button/radio_button.css

@@ -38,6 +38,22 @@
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 40%, transparent);
 }
 .pk-radio[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 (and the theme-scoped invalid arms below beat it outright in light).
+   Keep the red border (invalid stays legible) but switch the ring to the
+   standard focus color — mirrors checkbox.css. */
+.pk-radio[aria-invalid="true"]:focus-visible,
+:root[data-theme="light"] .pk-radio[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-radio[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-radio:disabled { cursor: not-allowed; opacity: .5; }
 :root[data-theme="light"] .pk-radio:not(:checked) { background: transparent; }
 :root[data-theme="light"] .pk-radio[aria-invalid="true"] {

data/app/components/phlex_kit/radio_button/radio_button.rb

@@ -7,7 +7,7 @@ module PhlexKit
 
     def view_template
       input(**mix({
-        type: "radio",
+        type: :radio,
         class: "pk-radio",
         data: {
           phlex_kit__form_field_target: "input",

data/app/components/phlex_kit/resizable/resizable_controller.js

@@ -57,6 +57,9 @@ export default class extends Controller {
     try { handle.setPointerCapture(e.pointerId) } catch {}
 
     const onMove = (ev) => {
+      // Only the initiating pointer drives the drag — a second touch point
+      // over the handle must not hijack it.
+      if (ev.pointerId !== e.pointerId) return
       // LTR assumption: clientX grows toward the trailing panel; RTL drag
       // inversion is a documented limitation.
       const delta = (horizontal ? ev.clientX : ev.clientY) - drag.startPos
@@ -65,9 +68,12 @@ export default class extends Controller {
       const prevGrow = this.clampPrevGrow(prev, next, (prevSize / total) * drag.pairGrow, drag.pairGrow, drag.groupGrow)
       prev.style.flexGrow = prevGrow
       next.style.flexGrow = drag.pairGrow - prevGrow
-      this.syncValuenow(handle)
+      // Resizing this pair moves every share: 3+ panel groups have sibling
+      // handles whose aria-valuenow would otherwise go stale.
+      this.handleTargets.forEach((h) => this.syncValuenow(h))
     }
-    const onUp = () => {
+    const onUp = (ev) => {
+      if (ev.pointerId !== e.pointerId) return
       handle.removeEventListener("pointermove", onMove)
       handle.removeEventListener("pointerup", onUp)
       handle.removeEventListener("pointercancel", onUp)
@@ -89,8 +95,14 @@ export default class extends Controller {
     if (!prev || !next) return
 
     const horizontal = this.directionValue === "horizontal"
+    // Horizontal arrows follow visual direction (round-7 kit convention, same
+    // as tabs/toggle_group): in RTL the DOM-first panel is on the RIGHT, so
+    // ArrowLeft must GROW it (move the divider visually left). Only the
+    // pointer-drag clientX math keeps its documented LTR exemption; Up/Down
+    // never flip. Runtime dir check — reliable after a dynamic flip.
+    const rtl = horizontal && getComputedStyle(this.element).direction === "rtl"
     const steps = horizontal
-      ? { ArrowLeft: -0.05, ArrowRight: 0.05 }
+      ? (rtl ? { ArrowLeft: 0.05, ArrowRight: -0.05 } : { ArrowLeft: -0.05, ArrowRight: 0.05 })
       : { ArrowUp: -0.05, ArrowDown: 0.05 }
 
     const pairGrow = this.growOf(prev) + this.growOf(next) || 2
@@ -109,7 +121,8 @@ export default class extends Controller {
     const prevGrow = this.clampPrevGrow(prev, next, share * pairGrow, pairGrow, this.groupGrow())
     prev.style.flexGrow = prevGrow
     next.style.flexGrow = pairGrow - prevGrow
-    this.syncValuenow(handle)
+    // All handles: sibling dividers share panels in 3+ panel groups.
+    this.handleTargets.forEach((h) => this.syncValuenow(h))
   }
 
   growOf(el) {

data/app/components/phlex_kit/resizable/resizable_handle.rb

@@ -8,18 +8,20 @@ module PhlexKit
     end
 
     def view_template
-      div(**mix({
+      base = {
         class: "pk-resizable-handle",
-        role: "separator",
-        tabindex: "0",
-        # Correct for the default horizontal group; the controller re-stamps
-        # orientation (and aria-valuenow/min/max) per group direction on connect.
-        aria: { orientation: "vertical" },
         data: {
           phlex_kit__resizable_target: "handle",
           action: "pointerdown->phlex-kit--resizable#start keydown->phlex-kit--resizable#keydown"
         }
-      }, @attrs)) do
+      }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:role] = "separator" unless attr_set?(:role)
+      base[:tabindex] = "0" unless attr_set?(:tabindex)
+      # Correct for the default horizontal group; the controller re-stamps
+      # orientation (and aria-valuenow/min/max) per group direction on connect.
+      base[:aria] = { orientation: "vertical" } unless aria_key_set?(:orientation)
+      div(**mix(base, @attrs)) do
         span(class: "pk-resizable-handle-grip", aria: { hidden: "true" }) if @with_handle
       end
     end

data/app/components/phlex_kit/select/select.rb

@@ -39,7 +39,7 @@ module PhlexKit
           # keydown.esc rides on the root (not only the items) so Escape closes
           # the [popover=manual] panel with focus on the trigger too; handleEsc
           # no-ops while closed.
-          action: "click@window->phlex-kit--select#clickOutside keydown.esc->phlex-kit--select#handleEsc"
+          action: "mousedown@window->phlex-kit--select#onMousedownOutside click@window->phlex-kit--select#clickOutside keydown.esc->phlex-kit--select#handleEsc focusout->phlex-kit--select#onFocusout"
         }
       }, @attrs), &block)
     end

data/app/components/phlex_kit/select/select_content.rb

@@ -14,17 +14,19 @@ module PhlexKit
     end
 
     def view_template(&block)
-      div(**mix({
+      base = {
         id: @id,
-        role: "listbox",
-        tabindex: "-1",
         class: "pk-select-content",
-        popover: "manual",
         data: {
           phlex_kit__select_target: "content",
           action: "keydown->phlex-kit--select#typeahead"
         }
-      }, @attrs)) do
+      }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:role] = "listbox" unless attr_set?(:role)
+      base[:tabindex] = "-1" unless attr_set?(:tabindex)
+      base[:popover] = "manual" unless attr_set?(:popover)
+      div(**mix(base, @attrs)) do
         div(class: "pk-select-viewport", &block)
       end
     end

data/app/components/phlex_kit/select/select_controller.js

@@ -1,5 +1,20 @@
 import { Controller } from "@hotwired/stimulus";
 
+// One-shot capture listener swallowing the click an outside mousedown is about
+// to produce (see onMousedownOutside; same helper in dropdown/context/menubar
+// — duplicated per controller by design). Select is a MODAL menu: the
+// dismissing outside click ONLY dismisses, never also acts on what sits under
+// the pointer. Armed at MOUSEDOWN because for a focusable click target the same
+// gesture's focusout closes the panel before the click fires (a click-time
+// check would already see it closed and skip the swallow — audit round 8).
+const swallowClick = (ev) => {
+  ev.preventDefault();
+  ev.stopPropagation();
+};
+function armSwallowClick() {
+  window.addEventListener("click", swallowClick, { once: true, capture: true });
+}
+
 // Ported from ruby_ui's phlex-kit--select controller, minus the
 // @floating-ui/dom dependency: the panel is a native [popover=manual] in the
 // top layer, anchor-positioned with viewport-edge flipping by select.css
@@ -53,6 +68,12 @@ export default class extends Controller {
     const newValue = item.dataset.value;
 
     this.inputTarget.value = newValue;
+    // Also set the value ATTRIBUTE, not just the .value property: a Turbo
+    // snapshot restore clones the DOM (dropping the dirty property) and would
+    // otherwise revert the hidden input to its server value while the label
+    // and aria-selected still show the chosen item — submitting the wrong
+    // value behind a correct-looking UI. (re-derive-from-live-truth rule.)
+    this.inputTarget.setAttribute("value", newValue);
     this.valueTarget.innerText = item.innerText;
 
     this.dispatchOnChange(oldValue, newValue);
@@ -162,6 +183,17 @@ export default class extends Controller {
     this.itemTargets.forEach((item) => item.removeAttribute("aria-current"));
   }
 
+  // Modal dismiss: arm the swallow at mousedown so the outside click that
+  // dismisses an open select doesn't ALSO activate a focusable control under
+  // the pointer (the same gesture's focusout closes the panel before the
+  // click, so clickOutside below would already see it closed). Mirrors
+  // dropdown/context/menubar.
+  onMousedownOutside(event) {
+    if (!this.contentTarget.matches(":popover-open")) return;
+    if (this.element.contains(event.target)) return;
+    armSwallowClick();
+  }
+
   clickOutside(event) {
     if (!this.contentTarget.matches(":popover-open")) return;
     if (this.element.contains(event.target)) return;
@@ -170,6 +202,16 @@ export default class extends Controller {
     this.#hide();
   }
 
+  // APG (select-only combobox): Tab out of an open listbox closes it —
+  // dropdown_menu's onFocusout pattern. relatedTarget is null when the
+  // window itself blurs; leave the panel alone then.
+  onFocusout(event) {
+    if (!this.contentTarget.matches(":popover-open")) return;
+    const to = event.relatedTarget;
+    if (!to || this.element.contains(to)) return;
+    this.#hide();
+  }
+
   // Open/close derive from the live :popover-open state, never a stored
   // flag — a stale flag is how a close on an already-closed panel becomes
   // an open (bit the popover's keyboard toggle).

data/app/components/phlex_kit/select/select_separator.rb

@@ -4,7 +4,7 @@ module PhlexKit
   class SelectSeparator < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template
-      div(**mix({ class: "pk-select-separator", role: "separator", aria: { hidden: true } }, @attrs))
+      div(**mix({ class: "pk-select-separator", role: "separator", aria: { hidden: "true" } }, @attrs))
     end
   end
 end

data/app/components/phlex_kit/sheet/sheet_content_controller.js

@@ -63,12 +63,19 @@ export default class extends Controller {
   }
 
   keydown(event) {
-    // A native <dialog> nested inside this panel (e.g. a Dialog opened from
-    // within SheetContent) owns its own Escape handling; the keydown still
-    // bubbles through this element-scoped listener since dialog is a DOM
-    // descendant — ignore it so one Escape doesn't also close the sheet
-    // underneath.
+    // Yield to any inner overlay that owns this Escape so one keypress doesn't
+    // also close the sheet/drawer underneath: a native <dialog> (its own
+    // Escape handling), or an open [popover] menu — Select / DropdownMenu /
+    // Combobox, all popover=manual — rendered inside the panel. Two signals
+    // make the outcome independent of ordering: event.defaultPrevented catches
+    // an inner handler that already consumed the key (Select's Escape is
+    // element-scoped and fires deeper in the bubble, so it runs first); the
+    // live :popover-open check catches a menu whose Escape handler is
+    // document-level (DropdownMenu) and thus still open when this
+    // element-scoped listener runs.
+    if (event.key === "Escape" && event.defaultPrevented) return
     if (event.key === "Escape" && event.target.closest("dialog[open]")) return
+    if (event.key === "Escape" && this.panel.querySelector("[popover]:popover-open")) return
     if (event.key === "Escape") {
       event.preventDefault()
       // Stop the keydown from reaching a lower/outer overlay's own

data/app/components/phlex_kit/sidebar/sidebar_group_action.rb

@@ -8,7 +8,7 @@ module PhlexKit
     end
 
     def view_template(&block)
-      button(**mix({ class: "pk-sidebar-group-action", type: "button" }, @attrs), &block)
+      button(**mix({ class: "pk-sidebar-group-action", type: :button }, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/sidebar/sidebar_menu_action.rb

@@ -7,7 +7,7 @@ module PhlexKit
     end
 
     def view_template(&block)
-      button(**mix({ class: "pk-sidebar-menu-action", type: "button" }, @attrs), &block)
+      button(**mix({ class: "pk-sidebar-menu-action", type: :button }, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/sidebar/sidebar_rail.rb

@@ -17,12 +17,13 @@ module PhlexKit
       base = {
         type: :button,
         class: "pk-sidebar-rail",
-        aria_label: "Toggle sidebar",
         "aria-expanded": @expanded ? "true" : "false",
         tabindex: "-1",
-        title: "Toggle sidebar",
         data: { action: "click->phlex-kit--sidebar#toggle" }
       }
+      # Defaults only when the caller didn't supply their own — `mix` fuses.
+      base[:aria_label] = "Toggle sidebar" unless aria_labelled?
+      base[:title] = "Toggle sidebar" unless attr_set?(:title)
       base["aria-controls"] = @controls if @controls
       button(**mix(base, @attrs))
     end

data/app/components/phlex_kit/sidebar/sidebar_trigger.rb

@@ -20,10 +20,11 @@ module PhlexKit
       base = {
         type: :button,
         class: "pk-sidebar-trigger",
-        aria_label: "Toggle sidebar",
         "aria-expanded": @expanded ? "true" : "false",
         data: { action: "click->phlex-kit--sidebar#toggle" }
       }
+      # Default only when the caller didn't supply their own — `mix` fuses.
+      base[:aria_label] = "Toggle sidebar" unless aria_labelled?
       base["aria-controls"] = @controls if @controls
       button(**mix(base, @attrs)) do
         block ? yield : render(Icon.new(:menu, size: nil))

data/app/components/phlex_kit/switch/switch.rb

@@ -30,7 +30,10 @@ module PhlexKit
         end
         # role="switch" belongs on the focusable control: native checkedness then
         # maps to aria-checked for AT, and the label stays a plain label.
-        input(**mix({ class: "pk-switch-input", role: "switch" }, @attrs).merge(type: "checkbox", value: @checked_value))
+        # Default role only when the caller didn't supply their own — `mix` fuses.
+        input_base = { class: "pk-switch-input" }
+        input_base[:role] = "switch" unless attr_set?(:role)
+        input(**mix(input_base, @attrs).merge(type: "checkbox", value: @checked_value))
         span(class: "pk-switch-thumb")
       end
     end

data/app/components/phlex_kit/table/table_head.rb

@@ -6,7 +6,12 @@ module PhlexKit
     end
 
     def view_template(&block)
-      th(**mix({ class: "pk-table-head" }, @attrs), &block)
+      # scope="col" is the common case (header cells sit in a TableHeader row);
+      # a generated default, not a merged attr — `mix` would fuse a caller's
+      # `scope: "row"` into "col row" — so skip it when the caller sets scope.
+      base = { class: "pk-table-head" }
+      base[:scope] = "col" unless attr_set?(:scope)
+      th(**mix(base, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/tabs/tabs_content.rb

@@ -13,7 +13,12 @@ module PhlexKit
       # focusable, per the APG tabs pattern. `active:` (mirroring TabsTrigger's)
       # renders the panel visible pre-JS/no-JS; the controller's sync()
       # reconciles visibility from the active value after connect.
-      div(**mix({ class: @active ? "pk-tabs-content" : "pk-tabs-content pk-hidden", role: "tabpanel", id: @id, aria_labelledby: "pk-tabs-trigger-#{@value}", tabindex: "0", data: { phlex_kit__tabs_target: "content", value: @value } }, @attrs), &)
+      base = { class: @active ? "pk-tabs-content" : "pk-tabs-content pk-hidden", role: "tabpanel", id: @id, data: { phlex_kit__tabs_target: "content", value: @value } }
+      # Generated defaults only when the caller didn't supply their own —
+      # `mix` fuses (custom-id trigger pairing / a non-focusable panel).
+      base[:aria_labelledby] = "pk-tabs-trigger-#{@value}" unless aria_key_set?(:labelledby)
+      base[:tabindex] = "0" unless attr_set?(:tabindex)
+      div(**mix(base, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/tabs/tabs_trigger.rb

@@ -24,13 +24,15 @@ module PhlexKit
       base = {
         class: "pk-tabs-trigger", role: "tab", id: @id,
         aria_selected: @active ? "true" : "false",
-        aria_controls: "pk-tabs-panel-#{@value}",
         tabindex: @active ? "0" : "-1",
         # data-state is the only hook tabs.css styles the active trigger by —
         # it must be server-rendered or the active tab looks inactive pre-JS.
         data: { phlex_kit__tabs_target: "trigger", action: "click->phlex-kit--tabs#show", value: @value,
                 state: @active ? "active" : "inactive" }
       }
+      # Generated idref default only when the caller didn't supply their own
+      # (pairing with a custom-id TabsContent) — `mix` fuses.
+      base[:aria_controls] = "pk-tabs-panel-#{@value}" unless aria_key_set?(:controls)
       if @as == :a
         a(**mix(base, @attrs), &)
       else

data/app/components/phlex_kit/theme_toggle/theme_toggle_controller.js

@@ -25,12 +25,23 @@ export default class extends Controller {
     // echo guard in apply().
     this._rootObserver = new MutationObserver(() => this.syncPressed())
     this._rootObserver.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] })
+    // Cross-tab sync: `storage` fires only in OTHER tabs when localStorage.theme
+    // changes, so another tab's toggle re-applies here. Without this, this tab's
+    // DOM went stale while storedTheme() (read fresh from localStorage) already
+    // returned the new value — the echo guard in apply() then swallowed a
+    // genuine click because resolvedTheme() already matched.
+    this._onStorage = (e) => {
+      if (e.key !== "theme") return
+      this.applyTheme(this.storedTheme() || "system")
+    }
+    window.addEventListener("storage", this._onStorage)
     this.applyTheme(this.storedTheme() || "system")
   }
 
   disconnect() {
     this._media?.removeEventListener("change", this._onMediaChange)
     this._rootObserver?.disconnect()
+    window.removeEventListener("storage", this._onStorage)
   }
 
   syncPressed() {
@@ -41,12 +52,19 @@ export default class extends Controller {
 
   apply(e) {
     const theme = e.detail?.pressed ? "dark" : "light"
-    // connect()'s own pressed-state sync re-enters here via the toggle's
-    // change event (Stimulus value observation is async, so a flag can't
-    // gate it). If the incoming theme already matches the resolved one this
-    // is that echo, not a user toggle — persisting it would silently pin
-    // the visitor's OS preference in localStorage on first visit.
-    if (theme === this.resolvedTheme()) return
+    // Skip when this isn't a genuine user toggle — two echo shapes:
+    // - the incoming theme already matches the RESOLVED one: connect()'s own
+    //   pressed-state sync re-enters here via the toggle's change event
+    //   (Stimulus value observation is async, so a flag can't gate it), and a
+    //   "system" resolution lands here too — persisting either would silently
+    //   pin the visitor's OS preference in localStorage on first visit.
+    // - the root's data-theme ALREADY equals it: host code (or a cross-tab
+    //   storage sync) wrote the theme directly. The contract is that only a
+    //   user toggle persists, and a real user toggle reaches here BEFORE
+    //   applyTheme updates the root, so the root still holds the OLD value —
+    //   a match therefore means "not a user action, don't persist".
+    const rootTheme = document.documentElement.getAttribute("data-theme")
+    if (theme === this.resolvedTheme() || theme === rootTheme) return
     this.storeTheme(theme)
     this.applyTheme(theme)
   }

data/app/components/phlex_kit/toast/toast_controller.js

@@ -16,6 +16,11 @@ export default class extends Controller {
   }
 
   connect() {
+    // Inherit the region's duration when this item didn't set its own: a
+    // block-rendered ToastItem carries no duration-value, so without this the
+    // Stimulus 4000ms default would win and ToastRegion(duration:) would be
+    // dead config for block items (skeleton/flash items already stamp it).
+    this._inheritRegionDuration()
     this._timer = null
     this._unmountTimer = null
     this._startedAt = 0
@@ -35,7 +40,16 @@ export default class extends Controller {
     this._onPointerLeave = () => { if (!this._swipe.active) this._resume("hover") }
     // Keyboard parity with hover: tabbing into the toast (e.g. to reach its
     // action button) must pause auto-dismiss just like pointerenter does.
-    this._onFocusIn = () => this._pause("focus")
+    this._onFocusIn = (e) => {
+      this._pause("focus")
+      // Remember where focus came from the FIRST time it enters from outside
+      // the toaster, so dismissing the last focused toast can hand focus back
+      // instead of dropping it on <body>.
+      const list = this.element.closest(".pk-toast-list") || this.element
+      if (this._focusReturn == null && e.relatedTarget && !list.contains(e.relatedTarget)) {
+        this._focusReturn = e.relatedTarget
+      }
+    }
     this._onFocusOut = (e) => { if (!this.element.contains(e.relatedTarget)) this._resume("focus") }
     this._onKeyDown = this._onKeyDown.bind(this)
     this._onForceDismiss = (e) => { e.stopPropagation(); this._close() }
@@ -103,11 +117,42 @@ export default class extends Controller {
   _close(reason) {
     if (this.element.dataset.state === "closing") return
     this.element.dataset.state = "closing"
+    // If focus is inside this toast, move it BEFORE removal so it doesn't drop
+    // to <body> when the element is gone (Escape, close button, or action).
+    const hadFocus = this.element.contains(document.activeElement)
     this.element.dispatchEvent(new CustomEvent(reason === "auto" ? "phlex-kit:toast:auto-close" : "phlex-kit:toast:dismiss", { bubbles: true, detail: { id: this.element.id } }))
     this._invokeCallback(reason === "auto" ? this.onAutoCloseValue : this.onDismissValue)
+    if (hadFocus) this._restoreFocusOnClose()
     this._unmountTimer = setTimeout(() => this.element.remove(), TIME_BEFORE_UNMOUNT)
   }
 
+  // Keep keyboard focus inside the toaster when a focused toast is dismissed:
+  // hand it to an adjacent remaining toast, else back to wherever focus came
+  // from before it entered the toaster (tracked on first focusin).
+  _restoreFocusOnClose() {
+    const list = this.element.closest(".pk-toast-list")
+    const others = list
+      ? [...list.querySelectorAll("[data-controller~='phlex-kit--toast']")]
+          .filter((t) => t !== this.element && t.dataset.state !== "closing")
+      : []
+    if (others.length) {
+      const children = [...list.children]
+      const myIdx = children.indexOf(this.element)
+      const next = others.find((t) => children.indexOf(t) > myIdx) || others[others.length - 1]
+      next.focus()
+      return
+    }
+    if (this._focusReturn?.isConnected) this._focusReturn.focus()
+  }
+
+  _inheritRegionDuration() {
+    if (this.element.hasAttribute("data-phlex-kit--toast-duration-value")) return
+    const region = this.element.closest("[data-phlex-kit--toaster-duration-value]")
+    if (!region) return
+    const inherited = Number(region.getAttribute("data-phlex-kit--toaster-duration-value"))
+    if (Number.isFinite(inherited)) this.durationValue = inherited
+  }
+
   // on_dismiss:/on_auto_close: name a global function (Sonner-style callback
   // for server-rendered toasts).
   _invokeCallback(name) {