phlex_kit 0.11.0 → 0.12.0

data/app/components/phlex_kit/item/item.css

@@ -34,7 +34,8 @@ a.pk-item:hover { background: var(--pk-surface-2); }
   transform: translateY(.125rem);
   align-self: flex-start;
 }
-.pk-item-media.icon svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
+/* Glyphs default to size-4; explicit width attrs (Icon size:) win. */
+.pk-item-media.icon svg:not([width]) { width: 1rem; height: 1rem; }
 .pk-item-media.image {
   width: 2.5rem;
   height: 2.5rem;

data/app/components/phlex_kit/kbd/kbd.css

@@ -15,7 +15,8 @@
   font-weight: 500;
 }
 .pk-kbd-group { display: inline-flex; align-items: center; gap: .25rem; font-family: inherit; }
-.pk-kbd svg:not([class*="size-"]) { width: .75rem; height: .75rem; }
+/* Glyphs default to size-3; explicit width attrs (Icon size:) win. */
+.pk-kbd svg:not([width]) { width: .75rem; height: .75rem; }
 /* Inside an (inverted) tooltip the chip tints from the page background. */
 .pk-tooltip-content .pk-kbd {
   background: color-mix(in oklab, var(--pk-bg) 10%, transparent);

data/app/components/phlex_kit/label/label.css

@@ -9,4 +9,4 @@
   line-height: 1;
   user-select: none;
 }
-.pk-label:has(+ :disabled), .pk-label:has(:disabled) { cursor: not-allowed; opacity: .5; }
+.pk-label:has(+ :disabled), .pk-label:has(:disabled), :disabled + .pk-label { cursor: not-allowed; opacity: .5; }

data/app/components/phlex_kit/link/link.rb

