phlex_kit 0.5.1 → 0.6.1

data/app/components/phlex_kit/context_menu/context_menu.css

@@ -1,10 +1,13 @@
-/* Co-located with context_menu.rb. CSS-positioned at the cursor. Matches the
-   dropdown-menu grammar (shadcn's context menu shares the same part set):
-   gap-based rows, destructive variant, hidden-input checkbox/radio rows with
-   :has() indicators, pure-CSS hover submenus. Tokens global. */
-.pk-context-menu { position: relative; }
+/* Co-located with context_menu.rb. The panel is a native [popover=manual] in
+   the top layer, placed at the cursor in viewport coordinates and clamped by
+   the controller (a cursor point isn't an element, so it can't use anchor
+   positioning). Submenus DO anchor to their row and flip at the viewport
+   right edge. Matches the dropdown-menu grammar (shadcn's context menu
+   shares the same part set): gap-based rows, destructive variant,
+   hidden-input checkbox/radio rows with :has() indicators, pure-CSS hover
+   submenus. Tokens global. */
 .pk-context-menu-content {
-  position: absolute; z-index: 50; min-width: 8rem; overflow: visible;
+  position: fixed; inset: auto; margin: 0; min-width: 8rem; overflow: visible;
   border: 1px solid var(--pk-border); border-radius: calc(var(--pk-radius) - 2px); background: var(--pk-surface);
   color: var(--pk-text); padding: .25rem; box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
 }
