Add popover component

Adds a popover component built on the native HTML popover attribute:

- l-ui--popover Stimulus controller computes placement (top, bottom,
  left, right) with auto-flip near viewport edges; showing, hiding,
  light-dismiss, and Escape-to-close are handled by the browser
- l_ui_popover helper renders the trigger button, popover element, and
  Stimulus wiring, with placement, align, and container options
- l-ui-popover CSS classes, including menu variants for action lists
  (menu, menu-item, menu-item--danger, menu-divider)
- Popovers documentation page in the dummy app, plus row action menu
  examples on the tables pages
- Navigation items gain a hover background (bg-surface), with the
  active state kept above it
- Skill references updated for the new helper, classes, and controller

Author: thomasgallagher

.claude/skills/layered-ui-rails/SKILL.md

@@ -181,6 +181,7 @@ Quick reference:
 | `l_ui_theme_toggle` | Default header theme toggle button |
 | `l_ui_authentication` | Default header login/register buttons (Devise) |
 | `l_ui_navigation_toggle` | Default header sidebar toggle button |
+| `l_ui_popover(id: nil, placement: :bottom, align: :start, container: {})` | Floating panel anchored to a trigger, built on the native `popover` attribute |
 
 ## CSS classes
 
@@ -202,6 +203,7 @@ Key components:
 | Notices | `.l-ui-notice` (base), `--success`, `--warning`, `--error` |
 | Tabs | `.l-ui-tabs`, `.l-ui-tabs__list`, `.l-ui-tabs__tab`, `--active` |
 | Modal | `.l-ui-modal`, `.l-ui-modal__header`, `.l-ui-modal__body` |
+| Popover | `.l-ui-popover` |
 
 ## Stimulus controllers
 
@@ -217,6 +219,7 @@ All controllers use the `l-ui--` namespace and are auto-registered via importmap
 | Panel resize | `l-ui--panel-resize` | Panel width drag handle |
 | Modal | `l-ui--modal` | Native `<dialog>` with focus trap |
 | Tabs | `l-ui--tabs` | Accessible tabbed interface |
+| Popover | `l-ui--popover` | Positions a native `popover`-attribute element relative to its trigger, with auto-flip |
 | Search form | `l-ui--search-form` | Multi-scope search with Turbo support and pagination param preservation |
 
 ## Theming

.claude/skills/layered-ui-rails/references/CONTROLLERS.md

@@ -106,6 +106,31 @@ Accessible tabbed interface with keyboard navigation.
 </div>
 ```
 
+## Popover (`l-ui--popover`)
+
+Positions a native `popover`-attribute element relative to its trigger, with auto-flip near viewport edges. Showing, hiding, light-dismiss (outside click), and Escape-to-close are all handled by the browser via the `popover` attribute - this controller only handles placement.
+
+**Targets:** `trigger`, `popover`
+**Values:** `placement` (String, default `"bottom"`; one of `"top"`, `"bottom"`, `"left"`, `"right"`), `align` (String, default `"start"`; `"start"` or `"end"` - which edge of the popover flushes with the trigger on the cross axis)
+
+```html
+<div data-controller="l-ui--popover">
+  <button type="button" popovertarget="my-popover"
+          data-l-ui--popover-target="trigger"
+          class="l-ui-button l-ui-button--outline">
+    Open popover
+  </button>
+  <div id="my-popover" popover="auto" class="l-ui-popover"
+       data-l-ui--popover-target="popover">
+    Content here.
+  </div>
+</div>
+```
+
+Features:
+- Repositions on open, and while open on window resize/scroll
+- Flips to the opposite side if the preferred placement would overflow the viewport
+
 ## Panel (`l-ui--panel`)
 
 Resizable side panel. Full-width overlay on mobile, docked sidebar on desktop.

.claude/skills/layered-ui-rails/references/CSS.md

@@ -287,6 +287,16 @@ Always combine the base block with a modifier, e.g. `<span class="l-ui-badge l-u
 .l-ui-modal__body    Scrollable modal content
 ```
 
+## Popover
+
+```
+.l-ui-popover                    popover-attribute element; positioned by the l-ui--popover Stimulus controller
+.l-ui-popover__menu              Full-width list wrapper for a menu of actions inside a popover
+.l-ui-popover__menu-item         Full-width action link/button inside l-ui-popover__menu
+.l-ui-popover__menu-item--danger Danger styling for a destructive menu item
+.l-ui-popover__menu-divider      Horizontal rule separating groups of items (apply to an <hr>)
+```
+
 ## Breadcrumbs
 
 ```

