layered-ui-rails 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3300c4fe2f7e3d1fc8175af4985078888212de7a797482ffc12b5d60074b4b09
-  data.tar.gz: a56fed6fd7b9013d7c0a2ca988194d5071713e137f1c4022b58e86e205992bf1
+  metadata.gz: 9ced93c0df2346914e675fcdf3dd10657a079d3dcc046271dfb6bb24e6ff2c8c
+  data.tar.gz: 5e64064b0fdb591d0621118350bf5c1b181c88de7799a02a9b7f2e7e628f5ad0
 SHA512:
-  metadata.gz: 717f5fef1822f58376c54673e9c536be2d1509ee185d152f82e0bcce75e91930b2312d21d106b076ae58a0aff5c7c0f239fe7cff5147987b725dcaa433d773d2
-  data.tar.gz: e99903b76852ebf675b7583a71572b0bcd0cad27eb12a9231fc4a9b7ad2b9a4e9d5a3e48970e71713fe780307f6e63fee398a9c25c1c37d94c7d1439abf42f5a
+  metadata.gz: 9408f35f4b9b2d2a57d0227ec06cbf55a8f8c9ac692d97e1a0a6e9765f0b369bf9732aea5d8742b4c454c1cc555e258303abb2e57f878c352db18b5416fb454b
+  data.tar.gz: e24b88f24d9f70192bdfa75166f287da9bb01165c6af436b25efc812e7d83e1c5df2cd915896a75aa5c26a4c699c2fbcd3ac6661a0f8f0888d94d8366daac241

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

@@ -181,6 +181,8 @@ 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 |
+| `l_ui_tag(rounded: false, container: {})` | Interactive tag built from segments (`t.text`, `t.button`, `t.link`, `t.remove`) with an optional attached popover (`t.popover`); `rounded: true` for a pill shape |
 
 ## CSS classes
 
@@ -199,9 +201,11 @@ Key components:
 | Forms | `.l-ui-form`, `.l-ui-form__group`, `.l-ui-form__field`, `.l-ui-label`, `.l-ui-select` |
 | Tables | `.l-ui-table`, `.l-ui-table__header`, `.l-ui-table__cell`, `--primary`, `--action`, `.l-ui-table__action`, `--danger` |
 | Badges | `.l-ui-badge`, `--rounded`, `--default`, `--success`, `--warning`, `--danger` |
+| Tags | `.l-ui-tag`, `--rounded`, `__text`, `__button`, `__remove` |
 | 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 +221,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

data/.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.

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

