layered-ui-rails 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2371574fe91ff33cc9926d8e5fccf86afd408b90f61dc570514bd86d5f1bb149
-  data.tar.gz: ef320467046f71ad12c3b16f0f738188f3a5b40cf705d50e9fe8f11ea1512f6e
+  metadata.gz: ffb58ab0d1712c81928bbf3685708f5571e98dd1af70484024219dc6a491f2cc
+  data.tar.gz: 495f951c875f7572f38b77e6739fcbd49856160a0d84e96cd76f701c97d1262d
 SHA512:
-  metadata.gz: f5ea052a4964edc0edea159e1179aee36a32ec491c2cf39ed09de01af8be343e0bb289f9e5e911d5e95a887379357fa284966ff6d4471edeaa16f3c2cd3dc81b
-  data.tar.gz: 31a3897b1c16acc5923b6a442004f4f2ccc9e9f731270724ce39739e014df8afef062af1516a8a95aeb009b35727e602129bdc7cdbc8fa024d072c527dabdad8
+  metadata.gz: 4f855f052b32a2b172a8bb390d1bd19680fccc568996a9b286c4edf9eec2665ad3e0c97b8ff686d760da9dd8f9306ef941cb1ed449f65b984ac01d139818230d
+  data.tar.gz: a0abb3efe8343044f8581ad5f1c476f3a822c7225daf3ec5638d4a61cb685d5db3886f7f884d461ab685a4b8ff67f68894fca25324665219051ebd439a6a428a

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

@@ -240,7 +240,7 @@ Override CSS custom properties after the engine import. Values are full CSS colo
 }
 ```
 
-Key tokens: `--accent`, `--accent-foreground`, `--background`, `--foreground`, `--foreground-muted`, `--border`, `--border-control`, `--surface`, `--surface-highlighted`, `--danger`, `--header-height`.
+Key tokens: `--accent`, `--accent-foreground`, `--background`, `--foreground`, `--foreground-muted`, `--border`, `--border-control`, `--surface`, `--surface-highlighted`, `--danger`, `--header-height`, `--l-ui-navigation-width`.
 
 ## Asset overrides
 
@@ -250,9 +250,17 @@ Place files in `app/assets/images/layered_ui/` to replace engine defaults:
 
 The panel toggle button uses an inline SVG that inherits `currentColor`. Recolor it by overriding the `--button-primary-icon` Tier 2 token, or replace the image by setting both `@l_ui_panel_icon_light_url` and `@l_ui_panel_icon_dark_url` (per-request).
 
+## Ejecting a view
+
+Any engine view can be replaced by copying it to the same path in the host application - `app/views/devise/registrations/edit.html.erb` overrides the Settings screen, `app/views/layouts/layered_ui/_navigation.html.erb` the sidebar, and so on. Application views resolve before engine views, so no configuration is needed.
+
+Find the original to copy with `bundle info layered-ui-rails --path`. Unlike engine views, an ejected view lives in the host application, so it may use plain Tailwind utilities alongside the `l-ui-*` classes - the host's Tailwind build scans it.
+
+Note that `bin/rails generate devise:views` copies Devise's own unstyled views into `app/views/devise/`, which overrides *every* styled view the engine provides, not just the one being changed. Eject the individual views instead.
+
 ## 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 (including an account settings screen at `registrations#edit`), header login/register buttons, and sidebar user info with a Settings/Logout menu. 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 +269,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

@@ -132,6 +132,30 @@ Features:
 - 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`)
 
 Resizable side panel. Full-width overlay on mobile, docked sidebar on desktop.

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

@@ -289,6 +289,35 @@ Interactive tag - e.g. an email recipient or an active filter. A badge is a stat
 
 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
 
 ```
@@ -369,6 +398,9 @@ A tag takes the same subtle corner radius as a badge by default; add `l-ui-tag--
 .l-ui-navigation__section-chevron       Toggle chevron (rotates when closed)
 .l-ui-navigation__section-items         Section body (ul, hidden when closed)
 .l-ui-navigation__user            User info section
+.l-ui-navigation__user-button     Unpadded full-width account menu trigger (pair with .l-ui-button)
+.l-ui-navigation__user-chevron    Upward chevron inside the account menu trigger
+.l-ui-navigation__user-popover    Account menu popover sized to the sidebar's inner column
 .l-ui-navigation__user-name       User name text
 .l-ui-navigation__user-email      User email text
 ```
