phlex_kit 0.10.0 → 0.11.0

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

@@ -36,6 +36,9 @@ export default class extends Controller {
     const next = handle.nextElementSibling
     if (!prev || !next) return
     e.preventDefault()
+    // preventDefault suppresses mouse-driven focus — hand it to the handle
+    // so a drag can be fine-tuned with the arrow keys immediately.
+    handle.focus({ preventScroll: true })
 
     const horizontal = this.directionValue === "horizontal"
     const sizeOf = (el) => horizontal ? el.getBoundingClientRect().width : el.getBoundingClientRect().height

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

@@ -12,8 +12,11 @@ module PhlexKit
     end
 
     def view_template(&)
-      base = { class: "pk-scroll-area", tabindex: "0" }
-      base[:role] = "region" if labelled?
+      # 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")
       div(**mix(base, @attrs), &)
     end
 

data/app/components/phlex_kit/select/select.css

@@ -23,7 +23,8 @@
   border-radius: var(--pk-radius);
   border: 1px solid var(--pk-input);
   color: var(--pk-text);
-  padding: .25rem .5rem .25rem .625rem;
+  padding-block: .25rem;
+  padding-inline: .625rem .5rem;
   gap: .375rem;
   font: inherit;
   font-size: .875rem;
@@ -87,7 +88,9 @@
   user-select: none;
   gap: .375rem;
   border-radius: calc(var(--pk-radius) - 2px);
-  padding: .25rem 2rem .25rem .375rem;
+  /* 2rem gutter on the inline-end — where .pk-select-item-check sits. */
+  padding-block: .25rem;
+  padding-inline: .375rem 2rem;
   font-size: .875rem;
   color: var(--pk-text);
   outline: none;

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

@@ -9,7 +9,28 @@ export default class extends Controller {
   static targets = ["trigger", "content", "input", "value", "item"];
   static values = { open: Boolean };
 
+  initialize() {
+    // Stimulus fires [target]Connected before connect(): state used by
+    // itemTargetConnected must be initialized here.
+    this.itemIdCounter = 0;
+  }
+
+  // Per-item, not a connect()-time sweep: options injected later (Turbo
+  // stream/frame) must still get ids or aria-activedescendant would point
+  // at nothing — and a caller-provided id is left alone, not clobbered.
+  itemTargetConnected(item) {
+    if (!item.id) item.id = `${this.contentTarget.id}-${this.itemIdCounter++}`;
+  }
+
   connect() {
+    // A Turbo snapshot serializes aria-expanded / aria-activedescendant /
+    // aria-current even though :popover-open does not survive the restore —
+    // normalize here so a restored page doesn't announce an open listbox
+    // over a closed select (same mitigation as dropdown_menu's connect).
+    this.openValue = false;
+    this.triggerTarget.setAttribute("aria-expanded", "false");
+    this.triggerTarget.removeAttribute("aria-activedescendant");
+    this.itemTargets.forEach((item) => item.removeAttribute("aria-current"));
     this.generateItemsIds();
   }
 
@@ -176,10 +197,12 @@ export default class extends Controller {
   generateItemsIds() {
     const contentId = this.contentTarget.getAttribute("id");
     this.triggerTarget.setAttribute("aria-controls", contentId);
-
-    this.itemTargets.forEach((item, index) => {
-      item.id = `${contentId}-${index}`;
-    });
+    // Name the listbox from the trigger (Radix wires it the same way) —
+    // an unnamed role=listbox is announced as an anonymous list.
+    if (!this.triggerTarget.id) this.triggerTarget.id = `${contentId}-trigger`;
+    if (!this.contentTarget.hasAttribute("aria-labelledby")) {
+      this.contentTarget.setAttribute("aria-labelledby", this.triggerTarget.id);
+    }
   }
 
   setAriaCurrentAndActiveDescendant(currentIndex) {

data/app/components/phlex_kit/separator/separator.rb

@@ -24,7 +24,11 @@ module PhlexKit
     end
 
     def view_template(&block)
-      send(@as, **mix({ role: (@decorative ? "none" : "separator"), class: classes }, @attrs), &block)
+      base = { role: (@decorative ? "none" : "separator"), class: classes }
+      # role="separator" is implicitly horizontal — a semantic vertical one
+      # must say so or AT announces the wrong axis.
+      base[:"aria-orientation"] = "vertical" if !@decorative && @orientation == :vertical
+      send(@as, **mix(base, @attrs), &block)
     end
 
     private

data/app/components/phlex_kit/sheet/sheet.css

@@ -16,8 +16,10 @@
 }
 .pk-sheet-content.right { inset-block: 0; right: 0; height: 100%; width: 75%; max-width: 24rem; border-left: 1px solid var(--pk-border); }
 .pk-sheet-content.left  { inset-block: 0; left: 0;  height: 100%; width: 75%; max-width: 24rem; border-right: 1px solid var(--pk-border); }
-.pk-sheet-content.top    { inset-inline: 0; top: 0;    border-bottom: 1px solid var(--pk-border); }
-.pk-sheet-content.bottom { inset-inline: 0; bottom: 0; border-top: 1px solid var(--pk-border); }
+/* max-height: without it a tall top/bottom panel grows past the viewport and
+   overflow:auto never engages (footer/close unreachable). */
+.pk-sheet-content.top    { inset-inline: 0; top: 0;    max-height: 100dvh; border-bottom: 1px solid var(--pk-border); }
+.pk-sheet-content.bottom { inset-inline: 0; bottom: 0; max-height: 100dvh; border-top: 1px solid var(--pk-border); }
 .pk-sheet-header { display: flex; flex-direction: column; gap: .125rem; padding: 1rem; }
 .pk-sheet-footer { display: flex; flex-direction: column-reverse; gap: .5rem; padding: 1rem; margin-top: auto; }
 .pk-sheet-title { font-size: 1rem; font-weight: 500; line-height: 1; color: var(--pk-text); }

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

@@ -29,6 +29,10 @@ export default class extends Controller {
     this.#restoreInert()
     document.body.style.overflow = this.previousOverflow
     if (this.opener?.isConnected) this.opener.focus()
+    // Tell the source phlex-kit--sheet controller the clone is gone so it
+    // can flip the trigger's aria-expanded back (removal happens by many
+    // paths: close button, Escape, backdrop, before-cache).
+    document.dispatchEvent(new CustomEvent("phlex-kit:sheet-content:closed"))
   }
 
   close() {

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

@@ -19,17 +19,32 @@ export default class extends Controller {
 
   connect() {
     document.addEventListener("turbo:before-cache", this.clearOverlay)
+    // 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]")
+    this.invoker?.setAttribute("aria-haspopup", "dialog")
+    this.invoker?.setAttribute("aria-expanded", "false")
+    this.onOverlayClosed = () => {
+      if (!this.overlay?.isConnected) this.invoker?.setAttribute("aria-expanded", "false")
+    }
+    document.addEventListener("phlex-kit:sheet-content:closed", this.onOverlayClosed)
     if (this.openValue) this.open()
   }
 
   disconnect() {
     document.removeEventListener("turbo:before-cache", this.clearOverlay)
+    document.removeEventListener("phlex-kit:sheet-content:closed", this.onOverlayClosed)
     this.clearOverlay()
   }
 
   open() {
     if (this.overlay?.isConnected) return
+    // open: is one-shot — the reflected value sits in the Turbo snapshot, so
+    // a cache-restored reconnect would re-open a dismissed sheet.
+    this.openValue = false
     document.body.insertAdjacentHTML("beforeend", this.contentTarget.innerHTML)
     this.overlay = document.body.lastElementChild
+    this.invoker?.setAttribute("aria-expanded", "true")
   }
 }

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

@@ -11,8 +11,16 @@ module PhlexKit
   # untouched — keep the label in a real element there. Attrs pass through via
   # mix. See sidebar.rb.
   class SidebarMenuButton < BaseComponent
+    # `as:` is dispatched dynamically (send) — whitelist so it can't reach
+    # arbitrary (including private) methods; to_sym so a String "a" still
+    # earns aria-current when active.
+    AS_TAGS = %i[button a].freeze
+
     def initialize(as: :button, active: false, tooltip: nil, **attrs)
-      @as = as
+      @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown SidebarMenuButton as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @active = active
       @tooltip = tooltip
       @attrs = attrs

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

@@ -5,8 +5,15 @@ module PhlexKit
   # primary). Kwarg rather than attr for the same mix-merge reason as
   # SidebarMenuButton. See sidebar.rb.
   class SidebarMenuSubButton < BaseComponent
+    # `as:` is dispatched dynamically (send) — whitelist, matching
+    # SidebarMenuButton.
+    AS_TAGS = %i[a button].freeze
+
     def initialize(as: :a, active: false, **attrs)
-      @as = as
+      @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown SidebarMenuSubButton as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @active = active
       @attrs = attrs
     end

data/app/components/phlex_kit/slider/slider.css

@@ -18,6 +18,15 @@
     var(--pk-brand) var(--pk-slider-progress, 50%),
     var(--pk-surface-2) var(--pk-slider-progress, 50%));
 }
+/* Chrome mirrors the native range input in RTL but the gradient stays
+   physical — repaint the fill from the right. (:dir() reads document
+   directionality, so .vertical's internal `direction: rtl` flip below
+   doesn't match; its own `to top` gradient also comes later and wins.) */
+.pk-slider:dir(rtl)::-webkit-slider-runnable-track {
+  background: linear-gradient(to left,
+    var(--pk-brand) var(--pk-slider-progress, 50%),
+    var(--pk-surface-2) var(--pk-slider-progress, 50%));
+}
 .pk-slider::-webkit-slider-thumb {
   -webkit-appearance: none;
   width: .75rem;
@@ -57,6 +66,12 @@
 .pk-slider:active::-moz-range-thumb {
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
+/* line 13 strips the native outline in every browser — without this arm the
+   replacement ring only existed on the -webkit thumb and Firefox keyboard
+   focus was invisible. */
+.pk-slider:focus-visible::-moz-range-thumb {
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
+}
 .pk-slider:disabled { opacity: .5; cursor: not-allowed; }
 /* Vertical: modern writing-mode flip (min-h-40 like theirs). */
 .pk-slider.vertical {

data/app/components/phlex_kit/switch/switch.css

@@ -49,6 +49,11 @@
   transform: translateX(calc(100% - 2px));
   background: var(--pk-brand-ink);
 }
+/* RTL: the resting thumb sits at the physical right — checked travel must
+   slide it left or it leaves the track. */
+.pk-switch:dir(rtl):has(.pk-switch-input:checked) .pk-switch-thumb {
+  transform: translateX(calc(-100% + 2px));
+}
 :root[data-theme="light"] .pk-switch { background: var(--pk-input); }
 :root[data-theme="light"] .pk-switch:has(.pk-switch-input:checked) { background: var(--pk-brand); }
 :root[data-theme="light"] .pk-switch-thumb { background: var(--pk-bg) !important; }

data/app/components/phlex_kit/table/table.css

@@ -5,9 +5,10 @@
 .pk-table-wrapper { position: relative; width: 100%; overflow: auto; }
 .pk-table { width: 100%; border-collapse: collapse; caption-side: bottom; font-size: .875rem; }
 
-.pk-table-header .pk-table-row { border-bottom: 1px solid var(--pk-border); }
 .pk-table-body .pk-table-row:last-child { border-bottom: 0; }
 .pk-table-footer { border-top: 1px solid var(--pk-border); font-weight: 500; background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent); }
+/* shadcn parity: the totals row doesn't draw a stray line under the table. */
+.pk-table-footer .pk-table-row:last-child { border-bottom: 0; }
 
 .pk-table-row { border-bottom: 1px solid var(--pk-border); transition: background-color .12s ease; }
 .pk-table-row:hover { background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent); }

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

@@ -22,12 +22,15 @@ module PhlexKit
   #
   # Tailwind → vanilla `.pk-table-*` (table.css), palette from the global tokens.
   class Table < BaseComponent
-    def initialize(**attrs)
+    def initialize(wrapper: {}, **attrs)
+      @wrapper = wrapper
       @attrs = attrs
     end
 
     def view_template(&block)
-      div(class: "pk-table-wrapper") do
+      # Caller attrs land on the <table>; wrapper: reaches the scroll
+      # container (e.g. to cap its height) — same escape hatch as Switch.
+      div(**mix({ class: "pk-table-wrapper" }, @wrapper)) do
         table(**mix({ class: "pk-table" }, @attrs), &block)
       end
     end

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

@@ -1,8 +1,10 @@
 module PhlexKit
   class TabsContent < BaseComponent
-    def initialize(value:, active: false, **attrs)
+    # id: is a named kwarg (not left in **attrs) — see TabsTrigger.
+    def initialize(value:, active: false, id: nil, **attrs)
       @value = value
       @active = active
+      @id = id || "pk-tabs-panel-#{value}"
       @attrs = attrs
     end
     def view_template(&)
@@ -11,7 +13,7 @@ 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: "pk-tabs-panel-#{@value}", aria_labelledby: "pk-tabs-trigger-#{@value}", tabindex: "0", data: { phlex_kit__tabs_target: "content", value: @value } }, @attrs), &)
+      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), &)
     end
   end
 end

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

