layered-ui-rails 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93bf15a80c67a460c8eada9407beb94507d3dce7fe511e935355abcd329a4d8
-  data.tar.gz: 06d49cc35c54fa21fddb6ced245abfa9ad4783003a03074beb9467e03f46cbb1
+  metadata.gz: 2371574fe91ff33cc9926d8e5fccf86afd408b90f61dc570514bd86d5f1bb149
+  data.tar.gz: ef320467046f71ad12c3b16f0f738188f3a5b40cf705d50e9fe8f11ea1512f6e
 SHA512:
-  metadata.gz: f4435d521aa96f5e74b0d1183ae5d486b795d28eb6d6dc16728b8147599715a5e49b64c0a226a78b5aed479c6586dd73f02962321d2e976e693453f79d022fe6
-  data.tar.gz: 21030bae58aefc605b07370d6dcc615a1f1441566a72b28859068151109d41005b1fc333234878293a4c02d424d5896f9b3230886f1efcfc071ce3cbb493a7d4
+  metadata.gz: f5ea052a4964edc0edea159e1179aee36a32ec491c2cf39ed09de01af8be343e0bb289f9e5e911d5e95a887379357fa284966ff6d4471edeaa16f3c2cd3dc81b
+  data.tar.gz: 31a3897b1c16acc5923b6a442004f4f2ccc9e9f731270724ce39739e014df8afef062af1516a8a95aeb009b35727e602129bdc7cdbc8fa024d072c527dabdad8

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

@@ -182,6 +182,7 @@ Quick reference:
 | `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
 
@@ -200,6 +201,7 @@ 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` |

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

@@ -111,7 +111,7 @@ Accessible tabbed interface with keyboard navigation.
 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)
+**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), `open` (Boolean, default `false`; when true the popover opens as soon as the controller connects, shown and positioned in the same task so it never paints unpositioned - e.g. re-opening a filter popover after a form submission re-renders the page)
 
 ```html
 <div data-controller="l-ui--popover">
@@ -130,6 +130,7 @@ Positions a native `popover`-attribute element relative to its trigger, with aut
 Features:
 - Repositions on open, and while open on window resize/scroll
 - Flips to the opposite side if the preferred placement would overflow the viewport
+- `data-l-ui--popover-open-value="true"` opens the popover on connect without a flash of unpositioned content
 
 ## Panel (`l-ui--panel`)
 
@@ -202,3 +203,20 @@ When multiple search forms exist on one page (each with a different `scope` valu
   &lt;%= l_ui_pagy(@users_pagy) %&gt;
 &lt;% end %&gt;
 ```
+
+## Scroll hint (`l-ui--scroll-hint`)
+
+Fades the clipped edges of a horizontal scroller while more content is available in that direction, so it is obvious the region can be scrolled.
+
+**Targets:** `scroller` (the scrollable element)
+**Behaviour:** toggles `l-ui-scroll-hint--left`/`l-ui-scroll-hint--right` on the wrapper from the scroll position; updates on scroll and when the scroller or its content resizes. While the scroller overflows it is given `tabindex="0"` so keyboard users can scroll it (WCAG 2.1.1); the attribute is removed when it fits.
+
+`l_ui_table` wires this up automatically. For hand-written tables (or any other horizontal scroller), wrap the scrolling element:
+
+```html
+<div class="l-ui-scroll-hint" data-controller="l-ui--scroll-hint">
+  <div class="l-ui-table-container" data-l-ui--scroll-hint-target="scroller">
+    <table class="l-ui-table">...</table>
+  </div>
+</div>
+```

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

