keystone_ui 0.52.0 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f67e6bd82fbcc8daa1e455f60140395bb002aee59ba2f055191130827707b0a
-  data.tar.gz: 6335b10c5578ce27579cab7e1da5a2f05e4eeca7c99d5e92173d7278a25efd9c
+  metadata.gz: e7f6b6d63755b597d7b876ddba35bd4f6bbdb6039b0b16be57197cf4af01ea48
+  data.tar.gz: c2093a32f35bf5beb3a469cfffe14033e491f8e6435bb32003b203652574f990
 SHA512:
-  metadata.gz: b49bb408da1f06272f711cbe7f077f8b7b438f89ae13c91d18309e3afda1d81689667ac45ff6bccb5fb94fae2abc02457caae6fc6890278635b2aae641b872ef
-  data.tar.gz: 2e7fd2e99b1368b703f3f29ee435ad4a2695856fd2301e182d5022d84ea29122d448712c940f77e9a0ab43310d436c37e80c4298001536d137a2b68cbd24db7c
+  metadata.gz: ac7541139dd31e4269cbca2dc13e3201d6c44ffd9b4a8088f90a2361f15cee3e627d808277b31e7a5981c0c19d56fa453cb186350870cf48d5416d7ef0ab6a2b
+  data.tar.gz: bf3cb63e70d990d5b01bee266a2446d15cd8f7b710b63c767e129134312d9f6e999d6e56ef6d709614ff4a63699b303e231cbebed874001ce4c03f7c46756401

data/app/assets/javascripts/keystone_ui/index.js

@@ -1,5 +1,6 @@
 import ColorPickerController from "keystone_ui/color_picker_controller"
 import MultiSelectController from "keystone_ui/multi_select_controller"
+import SearchSelectController from "keystone_ui/search_select_controller"
 import SwipeDeckController from "keystone_ui/swipe_deck_controller"
 import ColumnPickerController from "keystone_ui/column_picker_controller"
 import FileUploadController from "keystone_ui/file_upload_controller"
