phlex_kit 0.11.0 → 0.13.0

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

@@ -23,3 +23,22 @@
 .pk-progress:dir(rtl) .pk-progress-indicator {
   transform: translateX(calc((100 - var(--pk-progress-value, 0)) * 1%));
 }
+
+/* Indeterminate (value: nil): a 40%-wide segment sweeps the track.
+   translateX % is relative to the segment's own width: -100% parks it just
+   off the track's start edge, +250% (track = 250% of segment) just past the
+   end. Direction-agnostic — the sweep reads fine mirrored, no RTL arm. */
+.pk-progress.indeterminate .pk-progress-indicator {
+  width: 40%;
+  transition: none;
+  animation: pk-progress-indeterminate 1.5s ease-in-out infinite;
+}
+@keyframes pk-progress-indeterminate {
+  from { transform: translateX(-100%); }
+  to { transform: translateX(250%); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .pk-progress.indeterminate .pk-progress-indicator {
+    animation-duration: 3s;
+  }
+}

data/app/components/phlex_kit/progress/progress.rb

@@ -6,29 +6,45 @@ module PhlexKit
   class Progress < BaseComponent
     # value_text: is a named kwarg (not read from **attrs) because `mix`
     # would *fuse* a caller "aria-valuetext" with the generated default.
+    # `value: nil` renders the INDETERMINATE state (Radix parity): a sliding
+    # animation, data-state="indeterminate", and no aria-valuenow — which is
+    # exactly how ARIA marks a progressbar of unknown value.
     def initialize(value: 0, value_text: nil, **attrs)
-      @value = value.to_f.clamp(0.0, 100.0)
+      @value = value.nil? ? nil : value.to_f.clamp(0.0, 100.0)
       @value_text = value_text
       @attrs = attrs
     end
 
     def view_template
-      # %g drops float artifacts ("40.0" would be announced as "forty point
-      # zero percent"). The value travels as a custom property so the fill
-      # transform lives in progress.css, where a :dir(rtl) arm can flip it —
-      # an inline translateX always filled from the physical left.
-      v = Kernel.format("%g", @value)
-      div(**mix({
+      div(**mix(root_attrs, @attrs)) do
+        div(class: "pk-progress-indicator")
+      end
+    end
+
+    private
+
+    def root_attrs
+      base = {
         role: "progressbar",
-        "aria-valuenow": v,
         "aria-valuemin": 0,
         "aria-valuemax": 100,
-        "aria-valuetext": @value_text || "#{v}%",
-        class: "pk-progress",
-        style: "--pk-progress-value: #{v};"
-      }, @attrs)) do
-        div(class: "pk-progress-indicator")
+        class: "pk-progress"
+      }
+      if @value.nil?
+        base[:class] = "pk-progress indeterminate"
+        base[:data] = { state: "indeterminate" }
+        base[:"aria-valuetext"] = @value_text if @value_text
+      else
+        # %g drops float artifacts ("40.0" would be announced as "forty point
+        # zero percent"). The value travels as a custom property so the fill
+        # transform lives in progress.css, where a :dir(rtl) arm can flip it —
+        # an inline translateX always filled from the physical left.
+        v = Kernel.format("%g", @value)
+        base[:"aria-valuenow"] = v
+        base[:"aria-valuetext"] = @value_text || "#{v}%"
+        base[:style] = "--pk-progress-value: #{v};"
       end
+      base
     end
   end
 end

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

@@ -15,22 +15,9 @@ module PhlexKit
       # Defaults only when the caller didn't supply their own — `mix` would
       # 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[:tabindex] = "0" unless attr_set?(:tabindex)
+      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 attr_set?(:role)
+          panel_attrs[:aria] = { modal: "true" } unless aria_key_set?(:modal)
+          panel_attrs[:tabindex] = "-1" unless attr_set?(: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) || 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,12 @@ 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()
+      // pointerleave is suppressed while a swipe is active, so release the
+      // hover hold here — but only if the pointer actually left the toast; a
+      // cancelled swipe ending under the cursor must stay hover-paused (the
+      // eventual pointerleave resumes it, including the touch case where
+      // pointerleave fires right after pointerup).
+      if (!this.element.matches(":hover")) 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 attr_set?(:role)
+        attrs[:role] = ALERT_VARIANTS.include?(@variant) ? "alert" : "status"
+      end
+      attrs[:tabindex] = "0" unless attr_set?(:tabindex)
+      unless aria_key_set?(:atomic)
+        attrs[:aria] = { atomic: "true" }
+      end
       attrs[:id] = @id if @id
       attrs
     end

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

@@ -10,6 +10,12 @@ module PhlexKit
   class ToastRegion < BaseComponent
     SKELETON_VARIANTS = %i[default success error warning info loading].freeze
 
+    # Sentinel default for dir: — distinguishes "caller didn't pass dir:" (omit
+    # the attribute, inherit from the page) from an explicit dir: :ltr (must
+    # render dir="ltr"), which a plain `:ltr` default can't tell apart.
+    DIR_UNSET = Object.new.freeze
+    private_constant :DIR_UNSET
+
     POSITIONS = {
       top_left: "top-left",
       top_center: "top-center",
@@ -30,7 +36,7 @@ module PhlexKit
       rich_colors: false,
       close_button: false,
       hotkey: %w[alt t],
-      dir: :ltr,
+      dir: DIR_UNSET,
       flash: nil,
       id: "pk-toaster",
       **attrs
@@ -53,7 +59,8 @@ module PhlexKit
       end
       @close_button = close_button
       @hotkey = hotkey
-      @dir = dir.to_sym
+      @dir_explicit = !dir.equal?(DIR_UNSET)
+      @dir = (@dir_explicit ? dir : :ltr).to_sym
       unless %i[ltr rtl auto].include?(@dir)
         raise ArgumentError, "ToastRegion dir: must be :ltr, :rtl or :auto"
       end
@@ -138,7 +145,9 @@ module PhlexKit
           phlex_kit__toaster_hotkey_value: Array(@hotkey).join("+")
         }
       }
-      base[:dir] = @dir.to_s unless @dir == :ltr
+      # Only an explicit dir: renders the attribute — the true default (no
+      # dir: passed) omits it so the toast inherits the page's direction.
+      base[:dir] = @dir.to_s if @dir_explicit
       base
     end
   end