@@ -204,6 +204,7 @@ Always combine the `l-ui-surface` base class with any modifiers (e.g. `l-ui-surf
 
 ```
 .l-ui-table                        Table element
+.l-ui-table--floating-actions      Modifier: pins action cells to the right-hand edge of the scroll container during horizontal scrolling (sticky; solid background with a faded leading edge)
 .l-ui-table__header                <thead> row
 .l-ui-table__header-cell           <th> cell
 .l-ui-table__header-cell--action   Right-aligned action header
@@ -217,6 +218,9 @@ Always combine the `l-ui-surface` base class with any modifiers (e.g. `l-ui-surf
 .l-ui-table__action                Action link/button (inside a __cell--action)
 .l-ui-table__action--danger        Danger modifier (combine with l-ui-table__action)
 .l-ui-table-container              Overflow wrapper for responsive tables
+.l-ui-scroll-hint                  Wrapper around a horizontal scroller (e.g. l-ui-table-container); fades the clipped edge while more content is available (paired with the l-ui--scroll-hint controller)
+.l-ui-scroll-hint--left            Fade visible on the left edge (toggled by the controller)
+.l-ui-scroll-hint--right           Fade visible on the right edge (toggled by the controller)
 ```
 
 WCAG 2.2 AA table pattern:
@@ -269,6 +273,22 @@ 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-row       Canonical container for a row of tags plus any trailing actions (e.g. a filter bar); wrapping flex row with gap
+.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__label    Inner wrapper (span) around a text/button segment's content; truncates long labels with an ellipsis
+.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. A tag never grows past its container; wrap label content in `l-ui-tag__label` so it truncates with an ellipsis instead of overflowing. Prefer the `l_ui_tag` helper (see HELPERS.md), which renders the label wrapper and wires an optional popover.
+
 ## Tabs
 
 ```

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

@@ -197,8 +197,8 @@ Returns a `<th>` element with sort link and ARIA sort attributes.
 
 ```ruby
 l_ui_table(records, columns:, caption: nil, actions: nil,
-           actions_label: "Actions", query: nil, url: nil,
-           turbo_frame: nil, row_id: nil)
+           actions_label: "Actions", floating_actions: false,
+           query: nil, url: nil, turbo_frame: nil, row_id: nil)
 ```
 
 - `records` (ActiveRecord::Relation or Array) - the collection to render
@@ -206,11 +206,14 @@ l_ui_table(records, columns:, caption: nil, actions: nil,
 - `caption` (String, optional) - visually hidden table caption for accessibility
 - `actions` (Proc, optional) - receives (record), returns action cell content
 - `actions_label` (String) - header text for the actions column, default "Actions"
+- `floating_actions` (Boolean) - pin the actions column to the right-hand edge of the scroll container while the table scrolls horizontally (adds `l-ui-table--floating-actions`), default false
 - `query` (Ransack::Search, optional) - enables sortable column headers
 - `url` (String, optional) - sort link URL (passed to `l_ui_sort_link`)
 - `turbo_frame` (String, optional) - turbo frame target for sort links
 - `row_id` (Proc, optional) - receives (record), returns the `<tr>` id. Defaults to `dom_id(record)` for records that respond to `to_key` (ActiveRecord). Return `nil` to omit the id.
 
+The rendered table is wrapped in an `l-ui-scroll-hint` element wired to the `l-ui--scroll-hint` controller, which fades the clipped edge when the table overflows horizontally.
+
 Column options:
 - `attribute` (Symbol) - used for label generation and sort links
 - `label` (String, optional) - custom header text; defaults to humanised attribute
@@ -325,12 +328,13 @@ Calling `dialog.showModal()` directly is not supported - it bypasses the `l-ui--
 ## Popover
 
 ```ruby
-l_ui_popover(id: nil, placement: :bottom, align: :start, container: {}, &block)
+l_ui_popover(id: nil, placement: :bottom, align: :start, open: false, 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
+- `open` (Boolean, optional) - when `true`, the popover opens as soon as its Stimulus controller connects, shown and positioned in the same task so it never paints unpositioned. Useful for re-opening a popover after a form submission re-renders the page (e.g. `open: params[:filtering].present?`). Defaults to `false`
 - `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
 
@@ -367,6 +371,43 @@ For a list of actions (e.g. a "more" menu on a table row), wrap the items in a `
     }) %>
 ```
 
+## 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, open: false, &block)` - attaches a popover; the block is the popover body. Options match `l_ui_popover`
+
+Text, button, and link segments wrap their content in `<span class="l-ui-tag__label">`, which truncates long labels with an ellipsis when the tag is squeezed (the tag itself never grows past its container).
+
+```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,23 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.22.0] - 2026-07-10
+
+### Added
+
+- Floating table actions: pass `floating_actions: true` to `l_ui_table` (or add `l-ui-table--floating-actions` to a hand-written table) to pin the actions column to the right-hand edge of the scroll container, so row actions stay visible while the table scrolls horizontally. The pinned cells sit on a solid background with a faded leading edge, and the container gains scroll padding so focused cells scroll clear of the pinned column.
+- Scroll hint: the new `l-ui--scroll-hint` Stimulus controller and `l-ui-scroll-hint` wrapper fade the clipped edges of a horizontal scroller while more content is available in that direction. While the scroller overflows it is made keyboard-focusable so the region stays keyboard-scrollable. `l_ui_table` wraps every table in a scroll hint automatically; wrap hand-written tables (or any other horizontal scroller) yourself.
+- Popover `open:` option: `l_ui_popover(open: true)` (and `t.popover(open: true)` on a tag) opens the popover as soon as its Stimulus controller connects, shown and positioned in the same task so it never paints unpositioned - useful for re-opening a filter popover after a form submission re-renders the page.
+- `l-ui-tag-row`: the canonical container for a row of tags plus any trailing actions (e.g. a filter bar) - a wrapping flex row with a gap, so tags move onto new lines on narrow screens instead of overflowing.
+- Tag truncation: a tag never grows past its container, and label segments wrap their content in the new `l-ui-tag__label` so long labels truncate with an ellipsis instead of overflowing. The `l_ui_tag` helper renders the wrapper automatically; add it yourself in hand-written markup.
+
+## [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

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, popovers, 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/tailwind/layered_ui/engine.css

@@ -1655,7 +1655,16 @@ pre.l-ui-surface {
 /* Tables */
 
 .l-ui-table-container {
-  @apply overflow-x-auto;
+  @apply overflow-x-auto
+         focus-ring;
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-border) transparent;
+}
+
+/* Scrolls focused cells clear of the pinned actions column (WCAG 2.4.11) */
+
+.l-ui-table-container:has(.l-ui-table--floating-actions) {
+  @apply scroll-pr-20;
 }
 
 .l-ui-table {
@@ -1739,6 +1748,50 @@ pre.l-ui-surface {
   @apply pr-0;
 }
 
+/* The 1.5rem fade-in must match the leading padding so the actions always
+   sit on solid background; z-10 lifts the cells above the scroll-hint fade */
+
+.l-ui-table--floating-actions th.l-ui-table__header-cell--action,
+.l-ui-table--floating-actions td.l-ui-table__cell--action {
+  @apply sticky right-0 z-10
+         pl-6 pr-2
+         bg-linear-to-r from-background/0 to-background to-[1.5rem];
+}
+
+/* Scroll hint */
+
+/* The --left/--right modifiers are toggled by the l-ui--scroll-hint
+   controller from the scroll position of the wrapped scroller */
+
+.l-ui-scroll-hint {
+  @apply relative;
+}
+
+.l-ui-scroll-hint::before,
+.l-ui-scroll-hint::after {
+  @apply absolute inset-y-0
+         w-8
+         opacity-0
+         transition-opacity
+         pointer-events-none;
+  content: "";
+}
+
+.l-ui-scroll-hint::before {
+  @apply left-0
+         bg-linear-to-r from-background to-background/0;
+}
+
+.l-ui-scroll-hint::after {
+  @apply right-0
+         bg-linear-to-l from-background to-background/0;
+}
+
+.l-ui-scroll-hint--left::before,
+.l-ui-scroll-hint--right::after {
+  @apply opacity-100;
+}
+
 /* Pagination */
 
 @utility pagination-base {
@@ -1855,6 +1908,84 @@ 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-row {
+  @apply flex flex-wrap items-center
+         gap-2;
+}
+
+/* The row wraps whole items onto new lines, so a squeezed trailing action
+   should move down rather than wrap its label mid-text. Scoped here because
+   elsewhere (e.g. a full-width button in a narrow panel) nowrap would force
+   horizontal overflow instead of wrapping. */
+.l-ui-tag-row .l-ui-button {
+  @apply whitespace-nowrap;
+}
+
+.l-ui-tag {
+  @apply inline-flex items-stretch
+         max-w-full 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
+         min-w-0
+         gap-1 px-3;
+}
+
+.l-ui-tag__button {
+  @apply flex items-center
+         min-w-0
+         gap-1 px-3
+         rounded
+         focus-ring
+         cursor-pointer;
+}
+
+/* This wrapper exists so long labels can truncate: ellipsis has no effect on
+   text sitting directly inside a flex container like the segment. */
+.l-ui-tag__label {
+  @apply overflow-hidden
+         text-ellipsis whitespace-nowrap;
+}
+
+/* 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 {

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

@@ -22,8 +22,11 @@ module Layered
       #   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).
+      #   open:       (Boolean) When true, the popover opens as soon as its Stimulus controller connects - shown and positioned in the same
+      #                         task, so it never paints unpositioned. Useful for re-opening a popover after a form submission re-renders
+      #                         the page. Defaults to false.
       #   container:  (Hash)    Extra HTML attributes for the wrapping <div>.
-      def l_ui_popover(id: nil, placement: :bottom, align: :start, container: {}, &block)
+      def l_ui_popover(id: nil, placement: :bottom, align: :start, open: false, container: {}, &block)
         id ||= "l-ui-popover-#{SecureRandom.hex(4)}"
         builder = PopoverBuilder.new(self, id: id)
         body_content = capture { block.call(builder) }
@@ -34,6 +37,7 @@ module Layered
         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_data[:"l-ui--popover-open-value"] = true if open
         container_attrs[:data] = container_data
 
         tag.div(**container_attrs) do

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

@@ -31,6 +31,14 @@ module Layered
       #   sortable:  (Boolean) Show sort link when query: is provided. Defaults to true.
       #   render:    (Proc)    Required. Receives (record), returns cell content.
       #
+      # Pass +floating_actions: true+ to pin the actions column to the
+      # right-hand edge of the scroll container, so row actions stay visible
+      # while the table scrolls horizontally.
+      #
+      # The table is wrapped in an +l-ui-scroll-hint+ element wired to the
+      # +l-ui--scroll-hint+ controller, which fades the clipped edge while
+      # more columns are available in that direction.
+      #
       # Pass +query:+ (a Ransack search object) and +turbo_frame:+ to enable
       # sortable column headers via +l_ui_sort_link+.
       #
@@ -38,7 +46,7 @@ module Layered
       # +to_key+ (i.e. ActiveRecord), so individual rows can be targeted by
       # Turbo Streams. Pass +row_id:+ as a proc to override (return +nil+ to
       # omit the id).
-      def l_ui_table(records, columns:, caption: nil, actions: nil, actions_label: "Actions", query: nil, url: nil, turbo_frame: nil, row_id: nil)
+      def l_ui_table(records, columns:, caption: nil, actions: nil, actions_label: "Actions", floating_actions: false, query: nil, url: nil, turbo_frame: nil, row_id: nil)
         columns = normalise_table_columns(columns)
         col_count = columns.size + (actions ? 1 : 0)
 
@@ -75,8 +83,11 @@ module Layered
         end
 
         caption_tag = caption ? tag.caption(caption, class: "l-ui-sr-only") : nil
-        table = tag.table(class: "l-ui-table") { safe_join([caption_tag, thead, tbody].compact) }
-        tag.div(table, class: "l-ui-table-container")
+        table_classes = ["l-ui-table"]
+        table_classes << "l-ui-table--floating-actions" if actions && floating_actions
+        table = tag.table(class: table_classes.join(" ")) { safe_join([caption_tag, thead, tbody].compact) }
+        container = tag.div(table, class: "l-ui-table-container", data: { "l-ui--scroll-hint-target" => "scroller" })
+        tag.div(container, class: "l-ui-scroll-hint", data: { controller: "l-ui--scroll-hint" })
       end
 
       private

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

@@ -0,0 +1,180 @@
+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, open: false, &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_data[:"l-ui--popover-open-value"] = true if builder.popover_open
+          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_open, :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, open: false, &block)
+          @popover_id = id || "l-ui-tag-popover-#{SecureRandom.hex(4)}"
+          @popover_placement = placement
+          @popover_align = align
+          @popover_open = open
+          @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(l_ui_tag_label(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(l_ui_tag_label(segment[:content]), **options)
+        when :link
+          options[:class] = class_names("l-ui-tag__button", options[:class])
+          link_to(l_ui_tag_label(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
+
+      # Wraps a label segment's content so long labels can truncate with an
+      # ellipsis - ellipsis has no effect on text sitting directly inside a
+      # flex container like the segment.
+      def l_ui_tag_label(content)
+        tag.span(content, class: "l-ui-tag__label")
+      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

@@ -9,7 +9,8 @@ export default class extends Controller {
   static targets = ["trigger", "popover"]
   static values = {
     placement: { type: String, default: "bottom" },
-    align: { type: String, default: "start" }
+    align: { type: String, default: "start" },
+    open: { type: Boolean, default: false }
   }
 
   static GAP = 8
@@ -24,6 +25,16 @@ export default class extends Controller {
       }
     }
     element.addEventListener("toggle", this._toggleHandler)
+
+    // Open on connect when requested (e.g. re-opening a filter popover after
+    // a form submission re-renders the page). showPopover() and position()
+    // must run back-to-back in the same task: the native toggle event is
+    // dispatched asynchronously, so relying on the listener alone would paint
+    // the popover unpositioned at the viewport origin for one frame.
+    if (this.openValue && !element.matches(":popover-open")) {
+      element.showPopover()
+      this.position()
+    }
   }
 
   popoverTargetDisconnected(element) {

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

@@ -0,0 +1,46 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Fades the clipped edges of a horizontal scroller while more content is
+// available in that direction, by toggling the l-ui-scroll-hint--left/--right
+// modifiers on its wrapper. Also makes the scroller keyboard-focusable while
+// it overflows, so the region stays keyboard-scrollable.
+export default class extends Controller {
+  static targets = ["scroller"]
+
+  initialize() {
+    this.update = this.update.bind(this)
+  }
+
+  connect() {
+    this.scrollerTarget.addEventListener("scroll", this.update, { passive: true })
+
+    this.resizeObserver = new ResizeObserver(this.update)
+    this.resizeObserver.observe(this.scrollerTarget)
+    if (this.scrollerTarget.firstElementChild) {
+      this.resizeObserver.observe(this.scrollerTarget.firstElementChild)
+    }
+
+    this.update()
+  }
+
+  disconnect() {
+    this.scrollerTarget.removeEventListener("scroll", this.update)
+    this.resizeObserver.disconnect()
+  }
+
+  update() {
+    const scroller = this.scrollerTarget
+    // 1px tolerance for fractional scroll positions on high-DPI screens
+    const overflows = scroller.scrollWidth - scroller.clientWidth > 1
+
+    // Keep the region keyboard-scrollable while it overflows (WCAG 2.1.1)
+    if (overflows) {
+      scroller.setAttribute("tabindex", "0")
+    } else {
+      scroller.removeAttribute("tabindex")
+    }
+
+    this.element.classList.toggle("l-ui-scroll-hint--left", scroller.scrollLeft > 1)
+    this.element.classList.toggle("l-ui-scroll-hint--right", overflows && scroller.scrollLeft < scroller.scrollWidth - scroller.clientWidth - 1)
+  }
+}

data/app/javascript/layered_ui/index.js

@@ -7,6 +7,7 @@ import PanelResizeController from "layered_ui/controllers/l_ui/panel_resize_cont
 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 ScrollHintController from "layered_ui/controllers/l_ui/scroll_hint_controller"
 import SearchFormController from "layered_ui/controllers/l_ui/search_form_controller"
 import TabsController from "layered_ui/controllers/l_ui/tabs_controller"
 
@@ -19,4 +20,5 @@ 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--scroll-hint", ScrollHintController)
 application.register("l-ui--tabs", TabsController)

data/config/importmap.rb

@@ -14,6 +14,7 @@ pin "layered_ui/controllers/l_ui/panel_controller", to: "layered_ui/controllers/
 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/scroll_hint_controller", to: "layered_ui/controllers/l_ui/scroll_hint_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/layered/ui/engine.rb

@@ -38,6 +38,7 @@ module Layered
           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.20.0"
+    VERSION = "0.22.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.22.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
@@ -224,6 +225,7 @@ files:
 - 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
@@ -232,6 +234,7 @@ files:
 - 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/scroll_hint_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