tam_select 0.1.0 → 1.0.0

checksums.yaml

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

data/README.md

@@ -1,6 +1,7 @@
-# Tam Select
+the # 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)
 
 **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.
 
@@ -35,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/tam_select_remote_controller.rb
 app/helpers/tam_select_helper.rb
 ```
 
@@ -47,6 +49,23 @@ Add the generated JavaScript to Tailwind's source detection in `app/assets/tailw
 @source "../../javascript/tam_select/**/*.js";
 ```
 
+### Updating
+
+The Rails integration files are copied into your application, so updating the gem does not update them automatically. Commit local customizations first, then run:
+
+```bash
+bundle update tam_select
+bin/rails generate tam_select:install
+```
+
+Rails prompts before replacing changed files. To replace every generated file without prompting, use:
+
+```bash
+bin/rails generate tam_select:install --force
+```
+
+Review `git diff` afterward because `--force` overwrites application-specific customizations.
+
 ## Features
 
 - Single and multiple selection
@@ -123,7 +142,7 @@ The install generator creates `app/inputs/tam_select_input.rb`. Use it like any
       prompt: "Select region",
       input_html: {
         tam_options: {
-          remoteUrl: regions_path,
+          remoteUrl: region_options_path(format: :json),
           minQueryLength: 1
         }
       } %>
@@ -153,6 +172,63 @@ 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
+
+The installer generates `TamSelectRemoteController`. Create a small subclass for each allowed remote source:
+
+```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
+```
+
+Expose the JSON endpoint and pass it to the input:
+
+```ruby
+# config/routes.rb
+get "region_options", to: "region_options#index", defaults: { format: :json }
+```
+
+```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
+        }
+      } %>
+```
+
+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
+Accept: application/json
+```
+
+Test an endpoint independently with:
+
+```bash
+curl -H "Accept: application/json" \
+  "http://localhost:3000/region_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.
+
 ## Core JavaScript
 
 ```js

data/lib/generators/tam_select/install_generator.rb

@@ -20,6 +20,10 @@ module TamSelect
         copy_file "lib/generators/tam_select/templates/tam_select_paginatable.rb", "app/controllers/concerns/tam_select_paginatable.rb"
       end
 
+      def copy_remote_controller
+        copy_file "lib/generators/tam_select/templates/tam_select_remote_controller.rb", "app/controllers/tam_select_remote_controller.rb"
+      end
+
       def copy_helper
         copy_file "lib/generators/tam_select/templates/tam_select_helper.rb", "app/helpers/tam_select_helper.rb"
       end

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

@@ -0,0 +1,44 @@
+class TamSelectRemoteController < ApplicationController
+  include TamSelectPaginatable
+
+  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
+end

data/lib/tam_select/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tam_select
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.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_controller.rb
 - lib/tam_select.rb
 - lib/tam_select/engine.rb
 - lib/tam_select/version.rb