@@ -269,6 +269,20 @@ Always combine the base block with one variant modifier (e.g. `class="l-ui-notic
 
 Always combine the base block with a modifier, e.g. `<span class="l-ui-badge l-ui-badge--success">`.
 
+## Tags
+
+Interactive tag - e.g. an email recipient or an active filter. A badge is a static styled span; a tag is a container with separately interactive segments.
+
+```
+.l-ui-tag           Tag container (div); carries colour and shape but no padding - segments supply it
+.l-ui-tag--rounded  Pill shape (matching l-ui-badge--rounded); default is the subtle badge radius
+.l-ui-tag__text     Static label segment (span)
+.l-ui-tag__button   Interactive label segment (button or a); focus ring + pointer
+.l-ui-tag__remove   Trailing remove segment (button or a) holding a ✕ icon (e.g. l-ui-icon--xs); needs an aria-label
+```
+
+A tag takes the same subtle corner radius as a badge by default; add `l-ui-tag--rounded` for a pill. Segments must be direct children in label-then-remove order; when a remove segment follows, the label segment automatically drops its right padding so the remove owns the gap and every part of the tag stays clickable. Prefer the `l_ui_tag` helper (see HELPERS.md), which also wires an optional popover.
+
 ## Tabs
 
 ```
@@ -287,6 +301,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
 
 ```

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

@@ -322,6 +322,86 @@ 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
+    }) %>
+```
+
+## Tag
+
+```ruby
+l_ui_tag(rounded: false, container: {}, &block)
+```
+
+Renders an interactive tag (`class="l-ui-tag"`) - e.g. an email recipient or an active filter. Visually related to `l-ui-badge` but a distinct control: a badge is a static styled span, while a tag is a container whose segments (label, remove) are separately interactive.
+
+- `rounded` (Boolean, optional) - pill shape (matching `l-ui-badge--rounded`); defaults to `false` for the subtle badge radius
+- `container` (Hash, optional) - extra HTML attributes for the wrapping `<div>` (e.g. `class:`)
+- `&block` - declare segments on the builder; they render in call order. Use `<%` (not `<%=`) - segment content is captured by the builder
+
+Builder methods:
+
+- `t.text(content = nil, **opts, &block)` - static label segment (`<span class="l-ui-tag__text">`)
+- `t.button(**opts, &block)` - button segment (`<button class="l-ui-tag__button">`); opens the tag's popover when one is declared
+- `t.link(url, **opts, &block)` - link segment, styled like a button segment
+- `t.remove(url = nil, **opts, &block)` - trailing remove segment (`l-ui-tag__remove`): a link when `url` is given, otherwise a button. Renders a ✕ icon unless the block supplies custom content. Pass `aria: { label: ... }` so it has an accessible name
+- `t.popover(id: nil, placement: :bottom, align: :start, &block)` - attaches a popover; the block is the popover body. Options match `l_ui_popover`
+
+```erb
+<%= l_ui_tag do |t| %>
+  <% t.button(aria: { label: "Edit status filter" }) do %>
+    Status: Active
+  <% end %>
+  <% t.remove remove_filter_path, aria: { label: "Remove status filter" },
+       data: { turbo_frame: "results" } %>
+  <% t.popover do %>
+    <p>Filter controls.</p>
+  <% end %>
+<% end %>
+```
+
+When a popover is declared, the tag container itself becomes the `l-ui--popover` controller root and placement target - the popover aligns with the whole tag rather than the label button inside it - and button segments are wired to open it via `popovertarget`. A tag without a popover renders no Stimulus wiring.
+
 ## Header
 
 ```ruby

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.21.0] - 2026-07-09
+
+### Added
+
+- Tags: interactive tags (`l-ui-tag`), such as email recipients or active filters. Visually related to badges but a distinct control: a badge is a static styled span, while a tag is a container whose segments - `l-ui-tag__text` (static label), `l-ui-tag__button` (button or link label), and `l-ui-tag__remove` (trailing ✕ link or button) - are separately interactive, each carrying its share of the tag's padding so every part is a hit target. Takes the same subtle corner radius as a badge by default, with `l-ui-tag--rounded` for a pill shape (matching `l-ui-badge--rounded`). The `l_ui_tag` helper builds the tag from builder calls (`t.text`, `t.button`, `t.link`, `t.remove`, `t.popover`) and takes a `rounded:` option; declaring `t.popover` makes the whole tag the popover's placement target and wires button segments to open it via `popovertarget`. The default `t.remove` control is a filled x-circle.
+- `icon_close_circle.svg` (a filled circle with a cross knocked out) added to the bundled icon set, used by the tag remove control and available as a general-purpose icon.
+
+## [0.20.0] - 2026-07-08
+
+### Added
+
+- Popovers: floating panels anchored to a trigger button, built on the native HTML `popover` attribute. Showing, hiding, light-dismiss (outside click), and Escape-to-close are all handled by the browser; the new `l-ui--popover` Stimulus controller only computes placement, flipping to the opposite side if the preferred side would overflow the viewport. Use the `l_ui_popover` helper (options: `id:`, `placement:` of `:top`/`:bottom`/`:left`/`:right`, `align:` of `:start`/`:end`, `container:`) with `p.trigger` for the button, or wire the `l-ui-popover` class and controller targets by hand for full control over markup.
+- Popover menus: `l-ui-popover__menu`, `l-ui-popover__menu-item`, `l-ui-popover__menu-item--danger`, and `l-ui-popover__menu-divider` style a list of actions inside a popover - e.g. a "more" menu on a table row via `l_ui_table`'s `actions:` proc. Give an icon-only trigger an `aria-label` so it has an accessible name.
+- `icon_more.svg` (vertical ellipsis) added to the bundled icon set, for "more actions" popover triggers.
+
+### Changed
+
+- Navigation items now show a `surface` background on hover, matching the hover treatment of other menu rows. The active item keeps its highlighted background on hover.
+- The overrides generator now stamps the gem version it was generated from into the overrides file's header comment.
+
 ## [0.19.0] - 2026-06-15
 
 ### Added

data/README.md

@@ -36,7 +36,7 @@ An open source, Rails 8+ engine that provides WCAG 2.2 AA compliant design token
 - **Dark/light theme** - system preference detection with localStorage persistence and manual toggle
 - **Responsive layout** - header, sidebar navigation, main content area, and optional resizable panel
 - **WCAG 2.2 AA compliant** - skip links, focus indicators, ARIA attributes, and 4.5:1 contrast ratios
-- **Components** - buttons, forms, surfaces, tables, tabs, notices, badges, conversations, modals, and pagination
+- **Components** - buttons, forms, surfaces, tables, tabs, notices, badges, tags, conversations, modals, popovers, and pagination
 - **Optional integrations** - Devise authentication and Pagy pagination with styled views
 - **Customisable branding** - Override the default logos and icons and colors
 - **Google Lighthouse** - `layered-ui-rails` scores a [perfect 100](https://github.com/layered-ai-public/layered-ui-rails/raw/refs/heads/main/test/dummy/app/assets/images/lighthouse.webp) across all four Google Lighthouse categories - performance, accessibility, best practices, and SEO

data/app/assets/images/layered_ui/icon_close_circle.svg

@@ -0,0 +1,3 @@
+<svg fill="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M12 2.25c-5.385 0-9.75 4.365-9.75 9.75s4.365 9.75 9.75 9.75 9.75-4.365 9.75-9.75S17.385 2.25 12 2.25Zm-1.72 6.97a.75.75 0 0 0-1.06 1.06L10.94 12l-1.72 1.72a.75.75 0 1 0 1.06 1.06L12 13.06l1.72 1.72a.75.75 0 1 0 1.06-1.06L13.06 12l1.72-1.72a.75.75 0 1 0-1.06-1.06L12 10.94l-1.72-1.72Z" />
+</svg>

data/app/assets/images/layered_ui/icon_more.svg

@@ -0,0 +1,5 @@
+<svg fill="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="12" cy="5" r="2" />
+  <circle cx="12" cy="12" r="2" />
+  <circle cx="12" cy="19" r="2" />
+</svg>

data/app/assets/tailwind/layered_ui/engine.css

@@ -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;
 }
@@ -1851,6 +1855,62 @@ pre.l-ui-surface {
          bg-error-bg;
 }
 
+/* Tags */
+
+/* An interactive tag - e.g. an email recipient or an active filter. Related
+   to the badge visually, but a distinct control: a badge is a static styled
+   span, while a tag is a container with interactive segments. The container
+   carries no padding of its own - each segment supplies its share, so every
+   part of the tag is a hit target. */
+
+.l-ui-tag {
+  @apply inline-flex items-stretch
+         min-h-[32px]
+         text-xs font-medium
+         text-foreground-muted
+         bg-surface-highlighted
+         rounded;
+}
+
+/* Pill shape, matching l-ui-badge--rounded. */
+.l-ui-tag--rounded {
+  @apply !rounded-full;
+}
+
+.l-ui-tag__text {
+  @apply flex items-center
+         gap-1 px-3;
+}
+
+.l-ui-tag__button {
+  @apply flex items-center
+         gap-1 px-3
+         rounded
+         focus-ring
+         cursor-pointer;
+}
+
+/* Segment focus rings follow the tag's shape. */
+.l-ui-tag--rounded .l-ui-tag__button,
+.l-ui-tag--rounded .l-ui-tag__remove {
+  @apply !rounded-full;
+}
+
+/* When a remove segment follows, it owns the gap between the label and the
+   ✕ (its left padding), so the label segment gives up its right padding. */
+.l-ui-tag__text:has(+ .l-ui-tag__remove),
+.l-ui-tag__button:has(+ .l-ui-tag__remove) {
+  @apply pr-0;
+}
+
+.l-ui-tag__remove {
+  @apply flex items-center
+         pl-1.5 pr-2
+         rounded
+         focus-ring
+         cursor-pointer;
+}
+
 /* Panel */
 
 .l-ui-panel__button {
@@ -2242,6 +2302,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 */

data/app/helpers/layered/ui/popover_helper.rb

@@ -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

data/app/helpers/layered/ui/tag_helper.rb

@@ -0,0 +1,171 @@
+module Layered
+  module Ui
+    module TagHelper
+      # Renders an interactive tag - e.g. an email recipient or an active
+      # filter. Visually related to +l-ui-badge+, but a distinct control: a
+      # badge is a static styled span, while a tag is a container whose
+      # segments (label, remove) are separately interactive.
+      #
+      #   <%= l_ui_tag do |t| %>
+      #     <% t.text "alice@example.com" %>
+      #     <% t.remove aria: { label: "Remove alice@example.com" } %>
+      #   <% end %>
+      #
+      # A tag may carry a popover. The whole tag becomes the placement target
+      # (so the popover aligns with the tag rather than the segment inside
+      # it), and button segments open it via +popovertarget+:
+      #
+      #   <%= l_ui_tag do |t| %>
+      #     <% t.button(aria: { label: "Edit status filter" }) do %>
+      #       Status: Active
+      #     <% end %>
+      #     <% t.remove remove_filter_path, aria: { label: "Remove status filter" } %>
+      #     <% t.popover do %>
+      #       <p>Filter controls.</p>
+      #     <% end %>
+      #   <% end %>
+      #
+      # Note: use +<% t.button %>+ (without the equals sign) so segment content
+      # is captured by the builder rather than written to the body buffer.
+      #
+      # Segments render in the order they are declared; the popover element is
+      # always appended last. Give icon-only segments (such as +t.remove+) an
+      # +aria-label+ so they have an accessible name.
+      #
+      # Options:
+      #   rounded:   (Boolean) Pill shape (matching +l-ui-badge--rounded+); defaults to false for the subtle badge shape.
+      #   container: (Hash)    Extra HTML attributes for the wrapping <div>.
+      #
+      # Builder methods:
+      #   t.text(content = nil, **options, &block)  Static label segment (<span>).
+      #   t.button(**options, &block)               Button segment; opens the tag's popover when one is declared.
+      #   t.link(url, **options, &block)            Link segment, styled like a button segment.
+      #   t.remove(url = nil, **options, &block)    Trailing remove segment: a link when +url+ is given, otherwise a
+      #                                             button. Renders a ✕ icon unless the block supplies custom content.
+      #   t.popover(id: nil, placement: :bottom, align: :start, &block)
+      #                                             Attaches a popover to the tag; the block is the popover body.
+      #                                             Options match +l_ui_popover+.
+      def l_ui_tag(rounded: false, container: {}, &block)
+        builder = TagBuilder.new(self)
+        capture { block.call(builder) }
+
+        container_attrs = container.deep_dup
+        container_attrs[:class] = class_names("l-ui-tag", ("l-ui-tag--rounded" if rounded), container_attrs[:class])
+
+        if builder.popover?
+          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-target"] = "trigger"
+          container_data[:"l-ui--popover-placement-value"] = builder.popover_placement
+          container_data[:"l-ui--popover-align-value"] = builder.popover_align
+          container_attrs[:data] = container_data
+        end
+
+        tag.div(**container_attrs) do
+          parts = builder.segments.map { |segment| l_ui_tag_segment(builder, segment) }
+          parts << l_ui_tag_popover(builder) if builder.popover?
+          safe_join(parts)
+        end
+      end
+
+      class TagBuilder
+        attr_reader :segments, :popover_id, :popover_placement, :popover_align, :popover_body
+
+        def initialize(view)
+          @view = view
+          @segments = []
+        end
+
+        def text(content = nil, **options, &block)
+          content = @view.capture(&block) if block
+          @segments << { kind: :text, content: content, options: options }
+          nil
+        end
+
+        def button(**options, &block)
+          content = block ? @view.capture(&block) : nil
+          @segments << { kind: :button, content: content, options: options }
+          nil
+        end
+
+        def link(url, **options, &block)
+          content = block ? @view.capture(&block) : nil
+          @segments << { kind: :link, url: url, content: content, options: options }
+          nil
+        end
+
+        def remove(url = nil, **options, &block)
+          content = block ? @view.capture(&block) : nil
+          @segments << { kind: :remove, url: url, content: content, options: options }
+          nil
+        end
+
+        def popover(id: nil, placement: :bottom, align: :start, &block)
+          @popover_id = id || "l-ui-tag-popover-#{SecureRandom.hex(4)}"
+          @popover_placement = placement
+          @popover_align = align
+          @popover_body = @view.capture(&block)
+          nil
+        end
+
+        def popover?
+          !@popover_id.nil?
+        end
+      end
+
+      private
+
+      def l_ui_tag_segment(builder, segment)
+        options = segment[:options].deep_dup
+
+        case segment[:kind]
+        when :text
+          options[:class] = class_names("l-ui-tag__text", options[:class])
+          tag.span(segment[:content], **options)
+        when :button
+          options[:class] = class_names("l-ui-tag__button", options[:class])
+          options[:type] ||= "button"
+          options[:popovertarget] ||= builder.popover_id if builder.popover?
+          tag.button(segment[:content], **options)
+        when :link
+          options[:class] = class_names("l-ui-tag__button", options[:class])
+          link_to(segment[:content], segment[:url], options)
+        when :remove
+          options[:class] = class_names("l-ui-tag__remove", options[:class])
+          content = segment[:content] || l_ui_tag_remove_icon
+          if segment[:url]
+            link_to(content, segment[:url], options)
+          else
+            options[:type] ||= "button"
+            tag.button(content, **options)
+          end
+        end
+      end
+
+      # Filled x-circle, matching the bundled +icon_close_circle.svg+ asset.
+      # Rendered inline (rather than via image_tag) so it inherits the tag's
+      # muted +currentColor+; an <img>-loaded SVG cannot.
+      def l_ui_tag_remove_icon
+        tag.svg(
+          tag.path("fill-rule" => "evenodd", "clip-rule" => "evenodd",
+            "d" => "M12 2.25c-5.385 0-9.75 4.365-9.75 9.75s4.365 9.75 9.75 9.75 9.75-4.365 9.75-9.75S17.385 2.25 12 2.25Zm-1.72 6.97a.75.75 0 0 0-1.06 1.06L10.94 12l-1.72 1.72a.75.75 0 1 0 1.06 1.06L12 13.06l1.72 1.72a.75.75 0 1 0 1.06-1.06L13.06 12l1.72-1.72a.75.75 0 1 0-1.06-1.06L12 10.94l-1.72-1.72Z"),
+          class: "l-ui-icon--sm",
+          fill: "currentColor",
+          "viewBox" => "0 0 24 24",
+          "aria-hidden" => "true"
+        )
+      end
+
+      def l_ui_tag_popover(builder)
+        tag.div(
+          builder.popover_body,
+          id: builder.popover_id,
+          popover: "auto",
+          class: "l-ui-popover",
+          data: { "l-ui--popover-target" => "popover" }
+        )
+      end
+    end
+  end
+end

data/app/javascript/layered_ui/controllers/l_ui/popover_controller.js

@@ -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
+  }
+}

data/app/javascript/layered_ui/index.js

@@ -6,6 +6,7 @@ import PanelController from "layered_ui/controllers/l_ui/panel_controller"
 import PanelResizeController from "layered_ui/controllers/l_ui/panel_resize_controller"
 import PanelButtonController from "layered_ui/controllers/l_ui/panel_button_controller"
 import ModalController from "layered_ui/controllers/l_ui/modal_controller"
+import PopoverController from "layered_ui/controllers/l_ui/popover_controller"
 import SearchFormController from "layered_ui/controllers/l_ui/search_form_controller"
 import TabsController from "layered_ui/controllers/l_ui/tabs_controller"
 
@@ -17,4 +18,5 @@ application.register("l-ui--panel", PanelController)
 application.register("l-ui--panel-resize", PanelResizeController)
 application.register("l-ui--panel-button", PanelButtonController)
 application.register("l-ui--modal", ModalController)
+application.register("l-ui--popover", PopoverController)
 application.register("l-ui--tabs", TabsController)

data/config/importmap.rb

@@ -13,6 +13,7 @@ pin "layered_ui/controllers/l_ui/navigation_section_controller", to: "layered_ui
 pin "layered_ui/controllers/l_ui/panel_controller", to: "layered_ui/controllers/l_ui/panel_controller.js"
 pin "layered_ui/controllers/l_ui/panel_resize_controller", to: "layered_ui/controllers/l_ui/panel_resize_controller.js"
 pin "layered_ui/controllers/l_ui/panel_button_controller", to: "layered_ui/controllers/l_ui/panel_button_controller.js"
+pin "layered_ui/controllers/l_ui/popover_controller", to: "layered_ui/controllers/l_ui/popover_controller.js"
 pin "layered_ui/controllers/l_ui/search_form_controller", to: "layered_ui/controllers/l_ui/search_form_controller.js"
 pin "layered_ui/controllers/l_ui/tabs_controller", to: "layered_ui/controllers/l_ui/tabs_controller.js"
 pin "layered_ui/controllers/l_ui/theme_controller", to: "layered_ui/controllers/l_ui/theme_controller.js"

data/lib/generators/layered/ui/create_overrides_generator.rb

@@ -23,7 +23,7 @@ module Layered
         def overrides_content
           <<~CSS
             /*
-             * layered-ui-rails color overrides
+             * layered-ui-rails color overrides (generated from v#{Layered::Ui::VERSION})
              *
              * Uncomment and edit any variable below to customise the UI.
              * This file is NOT overwritten by the install generator, so your

data/lib/layered/ui/engine.rb

@@ -36,7 +36,9 @@ module Layered
           helper Layered::Ui::FormHelper
           helper Layered::Ui::HeaderHelper
           helper Layered::Ui::ModalHelper
+          helper Layered::Ui::PopoverHelper
           helper Layered::Ui::RansackHelper
+          helper Layered::Ui::TagHelper
         end
       end
 

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.19.0"
+    VERSION = "0.21.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.21.0
 platform: ruby
 authors:
 - layered.ai
@@ -193,6 +193,7 @@ files:
 - app/assets/images/layered_ui/icon_chevron_down.svg
 - app/assets/images/layered_ui/icon_chevron_right.svg
 - app/assets/images/layered_ui/icon_close.svg
+- app/assets/images/layered_ui/icon_close_circle.svg
 - app/assets/images/layered_ui/icon_dark.svg
 - app/assets/images/layered_ui/icon_discord.svg
 - app/assets/images/layered_ui/icon_github.svg
@@ -203,6 +204,7 @@ files:
 - app/assets/images/layered_ui/icon_linkedin.svg
 - app/assets/images/layered_ui/icon_mail.svg
 - app/assets/images/layered_ui/icon_moon.svg
+- app/assets/images/layered_ui/icon_more.svg
 - app/assets/images/layered_ui/icon_panel_close.svg
 - app/assets/images/layered_ui/icon_sun.svg
 - app/assets/images/layered_ui/icon_x.svg
@@ -220,8 +222,10 @@ files:
 - app/helpers/layered/ui/modal_helper.rb
 - app/helpers/layered/ui/navigation_helper.rb
 - app/helpers/layered/ui/pagy_helper.rb
+- app/helpers/layered/ui/popover_helper.rb
 - app/helpers/layered/ui/ransack_helper.rb
 - app/helpers/layered/ui/table_helper.rb
+- app/helpers/layered/ui/tag_helper.rb
 - app/helpers/layered/ui/title_bar_helper.rb
 - app/javascript/layered_ui/controllers/l_ui/modal_controller.js
 - app/javascript/layered_ui/controllers/l_ui/navigation_controller.js
@@ -229,6 +233,7 @@ files:
 - app/javascript/layered_ui/controllers/l_ui/panel_button_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_resize_controller.js
+- app/javascript/layered_ui/controllers/l_ui/popover_controller.js
 - app/javascript/layered_ui/controllers/l_ui/search_form_controller.js
 - app/javascript/layered_ui/controllers/l_ui/tabs_controller.js
 - app/javascript/layered_ui/controllers/l_ui/theme_controller.js