phlex_kit 0.5.1 → 0.6.1

data/app/components/phlex_kit/hover_card/hover_card_controller.js

@@ -1,11 +1,25 @@
 import { Controller } from "@hotwired/stimulus"
 
-// Connects to data-controller="phlex-kit--hover-card". Show on hover/focus with a
-// small open/close delay. CSS positions the card under the trigger.
+// Connects to data-controller="phlex-kit--hover-card". Show on hover/focus
+// with a small open/close delay. The panel is a native [popover=manual]
+// (top layer; manual because the controller owns open/close — hover
+// semantics want no light dismiss), anchor-positioned by hover_card.css.
 export default class extends Controller {
-  static targets = ["content"]
+  static targets = ["trigger", "content"]
   static values = { openDelay: { type: Number, default: 200 }, closeDelay: { type: Number, default: 200 } }
-  show() { clearTimeout(this.t); this.t = setTimeout(() => { this.contentTarget.classList.remove("pk-hidden"); this.contentTarget.dataset.state = "open" }, this.openDelayValue) }
-  hide() { clearTimeout(this.t); this.t = setTimeout(() => { this.contentTarget.classList.add("pk-hidden"); this.contentTarget.dataset.state = "closed" }, this.closeDelayValue) }
+  show() {
+    clearTimeout(this.t)
+    this.t = setTimeout(() => {
+      if (!this.contentTarget.matches(":popover-open")) this.contentTarget.showPopover()
+      this.contentTarget.dataset.state = "open"
+    }, this.openDelayValue)
+  }
+  hide() {
+    clearTimeout(this.t)
+    this.t = setTimeout(() => {
+      if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover()
+      this.contentTarget.dataset.state = "closed"
+    }, this.closeDelayValue)
+  }
   disconnect() { clearTimeout(this.t) }
 }

data/app/components/phlex_kit/input_group/input_group_addon.rb

@@ -17,7 +17,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-input-group-addon #{ALIGNS.fetch(@align)}", role: "group" }, @attrs), &)
+      div(**mix({ class: "pk-input-group-addon #{fetch_option(ALIGNS, @align, :align)}", role: "group" }, @attrs), &)
     end
   end
 end

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

@@ -6,16 +6,19 @@ module PhlexKit
   # InputOtpGroup(InputOtpSlot…) [+ InputOtpSeparator + more groups]; slot
   # count must total `length:`. `.pk-input-otp*` (input_otp.css).
   class InputOtp < BaseComponent
-    def initialize(length: 6, name: nil, value: nil, **attrs)
+    def initialize(length: 6, name: nil, value: nil, label: "One-time code", **attrs)
       @length = length
       @name = name
       @value = value
