layered-ui-rails 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ced93c0df2346914e675fcdf3dd10657a079d3dcc046271dfb6bb24e6ff2c8c
-  data.tar.gz: 5e64064b0fdb591d0621118350bf5c1b181c88de7799a02a9b7f2e7e628f5ad0
+  metadata.gz: 2346c306d3b5e355c1f61a51254d79701fe3a9ad2e8bc5817aa7311b0e024db0
+  data.tar.gz: b01fdcd1dca34dd339ea4183933b5b6fcded78d3a2ee2c4c371ed92cd18e3214
 SHA512:
-  metadata.gz: 9408f35f4b9b2d2a57d0227ec06cbf55a8f8c9ac692d97e1a0a6e9765f0b369bf9732aea5d8742b4c454c1cc555e258303abb2e57f878c352db18b5416fb454b
-  data.tar.gz: e24b88f24d9f70192bdfa75166f287da9bb01165c6af436b25efc812e7d83e1c5df2cd915896a75aa5c26a4c699c2fbcd3ac6661a0f8f0888d94d8366daac241
+  metadata.gz: 29160e5b7d0dea492dd8cb2591b3797a564e2bef6bdabe7fa355ad79cde4dc516cf8537eef1c6298852a22dacf74126b5405bdbcd6fe63dd358adc37779e693e
+  data.tar.gz: 8ef704e93632b9f1d60eb4f521f82c7b55e072ef507cea2267fbccdd6ecd76980e43bf6720c3ce0449df38dcfc3753d970167cf5a6b80af85cb868fb5a1169e1

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

@@ -252,7 +252,7 @@ The panel toggle button uses an inline SVG that inherits `currentColor`. Recolor
 
 ## Optional integrations
 
-- **Devise** - auto-detected. Provides styled auth views, header login/register buttons, sidebar user info and logout. Setup: `bundle add devise`, run `devise:install` and `devise User` generators, add `devise_for :users` to routes. Configure `Layered::Ui.current_user_method` if not using `:current_user`. Helpers: `l_ui_devise_installed?`, `l_ui_user_signed_in?`.
+- **Devise** - auto-detected. Provides styled auth views, header login/register buttons, sidebar user info and logout. Setup: `bundle add devise`, run `devise:install` and `devise User` generators, add `devise_for :users` to routes. Configure `Layered::Ui.current_user_method` if not using `:current_user`, and `Layered::Ui.devise_scope` if the Devise mapping isn't `:user`. Helpers: `l_ui_devise_installed?`, `l_ui_user_signed_in?`.
 - **Pagy** - auto-detected. Use `l_ui_pagy(@pagy)` for styled pagination.
 - **Ransack** - auto-detected. Use `l_ui_search_form` and `l_ui_sort_link` for styled search and sortable tables.
 