@@ -20,6 +21,7 @@ import { keepPageThemeInStep } from "keystone_ui/page_theme"
 export function registerControllers(application) {
   application.register("color-picker", ColorPickerController)
   application.register("multi-select", MultiSelectController)
+  application.register("search-select", SearchSelectController)
   application.register("swipe-deck", SwipeDeckController)
   application.register("column-picker", ColumnPickerController)
   application.register("file-upload", FileUploadController)

data/app/assets/javascripts/keystone_ui/search_select_controller.js

@@ -0,0 +1,69 @@
+import { Controller } from "@hotwired/stimulus"
+
+const escaped = (text) => String(text).replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`)
+
+export default class extends Controller {
+  static targets = ["id", "input", "list", "newFields"]
+  static values = { url: String, newLabel: String }
+
+  async search() {
+    const response = await fetch(`${this.urlValue}?q=${encodeURIComponent(this.inputTarget.value)}`, { headers: { Accept: "application/json" } })
+    this.matches = await response.json()
+    this.highlighted = -1
+    this.draw()
+    this.listTarget.classList.remove("hidden")
+  }
+
+  key(event) {
+    if (event.key === "Enter") return this.pickHighlighted(event)
+    if (event.key === "Escape") return this.listTarget.classList.add("hidden")
+
+    const moves = { ArrowDown: 1, ArrowUp: -1 }
+    if (!(event.key in moves) || !this.matches) return
+
+    event.preventDefault()
+    this.highlighted = Math.min(Math.max(this.highlighted + moves[event.key], 0), this.choiceCount() - 1)
+    this.draw()
+  }
+
+  pickHighlighted(event) {
+    if (this.highlighted === undefined || this.highlighted < 0) return
+
+    const match = this.matches[this.highlighted]
+    if (match) this.choose({ params: match, preventDefault: () => event.preventDefault() })
+    else this.chooseNew(event)
+  }
+
+  draw() {
+    this.listTarget.innerHTML = this.matches.map((match, index) => this.option(match, index === this.highlighted)).join("") + this.newOption(this.highlighted === this.matches.length)
+  }
+
+  choiceCount() {
+    return this.matches.length + (this.newLabelValue ? 1 : 0)
+  }
+
+  choose(event) {
+    event.preventDefault()
+    this.idTarget.value = String(event.params.id)
+    this.inputTarget.value = event.params.label
+    if (this.hasNewFieldsTarget) this.newFieldsTarget.classList.add("hidden")
+    this.listTarget.classList.add("hidden")
+  }
+
+  chooseNew(event) {
+    event.preventDefault()
+    this.idTarget.value = ""
+    if (this.hasNewFieldsTarget) this.newFieldsTarget.classList.remove("hidden")
+    this.listTarget.classList.add("hidden")
+  }
+
+  newOption(highlighted = false) {
+    if (!this.newLabelValue) return ""
+
+    return `<li role="option" class="ks-menu-option" data-action="mousedown->search-select#chooseNew" aria-selected="${highlighted}">${escaped(this.newLabelValue)}</li>`
+  }
+
+  option(match, highlighted = false) {
+    return `<li role="option" class="ks-menu-option" data-action="mousedown->search-select#choose" data-search-select-id-param="${escaped(match.id)}" data-search-select-label-param="${escaped(match.label)}" aria-selected="${highlighted}">${escaped(match.label)}</li>`
+  }
+}

data/app/components/keystone/ui/search_select_component.html.erb

@@ -0,0 +1,9 @@
+<div class="<%= WRAPPER_CLASSES %>" data-controller="search-select" data-search-select-url-value="<%= url %>" data-search-select-new-label-value="<%= new_label %>">
+  <label class="<%= LABEL_CLASSES %>"><%= label %></label>
+  <input type="hidden" name="<%= name %>" value="<%= selected_id %>" data-search-select-target="id">
+  <input type="text" autocomplete="off" value="<%= selected_label %>" class="<%= Keystone::Ui::InputComponent::BASE_CLASSES %>" data-search-select-target="input" data-action="input->search-select#search keydown->search-select#key">
+  <ul role="listbox" class="<%= LIST_CLASSES %>" data-search-select-target="list"></ul>
+  <% if content? %>
+    <div class="hidden" data-search-select-target="newFields"><%= content %></div>
+  <% end %>
+</div>

data/app/components/keystone/ui/search_select_component.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class SearchSelectComponent < ViewComponent::Base
+      WRAPPER_CLASSES = "ks-form-field relative"
+      LABEL_CLASSES = "ks-label"
+      LIST_CLASSES = "ks-menu absolute z-10 w-full hidden"
+
+      attr_reader :name, :label, :url, :selected_id, :selected_label, :new_label
+
+      def initialize(name:, label:, url:, selected_id: nil, selected_label: nil, new_label: nil)
+        @name = name
+        @label = label
+        @url = url
+        @selected_id = selected_id
+        @selected_label = selected_label
+        @new_label = new_label
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_helper.rb

@@ -193,6 +193,10 @@ module KeystoneUiHelper
     render Keystone::Ui::MultiSelectComponent.new(**args)
   end
 
+  def ui_search_select(**args, &block)
+    render Keystone::Ui::SearchSelectComponent.new(**args), &block
+  end
+
   def ui_swipe_deck(**args, &block)
     render Keystone::Ui::SwipeDeckComponent.new(**args), &block
   end

data/config/importmap.rb

@@ -1,6 +1,7 @@
 pin "keystone_ui/index", to: "keystone_ui/index.js"
 pin "keystone_ui/color_picker_controller", to: "keystone_ui/color_picker_controller.js"
 pin "keystone_ui/multi_select_controller", to: "keystone_ui/multi_select_controller.js"
+pin "keystone_ui/search_select_controller", to: "keystone_ui/search_select_controller.js"
 pin "keystone_ui/swipe_deck_controller", to: "keystone_ui/swipe_deck_controller.js"
 pin "keystone_ui/column_picker_controller", to: "keystone_ui/column_picker_controller.js"
 pin "keystone_ui/file_upload_controller", to: "keystone_ui/file_upload_controller.js"

data/lib/keystone_ui/safelist.rb

@@ -51,6 +51,7 @@ module Keystone
       Keystone::Ui::ShowPageComponent,
       Keystone::Ui::OptionCardComponent,
       Keystone::Ui::RadioCardComponent,
+      Keystone::Ui::SearchSelectComponent,
       Keystone::Ui::CheckboxRowComponent,
       Keystone::Ui::ProgressComponent,
       Keystone::Ui::ColorPickerComponent,

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.52.0"
+  VERSION = "0.53.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -1,6 +1,6 @@
 ---
 name: keystone_ui-develop
-description: Use PROACTIVELY for building or editing screens in a Rails app that has keystone_ui — page shells with Back links and breadcrumbs, forms and fields, data tables with saved columns, desktop navigation, sidebars and bottom tabs, action menus for a record's Edit and Delete, dashboards with stat cards, charts, funnels and goal buckets, amounts shown in green or red as a gain or loss, info buttons and breakdowns, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
+description: Use PROACTIVELY for building or editing screens in a Rails app that has keystone_ui — page shells with Back links and breadcrumbs, forms and fields, a search field that picks a record or enters a new one, data tables with saved columns, desktop navigation, sidebars and bottom tabs, action menus for a record's Edit and Delete, dashboards with stat cards, charts, funnels and goal buckets, amounts shown in green or red as a gain or loss, info buttons and breakdowns, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
 tools: Bash, Read, Write, Edit, Grep
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -52,6 +52,7 @@ not available in the app yet, that is `keystone_ui-install`'s job.
 - `ui_textarea` — a bare styled textarea with no label.
 - `ui_select` — a bare styled select with no label.
 - `ui_multi_select` — a dropdown of checkboxes posting every checked value.
+- `ui_search_select` — a form field that searches the app as a person types and submits the id of the record they pick.
 - `ui_file_upload` — a file drop zone with selected-file feedback.
 - `ui_color_picker` — a colour swatch that writes a hex value into a hidden input.
 - `ui_radio_card` — a selectable card backed by a radio input.
@@ -302,6 +303,31 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
      `"status[]"`. `options:` is `[[label, value], ...]` and `selected:` is the
      values to check. Its button reads "All <label>" with nothing checked and
      "N selected" otherwise.
+   - `ui_search_select(name:, label:, url:, selected_id: nil, selected_label: nil, new_label: nil)`
+     is one field inside a `ui_form`, for picking one record from more than a
+     select can list. Each keystroke sends `GET url?q=<typed text>` with
+     `Accept: application/json`, and the app answers with a JSON array of
+     `{ "id": ..., "label": ... }` objects in the order to list them. Labels
+     are shown as plain text. Picking a match by click, or by the arrow keys
+     and Enter, puts its id in a hidden input named `name` and its label in
+     the field. Escape closes the list.
+   - The app owns the search endpoint: the route, which records it searches,
+     how it matches the typed text, how many matches it returns, and which
+     records the current user may see. Ask the developer for each, and scope
+     the query to the current account.
+   - `selected_id:` and `selected_label:` open the field with a record already
+     chosen, such as on an edit screen, so the form submits that id unchanged
+     when nothing else is picked.
+   - Typing without picking leaves the hidden id as it was, so the form submits
+     the last picked id, or `selected_id:`, whatever the field shows.
+   - `new_label:` adds a last choice, such as "Enter a new address", shown in
+     the list after each search. Picking it clears the hidden id and shows the
+     block passed to the helper, which holds the fields for a new record such
+     as `ui_form_field` calls. Picking a match afterwards hides them again.
+   - The block's fields are submitted whether shown or hidden, so the app's
+     controller treats a blank id as "create from the new fields" and a present
+     id as "use that record and ignore the new fields". Ask the developer
+     whether a person may enter a new record, and what `new_label:` says.
    - `ui_file_upload(name:, label: nil, accept: nil, multiple: false, hint: nil)`
      needs the enclosing form to be multipart.
    - `ui_color_picker(name:, value: "#000000", label: nil)` writes the chosen
@@ -516,7 +542,8 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
       and rejecting sends `swipe-deck:skip`. Both carry `detail.itemId` (the
       item's `id`, or its position) and `detail.card`, and `complete` carries
       `detail.value` from an input marked `data-swipe-deck-value`, or `null`.
-    - For these, the pipeline's URLs and the column picker's save URL, do not
+    - For these, the pipeline's URLs, the column picker's save URL and the
+      search select's search URL, do not
       invent routes or how the outcome is stored. Ask the developer, then
       build what they pick.
 

data/the_local/agents/keystone_ui-info.md

@@ -12,7 +12,7 @@ nothing and gives no steps.
 
 keystone_ui is a Rails engine gem that supplies a host app's UI as view helpers
 built on ViewComponent. Screens are built from named pieces — page shells,
-sections, panels, grids, forms and fields, data tables, navigation, cards, stat
+sections, panels, grids, forms and fields, search dropdowns, data tables, navigation, cards, stat
 tiles, charts, funnels, goal buckets, pipelines, breakdowns and info buttons —
 instead of hand-written ERB and Tailwind. Every class the UI renders lives in the
 gem, so two pages built from the same helpers cannot disagree about spacing,
@@ -78,6 +78,14 @@ One decision: is keystone_ui set up in the app?
   it: which hideable columns to hide and their order. With a save address, a
   "Columns" menu lets the user change it. A locked first column stays in view
   while the table scrolls sideways and is never hidden or moved.
+- **Search dropdowns.** A search dropdown picks one record by its id from
+  matches the host serves. As the user types, it requests the host's search
+  address with the text as `q` and expects JSON back: a list of matches, each
+  with an `id` and a `label`. Picking a match submits its id under the field's
+  name. When the dropdown offers a choice to enter a new record, picking it
+  submits an empty id and shows the new record's fields the page placed inside
+  the dropdown, and picking a match afterwards hides them again. The arrow keys
+  move through the list, Enter picks, and Escape closes it.
 - **Action menus.** Each action is a label, an address and an HTTP method. A
   plain visit is a link, and any other method is a button, so an action that
   changes data is never a bare link. A delete asks for confirmation by default.
@@ -98,9 +106,9 @@ One decision: is keystone_ui set up in the app?
 - **Static Tailwind classes.** Class names are never interpolated, so Tailwind's
   scanner finds them. Sizes that depend on data, such as a progress bar's
   width, use an inline style. The host needs tailwindcss-rails v4+.
-- **Interactivity is Stimulus.** Dropdowns, modals, tab switchers, the column
-  picker, info buttons, charts, copy buttons and the theme toggle ship as
+- **Interactivity is Stimulus.** Dropdowns, search dropdowns, modals, tab
+  switchers, the column picker, info buttons, charts, copy buttons and the theme toggle ship as
   Stimulus controllers, so a host writes no JavaScript. Components that post,
   such as the column picker and the pipeline, post to endpoints the host or
   another gem owns.
-- Ruby >= 3.2, ViewComponent >= 2.0 and < 5, keystone_ui-styles >= 0.14.0.
+- Ruby >= 3.2, ViewComponent >= 2.0 and < 5, keystone_ui-styles >= 0.25.0.

data/the_local/agents/keystone_ui-install.md

@@ -50,7 +50,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
 ## How to use it
 
 1. Confirm the prerequisites: Ruby >= 3.2 and **tailwindcss-rails v4+** in the
-   host app. The gem brings ViewComponent and keystone_ui-styles 0.14.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.25.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 
@@ -92,7 +92,8 @@ built on ViewComponent; hook it in before building any screen with those helpers
    - `app/javascript/controllers/index.js not found` — ask the developer where
      the Stimulus application is set up and add those two lines there. Without
      them, dropdowns, modals, file uploads, the column picker, the theme toggle,
-     the info button's popups and the other interactive components do nothing.
+     the info button's popups, the search select's list of matches and the other
+     interactive components do nothing.
      `registerControllers(application)` also copies `data-theme` and `data-look`
      from each page Turbo renders onto the `<html>` tag. Without it, a Turbo
      visit keeps the theme and look of the first page loaded.
@@ -159,7 +160,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
    ```
 
    Buttons, panels, cards, alerts, badges, form fields, the modal, the mobile
-   action menu, the action menu, the column picker, multi select, copy button, theme toggle,
+   action menu, the action menu, the column picker, multi select, search select, copy button, theme toggle,
    checkbox row, radio card, option card, file upload and colour picker read
    these variables. So do the data display components: stat card, chart card,
    card link, CTA banner, feature grid, hero, data table, code, accordion,

data/the_local/interface.yml

@@ -52,6 +52,7 @@ develop:
   - ui_settings_link
   - ui_color_picker
   - ui_multi_select
+  - ui_search_select
   - ui_swipe_deck
   - ui_column_picker
   - ui_form
@@ -137,6 +138,9 @@ sources:
   - app/components/keystone/ui/mobile_header_component.html.erb
   - app/components/keystone/ui/modal_component.rb
   - app/components/keystone/ui/multi_select_component.rb
+  - app/components/keystone/ui/search_select_component.rb
+  - app/components/keystone/ui/search_select_component.html.erb
+  - app/assets/javascripts/keystone_ui/search_select_controller.js
   - app/components/keystone/ui/nav_dropdown_component.rb
   - app/components/keystone/ui/nav_item_component.rb
   - app/components/keystone/ui/navbar_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.52.0
+  version: 0.53.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.25.0
+        version: 0.27.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.25.0
+        version: 0.27.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -67,6 +67,7 @@ files:
 - app/assets/javascripts/keystone_ui/modal_controller.js
 - app/assets/javascripts/keystone_ui/multi_select_controller.js
 - app/assets/javascripts/keystone_ui/page_theme.js
+- app/assets/javascripts/keystone_ui/search_select_controller.js
 - app/assets/javascripts/keystone_ui/stat_card_info_controller.js
 - app/assets/javascripts/keystone_ui/swipe_deck_controller.js
 - app/assets/javascripts/keystone_ui/tab_switcher_controller.js
@@ -186,6 +187,8 @@ files:
 - app/components/keystone/ui/radio_card_component.html.erb
 - app/components/keystone/ui/radio_card_component.rb
 - app/components/keystone/ui/saved_layout.rb
+- app/components/keystone/ui/search_select_component.html.erb
+- app/components/keystone/ui/search_select_component.rb
 - app/components/keystone/ui/section_component.html.erb
 - app/components/keystone/ui/section_component.rb
 - app/components/keystone/ui/select_component.html.erb