.claude/skills/layered-ui-rails/references/HELPERS.md

@@ -322,6 +322,51 @@ The button does not need to be inside the helper's wrapper, and no `data-control
 
 Calling `dialog.showModal()` directly is not supported - it bypasses the `l-ui--modal` controller and skips scroll lock, focus restoration, open-count tracking, and the screen-reader announcement.
 
+## Popover
+
+```ruby
+l_ui_popover(id: nil, placement: :bottom, align: :start, container: {}, &block)
+```
+
+- `id` (String, optional) - DOM id for the popover element; defaults to an auto-generated id
+- `placement` (Symbol, optional) - `:top`, `:bottom` (default), `:left`, or `:right`. Flips automatically if it would overflow the viewport
+- `align` (Symbol, optional) - `:start` (default) flushes the popover's leading edge with the trigger's; `:end` flushes its trailing edge instead. For example, `placement: :bottom, align: :end` hangs the popover down and to the left of a trigger at the right end of a row
+- `container` (Hash, optional) - extra HTML attributes for the wrapping `<div>` (e.g. `class:`)
+- `&block` - the block's content is the popover body; call `p.trigger(**options, &block)` inside it to render the trigger button
+
+```erb
+<%= l_ui_popover(placement: :bottom) do |p| %>
+  <% p.trigger(class: "l-ui-button l-ui-button--outline") do %>
+    Options
+  <% end %>
+  <p>Popover content.</p>
+<% end %>
+```
+
+Renders the trigger `<button popovertarget="...">` and the `popover="auto"` element (`class="l-ui-popover"`), and wires the `l-ui--popover` Stimulus controller for placement. Showing, hiding, light-dismiss (outside click), and Escape-to-close are all handled natively by the browser via the `popover` attribute - no Stimulus action is needed to open or close it.
+
+If the trigger contains only an icon (no visible text), pass `aria-label:` to `p.trigger` so the button has an accessible name.
+
+For a list of actions (e.g. a "more" menu on a table row), wrap the items in a `<div class="l-ui-popover__menu">` and give each link/button `l-ui-popover__menu-item` (add `l-ui-popover__menu-item--danger` for destructive actions, and an `<hr class="l-ui-popover__menu-divider">` to separate groups of items):
+
+```erb
+<%= l_ui_table(@users, columns: [...],
+    actions: ->(r) {
+      l_ui_popover(align: :end) do |p|
+        p.trigger(class: "l-ui-button l-ui-button--outline l-ui-button--icon l-ui-button--small", "aria-label" => "Actions for #{r.name}") do
+          image_tag "layered_ui/icon_more.svg", alt: "", class: "l-ui-icon l-ui-icon--sm", aria: { hidden: true }
+        end
+        tag.div(class: "l-ui-popover__menu") do
+          safe_join([
+            link_to("Edit", edit_user_path(r), class: "l-ui-popover__menu-item"),
+            tag.hr(class: "l-ui-popover__menu-divider"),
+            button_to("Delete", user_path(r), method: :delete, class: "l-ui-popover__menu-item l-ui-popover__menu-item--danger")
+          ])
+        end
+      end
+    }) %>
+```
+
 ## Header
 
 ```ruby

app/assets/images/layered_ui/icon_more.svg

@@ -1035,12 +1035,16 @@
          w-full min-h-[40px]
          gap-3 px-3
          text-sm font-medium text-foreground-muted
+         hover:bg-surface
          rounded-sm
          focus-ring
          transition-colors;
 }
 
-.l-ui-navigation__item--active {
+/* Repeats hover so the active background wins over the base item's
+   hover:bg-surface - equal specificity, but this rule comes later. */
+.l-ui-navigation__item--active,
+.l-ui-navigation__item--active:hover {
   @apply text-foreground
          bg-surface-highlighted;
 }
@@ -2242,6 +2246,45 @@ pre.l-ui-surface {
          px-5 py-4;
 }
 
+/* Popover */
+
+.l-ui-popover {
+  @apply fixed inset-auto
+         max-w-xs
+         m-0 p-3
+         text-sm text-foreground
+         bg-background
+         border border-border rounded-sm;
+}
+
+/* A list of actions inside a popover (e.g. a table row's "more" menu).
+   Negative margin cancels l-ui-popover's own padding; px-1/py-1 restore a
+   small inset for the list itself. */
+.l-ui-popover__menu {
+  @apply flex flex-col
+         -m-3 px-1 py-1;
+}
+
+.l-ui-popover__menu-item {
+  @apply block w-full
+         px-3 py-2
+         text-sm text-left text-foreground
+         hover:bg-surface focus:bg-surface
+         rounded-sm
+         focus-ring
+         transition-colors
+         cursor-pointer;
+}
+
+.l-ui-popover__menu-item--danger {
+  @apply text-danger;
+}
+
+.l-ui-popover__menu-divider {
+  @apply my-1
+         border-t border-border;
+}
+
 /* Safari */
 @media (max-width: 767px) {
   /* iOS Safari ignores overflow:hidden on body; position:fixed is required */

app/assets/tailwind/layered_ui/engine.css

@@ -0,0 +1,81 @@
+module Layered
+  module Ui
+    module PopoverHelper
+      # Renders a floating panel anchored to a trigger button, built on the
+      # native HTML +popover+ attribute. Showing, hiding, light-dismiss, and
+      # Escape-to-close are all handled by the browser; the +l-ui--popover+
+      # Stimulus controller only computes placement (with auto-flip near
+      # viewport edges).
+      #
+      #   <%= l_ui_popover(placement: :bottom) do |p| %>
+      #     <% p.trigger(class: "l-ui-button l-ui-button--outline") do %>
+      #       Options
+      #     <% end %>
+      #     <p>Popover content.</p>
+      #   <% end %>
+      #
+      # Note: use +<% p.trigger %>+ (without the equals sign) so its content is
+      # captured by the builder rather than written to the body buffer.
+      #
+      # Options:
+      #   id:         (String)  DOM id for the popover element; defaults to an auto-generated id.
+      #   placement:  (Symbol)  :top, :bottom (default), :left, or :right. Flips automatically if it would overflow the viewport.
+      #   align:      (Symbol)  :start (default) flushes the popover's leading edge with the trigger's; :end flushes its trailing edge instead
+      #                         (e.g. placement: :bottom, align: :end hangs the popover down and to the left of a trigger at the right end of a row).
+      #   container:  (Hash)    Extra HTML attributes for the wrapping <div>.
+      def l_ui_popover(id: nil, placement: :bottom, align: :start, container: {}, &block)
+        id ||= "l-ui-popover-#{SecureRandom.hex(4)}"
+        builder = PopoverBuilder.new(self, id: id)
+        body_content = capture { block.call(builder) }
+
+        container_attrs = container.deep_dup
+        container_data = container_attrs[:data] || {}
+        existing_controller = container_data.delete(:controller) || container_data.delete("controller")
+        container_data[:controller] = [existing_controller, "l-ui--popover"].compact.reject(&:empty?).join(" ")
+        container_data[:"l-ui--popover-placement-value"] = placement
+        container_data[:"l-ui--popover-align-value"] = align
+        container_attrs[:data] = container_data
+
+        tag.div(**container_attrs) do
+          safe_join([
+            builder.trigger_html || ActiveSupport::SafeBuffer.new,
+            render_popover(builder, body_content)
+          ])
+        end
+      end
+
+      class PopoverBuilder
+        attr_reader :id, :trigger_html
+
+        def initialize(view, id:)
+          @view = view
+          @id = id
+        end
+
+        def trigger(**options, &block)
+          options = options.deep_dup
+          options[:type] ||= "button"
+          options[:popovertarget] = id
+          data = options[:data] || {}
+          data[:"l-ui--popover-target"] = "trigger"
+          options[:data] = data
+          content = @view.capture(&block)
+          @trigger_html = @view.tag.button(content, **options)
+          nil
+        end
+      end
+
+      private
+
+      def render_popover(builder, body_content)
+        tag.div(
+          body_content,
+          id: builder.id,
+          popover: "auto",
+          class: "l-ui-popover",
+          data: { "l-ui--popover-target" => "popover" }
+        )
+      end
+    end
+  end
+end

app/helpers/layered/ui/popover_helper.rb

@@ -0,0 +1,112 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Positions a native `popover`-attribute element relative to its trigger.
+// Showing, hiding, light-dismiss, and Escape-to-close are all handled by the
+// browser via the popover attribute; this controller only computes placement
+// (with auto-flip near viewport edges), since CSS anchor positioning isn't
+// yet reliable across all supported browsers.
+export default class extends Controller {
+  static targets = ["trigger", "popover"]
+  static values = {
+    placement: { type: String, default: "bottom" },
+    align: { type: String, default: "start" }
+  }
+
+  static GAP = 8
+
+  popoverTargetConnected(element) {
+    this._toggleHandler = (event) => {
+      if (event.newState === "open") {
+        this.position()
+        this._addRepositionListeners()
+      } else {
+        this._removeRepositionListeners()
+      }
+    }
+    element.addEventListener("toggle", this._toggleHandler)
+  }
+
+  popoverTargetDisconnected(element) {
+    element.removeEventListener("toggle", this._toggleHandler)
+    this._removeRepositionListeners()
+  }
+
+  disconnect() {
+    this._removeRepositionListeners()
+  }
+
+  // Compute and apply the popover's fixed position relative to the trigger,
+  // flipping to the opposite side if the preferred placement would overflow
+  // the viewport.
+  position() {
+    if (!this.hasTriggerTarget || !this.hasPopoverTarget) return
+
+    const gap = this.constructor.GAP
+    const trigger = this.triggerTarget.getBoundingClientRect()
+    const popover = this.popoverTarget.getBoundingClientRect()
+    const align = this.alignValue
+
+    // The cross-axis coordinate (horizontal for top/bottom, vertical for
+    // left/right): "start" flushes the popover's leading edge with the
+    // trigger's, "end" flushes its trailing edge instead - e.g. a "bottom"
+    // placement with "end" align hangs the popover down and to the left of
+    // a trigger sitting at the right end of a row.
+    const crossAxisStart = (placement) =>
+      placement === "top" || placement === "bottom"
+        ? align === "end" ? trigger.right - popover.width : trigger.left
+        : align === "end" ? trigger.bottom - popover.height : trigger.top
+
+    const coordsFor = (placement) => {
+      switch (placement) {
+        case "top":
+          return { top: trigger.top - popover.height - gap, left: crossAxisStart(placement) }
+        case "left":
+          return { top: crossAxisStart(placement), left: trigger.left - popover.width - gap }
+        case "right":
+          return { top: crossAxisStart(placement), left: trigger.right + gap }
+        default:
+          return { top: trigger.bottom + gap, left: crossAxisStart(placement) }
+      }
+    }
+
+    let placement = this.placementValue
+    let coords = coordsFor(placement)
+
+    if (placement === "bottom" && coords.top + popover.height > window.innerHeight) {
+      placement = "top"
+      coords = coordsFor(placement)
+    } else if (placement === "top" && coords.top < 0) {
+      placement = "bottom"
+      coords = coordsFor(placement)
+    } else if (placement === "right" && coords.left + popover.width > window.innerWidth) {
+      placement = "left"
+      coords = coordsFor(placement)
+    } else if (placement === "left" && coords.left < 0) {
+      placement = "right"
+      coords = coordsFor(placement)
+    }
+
+    let left = coords.left
+    if (placement === "top" || placement === "bottom") {
+      left = Math.min(Math.max(gap, left), window.innerWidth - popover.width - gap)
+    }
+
+    this.popoverTarget.style.top = `${Math.max(gap, coords.top)}px`
+    this.popoverTarget.style.left = `${left}px`
+  }
+
+  // Private
+
+  _addRepositionListeners() {
+    this._repositionHandler = () => this.position()
+    window.addEventListener("resize", this._repositionHandler)
+    window.addEventListener("scroll", this._repositionHandler, true)
+  }
+
+  _removeRepositionListeners() {
+    if (!this._repositionHandler) return
+    window.removeEventListener("resize", this._repositionHandler)
+    window.removeEventListener("scroll", this._repositionHandler, true)
+    this._repositionHandler = null
+  }
+}