tam_select 1.2.0 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77477a755bd92b2c88c2f6909b1cd30fc80f4586cc06b047a60a524e95b08b8f
-  data.tar.gz: 55381cbe7a64e822f2f2ea6d48afc933d00f353b4f5563d733606b1520bc09df
+  metadata.gz: d83036c60f51e481343b204bc7e6333c92cc36d6c2d1190656cd956b0e3c4301
+  data.tar.gz: 0576a3df23baad11bc818b4a2d9c05ccc035e7c7ae369b67606ef1c03c398aea
 SHA512:
-  metadata.gz: 749ebc117bccbcb42ada9476629f5897cec512fbd80c669be9bf64150554e2e217907efbd4d4cbb636707bb9650921f630c164ad6fa1cca12141309d1bfcba67
-  data.tar.gz: b2b39df96276b3255dce1ab5903ec53ede199a0e741f51b36d243bc129708992a09035150c4f946dfd2da2a065dc43ec9267886d985fcc39a8fff496d95014d4
+  metadata.gz: 0bd5a3e7eb8d90cb9d18b801a55943abc9da582a33a0616ceadbf8e1a27fcff5ea5df795bae552b4e64d97c3c6e7cb298069285afddae4499c64af1b1cd0579e
+  data.tar.gz: 8aed36fcd88674f2cb3d91794ca224f75f909f79d805ba6d67cc613dd9bcf624ee7e2358a39ddcefaf5ff2cd24b27e9583e21ca1bd63e3eaa4b1289c04b87eac

data/README.md