@@ -2,14 +2,19 @@ module PhlexKit
   class TabsList < BaseComponent
     VARIANTS = { default: nil, line: "line" }.freeze
 
-    def initialize(variant: :default, **attrs)
+    def initialize(variant: :default, orientation: :horizontal, **attrs)
       @variant = variant.to_sym
+      @orientation = orientation.to_sym
       @attrs = attrs
     end
 
     def view_template(&)
       classes = [ "pk-tabs-list", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" ")
-      div(**mix({ class: classes, role: "tablist", data: { phlex_kit__tabs_target: "list", action: "keydown->phlex-kit--tabs#keydown" } }, @attrs), &)
+      base = { class: classes, role: "tablist", data: { phlex_kit__tabs_target: "list", action: "keydown->phlex-kit--tabs#keydown" } }
+      # Server-rendered so AT hears the right axis pre-JS / with JS off; the
+      # controller re-stamps it on connect from the root's vertical class.
+      base[:aria] = { orientation: "vertical" } if @orientation == :vertical
+      div(**mix(base, @attrs), &)
     end
   end
 end

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

@@ -1,9 +1,18 @@
 module PhlexKit
   class TabsTrigger < BaseComponent
-    def initialize(value:, as: :button, active: false, **attrs)
+    # id: is a named kwarg (not left in **attrs) because `mix` would *merge* a
+    # caller id with the deterministic one into an invalid two-token id,
+    # breaking the aria pairing pre-JS (and scopeIds' caller-id detection).
+    AS_TAGS = %i[button a].freeze
+
+    def initialize(value:, as: :button, active: false, id: nil, **attrs)
       @value = value
       @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown TabsTrigger as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @active = active
