phlex_kit 0.10.0 → 0.11.0

data/app/components/phlex_kit/data_table/data_table_column_toggle.rb

@@ -27,7 +27,10 @@ module PhlexKit
               # invalid ARIA. The change event bubbles from the hidden checkbox
               # to this row, where our toggle action picks it up.
               render DropdownMenuCheckboxItem.new(
-                checked: true,
+                # visible: false starts the menu row unchecked for a column
+                # the host server-renders hidden (pk-hidden on its cells) —
+                # checked: true hardcoded meant the two could never agree.
+                checked: col.fetch(:visible, true),
                 data: {
                   column_key: col[:key].to_s,
                   action: "change->phlex-kit--data-table-column-visibility#toggle"

data/app/components/phlex_kit/data_table/data_table_controller.js

@@ -20,7 +20,11 @@ export default class extends Controller {
   toggleAll(event) {
     const checked = event.target.checked;
     this.rowCheckboxTargets.forEach((cb) => {
+      if (cb.checked === checked) return;
       cb.checked = checked;
+      // Programmatic .checked flips fire no event — hosts (and the
+      // form-field wiring on PhlexKit::Checkbox) must still hear select-all.
+      cb.dispatchEvent(new Event("change", { bubbles: true }));
     });
     this.updateState();
   }

data/app/components/phlex_kit/date_picker/date_picker.rb

@@ -31,6 +31,12 @@ module PhlexKit
       # until the first interaction.
       @value = value || format_selected_date
       @placeholder = placeholder
+      # An id smuggled through input_attrs would MERGE with the generated one
+      # (mix fuses duplicate string attrs), breaking label[for] and the
+      # calendar outlet selector — the top-level id: kwarg is the one path.
+      if input_attrs.key?(:id) || input_attrs.key?("id")
+        raise ArgumentError, "DatePicker: pass id: as the top-level kwarg, not input_attrs[:id]"
+      end
       @input_attrs = input_attrs
       @calendar_attrs = calendar_attrs
       @trigger_attrs = trigger_attrs

data/app/components/phlex_kit/dialog/dialog.css

@@ -11,7 +11,9 @@
   --pk-dialog-spacing: 1rem;
   position: fixed; z-index: 50; width: 100%;
   max-width: min(24rem, calc(100% - 2rem));
-  max-height: 100vh;
+  /* Breathing room like the horizontal inset — 100vh touched the screen
+     edges and overflowed behind mobile browser chrome (dvh tracks it). */
+  max-height: calc(100dvh - 2rem);
   overflow-y: auto; gap: 1rem;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: calc(var(--pk-radius) + 2px); background: var(--pk-surface); color: var(--pk-text);

data/app/components/phlex_kit/dialog/dialog_content.rb

@@ -21,7 +21,7 @@ module PhlexKit
       aria = {}
       aria[:labelledby] = @labelledby if @labelledby
       aria[:describedby] = @describedby if @describedby
-      dialog(**mix({ class: cls, aria: aria, data: { phlex_kit__dialog_target: "dialog", action: "click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
+      dialog(**mix({ class: cls, aria: aria, data: { phlex_kit__dialog_target: "dialog", action: "pointerdown->phlex-kit--dialog#backdropPointerdown click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
         yield
         if @show_close_button
           button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--dialog#dismiss" }) do

data/app/components/phlex_kit/dialog/dialog_controller.js

@@ -44,15 +44,26 @@ export default class extends Controller {
     document.body.style.overflow = "hidden"
   }
   dismiss() { this.dialogTarget.close() }
+  // Only a press that STARTED on the backdrop may dismiss: a drag-select
+  // beginning inside the panel and released over the backdrop fires the
+  // click on <dialog> with outside coordinates — that must not close it
+  // (Radix guards on pointerdown origin the same way).
+  backdropPointerdown(e) {
+    this.pressStartedOutside = e.target === this.dialogTarget && !this.#insideBox(e)
+  }
   // Only a click on the ::backdrop dismisses. e.target is the <dialog> for
   // backdrop clicks, but ALSO for clicks on the dialog's own padding/flex
   // gaps — disambiguate by testing the click point against the dialog's box.
   backdropClick(e) {
     if (e.target !== this.dialogTarget) return
     if (e.detail === 0) return // synthetic/keyboard click — no coordinates
+    if (!this.pressStartedOutside) return
+    this.pressStartedOutside = false
+    if (!this.#insideBox(e)) this.dismiss()
+  }
+  #insideBox(e) {
     const r = this.dialogTarget.getBoundingClientRect()
-    const inside = e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom
-    if (!inside) this.dismiss()
+    return e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom
   }
   handleClose = () => { document.body.style.overflow = this.previousOverflow ?? "" }
 }

data/app/components/phlex_kit/dropdown_menu/dropdown_menu.css

@@ -20,14 +20,17 @@
   position-try-fallbacks: flip-block;
 }
 .pk-dropdown-menu-content-up { position-area: block-start span-inline-end; margin: 0 0 4px; }
+/* Gap margins are logical to match the logical position-area — physical
+   margins landed on the wrong side in RTL (and flip-inline flips logical
+   margins along with the placement). */
 .pk-dropdown-menu-content-right {
   position-area: inline-end span-block-end;
-  margin: 0 0 0 4px;
+  margin: 0; margin-inline-start: 4px;
   position-try-fallbacks: flip-inline;
 }
 .pk-dropdown-menu-content-left {
   position-area: inline-start span-block-end;
-  margin: 0 4px 0 0;
+  margin: 0; margin-inline-end: 4px;
   position-try-fallbacks: flip-inline;
 }
 .pk-dropdown-menu-viewport {

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_controller.js

@@ -16,20 +16,47 @@ export default class extends Controller {
 
   connect() {
     this.boundHandleKeydown = this.#handleKeydown.bind(this);
+    // Outstanding syncSub rAF handles — cancelled on disconnect so a queued
+    // frame never touches a torn-down menu (menubar's pattern).
+    this.subFrames = new Set();
     // The visible control is the caller's button/link inside the trigger
     // wrapper — that's what AT reads, so the popup wiring belongs on it.
     this.invoker = this.triggerTarget.querySelector("button, a, [tabindex]") || this.triggerTarget;
     this.invoker.setAttribute("aria-haspopup", "menu");
     this.invoker.setAttribute("aria-expanded", "false");
+    // Associate trigger and menu for AT (the dialog controller wires its
+    // ids the same way).
+    if (!this.contentTarget.id) this.contentTarget.id = `pk-dropdown-menu-${Math.random().toString(36).slice(2, 8)}`;
+    this.invoker.setAttribute("aria-controls", this.contentTarget.id);
+    // Turbo snapshots BEFORE disconnect — an open menu (reflected in the
+    // open value) would be resurrected from the page cache on restore.
+    this.boundBeforeCache = () => this.close();
+    document.addEventListener("turbo:before-cache", this.boundBeforeCache);
     // `open:` on the Ruby side renders the value — start open (same
     // kwarg -> value -> connect flow as Collapsible).
     if (this.openValue) this.#open();
   }
 
   disconnect() {
+    document.removeEventListener("turbo:before-cache", this.boundBeforeCache);
+    this.subFrames.forEach((id) => cancelAnimationFrame(id));
+    this.subFrames.clear();
     this.#removeEventListeners();
   }
 
+  // Mirrors the CSS-driven submenu state (:hover / :focus-within) onto the
+  // sub trigger's aria-expanded. rAF: on mouseleave/focusout the pseudo-class
+  // state isn't settled until the event finishes dispatching.
+  syncSub(e) {
+    const sub = e.currentTarget;
+    const id = requestAnimationFrame(() => {
+      this.subFrames.delete(id);
+      sub.querySelector(":scope > [aria-haspopup]")
+        ?.setAttribute("aria-expanded", sub.matches(":hover, :focus-within"));
+    });
+    this.subFrames.add(id);
+  }
+
   onClickOutside(event) {
     // Gate on the live :popover-open state, not the stored flag — a stale
     // flag is how a close on an already-closed panel becomes an open.

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_sub.rb

@@ -5,7 +5,9 @@ module PhlexKit
   class DropdownMenuSub < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-dropdown-menu-sub" }, @attrs), &)
+      # syncSub mirrors the CSS-driven reveal state onto the sub trigger's
+      # aria-expanded (same wiring as MenubarSub).
+      div(**mix({ class: "pk-dropdown-menu-sub", data: { action: "mouseenter->phlex-kit--dropdown-menu#syncSub mouseleave->phlex-kit--dropdown-menu#syncSub focusin->phlex-kit--dropdown-menu#syncSub focusout->phlex-kit--dropdown-menu#syncSub" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_sub_trigger.rb

@@ -10,7 +10,9 @@ module PhlexKit
         # -1: roving focus reaches it via arrows (focus-within opens the sub);
         # tabindex 0 made it a stray tab stop inside the menu.
         tabindex: "-1",
-        aria: { haspopup: "menu" },
+        # expanded starts false and is mirrored live by the controller's
+        # syncSub (the reveal itself is pure CSS :hover/:focus-within).
+        aria: { haspopup: "menu", expanded: "false" },
         data: { phlex_kit__dropdown_menu_target: "menuItem" }
       }, @attrs)) do
         block&.call

data/app/components/phlex_kit/field/field_separator.rb

@@ -6,7 +6,7 @@ module PhlexKit
     def initialize(**attrs) = (@attrs = attrs)
 
     def view_template(&block)
-      div(**mix({ class: "pk-field-separator", data: { content: block ? "true" : "false" } }, @attrs)) do
+      div(**mix({ class: "pk-field-separator" }, @attrs)) do
         render Separator.new(class: "pk-field-separator-line")
         span(class: "pk-field-separator-content", &block) if block
       end

data/app/components/phlex_kit/form_field/form_field_controller.js

@@ -9,10 +9,21 @@ import { Controller } from "@hotwired/stimulus";
 // back to the browser's validationMessage.
 // Connects to data-controller="phlex-kit--form-field"
 export default class extends Controller {
-  static targets = ["input", "error"];
+  static targets = ["input", "error", "hint"];
   static values = { shouldValidate: false };
 
   connect() {
+    // Hints are static description text — wire them onto every control's
+    // aria-describedby up front (errors join/leave dynamically via
+    // #describeBy, which preserves foreign tokens like these).
+    this.hintTargets.forEach((hint) => {
+      if (!hint.id) return;
+      this.inputTargets.forEach((input) => {
+        const tokens = (input.getAttribute("aria-describedby") || "").split(/\s+/).filter(Boolean);
+        if (!tokens.includes(hint.id)) tokens.push(hint.id);
+        input.setAttribute("aria-describedby", tokens.join(" "));
+      });
+    });
     if (this.hasErrorTarget) {
       if (this.errorTarget.textContent.trim()) {
         this.shouldValidateValue = true;
@@ -37,6 +48,16 @@ export default class extends Controller {
     if (!this.hasErrorTarget) return;
     error.preventDefault();
 
+    // preventDefault also cancels the browser's focus-first-invalid — restore
+    // it for the first invalid control of the submit pass (all invalid events
+    // fire in the same task, so the microtask reset scopes "first" correctly).
+    if (!this._focusedInvalid) {
+      this._focusedInvalid = true;
+      queueMicrotask(() => { this._focusedInvalid = false; });
+      error.target.focus({ preventScroll: true });
+      error.target.scrollIntoView({ block: "nearest" });
+    }
+
     this.shouldValidateValue = true;
     this.#setErrorMessage(error);
   }

data/app/components/phlex_kit/form_field/form_field_hint.rb

@@ -2,12 +2,16 @@ module PhlexKit
   # Muted helper text under a PhlexKit::FormField control. Hidden when empty.
   # See form_field.rb.
   class FormFieldHint < BaseComponent
-    def initialize(**attrs)
+    # A default id (like FormFieldError) so the controller can wire the hint
+    # into every control's aria-describedby — without it SR users never heard
+    # the hint text. id: is a named kwarg to avoid mix id-fusion.
+    def initialize(id: nil, **attrs)
+      @id = id || "pk-form-field-hint-#{SecureRandom.hex(4)}"
       @attrs = attrs
     end
 
     def view_template(&block)
-      p(**mix({ class: "pk-form-field-hint" }, @attrs), &block)
+      p(**mix({ id: @id, class: "pk-form-field-hint", data: { phlex_kit__form_field_target: "hint" } }, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/hover_card/hover_card.css

@@ -22,12 +22,14 @@
   box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent); outline: none;
 }
 .pk-hover-card-content.top { position-area: block-start span-inline-end; margin: 0 0 .25rem; }
+/* Gap margins are logical to match the logical position-area (and tooltip's
+   pattern) — physical margins landed on the wrong side in RTL. */
 .pk-hover-card-content.left {
-  position-area: inline-start; margin: 0 .25rem 0 0;
+  position-area: inline-start; margin: 0; margin-inline-end: .25rem;
   position-try-fallbacks: flip-inline;
 }
 .pk-hover-card-content.right {
-  position-area: inline-end; margin: 0 0 0 .25rem;
+  position-area: inline-end; margin: 0; margin-inline-start: .25rem;
   position-try-fallbacks: flip-inline;
 }
 /* Hiding must survive author display values (a host class like

data/app/components/phlex_kit/icon/icon.css

@@ -0,0 +1,9 @@
+/* Co-located with icon.rb — PhlexKit::Icon. The .pk-icon class was emitted
+   with no rule anywhere (audit round 6): the bare SVG inherited the UA's
+   inline/baseline layout (descender gap under icons) and could be squashed
+   inside height-constrained flex scroll panes. */
+.pk-icon {
+  display: inline-block;
+  vertical-align: middle;
+  flex: none;
+}

data/app/components/phlex_kit/icon/icon.rb

@@ -20,7 +20,13 @@ module PhlexKit
 
     def view_template
       icon = Icons.fetch(@name, library: @library || PhlexKit.config.icon_library)
-      svg(**mix(base_attrs(icon), @attrs)) do |s|
+      base = base_attrs(icon)
+      # `mix` merges duplicate string attrs ("16 24") — drop a generated attr
+      # whenever the caller supplies their own copy, so theirs wins.
+      %i[width height viewbox aria-hidden].each do |key|
+        base.delete(key) if @attrs.key?(key) || @attrs.key?(key.to_s)
+      end
+      svg(**mix(base, @attrs)) do |s|
         icon[:elements].each { |tag, attrs| s.public_send(tag, **attrs) }
       end
     end

data/app/components/phlex_kit/input_group/input_group.css

@@ -59,7 +59,6 @@
   justify-content: center;
   gap: .5rem;
   flex: none;
-  cursor: text;
   user-select: none;
   padding-block: .375rem;
   color: var(--pk-muted);

data/app/components/phlex_kit/marker/marker.rb

@@ -10,13 +10,20 @@ module PhlexKit
     # unknown values used to fall through silently to <div> — fail loud instead.
     AS_TAGS = %i[div button].freeze
 
-    def initialize(variant: :default, href: nil, as: :div, **attrs)
+    # type: is a named kwarg (not a mix default) because `mix` would *fuse* a
+    # caller type: "submit" with the generated "button" into an invalid
+    # two-token value the browser resolves back to submit.
+    def initialize(variant: :default, href: nil, as: :div, type: :button, **attrs)
       @variant = variant.to_sym
       @href = href
       @as = as.to_sym
       unless AS_TAGS.include?(@as)
         raise ArgumentError, "unknown Marker as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
       end
+      if @href && @as != :div
+        raise ArgumentError, "Marker href: renders an <a> — it can't combine with as: #{@as.inspect}"
+      end
+      @type = type
       @attrs = attrs
     end
 
@@ -25,7 +32,7 @@ module PhlexKit
       if @href
         a(**mix({ class: classes, href: @href }, @attrs), &)
       elsif @as == :button
-        button(**mix({ class: classes, type: "button" }, @attrs), &)
+        button(**mix({ class: classes, type: @type }, @attrs), &)
       else
         div(**mix({ class: classes }, @attrs), &)
       end

data/app/components/phlex_kit/masked_input/masked_input_controller.js

@@ -26,13 +26,27 @@ export default class extends Controller {
   apply() {
     const el = this.element
     // The whole value is rewritten below, which throws the caret to the end —
-    // remember how many maskable chars sit before it and re-seat it after
-    // the same count in the masked output (mid-field edits keep their place).
+    // re-seat it after the same number of TOKEN-filled (user) characters.
+    // Counting is done in token space, not "any alphanumeric" space: mask
+    // literals can themselves be alphanumeric (the "1" in "+1 (###) ###-####"),
+    // and counting them as user input reordered every subsequent keystroke.
     const caret = el.selectionStart ?? el.value.length
-    const rawBefore = this.maskable(el.value.slice(0, caret)).length
+    const filledBefore = this.maskFill(this.maskable(el.value.slice(0, caret))).tokenPos.length
 
-    const raw = this.maskable(el.value)
+    const { out, tokenPos } = this.maskFill(this.maskable(el.value))
+    el.value = out
+
+    if (document.activeElement === el) {
+      const pos = filledBefore === 0 ? 0 : tokenPos[filledBefore - 1] + 1
+      el.setSelectionRange(pos, pos)
+    }
+  }
+
+  // Fill the mask from `raw`, returning the output and the output indices
+  // that were filled from user input (vs emitted as mask literals).
+  maskFill(raw) {
     let out = "", i = 0
+    const tokenPos = []
     for (const t of this.mask) {
       if (i >= raw.length) break
       if (t === "#" || t === "A" || t === "*") {
@@ -41,19 +55,11 @@ export default class extends Controller {
         const re = t === "#" ? /\d/ : t === "A" ? /[A-Za-z]/ : /[0-9A-Za-z]/
         while (i < raw.length && !re.test(raw[i])) i++
         if (i >= raw.length) break
+        tokenPos.push(out.length)
         out += raw[i++]
       } else { out += t; if (raw[i] === t) i++ }
     }
-    el.value = out
-
-    if (document.activeElement === el) {
-      let pos = 0, seen = 0
-      while (pos < out.length && seen < rawBefore) {
-        if (/[0-9A-Za-z]/.test(out[pos])) seen++
-        pos++
-      }
-      el.setSelectionRange(pos, pos)
-    }
+    return { out, tokenPos }
   }
   // Transliterate full-width digits (０-９, U+FF10–FF19 — common IME numeric
   // output) to ASCII before the charset filter would silently drop them.

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

@@ -42,6 +42,12 @@ export default class extends Controller {
       if (!panel.id) panel.id = `pk-menu-panel-${++uid}`
       trigger.setAttribute("aria-controls", panel.id)
     }
+    // A Turbo snapshot serializes aria-expanded="true" even though the
+    // panel's :popover-open does not survive the restore — no panel can be
+    // open at connect time, so stamp every expanded marker back to false
+    // (only on elements that already carry it: plain nav links must not
+    // grow an aria-expanded). Covers the trigger and CSS-revealed subs.
+    menu.querySelectorAll("[aria-expanded='true']").forEach((el) => el.setAttribute("aria-expanded", "false"))
     if (this.roving) this.applyRoving()
   }
 

data/app/components/phlex_kit/message/message.rb

@@ -3,8 +3,13 @@ module PhlexKit
   # align: :end reverses the row. Compose Message > MessageContent (+ Avatar/
   # Header/Footer); group several in a MessageGroup.
   class Message < BaseComponent
+    ALIGNS = %i[start end].freeze
+
     def initialize(align: :start, **attrs)
       @align = align.to_sym
+      # Fail loud like sibling Bubble: message.css only styles data-align="end",
+      # so an unknown value silently rendered a start-aligned row.
+      raise KeyError, "unknown Message align #{@align}" unless ALIGNS.include?(@align)
       @attrs = attrs
     end
     def view_template(&)

data/app/components/phlex_kit/message_scroller/message_scroller_controller.js

@@ -378,6 +378,9 @@ export default class extends Controller {
       button.setAttribute("data-active", active ? "true" : "false");
       // Remove the inert button from the tab order so there are no ghost stops.
       button.setAttribute("tabindex", active ? "0" : "-1");
+      // opacity-only hiding leaves it in the accessibility tree — a SR
+      // virtual cursor would still find a phantom jump button.
+      button.setAttribute("aria-hidden", active ? "false" : "true");
     });
   }
 }

data/app/components/phlex_kit/native_select/native_select.rb

@@ -21,20 +21,29 @@ module PhlexKit
       sm: "sm"
     }.freeze
 
+    # An Integer size: is the NATIVE <select size> (multi-row list box) and
+    # passes straight through — the kit's visual sizes stay symbols.
     def initialize(size: :default, **attrs)
-      @size = size.to_sym
+      if size.is_a?(Integer)
+        @native_size = size
+        @size = :default
+      else
+        @size = size.to_sym
+      end
       @attrs = attrs
     end
 
     def view_template(&block)
       div(class: "pk-native-select") do
-        select(**mix({
+        base = {
           class: classes,
           data: {
             phlex_kit__form_field_target: "input",
             action: "change->phlex-kit--form-field#onChange invalid->phlex-kit--form-field#onInvalid"
           }
-        }, @attrs), &block)
+        }
+        base[:size] = @native_size if @native_size
+        select(**mix(base, @attrs), &block)
         render PhlexKit::NativeSelectIcon.new
       end
     end

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

@@ -23,7 +23,10 @@ module PhlexKit
           # mouseenter->cancelClose: re-entering the nav over list padding /
           # whitespace must cancel the pending mouseleave grace-close (only
           # trigger/panel mouseenter did before).
-          action: "click@window->phlex-kit--menubar#onClickOutside keydown->phlex-kit--menubar#onKeydown mouseleave->phlex-kit--menubar#closeSoon mouseenter->phlex-kit--menubar#cancelClose"
+          # focusout->onFocusout: a keyboard user tabbing past the panel's
+          # last link must close it (menubar wires the same handler; closeSoon
+          # is pointer-only and never fires for this path).
+          action: "click@window->phlex-kit--menubar#onClickOutside keydown->phlex-kit--menubar#onKeydown focusout->phlex-kit--menubar#onFocusout mouseleave->phlex-kit--menubar#closeSoon mouseenter->phlex-kit--menubar#cancelClose"
         }
       }, @attrs), &)
     end

data/app/components/phlex_kit/pagination/pagination.rb

@@ -2,9 +2,17 @@ module PhlexKit
   # Page navigation. Ported from ruby_ui's RubyUI::Pagination. Compose Pagination >
   # PaginationContent > PaginationItem(href:, active:) / PaginationEllipsis.
   class Pagination < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    # label: is a named kwarg (not a mix default) because `mix` would *fuse* a
+    # caller aria-label with the hardcoded "pagination" ("pagination Résultats").
+    def initialize(label: "pagination", **attrs)
+      @label = label
+      @attrs = attrs
+    end
+
     def view_template(&)
-      nav(**mix({ class: "pk-pagination", role: "navigation", aria: { label: "pagination" } }, @attrs), &)
+      base = { class: "pk-pagination", role: "navigation" }
+      base[:aria] = { label: @label } unless aria_labelled?
+      nav(**mix(base, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/pagination/pagination_next.rb

@@ -15,7 +15,9 @@ module PhlexKit
       # custom (possibly localized) label: speaks for itself — hardcoding
       # "Go to next page" over it would make AT announce the wrong language.
       base = { href: @href, class: "pk-button ghost pk-pagination-next" }
-      base[:aria] = { label: "Go to next page" } if @label == DEFAULT_LABEL
+      # ...and never over a caller-supplied aria label — `mix` would fuse
+      # the two strings instead of overriding.
+      base[:aria] = { label: "Go to next page" } if @label == DEFAULT_LABEL && !aria_labelled?
       li do
         a(**mix(base, @attrs)) do
           span(class: "pk-pagination-label") { @label }

data/app/components/phlex_kit/pagination/pagination_previous.rb

@@ -16,7 +16,9 @@ module PhlexKit
       # custom (possibly localized) label: speaks for itself — hardcoding
       # "Go to previous page" over it would make AT announce the wrong language.
       base = { href: @href, class: "pk-button ghost pk-pagination-previous" }
-      base[:aria] = { label: "Go to previous page" } if @label == DEFAULT_LABEL
+      # ...and never over a caller-supplied aria label — `mix` would fuse
+      # the two strings instead of overriding.
+      base[:aria] = { label: "Go to previous page" } if @label == DEFAULT_LABEL && !aria_labelled?
       li do
         a(**mix(base, @attrs)) do
           render Icon.new(:chevron_left, size: nil)

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,25 @@ 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()
+  }
 
   // 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