phlex_kit 0.8.0 → 0.9.0

data/app/components/phlex_kit/input_otp/input_otp_separator.rb

@@ -1,7 +1,9 @@
 module PhlexKit
-  # Divider between OTP groups. See input_otp.rb.
+  # Divider between OTP groups. See input_otp.rb. Purely decorative — the dash
+  # is aria-hidden (no separator role) so AT doesn't announce a stray "-"
+  # between the digit fields.
   class InputOtpSeparator < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
-    def view_template = div(**mix({ class: "pk-input-otp-separator", role: "separator" }, @attrs)) { "-" }
+    def view_template = div(**mix({ class: "pk-input-otp-separator", aria_hidden: "true" }, @attrs)) { "-" }
   end
 end

data/app/components/phlex_kit/item/item.css

@@ -60,7 +60,7 @@ a.pk-item:hover { background: var(--pk-surface-2); }
   color: var(--pk-muted);
   font-size: .875rem;
   line-height: 1.5;
-  text-align: left;
+  text-align: start;
   overflow: hidden;
   text-overflow: ellipsis;
 }

data/app/components/phlex_kit/item/item_group.rb

@@ -1,7 +1,9 @@
 module PhlexKit
-  # Stack of Items. See item.rb.
+  # Stack of Items. See item.rb. No role="list": Items carry no
+  # role="listitem" (an href Item is an <a> that must keep its link role), so
+  # claiming a list here made AT announce an empty list.
   class ItemGroup < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
-    def view_template(&) = div(**mix({ class: "pk-item-group", role: "list" }, @attrs), &)
+    def view_template(&) = div(**mix({ class: "pk-item-group" }, @attrs), &)
   end
 end

data/app/components/phlex_kit/item/item_separator.rb

@@ -4,7 +4,9 @@ module PhlexKit
   class ItemSeparator < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template
-      div(**mix({ class: "pk-item-separator", role: "separator", aria: { hidden: true } }, @attrs))
+      # Purely decorative — aria-hidden only (role="separator" would
+      # contradict aria-hidden and confuse AT).
+      div(**mix({ class: "pk-item-separator", aria: { hidden: true } }, @attrs))
     end
   end
 end

data/app/components/phlex_kit/marker/marker.css

@@ -10,7 +10,7 @@
   min-height: 1rem;
   color: var(--pk-muted);
   font-size: .875rem;
-  text-align: left;
+  text-align: start;
 }
 a.pk-marker, button.pk-marker {
   cursor: pointer;

data/app/components/phlex_kit/masked_input/masked_input.rb

@@ -1,7 +1,7 @@
 module PhlexKit
   # Text input with an inline mask. Ported from ruby_ui's RubyUI::MaskedInput —
   # ruby_ui uses the `maska` JS lib; PhlexKit ships a small dependency-free mask
-  # controller (#=digit, A=letter, *=any) driven by a data-mask attribute. Swap in
+  # controller (#=digit, A=letter, *=any alphanumeric) driven by a data-mask attribute. Swap in
   # maska by replacing masked_input_controller.js if you need its full feature set.
   class MaskedInput < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)

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

@@ -1,26 +1,51 @@
 import { Controller } from "@hotwired/stimulus"
 
 // Connects to data-controller="phlex-kit--masked-input". Lightweight, dependency-