+      @id = id || "pk-tabs-trigger-#{value}"
       @attrs = attrs
     end
     def view_template(&)
@@ -13,7 +22,7 @@ module PhlexKit
       # aria-selected and the roving tabindex are kept in sync by the
       # controller's activeValueChanged.
       base = {
-        class: "pk-tabs-trigger", role: "tab", id: "pk-tabs-trigger-#{@value}",
+        class: "pk-tabs-trigger", role: "tab", id: @id,
         aria_selected: @active ? "true" : "false",
         aria_controls: "pk-tabs-panel-#{@value}",
         tabindex: @active ? "0" : "-1",

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

@@ -18,11 +18,25 @@ export default class extends Controller {
       if (!this.storedTheme()) this.applyTheme("system")
     }
     this._media.addEventListener("change", this._onMediaChange)
+    // Multiple toggles on one page (header + mobile menu): each instance
+    // observes :root[data-theme] so a change applied by ANY of them (or by
+    // host code) re-syncs every toggle's pressed state — without this the
+    // stale one showed the wrong state and its first click was eaten by the
+    // echo guard in apply().
+    this._rootObserver = new MutationObserver(() => this.syncPressed())
+    this._rootObserver.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] })
     this.applyTheme(this.storedTheme() || "system")
   }
 
   disconnect() {
     this._media?.removeEventListener("change", this._onMediaChange)
+    this._rootObserver?.disconnect()
+  }
+
+  syncPressed() {
+    const theme = document.documentElement.getAttribute("data-theme") || "system"
+    const dark = theme === "system" ? this._media.matches : theme === "dark"
+    this.element.setAttribute("data-phlex-kit--toggle-pressed-value", dark ? "true" : "false")
   }
 
   apply(e) {

data/app/components/phlex_kit/toast/toast.css

@@ -7,7 +7,8 @@
 .pk-toast-region {
   position: fixed;
   z-index: 100;
-  padding: 1.5rem;
+  /* --pk-toast-offset is stamped inline by ToastRegion(offset:). */
+  padding: var(--pk-toast-offset, 1.5rem);
   pointer-events: none;
 }
 .pk-toast-region[data-position="top-left"] { top: 0; left: 0; }

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

@@ -12,7 +12,10 @@ module PhlexKit
 
     def view_template
       data = { slot: "action" }
-      data[:action] = @on if @on
+      # 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
       button(**mix({ type: :button, class: "pk-toast-action", data: data }, @attrs)) { @label }
     end
   end

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

@@ -46,8 +46,11 @@ export default class extends Controller {
     this.element.addEventListener("keydown", this._onKeyDown)
     this.element.addEventListener("phlex-kit:toast:force-dismiss", this._onForceDismiss)
     this.element.addEventListener("phlex-kit:toast:restart", this._onRestart)
-    document.addEventListener("phlex-kit:toast:pause", this._onRegionPause)
-    document.addEventListener("phlex-kit:toast:resume", this._onRegionResume)
+    // Region-scoped: the toaster dispatches pause/resume on its own list, so
+    // another region's hover can't freeze (or resume) this toast's timer.
+    this._regionList = this.element.closest(".pk-toast-list") || document
+    this._regionList.addEventListener("phlex-kit:toast:pause", this._onRegionPause)
+    this._regionList.addEventListener("phlex-kit:toast:resume", this._onRegionResume)
 
     requestAnimationFrame(() => {
       this.element.dataset.state = "open"
@@ -79,8 +82,8 @@ export default class extends Controller {
     this.element.removeEventListener("keydown", this._onKeyDown)
     this.element.removeEventListener("phlex-kit:toast:force-dismiss", this._onForceDismiss)
     this.element.removeEventListener("phlex-kit:toast:restart", this._onRestart)
-    document.removeEventListener("phlex-kit:toast:pause", this._onRegionPause)
-    document.removeEventListener("phlex-kit:toast:resume", this._onRegionResume)
+    this._regionList?.removeEventListener("phlex-kit:toast:pause", this._onRegionPause)
+    this._regionList?.removeEventListener("phlex-kit:toast:resume", this._onRegionResume)
   }
 
   dismiss(e) {

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

@@ -41,11 +41,22 @@ module PhlexKit
       @duration = duration
       @gap = gap
       @offset = offset
+      # theme:/rich_colors: are Sonner API surface the kit deliberately does
+      # not implement (tokens are :root-scoped; there is no status palette) —
+      # fail loud rather than silently no-op (audit round 6).
       @theme = theme.to_sym
-      @rich_colors = rich_colors
+      unless @theme == :system
+        raise ArgumentError, "ToastRegion theme: only :system is supported — toasts follow the page theme (:root[data-theme])"
+      end
+      if rich_colors
+        raise ArgumentError, "ToastRegion rich_colors: is not supported — the kit has no status color palette (toasts follow --pk-* tokens)"
+      end
       @close_button = close_button
       @hotkey = hotkey
-      @dir = dir
+      @dir = dir.to_sym
+      unless %i[ltr rtl auto].include?(@dir)
+        raise ArgumentError, "ToastRegion dir: must be :ltr, :rtl or :auto"
+      end
       @flash = flash
       # Base id for the <ol> stack; the wrapper takes "#{id}-region". Defaults
       # keep the historical "pk-toaster"/"pk-toaster-region" pair — pass a
@@ -105,10 +116,12 @@ module PhlexKit
     end
 
     def region_attrs
-      {
+      base = {
         id: "#{@id}-region",
         role: "region",
         class: "pk-toast-region",
+        # offset: viewport-edge padding, consumed by toast.css.
+        style: "--pk-toast-offset: #{@offset.is_a?(Numeric) ? "#{@offset}px" : @offset};",
         # No aria-live here: each toast item is its own live region
         # (role="status"/"alert"); a live wrapper would double-announce.
         aria: { label: "Notifications" },
@@ -122,14 +135,11 @@ module PhlexKit
           phlex_kit__toaster_max_value: @max.to_s,
           phlex_kit__toaster_duration_value: @duration.to_s,
           phlex_kit__toaster_gap_value: @gap.to_s,
-          phlex_kit__toaster_offset_value: @offset.to_s,
-          phlex_kit__toaster_theme_value: @theme.to_s,
-          phlex_kit__toaster_rich_colors_value: @rich_colors.to_s,
-          phlex_kit__toaster_close_button_value: @close_button.to_s,
-          phlex_kit__toaster_hotkey_value: Array(@hotkey).join("+"),
-          phlex_kit__toaster_dir_value: @dir.to_s
+          phlex_kit__toaster_hotkey_value: Array(@hotkey).join("+")
         }
       }
+      base[:dir] = @dir.to_s unless @dir == :ltr
+      base
     end
   end
 end

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

@@ -34,12 +34,10 @@ export default class extends Controller {
     max: { type: Number, default: 3 },
     duration: { type: Number, default: 4000 },
     gap: { type: Number, default: 14 },
-    offset: { type: Number, default: 24 },
-    theme: { type: String, default: "system" },
-    richColors: { type: Boolean, default: false },
-    closeButton: { type: Boolean, default: false },
+    // offset is a CSS custom property (--pk-toast-offset) and dir a real
+    // dir attribute, both stamped by ToastRegion; theme/richColors are
+    // unsupported (region raises) — none of them are controller state.
     hotkey: { type: String, default: "alt+t" },
-    dir: { type: String, default: "ltr" },
   }
 
   // State the target callbacks touch lives here, NOT in connect(): Stimulus
@@ -192,7 +190,10 @@ export default class extends Controller {
     // Mirror the pause state onto the DOM so toasts spawned while the stack
     // is already hovered can arm paused (the pause event predates them).
     this._listEl?.toggleAttribute("data-pk-toasts-paused", value)
-    document.dispatchEvent(new CustomEvent(value ? "phlex-kit:toast:pause" : "phlex-kit:toast:resume"))
+    // Region-scoped, not document-global: on multi-region pages one region's
+    // hover must not pause (or worse, RESUME under the pointer) another's
+    // toasts. Toasts listen on their own list element.
+    this._listEl.dispatchEvent(new CustomEvent(value ? "phlex-kit:toast:pause" : "phlex-kit:toast:resume"))
   }
 
   _setExpanded(value) {
@@ -277,7 +278,14 @@ export default class extends Controller {
     const wantCtrl = parts.includes("ctrl")
     const wantMeta = parts.includes("meta")
     const wantShift = parts.includes("shift")
-    if (e.key.toLowerCase() !== key.toLowerCase()) return
+    // Match e.code as well as e.key: with Option held, macOS reports the
+    // COMPOSED character (Option+T → "†"), so alt+ hotkeys never match on
+    // e.key alone (Sonner matches event.code for the same reason).
+    const code = (e.code || "").toLowerCase()
+    const keyMatches = e.key.toLowerCase() === key.toLowerCase()
+      || code === `key${key.toLowerCase()}`
+      || code === `digit${key.toLowerCase()}`
+    if (!keyMatches) return
     if (wantAlt !== e.altKey) return
     if (wantCtrl !== e.ctrlKey) return
     if (wantMeta !== e.metaKey) return

data/app/components/phlex_kit/toggle_group/toggle_group.rb

@@ -21,7 +21,7 @@ module PhlexKit
 
     def view_template(&block)
       div(**mix(group_default_attrs, @attrs)) do
-        yield(self)
+        yield(self) if block
         render_hidden_inputs
       end
     end

data/app/components/phlex_kit/toggle_group/toggle_group_controller.js

@@ -45,11 +45,15 @@ export default class extends Controller {
     const next = items[nextIndex]
     this.updateRovingTabindex(next)
     next.focus()
+    // APG radio-group keyboard model: with role="radio", arrows move focus
+    // AND check the landed-on item (Home/End included).
+    if (next !== event.currentTarget) next.click()
   }
 
   reconcile() {
     if (this.typeValue === "single") {
-      const pressed = this.itemTargets.find((el) => this.isPressed(el))
+      // A disabled button can't take focus — never hand it the tab stop.
+      const pressed = this.itemTargets.find((el) => this.isPressed(el) && !el.disabled)
       const first = pressed || this.enabledItems()[0]
       this.itemTargets.forEach((el) => el.setAttribute("tabindex", el === first ? "0" : "-1"))
     } else {

data/app/components/phlex_kit/toggle_group/toggle_group_item.rb

@@ -1,6 +1,12 @@
 module PhlexKit
   class ToggleGroupItem < Toggle
     def initialize(value:, group_context:, variant: nil, size: nil, **attrs)
+      # Toggle kwargs this item renders no markup for — inheriting them
+      # silently discarded the caller's input.
+      unsupported = attrs.keys & %i[wrapper name unpressed_value]
+      if unsupported.any?
+        raise ArgumentError, "ToggleGroupItem does not support #{unsupported.join(", ")} (group items render a bare button)"
+      end
       @item_value = value.to_s
       @group_context = group_context
       pressed = group_context[:selected_values].include?(@item_value)
@@ -26,7 +32,9 @@ module PhlexKit
       if @group_context[:type] == :single
         a[:role] = "radio"
         a[:aria] = { checked: @pressed.to_s }
-        a[:tabindex] = @pressed ? "0" : "-1"
+        # A disabled button can't take focus — giving the tab stop to a
+        # pressed-but-disabled item made the whole group Tab-unreachable.
+        a[:tabindex] = (@pressed && !@disabled) ? "0" : "-1"
       else
         a[:aria] = { pressed: @pressed.to_s }
         a[:tabindex] = "0"

data/app/components/phlex_kit/tooltip/tooltip.css

@@ -79,6 +79,9 @@
   .pk-tooltip:hover .pk-tooltip-content {
     opacity: 1;
     visibility: visible;
+    /* WCAG 1.4.13 Hoverable: the revealed bubble must accept the pointer —
+       it's a DOM child of .pk-tooltip, so hovering it keeps the reveal. */
+    pointer-events: auto;
     transition-delay: .4s, .4s;
   }
 }
@@ -87,9 +90,10 @@
 .pk-tooltip:has(:focus-visible) .pk-tooltip-content {
   opacity: 1;
   visibility: visible;
+  pointer-events: auto;
   transition-delay: 0s, 0s;
 }
 /* Escape-dismissed (WCAG 1.4.13): suppressed until pointer/focus leaves.
    transition: none so the hide is immediate regardless of hover-in delays. */
 .pk-tooltip[data-pk-dismissed]:hover .pk-tooltip-content,
-.pk-tooltip[data-pk-dismissed]:focus-within .pk-tooltip-content { opacity: 0; visibility: hidden; transition: none; }
+.pk-tooltip[data-pk-dismissed]:focus-within .pk-tooltip-content { opacity: 0; visibility: hidden; pointer-events: none; transition: none; }

data/app/components/phlex_kit/tooltip/tooltip_controller.js

@@ -11,7 +11,13 @@ export default class extends Controller {
     const trigger = this.element.querySelector(".pk-tooltip-trigger")
     if (content && trigger) {
       if (!content.id) content.id = `pk-tooltip-${Math.random().toString(36).slice(2, 8)}`
-      if (!trigger.hasAttribute("aria-describedby")) trigger.setAttribute("aria-describedby", content.id)
+      // Describe the element that actually takes focus: with focusable: false
+      // the wrapper span never receives focus, so a describedby left only on
+      // it is never announced — wire the focusable child too.
+      const focusable = trigger.querySelector("button, a[href], input, select, textarea, [tabindex]")
+      ;[trigger, focusable].forEach((el) => {
+        if (el && !el.hasAttribute("aria-describedby")) el.setAttribute("aria-describedby", content.id)
+      })
     }
 
     this._onKeydown = (e) => {