@@ -261,6 +261,7 @@ The panel toggle button uses an inline SVG that inherits `currentColor`. Recolor
 ```ruby
 # config/initializers/layered_ui.rb
 Layered::Ui.current_user_method = :current_member  # default: :current_user
+Layered::Ui.devise_scope = :member                 # default: :user
 ```
 
 ## Common issues

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,31 @@ 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
+
+## Combobox (`l-ui--combobox`)
+
+Drives the token select rendered by `l_ui_combobox`: type-ahead filtering, selections held as tokens with their own hidden inputs, optional creation of values outside the collection, optional reordering, and optional remote options.
+
+**Targets:** `control`, `tokens`, `token`, `input`, `listbox`, `option`, `empty`, `notice`, `noticeText`, `busy`, `moreSpinner`, `template`, `optionTemplate`, `status`
+**Values:** `multiple` (Boolean, default `true`), `create` (Boolean, default `false`), `reorder` (Boolean, default `false`), `disabled` (Boolean, default `false`), `name` (String - parameter existing values post under), `createName` (String - parameter created values post under), `url` (String - endpoint searched as the user types; empty means filter in the browser), `minChars` (Number, default `0` - characters needed before a remote search runs), `text` (Object - the wording for the messages built here, from the helper's `text:` option; `%{name}` placeholders are substituted at use, and a key the caller emptied is left unsaid)
+**Actions:** `focusInput`, `open`, `close`, `blur`, `scrolled`, `filter`, `keydown`, `selectOption`, `removeToken`, `moveTokenEarlier`, `moveTokenLater`, `dragstart`, `dragover`, `drop`, `dragend`
+
+Features:
+- Focus never leaves the input while the list is browsed; the highlight follows `aria-activedescendant`
+- Down/Up/Home/End move the highlight, Enter chooses, Escape closes then clears, Backspace on the empty input removes the last token
+- With nothing highlighted, Down enters the list at the first option and Up at the last, matching the ARIA combobox pattern; the highlight wraps at either end
+- Choosing an already-selected option removes it again (multi select); single select replaces the token and closes
+- In create mode, a term matching no option is offered as `Add "term"` and posts under `createName`
+- Reorder mode disables the dead-end move control on the first and last token and moves focus so it is never lost; a disabled combobox is left alone, so its controls stay disabled
+- Dragging is a pointer enhancement only, advertised by a decorative grip handle - the move buttons are the accessible path, as WCAG 2.2 SC 2.5.7 requires
+- Selections, filter counts, and moves are announced through a local `role="status"` region
+- With `url` set, each keystroke schedules a debounced fetch of `url?term=...`; the previous request is aborted and an overtaken response is dropped, so the list always answers what is currently typed. Leaving the field abandons a search in flight, so nothing spins beside a closed listbox and nothing is announced after focus has moved on. Responses replace the options wholesale, cloned from the `optionTemplate`, and the browser does no filtering of its own
+- Further pages are appended as the end of a remote list is reached - within `LOAD_MORE_MARGIN` of its foot (the `scrolled` action, bound to the listbox), or on Down/End at the last option, so the keyboard is not capped at the first page. Down loads instead of wrapping while pages remain, and highlights the first newly loaded option; option ids run on across pages so `aria-activedescendant` can never point at a reused id
+- The `notice` row carries only durable messages: how far into the matches the list has got, a failed request, and the character threshold. Each appended page is announced through the status region
+- A request in flight shows a spinner rather than a message - `busy` (trailing the input) while searching, `moreSpinner` (in the notice row) while a page loads - after `SPINNER_DELAY`, so a fast response never flashes one. `aria-busy` goes on the listbox immediately, since it costs nothing and says the same thing to a screen reader
+
+Use the `l_ui_combobox` helper (see HELPERS.md) rather than writing the markup by hand.
 
 ## Panel (`l-ui--panel`)
 
@@ -202,3 +227,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:
@@ -274,14 +278,45 @@ Always combine the base block with a modifier, e.g. `<span class="l-ui-badge l-u
 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. Prefer the `l_ui_tag` helper (see HELPERS.md), which also wires an optional popover.
+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.
+
+## Combobox
+
+Token select: a text input with type-ahead filtering whose selections become tags. Built on the ARIA combobox pattern (`role="combobox"` input + `role="listbox"` popup).
+
+```
+.l-ui-combobox                    Wrapper (data-controller="l-ui--combobox"); position context for the listbox
+.l-ui-combobox__control           Field-styled wrapping flex row holding the tokens and the input; draws the focus ring via :focus-within
+.l-ui-combobox__control--disabled Dimmed, non-interactive control
+.l-ui-combobox__tokens            <ul> of tokens inside the control (collapses when empty)
+.l-ui-combobox__token             A selection (<li>); combine with l-ui-tag, whose segments it reuses
+.l-ui-combobox__token--draggable  A token that can be dragged (reorder mode, not disabled); takes cursor-grab
+.l-ui-combobox__token--dragging   Applied to the token being dragged
+.l-ui-combobox__grip              Decorative drag handle at a draggable token's leading edge (aria-hidden)
+.l-ui-combobox__move              Move-earlier / move-later control inside a token (reorder mode)
+.l-ui-combobox__input             The combobox text input; borderless, grows to fill the control, and carries a token's min-height so the control doesn't grow as the first token lands
+.l-ui-combobox__listbox           Absolutely positioned option list (role="listbox"); toggled with the hidden attribute
+.l-ui-combobox__option            An option (role="option"); hover takes bg-surface
+.l-ui-combobox__option--active    The option pointed at by aria-activedescendant (highlight, not DOM focus); bg-surface-highlighted, so it stays legible under a stray pointer
+.l-ui-combobox__option--create    The "Add ..." option offered in create mode
+.l-ui-combobox__option-check      Accent-filled circle holding the tick, shown on options with aria-selected="true"; reserved space so options don't shift
+.l-ui-combobox__option-check-icon The tick itself; sized well inside the circle and drawn with a stroke so its weight holds up at that size
+.l-ui-combobox__empty             "No matches" message
+.l-ui-combobox__spinner           Busy ring shown while a remote request is in flight; keeps its shape without the animation under prefers-reduced-motion
+.l-ui-combobox__busy              Wrapper holding the spinner at the control's trailing edge (hidden until a search is slow enough to report)
+.l-ui-combobox__notice            Presentational row for what the list has to say about itself - a remote search in flight, a failed one, or a truncated result set. Sticks to the foot of the scrolling list and is ruled off from the options above it; the listbox drops its bottom padding while the notice shows, so nothing scrolls through the gap
+```
+
+The listbox and filtered-out options are hidden with the `hidden` attribute, so `.l-ui-combobox [hidden] { display: none !important }` restores Preflight's rule (these components sit outside `@layer`, which would otherwise beat it). Prefer the `l_ui_combobox` helper (see HELPERS.md), which renders the whole structure with its ARIA wiring.
 
 ## 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
 
@@ -385,7 +389,9 @@ Builder methods:
 - `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`
+- `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| %>
@@ -402,6 +408,87 @@ Builder methods:
 
 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.
 
+## Combobox
+
+```ruby
+l_ui_combobox(name, collection: nil, form: nil, selected: nil, multiple: true,
+              create: false, create_name: nil, reorder: false, url: nil,
+              min_chars: 0, text: {}, id: nil, label: nil, hint: nil, placeholder: nil,
+              required: false, disabled: false, container: {})
+```
+
+Renders a token select (`class="l-ui-combobox"`): a text input with type-ahead filtering whose selections become removable tags, in the style of an email recipient field. Built on the ARIA combobox pattern - no third-party select library.
+
+- `name` (String or Symbol) - the parameter, e.g. `"post[tag_ids]"`. A Symbol is resolved against `form:`
+- `collection` (Array) - `["Label", value]` pairs, `{ label:, value: }` hashes, or plain strings. Required unless `url:` is given
+- `form` (FormBuilder, optional) - derives parameter names from the builder for Symbol names
+- `selected` (Array or value, optional) - selected values, or `["Label", value]` pairs / `{ label:, value: }` hashes where the label is not in `collection` (the only form a remote selection can take). A value with no label renders as a created token (requires `create:`)
+- `multiple` (Boolean, default `true`) - multi select; `false` drops the `[]` suffix, replaces the token on choice, and closes the list
+- `create` (Boolean, default `false`) - allow values outside the collection; requires `create_name:`
+- `create_name` (String or Symbol) - parameter created values post under, keeping record IDs and free text unambiguous server-side
+- `reorder` (Boolean, default `false`) - move controls plus mouse dragging (each token gains a decorative grip handle advertising the drag); parameters post in the displayed order
+- `url` (String, optional) - endpoint searched as the user types; options come from it rather than from `collection:`
+- `min_chars` (Integer, default `0`) - characters needed before a remote search runs; `0` searches as soon as the field is focused
+- `text` (Hash, optional) - wording for every string the control shows, merged over `Layered::Ui::ComboboxHelper::COMBOBOX_TEXT`: `empty:` ("No matches"), `create:` ("Add “%{term}”"), `min_chars:` ("Type %{count} characters to search."), `progress:` ("Showing %{shown} of %{count} matches."), `error:`, `more_error:`. Placeholders use Rails' `%{name}` syntax; `progress: nil` drops the progress line; an unknown key raises
+- `label`, `hint`, `placeholder`, `required`, `disabled`, `id`, `container` - as for a normal field
+
+```erb
+<%= form_with model: @post do |f| %>
+  <%= l_ui_combobox(:tag_ids, form: f,
+        label: "Tags",
+        collection: Tag.pluck(:name, :id),
+        selected: @post.tag_ids,
+        create: true,
+        create_name: :new_tag_names) %>
+<% end %>
+
+<%# post[tag_ids][]       => ["", "7"]  %>
+<%# post[new_tag_names][] => ["urgent"] %>
+```
+
+Each selection carries its own hidden input, so the control submits with an ordinary form post, and a blank value is always posted first - clearing every token submits an empty collection instead of omitting the parameter and leaving the association untouched. Selections are announced through a local `role="status"` region, and the keyboard help is bound to the input with `aria-describedby`. Reordering exposes move buttons as well as dragging, since WCAG 2.2 SC 2.5.7 requires a single-pointer alternative to a drag.
+
+### Remote options
+
+With `url:`, options are fetched from that endpoint as the user types (debounced, with overtaken responses discarded) instead of being rendered up front and filtered in the browser. Matches load a page at a time, the next page appended as the end of the list is reached - by scrolling to its foot or by pressing Down on its last option, so the keyboard is not capped at the first page. A presentational note under the options (`class="l-ui-combobox__notice"`) says how far into the matches the list has got, or that they could not be loaded; a request in flight shows a spinner instead (trailing the field while searching, beside the note while a page loads), after a short delay so a quick answer never flashes one. Remote selections must be passed as `["Label", value]` pairs, since the browser has no collection to look a label up in.
+
+```ruby
+Layered::Ui::ComboboxOptions   # Controller concern building the JSON the endpoint answers with
+
+l_ui_combobox_options(scope, label:, value: :id, search: nil, predicate: :cont,
+                      combinator: :or, term: nil, page: nil, limit: 20)
+```
+
+- `scope` (Relation or model class) - what the user is allowed to see; the endpoint stays an ordinary action in the host app, authorised as any index is
+- `label` (Symbol or Proc) - attribute, or callable taking the record, used for the option's label
+- `value` (Symbol or Proc, default `:id`) - attribute, or callable, used for the option's value
+- `search` (Array, defaults to `label`) - attributes the term is matched against; required when `label:` is a callable, since a computed label gives the database nothing to search on. An attribute neither backend can search raises rather than quietly matching everything
+- `predicate` (Symbol, default `:cont`) - Ransack predicate for the match; `:i_cont` ignores case. Without Ransack only `:cont` and `:i_cont` can be built, and any other raises rather than quietly matching on something else
+- `combinator` (Symbol, default `:or`) - how the search attributes combine, `:or` or `:and`; honoured on both paths, and anything else raises
+- `term`, `page` - default to `params[:term]` and `params[:page]`
+- `limit` (Integer, default 20) - options per page
+
+Ransack builds the predicate when it is available (so association attributes work) and Pagy takes the page; there is a plain `LIKE` plus `limit`/`offset` fallback, so neither gem is required. An unordered scope is ordered by the label so pages do not overlap.
+
+```erb
+<%= l_ui_combobox(:author_id, form: f, multiple: false,
+      url: options_users_path, min_chars: 2,
+      selected: [[@post.author.name, @post.author_id]]) %>
+```
+
+```ruby
+class UsersController < ApplicationController
+  include Layered::Ui::ComboboxOptions
+
+  def options
+    render json: l_ui_combobox_options(policy_scope(User), label: :name, search: [:name, :email])
+  end
+end
+
+# GET /users/options?term=ali&page=1
+# { "options": [{ "label": "Alice Johnson", "value": "2" }], "page": 1, "pages": 1, "count": 1 }
+```
+
 ## Header
 
 ```ruby
@@ -424,16 +511,20 @@ Use these when overriding the header actions group with `:l_ui_header_actions` t
 ## Authentication
 
 ```ruby
-l_ui_user_signed_in?   # Returns true if current user is present
-l_ui_current_user      # Returns the current user object
-l_ui_devise_installed? # Returns true if Devise is loaded
+l_ui_user_signed_in?      # Returns true if current user is present
+l_ui_current_user         # Returns the current user object
+l_ui_devise_installed?    # Returns true if Devise is loaded
+l_ui_new_registration_path # Devise registration path for the configured scope, or nil
+l_ui_new_session_path      # Devise sign-in path for the configured scope, or nil
+l_ui_destroy_session_path  # Devise sign-out path for the configured scope, or nil
 ```
 
-Configure the current user method:
+Configure the current user method, and the Devise scope used to build the login/register/logout paths (`new_registration_path`, `new_session_path`, `destroy_session_path`):
 
 ```ruby
 # config/initializers/layered_ui.rb
 Layered::Ui.current_user_method = :current_member
+Layered::Ui.devise_scope = :member
 ```
 
 ## Shared partials

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.23.0] - 2026-08-22
+
+### Added
+
+- Combobox: a token select (`l-ui-combobox`) - a text input with type-ahead filtering whose selections become removable tags, in the style of an email recipient field. Built on the ARIA combobox pattern (a `role="combobox"` input owning a `role="listbox"` popup, with the highlight following `aria-activedescendant` so focus stays in the input), with no third-party select library. The `l_ui_combobox` helper renders the whole control and its ARIA wiring; the new `l-ui--combobox` Stimulus controller drives it. Selections carry their own hidden inputs, so it submits with an ordinary form post.
+- Combobox options: `multiple: false` for a one-of-many control; `create:` (with `create_name:`) to add a term that matches no option, posting new values under their own parameter so the server never has to guess whether a value is a record's ID or free text; `reorder:` for move controls and mouse dragging, the buttons being the accessible path WCAG 2.2 SC 2.5.7 requires; and `text:` to reword or translate every string the control shows, using Rails' own `%{name}` placeholders.
+- Combobox remote options: pass `url:` and the options are fetched from that endpoint as the user types, for collections too large to send with the page. Requests are debounced and an overtaken response is discarded, `min_chars:` sets how much has to be typed first, and matches load a page at a time - reaching the end of the list appends the next page, by scrolling to its foot or by pressing Down on its last option, so the keyboard is not capped at the first page. A note under the options says how far into the matches the list has got; a request in flight shows a spinner after a short delay, so a quick answer never flashes one.
+- `Layered::Ui::ComboboxOptions`: a controller concern building the JSON a remote combobox expects, so the endpoint is a couple of lines. `l_ui_combobox_options(scope, label:, search:)` reads `term` and `page` from the query string and answers with `{ options: [{ label:, value: }], page:, pages:, count: }`, searching with Ransack and paging with Pagy when they are available and falling back to a plain `LIKE` with `limit`/`offset` when they are not. Endpoints stay ordinary actions in the host app, scoped and authorised as any index is.
+- `Layered::Ui.devise_scope`: the Devise mapping the header and sidebar link to, so an app that scopes authentication to something other than `:user` (`devise_for :members`) gets the right registration, session and logout paths. Defaults to `:user`.
+
+## [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

data/README.md

@@ -31,12 +31,33 @@ An open source, Rails 8+ engine that provides WCAG 2.2 AA compliant design token
   </tr>
 </table>
 
+## Quick start
+
+The fastest way to get going is [layered-foundation-rails](https://github.com/layered-ai-public/layered-foundation-rails) - an accessible Rails starter app with `layered-ui-rails` pre-installed and configured. It also includes additional skills and scripts to get you on your way.
+
+Clone the complete starter app:
+
+```bash
+git clone https://github.com/layered-ai-public/layered-foundation-rails.git myapp
+cd myapp
+bin/rails layered:foundation:setup
+```
+
+Or apply it as a Rails template:
+
+```bash
+rails new myapp --css tailwind \
+  -m https://raw.githubusercontent.com/layered-ai-public/layered-foundation-rails/main/template.rb
+```
+
+Adding `layered-ui-rails` to an existing app? See [Installation](#installation).
+
 ## Features
 
 - **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, tags, conversations, modals, popovers, and pagination
+- **Components** - buttons, forms, comboboxes, 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
@@ -180,6 +201,24 @@ For per-request icons, set instance variables - the engine renders `<link>` and
 
 > **Security:** Rails HTML-escapes URL values, so XSS via attribute injection is mitigated. However, if values are tenant-controlled, validate that they are legitimate URLs - reject `javascript:` schemes and ensure values point to expected origins.
 
+## Authentication
+
+The engine reads the signed-in user through `l_ui_current_user`, which delegates to your app's `current_user` helper by default. If your app uses a different helper (e.g. a Devise `Member` model, or Rails' built-in authentication generator with a custom name), configure it in an initializer:
+
+```ruby
+# config/initializers/layered_ui.rb
+Layered::Ui.current_user_method = :current_member
+```
+
+If your Devise mapping isn't `:user` (e.g. `devise_for :members`), also set the scope so the header and sidebar link to the right registration, session, and logout paths:
+
+```ruby
+# config/initializers/layered_ui.rb
+Layered::Ui.devise_scope = :member
+```
+
+Apps without authentication need no configuration - the user section of the navigation simply doesn't render. The sidebar shows the user's `name` and `email` when the model responds to those methods. Only one method is supported, so apps with multiple Devise scopes should pick the one to display.
+
 ## Documentation
 
 An online version of the documentation is available at **[layered-ui-rails.layered.ai](https://layered-ui-rails.layered.ai)**.