phlex_kit 0.10.0 → 0.12.0

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(" ")
       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)
@@ -46,10 +51,14 @@ 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)
-
-    requestAnimationFrame(() => {
+    // 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)
+
+    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
@@ -57,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()
@@ -67,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)
@@ -79,8 +90,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) {
@@ -112,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)
@@ -189,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

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
@@ -41,11 +47,23 @@ 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_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
       @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 +123,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 +142,13 @@ 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("+")
         }
       }
+      # 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
 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
@@ -174,6 +172,7 @@ export default class extends Controller {
       )
       return
     }
+    if (!this._listEl) return
     const el = this._listEl.querySelector(`#${CSS.escape(id)}`)
     if (el) el.dispatchEvent(new CustomEvent("phlex-kit:toast:force-dismiss", { bubbles: true }))
   }
@@ -192,7 +191,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 +279,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
@@ -321,6 +330,7 @@ export default class extends Controller {
   }
 
   _mutate(id, variant, text) {
+    if (!this._listEl) return
     const el = this._listEl.querySelector(`#${CSS.escape(id)}`)
     if (!el) return
     el.dataset.variant = variant

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

@@ -21,20 +21,35 @@ module PhlexKit
 
     def view_template(&block)
       div(**mix(group_default_attrs, @attrs)) do
-        yield(self)
+        yield(self) if block
         render_hidden_inputs
       end
     end
 
     def item_context
       { type: @type, variant: @variant, size: @size, disabled: @disabled,
-        selected_values: selected_values, spacing: @spacing, orientation: @orientation }
+        selected_values: selected_values, spacing: @spacing, orientation: @orientation,
+        group: self }
     end
 
     def ToggleGroupItem(**kwargs, &block)
       render PhlexKit::ToggleGroupItem.new(group_context: item_context, **kwargs), &block
     end
 
+    # Roving-tabindex initial stop (single-type, nothing selected): the FIRST
+    # enabled item claims tabindex="0" server-side, mirroring what
+    # toggle_group_controller.js's reconcile() computes at runtime
+    # (`pressed || enabledItems()[0]`). Items call this once each, in render
+    # order, as they're constructed — a single-threaded sequential claim, not
+    # a lookahead over siblings not yet rendered.
+    def claim_tab_stop(item_disabled)
+      return false unless selected_values.empty?
+      return false if item_disabled
+      return false if @tab_stop_claimed
+      @tab_stop_claimed = true
+      true
+    end
+
     private
 
     def selected_values

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

@@ -33,23 +33,30 @@ export default class extends Controller {
     if (items.length === 0) return
     const currentIndex = items.indexOf(event.currentTarget)
     let nextIndex = currentIndex
-    switch (event.key) {
-      case "ArrowRight": case "ArrowDown": nextIndex = (currentIndex + 1) % items.length; break
-      case "ArrowLeft": case "ArrowUp": nextIndex = (currentIndex - 1 + items.length) % items.length; break
-      case "Home": nextIndex = 0; break
-      case "End": nextIndex = items.length - 1; break
-      case " ": case "Enter": event.preventDefault(); event.currentTarget.click(); return
-      default: return
-    }
+    // In RTL the horizontal arrows mirror (physical LEFT = next); Up/Down are
+    // unaffected. Runtime dir check is reliable after a dynamic flip.
+    const rtl = getComputedStyle(this.element).direction === "rtl"
+    const fwd = rtl ? "ArrowLeft" : "ArrowRight"
+    const back = rtl ? "ArrowRight" : "ArrowLeft"
+    if (event.key === fwd || event.key === "ArrowDown") nextIndex = (currentIndex + 1) % items.length
+    else if (event.key === back || event.key === "ArrowUp") nextIndex = (currentIndex - 1 + items.length) % items.length
+    else if (event.key === "Home") nextIndex = 0
+    else if (event.key === "End") nextIndex = items.length - 1
+    else if (event.key === " " || event.key === "Enter") { event.preventDefault(); event.currentTarget.click(); return }
+    else return
     event.preventDefault()
     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,13 +1,27 @@
 module PhlexKit
   class ToggleGroupItem < Toggle
     def initialize(value:, group_context:, variant: nil, size: nil, **attrs)
+      # Toggle kwargs this item renders no markup for, or that the group
+      # derives itself (pressed: comes from the group's selected_values) —
+      # inheriting them silently discarded the caller's input.
+      unsupported = attrs.keys & %i[wrapper name unpressed_value pressed]
+      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)
+      item_disabled = attrs.key?(:disabled) ? attrs.delete(:disabled) : group_context[:disabled]
+      # Roving tabindex initial stop: when nothing is selected yet, the first
+      # enabled item claims tabindex="0" (see ToggleGroup#claim_tab_stop).
+      # group_context[:group] is nil for a hand-built context (bypassing
+      # ToggleGroup#item_context) — treat that as "no tab-stop claim" rather
+      # than raising, since standalone tests construct contexts by hand.
+      @is_first_tab_stop = group_context[:group]&.claim_tab_stop(item_disabled) || false
       super(pressed: pressed, name: nil, value: @item_value,
             variant: variant || group_context[:variant],
             size: size || group_context[:size],
-            disabled: group_context[:disabled], **attrs)
+            disabled: item_disabled, **attrs)
     end
 
     def view_template(&block)
