phlex_kit 0.10.0 → 0.12.0

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

@@ -17,14 +17,23 @@ export default class extends Controller {
     if (invoker) {
       invoker.popoverTargetElement = this.contentTarget
     } else {
+      // Button-less fallback: keyboard toggling and popup semantics don't
+      // come for free like they do with popoverTargetElement — wire Enter
+      // (and Space, off text-entry controls) plus aria-haspopup/-expanded
+      // onto the focusable child so AT users can discover and open it.
+      this.fallbackInvoker = this.triggerTarget.querySelector("input, a[href], select, textarea, [tabindex]") || this.triggerTarget
+      this.fallbackInvoker.setAttribute("aria-haspopup", "dialog")
+      this.fallbackInvoker.setAttribute("aria-expanded", this.contentTarget.matches(":popover-open") ? "true" : "false")
       this.triggerTarget.addEventListener("pointerdown", this.armToggle)
       this.triggerTarget.addEventListener("click", this.toggle)
+      this.triggerTarget.addEventListener("keydown", this.keyToggle)
     }
   }
 
   disconnect() {
     this.triggerTarget.removeEventListener("pointerdown", this.armToggle)
     this.triggerTarget.removeEventListener("click", this.toggle)
+    this.triggerTarget.removeEventListener("keydown", this.keyToggle)
   }
 
   armToggle = () => { this.wasOpen = this.contentTarget.matches(":popover-open") }
@@ -32,12 +41,44 @@ export default class extends Controller {
     if (this.wasOpen) { this.wasOpen = false; return }
     this.contentTarget.togglePopover()
   }
+  keyToggle = (e) => {
+    const textEntry = /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName)
+    if (e.key !== "Enter" && !(e.key === " " && !textEntry)) return
+    e.preventDefault()
+    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) => { e.target.dataset.state = e.newState === "open" ? "open" : "closed" }
+  syncState = (e) => {
+    e.target.dataset.state = e.newState === "open" ? "open" : "closed"
+    this.fallbackInvoker?.setAttribute("aria-expanded", e.newState === "open" ? "true" : "false")
+  }
 
   contentTargetConnected(el) {
+    // A Turbo snapshot serializes data-state="open" but :popover-open does
+    // not survive the restore — resync before listening so host CSS keyed
+    // on the state hook doesn't misfire.
+    el.dataset.state = el.matches(":popover-open") ? "open" : "closed"
     el.addEventListener("toggle", this.syncState)
   }
 

data/app/components/phlex_kit/progress/progress.css

@@ -14,4 +14,12 @@
   width: 100%;
   background: var(--pk-brand);
   transition: transform .3s ease;
+  /* value% − 100%: slides the full-width indicator into view from the
+     inline-start edge. --pk-progress-value is a unitless 0–100 set inline
+     by progress.rb. */
+  transform: translateX(calc((var(--pk-progress-value, 0) - 100) * 1%));
+}
+/* RTL: the bar fills from the right, so travel flips. */
+.pk-progress:dir(rtl) .pk-progress-indicator {
+  transform: translateX(calc((100 - var(--pk-progress-value, 0)) * 1%));
 }

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

@@ -4,21 +4,30 @@ module PhlexKit
   # JS; width comes from a caller `class:`/`style:`. Tailwind → vanilla
   # `.pk-progress*` (progress.css).
   class Progress < BaseComponent
-    def initialize(value: 0, **attrs)
+    # value_text: is a named kwarg (not read from **attrs) because `mix`
+    # would *fuse* a caller "aria-valuetext" with the generated default.
+    def initialize(value: 0, value_text: nil, **attrs)
       @value = 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({
         role: "progressbar",
-        "aria-valuenow": @value,
+        "aria-valuenow": v,
         "aria-valuemin": 0,
         "aria-valuemax": 100,
-        "aria-valuetext": "#{@value}%",
-        class: "pk-progress"
+        "aria-valuetext": @value_text || "#{v}%",
+        class: "pk-progress",
+        style: "--pk-progress-value: #{v};"
       }, @attrs)) do
-        div(class: "pk-progress-indicator", style: "transform: translateX(-#{100 - @value}%)")
+        div(class: "pk-progress-indicator")
       end
     end
   end

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,22 +12,12 @@ 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 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.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();
   }
 
@@ -38,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();
 
@@ -176,10 +219,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/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/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.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,18 +27,57 @@ 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()
+    // 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() {
     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,25 +11,55 @@ 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
     }
   }
 
   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).
+    // 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 = () => {
+      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/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.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/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/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_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)