tam_select 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cf23ba08878f41cb17355d5ce629542fc3bab8e61756960403223d2abde898c
+  data.tar.gz: 9257189f40b467cfdf80106c5c2c30ce3430f10395c8bb122b7c6ae09ee6a3c6
+SHA512:
+  metadata.gz: 8c2ac3a785840329c378213fa5fdf9499756c44adc64788c6170ac5fc8f8a2de2c18eb7bd8949dbf6cd9792894ef7b5ca75e5b1135066d31052de62598e67510
+  data.tar.gz: 326c67bbe68fc22799b6a24993bd378ebb06650772d829ffdba775fe2f119997df09a66bb63c99b1661cc85e21b3e29a3f3662b2b71fa57789fb997fc126e368

data/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 tam-select contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

data/README.md

@@ -0,0 +1,215 @@
+# Tam Select
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**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.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- Rails 8
+- Stimulus 3.2 or newer
+- Tailwind CSS 4
+- Simple Form when using the `TamSelectInput` integration
+
+## Rails installation
+
+Add the gem directly from GitHub:
+
+```ruby
+# Gemfile
+gem "tam_select", github: "tamiru/tam_select"
+```
+
+Install the dependency and generate the Rails integration files:
+
+```bash
+bundle install
+bin/rails generate tam_select:install
+```
+
+The generator installs:
+
+```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/helpers/tam_select_helper.rb
+```
+
+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.
+
+Add the generated JavaScript to Tailwind's source detection in `app/assets/tailwind/application.css`:
+
+```css
+@import "tailwindcss";
+@source "../../javascript/tam_select/**/*.js";
+```
+
+## Features
+
+- Single and multiple selection
+- Local search and user-created tags
+- Remote JSON search with debouncing and incremental pagination
+- Loading, empty, and error states
+- Keyboard navigation: arrows, Enter, Escape, Tab, and Backspace
+- Combobox/listbox ARIA semantics
+- Light and dark Tailwind themes
+- Rails 8, Turbo, Turbo Frames, Stimulus, and Simple Form integration
+- 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:
+
+```css
+@import "tailwindcss";
+@source "../../../node_modules/tam-select/src/**/*.js";
+@source "../../../node_modules/tam-select/rails/**/*.js";
+```
+
+When the Rails generator is used, scan the generated component source:
+
+```css
+@source "../../javascript/tam_select/**/*.js";
+```
+
+## Rails and Stimulus
+
+The install generator copies the Stimulus controller into your application, where Stimulus normally discovers it automatically. If controllers are registered manually:
+
+```js
+import TamSelectController from "./tam_select_controller"
+application.register("tam-select", TamSelectController)
+```
+
+Use a normal Rails select:
+
+```erb
+<%= form.select :region_id,
+      options_from_collection_for_select(Region.order(:name), :id, :name, form.object.region_id),
+      { prompt: "Select region" },
+      data: {
+        controller: "tam-select",
+        tam_select_options_value: {
+          searchable: true,
+          placeholder: "Select region…"
+        }.to_json
+      } %>
+```
+
+Stimulus destroys generated markup when Turbo removes the select and recreates it on reconnection.
+
+## Simple Form
+
+The install generator creates `app/inputs/tam_select_input.rb`. Use it like any other Simple Form input:
+
+```erb
+<%= form.input :region_id,
+      as: :tam_select,
+      collection: Region.order(:name),
+      label_method: :name,
+      value_method: :id,
+      prompt: "Select region",
+      input_html: {
+        tam_options: {
+          remoteUrl: regions_path,
+          minQueryLength: 1
+        }
+      } %>
+```
+
+For a many-to-many field, add `multiple: true` to `input_html`.
+
+## Remote API contract
+
+`tam-select` sends `q` and `page` query parameters and expects:
+
+```json
+{
+  "items": [
+    { "value": "1", "label": "Addis Ababa" },
+    { "value": "2", "label": "Afar" }
+  ],
+  "pagination": {
+    "page": 1,
+    "next_page": 2,
+    "has_more": true
+  }
+}
+```
+
+The generator installs `TamSelectPaginatable` as a Rails response helper. A complete Region controller is available in [`examples/regions_controller.rb`](examples/regions_controller.rb).
+
+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.
+
+## Core JavaScript
+
+```js
+import TamSelect from "tam-select"
+
+const instance = new TamSelect(document.querySelector("#student_region_id"), {
+  searchable: true,
+  creatable: false,
+  remoteUrl: "/regions",
+  minQueryLength: 1
+})
+
+instance.setValue("2")
+instance.clear()
+instance.refresh()
+instance.destroy()
+```
+
+## Main options
+
+| Option | Default | Purpose |
+|---|---:|---|
+| `searchable` | `true` | Enables text filtering |
+| `creatable` | `false` | Allows typed values to become options |
+| `clearable` | `true` | Displays the clear control |
+| `closeAfterSelect` | Single only | Keeps multiple dropdowns open |
+| `remoteUrl` | `null` | JSON search endpoint |
+| `queryParam` | `q` | Remote search parameter |
+| `pageParam` | `page` | Remote page parameter |
+| `debounce` | `250` | Remote request delay in milliseconds |
+| `minQueryLength` | `0` | Characters required before requesting |
+| `valueField` | `value` | Remote item value key |
+| `labelField` | `label` | Remote item label key |
+| `classes` | `{}` | Overrides any Tailwind class group |
+
+## Events
+
+Listen on the original select. Every event bubbles:
+
+```js
+select.addEventListener("tam-select:change", ({ detail }) => console.log(detail.value))
+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))
+```
+
+Standard native `change` events are also dispatched for Rails and other controllers.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+npm test
+npm run check
+```
+
+## License
+
+Tam Select is available under the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+begin
+  require "rake/testtask"
+  Rake::TestTask.new
+rescue LoadError
+  # The gem has no Ruby runtime tests yet.
+end

data/examples/form.html.erb

@@ -0,0 +1,30 @@
+<%= simple_form_for @student do |form| %>
+  <%= form.input :region_id,
+        as: :tam_select,
+        collection: Region.order(:name),
+        label_method: :name,
+        value_method: :id,
+        prompt: "Select region",
+        input_html: {
+          tam_options: {
+            remoteUrl: regions_path,
+            minQueryLength: 1,
+            placeholder: "Select region…",
+            searchPlaceholder: "Search regions…"
+          }
+        } %>
+
+  <%= form.input :skill_ids,
+        as: :tam_select,
+        collection: Skill.order(:name),
+        label_method: :name,
+        value_method: :id,
+        input_html: {
+          multiple: true,
+          tam_options: {
+            creatable: true,
+            closeAfterSelect: false,
+            placeholder: "Add skills…"
+          }
+        } %>
+<% end %>

data/examples/regions_controller.rb

@@ -0,0 +1,10 @@
+class RegionsController < ApplicationController
+  include TamSelectPaginatable
+
+  def index
+    query = params[:q].to_s.strip
+    regions = Region.order(:name)
+    regions = regions.where("name LIKE ?", "%#{Region.sanitize_sql_like(query)}%") if query.present?
+    render json: tam_select_payload(regions, label: :name)
+  end
+end

data/lib/generators/tam_select/install_generator.rb

@@ -0,0 +1,35 @@
+require "rails/generators"
+
+module TamSelect
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../..", __dir__)
+
+      desc "Install tam_select JavaScript, Stimulus, Simple Form and Rails integration"
+
+      def copy_javascript
+        copy_file "src/tam-select.js", "app/javascript/tam_select/tam_select.js"
+        copy_file "lib/generators/tam_select/templates/tam_select_controller.js", "app/javascript/controllers/tam_select_controller.js"
+      end
+
+      def copy_simple_form_input
+        copy_file "lib/generators/tam_select/templates/tam_select_input.rb", "app/inputs/tam_select_input.rb"
+      end
+
+      def copy_controller_concern
+        copy_file "lib/generators/tam_select/templates/tam_select_paginatable.rb", "app/controllers/concerns/tam_select_paginatable.rb"
+      end
+
+      def copy_helper
+        copy_file "lib/generators/tam_select/templates/tam_select_helper.rb", "app/helpers/tam_select_helper.rb"
+      end
+
+      def show_tailwind_instruction
+        say "\ntam_select installed.", :green
+        say "Tailwind CSS 4 scans app/javascript automatically in most Rails setups."
+        say "If your setup uses explicit sources, add:"
+        say '@source "../../javascript/tam_select/**/*.js";'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+import { Controller } from "@hotwired/stimulus"
+import TamSelect from "../tam_select/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() }
+}

data/lib/generators/tam_select/templates/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], "tam-select"].compact.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/lib/generators/tam_select/templates/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], "tam-select"].compact.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/lib/generators/tam_select/templates/tam_select_paginatable.rb

@@ -0,0 +1,25 @@
+module TamSelectPaginatable
+  extend ActiveSupport::Concern
+
+  private
+
+  def tam_select_payload(scope, label:, value: :id, 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: record.public_send(value).to_s,
+          label: label.respond_to?(:call) ? label.call(record) : record.public_send(label).to_s
+        }
+      end,
+      pagination: {
+        page: page,
+        next_page: has_more ? page + 1 : nil,
+        has_more: has_more
+      }
+    }
+  end
+end

data/lib/tam_select/engine.rb

@@ -0,0 +1,6 @@
+require "rails/engine"
+
+module TamSelect
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/tam_select/version.rb

@@ -0,0 +1,3 @@
+module TamSelect
+  VERSION = "0.1.0"
+end

data/lib/tam_select.rb

@@ -0,0 +1,6 @@
+require "tam_select/version"
+require "tam_select/engine"
+
+module TamSelect
+  class Error < StandardError; end
+end

data/src/tam-select.js

@@ -0,0 +1,482 @@
+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",
+  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",
+  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",
+  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",
+  error: "px-3 py-3 text-sm text-red-600 dark:text-red-400"
+}
+
+const ICONS = {
+  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>'
+}
+
+const uid = () => `tam-select-${Math.random().toString(36).slice(2, 10)}`
+const normalize = value => String(value ?? "").normalize("NFKD").toLocaleLowerCase()
+const toggleClasses = (element, classNames, force) => {
+  String(classNames).split(/\s+/).filter(Boolean).forEach(className => element.classList.toggle(className, force))
+}
+
+export class TamSelect {
+  static instances = new WeakMap()
+
+  static getInstance(element) {
+    return this.instances.get(element) || null
+  }
+
+  constructor(select, options = {}) {
+    if (!(select instanceof HTMLSelectElement)) throw new TypeError("TamSelect requires a <select> element")
+    if (TamSelect.instances.has(select)) return TamSelect.instances.get(select)
+
+    this.select = select
+    this.options = {
+      searchable: true,
+      creatable: false,
+      clearable: true,
+      closeAfterSelect: !select.multiple,
+      placeholder: select.dataset.placeholder || select.querySelector('option[value=""]')?.textContent || "Select…",
+      searchPlaceholder: "Search…",
+      noResultsText: "No results found",
+      createText: query => `Create “${query}”`,
+      loadingText: "Loading…",
+      loadMoreText: "Load more",
+      remoteUrl: null,
+      queryParam: "q",
+      pageParam: "page",
+      debounce: 250,
+      minQueryLength: 0,
+      valueField: "value",
+      labelField: "label",
+      itemsPath: "items",
+      paginationPath: "pagination",
+      classes: {},
+      headers: {},
+      ...options
+    }
+    this.classes = { ...DEFAULT_CLASSES, ...this.options.classes }
+    this.multiple = select.multiple
+    this.items = []
+    this.filtered = []
+    this.activeIndex = -1
+    this.opened = false
+    this.loading = false
+    this.error = null
+    this.query = ""
+    this.page = 1
+    this.hasMore = false
+    this.abortController = null
+    this.originalTabIndex = select.getAttribute("tabindex")
+    this.build()
+    this.bind()
+    this.readNativeOptions()
+    this.renderSelection()
+    TamSelect.instances.set(select, this)
+  }
+
+  build() {
+    this.id = this.select.id || uid()
+    if (!this.select.id) this.select.id = this.id
+    this.listboxId = `${this.id}-listbox`
+    this.select.classList.add("sr-only")
+    this.select.tabIndex = -1
+
+    this.wrapper = document.createElement("div")
+    this.wrapper.className = this.classes.wrapper
+    this.wrapper.dataset.tamSelectRoot = ""
+    this.control = document.createElement("div")
+    this.control.className = this.classes.control
+    this.control.setAttribute("role", "combobox")
+    this.control.setAttribute("aria-haspopup", "listbox")
+    this.control.setAttribute("aria-expanded", "false")
+    this.control.setAttribute("aria-controls", this.listboxId)
+    this.control.tabIndex = this.select.disabled ? -1 : 0
+
+    this.values = document.createElement("div")
+    this.values.className = "contents"
+    this.input = document.createElement("input")
+    this.input.type = "text"
+    this.input.className = this.classes.input
+    this.input.placeholder = this.options.searchable ? this.options.searchPlaceholder : ""
+    this.input.autocomplete = "off"
+    this.input.spellcheck = false
+    this.input.setAttribute("aria-autocomplete", "list")
+    this.input.setAttribute("aria-controls", this.listboxId)
+    if (!this.options.searchable) this.input.readOnly = true
+
+    this.clearButton = document.createElement("button")
+    this.clearButton.type = "button"
+    this.clearButton.className = this.classes.clear
+    this.clearButton.setAttribute("aria-label", "Clear selection")
+    this.clearButton.innerHTML = ICONS.close
+
+    this.chevron = document.createElement("span")
+    this.chevron.className = this.classes.chevron
+    this.chevron.innerHTML = ICONS.chevron
+    this.dropdown = document.createElement("div")
+    this.dropdown.id = this.listboxId
+    this.dropdown.className = `${this.classes.dropdown} hidden`
+    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.wrapper.append(this.control, this.dropdown)
+    this.select.after(this.wrapper)
+    this.applyDisabled()
+  }
+
+  bind() {
+    this.onControlClick = event => {
+      if (this.select.disabled || event.target.closest("button")) return
+      this.open()
+      this.input.focus()
+    }
+    this.onInput = () => {
+      this.query = this.input.value
+      this.page = 1
+      this.open()
+      if (this.options.remoteUrl) this.scheduleRemote()
+      else this.filterLocal()
+    }
+    this.onKeydown = event => this.handleKeydown(event)
+    this.onClear = event => { event.stopPropagation(); this.clear() }
+    this.onOutside = event => { if (!this.wrapper.contains(event.target)) this.close() }
+    this.onNativeChange = () => { this.readNativeOptions(); this.renderSelection(); this.renderDropdown() }
+    this.onScroll = () => {
+      if (!this.options.remoteUrl || !this.hasMore || this.loading) return
+      if (this.dropdown.scrollTop + this.dropdown.clientHeight >= this.dropdown.scrollHeight - 32) this.loadRemote(this.page + 1, true)
+    }
+    this.control.addEventListener("click", this.onControlClick)
+    this.input.addEventListener("input", this.onInput)
+    this.control.addEventListener("keydown", this.onKeydown)
+    this.clearButton.addEventListener("click", this.onClear)
+    this.dropdown.addEventListener("scroll", this.onScroll)
+    this.select.addEventListener("change", this.onNativeChange)
+    document.addEventListener("pointerdown", this.onOutside)
+  }
+
+  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 }))
+    this.filterLocal(false)
+  }
+
+  selectedItems() { return this.items.filter(item => item.option?.selected || item.selected) }
+
+  filterLocal(render = true) {
+    const needle = normalize(this.query)
+    this.filtered = this.items.filter(item => !needle || normalize(item.label).includes(needle))
+    this.activeIndex = this.filtered.findIndex(item => !item.disabled)
+    if (render) this.renderDropdown()
+  }
+
+  renderSelection() {
+    const selected = this.selectedItems()
+    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)
+    }
+    const hasValue = selected.length > 0
+    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)
+  }
+
+  makeTag(item) {
+    const tag = document.createElement("span")
+    tag.className = this.classes.tag
+    const label = document.createElement("span")
+    label.className = "max-w-48 truncate"
+    label.textContent = item.label
+    const remove = document.createElement("button")
+    remove.type = "button"
+    remove.className = this.classes.tagRemove
+    remove.setAttribute("aria-label", `Remove ${item.label}`)
+    remove.innerHTML = ICONS.close
+    remove.addEventListener("click", event => { event.stopPropagation(); this.deselect(item.value) })
+    tag.append(label, remove)
+    return tag
+  }
+
+  renderDropdown() {
+    if (!this.opened) return
+    this.dropdown.replaceChildren()
+    if (this.error) {
+      const error = document.createElement("div")
+      error.className = this.classes.error
+      error.setAttribute("role", "alert")
+      error.textContent = this.error
+      this.dropdown.append(error)
+      return
+    }
+    if (this.loading && this.page === 1) return this.renderMessage(this.options.loadingText, true)
+
+    const visible = this.multiple ? this.filtered : this.filtered.filter(item => !item.selected)
+    visible.forEach((item, index) => this.dropdown.append(this.makeOption(item, index)))
+    if (this.options.creatable && this.query.trim() && !this.items.some(item => normalize(item.label) === normalize(this.query))) {
+      this.dropdown.append(this.makeCreateOption())
+    }
+    if (!this.dropdown.children.length) this.renderMessage(this.options.noResultsText)
+    if (this.loading && this.page > 1) this.renderMessage(this.options.loadingText, true)
+    else if (this.hasMore) this.renderMessage(this.options.loadMoreText)
+  }
+
+  makeOption(item, index) {
+    const option = document.createElement("div")
+    option.id = `${this.listboxId}-option-${index}`
+    option.dataset.value = item.value
+    option.className = [this.classes.option, index === this.activeIndex && this.classes.optionActive, item.selected && this.classes.optionSelected, item.disabled && this.classes.optionDisabled].filter(Boolean).join(" ")
+    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)
+    if (item.selected) {
+      const check = document.createElement("span")
+      check.innerHTML = ICONS.check
+      option.append(check)
+    }
+    option.addEventListener("pointermove", () => { this.activeIndex = index; this.updateActiveOption() })
+    option.addEventListener("click", () => { if (!item.disabled) this.toggleItem(item) })
+    return option
+  }
+
+  makeCreateOption() {
+    const option = document.createElement("div")
+    option.className = this.classes.option
+    option.setAttribute("role", "option")
+    option.textContent = typeof this.options.createText === "function" ? this.options.createText(this.query.trim()) : this.options.createText
+    option.addEventListener("click", () => this.createItem(this.query.trim()))
+    return option
+  }
+
+  renderMessage(text, spinner = false) {
+    const message = document.createElement("div")
+    message.className = this.classes.message
+    if (spinner) {
+      const row = document.createElement("span")
+      row.className = "inline-flex items-center gap-2"
+      const icon = document.createElement("span")
+      icon.className = this.classes.spinner
+      row.append(icon, document.createTextNode(text))
+      message.append(row)
+    } else message.textContent = text
+    this.dropdown.append(message)
+  }
+
+  handleKeydown(event) {
+    if (this.select.disabled) return
+    if (["ArrowDown", "ArrowUp"].includes(event.key)) {
+      event.preventDefault()
+      this.open()
+      const direction = event.key === "ArrowDown" ? 1 : -1
+      this.moveActive(direction)
+    } else if (event.key === "Enter") {
+      if (!this.opened) return this.open()
+      event.preventDefault()
+      const item = this.filtered[this.activeIndex]
+      if (item && !item.disabled) this.toggleItem(item)
+      else if (this.options.creatable && this.query.trim()) this.createItem(this.query.trim())
+    } else if (event.key === "Escape") {
+      event.preventDefault(); this.close(); this.control.focus()
+    } else if (event.key === "Backspace" && this.multiple && !this.input.value) {
+      const last = this.selectedItems().at(-1)
+      if (last) this.deselect(last.value)
+    } else if (event.key === "Tab") this.close()
+  }
+
+  moveActive(direction) {
+    if (!this.filtered.length) return
+    let next = this.activeIndex
+    for (let count = 0; count < this.filtered.length; count += 1) {
+      next = (next + direction + this.filtered.length) % this.filtered.length
+      if (!this.filtered[next].disabled) break
+    }
+    this.activeIndex = next
+    this.updateActiveOption()
+  }
+
+  updateActiveOption() {
+    this.dropdown.querySelectorAll('[role="option"]').forEach((option, index) => toggleClasses(option, this.classes.optionActive, index === this.activeIndex))
+    const active = this.dropdown.querySelector(`#${CSS.escape(`${this.listboxId}-option-${this.activeIndex}`)}`)
+    if (active) { this.input.setAttribute("aria-activedescendant", active.id); active.scrollIntoView({ block: "nearest" }) }
+  }
+
+  toggleItem(item) {
+    if (this.multiple && item.selected) this.deselect(item.value)
+    else this.selectValue(item.value)
+  }
+
+  selectValue(value) {
+    const item = this.ensureNativeOption(value)
+    if (!this.multiple) Array.from(this.select.options).forEach(option => { option.selected = false })
+    item.option.selected = true
+    item.selected = true
+    this.commit()
+    if (this.options.closeAfterSelect) this.close()
+    else { this.input.value = ""; this.query = ""; this.filterLocal() }
+  }
+
+  deselect(value) {
+    const item = this.items.find(entry => String(entry.value) === String(value))
+    if (!item) return
+    item.selected = false
+    if (item.option) item.option.selected = false
+    this.commit()
+  }
+
+  clear() {
+    Array.from(this.select.options).forEach(option => { option.selected = false })
+    this.items.forEach(item => { item.selected = false })
+    this.commit()
+  }
+
+  createItem(label) {
+    const value = typeof this.options.createValue === "function" ? this.options.createValue(label) : label
+    const item = this.addItem({ value, label, selected: false, created: true })
+    this.selectValue(item.value)
+    this.emit("tam-select:create", { item })
+  }
+
+  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
+    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 = ""
+    this.select.add(option)
+    const item = { ...raw, value, label, option, selected: option.selected, disabled: Boolean(raw.disabled) }
+    option.disabled = item.disabled
+    this.items.push(item)
+    this.filterLocal(false)
+    return item
+  }
+
+  ensureNativeOption(value) {
+    return this.items.find(item => String(item.value) === String(value)) || this.addItem({ value, label: value })
+  }
+
+  commit() {
+    this.renderSelection()
+    this.renderDropdown()
+    this.select.dispatchEvent(new Event("change", { bubbles: true }))
+    this.emit("tam-select:change", { value: this.value, items: this.selectedItems() })
+  }
+
+  get value() { return this.multiple ? this.selectedItems().map(item => item.value) : this.selectedItems()[0]?.value ?? "" }
+
+  setValue(value) {
+    const values = new Set((Array.isArray(value) ? value : [value]).map(String))
+    this.items.forEach(item => { item.selected = values.has(String(item.value)); if (item.option) item.option.selected = item.selected })
+    this.commit()
+  }
+
+  open() {
+    if (this.opened || this.select.disabled) return
+    this.opened = true
+    this.dropdown.classList.remove("hidden")
+    this.control.setAttribute("aria-expanded", "true")
+    this.chevron.classList.add(...this.classes.chevronOpen.split(" "))
+    this.renderSelection()
+    if (this.options.remoteUrl && !this.filtered.length) this.loadRemote(1)
+    else this.renderDropdown()
+    this.emit("tam-select:open")
+  }
+
+  close() {
+    if (!this.opened) return
+    this.opened = false
+    this.dropdown.classList.add("hidden")
+    this.control.setAttribute("aria-expanded", "false")
+    this.input.removeAttribute("aria-activedescendant")
+    this.chevron.classList.remove(...this.classes.chevronOpen.split(" "))
+    this.input.value = ""
+    this.query = ""
+    this.filterLocal(false)
+    this.renderSelection()
+    this.emit("tam-select:close")
+  }
+
+  scheduleRemote() {
+    clearTimeout(this.remoteTimer)
+    if (this.query.length < this.options.minQueryLength) { this.filtered = []; return this.renderDropdown() }
+    this.remoteTimer = setTimeout(() => this.loadRemote(1), this.options.debounce)
+  }
+
+  async loadRemote(page = 1, append = false) {
+    if (!append) this.abortController?.abort()
+    this.abortController = new AbortController()
+    this.loading = true
+    this.error = null
+    this.page = page
+    this.renderDropdown()
+    try {
+      const url = new URL(this.options.remoteUrl, window.location.origin)
+      url.searchParams.set(this.options.queryParam, this.query)
+      url.searchParams.set(this.options.pageParam, page)
+      const response = await fetch(url, { headers: { Accept: "application/json", ...this.options.headers }, signal: this.abortController.signal })
+      if (!response.ok) throw new Error(`Request failed (${response.status})`)
+      const data = await response.json()
+      const rawItems = this.getPath(data, this.options.itemsPath) || []
+      const remoteItems = rawItems.map(raw => this.addItem({ ...raw, value: String(raw[this.options.valueField]), label: String(raw[this.options.labelField]) }))
+      const values = new Set(remoteItems.map(item => item.value))
+      this.filtered = append ? [...this.filtered, ...remoteItems.filter(item => !this.filtered.some(old => old.value === item.value))] : this.items.filter(item => values.has(String(item.value)) || item.selected)
+      const pagination = this.getPath(data, this.options.paginationPath) || {}
+      this.hasMore = Boolean(pagination.next_page || pagination.has_more || (pagination.page && pagination.total_pages && pagination.page < pagination.total_pages))
+      this.activeIndex = this.filtered.findIndex(item => !item.disabled)
+      this.emit("tam-select:load", { items: remoteItems, pagination })
+    } catch (error) {
+      if (error.name !== "AbortError") { this.error = error.message || "Unable to load options"; this.emit("tam-select:error", { error }) }
+    } finally {
+      this.loading = false
+      this.renderDropdown()
+    }
+  }
+
+  getPath(object, path) { return String(path).split(".").reduce((value, key) => value?.[key], object) }
+
+  applyDisabled() {
+    toggleClasses(this.control, this.classes.controlDisabled, this.select.disabled)
+    this.control.tabIndex = this.select.disabled ? -1 : 0
+    this.input.disabled = this.select.disabled
+  }
+
+  refresh() { this.readNativeOptions(); this.applyDisabled(); this.renderSelection(); this.renderDropdown() }
+
+  emit(name, detail = {}) { this.select.dispatchEvent(new CustomEvent(name, { bubbles: true, detail: { tamSelect: this, ...detail } })) }
+
+  destroy() {
+    clearTimeout(this.remoteTimer)
+    this.abortController?.abort()
+    document.removeEventListener("pointerdown", this.onOutside)
+    this.select.removeEventListener("change", this.onNativeChange)
+    this.wrapper.remove()
+    this.select.classList.remove("sr-only")
+    if (this.originalTabIndex === null) this.select.removeAttribute("tabindex")
+    else this.select.setAttribute("tabindex", this.originalTabIndex)
+    TamSelect.instances.delete(this.select)
+  }
+}
+
+export default TamSelect

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: tam_select
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tamiru Hailu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Tam Select provides searchable, multi-select, remote-data, and user-created
+  option support for Ruby on Rails applications using Simple Form, Stimulus, Turbo,
+  and Tailwind CSS.
+email:
+- tamiruhailu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- examples/form.html.erb
+- examples/regions_controller.rb
+- lib/generators/tam_select/install_generator.rb
+- lib/generators/tam_select/templates/tam_select_controller.js
+- 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/tam_select.rb
+- lib/tam_select/engine.rb
+- lib/tam_select/version.rb
+- src/tam-select.js
+homepage: https://github.com/tamiru/tam_select
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tamiru/tam_select
+  changelog_uri: https://github.com/tamiru/tam_select/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: An accessible select component for Ruby on Rails
+test_files: []