layered-ui-rails 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63d902f842afed6b1e9d7784677a2a748d3775ef9884bb27f9ed6439133b3638
-  data.tar.gz: 25d8cf1f06bfadd24dc8e97efd1cc14f4d818ce5285e4da980dcd65f21d96ea9
+  metadata.gz: 9dfe5e770b8f6bbc52666be84b646ebe235fdf2cf1e15f7d9759fb1b880bc5be
+  data.tar.gz: d829e69ff914ace72a2e80da0ff468459dfbac0942cea828a6e28693ac46126c
 SHA512:
-  metadata.gz: 97a9c888d83d7a4a2317eae38fdd77e91dcb8eeab33b76b85bb7dc8afb9c7d8349ff5f9b693633f16218b8a906d3f2029b1753a6f730910a83f47169d523f4e0
-  data.tar.gz: 80572d1c7b424944cc9a7b324b749a01bc3708f0251eacc0ea2f4faa6be864bfbc8249b4ea6ed68961878a2f29bd1d516acb84f6af7cd50d73123bb09302c062
+  metadata.gz: e288640f0616aa44e630c238e17eb5213ab7ddedf0d7d3cd334b010481f51b4726c681c969dc6ed0b6ccece28471e9b8c84fffa9dba713b395f9eec1fdf2f747
+  data.tar.gz: 6c3e63f142ccdff6917c7e792f8cdf94f0446ac50134db3b639ea96faff354cb5b138178133e5b0acff3f7234beed2a20d71876e6143de1e2550e8e9cf60978e

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

@@ -196,33 +196,48 @@ Drag handle for resizing the panel width on desktop.
 
 ## Search form (`l-ui--search-form`)
 
-Manages multi-scope search forms with parameter preservation and Turbo frame support.
+Searches as the user types, and manages multi-scope search forms with parameter preservation and Turbo frame support.
 