-// free mask driven by a data-mask pattern (# = digit, A = letter, * = any). Swap
-// in `maska` (ruby_ui's choice) here if you need a fuller mask engine.
+// free mask driven by a data-mask pattern (# = digit, A = letter, * = any
+// alphanumeric — formatting characters are stripped before matching, so *
+// cannot match punctuation; swap in `maska` (ruby_ui's choice) if you need a
+// fuller mask engine).
 export default class extends Controller {
   connect() {
     this.mask = this.element.getAttribute("data-mask") || ""
     if (!this.mask) return
-    this.onInput = () => this.apply()
+    // Skip IME composition updates — masking mid-composition mangles the text.
+    this.onInput = (e) => { if (!e.isComposing) this.apply() }
     this.element.addEventListener("input", this.onInput)
+    // A server-prefilled value renders unmasked — format it once up front.
+    if (this.element.value) this.apply()
   }
   disconnect() { if (this.onInput) this.element.removeEventListener("input", this.onInput) }
   apply() {
-    const raw = this.element.value.replace(/[^0-9A-Za-z]/g, "")
+    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).
+    const caret = el.selectionStart ?? el.value.length
+    const rawBefore = el.value.slice(0, caret).replace(/[^0-9A-Za-z]/g, "").length
+
+    const raw = el.value.replace(/[^0-9A-Za-z]/g, "")
     let out = "", i = 0
     for (const t of this.mask) {
       if (i >= raw.length) break
-      if (t === "#") { if (/\d/.test(raw[i])) out += raw[i++]; else break }
-      else if (t === "A") { if (/[A-Za-z]/.test(raw[i])) out += raw[i++]; else break }
-      else if (t === "*") { out += raw[i++] }
-      else { out += t; if (raw[i] === t) i++ }
+      if (t === "#" || t === "A" || t === "*") {
+        // Skip wrong-class characters instead of aborting the fill —
+        // "12a34" against ##/## must yield "12/34", not "12".
+        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
+        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)
     }
-    this.element.value = out
   }
 }

data/app/components/phlex_kit/menubar/menubar.css

@@ -30,6 +30,7 @@
 }
 .pk-menubar-trigger:hover,
 .pk-menubar-trigger[aria-expanded="true"] { background: var(--pk-surface-2); }
+.pk-menubar-trigger:focus-visible { box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent); }
 .pk-menubar-content {
   position: fixed;
   position-anchor: --pk-menubar-menu;
@@ -46,7 +47,7 @@
   background: var(--pk-surface);
   color: var(--pk-text);
   padding: .25rem;
-  box-shadow: 0 8px 24px rgb(0 0 0 / .3);
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent);
 }
 /* Hover bridge over the trigger→panel gap — both sides, since a flip
    fallback puts the gap below the panel instead of above. */
@@ -82,7 +83,7 @@
 .pk-menubar-item svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
 .pk-menubar-item:hover, .pk-menubar-item:focus { background: var(--pk-accent); }
 .pk-menubar-item[data-disabled="true"] { pointer-events: none; opacity: .5; }
-.pk-menubar-item.inset { padding-left: 1.75rem; }
+.pk-menubar-item.inset { padding-inline-start: 1.75rem; }
 .pk-menubar-item.destructive { color: var(--pk-red); }
 .pk-menubar-item.destructive > svg { color: var(--pk-red); }
 .pk-menubar-item.destructive:hover,
@@ -90,9 +91,9 @@
   background: color-mix(in oklab, var(--pk-red) 12%, transparent);
   color: var(--pk-red);
 }
-.pk-menubar-shortcut { margin-left: auto; font-size: .75rem; color: var(--pk-muted); letter-spacing: .1em; }
+.pk-menubar-shortcut { margin-inline-start: auto; font-size: .75rem; color: var(--pk-muted); letter-spacing: .1em; }
 .pk-menubar-label { padding: .25rem .375rem; font-size: .875rem; font-weight: 500; }
-.pk-menubar-label.inset { padding-left: 1.75rem; }
+.pk-menubar-label.inset { padding-inline-start: 1.75rem; }
 .pk-menubar-separator { height: 1px; margin: .25rem -0.25rem; background: var(--pk-border); }
 .pk-menubar-group { display: contents; }
 
@@ -105,10 +106,10 @@
   pointer-events: none;
 }
 .pk-menubar-checkbox-item,
