tam_select 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3f063f1d79268f900b10c4b86399cba1a34dac0154a90c4c12fd505771a1431
-  data.tar.gz: 0cf4fe7a1cf1d1dc479065318819db1ced4e71888e81e6c98a25fc6920841852
+  metadata.gz: 77477a755bd92b2c88c2f6909b1cd30fc80f4586cc06b047a60a524e95b08b8f
+  data.tar.gz: 55381cbe7a64e822f2f2ea6d48afc933d00f353b4f5563d733606b1520bc09df
 SHA512:
-  metadata.gz: 8ad40f38121d3e83e9260c825c8bbd7546c62d87073fef14ef63c70fd027a1a08bcbd18d51d60198d3a06410b2e3c3ffd325182f99b9b08c1af7b23e725a70c3
-  data.tar.gz: 55469f46c8348ed51dff78070efe3ddf8b95ce43cb2ae3d5b299382bf80437022fe1f91066e07c2b4d061abfba0c984d892d958616692a02415c062e4cb622db
+  metadata.gz: 749ebc117bccbcb42ada9476629f5897cec512fbd80c669be9bf64150554e2e217907efbd4d4cbb636707bb9650921f630c164ad6fa1cca12141309d1bfcba67
+  data.tar.gz: b2b39df96276b3255dce1ab5903ec53ede199a0e741f51b36d243bc129708992a09035150c4f946dfd2da2a065dc43ec9267886d985fcc39a8fff496d95014d4

data/README.md