@@ -459,6 +491,7 @@ Always combine the base block with one size modifier (e.g. `class="l-ui-icon l-u
 ```
 .l-ui-mt-0/2/3/4/6/8            Margin top (fixed scale)
 .l-ui-mb-0                      Margin bottom zero
+.l-ui-mb-4                      Margin bottom (1rem)
 .l-ui-sr-only                   Visually hidden, screen reader only
 .l-ui-skip-link                 Accessibility skip link
 .l-ui-list                      Styled list
@@ -504,6 +537,7 @@ Tier 2 - Full palette (override individually as needed):
 --error-text            Error text
 --header-height         Header height (default 63px)
 --l-ui-gutter           Page/header horizontal + bottom padding (default 1rem)
+--l-ui-navigation-width Sidebar navigation width (default 256px)
 --l-ui-contained-width  Max width of contained content - header + .l-ui-page__contained (default 80rem)
 ```
 

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

@@ -283,6 +283,7 @@ Field options:
 l_ui_normalise_field(record, config)  # Normalise a raw field config into canonical form
 l_ui_field_error_id(record, attribute)  # Error element ID for aria-describedby
 l_ui_field_hint_id(record, attribute)   # Hint element ID for aria-describedby
+l_ui_field_describedby(record, attribute, hint: false)  # Space-joined hint + error IDs for aria-describedby
 ```
 
 ## Modal
@@ -408,6 +409,87 @@ Text, button, and link segments wrap their content in `<span class="l-ui-tag__la
 
 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
@@ -430,16 +512,22 @@ 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_settings_screen?     # Returns true on the Settings screen (Devise registrations#edit)
+l_ui_new_registration_path # Devise registration path for the configured scope, or nil
+l_ui_edit_registration_path # Devise account settings 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/settings/logout paths (`new_registration_path`, `edit_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,35 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.24.0] - 2026-08-22
+
+### Added
+
+- Devise account settings: Devise's `registrations#edit` is styled as a Settings screen at `/users/edit`, with the account details under an "Account" tab. A signed-in user can change their email (and their name, if the model has one), set a new password, or cancel their account - all of it confirmed with the current password, as Devise expects. If your user model has a `name` attribute, permit it for `:account_update` as well as `:sign_up`. Link to the screen with `l_ui_edit_registration_path`, and use `l_ui_settings_screen?` to keep application chrome that a layout otherwise strips from Devise views.
+- Sidebar account menu: the signed-in user's name and email in the sidebar are now a menu button opening a popover holding Settings and Logout, replacing the standalone logout button. The menu is sized to the sidebar's inner column so it lines up with the name and email, and only the entries whose Devise routes exist are rendered.
+- Ejecting a view: any engine view can be replaced by copying it to the matching path in your application - `app/views/devise/registrations/edit.html.erb` takes over the Settings screen, `app/views/layouts/layered_ui/_navigation.html.erb` the sidebar - with no configuration. The engine's views are still prepended so they beat Devise's own, but your `app/views` is prepended back on top, restoring the precedence Rails gives you by default. Note that `bin/rails generate devise:views` generates *every* Devise view, so it replaces the whole styled set rather than the one you meant to change. See `UPGRADING.md`.
+- `--l-ui-navigation-width`: the sidebar navigation width (default 256px), previously hard-coded, now overridable alongside the other layout tokens.
+
+### Fixed
+
+- Devise form fields are scoped to the mapping rather than the model, so an app whose mapping name differs from its model (`devise_for :members, class_name: "User"`) submits parameters under the name Devise looks for. Previously the fields were named after the model, and nothing the user typed reached the controller.
+- Field hints on the Devise views carry an id and are referenced by their input's `aria-describedby` (assembled by the new `l_ui_field_describedby` helper), so a screen reader announces the password length requirement along with the field instead of leaving it unlinked.
+- The "Need assistance?" heading on the Devise views is rendered only when at least one of the links beneath it is. Previously it appeared whenever the matching Devise modules were enabled, so a page whose only link was suppressed showed a heading over nothing.
+
+### Changed
+
+- Logout has moved out of the sidebar into the account menu. A host that targeted the sidebar's `l-ui-button--outline-danger` logout button, in CSS or in a system test, will need to look inside `l-ui-navigation__user-popover` instead.
+
+## [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

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)**.