tam_select 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cdee3c229caaeda5d7f572395009c1ffd03e58c1f5376c215ced0e751c35fb9
-  data.tar.gz: 9896dd22aa1dc9af3727596c1bee1d82ca6b8f1462a3e24a5177b10306853888
+  metadata.gz: 77477a755bd92b2c88c2f6909b1cd30fc80f4586cc06b047a60a524e95b08b8f
+  data.tar.gz: 55381cbe7a64e822f2f2ea6d48afc933d00f353b4f5563d733606b1520bc09df
 SHA512:
-  metadata.gz: 271d3b88383037c504189080665c0c15e19a640e6f8efe0d580683d9f543a0a56ff496a667064b788fbd8a8f1ddc8f48512d755cfc10985ec043d36c042891ce
-  data.tar.gz: be82081ad386749cb1ff40f1cd48ca80417104712c417de25dccc969082f3f2edfce09a912bce53467c34e170b1a0235245caede8d53717b7fff5d3b21d8f072
+  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-1.1.0-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.
 
@@ -73,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
@@ -104,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:
@@ -193,8 +206,8 @@ Options are passed under `input_html[:tam_options]`. Common options include `sea
 ```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,
@@ -221,6 +234,8 @@ class RegionsController < ApplicationController
     model: Region,
     label: :name,
     value: :id,
+    detail: :description,
+    meta: :code,
     search_by: %i[name code],
     scope: -> { Region.order(:name) },
     per_page: 20
@@ -255,51 +270,43 @@ Point Simple Form to that collection action:
 
 Typing sends `GET /regions/tam_select_options.json?q=addis&page=1` and receives the standard Tam Select JSON payload.
 
-### Generic remote controller
+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.
 
-The installer generates `TamSelectRemoteController`. Create a small subclass for each allowed remote source:
+This works well for program and student searches. For example, return the program name as `label` and admission as `detail`:
 
 ```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
-end
+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) }
+)
 ```
 
-Expose the JSON endpoint and pass it to the input:
+For student search, add the admission number and photo URL:
 
 ```ruby
-# config/routes.rb
-get "region_options", to: "region_options#index", defaults: { format: :json }
+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
-<%= form.input :region_id,
-      as: :tam_select,
-      collection: [form.object.region].compact,
-      label_method: :name,
-      value_method: :id,
-      input_html: {
-        tam_options: {
-          remoteUrl: region_options_path(format: :json),
-          minQueryLength: 1
-        }
-      } %>
+<option value="1" data-detail="Admission no. UG/1024/26" data-meta="Active" data-image="/avatars/hana.jpg">Hana Bekele</option>
 ```
 
-Do not accept a model name from request parameters. Declaring each source in a controller subclass prevents clients from querying arbitrary application models.
-
 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
 ```
 
@@ -307,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.
@@ -345,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/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

@@ -7,11 +7,14 @@ module TamSelectRemote
   end
 
   class_methods do
-    def tam_select_remote(model:, label:, value: :id, search_by: nil, scope: nil, per_page: 20)
+    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
@@ -27,6 +30,9 @@ module TamSelectRemote
       records,
       label: config[:label],
       value: config[:value],
+      detail: config[:detail],
+      meta: config[:meta],
+      image: config[:image],
       per_page: config[:per_page]
     )
   end

data/lib/tam_select/version.rb

@@ -1,3 +1,3 @@
 module TamSelect
-  VERSION = "1.1.1"
+  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.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Tamiru Hailu