@@ -1,7 +1,7 @@
-the # Tam Select
+# Tam Select
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Gem Version](https://img.shields.io/badge/version-0.1.1-blue.svg)](https://github.com/tamiru/tam_select)
+[![Gem Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://github.com/tamiru/tam_select)
 
 **Tam Select** is an accessible, searchable select component for Ruby on Rails, built for Simple Form, Stimulus, Turbo, and Tailwind CSS. It keeps the native `<select>` as the source of truth, so Rails form submission, validation, selected values, and browser autofill continue to work.
 
@@ -36,6 +36,7 @@ app/javascript/tam_select/tam_select.js
 app/javascript/controllers/tam_select_controller.js
 app/inputs/tam_select_input.rb
 app/controllers/concerns/tam_select_paginatable.rb
+app/controllers/concerns/tam_select_remote.rb
 app/controllers/tam_select_remote_controller.rb
 app/helpers/tam_select_helper.rb
 ```
@@ -72,6 +73,7 @@ Review `git diff` afterward because `--force` overwrites application-specific cu
 - Local search and user-created tags
 - Remote JSON search with debouncing and incremental pagination
 - Loading, empty, and error states
+- Polished search control with clear, search, selected, and open-state affordances
 - Keyboard navigation: arrows, Enter, Escape, Tab, and Backspace
 - Combobox/listbox ARIA semantics
 - Light and dark Tailwind themes
@@ -103,6 +105,18 @@ When the Rails generator is used, scan the generated component source:
 @source "../../javascript/tam_select/**/*.js";
 ```
 
+Tam Select includes adaptive light and dark styles for every state. It follows a `dark` class on the document or any ancestor and also sets the appropriate native `color-scheme`:
+
+```js
+document.documentElement.classList.toggle("dark")
+```
+
+For Tailwind CSS 4 class-based theming, define the variant in the application stylesheet if it is not already present:
+
+```css
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
 ## Rails and Stimulus
 
 The install generator copies the Stimulus controller into your application, where Stimulus normally discovers it automatically. If controllers are registered manually:
@@ -131,7 +145,9 @@ Stimulus destroys generated markup when Turbo removes the select and recreates i
 
 ## Simple Form
 
-The install generator creates `app/inputs/tam_select_input.rb`. Use it like any other Simple Form input:
+The install generator creates `app/inputs/tam_select_input.rb`. Use `as: :tam_select` with any Simple Form collection input.
+
+### Local collection
 
 ```erb
 <%= form.input :region_id,
@@ -139,16 +155,49 @@ The install generator creates `app/inputs/tam_select_input.rb`. Use it like any
       collection: Region.order(:name),
       label_method: :name,
       value_method: :id,
+      prompt: "Select region" %>
+```
+
+### Remote collection
+
+Keep the currently selected record in the initial collection so edit forms can display its label before the AJAX request completes:
+
+```erb
+<%= form.input :region_id,
+      as: :tam_select,
+      collection: [form.object.region].compact,
+      label_method: :name,
+      value_method: :id,
       prompt: "Select region",
       input_html: {
         tam_options: {
-          remoteUrl: region_options_path(format: :json),
-          minQueryLength: 1
+          remoteUrl: tam_select_options_regions_path(format: :json),
+          minQueryLength: 1,
+          debounce: 250
+        }
+      } %>
+```
+
+The concern and route required by this example are described in [Add remote search to an existing controller](#add-remote-search-to-an-existing-controller).
+
+### Multiple selection
+
+```erb
+<%= form.input :skill_ids,
+      as: :tam_select,
+      collection: Skill.order(:name),
+      label_method: :name,
+      value_method: :id,
+      input_html: {
+        multiple: true,
+        tam_options: {
+          searchable: true,
+          closeAfterSelect: false
         }
       } %>
 ```
 
-For a many-to-many field, add `multiple: true` to `input_html`.
+Options are passed under `input_html[:tam_options]`. Common options include `searchable`, `creatable`, `clearable`, `placeholder`, `searchPlaceholder`, `remoteUrl`, `minQueryLength`, and `debounce`. See [Main options](#main-options) for defaults.
 
 ## Remote API contract
 
@@ -157,8 +206,8 @@ For a many-to-many field, add `multiple: true` to `input_html`.
 ```json
 {
   "items": [
-    { "value": "1", "label": "Addis Ababa" },
-    { "value": "2", "label": "Afar" }
+    { "value": "1", "label": "Hana Bekele", "detail": "Admission no. UG/1024/26", "meta": "Active", "image": "/avatars/hana.jpg" },
+    { "value": "2", "label": "Afar", "detail": "Semera", "meta": "AF" }
   ],
   "pagination": {
     "page": 1,
@@ -172,31 +221,39 @@ The generator installs `TamSelectPaginatable` as a Rails response helper. A comp
 
 Secure remote endpoints exactly like other Rails JSON endpoints. Scope records by the current user's permissions and never trust a submitted value merely because it appeared in the dropdown.
 
-### Generic remote controller
+### Add remote search to an existing controller
 
-The installer generates `TamSelectRemoteController`. Create a small subclass for each allowed remote source:
+Include `TamSelectRemote` and declare the allowed model and searchable fields. This adds the public `tam_select_options` action to the controller:
 
 ```ruby
-# app/controllers/region_options_controller.rb
-class RegionOptionsController < TamSelectRemoteController
-  tam_select model: Region, label: :name, search_by: %i[name code]
-
-  private
-
-  # Override this method when records require authorization or tenant scoping.
-  def tam_select_scope(config)
-    current_account.regions.order(:name)
-  end
+# app/controllers/regions_controller.rb
+class RegionsController < ApplicationController
+  include TamSelectRemote
+
+  tam_select_remote(
+    model: Region,
+    label: :name,
+    value: :id,
+    detail: :description,
+    meta: :code,
+    search_by: %i[name code],
+    scope: -> { Region.order(:name) },
+    per_page: 20
+  )
 end
 ```
 
-Expose the JSON endpoint and pass it to the input:
+The optional `scope` lambda runs in the controller context, so it can use `current_user`, `current_account`, or an authorization policy.
 
 ```ruby
 # config/routes.rb
-get "region_options", to: "region_options#index", defaults: { format: :json }
+resources :regions do
+  get :tam_select_options, on: :collection, defaults: { format: :json }
+end
 ```
 
+Point Simple Form to that collection action:
+
 ```erb
 <%= form.input :region_id,
       as: :tam_select,
@@ -205,18 +262,51 @@ get "region_options", to: "region_options#index", defaults: { format: :json }
       value_method: :id,
       input_html: {
         tam_options: {
-          remoteUrl: region_options_path(format: :json),
+          remoteUrl: tam_select_options_regions_path(format: :json),
           minQueryLength: 1
         }
       } %>
 ```
 
-Do not accept a model name from request parameters. Declaring each source in a controller subclass prevents clients from querying arbitrary application models.
+Typing sends `GET /regions/tam_select_options.json?q=addis&page=1` and receives the standard Tam Select JSON payload.
+
+Remote items may include optional `detail`, `meta`, and `image` fields. Tam Select renders the primary label with the detail on a second line and an optional circular image on the left. The selected value keeps the same image, label, and detail, including an initial value rendered before remote search completes. `meta` remains a badge on the right.
+
+This works well for program and student searches. For example, return the program name as `label` and admission as `detail`:
+
+```ruby
+tam_select_remote(
+  model: Estudent::Program,
+  label: :name,
+  detail: ->(program) { program.admission.to_s },
+  search_by: %i[name],
+  scope: -> { Estudent::Program.includes(admission: %i[admission_type enrollment_type enrollment_mode]).order(:name) }
+)
+```
+
+For student search, add the admission number and photo URL:
+
+```ruby
+tam_select_remote(
+  model: Estudent::Student,
+  label: ->(student) { student.full_name },
+  detail: ->(student) { "Admission no. #{student.applicant.registration_number}" },
+  image: ->(student) { url_for(student.applicant.person.avatar) if student.applicant.person.avatar.attached? },
+  search_by: %i[id_number],
+  scope: -> { Estudent::Student.includes(applicant: { person: { avatar_attachment: :blob } }) }
+)
+```
+
+For a local native select, provide the same values as option data attributes:
+
+```erb
+<option value="1" data-detail="Admission no. UG/1024/26" data-meta="Active" data-image="/avatars/hana.jpg">Hana Bekele</option>
+```
 
 The browser sends requests such as:
 
 ```text
-GET /region_options.json?q=addis&page=1
+GET /regions/tam_select_options.json?q=addis&page=1
 Accept: application/json
 ```
 
@@ -224,7 +314,7 @@ Test an endpoint independently with:
 
 ```bash
 curl -H "Accept: application/json" \
-  "http://localhost:3000/region_options.json?q=addis&page=1"
+  "http://localhost:3000/regions/tam_select_options.json?q=addis&page=1"
 ```
 
 A `406 Not Acceptable` response means the route or controller rejected JSON. Keep `defaults: { format: :json }` on the route, use a `.json` URL, and ensure the controller does not restrict responses to HTML only.
@@ -262,6 +352,7 @@ instance.destroy()
 | `minQueryLength` | `0` | Characters required before requesting |
 | `valueField` | `value` | Remote item value key |
 | `labelField` | `label` | Remote item label key |
+| `imageField` | `image` | Remote item image URL key |
 | `classes` | `{}` | Overrides any Tailwind class group |
 
 ## Events

data/lib/generators/tam_select/install_generator.rb

@@ -18,6 +18,7 @@ module TamSelect
 
       def copy_controller_concern
         copy_file "lib/generators/tam_select/templates/tam_select_paginatable.rb", "app/controllers/concerns/tam_select_paginatable.rb"
+        copy_file "lib/generators/tam_select/templates/tam_select_remote.rb", "app/controllers/concerns/tam_select_remote.rb"
       end
 
       def copy_remote_controller

data/lib/generators/tam_select/templates/tam_select_paginatable.rb

@@ -3,7 +3,7 @@ module TamSelectPaginatable
 
   private
 
-  def tam_select_payload(scope, label:, value: :id, per_page: 20)
+  def tam_select_payload(scope, label:, value: :id, detail: nil, meta: nil, image: nil, per_page: 20)
     page = [params.fetch(:page, 1).to_i, 1].max
     records = scope.limit(per_page + 1).offset((page - 1) * per_page).to_a
     has_more = records.length > per_page
@@ -11,9 +11,12 @@ module TamSelectPaginatable
     {
       items: records.first(per_page).map do |record|
         {
-          value: record.public_send(value).to_s,
-          label: label.respond_to?(:call) ? label.call(record) : record.public_send(label).to_s
-        }
+          value: tam_select_record_value(record, value).to_s,
+          label: tam_select_record_value(record, label).to_s,
+          detail: detail && tam_select_record_value(record, detail).to_s,
+          meta: meta && tam_select_record_value(record, meta).to_s,
+          image: image && tam_select_record_value(record, image).to_s
+        }.compact
       end,
       pagination: {
         page: page,
@@ -22,4 +25,8 @@ module TamSelectPaginatable
       }
     }
   end
+
+  def tam_select_record_value(record, resolver)
+    resolver.respond_to?(:call) ? resolver.call(record) : record.public_send(resolver)
+  end
 end

data/lib/generators/tam_select/templates/tam_select_remote.rb

@@ -0,0 +1,60 @@
+module TamSelectRemote
+  extend ActiveSupport::Concern
+
+  included do
+    include TamSelectPaginatable
+    class_attribute :tam_select_remote_config, instance_writer: false
+  end
+
+  class_methods do
+    def tam_select_remote(model:, label:, value: :id, detail: nil, meta: nil, image: nil, search_by: nil, scope: nil, per_page: 20)
+      self.tam_select_remote_config = {
+        model: model,
+        label: label,
+        value: value,
+        detail: detail,
+        meta: meta,
+        image: image,
+        search_by: Array(search_by || label),
+        scope: scope,
+        per_page: per_page
+      }.freeze
+    end
+  end
+
+  def tam_select_options
+    config = tam_select_remote_config!
+    records = tam_select_remote_search(tam_select_remote_scope(config), config)
+
+    render json: tam_select_payload(
+      records,
+      label: config[:label],
+      value: config[:value],
+      detail: config[:detail],
+      meta: config[:meta],
+      image: config[:image],
+      per_page: config[:per_page]
+    )
+  end
+
+  private
+
+  def tam_select_remote_config!
+    self.class.tam_select_remote_config ||
+      raise("Configure #{self.class.name} with tam_select_remote(...)")
+  end
+
+  def tam_select_remote_scope(config)
+    config[:scope] ? instance_exec(&config[:scope]) : config[:model].all
+  end
+
+  def tam_select_remote_search(records, config)
+    query = params[:q].to_s.strip
+    return records if query.blank?
+
+    model = config[:model]
+    pattern = "%#{model.sanitize_sql_like(query)}%"
+    predicates = config[:search_by].map { |field| model.arel_table[field].matches(pattern) }
+    records.where(predicates.reduce(&:or))
+  end
+end

data/lib/generators/tam_select/templates/tam_select_remote_controller.rb

@@ -1,44 +1,6 @@
 class TamSelectRemoteController < ApplicationController
-  include TamSelectPaginatable
+  include TamSelectRemote
 
-  class_attribute :tam_select_config, instance_writer: false
-
-  def self.tam_select(model:, label:, value: :id, search_by: nil, per_page: 20)
-    self.tam_select_config = {
-      model: model,
-      label: label,
-      value: value,
-      search_by: Array(search_by || label),
-      per_page: per_page
-    }.freeze
-  end
-
-  def index
-    config = self.class.tam_select_config
-    raise "Configure #{self.class.name} with tam_select(...)" unless config
-
-    records = search(tam_select_scope(config), config)
-    render json: tam_select_payload(
-      records,
-      label: config[:label],
-      value: config[:value],
-      per_page: config[:per_page]
-    )
-  end
-
-  private
-
-  def tam_select_scope(config)
-    config[:model].all
-  end
-
-  def search(records, config)
-    query = params[:q].to_s.strip
-    return records if query.blank?
-
-    model = config[:model]
-    pattern = "%#{model.sanitize_sql_like(query)}%"
-    predicates = config[:search_by].map { |field| model.arel_table[field].matches(pattern) }
-    records.where(predicates.reduce(&:or))
-  end
+  # Configure this base controller in a subclass, or include TamSelectRemote
+  # directly in an existing resource controller. See the Tam Select README.
 end

data/lib/tam_select/version.rb

@@ -1,3 +1,3 @@
 module TamSelect
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/src/tam-select.js

@@ -1,18 +1,25 @@
 const DEFAULT_CLASSES = {
-  wrapper: "tam-select relative w-full",
-  control: "flex min-h-10 w-full cursor-text flex-wrap items-center gap-1.5 rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 shadow-sm transition focus-within:border-blue-500 focus-within:ring-2 focus-within:ring-blue-500/20 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100",
-  controlDisabled: "cursor-not-allowed bg-zinc-100 opacity-60 dark:bg-zinc-800",
-  input: "min-w-16 flex-1 border-0 bg-transparent p-0 text-sm text-zinc-900 outline-none placeholder:text-zinc-400 focus:ring-0 dark:text-zinc-100 dark:placeholder:text-zinc-500",
+  wrapper: "tam-select relative w-full text-zinc-900 [color-scheme:light] dark:text-zinc-100 dark:[color-scheme:dark]",
+  control: "flex min-h-11 w-full cursor-text flex-wrap items-center gap-2 rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 shadow-sm transition-colors hover:border-zinc-400 focus-within:border-blue-500 focus-within:ring-2 focus-within:ring-blue-500/20 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100 dark:shadow-black/20 dark:hover:border-zinc-600 dark:focus-within:border-blue-400 dark:focus-within:ring-blue-400/20",
+  controlDisabled: "cursor-not-allowed bg-zinc-100 opacity-60 dark:bg-zinc-800 dark:text-zinc-400",
+  input: "min-w-16 flex-1 border-0 bg-transparent p-0 text-left text-sm text-zinc-900 outline-none placeholder:text-zinc-400 focus:ring-0 dark:text-zinc-100 dark:placeholder:text-zinc-500",
+  searchIcon: "size-4 shrink-0 text-zinc-400 dark:text-zinc-500",
   placeholder: "pointer-events-none text-zinc-400 dark:text-zinc-500",
   tag: "inline-flex max-w-full items-center gap-1 rounded-md bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700 ring-1 ring-inset ring-blue-200 dark:bg-blue-950/50 dark:text-blue-300 dark:ring-blue-800",
   tagRemove: "rounded p-0.5 hover:bg-blue-100 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:hover:bg-blue-900",
-  clear: "ml-auto rounded p-1 text-zinc-400 hover:bg-zinc-100 hover:text-zinc-700 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:hover:bg-zinc-800 dark:hover:text-zinc-200",
+  clear: "ml-auto rounded p-1 text-zinc-400 transition-colors hover:bg-zinc-100 hover:text-zinc-700 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:text-zinc-500 dark:hover:bg-zinc-800 dark:hover:text-zinc-200 dark:focus:ring-blue-400",
   chevron: "ml-1 size-4 shrink-0 text-zinc-400 transition-transform",
   chevronOpen: "rotate-180",
-  dropdown: "absolute z-50 mt-1 max-h-72 w-full overflow-auto rounded-lg border border-zinc-200 bg-white p-1 shadow-xl ring-1 ring-black/5 dark:border-zinc-700 dark:bg-zinc-900",
-  option: "flex cursor-pointer items-center justify-between gap-3 rounded-md px-3 py-2 text-sm text-zinc-700 outline-none dark:text-zinc-200",
-  optionActive: "bg-zinc-100 dark:bg-zinc-800",
-  optionSelected: "bg-blue-50 font-medium text-blue-700 dark:bg-blue-950/50 dark:text-blue-300",
+  dropdown: "absolute z-50 mt-1.5 max-h-72 w-full overflow-auto rounded-lg border border-zinc-200 bg-white p-1.5 shadow-xl ring-1 ring-black/5 dark:border-zinc-700 dark:bg-zinc-900 dark:shadow-black/40 dark:ring-white/10",
+  option: "flex min-h-11 cursor-pointer items-center justify-between gap-3 rounded-md px-3 py-2 text-sm text-zinc-700 outline-none transition-colors dark:text-zinc-200",
+  optionContent: "flex min-w-0 flex-1 items-center gap-3",
+  optionText: "flex min-w-0 flex-1 flex-col",
+  optionLabel: "font-normal",
+  optionDetail: "text-xs font-normal text-zinc-500 dark:text-zinc-400",
+  optionImage: "size-9 shrink-0 rounded-full bg-zinc-100 object-cover dark:bg-zinc-800",
+  optionMeta: "shrink-0 rounded bg-zinc-100 px-1.5 py-0.5 text-xs font-medium text-zinc-600 dark:bg-zinc-800 dark:text-zinc-300",
+  optionActive: "bg-zinc-100 text-zinc-950 dark:bg-zinc-800 dark:text-white",
+  optionSelected: "bg-blue-50 text-blue-700 dark:bg-blue-950/60 dark:text-blue-300",
   optionDisabled: "cursor-not-allowed opacity-50",
   message: "px-3 py-6 text-center text-sm text-zinc-500 dark:text-zinc-400",
   spinner: "size-4 animate-spin rounded-full border-2 border-zinc-300 border-t-blue-600",
@@ -20,6 +27,7 @@ const DEFAULT_CLASSES = {
 }
 
 const ICONS = {
+  search: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path stroke-linecap="round" d="m14.5 14.5 3 3m-1.25-8.25a7 7 0 1 1-14 0 7 7 0 0 1 14 0Z"/></svg>',
   chevron: '<svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" d="M5.22 7.22a.75.75 0 011.06 0L10 10.94l3.72-3.72a.75.75 0 111.06 1.06l-4.25 4.25a.75.75 0 01-1.06 0L5.22 8.28a.75.75 0 010-1.06z" clip-rule="evenodd"/></svg>',
   close: '<svg viewBox="0 0 20 20" fill="currentColor" class="size-3" aria-hidden="true"><path d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z"/></svg>',
   check: '<svg viewBox="0 0 20 20" fill="currentColor" class="size-4" aria-hidden="true"><path fill-rule="evenodd" d="M16.7 5.3a1 1 0 010 1.4l-8 8a1 1 0 01-1.4 0l-4-4a1 1 0 011.4-1.4L8 12.6l7.3-7.3a1 1 0 011.4 0z" clip-rule="evenodd"/></svg>'
@@ -61,6 +69,7 @@ export class TamSelect {
       minQueryLength: 0,
       valueField: "value",
       labelField: "label",
+      imageField: "image",
       itemsPath: "items",
       paginationPath: "pagination",
       classes: {},
@@ -107,6 +116,9 @@ export class TamSelect {
 
     this.values = document.createElement("div")
     this.values.className = "contents"
+    this.searchIcon = document.createElement("span")
+    this.searchIcon.className = this.classes.searchIcon
+    this.searchIcon.innerHTML = ICONS.search
     this.input = document.createElement("input")
     this.input.type = "text"
     this.input.className = this.classes.input
@@ -132,7 +144,7 @@ export class TamSelect {
     this.dropdown.setAttribute("role", "listbox")
     if (this.multiple) this.dropdown.setAttribute("aria-multiselectable", "true")
 
-    this.control.append(this.values, this.input, this.clearButton, this.chevron)
+    this.control.append(this.values, this.searchIcon, this.input, this.clearButton, this.chevron)
     this.wrapper.append(this.control, this.dropdown)
     this.select.after(this.wrapper)
     this.applyDisabled()
@@ -171,7 +183,16 @@ export class TamSelect {
   readNativeOptions() {
     this.items = Array.from(this.select.options)
       .filter(option => option.value !== "" || option.selected)
-      .map(option => ({ value: option.value, label: option.textContent.trim(), disabled: option.disabled, selected: option.selected, option }))
+      .map(option => ({
+        value: option.value,
+        label: option.textContent.trim(),
+        detail: option.dataset.detail || null,
+        meta: option.dataset.meta || null,
+        image: option.dataset.image || null,
+        disabled: option.disabled,
+        selected: option.selected,
+        option
+      }))
     this.filterLocal(false)
   }
 
@@ -179,7 +200,7 @@ export class TamSelect {
 
   filterLocal(render = true) {
     const needle = normalize(this.query)
-    this.filtered = this.items.filter(item => !needle || normalize(item.label).includes(needle))
+    this.filtered = this.items.filter(item => !needle || [item.label, item.detail, item.meta].some(value => normalize(value).includes(needle)))
     this.activeIndex = this.filtered.findIndex(item => !item.disabled)
     if (render) this.renderDropdown()
   }
@@ -189,12 +210,10 @@ export class TamSelect {
     this.values.replaceChildren()
     if (this.multiple) selected.forEach(item => this.values.append(this.makeTag(item)))
     else if (selected.length) {
-      const label = document.createElement("span")
-      label.className = "min-w-0 flex-1 truncate"
-      label.textContent = selected[0].label
-      this.values.append(label)
+      this.values.append(this.makeItemContent(selected[0], true))
     }
     const hasValue = selected.length > 0
+    this.searchIcon.classList.toggle("hidden", !this.options.searchable || (hasValue && !this.opened))
     this.input.classList.toggle("hidden", !this.multiple && hasValue && !this.opened)
     this.input.placeholder = hasValue ? "" : this.options.placeholder
     this.clearButton.classList.toggle("hidden", !this.options.clearable || !hasValue || this.select.disabled)
@@ -247,10 +266,14 @@ export class TamSelect {
     option.setAttribute("role", "option")
     option.setAttribute("aria-selected", String(Boolean(item.selected)))
     option.setAttribute("aria-disabled", String(Boolean(item.disabled)))
-    const label = document.createElement("span")
-    label.className = "min-w-0 flex-1 truncate"
-    label.textContent = item.label
-    option.append(label)
+    const content = this.makeItemContent(item)
+    option.append(content)
+    if (item.meta) {
+      const meta = document.createElement("span")
+      meta.className = this.classes.optionMeta
+      meta.textContent = item.meta
+      option.append(meta)
+    }
     if (item.selected) {
       const check = document.createElement("span")
       check.innerHTML = ICONS.check
@@ -261,6 +284,34 @@ export class TamSelect {
     return option
   }
 
+  makeItemContent(item, selected = false) {
+    const content = document.createElement("span")
+    content.className = this.classes.optionContent
+    if (selected) content.classList.add("min-w-0", "flex-1")
+    if (item.image) {
+      const image = document.createElement("img")
+      image.className = this.classes.optionImage
+      image.src = item.image
+      image.alt = ""
+      image.loading = "lazy"
+      content.append(image)
+    }
+    const text = document.createElement("span")
+    text.className = this.classes.optionText
+    const label = document.createElement("span")
+    label.className = `${this.classes.optionLabel} truncate`
+    label.textContent = item.label
+    text.append(label)
+    if (item.detail) {
+      const detail = document.createElement("span")
+      detail.className = `${this.classes.optionDetail} truncate`
+      detail.textContent = item.detail
+      text.append(detail)
+    }
+    content.append(text)
+    return content
+  }
+
   makeCreateOption() {
     const option = document.createElement("div")
     option.className = this.classes.option
@@ -361,12 +412,29 @@ export class TamSelect {
   addItem(raw) {
     const value = String(raw.value ?? raw[this.options.valueField])
     const existing = this.items.find(item => String(item.value) === value)
-    if (existing) return existing
+    if (existing) {
+      const image = raw.image ?? raw[this.options.imageField]
+      Object.assign(existing, raw, {
+        detail: raw.detail ?? existing.detail,
+        meta: raw.meta ?? existing.meta,
+        image: image ?? existing.image
+      })
+      if (existing.option) {
+        if (existing.detail != null) existing.option.dataset.detail = String(existing.detail)
+        if (existing.meta != null) existing.option.dataset.meta = String(existing.meta)
+        if (existing.image != null) existing.option.dataset.image = String(existing.image)
+      }
+      return existing
+    }
     const label = String(raw.label ?? raw[this.options.labelField] ?? value)
     const option = new Option(label, value, Boolean(raw.selected), Boolean(raw.selected))
     option.dataset.tamSelectGenerated = ""
+    if (raw.detail != null) option.dataset.detail = String(raw.detail)
+    if (raw.meta != null) option.dataset.meta = String(raw.meta)
+    const image = raw.image ?? raw[this.options.imageField]
+    if (image != null) option.dataset.image = String(image)
     this.select.add(option)
-    const item = { ...raw, value, label, option, selected: option.selected, disabled: Boolean(raw.disabled) }
+    const item = { ...raw, value, label, image: image == null ? null : String(image), option, selected: option.selected, disabled: Boolean(raw.disabled) }
     option.disabled = item.disabled
     this.items.push(item)
     this.filterLocal(false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tam_select
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Tamiru Hailu
@@ -62,6 +62,7 @@ files:
 - lib/generators/tam_select/templates/tam_select_helper.rb
 - lib/generators/tam_select/templates/tam_select_input.rb
 - lib/generators/tam_select/templates/tam_select_paginatable.rb
+- lib/generators/tam_select/templates/tam_select_remote.rb
 - lib/generators/tam_select/templates/tam_select_remote_controller.rb
 - lib/tam_select.rb
 - lib/tam_select/engine.rb