@@ -64,16 +67,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-context-menu-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-context-menu-sub { anchor-name: --pk-context-menu-sub; anchor-scope: --pk-context-menu-sub; }
 .pk-context-menu-sub-chevron { margin-left: auto; width: 1rem; height: 1rem; }
 .pk-context-menu-sub-content {
-  position: absolute;
-  top: -0.25rem;
-  left: 100%;
-  z-index: 60;
+  position: fixed;
+  position-anchor: --pk-context-menu-sub;
+  inset: auto;
+  position-area: inline-end span-block-end;
+  margin-top: -0.25rem;
+  position-try-fallbacks: flip-inline;
   min-width: 10rem;
-  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-context-menu-sub-viewport {
@@ -89,3 +98,6 @@
 .pk-context-menu-sub:focus-within > .pk-context-menu-sub-content { display: block; }
 .pk-context-menu-sub:hover > .pk-context-menu-sub-trigger,
 .pk-context-menu-sub:focus-within > .pk-context-menu-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-context-menu-content:not(:popover-open) { display: none; }

data/app/components/phlex_kit/context_menu/context_menu_content.rb

@@ -2,7 +2,7 @@ module PhlexKit
   class ContextMenuContent < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-context-menu-content pk-hidden", role: "menu", tabindex: "-1", aria: { orientation: "vertical" }, data: { phlex_kit__context_menu_target: "content", state: "closed" } }, @attrs), &)
+      div(**mix({ class: "pk-context-menu-content", popover: "manual", role: "menu", tabindex: "-1", aria: { orientation: "vertical" }, data: { phlex_kit__context_menu_target: "content", state: "closed" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/context_menu/context_menu_controller.js

@@ -1,28 +1,87 @@
 import { Controller } from "@hotwired/stimulus"
 
-// Connects to data-controller="phlex-kit--context-menu". Opens at the cursor on
-// contextmenu; closes on outside click or Escape. CSS positioning (no floating-ui).
+// Connects to data-controller="phlex-kit--context-menu". Opens at the cursor
+// on contextmenu (at the trigger's rect for the keyboard Menu key / Shift+F10,
+// which fire with clientX/Y of 0) and focuses the first item; ArrowDown/
+// ArrowUp/Home/End rove over the items (skipping [data-disabled]); closes on
+// outside click or Escape, returning focus to the trigger. The panel is a
+// native [popover=manual] in the top layer (context_menu.css); it is placed
+// in viewport coordinates after showPopover() — a hidden popover has no
+// size — and clamped so it never overflows the viewport (no floating-ui).
 export default class extends Controller {
-  static targets = ["content"]
+  static targets = ["content", "trigger", "menuItem"]
+
   connect() {
     this.onDoc = (e) => { if (!this.contentTarget.contains(e.target)) this.close() }
-    this.onKey = (e) => { if (e.key === "Escape") this.close() }
+    this.onKey = (e) => this.keydown(e)
   }
-  disconnect() { document.removeEventListener("click", this.onDoc); document.removeEventListener("keydown", this.onKey) }
+
+  disconnect() {
+    document.removeEventListener("click", this.onDoc)
+    document.removeEventListener("keydown", this.onKey)
+  }
+
   open(e) {
     e.preventDefault()
-    const r = this.element.getBoundingClientRect()
-    this.contentTarget.style.left = `${e.clientX - r.left}px`
-    this.contentTarget.style.top = `${e.clientY - r.top}px`
-    this.contentTarget.classList.remove("pk-hidden")
-    this.contentTarget.dataset.state = "open"
+    let x = e.clientX
+    let y = e.clientY
+    if (x === 0 && y === 0) {
+      const t = this.anchor().getBoundingClientRect()
+      x = t.left
+      y = t.bottom
+    }
+    const c = this.contentTarget
+    if (!c.matches(":popover-open")) c.showPopover()
+    x = Math.max(4, Math.min(x, window.innerWidth - c.offsetWidth - 4))
+    y = Math.max(4, Math.min(y, window.innerHeight - c.offsetHeight - 4))
+    c.style.left = `${x}px`
+    c.style.top = `${y}px`
+    c.dataset.state = "open"
     document.addEventListener("click", this.onDoc)
     document.addEventListener("keydown", this.onKey)
+    this.items()[0]?.focus()
   }
-  close() {
-    this.contentTarget.classList.add("pk-hidden")
+
+  close(opts = {}) {
+    if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover()
     this.contentTarget.dataset.state = "closed"
     document.removeEventListener("click", this.onDoc)
     document.removeEventListener("keydown", this.onKey)
+    if (opts.refocus === true) this.anchor().focus()
+  }
+
+  keydown(e) {
+    const items = this.items()
+    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
+    }
+  }
+
+  anchor() {
+    return this.hasTriggerTarget ? this.triggerTarget : this.element
+  }
+
+  items() {
+    return this.menuItemTargets.filter((el) => !el.closest("[data-disabled]") && !el.closest(".pk-hidden"))
   }
 }

data/app/components/phlex_kit/context_menu/context_menu_item.rb

@@ -17,9 +17,13 @@ module PhlexKit
     end
 
     def view_template(&block)
-      classes = [ "pk-context-menu-item", VARIANTS.fetch(@variant) ].compact.join(" ")
-      a(**mix({ href: @href, role: "menuitem", tabindex: "-1", class: classes,
-                data: { action: "click->phlex-kit--context-menu#close", phlex_kit__context_menu_target: "menuItem", disabled: @disabled } }, @attrs)) do
+      classes = [ "pk-context-menu-item", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" ")
+      base = { href: @href, role: "menuitem", tabindex: "-1", class: classes,
+               data: { action: ("click->phlex-kit--context-menu#close" unless @disabled),
+                       phlex_kit__context_menu_target: "menuItem",
+                       disabled: (@disabled ? "true" : nil) }.compact }
+      base[:aria] = { disabled: "true" } if @disabled
+      a(**mix(base, @attrs)) do
         if @checked
           span(class: "pk-context-menu-check") do
             render Icon.new(:check, size: nil)

data/app/components/phlex_kit/context_menu/context_menu_label.rb

@@ -5,7 +5,7 @@ module PhlexKit
       @attrs = attrs
     end
     def view_template(&)
-      div(**mix({ class: ["pk-context-menu-label", (@inset ? "inset" : nil)].compact.join(" ") }, @attrs), &)
+      div(**mix({ class: [ "pk-context-menu-label", (@inset ? "inset" : nil) ].compact.join(" ") }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/context_menu/context_menu_trigger.rb

@@ -2,7 +2,9 @@ module PhlexKit
   class ContextMenuTrigger < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-context-menu-trigger", data: { phlex_kit__context_menu_target: "trigger", action: "contextmenu->phlex-kit--context-menu#open" } }, @attrs), &)
+      # tabindex 0 so the keyboard context-menu key (Menu / Shift+F10) can
+      # reach it, and so Escape has somewhere to return focus to.
+      div(**mix({ class: "pk-context-menu-trigger", tabindex: "0", data: { phlex_kit__context_menu_target: "trigger", action: "contextmenu->phlex-kit--context-menu#open" } }, @attrs), &)
     end
   end
 end

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

@@ -12,7 +12,7 @@ export default class extends Controller {
     const root = this.element.closest('[data-controller~="phlex-kit--data-table"]');
     if (!root) return;
     root
-      .querySelectorAll(`[data-column="${key}"]`)
+      .querySelectorAll(`[data-column="${CSS.escape(key)}"]`)
       .forEach((el) => el.classList.toggle("pk-hidden", !visible));
   }
 }

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

@@ -10,7 +10,6 @@ export default class extends Controller {
     "selectAll",
     "rowCheckbox",
     "selectionSummary",
-    "selectionBar",
     "bulkActions",
   ];
 
@@ -45,6 +44,18 @@ export default class extends Controller {
     const total = this.rowCheckboxTargets.length;
     const selected = this.rowCheckboxTargets.filter((cb) => cb.checked).length;
 
+    // table.css styles .pk-table-row[data-state="selected"] — set it so
+    // selected rows actually get the highlight.
+    this.rowCheckboxTargets.forEach((cb) => {
+      const row = cb.closest(".pk-table-row");
+      if (!row) return;
+      if (cb.checked) {
+        row.setAttribute("data-state", "selected");
+      } else {
+        row.removeAttribute("data-state");
+      }
+    });
+
     if (this.hasSelectAllTarget) {
       this.selectAllTarget.checked = total > 0 && selected === total;
       this.selectAllTarget.indeterminate = selected > 0 && selected < total;

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

@@ -56,22 +56,24 @@ module PhlexKit
     end
 
     def prev_item
-      if current <= 1
-        li do
-          span(class: "pk-data-table-page-disabled") { @prev_label }
-        end
-      else
-        render PaginationItem.new(href: page_href(current - 1)) { @prev_label }
-      end
+      edge_item(disabled: current <= 1, href: page_href(current - 1),
+        label: @prev_label, name: "Go to previous page")
     end
 
     def next_item
-      if current >= total
+      edge_item(disabled: current >= total, href: page_href(current + 1),
+        label: @next_label, name: "Go to next page")
+    end
+
+    # The default labels are bare glyphs ("<"/">") — give AT a real name, and
+    # announce the disabled edge instead of rendering an anonymous span.
+    def edge_item(disabled:, href:, label:, name:)
+      if disabled
         li do
-          span(class: "pk-data-table-page-disabled") { @next_label }
+          span(class: "pk-data-table-page-disabled", aria: { disabled: "true", label: name }) { label }
         end
       else
-        render PaginationItem.new(href: page_href(current + 1)) { @next_label }
+        render PaginationItem.new(href: href, aria: { label: name }) { label }
       end
     end
 

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

@@ -10,6 +10,7 @@ module PhlexKit
     def view_template
       div(**mix({
         class: "pk-data-table-selection-summary",
+        role: "status", # live region — selection changes are announced to AT
         data: { phlex_kit__data_table_target: "selectionSummary" }
       }, @attrs)) do
         plain "0 of #{@total_on_page} row(s) selected."

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

@@ -15,8 +15,12 @@ module PhlexKit
       @attrs = attrs
     end
 
+    ARIA_SORT = { "asc" => "ascending", "desc" => "descending" }.freeze
+
     def view_template
-      render TableHead.new(**mix({ class: "pk-data-table-sort-head" }, @attrs)) do
+      defaults = { class: "pk-data-table-sort-head" }
+      defaults[:aria] = { sort: ARIA_SORT.fetch(current_direction) } if current_direction
+      render TableHead.new(**mix(defaults, @attrs)) do
         a(href: sort_href, class: "pk-data-table-sort-link") do
           plain @label
           sort_icon

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

@@ -1,19 +1,27 @@
 module PhlexKit
   # The <dialog> box. `size:` picks the width tier (md = shadcn's default
   # max-w-sm); `show_close_button: false` drops the top-right ✕ (their
-  # showCloseButton). See dialog.rb.
+  # showCloseButton). `labelledby:`/`describedby:` render aria-labelledby /
+  # aria-describedby for callers who assign their own ids to DialogTitle /
+  # DialogDescription; when absent, the phlex-kit--dialog controller auto-wires
+  # them in connect(). See dialog.rb.
   class DialogContent < BaseComponent
     SIZES = { xs: "xs", sm: "sm", md: nil, lg: "lg", xl: "xl", full: "full" }.freeze
 
-    def initialize(size: :md, show_close_button: true, **attrs)
+    def initialize(size: :md, show_close_button: true, labelledby: nil, describedby: nil, **attrs)
       @size = size.to_sym
       @show_close_button = show_close_button
+      @labelledby = labelledby
+      @describedby = describedby
       @attrs = attrs
     end
 
     def view_template(&block)
-      cls = [ "pk-dialog", SIZES.fetch(@size) ].compact.join(" ")
-      dialog(**mix({ class: cls, data: { phlex_kit__dialog_target: "dialog", action: "click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
+      cls = [ "pk-dialog", fetch_option(SIZES, @size, :size) ].compact.join(" ")
+      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
         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

@@ -1,14 +1,27 @@
 import { Controller } from "@hotwired/stimulus"
 
 // Connects to data-controller="phlex-kit--dialog". Ported from ruby_ui.
+// connect() auto-wires the dialog's accessible name: when the caller didn't
+// pass labelledby:/describedby: to DialogContent, the title/description parts
+// get generated ids and the <dialog> points at them.
 export default class extends Controller {
   static targets = ["dialog"]
   static values = { open: { type: Boolean, default: false } }
 
   connect() {
     this.dialogTarget.addEventListener("close", this.handleClose)
+    this.#wireAria("aria-labelledby", ".pk-dialog-title")
+    this.#wireAria("aria-describedby", ".pk-dialog-description")
     if (this.openValue) this.open()
   }
+
+  #wireAria(attr, selector) {
+    if (this.dialogTarget.getAttribute(attr)) return
+    const el = this.dialogTarget.querySelector(selector)
+    if (!el) return
+    if (!el.id) el.id = `pk-dialog-${attr.slice(5)}-${Math.random().toString(36).slice(2, 10)}`
+    this.dialogTarget.setAttribute(attr, el.id)
+  }
   disconnect() {
     this.dialogTarget.removeEventListener("close", this.handleClose)
     document.body.style.removeProperty("overflow")

data/app/components/phlex_kit/drawer/drawer_content.rb

@@ -12,9 +12,9 @@ module PhlexKit
 
     def view_template(&block)
       template(data: { phlex_kit__sheet_target: "content" }) do
-        div(data: { controller: "phlex-kit--sheet-content" }) do
+        div(data: { controller: "phlex-kit--sheet-content", action: "keydown->phlex-kit--sheet-content#keydown" }) do
           div(class: "pk-drawer-overlay", data: { action: "click->phlex-kit--sheet-content#close" })
-          div(**mix({ class: "pk-drawer #{SIDES.fetch(@side)}", role: "dialog", aria: { modal: "true" } }, @attrs)) do
+          div(**mix({ class: "pk-drawer #{fetch_option(SIDES, @side, :side)}", role: "dialog", aria: { modal: "true" }, tabindex: "-1", data: { phlex_kit__sheet_content_target: "panel" } }, @attrs)) do
             div(class: "pk-drawer-handle", aria: { hidden: "true" })
             yield if block
           end

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

@@ -1,13 +1,25 @@
 /* Co-located with dropdown_menu.rb — UI::DropdownMenu (+ Trigger / Content / Item
-   / Label / Separator). ruby_ui's structure + Stimulus kept; @floating-ui dropped
-   in favour of CSS positioning (panel below the trigger, or above with
-   `side: :top`). Tailwind → vanilla. Theme tokens come from the global stylesheet. */
-.pk-dropdown-menu { position: relative; display: inline-block; }
-.pk-dropdown-menu-trigger { display: inline-block; }
+   / Label / Separator). ruby_ui's structure + Stimulus kept; @floating-ui dropped.
+   The panel is a native [popover=manual] in the top layer, anchor-positioned to
+   the trigger (Baseline 2026); position-try-fallbacks flips it above at the
+   viewport bottom (`side: :top` starts above and flips down). Submenus anchor
+   to their row the same way and flip at the right edge. Tailwind → vanilla.
+   Theme tokens come from the global stylesheet. */
+.pk-dropdown-menu { display: inline-block; anchor-scope: --pk-dropdown-menu; }
+.pk-dropdown-menu-trigger { display: inline-block; anchor-name: --pk-dropdown-menu; }
 
-.pk-dropdown-menu-content { position: absolute; top: 100%; left: 0; z-index: 50; margin-top: 4px; }
-.pk-dropdown-menu-content-up { top: auto; bottom: 100%; margin-top: 0; margin-bottom: 4px; }
-.pk-dropdown-menu-content.hidden { display: none; }
+.pk-dropdown-menu-content {
+  position: fixed;
+  position-anchor: --pk-dropdown-menu;
+  inset: auto;
+  /* the bordered box is the inner viewport — strip the [popover] UA chrome
+     (border: solid, padding, Canvas background) from this wrapper */
+  border: 0; padding: 0; background: transparent; color: inherit; overflow: visible;
+  position-area: block-end span-inline-end;
+  margin: 4px 0 0;
+  position-try-fallbacks: flip-block;
+}
+.pk-dropdown-menu-content-up { position-area: block-start span-inline-end; margin: 0 0 4px; }
 .pk-dropdown-menu-viewport {
   min-width: 10rem;
   border-radius: calc(var(--pk-radius) - 2px);
@@ -85,19 +97,28 @@
   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-dropdown-menu-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-dropdown-menu-sub { anchor-name: --pk-dropdown-menu-sub; anchor-scope: --pk-dropdown-menu-sub; }
 .pk-dropdown-menu-sub-chevron { margin-left: auto; width: 1rem; height: 1rem; }
 .pk-dropdown-menu-sub-content {
-  position: absolute;
-  top: -0.25rem;
-  left: 100%;
-  z-index: 60;
+  position: fixed;
+  position-anchor: --pk-dropdown-menu-sub;
+  inset: auto;
+  position-area: inline-end span-block-end;
+  margin-top: -0.25rem;
+  position-try-fallbacks: flip-inline;
   min-width: 10rem;
-  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-dropdown-menu-sub:hover > .pk-dropdown-menu-sub-content,
 .pk-dropdown-menu-sub:focus-within > .pk-dropdown-menu-sub-content { display: block; }
 .pk-dropdown-menu-sub:hover > .pk-dropdown-menu-sub-trigger,
 .pk-dropdown-menu-sub:focus-within > .pk-dropdown-menu-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-dropdown-menu-content:not(:popover-open) { display: none; }

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

@@ -1,5 +1,6 @@
 module PhlexKit
-  # The dropdown panel. Hidden until the trigger toggles it. `side:` is :bottom
+  # The dropdown panel — a native [popover=manual] the trigger toggles,
+  # anchor-positioned with viewport-edge flipping. `side:` is :bottom
   # (default, opens below) or :top (opens above — for triggers near the bottom of
   # the viewport, e.g. the sidebar footer). See dropdown_menu.rb.
   class DropdownMenuContent < BaseComponent
@@ -9,7 +10,7 @@ module PhlexKit
     end
 
     def view_template(&block)
-      div(class: wrapper_classes, data: { phlex_kit__dropdown_menu_target: "content" }) do
+      div(class: wrapper_classes, popover: "manual", data: { phlex_kit__dropdown_menu_target: "content" }) do
         div(**mix({ class: "pk-dropdown-menu-viewport" }, @attrs), &block)
       end
     end
@@ -17,7 +18,7 @@ module PhlexKit
     private
 
     def wrapper_classes
-      [ "pk-dropdown-menu-content", ("pk-dropdown-menu-content-up" if @side == :top), "hidden" ].compact.join(" ")
+      [ "pk-dropdown-menu-content", ("pk-dropdown-menu-content-up" if @side == :top) ].compact.join(" ")
     end
   end
 end

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

@@ -1,10 +1,10 @@
 import { Controller } from "@hotwired/stimulus";
 
-// Ported from ruby_ui's phlex-kit--dropdown-menu controller. The ONE change from
-// upstream: the @floating-ui/dom dependency is removed — the panel is positioned
-// with plain CSS (.ui-dropdown-menu-content { position:absolute }), so this app
-// needs no npm/build step. Toggle, click-outside, and arrow/enter keyboard nav
-// are unchanged.
+// Ported from ruby_ui's phlex-kit--dropdown-menu controller, minus the
+// @floating-ui/dom dependency: the panel is a native [popover=manual] in the
+// top layer, anchor-positioned with viewport-edge flipping by
+// dropdown_menu.css (manual so this controller keeps owning click-outside,
+// Escape, and arrow/enter keyboard nav — all unchanged from upstream).
 export default class extends Controller {
   static targets = ["trigger", "content", "menuItem"];
   static values = { open: { type: Boolean, default: false } };
@@ -27,23 +27,20 @@ export default class extends Controller {
   }
 
   toggle() {
-    this.contentTarget.classList.contains("hidden") ? this.#open() : this.close();
+    this.contentTarget.matches(":popover-open") ? this.close() : this.#open();
   }
 
   #open() {
     this.openValue = true;
     this.#deselectAll();
     this.#addEventListeners();
-    // Lift the open menu above siblings (the container has no static z-index).
-    this.element.style.zIndex = "50";
-    this.contentTarget.classList.remove("hidden");
+    this.contentTarget.showPopover();
   }
 
   close() {
     this.openValue = false;
     this.#removeEventListeners();
-    this.element.style.zIndex = "";
-    this.contentTarget.classList.add("hidden");
+    if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover();
   }
 
   #handleKeydown(e) {

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

@@ -15,7 +15,7 @@ module PhlexKit
       base = {
         role: "menuitem",
         tabindex: "-1",
-        class: [ "pk-dropdown-menu-item", VARIANTS.fetch(@variant) ].compact.join(" "),
+        class: [ "pk-dropdown-menu-item", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" "),
         data: { phlex_kit__dropdown_menu_target: "menuItem", action: "click->phlex-kit--dropdown-menu#close" }
       }
       base[:href] = @href unless @as == :div

data/app/components/phlex_kit/empty/empty_media.rb

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

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

@@ -26,7 +26,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      data = { slot: "field", orientation: ORIENTATIONS.fetch(@orientation) }
+      data = { slot: "field", orientation: fetch_option(ORIENTATIONS, @orientation, :orientation) }
       data[:invalid] = "true" if @invalid
       data[:disabled] = "true" if @disabled
       div(**mix({ class: "pk-field", role: "group", data: data }, @attrs), &)

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

@@ -11,7 +11,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      legend(**mix({ class: "pk-field-legend #{VARIANTS.fetch(@variant)}" }, @attrs), &)
+      legend(**mix({ class: "pk-field-legend #{fetch_option(VARIANTS, @variant, :variant)}" }, @attrs), &)
     end
   end
 end

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

@@ -1,16 +1,35 @@
 /* Co-located with hover_card.rb. Matched to shadcn/ui's current hover-card
    (nova): 16rem popover panel, rounded-lg, p-2.5, text-sm, foreground-tint
-   ring. side: top/left/right flip the CSS position (bottom default).
-   Tokens from the global stylesheet. */
-.pk-hover-card { position: relative; display: inline-block; }
-.pk-hover-card-trigger { display: inline-block; }
+   ring. Tokens from the global stylesheet.
+   The panel is a native [popover=manual] in the top layer, anchor-positioned
+   to the trigger (Baseline 2026); position-try-fallbacks flips it to the
+   opposite side at the viewport edge. side: top/left/right pick the
+   position-area (bottom default). anchor-scope keeps sibling hover cards
+   from resolving to each other's anchors. */
+.pk-hover-card { display: inline-block; anchor-scope: --pk-hover-card; }
+.pk-hover-card-trigger { display: inline-block; anchor-name: --pk-hover-card; }
 .pk-hover-card-content {
-  position: absolute; z-index: 50; top: calc(100% + .25rem); left: 0; width: 16rem;
+  position: fixed;
+  position-anchor: --pk-hover-card;
+  inset: auto;
+  position-area: block-end span-inline-end;
+  margin: .25rem 0 0;
+  position-try-fallbacks: flip-block;
+  width: 16rem;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: var(--pk-radius); background: var(--pk-surface);
   color: var(--pk-text); padding: .625rem; font-size: .875rem;
   box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
 }
-.pk-hover-card-content.top { top: auto; bottom: calc(100% + .25rem); }
-.pk-hover-card-content.left { top: 50%; left: auto; right: calc(100% + .25rem); transform: translateY(-50%); }
-.pk-hover-card-content.right { top: 50%; left: calc(100% + .25rem); transform: translateY(-50%); }
+.pk-hover-card-content.top { position-area: block-start span-inline-end; margin: 0 0 .25rem; }
+.pk-hover-card-content.left {
+  position-area: inline-start; margin: 0 .25rem 0 0;
+  position-try-fallbacks: flip-inline;
+}
+.pk-hover-card-content.right {
+  position-area: inline-end; margin: 0 0 0 .25rem;
+  position-try-fallbacks: flip-inline;
+}
+/* Hiding must survive author display values (a host class like
+   display:grid would beat the UA [popover] { display: none }). */
+.pk-hover-card-content:not(:popover-open) { display: none; }

data/app/components/phlex_kit/hover_card/hover_card.rb

@@ -1,5 +1,6 @@
 module PhlexKit
-  # Hover/focus-triggered floating card, positioned with CSS. Ported from ruby_ui's
+  # Hover/focus-triggered floating card — native [popover] + CSS anchor
+  # positioning with viewport-edge flipping. Ported from ruby_ui's
   # RubyUI::HoverCard. Compose HoverCard > (HoverCardTrigger + HoverCardContent).
   class HoverCard < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)

data/app/components/phlex_kit/hover_card/hover_card_content.rb

@@ -10,8 +10,8 @@ module PhlexKit
     end
 
     def view_template(&)
-      classes = [ "pk-hover-card-content", "pk-hidden", SIDES.fetch(@side) ].compact.join(" ")
-      div(**mix({ class: classes, data: { phlex_kit__hover_card_target: "content", state: "closed" } }, @attrs), &)
+      classes = [ "pk-hover-card-content", fetch_option(SIDES, @side, :side) ].compact.join(" ")
+      div(**mix({ class: classes, popover: "manual", data: { phlex_kit__hover_card_target: "content", state: "closed" } }, @attrs), &)
     end
   end
 end