layered-ui-rails 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2371574fe91ff33cc9926d8e5fccf86afd408b90f61dc570514bd86d5f1bb149
-  data.tar.gz: ef320467046f71ad12c3b16f0f738188f3a5b40cf705d50e9fe8f11ea1512f6e
+  metadata.gz: 2346c306d3b5e355c1f61a51254d79701fe3a9ad2e8bc5817aa7311b0e024db0
+  data.tar.gz: b01fdcd1dca34dd339ea4183933b5b6fcded78d3a2ee2c4c371ed92cd18e3214
 SHA512:
-  metadata.gz: f5ea052a4964edc0edea159e1179aee36a32ec491c2cf39ed09de01af8be343e0bb289f9e5e911d5e95a887379357fa284966ff6d4471edeaa16f3c2cd3dc81b
-  data.tar.gz: 31a3897b1c16acc5923b6a442004f4f2ccc9e9f731270724ce39739e014df8afef062af1516a8a95aeb009b35727e602129bdc7cdbc8fa024d072c527dabdad8
+  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

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

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

@@ -408,6 +408,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 +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,16 @@
 
 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

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

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

@@ -1986,6 +1986,225 @@ pre.l-ui-surface {
          cursor-pointer;
 }
 
+/* Combobox */
+
+/* A token select: a text input with type-ahead filtering whose selections
+   become tags. The control is styled to read as a single form field, so it
+   borrows the field's border, radius and metrics while laying its tokens and
+   input out as a wrapping flex row. */
+
+.l-ui-combobox {
+  @apply relative
+         w-full;
+}
+
+/* The listbox and its filtered-out options are hidden with the `hidden`
+   attribute rather than a class, so their `display` must not be set by the
+   rules below - these components sit outside `@layer`, which would otherwise
+   beat Preflight's `[hidden]` rule. */
+.l-ui-combobox [hidden] {
+  display: none !important;
+}
+
+.l-ui-combobox__control {
+  @apply flex flex-wrap items-center
+         w-full min-h-[44px]
+         mt-2 p-1.5 gap-1.5
+         /* text-base at mobile; text-sm at md+ */
+         text-base font-inter text-foreground
+         bg-background
+         border border-border-control rounded-sm
+         cursor-text;
+
+  @media (min-width: 768px) {
+    @apply text-sm;
+  }
+}
+
+/* Focus lives on the input inside the control, so the ring is drawn on the
+   control to match the outline of a plain form field. */
+.l-ui-combobox__control:focus-within {
+  @apply ring-2 ring-ring ring-offset-2 ring-offset-background outline-none;
+}
+
+.field_with_errors .l-ui-combobox__control {
+  @apply bg-error-bg/10
+         border-2 border-danger;
+}
+
+.l-ui-combobox__control--disabled {
+  @apply opacity-60
+         cursor-default;
+}
+
+.l-ui-combobox__tokens {
+  @apply flex flex-wrap items-center
+         gap-1.5;
+}
+
+/* Without this the control's gap would leave a blank inset before the input
+   while nothing is selected. */
+.l-ui-combobox__tokens:empty {
+  @apply hidden;
+}
+
+.l-ui-combobox__token {
+  @apply cursor-default;
+}
+
+/* The grab cursor covers the label; the controls inside keep their own
+   pointer, so each part of the token still reads as what it does. */
+.l-ui-combobox__token--draggable {
+  @apply cursor-grab;
+}
+
+.l-ui-combobox__token--dragging {
+  @apply opacity-50
+         cursor-grabbing;
+}
+
+/* Decorative drag handle. Sits at the leading edge, where the convention puts
+   it, and takes the label segment's left padding so the token doesn't widen. */
+.l-ui-combobox__grip {
+  @apply flex shrink-0 items-center
+         pl-2
+         text-foreground-muted;
+}
+
+.l-ui-combobox__grip + .l-ui-tag__text {
+  @apply pl-1.5;
+}
+
+.l-ui-combobox__move {
+  @apply px-1;
+}
+
+.l-ui-combobox__move:disabled {
+  @apply opacity-40
+         cursor-default;
+}
+
+/* The min-height matches a token's (l-ui-tag), so the control is the same
+   height whether or not anything is selected - without it the shorter line box
+   of an empty input makes the field grow as the first token lands. */
+.l-ui-combobox__input {
+  @apply flex-1
+         min-w-[8rem] min-h-8
+         px-1.5 py-1
+         text-inherit
+         bg-transparent
+         border-0
+         outline-none;
+}
+
+.l-ui-combobox__listbox {
+  @apply absolute right-0 left-0 z-30
+         max-h-64
+         mt-1 p-1
+         overflow-y-auto
+         bg-background
+         border border-border rounded-sm
+         shadow-lg;
+}
+
+.l-ui-combobox__option {
+  @apply flex items-center justify-between
+         gap-2 px-3 py-2.5
+         text-sm font-inter text-foreground
+         hover:bg-surface
+         rounded-sm
+         transition-colors
+         cursor-pointer;
+}
+
+/* The highlighted option follows aria-activedescendant, not DOM focus, which
+   stays in the input while the list is browsed. It takes the stronger of the
+   two surfaces so a keyboard highlight stays legible under a stray pointer. */
+.l-ui-combobox__option--active {
+  @apply bg-surface-highlighted;
+}
+
+/* Reserved rather than removed, so options don't shift as they are chosen.
+   The accent pair is used both ways round, so the tick keeps its contrast in
+   either theme. */
+.l-ui-combobox__option-check {
+  @apply flex shrink-0 items-center justify-center
+         w-5 h-5
+         text-accent-foreground
+         bg-accent
+         rounded-full
+         invisible;
+}
+
+/* Sized well inside the circle so the tick has room to breathe. It is drawn as
+   a stroked path rather than a filled one, so the weight stays readable at
+   this size - see the stroke-width on the icon itself. */
+.l-ui-combobox__option-check-icon {
+  @apply w-2.5 h-2.5;
+}
+
+.l-ui-combobox__option[aria-selected="true"] .l-ui-combobox__option-check {
+  @apply visible;
+}
+
+.l-ui-combobox__option--create {
+  @apply font-medium;
+}
+
+.l-ui-combobox__empty {
+  @apply px-3 py-2.5
+         text-sm font-inter text-foreground-muted;
+}
+
+/* Stands in for a "searching" message: a request in flight is a state, and a
+   message that comes and goes within a keystroke cannot be read. The ring keeps
+   its shape without the animation, so it still reads as busy where motion is
+   turned down. */
+.l-ui-combobox__spinner {
+  @apply block shrink-0
+         w-4 h-4
+         border-2 border-border border-t-foreground-muted rounded-full
+         animate-spin
+         motion-reduce:animate-none;
+}
+
+/* Sits at the trailing edge of the control, where a search field puts its
+   progress. */
+.l-ui-combobox__busy {
+  @apply flex shrink-0 items-center
+         pr-1.5;
+}
+
+/* What the list has to say about itself - a search in flight, a failure, or a
+   truncated result set. Sticks to the foot of the scrolling list, since a note
+   saying the results were cut short is no use below the fold, and is set apart
+   from the options above it because it is not something that can be chosen. */
+.l-ui-combobox__notice {
+  @apply sticky bottom-0 flex items-center
+         gap-2 px-3 py-2
+         text-xs font-inter text-foreground-muted
+         bg-background;
+}
+
+/* Smaller than the control's, so a page being fetched reads as a detail of the
+   list rather than competing with it. */
+.l-ui-combobox__notice .l-ui-combobox__spinner {
+  @apply w-3 h-3;
+}
+
+/* The list's own bottom padding would sit below the sticky notice, leaving a gap
+   for the options to scroll through, so it is dropped while the notice is
+   showing - the notice brings its own padding. */
+.l-ui-combobox__listbox:has(.l-ui-combobox__notice:not([hidden])) {
+  @apply pb-0;
+}
+
+/* The rule only earns its place once there is a list above it to separate. */
+.l-ui-combobox__option ~ .l-ui-combobox__notice {
+  @apply mt-1 pt-2
+         border-t border-border;
+}
+
 /* Panel */
 
 .l-ui-panel__button {