-**Values:** `scope` (String, default `"q"`)
-**Actions:** `preserve`, `clear`, `rewriteLink`
+**Targets:** `input`, `clear`
+**Values:** `scope` (String, default `"q"`), `pageParam` (String, default `"page"` - Pagy's page key for this collection, given rather than derived from `scope`), `live` (Boolean, default `false`), `minChars` (Number, default `0`), `count` (Number, default `-1` - meaning no count was given, so nothing is announced)
+**Actions:** `search`, `clearSearch`, `toggleClear`, `submitNow`, `preserve`, `clear`, `rewriteLink`
 
 ```html
 <form data-controller="l-ui--search-form"
       data-l-ui--search-form-scope-value="q"
+      data-l-ui--search-form-page-param-value="page"
+      data-l-ui--search-form-live-value="true"
+      data-l-ui--search-form-count-value="12"
       data-action="submit->l-ui--search-form#preserve"
-      data-turbo-frame="results">
-  <!-- search fields -->
-  <button type="button" data-action="click->l-ui--search-form#clear">
-    Clear
-  </button>
+      data-turbo-frame="results"
+      data-turbo-action="replace"
+      role="search" aria-label="Search">
+  <input data-l-ui--search-form-target="input"
+         data-action="input->l-ui--search-form#search keydown.esc->l-ui--search-form#clearSearch">
+  <button type="button" data-l-ui--search-form-target="clear"
+          data-action="l-ui--search-form#clearSearch" hidden>Clear search</button>
 </form>
 ```
 
-When multiple search forms exist on one page (each with a different `scope` value), submitting one form automatically preserves the other forms' query parameters. The `page` param and any scoped page param matching the scope (e.g. `users_page` for scope `users_q`) are reset on submit so pagination returns to page 1.
+- **`search`** - debounced (300ms, longer than the combobox's, since a search here re-renders a whole collection). Submits with `requestSubmit()`, not `submit()`, so the `submit` event fires and `preserve` still runs. A keystroke arriving mid-request is fine: Turbo stops a frame submission already in flight, so no `AbortController` is needed here.
+- **`toggleClear`** - shows or hides the clear button to match the field. Only wired on a form that does not search as you type, where nothing else runs on a keystroke; `search` does it as part of its own work.
+- **`clearSearch`** - the ✕ and Escape in the field. Skips the debounce, and focuses the input *before* the button hides itself, so focus does not fall to the body (WCAG 2.4.3).
+- **Caret preservation** - a frame render replaces the form and the input being typed into. The value, selection and focus are stashed in module state (the only thing that survives the swap), keyed per form, and restored by the controller that connects in its place. Only a render answering one of this form's own searches restores focus, so a sort link or a page link never steals it; entries older than 5s are ignored.
+- **Announcements** - after a search, the result count goes to the layout's `#l-ui-live-region`, which sits outside every frame. The term is included in the message because a live region does not re-announce text identical to what it already holds.
+- **`clear`** - for a *hand-built* clear link beside an unframed form, which has no controller of its own (`l_ui_search_form` wires the in-field clear button to `clearSearch` instead, on any framed form, live or not). It rewrites the clicked link's href so the other scopes' params survive the navigation; give the link its own `data-turbo-frame` and `data-turbo-action` to keep it inside the frame.
+
+When multiple search forms exist on one page (each with a different `scope` value), submitting one form automatically preserves the other forms' query parameters. This form's own `pageParam` is reset on submit so pagination returns to page 1 - give each collection its own (`page_param: "users_page"` on the helper, `l_ui__search_form_page_param_value` on the frame), since Pagy's `page_key:` is the host's choice and cannot be inferred from the Ransack `search_key`.
 
 **`rewriteLink`** - merges current URL params into a clicked link's href. Useful for pagination links inside Turbo Frames where the server-rendered href may be missing params from other scopes. Attach to a parent element (e.g. the Turbo Frame):
 
 ```html
 &lt;%= turbo_frame_tag "users_collection", data: { turbo_action: "advance",
       controller: "l-ui--search-form", l_ui__search_form_scope_value: "users_q",
+      l_ui__search_form_page_param_value: "users_page",
       action: "click->l-ui--search-form#rewriteLink" } do %&gt;
   &lt;%= l_ui_search_form(@users_q, url: users_path, fields: [:name, :email],
-                       clear: true, turbo_frame: "users_collection") %&gt;
+                       live: true, count: @users_pagy.count,
+                       page_param: "users_page", turbo_frame: "users_collection") %&gt;
   &lt;%= l_ui_table(@users, ..., query: @users_q, turbo_frame: "users_collection") %&gt;
   &lt;%= l_ui_pagy(@users_pagy) %&gt;
 &lt;% end %&gt;

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

@@ -192,6 +192,9 @@ Always combine the `l-ui-surface` base class with any modifiers (e.g. `l-ui-surf
 .l-ui-select-container           Select wrapper (custom arrow)
 
 .l-ui-search-inline            Inline search form layout
+.l-ui-search-control             Field + clear button wrapper (own positioning context)
+.l-ui-search-control--clearable  Leaves room in the field for the clear button
+.l-ui-search-control__clear      Clear button inside the field's trailing edge (24x24)
 
 .l-ui-radio                    Radio button group
 .l-ui-radio__item              Radio item wrapper

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

@@ -131,8 +131,9 @@ l_ui_pagy(pagy)
 
 ```ruby
 l_ui_search_form(query, url: nil, fields: [], predicate: :cont, combinator: :or,
-                 label: "Search", placeholder: nil, button: "Search",
-                 clear: nil, turbo_frame: nil, html: {}, &block)
+                 label: "Search", placeholder: nil, button: nil, clear: nil,
+                 live: false, count: nil, min_chars: nil,
+                 page_param: "page", turbo_frame: nil, html: {}, &block)
 ```
 
 - `query` (Ransack::Search) - the `@q` object from controller
@@ -140,19 +141,35 @@ l_ui_search_form(query, url: nil, fields: [], predicate: :cont, combinator: :or,
 - `fields` (Array<Symbol>) - fields to search (simple mode)
 - `predicate` (Symbol) - ransack predicate, default `:cont`
 - `combinator` (Symbol) - `:or` or `:and` for multiple fields
-- `label` (String) - hidden label for the search input
+- `label` (String) - hidden label for the search input; also labels the `search` landmark in live mode
 - `placeholder` (String) - input placeholder
-- `button` (String) - submit button text
-- `clear` (String|Boolean) - clear button text; `true` for default, `false` to hide
+- `button` (String) - text for a *visible* submit button. In live mode, omitting it renders a submit that is present but neither seen nor tabbed to, which is what Enter and a JS-less browser submit through. A non-live form always gets a visible button, since it needs one that can be pressed
+- `clear` (String|Boolean) - the clear button built into the field; defaults to on whenever `turbo_frame:` is given, `false` to omit, a string to name it. Clearing means clearing the field and submitting, which the `l-ui--search-form` controller does, and that goes on any framed form - so a non-live form clears too. Asking for it without a frame raises, since there is no controller to drive it
+- `live` (Boolean, default `false`) - search as the user types. **Opt-in, and requires `turbo_frame:`** - passing `live: true` without one raises, since typing into an unframed form would mean a page load per keystroke. A frame alone does not turn it on: where a response lands and whether typing submits are separate decisions
+- `count` (Integer) - size of the result set, announced after each search. Live mode only. Without it nothing is announced, and `live: true` with no `count:` logs a warning in development
+- `min_chars` (Integer) - hold the search back until the term is this long. Live mode only
+- `page_param` (String, default `"page"`) - Pagy's page key for this collection, dropped when carrying other collections' params across a submit. Pagy's `page_key:` is the host's choice and bears no fixed relation to the Ransack `search_key`, so it is passed rather than guessed
 - `turbo_frame` (String) - turbo frame to target
 - `html` (Hash) - additional form HTML attributes
 - `&block` - custom form markup (overrides simple mode)
 
-Simple mode:
+`count:` and `min_chars:` describe typing, so they mean nothing to a form that submits when asked to: passing one alongside `live: false` raises rather than being quietly dropped. `clear:` is not one of these - it follows the controller, not live mode.
+
+A live search sets `data-turbo-action="replace"` on the *form*, so a keystroke does not push a history entry. Turbo reads the action from the submitter, then the form, then the frame, so sort links and pagination inside the same frame still advance.
+
+Simple mode - submits when asked to, with a visible Search button:
 
 ```erb
 <%= l_ui_search_form(@q, url: users_path, fields: [:name, :email],
-    placeholder: "Search users", clear: true, turbo_frame: "users") %>
+    placeholder: "Search users", turbo_frame: "users") %>
+```
+
+Searching as you type, with a clear button in the field:
+
+```erb
+<%= l_ui_search_form(@q, url: users_path, fields: [:name, :email],
+    placeholder: "Search users", turbo_frame: "users", live: true,
+    count: @pagy.count, page_param: "users_page") %>
 ```
 
 Custom mode:
@@ -166,6 +183,29 @@ Custom mode:
 <% end %>
 ```
 
+## Search control (requires ransack gem)
+
+```ruby
+l_ui_search_control(form, attribute, label: "Search", placeholder: nil,
+                    clear: nil, button: nil, live: false)
+```
+
+The control on its own - field, clear button and submit - for a caller who passes a block to `l_ui_search_form` and builds the row by hand. Both `live:` and `clear:` need the `l-ui--search-form` controller, which `l_ui_search_form` puts on the form when given a `turbo_frame:`. A hand-built form may not carry it, so `live:` is off unless asked for. `clear:` follows `live:` - `live: true` vouches for the controller being there - so pass `clear: true` explicitly for a form that carries the controller but should not submit as you type.
+
+```erb
+<%= l_ui_search_form(@q, url: users_path, turbo_frame: "users", live: true,
+                     count: @pagy.count) do |f| %>
+  <div class="l-ui-search-inline">
+    <%= my_filter_hidden_fields %>
+    <%= l_ui_search_control(f, :name_or_email_cont, placeholder: "Search users", live: true) %>
+  </div>
+<% end %>
+```
+
+The input is deliberately `type="text"`, not `type="search"`: WebKit draws its own cancel button on the latter, which would sit under this one and take the same tap.
+
+Left non-live the Search button is visible and the field still clears. Only a form with no `turbo_frame:` goes without a clear button; to put one beside such a form, build the link yourself and give it `data-action="click->l-ui--search-form#clear"`, which rewrites the href to carry any other scope's params.
+
 ## Sort link (requires ransack gem)
 
 ```ruby

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.27.0] - 2026-09-20
+
+### Added
+
+- The search box can search as you type. Pass `live: true` with a `turbo_frame:` and `l_ui_search_form` debounces a submit as the field changes, so results narrow without a button to press. Each search replaces the history entry rather than pushing one, so Back leaves the collection instead of replaying the term letter by letter - the URL still carries the term, so a search stays shareable and survives a reload. The action is set on the form, which Turbo reads before the frame's own, so sort links and pagination inside the same frame still advance.
+- The field carries its own clear button, built into its trailing edge and shown only once there is something to clear. Escape in the field clears it too, and focus returns to the input rather than falling to the body. `clear: false` omits the button; a string names it.
+- `l_ui_search_control` renders the control - field, clear button and submit - on its own, for a caller who passes a block to `l_ui_search_form` and builds the row by hand.
+- `count:` has the size of the result set announced after each search. Without it nothing is announced: a screen reader is otherwise told nothing when results change with no button press. The message goes to the layout's live region, which sits outside every frame, since a live region replaced in the same render as its own text is not reliably announced.
+- `min_chars:` holds a search back until the term is worth asking about.
+- The caret survives the frame render that answers a search, so a typed word is never interrupted mid-letter.
+- `page_param:` names the collection's Pagy page key, which is reset when a search carries the other collections' params across a submit. It was previously guessed from the Ransack `search_key` (`users_q` -> `users_page`), which is a convention nothing enforces: a host whose `page_key:` did not follow it leaked the page param into every preserved submit.
+
+### Fixed
+
+- The clear button keeps up with the field on a form that does not search as you type. Nothing ran on a keystroke there, so it stayed as the server rendered it: still showing over a field the user had just emptied, and still hidden when they typed a term into an empty one.
+- A response no longer pulls focus back into the search field. Whether the field had focus was a snapshot taken when the request went out, so a user who tabbed to something outside the frame while it was in flight was dragged back (WCAG 3.2.5). Focus is now taken back only when the render left it nowhere - the input that held it was destroyed with the frame - which a control outside the frame, still alive and still focused, is not.
+- Clearing the field no longer risks the old term coming back. Clearing changes the field without an input event, and the submit it asks for is declined when the empty term is already the one in flight, so nothing recorded the clear; the pending response then restored the text that had been typed and searched for it again.
+- The result count is announced against the term it actually counted. A response that answered `a` while `ada` was being typed announced its count as results for `ada`. Announcements now wait until the field and the answered term agree, which is the point at which the count is the answer to what the user can see.
+
+### Changed
+
+- **Breaking.** Searching as you type is opt-in. `live:` defaults to `false` and is no longer inferred from `turbo_frame:`: a frame says where a response lands, and whether typing should submit at all is a separate decision about the collection. `live: true` without a `turbo_frame:` raises. Existing framed call sites keep their current behaviour and need `live: true` added to take up the new one.
+- **Breaking.** `count:` and `min_chars:` describe typing, so they mean nothing to a form that submits when asked to: passing one alongside `live: false` now raises rather than being quietly dropped - the same treatment `l_ui_combobox` gives an option it cannot take.
+- **Breaking.** `l_ui_search_control` defaults to `live: false`, matching `l_ui_search_form`. It exists for hand-built forms, which are exactly the forms that may not carry the controller, so the default that works without one is the right one. Its `clear:` follows `live:`, since `live: true` vouches for the controller being present; pass `clear: true` for a form that carries the controller but should not submit as you type.
+- `live: true` with no `count:` logs a warning in development. Nothing is announced when results change without it, which is an accessibility hole rather than a default, and it had no symptom a sighted developer would notice.
+- **Breaking.** `button:` now defaults to `nil`. In live mode that renders a submit which is present but neither seen nor tabbed to - it is what Enter in the field and a browser with no JavaScript submit through. A form that submits only when asked to still gets a visible button, since it needs one that can be pressed; pass a string to name it.
+- **Breaking.** `clear:` now means the clear button inside the field, and defaults to on whenever `turbo_frame:` is given - it follows the `l-ui--search-form` controller, which goes on every framed form to preserve the other scopes, not live mode. A form that submits when asked to clears from inside the field too. Asking for `clear:` without a frame raises, since there is then no controller to drive it. The separate outline clear button is **gone**, along with the "requires an explicit `url:`" error it raised; the controller's `clear` action remains for a hand-built clear link beside an unframed form.
+- **Breaking.** A live search form is now a `search` landmark, labelled from `label:`.
+
 ## [0.26.0] - 2026-09-19
 
 ### Added

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

@@ -1559,6 +1559,37 @@ pre.l-ui-surface {
   }
 }
 
+/* The field and its clear button share a positioning context of their own, so
+   the button sits inside the input's edge whatever else the row holds. */
+.l-ui-search-control {
+  @apply relative flex-1;
+}
+
+/* Room for the button, so a long term scrolls under it rather than behind it. */
+.l-ui-search-control--clearable .l-ui-form__field {
+  @apply pr-10;
+}
+
+/* 24x24 is the smallest target WCAG 2.2 SC 2.5.8 accepts; the mark inside is
+   16px, so the rest is padding rather than a heavier glyph. Drawn in
+   currentColor from the foreground tokens, so it needs no dark-mode invert. */
+.l-ui-search-control__clear {
+  @apply absolute top-1/2 right-2 flex items-center justify-center
+         w-6 h-6
+         p-0
+         text-foreground-muted hover:text-foreground
+         bg-transparent
+         border-0 rounded-full
+         focus-ring
+         transition-colors
+         cursor-pointer;
+  transform: translateY(-50%);
+}
+
+.l-ui-search-control__clear[hidden] {
+  @apply hidden;
+}
+
 /* Switch */
 
 .l-ui-switch {

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

@@ -11,14 +11,43 @@ module Layered
       #     render "layered_ui/shared/search_field", form: f, field: :name_cont, label: "Name"
       #     f.submit "Go", class: "l-ui-button l-ui-button--primary"
       #   end
-      def l_ui_search_form(query, url: nil, fields: [], predicate: :cont, combinator: :or, label: "Search", placeholder: nil, button: "Search", clear: nil, turbo_frame: nil, html: {}, &block)
+      #
+      # Pass live: true (with a turbo_frame:) to search as the user types: no
+      # Search button to press, a clear button in the field, and count: to have
+      # the size of the result set announced. It is opt-in rather than inferred
+      # from turbo_frame:, which only says where a response lands.
+      #
+      # Left alone the form submits when asked to. It still gets the clear
+      # button: clearing means clearing the field and submitting, which the
+      # l-ui--search-form controller does, and that is attached to any framed
+      # form. Only an unframed form goes without - for a clear beside one,
+      # build the link and wire it to the controller's `clear` action.
+      def l_ui_search_form(query, url: nil, fields: [], predicate: :cont, combinator: :or,
+                           label: "Search", placeholder: nil, button: nil, clear: nil,
+                           live: false, count: nil, min_chars: nil,
+                           page_param: "page", turbo_frame: nil, html: {}, &block)
         result = require_ransack("l_ui_search_form") { |msg| tag.p(msg, class: "l-ui-notice l-ui-notice--warning") }
         return result unless result == true
 
+        validate_search_options!("l_ui_search_form", live: live, turbo_frame: turbo_frame,
+                                 clear: clear, count: count, min_chars: min_chars)
+        warn_missing_search_count if live && count.nil?
+
         scope = query.context&.search_key || :q
-        turbo_action = "advance"
+        # The clear button needs the controller, not live mode - and the
+        # controller goes on every framed form, to preserve the other scopes.
+        clear = turbo_frame.present? if clear.nil?
+        # Replace, so Back leaves the collection rather than replaying the term
+        # letter by letter. On the form, which Turbo reads before the frame's
+        # own, so sort links and pagination in that frame still advance.
+        turbo_action = live ? "replace" : "advance"
         html = html.merge(class: ["l-ui-form", html[:class]].compact.join(" "))
 
+        if live
+          html[:role] ||= "search"
+          html[:aria] = { label: label }.merge(html[:aria] || {})
+        end
+
         if turbo_frame
           existing_data = (html[:data] || {}).symbolize_keys
           existing_controller = existing_data[:controller]
@@ -27,10 +56,22 @@ module Layered
           action = [existing_action, "submit->l-ui--search-form#preserve"].compact.join(" ")
           turbo_action = existing_data[:turbo_action] || turbo_action
 
-          html[:data] = existing_data.except(:controller, :action, :l_ui__search_form_scope_value).merge(
+          # What `preserve` and `rewriteLink` drop when carrying other
+          # collections' params across a submit. Passed rather than guessed from
+          # the search key: Pagy's page key is the host's to choose.
+          values = { l_ui__search_form_scope_value: scope,
+                     l_ui__search_form_page_param_value: page_param }
+          if live
+            values[:l_ui__search_form_live_value] = true
+            values[:l_ui__search_form_min_chars_value] = min_chars if min_chars.to_i.positive?
+            values[:l_ui__search_form_count_value] = count unless count.nil?
+          end
+
+          html[:data] = existing_data.except(:controller, :action, :l_ui__search_form_scope_value,
+                                             :l_ui__search_form_page_param_value).merge(
             turbo_frame: turbo_frame, turbo_action: turbo_action,
             controller: controller, action: action,
-            l_ui__search_form_scope_value: scope
+            **values
           )
         end
 
@@ -43,22 +84,69 @@ module Layered
           placeholder ||= "Search by #{fields.map { |f| f.to_s.humanize.downcase }.join(', ')}"
 
           search_form_for(query, url: url, html: html, as: scope) do |f|
-            f.label(combined_field, label, class: "l-ui-sr-only") +
-              tag.div(class: "l-ui-search-inline") do
-                content = f.text_field(combined_field, class: "l-ui-form__field", placeholder: placeholder) +
-                  f.submit(button, class: "l-ui-button l-ui-button--primary")
-                if clear
-                  raise ArgumentError, "l_ui_search_form requires an explicit url: when clear: is set" unless url
-                  clear_options = { class: "l-ui-button l-ui-button--outline" }
-                  clear_options[:data] = { turbo_frame: turbo_frame, turbo_action: turbo_action, action: "click->l-ui--search-form#clear" } if turbo_frame
-                  content += link_to(clear == true ? "Clear" : clear, url, **clear_options)
-                end
-                content
-              end
+            tag.div(class: "l-ui-search-inline") do
+              l_ui_search_control(f, combined_field,
+                                  label: label, placeholder: placeholder,
+                                  button: button, clear: clear, live: live)
+            end
           end
         end
       end
 
+      # The search control itself - the field, a clear button built into its
+      # trailing edge, and the submit that keeps Enter and a JavaScript-less
+      # browser working. Rendered by l_ui_search_form's simple mode, and
+      # available on its own to a caller who passes a block and builds the row
+      # by hand:
+      #
+      #   <%= l_ui_search_form(@q, url: users_path, turbo_frame: "users",
+      #                        live: true, count: @pagy.count) do |f| %>
+      #     <div class="l-ui-search-inline">
+      #       <%= my_filter_hidden_fields %>
+      #       <%= l_ui_search_control(f, :name_or_email_cont, live: true) %>
+      #     </div>
+      #   <% end %>
+      #
+      # Both live: and clear: need the l-ui--search-form controller, which
+      # l_ui_search_form puts on the form when given a turbo_frame:. A
+      # hand-built form may not carry it, so both are off unless asked for.
+      def l_ui_search_control(form, attribute, label: "Search", placeholder: nil,
+                              clear: nil, button: nil, live: false)
+        # live: could not work without the controller, so it vouches for one
+        # being there. On its own the control cannot tell, so clear: is opted
+        # into by a caller who knows their form carries it.
+        clear = live if clear.nil?
+        # Either behaviour drives the field, so either needs it as a target.
+        controlled = live || clear.present?
+        hint_id = ("#{form.object_name}_#{attribute}_hint" if live)
+        actions = []
+        # Live, `search` refreshes the clear button as part of its own work.
+        actions << "input->l-ui--search-form#search" if live
+        actions << "input->l-ui--search-form#toggleClear" if clear.present? && !live
+        actions << "keydown.esc->l-ui--search-form#clearSearch" if controlled
+
+        field = form.text_field(
+          attribute,
+          class: "l-ui-form__field",
+          placeholder: placeholder,
+          autocomplete: "off",
+          # Not type="search": WebKit draws its own cancel button, which would
+          # sit under this one and take the same tap.
+          aria: { describedby: hint_id }.compact,
+          data: (controlled ? { "l-ui--search-form-target" => "input",
+                                action: actions.join(" ") } : {})
+        )
+
+        parts = [ form.label(attribute, label, class: "l-ui-sr-only"), field ]
+        parts << tag.span("Results update as you type.", id: hint_id, class: "l-ui-sr-only") if live
+        parts << l_ui_search_clear_button(form, attribute, clear) if clear
+
+        control = tag.div(safe_join(parts.compact),
+                          class: [ "l-ui-search-control", ("l-ui-search-control--clearable" if clear) ].compact.join(" "))
+
+        safe_join([ control, l_ui_search_submit(form, button, live: live) ].compact)
+      end
+
       SORT_INDICATORS = {
         "asc"  => { symbol: "▲", label: ", sorted ascending",  aria: "ascending" },
         "desc" => { symbol: "▼", label: ", sorted descending", aria: "descending" }
@@ -111,6 +199,100 @@ module Layered
 
       private
 
+      # Options that say something about typing, so they mean nothing to a form
+      # that submits when asked to. Passing one has no visible symptom, so it
+      # names itself rather than being quietly dropped.
+      LIVE_ONLY_OPTIONS = {
+        count: "there is nothing to announce when the user pressed the button themselves",
+        min_chars: "nothing is sent until the form is submitted"
+      }.freeze
+
+      def validate_search_options!(helper, live:, turbo_frame:, clear: nil, **options)
+        if live && turbo_frame.blank?
+          raise ArgumentError,
+                "#{helper} requires a turbo_frame: for live: true - typing into an unframed form " \
+                "would mean a full page load per keystroke"
+        end
+
+        if clear && turbo_frame.blank?
+          raise ArgumentError,
+                "#{helper}'s clear: requires a turbo_frame: - clearing means clearing the field and " \
+                "submitting, which the l-ui--search-form controller does, and it is only attached " \
+                "to a framed form"
+        end
+
+        return if live
+
+        options.each do |key, value|
+          # false and nil both say "not asked for", which is never a conflict.
+          next if value.nil? || value == false
+
+          raise ArgumentError,
+                "#{helper}'s #{key}: applies to live: true only - #{LIVE_ONLY_OPTIONS.fetch(key)}"
+        end
+      end
+
+      # count: is what a screen reader hears when results change with no button
+      # press, so its absence is a hole rather than a default - and one nothing
+      # on screen would reveal. A log line, not markup: the form itself is fine.
+      def warn_missing_search_count
+        return unless Rails.env.development?
+
+        Rails.logger.warn(
+          "[layered-ui-rails] l_ui_search_form with live: true was given no count:, so nothing is " \
+          "announced when results change. Pass count: @pagy.count (or the size of the result set)."
+        )
+      end
+
+      # Live, an unnamed submit is present but neither seen nor tabbed to: what
+      # Enter in the field and a JavaScript-less browser submit through, without
+      # a focus stop nobody can see (WCAG 2.4.7). A form that submits when asked
+      # to needs a button that can be asked, so it always gets a visible one.
+      def l_ui_search_submit(form, button, live: true)
+        return form.submit(button, class: "l-ui-button l-ui-button--primary") if button.is_a?(String)
+        return form.submit("Search", class: "l-ui-button l-ui-button--primary") unless live
+
+        form.submit("Search", class: "l-ui-sr-only", tabindex: -1)
+      end
+
+      def l_ui_search_clear_button(form, attribute, clear)
+        name = clear.is_a?(String) ? clear : "Clear search"
+
+        # Hidden until there is something to clear; the controller corrects it
+        # on connect. Ransack answers a combined reader like `name_or_email_cont`
+        # through method_missing and denies respond_to?, so the value is asked
+        # for rather than checked for.
+        blank = begin
+          form.object.public_send(attribute).blank?
+        rescue NoMethodError
+          true
+        end
+
+        tag.button(
+          safe_join([ l_ui_search_clear_icon, tag.span(name, class: "l-ui-sr-only") ]),
+          type: "button",
+          class: "l-ui-search-control__clear",
+          hidden: blank,
+          data: { "l-ui--search-form-target" => "clear", action: "l-ui--search-form#clearSearch" }
+        )
+      end
+
+      # Rendered inline rather than via image_tag so it inherits the surrounding
+      # currentColor, as the combobox icons do; an <img>-loaded SVG cannot, and
+      # would need the dark:invert of .l-ui-icon.
+      def l_ui_search_clear_icon
+        tag.svg(
+          tag.path("d" => "M6 6 18 18M18 6 6 18",
+                   "stroke-linecap" => "round", "stroke-linejoin" => "round"),
+          class: "l-ui-icon--xs",
+          fill: "none",
+          stroke: "currentColor",
+          "stroke-width" => "2",
+          "viewBox" => "0 0 24 24",
+          "aria-hidden" => "true"
+        )
+      end
+
       def ransack_available?
         defined?(Ransack)
       end

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

@@ -1,12 +1,103 @@
 import { Controller } from "@hotwired/stimulus"
+import { announce, clearAnnounceTimeout } from "layered_ui/utilities/announce"
+
+// Longer than the combobox's: a search re-renders a whole collection, so a
+// keystroke costs more here than a listbox fetch does.
+const SEARCH_DEBOUNCE = 300
+
+// A frame render destroys the input being typed into, so the field's state is
+// held outside the DOM and restored by the controller that connects in its
+// place. Keyed per form: two collections on a page must not restore into each
+// other.
+const stashes = new Map()
+
+// Older than this and the search has been walked away from, so focus is left
+// where the user since put it.
+const STASH_TTL = 5000
 
 // When multiple scoped Ransack collections share one page, preserves other
 // scopes' params across form submits (preserve), clear links (clear), and
-// pagination clicks (rewriteLink).
+// pagination clicks (rewriteLink). In live mode it also searches as the user
+// types, carrying the caret across the frame render that answers.
 export default class extends Controller {
-  static values = { scope: String }
+  static targets = ["input", "clear"]
+  static values = {
+    scope: String,
+    // Given, not derived from scope: Pagy's page key is the host's choice and
+    // follows no rule relating it to the Ransack search key.
+    pageParam: { type: String, default: "page" },
+    live: { type: Boolean, default: false },
+    minChars: { type: Number, default: 0 },
+    // -1 means the caller passed no count, so there is nothing to announce.
+    count: { type: Number, default: -1 }
+  }
+
+  connect() {
+    this._searchTimer = null
+    this._restore()
+    this._refreshClear()
+  }
+
+  disconnect() {
+    clearTimeout(this._searchTimer)
+    // An announcement schedules the shared region to be blanked. Left pending,
+    // it would wipe what the instance replacing this one has just announced.
+    clearAnnounceTimeout(this)
+  }
+
+  search(event) {
+    // A half-composed IME string is not a term yet.
+    if (event && event.isComposing) return
+
+    this._stash()
+    this._refreshClear()
+    this._schedule()
+  }
+
+  // The in-field clear button, and Escape in the field. An intentional search
+  // for the empty term, so it skips the debounce.
+  clearSearch(event) {
+    if (event) event.preventDefault()
+    if (!this.hasInputTarget) return
 
+    this.inputTarget.value = ""
+    // Focused before the button hides itself, or focus falls to the body and
+    // the user loses their place (WCAG 2.4.3).
+    this.inputTarget.focus()
+    this._refreshClear()
+    // No input event fires for this, and submitNow declines when the empty term
+    // is already in flight - so without this the stash keeps the old text, and
+    // the pending response restores it over the cleared field and searches it.
+    this._stash()
+    this.submitNow()
+  }
+
+  // A form that does not search as you type runs nothing on a keystroke, so the
+  // clear button needs telling that the field has gained or lost its term.
+  toggleClear() {
+    this._refreshClear()
+  }
+
+  submitNow() {
+    clearTimeout(this._searchTimer)
+
+    const term = this._term
+    // Too short to be worth asking about, but not yet abandoned.
+    if (term.length > 0 && term.length < this.minCharsValue) return
+    if (term === this._sent) return
+
+    // requestSubmit, not submit: it fires the submit event, so `preserve` runs
+    // and the form's own data-turbo-action is honoured.
+    this.element.requestSubmit()
+  }
+
+  // Every submit lands here - typed, Enter, or the clear button - so it is
+  // where the field's state is recorded for the render about to replace it.
   preserve(event) {
+    clearTimeout(this._searchTimer)
+    this._sent = this._term
+    this._stash({ submitted: this._sent })
+
     this.element.querySelectorAll("[data-l-ui-preserved]").forEach(el => el.remove())
 
     for (const [key, value] of this.#otherParams()) {
@@ -41,21 +132,98 @@ export default class extends Controller {
     link.href = url.pathname + url.search
   }
 
+  _schedule() {
+    clearTimeout(this._searchTimer)
+    this._searchTimer = setTimeout(() => this.submitNow(), SEARCH_DEBOUNCE)
+  }
+
+  _stash(extra = {}) {
+    if (!this.hasInputTarget) return
+
+    const input = this.inputTarget
+    stashes.set(this._key, {
+      ...(stashes.get(this._key) || {}),
+      value: input.value,
+      start: input.selectionStart,
+      end: input.selectionEnd,
+      focused: document.activeElement === input,
+      at: Date.now(),
+      ...extra
+    })
+  }
+
+  _restore() {
+    const stash = stashes.get(this._key)
+    if (!stash) return
+    stashes.delete(this._key)
+
+    // Only a render that answers a search of ours takes focus back: a sort link
+    // or a page link renders the same frame, and must not.
+    if (!("submitted" in stash)) return
+    if (Date.now() - stash.at > STASH_TTL) return
+    if (!this.hasInputTarget) return
+
+    this._sent = stash.submitted
+
+    // Anything typed while the request was in flight is newer than the term the
+    // response echoes, and wins.
+    if (this.inputTarget.value !== stash.value) this.inputTarget.value = stash.value
+
+    // The stash says the field had focus when the request went out, not whether
+    // it still should. A control outside the frame survives the render and is
+    // still focused; only focus left on the body was destroyed with the input,
+    // and an answer arriving must not pull the user back (WCAG 3.2.5).
+    const focusWentNowhere = !document.activeElement || document.activeElement === document.body
+    if (stash.focused && focusWentNowhere) {
+      this.inputTarget.focus({ preventScroll: true })
+      this.inputTarget.setSelectionRange(stash.start, stash.end)
+    }
+
+    // The count answers the term submitted, not what has been typed since, so
+    // announcing waits until they agree - the scheduling below means a truer
+    // answer is already on its way.
+    if (stash.value === stash.submitted) this._announceResults(stash.submitted)
+
+    // Keystrokes that landed after the request went out are still unsearched.
+    if (stash.value !== stash.submitted) this._schedule()
+  }
+
+  // The response renders the count onto the form, so it is already the new one
+  // here. It goes to the layout's region, outside every frame: a live region
+  // replaced in the same render as its own text is not reliably announced.
+  _announceResults(term) {
+    if (this.countValue < 0) return
+
+    const count = this.countValue
+    const results = count === 0 ? "No results" : count === 1 ? "1 result" : `${count} results`
+
+    // The term is included so no two announcements repeat verbatim - identical
+    // text in a live region is not announced again.
+    announce(term ? `${results} for ${term}` : results, this)
+  }
+
+  _refreshClear() {
+    if (this.hasClearTarget) this.clearTarget.hidden = this._term.length === 0
+  }
+
+  get _term() {
+    return this.hasInputTarget ? this.inputTarget.value : ""
+  }
+
+  get _key() {
+    return `${this.scopeValue}|${this.element.action}`
+  }
+
   #otherParams() {
     const currentParams = new URLSearchParams(window.location.search)
     const scope = this.scopeValue
     const result = new URLSearchParams()
 
     for (const [key, value] of currentParams) {
-      if (key === scope || key.startsWith(scope + "[") || key === "commit" || key === "page" || key === this.#pageParam) continue
+      if (key === scope || key.startsWith(scope + "[") || key === "commit" || key === this.pageParamValue) continue
       result.append(key, value)
     }
 
     return result
   }
-
-  get #pageParam() {
-    const scope = this.scopeValue
-    return scope.endsWith("_q") ? scope.slice(0, -2) + "_page" : null
-  }
 }

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.26.0"
+    VERSION = "0.27.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - layered.ai