-.pk-menubar-radio-item { position: relative; padding-left: 1.75rem; }
+.pk-menubar-radio-item { position: relative; padding-inline-start: 1.75rem; }
 .pk-menubar-item-indicator {
   position: absolute;
-  left: .375rem;
+  inset-inline-start: .375rem;
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -120,14 +121,14 @@
 .pk-menubar-radio-item .pk-menubar-item-indicator svg { width: .5rem; height: .5rem; }
 .pk-menubar-item:has(.pk-menubar-item-input:checked) .pk-menubar-item-indicator { visibility: visible; }
 .pk-menubar-item:has(.pk-menubar-item-input:focus-visible) {
-  box-shadow: 0 0 0 2px color-mix(in oklab, var(--pk-ring) 50%, transparent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
 
 /* Submenu: trigger row + side panel, revealed on hover/focus — pure CSS.
    The row is its own scoped anchor; the panel flips to the other side at
    the viewport right edge. */
 .pk-menubar-sub { anchor-name: --pk-menubar-sub; anchor-scope: --pk-menubar-sub; }
-.pk-menubar-sub-chevron { margin-left: auto; width: 1rem; height: 1rem; }
+.pk-menubar-sub-chevron { margin-inline-start: auto; width: 1rem; height: 1rem; }
 .pk-menubar-sub-content {
   position: fixed;
   position-anchor: --pk-menubar-sub;
@@ -148,7 +149,7 @@
   background: var(--pk-surface);
   color: var(--pk-text);
   padding: .25rem;
-  box-shadow: 0 8px 24px rgb(0 0 0 / .3);
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent);
 }
 .pk-menubar-sub:hover > .pk-menubar-sub-content,
 .pk-menubar-sub:focus-within > .pk-menubar-sub-content { display: block; }

data/app/components/phlex_kit/menubar/menubar_content.rb

@@ -1,9 +1,15 @@
 module PhlexKit
   # Dropdown panel of a MenubarMenu. See menubar.rb.
   class MenubarContent < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    def initialize(**attrs)
+      # Default id so the controller can wire the trigger's aria-controls to
+      # this panel in menuTargetConnected (same pattern as accordion).
+      @id = attrs.delete(:id) || "pk-menubar-content-#{SecureRandom.hex(4)}"
+      @attrs = attrs
+    end
+
     def view_template(&)
-      div(**mix({ class: "pk-menubar-content", popover: "manual", role: "menu" }, @attrs), &)
+      div(**mix({ id: @id, class: "pk-menubar-content", popover: "manual", role: "menu" }, @attrs), &)
     end
   end
 end

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

@@ -11,6 +11,8 @@ import { Controller } from "@hotwired/stimulus"
 // (skipping [data-disabled]); ArrowLeft/ArrowRight jump to the sibling menus;
 // Escape closes and returns focus to the trigger.
 // Connects to data-controller="phlex-kit--menubar"
+let uid = 0
+
 export default class extends Controller {
   static targets = ["menu"]
 
@@ -21,13 +23,38 @@ export default class extends Controller {
     return this.menuTargets.find((menu) => this.panel(menu)?.matches(":popover-open")) ?? null
   }
 
+  initialize() {
+    // menuTargetConnected fires BEFORE connect() — state it reads must be
+    // set here. Roving tabindex applies only in menubar mode: a nav's
+    // triggers and links stay natural tab stops.
+    this.roving = this.element.dataset.hoverOpen === undefined
+  }
+
+  // Pair each trigger with its panel for AT (aria-controls), and fold the
+  // trigger into the roving tabindex (first trigger 0, rest -1).
+  menuTargetConnected(menu) {
+    const trigger = this.trigger(menu)
+    const panel = this.panel(menu)
+    if (trigger && panel) {
+      if (!panel.id) panel.id = `pk-menu-panel-${++uid}`
+      trigger.setAttribute("aria-controls", panel.id)
+    }
+    if (this.roving) this.applyRoving()
+  }
+
+  menuTargetDisconnected() {
+    if (this.roving) this.applyRoving()
+  }
+
   disconnect() {
     clearTimeout(this.graceTimer)
   }
 
   toggle(e) {
     const menu = e.currentTarget.closest("[data-phlex-kit--menubar-target=\"menu\"]")
-    this.openMenu === menu ? this.close() : this.show(menu, true)
+    // detail 0 = keyboard-activated click (Enter/Space): only then does the
+    // first item get force-focused — a mouse open leaves focus on the trigger.
+    this.openMenu === menu ? this.close() : this.show(menu, e.detail === 0)
   }
 
   // Hover: switches between menus while one is open (menubar), or opens
@@ -58,10 +85,15 @@ export default class extends Controller {
   show(menu, focus = false) {
     if (this.openMenu !== menu) {
       this.close()
-      this.panel(menu)?.showPopover()
-      menu.querySelector("[aria-expanded]")?.setAttribute("aria-expanded", "true")
+      if (this.panel(menu)) {
+        this.panel(menu).showPopover()
+        menu.querySelector("[aria-expanded]")?.setAttribute("aria-expanded", "true")
+      }
     }
-    if (focus) this.items(menu)[0]?.focus()
+    if (this.roving) this.applyRoving(this.trigger(menu))
+    // No panel items (e.g. a panel-less nav link item reached via arrows):
+    // land on the trigger itself instead of stranding focus.
+    if (focus) (this.items(menu)[0] ?? this.trigger(menu))?.focus()
   }
 
   close(opts = {}) {
@@ -84,11 +116,20 @@ export default class extends Controller {
   // cleanup): roving focus while a menu is open, ArrowDown-opens while closed.
   onKeydown(e) {
     if (!this.openMenu) {
-      if (e.key !== "ArrowDown") return
       const menu = e.target.closest("[data-phlex-kit--menubar-target=\"menu\"]")
       if (!menu) return
-      e.preventDefault()
-      this.show(menu, true)
+      if (e.key === "ArrowDown") {
+        e.preventDefault()
+        this.show(menu, true)
+      } else if (e.key === "ArrowRight" || e.key === "ArrowLeft") {
+        // Closed bar: left/right move focus between the triggers (APG).
+        e.preventDefault()
+        const menus = this.menuTargets
+        const next = menus[(menus.indexOf(menu) + (e.key === "ArrowRight" ? 1 : -1) + menus.length) % menus.length]
+        const target = next ? this.trigger(next) : null
+        target?.focus()
+        if (this.roving && target) this.applyRoving(target)
+      }
       return
     }
     const items = this.items(this.openMenu)
@@ -114,17 +155,51 @@ export default class extends Controller {
         e.preventDefault()
         items[items.length - 1]?.focus()
         break
+      case "Enter":
+      case " ":
+        // Explicit click so label rows (checkbox/radio) activate — labels
+        // have no native keyboard activation (and this gives links Space).
+        if (index >= 0) {
+          e.preventDefault()
+          items[index].click()
+        }
+        break
       case "ArrowRight":
         e.preventDefault()
-        this.shift(1)
+        // On a sub trigger, enter the submenu (focus reveals it via
+        // :focus-within) instead of jumping to the next top-level menu.
+        if (document.activeElement?.matches(".pk-menubar-sub-trigger")) {
+          this.enterSub(document.activeElement)
+        } else {
+          this.shift(1)
+        }
         break
-      case "ArrowLeft":
+      case "ArrowLeft": {
         e.preventDefault()
-        this.shift(-1)
+        // Inside a submenu, step back to its trigger instead of switching menus.
+        const sub = document.activeElement?.closest(".pk-menubar-sub-content")
+        if (sub) {
+          sub.closest(".pk-menubar-sub")?.querySelector(".pk-menubar-sub-trigger")?.focus()
+        } else {
+          this.shift(-1)
+        }
         break
+      }
     }
   }
 
+  // Focus the first row of a sub trigger's panel. The panel opens on
+  // :focus-within, so focus the trigger first, then hop into the revealed
+  // panel's first visible item.
+  enterSub(trigger) {
+    trigger.focus()
+    const panel = trigger.closest(".pk-menubar-sub")?.querySelector(".pk-menubar-sub-content")
+    if (!panel) return
+    const first = [...panel.querySelectorAll("[role^=\"menuitem\"]")]
+      .find((el) => !el.closest("[data-disabled]") && el.getClientRects().length > 0)
+    first?.focus()
+  }
+
   // Mirrors a checkbox/radio item's native input state onto the item's
   // aria-checked (radios also reset their group's siblings).
   syncChecked(e) {
@@ -135,12 +210,38 @@ export default class extends Controller {
     group.forEach((i) => i.closest("[role^=\"menuitem\"]")?.setAttribute("aria-checked", i.checked))
   }
 
+  // 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
+    requestAnimationFrame(() => {
+      sub.querySelector(":scope > [aria-haspopup]")
+        ?.setAttribute("aria-expanded", sub.matches(":hover, :focus-within"))
+    })
+  }
+
   shift(dir) {
     const menus = this.menuTargets
     const index = menus.indexOf(this.openMenu)
     this.show(menus[(index + dir + menus.length) % menus.length], true)
   }
 
+  // The bar's single tab stop (APG menubar): `current` keeps tabindex 0,
+  // every other trigger gets -1.
+  applyRoving(current = null) {
+    const triggers = this.menuTargets.map((menu) => this.trigger(menu)).filter(Boolean)
+    if (triggers.length === 0) return
+    if (!current || !triggers.includes(current)) {
+      current = triggers.find((t) => t.getAttribute("tabindex") === "0") ?? triggers[0]
+    }
+    triggers.forEach((t) => t.setAttribute("tabindex", t === current ? "0" : "-1"))
+  }
+
+  trigger(menu) {
+    return menu?.querySelector("[aria-expanded], a, button, [tabindex]")
+  }
+
   panel(menu) {
     return menu.querySelector("[role=\"menu\"], .pk-menubar-content, .pk-navigation-menu-content")
   }
@@ -148,7 +249,13 @@ export default class extends Controller {
   items(menu) {
     const panel = this.panel(menu)
     if (!panel) return []
-    return [...panel.querySelectorAll("[role^=\"menuitem\"]")]
-      .filter((el) => !el.closest("[data-disabled]") && !el.closest(".pk-hidden"))
+    // getClientRects also skips rows inside a CLOSED sub panel (its
+    // display:none comes from the hover/focus-within CSS, not .pk-hidden) —
+    // focus() on those silently fails and the roving nav jams there.
+    // Nav panels hold plain links (no menu roles, matching Radix/shadcn) —
+    // fall back to them so arrow keys navigate there too.
+    const rows = [...panel.querySelectorAll("[role^=\"menuitem\"]")]
+    const list = rows.length ? rows : [...panel.querySelectorAll("a[href], button")]
+    return list.filter((el) => !el.closest("[data-disabled]") && el.getClientRects().length > 0)
   }
 }

data/app/components/phlex_kit/menubar/menubar_menu.rb

@@ -3,7 +3,10 @@ module PhlexKit
   class MenubarMenu < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-menubar-menu", data: { phlex_kit__menubar_target: "menu" } }, @attrs), &)
+      # role="none": role="menubar" only allows menuitem children in the
+      # accessibility tree — this layout wrapper must be presentational so
+      # the tree flattens to menubar > menuitem (axe: required-children).
+      div(**mix({ class: "pk-menubar-menu", role: "none", data: { phlex_kit__menubar_target: "menu" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/menubar/menubar_sub.rb

@@ -4,7 +4,12 @@ module PhlexKit
   class MenubarSub < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-menubar-sub" }, @attrs), &)
+      # syncSub mirrors the CSS-driven open state (:hover / :focus-within)
+      # onto the sub trigger's aria-expanded.
+      div(**mix({
+        class: "pk-menubar-sub",
+        data: { action: "mouseenter->phlex-kit--menubar#syncSub mouseleave->phlex-kit--menubar#syncSub focusin->phlex-kit--menubar#syncSub focusout->phlex-kit--menubar#syncSub" }
+      }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/menubar/menubar_sub_trigger.rb

@@ -6,8 +6,13 @@ module PhlexKit
       div(**mix({
         class: "pk-menubar-item pk-menubar-sub-trigger",
         role: "menuitem",
-        tabindex: "0",
-        aria: { haspopup: "menu" }
+        # -1: the roving focus reaches it via arrows (focus-within opens the
+        # sub); tabindex 0 made it a stray tab stop inside the open panel.
+        tabindex: "-1",
+        # expanded starts false; the sub is revealed by CSS (:hover /
+        # :focus-within), so MenubarSub's syncSub actions mirror that state
+        # onto this attribute.
+        aria: { haspopup: "menu", expanded: "false" }
       }, @attrs)) do
         block&.call
         render Icon.new(:chevron_right, size: nil, class: "pk-menubar-sub-chevron")

data/app/components/phlex_kit/message_scroller/message_scroller.css

@@ -11,7 +11,7 @@
   opacity: 0;
   pointer-events: none;
   transition: opacity .15s ease, transform .15s ease;
-  box-shadow: 0 2px 8px rgb(0 0 0 / .25);
+  box-shadow: 0 2px 8px color-mix(in srgb, var(--pk-shadow-color) 25%, transparent);
 }
 .pk-message-scroller-jump[data-active="true"] {
   opacity: 1;

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

@@ -65,8 +65,19 @@ export default class extends Controller {
       });
     }
 
+    // The MutationObserver only sees DOM changes — late image loads and
+    // viewport resizes also move the live edge, so keep the pin through both.
+    this.onContentGrowth = this.onContentGrowth.bind(this);
+    this.resizeObserver = new ResizeObserver(this.onContentGrowth);
+    if (this.hasContentTarget) this.resizeObserver.observe(this.contentTarget);
+    if (this.hasViewportTarget) {
+      this.resizeObserver.observe(this.viewportTarget);
+      // load doesn't bubble — capture catches images/media inside messages.
+      this.viewportTarget.addEventListener("load", this.onContentGrowth, true);
+    }
+
     // Apply the opening position after layout settles.
-    requestAnimationFrame(() => {
+    this.initialFrame = requestAnimationFrame(() => {
       this.applyDefaultPosition();
       this.updateButton();
     });
@@ -78,9 +89,22 @@ export default class extends Controller {
       this.viewportTarget.removeEventListener("wheel", this.onWheel);
       this.viewportTarget.removeEventListener("touchstart", this.onTouchStart);
       this.viewportTarget.removeEventListener("keydown", this.onKeydown);
+      this.viewportTarget.removeEventListener("load", this.onContentGrowth, true);
     }
     this.observer?.disconnect();
+    this.resizeObserver?.disconnect();
     if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
+    if (this.initialFrame) cancelAnimationFrame(this.initialFrame);
+  }
+
+  // Content/viewport geometry changed (image decoded, panel resized, …):
+  // re-pin to the live edge when following, otherwise just refresh the button.
+  onContentGrowth() {
+    if (this.programmatic) return;
+    if (this.autoScrollValue && this.following && !this.isAtEnd()) {
+      this.scrollToEnd("auto");
+    }
+    this.updateButton();
   }
 
   // --- Reader intent -------------------------------------------------------
@@ -91,17 +115,37 @@ export default class extends Controller {
     this.updateButton();
   }
 
-  // Any upward wheel is a deliberate move away from the live edge.
+  // Any upward wheel is a deliberate move away from the live edge. Any wheel
+  // during a programmatic scroll hands control straight back to the reader.
   onWheel(event) {
+    if (this.programmatic) {
+      this.interrupt();
+      return;
+    }
     if (event.deltaY < 0) this.release();
   }
 
   onTouchStart() {
     // A touch that turns into an upward drag surfaces through onScroll; this
     // just makes the release feel immediate when the reader grabs the list.
+    if (this.programmatic) {
+      this.interrupt();
+      return;
+    }
     if (!this.isAtEnd()) this.release();
   }
 
+  // Cancel an in-flight programmatic scroll and release the pin — the
+  // reader's wheel/touch always wins over our 300ms animation.
+  interrupt() {
+    if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
+    this.programmatic = false;
+    this.element.removeAttribute("data-autoscrolling");
+    this.viewportTarget?.removeAttribute("data-autoscrolling");
+    this.following = false;
+    this.updateButton();
+  }
+
   onKeydown(event) {
     const navKeys = ["ArrowUp", "PageUp", "Home", "ArrowDown", "PageDown", "End", " "];
     if (navKeys.includes(event.key)) this.release();

data/app/components/phlex_kit/native_select/native_select.css

@@ -61,7 +61,7 @@
 .pk-native-select-icon {
   position: absolute;
   top: 50%;
-  right: .625rem;
+  inset-inline-end: .625rem;
   transform: translateY(-50%);
   display: flex;
   pointer-events: none;

data/app/components/phlex_kit/navigation_menu/navigation_menu.css

@@ -39,7 +39,10 @@
   position-anchor: --pk-nav-item;
   inset: auto;
   position-area: block-end span-inline-end;
-  position-try-fallbacks: flip-block;
+  /* flip-inline too: a 16rem panel on an item near the right viewport edge
+     otherwise clips (same bug class popover fixed in #38). The hover
+     bridges span the block-axis gap, which flip-inline doesn't change. */
+  position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline;
   /* the [popover] UA style sets overflow:auto, which would clip the
      negative-offset ::before bridge below */
   overflow: visible;
@@ -54,7 +57,7 @@
   background: var(--pk-surface);
   color: var(--pk-text);
   padding: .25rem;
-  box-shadow: 0 8px 24px rgb(0 0 0 / .3);
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent);
 }
 .pk-navigation-menu-content .pk-navigation-menu-link {
   display: flex;
@@ -65,7 +68,12 @@
   align-items: flex-start;
   gap: .25rem;
 }
-/* Gap bridges on both sides — a flip fallback puts the gap below. */
+/* Gap bridges on both sides — a flip fallback puts the gap below. They only
+   exist while the panel is open (the closed panel is display:none) and are
+   already sized to the actual gap; the ~7px hit-area spill on the non-gap
+   side is the accepted cost: CSS has no selector for which position-try
+   fallback applied, so we can't scope the bridge to the active side, and
+   pointer-events:none would defeat the mouseleave continuity they exist for. */
 .pk-navigation-menu-content::before {
   content: "";
   position: absolute;

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

@@ -15,7 +15,12 @@ module PhlexKit
         data: {
           controller: "phlex-kit--menubar",
           hover_open: true,
-          action: "click@window->phlex-kit--menubar#onClickOutside keydown.esc->phlex-kit--menubar#close mouseleave->phlex-kit--menubar#closeSoon"
+          # onKeydown (not keydown.esc->close): the shared handler drives
+          # arrow-key navigation over the panels AND closes on Escape with
+          # focus returned to the trigger (bare #close as an action received
+          # the event as `opts`, so refocus never happened — focus fell to
+          # <body> when the panel hid).
+          action: "click@window->phlex-kit--menubar#onClickOutside keydown->phlex-kit--menubar#onKeydown mouseleave->phlex-kit--menubar#closeSoon"
         }
       }, @attrs), &)
     end

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

@@ -6,7 +6,7 @@ module PhlexKit
       button(**mix({
         type: :button,
         class: "pk-navigation-menu-trigger",
-        aria: { haspopup: "menu", expanded: "false" },
+        aria: { expanded: "false" }, # no haspopup="menu": the panel deliberately has no menu role (matching Radix/shadcn)
         data: { action: "click->phlex-kit--menubar#toggle mouseenter->phlex-kit--menubar#switch" }
       }, @attrs)) do
         block&.call

data/app/components/phlex_kit/pagination/pagination.css

@@ -6,7 +6,7 @@
 .pk-pagination-content { display: flex; flex-direction: row; align-items: center; gap: .125rem; list-style: none; margin: 0; padding: 0; }
 .pk-pagination-ellipsis { display: flex; height: 2rem; width: 2rem; align-items: center; justify-content: center; }
 .pk-pagination-ellipsis > svg { width: 1rem; height: 1rem; }
-.pk-button.pk-pagination-previous { padding-left: .375rem; }
-.pk-button.pk-pagination-next { padding-right: .375rem; }
+.pk-button.pk-pagination-previous { padding-inline-start: .375rem; }
+.pk-button.pk-pagination-next { padding-inline-end: .375rem; }
 .pk-pagination-label { display: none; }
 @media (min-width: 640px) { .pk-pagination-label { display: block; } }