@@ -20,6 +20,7 @@ module PhlexKit
     }.freeze
 
     SIZES = {
+      xs: "xs",
       sm: "sm",
       md: nil,
       lg: "lg",

data/app/components/phlex_kit/marker/marker.css

@@ -25,7 +25,8 @@ a.pk-marker, button.pk-marker {
   font-size: .875rem;
 }
 a.pk-marker:hover, button.pk-marker:hover { color: var(--pk-text); }
-.pk-marker svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
+/* Glyphs default to size-4; explicit width attrs (Icon size:) win. */
+.pk-marker svg:not([width]) { width: 1rem; height: 1rem; }
 .pk-marker-icon { display: inline-flex; flex: none; width: 1rem; height: 1rem; }
 .pk-marker-content { min-width: 0; overflow-wrap: break-word; }
 .pk-marker-content a { text-decoration: underline; text-underline-offset: 3px; color: inherit; }

data/app/components/phlex_kit/menubar/menubar.css

@@ -129,6 +129,9 @@
    the viewport right edge. */
 .pk-menubar-sub { anchor-name: --pk-menubar-sub; anchor-scope: --pk-menubar-sub; }
 .pk-menubar-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-menubar-sub-chevron { transform: scaleX(-1); }
 .pk-menubar-sub-content {
   position: fixed;
   position-anchor: --pk-menubar-sub;

data/app/components/phlex_kit/menubar/menubar_controller.js

@@ -48,6 +48,12 @@ export default class extends Controller {
     // (only on elements that already carry it: plain nav links must not
     // grow an aria-expanded). Covers the trigger and CSS-revealed subs.
     menu.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.
+    menu.querySelectorAll('input[type="checkbox"], input[type="radio"]').forEach((i) => {
+      i.closest('[role^="menuitem"]')?.setAttribute("aria-checked", i.checked)
+    })
     if (this.roving) this.applyRoving()
   }
 
@@ -107,8 +113,15 @@ export default class extends Controller {
     if (focus) (this.items(menu)[0] ?? this.trigger(menu))?.focus()
   }
 
+  // Also wired directly as the click handler on plain nav links (see
+  // navigation_menu_link.rb) — `opts` is then the click Event rather than an
+  // options hash. Guard the default href="#" (dropdown_menu_controller.js's
+  // close() does the same) so a link without a real destination doesn't
+  // scroll-to-top/append a hash; a link WITH a real href is left to navigate
+  // normally, closing whatever panel is open on the way out.
   close(opts = {}) {
     clearTimeout(this.graceTimer)
+    if (opts?.target?.closest?.('a[href="#"]')) opts.preventDefault?.()
     const menu = this.openMenu
     if (!menu) return
     const panel = this.panel(menu)
@@ -147,10 +160,14 @@ export default class extends Controller {
         e.preventDefault()
         this.show(menu, true)
       } else if (e.key === "ArrowRight" || e.key === "ArrowLeft") {
-        // Closed bar: left/right move focus between the triggers (APG).
+        // Closed bar: left/right move focus between the triggers (APG). In RTL
+        // the bar mirrors, so the physical LEFT arrow moves to the next
+        // trigger. Runtime dir check is reliable after a dynamic flip.
         e.preventDefault()
+        const rtl = getComputedStyle(this.element).direction === "rtl"
+        const step = (e.key === "ArrowRight" ? 1 : -1) * (rtl ? -1 : 1)
         const menus = this.menuTargets
-        const next = menus[(menus.indexOf(menu) + (e.key === "ArrowRight" ? 1 : -1) + menus.length) % menus.length]
+        const next = menus[(menus.indexOf(menu) + step + menus.length) % menus.length]
         const target = next ? this.trigger(next) : null
         target?.focus()
         if (this.roving && target) this.applyRoving(target)
@@ -190,23 +207,30 @@ export default class extends Controller {
         }
         break
       case "ArrowRight":
-        e.preventDefault()
-        // On a sub trigger, enter the submenu (focus reveals it via
-        // :focus-within) instead of jumping to the next top-level menu.
-        if (document.activeElement?.matches(".pk-menubar-sub-trigger")) {
-          this.enterSub(document.activeElement)
-        } else {
-          this.shift(1)
-        }
-        break
       case "ArrowLeft": {
         e.preventDefault()
-        // Inside a submenu, step back to its trigger instead of switching menus.
-        const sub = document.activeElement?.closest(".pk-menubar-sub-content")
-        if (sub) {
-          sub.closest(".pk-menubar-sub")?.querySelector(".pk-menubar-sub-trigger")?.focus()
+        // Both the submenu (opens inline-end = visually LEFT in RTL) and the
+        // top-level menu traversal follow visual direction: the "enter/next"
+        // key is ArrowLeft in RTL, ArrowRight in LTR. 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) instead of jumping to the next top-level menu.
+          if (document.activeElement?.matches(".pk-menubar-sub-trigger")) {
+            this.enterSub(document.activeElement)
+          } else {
+            this.shift(1)
+          }
         } else {
-          this.shift(-1)
+          // Inside a submenu, step back to its trigger instead of switching menus.
+          const sub = document.activeElement?.closest(".pk-menubar-sub-content")
+          if (sub) {
+            sub.closest(".pk-menubar-sub")?.querySelector(".pk-menubar-sub-trigger")?.focus()
+          } else {
+            this.shift(-1)
+          }
         }
         break
       }

data/app/components/phlex_kit/native_select/native_select.css

@@ -33,6 +33,20 @@
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
 .pk-native-select-field:disabled { cursor: not-allowed; opacity: .5; }
+/* [size] (a multi-row list box, NativeSelect.new(size: N)) or [multiple]
+   renders as a scrollable option list, not a single-line control — the fixed
+   2rem row height squashes it and there's no single line for the absolute
+   chevron to sit in, so auto-height the field and hide the chevron.
+   Note: [size="1"] is a single-line dropdown, not a list box — exclude it. */
+.pk-native-select-field[size]:not([size="1"]),
+.pk-native-select-field[multiple] {
+  height: auto;
+  padding-inline-end: .625rem;
+}
+.pk-native-select:has(.pk-native-select-field[size]:not([size="1"])) .pk-native-select-icon,
+.pk-native-select:has(.pk-native-select-field[multiple]) .pk-native-select-icon {
+  display: none;
+}
 .pk-native-select-field.sm {
   height: 1.75rem;
   padding-top: .125rem;

data/app/components/phlex_kit/navigation_menu/navigation_menu_link.rb

@@ -11,7 +11,14 @@ module PhlexKit
     end
 
     def view_template(&)
-      a(**mix({ class: "pk-navigation-menu-link", href: @href, data: { action: "mouseenter->phlex-kit--menubar#switch" } }, @attrs), &)
+      a(**mix({
+        class: "pk-navigation-menu-link",
+        href: @href,
+        # click: closes the open panel on real activation (and swallows the
+        # default href="#" the way dropdown_menu_controller.js's close() does
+        # — see menubar_controller.js#close).
+        data: { action: "mouseenter->phlex-kit--menubar#switch click->phlex-kit--menubar#close" }
+      }, @attrs), &)
     end
   end
 end

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

@@ -48,6 +48,25 @@ export default class extends Controller {
     this.contentTarget.togglePopover()
   }
 
+  // Public close, for consumers that need to dismiss the panel from outside
+  // a trigger interaction (e.g. the date picker closing on a complete
+  // calendar selection). Returns focus to the trigger's focusable child —
+  // dismissing without it would strand focus on the day button that's
+  // about to disappear from the DOM.
+  close() {
+    if (this.contentTarget.matches(":popover-open")) {
+      this.contentTarget.hidePopover()
+    }
+    this.focusTrigger()
+  }
+
+  focusTrigger() {
+    const focusable = this.fallbackInvoker
+      || this.triggerTarget.querySelector("button, input, a[href], select, textarea, [tabindex]")
+      || this.triggerTarget
+    focusable.focus()
+  }
+
   // One stable handler added/removed symmetrically — an anonymous listener
   // here would pile up a duplicate on every target reconnect.
   syncState = (e) => {

data/app/components/phlex_kit/scroll_area/scroll_area.rb

@@ -16,21 +16,8 @@ module PhlexKit
       # fuse role="region log" / tabindex="0 -1" instead of overriding.
       base = { class: "pk-scroll-area" }
       base[:tabindex] = "0" unless @attrs.key?(:tabindex) || @attrs.key?("tabindex")
-      base[:role] = "region" if labelled? && !@attrs.key?(:role) && !@attrs.key?("role")
+      base[:role] = "region" if aria_labelled? && !@attrs.key?(:role) && !@attrs.key?("role")
       div(**mix(base, @attrs), &)
     end
-
-    private
-
-    # True when the caller supplies an accessible name, via the aria: hash
-    # (aria: { label:/labelledby: }) or flat aria_label/aria-labelledby attrs.
-    def labelled?
-      aria = @attrs[:aria] || @attrs["aria"]
-      if aria.is_a?(Hash)
-        return true if %w[label labelledby].any? { |k| aria[k.to_sym] || aria[k] }
-      end
-      [ :aria_label, "aria_label", "aria-label",
-       :aria_labelledby, "aria_labelledby", "aria-labelledby" ].any? { |k| @attrs[k] }
-    end
   end
 end

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

@@ -59,6 +59,28 @@ export default class extends Controller {
     this.closeContent();
   }
 
+  // APG select pattern: ArrowDown/ArrowUp on the CLOSED trigger opens the
+  // listbox and highlights the first/last option, instead of only working
+  // once already open (combobox_controller.js's keyDownPressed/keyUpPressed
+  // does the equivalent for its own open/closed model).
+  handleTriggerArrowDown(event) {
+    if (this.openValue) return
+    event.preventDefault()
+    this.#show()
+    if (this.itemTargets.length === 0) return
+    this.resetCurrent()
+    this.setAriaCurrentAndActiveDescendant(0)
+  }
+
+  handleTriggerArrowUp(event) {
+    if (this.openValue) return
+    event.preventDefault()
+    this.#show()
+    if (this.itemTargets.length === 0) return
+    this.resetCurrent()
+    this.setAriaCurrentAndActiveDescendant(this.itemTargets.length - 1)
+  }
+
   onClick() {
     this.toggleContent();
 

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

@@ -16,7 +16,10 @@ module PhlexKit
         role: "combobox",
         class: [ "pk-select-trigger", fetch_option(SIZES, @size, :size) ].compact.join(" "),
         aria: { expanded: "false", haspopup: "listbox", autocomplete: "none" },
-        data: { action: "phlex-kit--select#onClick", phlex_kit__select_target: "trigger" }
+        data: { action: "phlex-kit--select#onClick " \
+                  "keydown.down->phlex-kit--select#handleTriggerArrowDown " \
+                  "keydown.up->phlex-kit--select#handleTriggerArrowUp",
+          phlex_kit__select_target: "trigger" }
       }, @attrs)) do
         block&.call
         icon

data/app/components/phlex_kit/sheet/sheet_content.rb

@@ -9,9 +9,19 @@ module PhlexKit
     end
     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-sheet-backdrop", data: { action: "click->phlex-kit--sheet-content#close" })
-          div(**mix({ class: [ "pk-sheet-content", fetch_option(SIDES, @side, :side) ].join(" "), role: "dialog", aria: { modal: "true" }, tabindex: "-1", data: { phlex_kit__sheet_content_target: "panel" } }, @attrs)) do
+        # data-pk-overlay-clone is a common marker read by other clone-based
+        # overlays (see alert_dialog_controller.js#topmost) to determine
+        # z-stacking across overlay families when they nest.
+        div(data: { controller: "phlex-kit--sheet-content", action: "keydown->phlex-kit--sheet-content#keydown", pk_overlay_clone: "" }) do
+          div(class: "pk-sheet-backdrop", data: { action: "click->phlex-kit--sheet-content#close mousedown->phlex-kit--sheet-content#overlayMousedown" })
+          panel_attrs = { class: [ "pk-sheet-content", fetch_option(SIDES, @side, :side) ].join(" "), 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
             block&.call
             if @show_close_button
               button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--sheet-content#close" }) do

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

@@ -15,6 +15,7 @@ export default class extends Controller {
   static targets = ["panel"]
 
   connect() {
+    this.restored = false
     this.opener = document.activeElement
     this.previousOverflow = document.body.style.overflow
     document.body.style.overflow = "hidden"
@@ -26,6 +27,20 @@ export default class extends Controller {
   }
 
   disconnect() {
+    this.restoreImmediate()
+  }
+
+  // Synchronously undoes everything connect() did: background inert,
+  // scroll lock, and the closed-notification to the source sheet
+  // controller. Called from disconnect() (the normal removal path) AND
+  // from the source phlex-kit--sheet controller's turbo:before-cache
+  // handler, which must restore state before Turbo's synchronous snapshot
+  // — disconnect() fires via MutationObserver, too late for that snapshot.
+  // Idempotent (guarded by `this.restored`) so whichever path runs second
+  // is a harmless no-op.
+  restoreImmediate() {
+    if (this.restored) return
+    this.restored = true
     this.#restoreInert()
     document.body.style.overflow = this.previousOverflow
     if (this.opener?.isConnected) this.opener.focus()
@@ -39,9 +54,30 @@ export default class extends Controller {
     this.element.remove()
   }
 
+  // Backdrop mousedown would move focus to <body>, killing this
+  // element-scoped keydown listener (Escape after a drag-off-backdrop would
+  // stop working) — prevented here so focus stays inside the panel. The
+  // backdrop's click->close action still fires normally afterward.
+  overlayMousedown(event) {
+    event.preventDefault()
+  }
+
   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.
+    if (event.key === "Escape" && event.target.closest("dialog[open]")) return
     if (event.key === "Escape") {
       event.preventDefault()
+      // Stop the keydown from reaching a lower/outer overlay's own
+      // document-level Escape listener (e.g. an alert_dialog this sheet is
+      // stacked on top of) — this element-scoped listener runs first during
+      // bubbling, and by the time a document-level listener would see it,
+      // this.close() has already removed the [data-pk-overlay-clone] marker
+      // the other overlay's #topmost() check relies on.
+      event.stopPropagation()
       this.close()
       return
     }

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

@@ -11,8 +11,19 @@ export default class extends Controller {
 
   initialize() {
     this.overlay = null
+    // Turbo snapshots synchronously right after dispatching this event —
+    // BEFORE Stimulus disconnect() runs (it fires via MutationObserver, too
+    // late to keep the snapshot from capturing an inerted, scroll-locked
+    // page). Reach into the clone's own controller and restore its state
+    // synchronously before removing it; that method is idempotent, so the
+    // content controller's own disconnect() (fired later, once the removal
+    // is observed) is a harmless no-op.
     this.clearOverlay = () => {
-      if (this.overlay?.isConnected) this.overlay.remove()
+      if (this.overlay?.isConnected) {
+        const content = this.application.getControllerForElementAndIdentifier(this.overlay, "phlex-kit--sheet-content")
+        content?.restoreImmediate()
+        this.overlay.remove()
+      }
       this.overlay = null
     }
   }
@@ -22,7 +33,11 @@ export default class extends Controller {
     // Popup semantics for AT: the trigger's real control announces that it
     // opens a dialog, and expanded state tracks the clone's lifetime (the
     // content controller signals removal via phlex-kit:sheet-content:closed).
-    this.invoker = this.element.querySelector(".pk-sheet-trigger button, .pk-sheet-trigger a, .pk-sheet-trigger [tabindex]")
+    // Drawer rides this same controller (see drawer.rb) — its trigger is
+    // marked .pk-drawer-trigger rather than .pk-sheet-trigger.
+    this.invoker = this.element.querySelector(
+      ".pk-sheet-trigger button, .pk-sheet-trigger a, .pk-sheet-trigger [tabindex], .pk-drawer-trigger button, .pk-drawer-trigger a, .pk-drawer-trigger [tabindex]"
+    )
     this.invoker?.setAttribute("aria-haspopup", "dialog")
     this.invoker?.setAttribute("aria-expanded", "false")
     this.onOverlayClosed = () => {

data/app/components/phlex_kit/spinner/spinner.rb

@@ -11,12 +11,15 @@ module PhlexKit
 
     def view_template
       # A visible loader, not decoration: role=status + label, aria-hidden off.
-      render Icon.new(:loader, size: nil, **mix({
+      base = {
         class: [ "pk-spinner", fetch_option(SIZES, @size, :size) ].compact.join(" "),
         role: "status",
-        aria: { label: "Loading" },
         "aria-hidden": false
-      }, @attrs))
+      }
+      # Default label only when the caller didn't supply their own — `mix`
+      # would fuse aria-label="Loading Saving" instead of overriding.
+      base[:aria] = { label: "Loading" } unless aria_labelled?
+      render Icon.new(:loader, size: nil, **mix(base, @attrs))
     end
   end
 end

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

@@ -6,6 +6,12 @@ module PhlexKit
     SIZES = { md: nil, sm: "sm" }.freeze
 
     def initialize(include_hidden: true, checked_value: "1", unchecked_value: "0", size: :md, wrapper: {}, **attrs)
+      # value: is silently clobbered below (the checkbox's real value comes
+      # from checked_value:) — fail loud rather than let a caller's value:
+      # vanish (mirrors ToggleGroupItem's unsupported-kwargs guard).
+      if attrs.key?(:value)
+        raise ArgumentError, "Switch does not support value: — the checkbox's value comes from checked_value:, pass that instead"
+      end
       @include_hidden = include_hidden
       @checked_value = checked_value
       @unchecked_value = unchecked_value

data/app/components/phlex_kit/tabs/tabs_controller.js

@@ -29,8 +29,14 @@ export default class extends Controller {
   // tab sets also answer to ArrowUp/ArrowDown.
   keydown(event) {
     const vertical = this.element.classList.contains("vertical")
-    const nextKeys = vertical ? ["ArrowRight", "ArrowDown"] : ["ArrowRight"]
-    const prevKeys = vertical ? ["ArrowLeft", "ArrowUp"] : ["ArrowLeft"]
+    // In RTL the tablist mirrors: the physical LEFT arrow moves to the NEXT
+    // trigger. The vertical Up/Down pair is unaffected (runtime dir check is
+    // reliable even after a dynamic flip — carousel's idiom).
+    const rtl = getComputedStyle(this.element).direction === "rtl"
+    const fwd = rtl ? "ArrowLeft" : "ArrowRight"
+    const back = rtl ? "ArrowRight" : "ArrowLeft"
+    const nextKeys = vertical ? [fwd, "ArrowDown"] : [fwd]
+    const prevKeys = vertical ? [back, "ArrowUp"] : [back]
     const triggers = this.triggerTargets.filter((el) => !el.disabled)
     if (triggers.length === 0) return
     const index = triggers.indexOf(document.activeElement)

data/app/components/phlex_kit/toast/toast_action.rb

@@ -15,7 +15,7 @@ module PhlexKit
       # Caller action first, then dismiss — client-spawned actions dismiss
       # their toast after onClick (Sonner parity), so server-rendered ones
       # must too.
-      data[:action] = [ @on, "click->phlex-kit--toast#dismiss" ].compact.join(" ") if @on
+      data[:action] = [ @on, "click->phlex-kit--toast#dismiss" ].compact.join(" ")
       button(**mix({ type: :button, class: "pk-toast-action", data: data }, @attrs)) { @label }
     end
   end

data/app/components/phlex_kit/toast/toast_close.rb

@@ -7,12 +7,15 @@ module PhlexKit
     end
 
     def view_template
-      button(**mix({
+      base = {
         type: :button,
         class: "pk-toast-close",
-        aria: { label: "Close toast" },
         data: { slot: "close", action: "click->phlex-kit--toast#dismiss" }
-      }, @attrs)) do
+      }
+      # Default label only when the caller didn't supply their own — `mix`
+      # would fuse aria-label into a two-token value instead of overriding.
+      base[:aria] = { label: "Close toast" } unless aria_labelled?
+      button(**mix(base, @attrs)) do
         render Icon.new(:x, size: 14)
         span(class: "pk-sr-only") { "Close" }
       end

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

@@ -20,23 +20,28 @@ export default class extends Controller {
     this._unmountTimer = null
     this._startedAt = 0
     this._remaining = this.durationValue
-    this._paused = false
+    // Independent pause sources (hover / focus / region) — resume only once
+    // ALL are clear. A single shared boolean let any one source's resume
+    // restart the timer while another source still held it paused (e.g.
+    // pointer leaving a toast into the gap while the region is still
+    // hover-paused).
+    this._pauseSources = new Set()
     this._swipe = { active: false, x: 0, y: 0, startedAt: 0 }
 
     this._onPointerDown = this._onPointerDown.bind(this)
     this._onPointerMove = this._onPointerMove.bind(this)
     this._onPointerUp = this._onPointerUp.bind(this)
-    this._onPointerEnter = () => this._pause()
-    this._onPointerLeave = () => { if (!this._swipe.active) this._resume() }
+    this._onPointerEnter = () => this._pause("hover")
+    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()
-    this._onFocusOut = (e) => { if (!this.element.contains(e.relatedTarget)) this._resume() }
+    this._onFocusIn = () => this._pause("focus")
+    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() }
     this._onRestart = () => this._restart()
-    this._onRegionPause = () => this._pause()
-    this._onRegionResume = () => this._resume()
+    this._onRegionPause = () => this._pause("region")
+    this._onRegionResume = () => this._resume("region")
 
     this.element.addEventListener("pointerdown", this._onPointerDown)
     this.element.addEventListener("pointerenter", this._onPointerEnter)
@@ -52,7 +57,8 @@ export default class extends Controller {
     this._regionList.addEventListener("phlex-kit:toast:pause", this._onRegionPause)
     this._regionList.addEventListener("phlex-kit:toast:resume", this._onRegionResume)
 
-    requestAnimationFrame(() => {
+    this._connectFrame = requestAnimationFrame(() => {
+      this._connectFrame = null
       this.element.dataset.state = "open"
       // Spawned under an already-hovered stack (the toaster stamps
       // data-pk-toasts-paused while dispatching pause): arm as paused so the
@@ -60,7 +66,7 @@ export default class extends Controller {
       // under the user's cursor.
       if (Number.isFinite(this.durationValue) && this.durationValue > 0 &&
           this.element.closest("[data-pk-toasts-paused]")) {
-        this._paused = true
+        this._pauseSources.add("region")
         this._remaining = this.durationValue
       } else {
         this._start()
@@ -70,6 +76,8 @@ export default class extends Controller {
 
   disconnect() {
     this._clearTimer()
+    if (this._connectFrame) cancelAnimationFrame(this._connectFrame)
+    this._connectFrame = null
     // Don't let a pending 200ms unmount fire after teardown (e.g. into a
     // Turbo-cached copy of the page).
     if (this._unmountTimer) clearTimeout(this._unmountTimer)
@@ -115,22 +123,30 @@ export default class extends Controller {
     this._timer = setTimeout(() => this._close("auto"), this._remaining)
   }
 
+  // Resets the timer duration but must respect any pause source still
+  // active (e.g. a promise resolving into a fresh duration while the toast
+  // is hovered) — arm paused instead of ticking away under the cursor, and
+  // leave the source set intact so the matching resume can still fire.
   _restart() {
     this._clearTimer()
+    this._remaining = this.durationValue
+    if (this._pauseSources.size > 0) return
     this._start()
   }
 
-  _pause() {
-    if (this._paused || !this._timer) return
-    this._paused = true
+  _pause(source) {
+    this._pauseSources.add(source)
+    if (!this._timer) return
     clearTimeout(this._timer)
     this._timer = null
     this._remaining -= performance.now() - this._startedAt
   }
 
-  _resume() {
-    if (!this._paused) return
-    this._paused = false
+  _resume(source) {
+    this._pauseSources.delete(source)
+    if (this._pauseSources.size > 0) return
+    if (this._timer) return
+    if (!Number.isFinite(this.durationValue) || this.durationValue <= 0) return
     if (this._remaining <= 0) return this._close("auto")
     this._startedAt = performance.now()
     this._timer = setTimeout(() => this._close("auto"), this._remaining)
@@ -192,7 +208,7 @@ export default class extends Controller {
       this.element.dataset.swipe = "cancel"
       this.element.style.removeProperty("--pk-toast-swipe-x")
       this.element.style.removeProperty("--pk-toast-swipe-y")
-      this._resume()
+      this._resume("hover")
     }
   }
 }

data/app/components/phlex_kit/toast/toast_item.rb

@@ -56,13 +56,17 @@ module PhlexKit
       data[:phlex_kit__toast_on_dismiss_value] = @on_dismiss if @on_dismiss
       data[:phlex_kit__toast_on_auto_close_value] = @on_auto_close if @on_auto_close
 
-      attrs = {
-        role: ALERT_VARIANTS.include?(@variant) ? "alert" : "status",
-        tabindex: "0",
-        class: "pk-toast",
-        aria: { atomic: "true" },
-        data: data
-      }
+      attrs = { class: "pk-toast", data: data }
+      # Defaults only when the caller didn't supply their own — `mix` would
+      # fuse role="status log" / tabindex="0 -1" / aria-atomic="true false"
+      # instead of overriding.
+      unless @attrs.key?(:role) || @attrs.key?("role")
+        attrs[:role] = ALERT_VARIANTS.include?(@variant) ? "alert" : "status"
+      end
+      attrs[:tabindex] = "0" unless @attrs.key?(:tabindex) || @attrs.key?("tabindex")
+      unless aria_key_set?(:atomic)
+        attrs[:aria] = { atomic: "true" }
+      end
       attrs[:id] = @id if @id
       attrs
     end