@@ -1,7 +1,7 @@
 # Tam Select
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Gem Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://github.com/tamiru/tam_select)
+[![Gem Version](https://img.shields.io/badge/version-1.2.3-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.
 
@@ -29,20 +29,53 @@ bundle install
 bin/rails generate tam_select:install
 ```
 
-The generator installs:
+The generator installs the core module, Stimulus controller, Rails helpers, and remote-search concerns:
 
 ```text
 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
 ```
 
+When Simple Form is present, it also installs `app/inputs/tam_select_input.rb`. Simple Form is optional; applications without it receive a short skip message and continue with standard Rails form helpers.
+
 Commit these generated files with the Rails application. This makes customization straightforward and allows Tailwind CSS 4 to scan the component without resolving a Ruby gem directory at build time.
 
+### Rails 8 importmap
+
+The default Rails 8 importmap setup needs no manual JavaScript package installation. The generator adds this pin to `config/importmap.rb`:
+
+```ruby
+pin "tam_select", to: "tam_select/tam_select.js"
+```
+
+The generated Stimulus controller imports `TamSelect` from `"tam_select"`. Running the generator again updates an old pin when necessary and never adds a duplicate. Rails' normal `pin_all_from "app/javascript/controllers", under: "controllers"` line discovers the generated controller.
+
+### jsbundling-rails and esbuild
+
+The same generated controller works with esbuild when the bare `tam_select` import is aliased to the generated core file. Add the alias flag to the existing `build` script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets --alias:tam_select=./app/javascript/tam_select/tam_select.js"
+  }
+}
+```
+
+This uses the local file installed by the generator. For non-Rails bundler use, install the npm package from GitHub and import its published package name instead:
+
+```bash
+npm install github:tamiru/tam_select
+```
+
+```js
+import TamSelect from "tam-select"
+```
+
 Add the generated JavaScript to Tailwind's source detection in `app/assets/tailwind/application.css`:
 
 ```css
@@ -50,7 +83,7 @@ Add the generated JavaScript to Tailwind's source detection in `app/assets/tailw
 @source "../../javascript/tam_select/**/*.js";
 ```
 
-### Updating
+### Upgrading
 
 The Rails integration files are copied into your application, so updating the gem does not update them automatically. Commit local customizations first, then run:
 
@@ -67,13 +100,15 @@ bin/rails generate tam_select:install --force
 
 Review `git diff` afterward because `--force` overwrites application-specific customizations.
 
+Versions before this release generated a relative controller import. After upgrading, confirm the controller uses `import TamSelect from "tam_select"` and that the importmap pin or esbuild alias above is present.
+
 ## Features
 
 - Single and multiple selection
 - 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
+- Select2-style closed selection and open search states with clear active, selected, disabled, loading, empty, and error feedback
 - Keyboard navigation: arrows, Enter, Escape, Tab, and Backspace
 - Combobox/listbox ARIA semantics
 - Light and dark Tailwind themes
@@ -81,14 +116,6 @@ Review `git diff` afterward because `--force` overwrites application-specific cu
 - Public API and bubbling custom events
 - No jQuery, Tom Select, Select2, Preline, or Floating UI dependency
 
-## JavaScript installation
-
-For a non-Rails application, install directly from GitHub:
-
-```bash
-npm install github:tamiru/tam_select
-```
-
 ## Tailwind CSS 4
 
 Add the package source to `app/assets/tailwind/application.css` so Tailwind generates every class used by the JavaScript templates:
@@ -117,7 +144,7 @@ For Tailwind CSS 4 class-based theming, define the variant in the application st
 @custom-variant dark (&:where(.dark, .dark *));
 ```
 
-## Rails and Stimulus
+## Standard Rails forms and Stimulus
 
 The install generator copies the Stimulus controller into your application, where Stimulus normally discovers it automatically. If controllers are registered manually:
 
@@ -143,9 +170,28 @@ Use a normal Rails select:
 
 Stimulus destroys generated markup when Turbo removes the select and recreates it on reconnection.
 
+For multiple selection, Rails must receive an array field and the native select must include `multiple: true`:
+
+```erb
+<%= form.select :skill_ids,
+      options_from_collection_for_select(Skill.order(:name), :id, :name, form.object.skill_ids),
+      {},
+      multiple: true,
+      data: {
+        controller: "tam-select",
+        tam_select_options_value: {
+          searchable: true,
+          closeAfterSelect: false,
+          placeholder: "Add skills…"
+        }.to_json
+      } %>
+```
+
+The original `<select>` remains the source of truth. This preserves form names in nested forms, submitted values, prompts, `required`, validation metadata, and native `change` events.
+
 ## Simple Form
 
-The install generator creates `app/inputs/tam_select_input.rb`. Use `as: :tam_select` with any Simple Form collection input.
+When the `simple_form` gem is installed, the generator creates `app/inputs/tam_select_input.rb`. Use `as: :tam_select` with any Simple Form collection input. The input forwards Simple Form's prompt, selected values, multiple flag, error classes, ARIA attributes, and nested builder context to the native collection select.
 
 ### Local collection
 
@@ -270,6 +316,8 @@ 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.
 
+When `pagination.has_more` is true, scrolling near the bottom requests `next_page`. Earlier pages keep their order, duplicate values are collapsed, and a later response can update an existing item's label, metadata, image, or disabled state. A new query aborts the old request and never displays cached results from the previous query.
+
 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`:
@@ -319,10 +367,42 @@ curl -H "Accept: application/json" \
 
 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.
 
+## Creatable values
+
+Set `creatable: true` for tag-style input. The Create action is part of the same keyboard list as normal results, so ArrowUp and ArrowDown can highlight it and Enter creates it.
+
+```erb
+<%= form.select :category_ids,
+      options_from_collection_for_select(Category.order(:name), :id, :name),
+      {},
+      multiple: true,
+      data: {
+        controller: "tam-select",
+        tam_select_options_value: {
+          creatable: true,
+          closeAfterSelect: false,
+          placeholder: "Add categories…"
+        }.to_json
+      } %>
+```
+
+Values and labels are compared with normalized, case-insensitive, accent-insensitive text before creation, preventing duplicate entries such as `Café` and `cafe`. A successful creation dispatches `tam-select:create`.
+
+## Keyboard and accessibility behavior
+
+- ArrowDown and ArrowUp open the list, move through the rendered entries, and skip disabled options.
+- Enter selects the highlighted option or activates the highlighted Create action.
+- Escape closes the list and returns focus to the combobox; Tab closes without trapping focus.
+- Backspace removes the last tag from a multiple select when the search input is empty.
+- Searchable controls use an input combobox; non-searchable controls use a focusable button combobox.
+- Rails labels, descriptions, required state, disabled state, and invalid state are mirrored from the native select.
+
 ## Core JavaScript
 
+For a generated Rails/importmap installation, use the pinned module name:
+
 ```js
-import TamSelect from "tam-select"
+import TamSelect from "tam_select"
 
 const instance = new TamSelect(document.querySelector("#student_region_id"), {
   searchable: true,
@@ -332,11 +412,15 @@ const instance = new TamSelect(document.querySelector("#student_region_id"), {
 })
 
 instance.setValue("2")
+instance.open()
+instance.close()
 instance.clear()
 instance.refresh()
 instance.destroy()
 ```
 
+When consuming the npm package directly, import from `"tam-select"` instead.
+
 ## Main options
 
 | Option | Default | Purpose |
@@ -345,6 +429,8 @@ instance.destroy()
 | `creatable` | `false` | Allows typed values to become options |
 | `clearable` | `true` | Displays the clear control |
 | `closeAfterSelect` | Single only | Keeps multiple dropdowns open |
+| `placeholder` | Native prompt or `Select…` | Closed-control placeholder |
+| `searchPlaceholder` | `Search…` | Search-input placeholder |
 | `remoteUrl` | `null` | JSON search endpoint |
 | `queryParam` | `q` | Remote search parameter |
 | `pageParam` | `page` | Remote page parameter |
@@ -353,6 +439,7 @@ instance.destroy()
 | `valueField` | `value` | Remote item value key |
 | `labelField` | `label` | Remote item label key |
 | `imageField` | `image` | Remote item image URL key |
+| `matcher` | `null` | Optional `(item, query) => boolean` local matcher |
 | `classes` | `{}` | Overrides any Tailwind class group |
 
 ## Events
@@ -361,6 +448,8 @@ Listen on the original select. Every event bubbles:
 
 ```js
 select.addEventListener("tam-select:change", ({ detail }) => console.log(detail.value))
+select.addEventListener("tam-select:open", () => console.log("opened"))
+select.addEventListener("tam-select:close", () => console.log("closed"))
 select.addEventListener("tam-select:load", ({ detail }) => console.log(detail.items))
 select.addEventListener("tam-select:create", ({ detail }) => console.log(detail.item))
 select.addEventListener("tam-select:error", ({ detail }) => console.error(detail.error))
@@ -368,6 +457,8 @@ select.addEventListener("tam-select:error", ({ detail }) => console.error(detail
 
 Standard native `change` events are also dispatched for Rails and other controllers.
 
+The supported public methods are `open()`, `close()`, `setValue(value)`, `clear()`, `refresh()`, and `destroy()`. Read the current native-compatible selection through `instance.value`, and recover an existing instance with `TamSelect.getInstance(select)`.
+
 ## Development
 
 ```bash

data/Rakefile

@@ -2,7 +2,10 @@ require "bundler/gem_tasks"
 
 begin
   require "rake/testtask"
-  Rake::TestTask.new
+  Rake::TestTask.new do |test|
+    test.libs << "test"
+    test.pattern = "test/**/*_test.rb"
+  end
 rescue LoadError
-  # The gem has no Ruby runtime tests yet.
+  # Rake's test task is unavailable.
 end

data/lib/generators/tam_select/install_generator.rb

@@ -12,8 +12,30 @@ module TamSelect
         copy_file "lib/generators/tam_select/templates/tam_select_controller.js", "app/javascript/controllers/tam_select_controller.js"
       end
 
+      def configure_importmap
+        importmap = "config/importmap.rb"
+        unless File.exist?(destination_path(importmap))
+          say "Importmap was not detected. For jsbundling/esbuild, alias tam_select to app/javascript/tam_select/tam_select.js.", :yellow
+          return
+        end
+
+        pin = 'pin "tam_select", to: "tam_select/tam_select.js"'
+        contents = File.read(destination_path(importmap))
+        existing_pin = /^\s*pin\s+["']tam_select["'].*$/
+
+        if contents.match?(existing_pin)
+          gsub_file importmap, existing_pin, pin unless contents.match?(/^#{Regexp.escape(pin)}$/)
+        else
+          append_to_file importmap, "\n#{pin}\n"
+        end
+      end
+
       def copy_simple_form_input
-        copy_file "lib/generators/tam_select/templates/tam_select_input.rb", "app/inputs/tam_select_input.rb"
+        if simple_form_available?
+          copy_file "lib/generators/tam_select/templates/tam_select_input.rb", "app/inputs/tam_select_input.rb"
+        else
+          say "Simple Form is not installed; skipped app/inputs/tam_select_input.rb. Standard Rails form helpers remain available.", :yellow
+        end
       end
 
       def copy_controller_concern
@@ -35,6 +57,16 @@ module TamSelect
         say "If your setup uses explicit sources, add:"
         say '@source "../../javascript/tam_select/**/*.js";'
       end
+
+      private
+
+      def destination_path(relative_path)
+        File.join(destination_root, relative_path)
+      end
+
+      def simple_form_available?
+        Gem.loaded_specs.key?("simple_form")
+      end
     end
   end
 end

data/lib/generators/tam_select/templates/tam_select_controller.js

@@ -1,5 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
-import TamSelect from "../tam_select/tam_select"
+import TamSelect from "tam_select"
 
 export default class extends Controller {
   static values = {

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

@@ -1,7 +1,7 @@
 module TamSelectHelper
   def tam_select_tag(name, option_tags = nil, options: {}, html_options: {}, &block)
     data = (html_options[:data] ||= {})
-    data[:controller] = [data[:controller], "tam-select"].compact.join(" ")
+    data[:controller] = (data[:controller].to_s.split + ["tam-select"]).uniq.join(" ")
     data[:tam_select_options_value] = options.to_json
     select_tag(name, option_tags, html_options, &block)
   end

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

@@ -4,7 +4,7 @@ class TamSelectInput < SimpleForm::Inputs::CollectionSelectInput
     label_method, value_method = detect_collection_methods
     tam_options = attributes.delete(:tam_options) || {}
     data = attributes[:data] ||= {}
-    data[:controller] = [data[:controller], "tam-select"].compact.join(" ")
+    data[:controller] = (data[:controller].to_s.split + ["tam-select"]).uniq.join(" ")
     data[:tam_select_options_value] = defaults.merge(tam_options).to_json
 
     @builder.collection_select(

data/lib/tam_select/version.rb

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

data/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "tam-select",
+  "version": "1.2.3",
+  "description": "Accessible, searchable select component for Ruby on Rails, Simple Form, Stimulus, Turbo, and Tailwind CSS",
+  "homepage": "https://github.com/tamiru/tam_select",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tamiru/tam_select.git"
+  },
+  "type": "module",
+  "main": "./src/tam-select.js",
+  "exports": {
+    ".": "./src/tam-select.js",
+    "./rails-controller": "./rails/app/javascript/controllers/tam_select_controller.js"
+  },
+  "files": [
+    "src",
+    "rails",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check": "node --check src/tam-select.js && node --check rails/app/javascript/controllers/tam_select_controller.js"
+  },
+  "keywords": [
+    "select",
+    "tailwindcss",
+    "stimulus",
+    "turbo",
+    "rails",
+    "combobox"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hotwired/stimulus": ">=3.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@hotwired/stimulus": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hotwired/stimulus": "^3.2.2",
+    "esbuild": "^0.28.1",
+    "jsdom": "^29.1.1"
+  }
+}

data/rails/app/controllers/concerns/tam_select_paginatable.rb

@@ -0,0 +1,32 @@
+module TamSelectPaginatable
+  extend ActiveSupport::Concern
+
+  private
+
+  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
+
+    {
+      items: records.first(per_page).map do |record|
+        {
+          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,
+        next_page: has_more ? page + 1 : nil,
+        has_more: has_more
+      }
+    }
+  end
+
+  def tam_select_record_value(record, resolver)
+    resolver.respond_to?(:call) ? resolver.call(record) : record.public_send(resolver)
+  end
+end

data/rails/app/helpers/tam_select_helper.rb

@@ -0,0 +1,17 @@
+module TamSelectHelper
+  def tam_select_tag(name, option_tags = nil, options: {}, html_options: {}, &block)
+    data = (html_options[:data] ||= {})
+    data[:controller] = (data[:controller].to_s.split + ["tam-select"]).uniq.join(" ")
+    data[:tam_select_options_value] = options.to_json
+    select_tag(name, option_tags, html_options, &block)
+  end
+
+  def tam_select_options(**overrides)
+    {
+      searchable: true,
+      clearable: true,
+      creatable: false,
+      placeholder: "Select…"
+    }.merge(overrides)
+  end
+end

data/rails/app/inputs/tam_select_input.rb

@@ -0,0 +1,30 @@
+class TamSelectInput < SimpleForm::Inputs::CollectionSelectInput
+  def input(wrapper_options = nil)
+    attributes = merge_wrapper_options(input_html_options, wrapper_options)
+    label_method, value_method = detect_collection_methods
+    tam_options = attributes.delete(:tam_options) || {}
+    data = attributes[:data] ||= {}
+    data[:controller] = (data[:controller].to_s.split + ["tam-select"]).uniq.join(" ")
+    data[:tam_select_options_value] = defaults.merge(tam_options).to_json
+
+    @builder.collection_select(
+      attribute_name,
+      collection,
+      value_method,
+      label_method,
+      input_options,
+      attributes
+    )
+  end
+
+  private
+
+  def defaults
+    {
+      searchable: options.fetch(:searchable, true),
+      creatable: options.fetch(:creatable, false),
+      clearable: options.fetch(:clearable, true),
+      placeholder: options[:placeholder] || options[:prompt] || "Select…"
+    }
+  end
+end

data/rails/app/javascript/controllers/tam_select_controller.js

@@ -0,0 +1,31 @@
+import { Controller } from "@hotwired/stimulus"
+import TamSelect from "tam-select"
+
+export default class extends Controller {
+  static values = {
+    options: { type: Object, default: {} }
+  }
+
+  connect() {
+    this.instance = TamSelect.getInstance(this.element) || new TamSelect(this.element, this.optionsValue)
+  }
+
+  disconnect() {
+    this.instance?.destroy()
+    this.instance = null
+  }
+
+  optionsValueChanged() {
+    if (!this.instance) return
+    this.instance.destroy()
+    this.instance = new TamSelect(this.element, this.optionsValue)
+  }
+
+  refresh() {
+    this.instance?.refresh()
+  }
+
+  clear() {
+    this.instance?.clear()
+  }
+}