@@ -26,7 +40,11 @@ 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.
+        # When nothing is selected, the first enabled item claims the initial
+        # roving-tabindex stop instead of every item defaulting to -1.
+        a[:tabindex] = (@pressed && !@disabled) || @is_first_tab_stop ? "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) => {

data/app/components/phlex_kit/typography/heading.rb

@@ -8,6 +8,9 @@ module PhlexKit
     # ruby_ui's level → default size mapping (h1 is big, h4 smaller); 5/6
     # extend the scale downward — HTML has h1–h6, so all six must map.
     LEVEL_SIZE = { "1" => "7", "2" => "6", "3" => "5", "4" => "4", "5" => "3", "6" => "2" }.freeze
+    # `as:` is dispatched dynamically (send) — whitelist so it can't reach
+    # arbitrary (including private) methods. Mirrors Separator/Marker.
+    AS_TAGS = %i[h1 h2 h3 h4 h5 h6 p span div].freeze
 
     # level: defaults to 1 so `Heading.new` is identical to `Heading.new(level: 1)`
     # (a nil default used to render h1 with the level-6 size — self-disagreeing).
@@ -18,7 +21,10 @@ module PhlexKit
         raise ArgumentError, "Invalid heading level: #{level.inspect} — valid: 1–6"
       end
       @level = level
-      @as = as
+      @as = as&.to_sym
+      if @as && !AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown Heading as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @size = size
       @attrs = attrs
     end

data/app/components/phlex_kit/typography/list.rb

@@ -0,0 +1,22 @@
+module PhlexKit
+  # Prose list, ported from shadcn/ui's typography "list" style (ruby_ui's
+  # TypographyList). Renders a ul (or ol via as:) with the .pk-list styling
+  # that previously shipped as an orphaned utility class. Children are plain
+  # <li>s.
+  class List < BaseComponent
+    # `as:` is dispatched dynamically (send) — whitelist like Separator.
+    AS_TAGS = %i[ul ol].freeze
+
+    def initialize(as: :ul, **attrs)
+      @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown List as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      send(@as, **mix({ class: "pk-list" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/typography/text.rb

@@ -27,9 +27,15 @@ module PhlexKit
       bold: "pk-text-bold",
       muted: "pk-text-muted"
     }.freeze
+    # `as:` is dispatched dynamically (send) — whitelist so it can't reach
+    # arbitrary (including private) methods. Mirrors Separator/Marker.
+    AS_TAGS = %i[p span div label small strong em].freeze
 
     def initialize(as: :p, size: "3", weight: :regular, **attrs)
-      @as = as
+      @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown Text as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @size = size.to_s
       @weight = weight.to_sym
       @attrs = attrs