+      @label = label
       @attrs = attrs
     end
 
     def view_template(&block)
       div(**mix({
         class: "pk-input-otp",
+        role: "group",
+        aria: { label: @label },
         data: {
           controller: "phlex-kit--input-otp",
           phlex_kit__input_otp_length_value: @length

data/app/components/phlex_kit/input_otp/input_otp_controller.js

@@ -10,6 +10,13 @@ export default class extends Controller {
   static values = { length: Number }
 
   connect() {
+    // Slots compose without knowing their position — label them here so AT
+    // announces "Digit N of M" instead of anonymous edit fields.
+    this.slotTargets.forEach((slot, i) => {
+      if (!slot.hasAttribute("aria-label")) {
+        slot.setAttribute("aria-label", `Digit ${i + 1} of ${this.slotTargets.length}`)
+      }
+    })
     this.syncValue()
   }
 
@@ -39,7 +46,11 @@ export default class extends Controller {
 
   onPaste(e) {
     e.preventDefault()
-    const chars = (e.clipboardData?.getData("text") || "").replace(/\s/g, "").split("")
+    let text = (e.clipboardData?.getData("text") || "").replace(/\s/g, "")
+    // Numeric slots reject non-digits on typing; pasted text like
+    // "code: 123456" should distribute only the digits.
+    if (e.target.getAttribute("inputmode") === "numeric") text = text.replace(/\D/g, "")
+    const chars = text.split("")
     if (!chars.length) return
     const start = this.slotTargets.indexOf(e.target)
     this.slotTargets.slice(start).forEach((slot, i) => { if (chars[i] != null) slot.value = chars[i] })

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

@@ -17,7 +17,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      classes = [ "pk-item", VARIANTS.fetch(@variant), SIZES.fetch(@size) ].compact.join(" ")
+      classes = [ "pk-item", fetch_option(VARIANTS, @variant, :variant), fetch_option(SIZES, @size, :size) ].compact.join(" ")
       if @href
         a(**mix({ class: classes, href: @href }, @attrs), &)
       else

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

@@ -11,7 +11,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      div(**mix({ class: [ "pk-item-media", VARIANTS.fetch(@variant) ].compact.join(" ") }, @attrs), &)
+      div(**mix({ class: [ "pk-item-media", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" ") }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/link/link.rb

@@ -41,7 +41,7 @@ module PhlexKit
     private
 
     def classes
-      [ "pk-button", VARIANTS.fetch(@variant), SIZES.fetch(@size), ("icon" if @icon) ].compact.join(" ")
+      [ "pk-button", fetch_option(VARIANTS, @variant, :variant), fetch_option(SIZES, @size, :size), ("icon" if @icon) ].compact.join(" ")
     end
   end
 end

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

@@ -15,7 +15,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      classes = [ "pk-marker", VARIANTS.fetch(@variant) ].compact.join(" ")
+      classes = [ "pk-marker", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" ")
       if @href
         a(**mix({ class: classes, href: @href }, @attrs), &)
       elsif @as == :button

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

@@ -13,7 +13,7 @@
   background: var(--pk-surface);
   padding: 3px;
 }
-.pk-menubar-menu { position: relative; }
+.pk-menubar-menu { anchor-name: --pk-menubar-menu; anchor-scope: --pk-menubar-menu; }
 .pk-menubar-trigger {
   display: flex;
   align-items: center;
@@ -31,12 +31,16 @@
 .pk-menubar-trigger:hover,
 .pk-menubar-trigger[aria-expanded="true"] { background: var(--pk-surface-2); }
 .pk-menubar-content {
-  position: absolute;
-  top: 100%;
-  left: 0;
-  z-index: 50;
+  position: fixed;
+  position-anchor: --pk-menubar-menu;
+  inset: auto;
+  position-area: block-end span-inline-end;
+  position-try-fallbacks: flip-block;
+  /* the [popover] UA style sets overflow:auto, which would clip the
+     negative-offset ::before/::after bridges below */
+  overflow: visible;
   min-width: 9rem;
-  margin-top: .5rem;
+  margin: .5rem 0 0;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: var(--pk-radius);
   background: var(--pk-surface);
@@ -44,7 +48,8 @@
   padding: .25rem;
   box-shadow: 0 8px 24px rgb(0 0 0 / .3);
 }
-/* Hover bridge over the trigger→panel gap. */
+/* Hover bridge over the trigger→panel gap — both sides, since a flip
+   fallback puts the gap below the panel instead of above. */
 .pk-menubar-content::before {
   content: "";
   position: absolute;
@@ -53,6 +58,14 @@
   right: 0;
   height: calc(.5rem + 1px);
 }
+.pk-menubar-content::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: calc(.5rem + 1px);
+}
 .pk-menubar-item {
   display: flex;
   align-items: center;
@@ -110,16 +123,22 @@
   box-shadow: 0 0 0 2px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
 
-/* Submenu: trigger row + side panel, revealed on hover/focus — pure CSS. */
-.pk-menubar-sub { position: relative; }
+/* 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-content {
-  position: absolute;
-  top: -0.25rem;
-  left: 100%;
-  z-index: 60;
+  position: fixed;
+  position-anchor: --pk-menubar-sub;
+  inset: auto;
+  position-area: inline-end span-block-end;
+  margin-top: -0.25rem;
+  position-try-fallbacks: flip-inline;
   min-width: 9rem;
-  padding-left: .25rem; /* hover bridge over the gap */
+  /* hover bridge over the gap — symmetric because flip tactics flip
+     margins/insets but not padding, so the flipped side needs one too */
+  padding: 0 .25rem;
   display: none;
 }
 .pk-menubar-sub-viewport {
@@ -135,3 +154,6 @@
 .pk-menubar-sub:focus-within > .pk-menubar-sub-content { display: block; }
 .pk-menubar-sub:hover > .pk-menubar-sub-trigger,
 .pk-menubar-sub:focus-within > .pk-menubar-sub-trigger { background: var(--pk-accent); }
+/* Hiding must survive author display values (a host class like
+   display:grid would beat the UA [popover] { display: none }). */
+.pk-menubar-content:not(:popover-open) { display: none; }

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

@@ -16,7 +16,7 @@ module PhlexKit
         role: "menubar",
         data: {
           controller: "phlex-kit--menubar",
-          action: "click@window->phlex-kit--menubar#onClickOutside keydown.esc->phlex-kit--menubar#close"
+          action: "click@window->phlex-kit--menubar#onClickOutside keydown->phlex-kit--menubar#onKeydown"
         }
       }, @attrs), &)
     end

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

@@ -13,9 +13,12 @@ module PhlexKit
     def view_template(&block)
       label(**mix({
         class: "pk-menubar-item pk-menubar-checkbox-item",
-        role: "menuitemcheckbox"
+        role: "menuitemcheckbox",
+        tabindex: "-1",
+        aria: { checked: @checked ? "true" : "false" }
       }, @attrs)) do
-        input(type: :checkbox, class: "pk-menubar-item-input", name: @name, value: @value, checked: @checked)
+        input(type: :checkbox, class: "pk-menubar-item-input", name: @name, value: @value, checked: @checked,
+              tabindex: "-1", data: { action: "change->phlex-kit--menubar#syncChecked" })
         span(class: "pk-menubar-item-indicator", aria: { hidden: "true" }) do
           render Icon.new(:check, size: nil)
         end

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

@@ -3,7 +3,7 @@ module PhlexKit
   class MenubarContent < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-menubar-content pk-hidden", role: "menu" }, @attrs), &)
+      div(**mix({ class: "pk-menubar-content", popover: "manual", role: "menu" }, @attrs), &)
     end
   end
 end

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

@@ -1,15 +1,26 @@
 import { Controller } from "@hotwired/stimulus"
 
-// PhlexKit's stand-in for Radix behind shadcn's Menubar and NavigationMenu:
-// click (or hover, for nav menus) opens a menu's panel; while one is open,
+// PhlexKit's stand-in for Radix behind shadcn's Menubar and NavigationMenu.
+// Panels are native [popover=manual] elements (manual: this controller owns
+// open/close), anchor-positioned per menu with viewport-edge flipping by
+// menubar.css / navigation_menu.css.
+// Click (or hover, for nav menus) opens a menu's panel; while one is open,
 // hovering a sibling trigger switches to it; Escape/outside/item click closes.
+// Keyboard (menubar mode): ArrowDown on a trigger opens its menu focusing the
+// first item; ArrowDown/ArrowUp/Home/End rove over the open menu's items
+// (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"
 export default class extends Controller {
   static targets = ["menu"]
 
+  initialize() {
+    this.openMenu = null
+  }
+
   toggle(e) {
     const menu = e.currentTarget.closest("[data-phlex-kit--menubar-target=\"menu\"]")
-    this.openMenu === menu ? this.close() : this.show(menu)
+    this.openMenu === menu ? this.close() : this.show(menu, true)
   }
 
   // Hover: switches between menus while one is open (menubar), or opens
@@ -20,24 +31,101 @@ export default class extends Controller {
     if (this.openMenu && this.openMenu !== menu) this.show(menu)
   }
 
-  show(menu) {
-    if (this.openMenu === menu) return
-    this.close()
-    menu.querySelector("[role=\"menu\"], .pk-menubar-content, .pk-navigation-menu-content")?.classList.remove("pk-hidden")
-    menu.querySelector("[aria-expanded]")?.setAttribute("aria-expanded", "true")
-    this.openMenu = menu
+  show(menu, focus = false) {
+    if (this.openMenu !== menu) {
+      this.close()
+      this.panel(menu)?.showPopover()
+      menu.querySelector("[aria-expanded]")?.setAttribute("aria-expanded", "true")
+      this.openMenu = menu
+    }
+    if (focus) this.items(menu)[0]?.focus()
   }
 
-  close() {
+  close(opts = {}) {
     const menu = this.openMenu
     if (!menu) return
-    menu.querySelector("[role=\"menu\"], .pk-menubar-content, .pk-navigation-menu-content")?.classList.add("pk-hidden")
-    menu.querySelector("[aria-expanded]")?.setAttribute("aria-expanded", "false")
+    const panel = this.panel(menu)
+    if (panel?.matches(":popover-open")) panel.hidePopover()
+    const trigger = menu.querySelector("[aria-expanded]")
+    trigger?.setAttribute("aria-expanded", "false")
     this.openMenu = null
+    if (opts.refocus === true) trigger?.focus()
   }
 
   onClickOutside(e) {
     if (this.element.contains(e.target)) return
     this.close()
   }
+
+  // Single keydown listener on the bar (wired via data-action, so no manual
+  // 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)
+      return
+    }
+    const items = this.items(this.openMenu)
+    const index = items.indexOf(document.activeElement)
+    switch (e.key) {
+      case "Escape":
+        e.preventDefault()
+        this.close({ refocus: true })
+        break
+      case "ArrowDown":
+        e.preventDefault()
+        items[(index + 1) % items.length]?.focus()
+        break
+      case "ArrowUp":
+        e.preventDefault()
+        items[index < 0 ? items.length - 1 : (index - 1 + items.length) % items.length]?.focus()
+        break
+      case "Home":
+        e.preventDefault()
+        items[0]?.focus()
+        break
+      case "End":
+        e.preventDefault()
+        items[items.length - 1]?.focus()
+        break
+      case "ArrowRight":
+        e.preventDefault()
+        this.shift(1)
+        break
+      case "ArrowLeft":
+        e.preventDefault()
+        this.shift(-1)
+        break
+    }
+  }
+
+  // Mirrors a checkbox/radio item's native input state onto the item's
+  // aria-checked (radios also reset their group's siblings).
+  syncChecked(e) {
+    const input = e.target
+    const group = input.name
+      ? this.element.querySelectorAll(`input[name="${CSS.escape(input.name)}"]`)
+      : [input]
+    group.forEach((i) => i.closest("[role^=\"menuitem\"]")?.setAttribute("aria-checked", i.checked))
+  }
+
+  shift(dir) {
+    const menus = this.menuTargets
+    const index = menus.indexOf(this.openMenu)
+    this.show(menus[(index + dir + menus.length) % menus.length], true)
+  }
+
+  panel(menu) {
+    return menu.querySelector("[role=\"menu\"], .pk-menubar-content, .pk-navigation-menu-content")
+  }
+
+  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"))
+  }
 }

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

@@ -1,16 +1,18 @@
 module PhlexKit
   # Menu row (an <a> — pass href:, or as: :div for buttons). `variant:
   # :destructive` tints red; `inset: true` aligns with checkbox/radio rows.
-  # Closes the bar. See menubar.rb.
+  # Closes the bar. `disabled: true` marks the row inert (skipped by roving
+  # focus, pointer-events off). See menubar.rb.
   class MenubarItem < BaseComponent
     VARIANTS = { default: nil, destructive: "destructive" }.freeze
 
-    def initialize(as: :a, href: "#", shortcut: nil, variant: :default, inset: false, **attrs)
+    def initialize(as: :a, href: "#", shortcut: nil, variant: :default, inset: false, disabled: false, **attrs)
       @as = as.to_sym
       @href = href
       @shortcut = shortcut
       @variant = variant.to_sym
       @inset = inset
+      @disabled = disabled
       @attrs = attrs
     end
 
@@ -18,10 +20,11 @@ module PhlexKit
       base = {
         role: "menuitem",
         tabindex: "-1",
-        class: [ "pk-menubar-item", VARIANTS.fetch(@variant), ("inset" if @inset) ].compact.join(" "),
-        data: { action: "click->phlex-kit--menubar#close" }
+        class: [ "pk-menubar-item", fetch_option(VARIANTS, @variant, :variant), ("inset" if @inset) ].compact.join(" "),
+        data: @disabled ? { disabled: "true" } : { action: "click->phlex-kit--menubar#close" }
       }
-      base[:href] = @href unless @as == :div
+      base[:aria] = { disabled: "true" } if @disabled
+      base[:href] = @href unless @as == :div || @disabled
       send(@as, **mix(base, @attrs)) do
         block&.call
         span(class: "pk-menubar-shortcut") { @shortcut } if @shortcut

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

@@ -13,9 +13,12 @@ module PhlexKit
     def view_template(&block)
       label(**mix({
         class: "pk-menubar-item pk-menubar-radio-item",
-        role: "menuitemradio"
+        role: "menuitemradio",
+        tabindex: "-1",
+        aria: { checked: @checked ? "true" : "false" }
       }, @attrs)) do
-        input(type: :radio, class: "pk-menubar-item-input", name: @name, value: @value, checked: @checked)
+        input(type: :radio, class: "pk-menubar-item-input", name: @name, value: @value, checked: @checked,
+              tabindex: "-1", data: { action: "change->phlex-kit--menubar#syncChecked" })
         span(class: "pk-menubar-item-indicator", aria: { hidden: "true" }) do
           # A filled selection dot is geometry, not icon-library vocabulary.
           svg(xmlns: "http://www.w3.org/2000/svg", viewbox: "0 0 24 24", fill: "currentColor") do |s|

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

@@ -6,6 +6,7 @@ module PhlexKit
       button(**mix({
         type: :button,
         class: "pk-menubar-trigger",
+        role: "menuitem",
         aria: { haspopup: "menu", expanded: "false" },
         data: { action: "click->phlex-kit--menubar#toggle mouseenter->phlex-kit--menubar#switch" }
       }, @attrs), &)

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

@@ -42,7 +42,7 @@ module PhlexKit
     private
 
     def classes
-      [ "pk-native-select-field", SIZES.fetch(@size) ].compact.join(" ")
+      [ "pk-native-select-field", fetch_option(SIZES, @size, :size) ].compact.join(" ")
     end
   end
 end

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

@@ -9,7 +9,7 @@
   padding: 0;
   list-style: none;
 }
-.pk-navigation-menu-item { position: relative; }
+.pk-navigation-menu-item { anchor-name: --pk-nav-item; anchor-scope: --pk-nav-item; }
 .pk-navigation-menu-trigger, .pk-navigation-menu-link {
   display: inline-flex;
   align-items: center;
@@ -35,15 +35,20 @@
 .pk-navigation-menu-chevron { width: .75rem; height: .75rem; transition: transform .2s ease; }
 .pk-navigation-menu-trigger[aria-expanded="true"] .pk-navigation-menu-chevron { transform: rotate(180deg); }
 .pk-navigation-menu-content {
-  position: absolute;
+  position: fixed;
+  position-anchor: --pk-nav-item;
+  inset: auto;
+  position-area: block-end span-inline-end;
+  position-try-fallbacks: flip-block;
+  /* the [popover] UA style sets overflow:auto, which would clip the
+     negative-offset ::before bridge below */
+  overflow: visible;
   /* invisible bridge over the gap so hovering toward the panel doesn't
-     mouseleave the nav and close it */
+     mouseleave the nav and close it (the panel stays a DOM descendant of
+     the nav even in the top layer, so :hover/mouseleave still track it) */
   --pk-nav-gap: .375rem;
-  top: 100%;
-  left: 0;
-  z-index: 50;
   min-width: 16rem;
-  margin-top: var(--pk-nav-gap);
+  margin: var(--pk-nav-gap) 0 0;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: var(--pk-radius);
   background: var(--pk-surface);
@@ -60,6 +65,7 @@
   align-items: flex-start;
   gap: .25rem;
 }
+/* Gap bridges on both sides — a flip fallback puts the gap below. */
 .pk-navigation-menu-content::before {
   content: "";
   position: absolute;
@@ -68,3 +74,14 @@
   right: 0;
   height: calc(var(--pk-nav-gap) + 1px);
 }
+.pk-navigation-menu-content::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: calc(var(--pk-nav-gap) + 1px);
+}
+/* Hiding must survive author display values (a host class like
+   display:grid would beat the UA [popover] { display: none }). */
+.pk-navigation-menu-content:not(:popover-open) { display: none; }

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

@@ -3,7 +3,9 @@ module PhlexKit
   class NavigationMenuContent < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-navigation-menu-content pk-hidden", role: "menu" }, @attrs), &)
+      # No role="menu" here — the panel holds plain links, not menuitems
+      # (Radix/shadcn ship no menu role on NavigationMenu content either).
+      div(**mix({ class: "pk-navigation-menu-content", popover: "manual" }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/popover/popover.css

@@ -1,12 +1,21 @@
-/* Co-located with popover.rb. CSS-positioned panel matched to nova: w-72,
-   rounded-lg, p-2.5 with a gap-2.5 column, foreground-tint ring, text-sm;
-   Header (title + muted description) stacks at gap-0.5. `align: :end`
-   flips the panel to the trigger's end edge. Tokens global. */
-.pk-popover { position: relative; display: inline-block; }
-.pk-popover-trigger { display: inline-block; }
+/* Co-located with popover.rb. Panel matched to nova: w-72, rounded-lg,
+   p-2.5 with a gap-2.5 column, foreground-tint ring, text-sm; Header
+   (title + muted description) stacks at gap-0.5. `align: :end` flips the
+   panel to the trigger's end edge. Tokens global.
+   The panel is a native [popover] in the top layer, anchor-positioned to
+   the trigger (Baseline 2026); position-try-fallbacks flips it above the
+   trigger when it would overflow the viewport bottom. anchor-scope keeps
+   sibling popovers from resolving to each other's anchors. */
+.pk-popover { display: inline-block; anchor-scope: --pk-popover; }
+.pk-popover-trigger { display: inline-block; anchor-name: --pk-popover; }
 .pk-popover-content {
-  position: absolute; z-index: 50; top: calc(100% + .25rem); left: 0;
-  display: flex; flex-direction: column; gap: .625rem;
+  position: fixed;
+  position-anchor: --pk-popover;
+  inset: auto;
+  position-area: block-end span-inline-end;
+  margin: .25rem 0 0;
+  position-try-fallbacks: flip-block;
+  flex-direction: column; gap: .625rem;
   width: 18rem;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: var(--pk-radius);
@@ -14,7 +23,13 @@
   font-size: .875rem;
   box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
 }
-.pk-popover-content.end { left: auto; right: 0; }
+/* display must be gated on :popover-open — an unconditional author
+   `display: flex` would beat the UA's [popover] { display: none }. */
+.pk-popover-content:popover-open { display: flex; }
+.pk-popover-content.end { position-area: block-end span-inline-start; }
 .pk-popover-header { display: flex; flex-direction: column; gap: .125rem; font-size: .875rem; }
 .pk-popover-title { margin: 0; font-size: .875rem; font-weight: 500; }
 .pk-popover-description { margin: 0; color: var(--pk-muted); }
+/* Hiding must survive author display values (a host class like
+   display:grid would beat the UA [popover] { display: none }). */
+.pk-popover-content:not(:popover-open) { display: none; }

data/app/components/phlex_kit/popover/popover.rb

@@ -1,5 +1,6 @@
 module PhlexKit
-  # Click-triggered floating panel, positioned with CSS (no @floating-ui). Ported
+  # Click-triggered floating panel — native [popover] + CSS anchor
+  # positioning with viewport-edge flipping (no @floating-ui). Ported
   # from ruby_ui's RubyUI::Popover. Compose Popover > (PopoverTrigger +
   # PopoverContent). phlex-kit--popover.
   class Popover < BaseComponent

data/app/components/phlex_kit/popover/popover_content.rb

@@ -1,6 +1,8 @@
 module PhlexKit
-  # The floating panel of a PhlexKit::Popover. `align: :end` flips it to the
-  # trigger's end edge (their align prop). See popover.rb.
+  # The floating panel of a PhlexKit::Popover — a native [popover=auto]
+  # element (top layer, browser light dismiss) anchor-positioned to the
+  # trigger with viewport-edge flipping (popover.css). `align: :end` flips it
+  # to the trigger's end edge (their align prop). See popover.rb.
   class PopoverContent < BaseComponent
     ALIGNS = { start: nil, end: "end" }.freeze
 
@@ -10,8 +12,8 @@ module PhlexKit
     end
 
     def view_template(&)
-      classes = [ "pk-popover-content", "pk-hidden", ALIGNS.fetch(@align) ].compact.join(" ")
-      div(**mix({ class: classes, data: { phlex_kit__popover_target: "content", state: "closed" } }, @attrs), &)
+      classes = [ "pk-popover-content", fetch_option(ALIGNS, @align, :align) ].compact.join(" ")
+      div(**mix({ class: classes, popover: "auto", data: { phlex_kit__popover_target: "content", state: "closed" } }, @attrs), &)
     end
   end
 end

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

@@ -1,12 +1,16 @@
 import { Controller } from "@hotwired/stimulus"
 
-// Connects to data-controller="phlex-kit--popover". Click to toggle; click
-// outside to close. CSS positions the panel under the trigger.
+// Connects to data-controller="phlex-kit--popover". The panel is a native
+// [popover=auto] — the browser owns light dismiss + Escape; CSS anchor
+// positioning places it (popover.css). Light dismiss fires on pointerdown
+// outside the panel, so a click on the trigger would close-then-reopen:
+// armToggle records the open state at pointerdown and toggle skips the
+// reopen.
 export default class extends Controller {
-  static targets = ["content"]
-  connect() { this.onDoc = (e) => { if (!this.element.contains(e.target)) this.hide() } }
-  disconnect() { document.removeEventListener("click", this.onDoc) }
-  toggle(e) { e?.preventDefault(); this.contentTarget.classList.contains("pk-hidden") ? this.show() : this.hide() }
-  show() { this.contentTarget.classList.remove("pk-hidden"); this.contentTarget.dataset.state = "open"; document.addEventListener("click", this.onDoc) }
-  hide() { this.contentTarget.classList.add("pk-hidden"); this.contentTarget.dataset.state = "closed"; document.removeEventListener("click", this.onDoc) }
+  static targets = ["trigger", "content"]
+  armToggle() { this.wasOpen = this.contentTarget.matches(":popover-open") }
+  toggle(e) { e?.preventDefault(); if (this.wasOpen) return; this.contentTarget.showPopover() }
+  contentTargetConnected(el) {
+    el.addEventListener("toggle", (e) => { el.dataset.state = e.newState === "open" ? "open" : "closed" })
+  }
 }