basho 0.2.2 → 0.3.0

data/README.md

@@ -2,7 +2,7 @@
 
 # Basho
 
-A Ruby gem for working with Japanese address data — prefectures, cities, postal codes, and regions — in a unified interface.
+A Ruby gem for working with Japanese address data -- prefectures, cities, postal codes, and regions -- in a unified interface.
 
 ## Why Basho
 
@@ -15,10 +15,13 @@ Dealing with Japanese addresses is tedious.
 
 Basho solves all of these.
 
-- **No DB migrations** — All data is bundled as JSON. Just `gem install` and go
-- **ActiveRecord integration** — `include Basho` + a one-line macro for automatic postal code to address resolution on save
-- **Hotwire-ready** — Built-in Rails Engine with postal code auto-fill and cascade select
-- **Lightweight** — Immutable models via `Data.define`, lazy loading, zero external dependencies
+## Features
+
+- **No DB migrations** -- All data is bundled as JSON. Just `gem install` and go
+- **Framework-agnostic** -- Works with plain Ruby, Sinatra, Rails API-only, or any Ruby app
+- **ActiveRecord integration** -- `include Basho` + a one-line macro for automatic postal code to address resolution on save
+- **Hotwire-ready** -- Built-in Rails Engine with postal code auto-fill via Turbo Frame + Stimulus
+- **Lightweight** -- Immutable models via `Data.define`, lazy loading, zero external dependencies
 
 ## Supported Versions
 
@@ -40,7 +43,7 @@ bundle install
 ### Look up an address from a postal code
 
 ```ruby
-postal = Basho::PostalCode.find("154-0011").first
+postal = Basho::PostalCode.find("154-0011")
 postal.prefecture_name  # => "東京都"
 postal.city_name        # => "世田谷区"
 postal.town             # => "上馬"
@@ -68,7 +71,7 @@ user.town_name  # => "上馬"
 
 ```ruby
 Basho::Prefecture.find(13).name           # => "東京都"
-Basho::Prefecture.where(region: "関東")    # => 7 results
+Basho::Prefecture.where(region: "関東")    # => 7 prefectures
 Basho::City.find("131016").name            # => "千代田区"
 ```
 
@@ -77,70 +80,109 @@ Basho::City.find("131016").name            # => "千代田区"
 ### Prefecture
 
 ```ruby
-Basho::Prefecture.find(13)             # Find by code
-Basho::Prefecture.find(name: "東京都")  # Find by name
-Basho::Prefecture.all                   # All 47 prefectures
-Basho::Prefecture.where(region: "関東") # Filter by region
+# Class methods
+Basho::Prefecture.find(13)                 # Find by code (Integer)
+Basho::Prefecture.find(name: "東京都")      # Find by Japanese name
+Basho::Prefecture.find(name_en: "Tokyo")   # Find by English name
+Basho::Prefecture.all                      # All 47 prefectures
+Basho::Prefecture.where(region: "関東")     # Filter by region name
+```
 
+```ruby
+# Instance methods / members
 pref = Basho::Prefecture.find(13)
-pref.code          # => 13
-pref.name          # => "東京都"
-pref.name_en       # => "Tokyo"
-pref.name_kana     # => "トウキョウト"
-pref.name_hiragana # => "とうきょうと"
-pref.type          # => "都"
-pref.region        # => Region
-pref.cities        # => Array<City>
-pref.capital       # => City (prefectural capital)
+pref.code          # => 13            (Integer)
+pref.name          # => "東京都"       (String)
+pref.name_en       # => "Tokyo"       (String)
+pref.name_kana     # => "トウキョウト"  (String, katakana)
+pref.name_hiragana # => "とうきょうと"  (String, hiragana)
+pref.region_name   # => "関東"         (String)
+pref.type          # => "都"           (String: "都" / "道" / "府" / "県")
+pref.capital_code  # => "131016"       (String, 6-digit city code)
+pref.region        # => Basho::Region
+pref.cities        # => Array<Basho::City>
+pref.capital       # => Basho::City (prefectural capital)
 ```
 
 ### City
 
 ```ruby
-Basho::City.find("131016")              # Find by municipality code
-Basho::City.where(prefecture_code: 13)  # Filter by prefecture
-Basho::City.valid_code?("131016")       # Validate check digit
+# Class methods
+Basho::City.find("131016")              # Find by 6-digit municipality code (String)
+Basho::City.where(prefecture_code: 13)  # Filter by prefecture code (Integer)
+Basho::City.valid_code?("131016")       # Validate JIS X 0401 check digit
+```
 
+```ruby
+# Instance methods / members
 city = Basho::City.find("131016")
-city.code             # => "131016"
-city.prefecture_code  # => 13
-city.name             # => "千代田区"
-city.name_kana        # => "チヨダク"
-city.capital?         # => false
-city.prefecture       # => Prefecture
+city.code             # => "131016"    (String, 6-digit)
+city.prefecture_code  # => 13          (Integer)
+city.name             # => "千代田区"   (String)
+city.name_kana        # => "チヨダク"   (String, katakana)
+city.district         # => nil         (String or nil, e.g. "島尻郡")
+city.capital          # => false       (Boolean, raw member)
+city.capital?         # => false       (Boolean, prefectural capital?)
+city.full_name        # => "千代田区"   (String, prepends district if present)
+city.prefecture       # => Basho::Prefecture
+```
+
+`district` is set only for towns/villages that belong to a county (gun). For example:
+
+```ruby
+city = Basho::City.find("473821")
+city.name       # => "八重瀬町"
+city.district   # => "島尻郡"
+city.full_name  # => "島尻郡八重瀬町"
 ```
 
 ### PostalCode
 
+`find` returns a single `PostalCode` or `nil`. `where` returns an `Array` (may contain multiple results for shared postal codes).
+
+```ruby
+# Class methods
+Basho::PostalCode.find("154-0011")    # => PostalCode or nil (first match)
+Basho::PostalCode.find("1540011")     # Hyphenless format also works
+Basho::PostalCode.where(code: "154-0011")  # => Array<PostalCode>
+```
+
 ```ruby
-results = Basho::PostalCode.find("154-0011")  # Always returns an Array
-results = Basho::PostalCode.find("1540011")    # Hyphenless format also works
-
-postal = results.first
-postal.code              # => "1540011"
-postal.formatted_code    # => "154-0011"
-postal.prefecture_code   # => 13
-postal.prefecture_name   # => "東京都"
-postal.city_name         # => "世田谷区"
-postal.town              # => "上馬"
-postal.prefecture        # => Prefecture
+# Instance methods / members
+postal = Basho::PostalCode.find("154-0011")
+postal.code              # => "1540011"   (String, 7 digits, no hyphen)
+postal.formatted_code    # => "154-0011"  (String, with hyphen)
+postal.prefecture_code   # => 13          (Integer)
+postal.city_name         # => "世田谷区"   (String)
+postal.town              # => "上馬"       (String)
+postal.prefecture_name   # => "東京都"     (String)
+postal.prefecture        # => Basho::Prefecture
 ```
 
 ### Region
 
+9 regions: Hokkaido, Tohoku, Kanto, Chubu, Kinki, Chugoku, Shikoku, Kyushu, Okinawa.
+
 ```ruby
-Basho::Region.all                # 8 regions
-Basho::Region.find("関東")       # Find by name
+# Class methods
+Basho::Region.all                # => Array of 9 regions
+Basho::Region.find("関東")       # Find by Japanese name
+Basho::Region.find("Kanto")     # Find by English name
+```
 
+```ruby
+# Instance methods / members
 region = Basho::Region.find("関東")
-region.name             # => "関東"
-region.name_en          # => "Kanto"
-region.prefectures      # => Array<Prefecture>
-region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]
+region.name             # => "関東"     (String)
+region.name_en          # => "Kanto"   (String)
+region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]  (Array<Integer>)
+region.prefectures      # => Array<Basho::Prefecture>
 ```
 
 ## ActiveRecord Integration
 
+Add `include Basho` to your model to enable the `basho` and `basho_postal` macros.
+
 ### Look up prefecture and city from a municipality code
 
 ```ruby
@@ -149,11 +191,19 @@ class Shop < ApplicationRecord
   basho :local_gov_code
 end
 
-shop.prefecture   # => Prefecture
-shop.city         # => City
+shop.city         # => Basho::City
+shop.prefecture   # => Basho::Prefecture
 shop.full_address # => "東京都千代田区"
 ```
 
+`basho :column` defines three instance methods:
+
+| Method | Return value |
+|--------|-------------|
+| `city` | `Basho::City` found by the column value |
+| `prefecture` | `Basho::Prefecture` via `city.prefecture` |
+| `full_address` | `"#{prefecture.name}#{city.name}"` or `nil` |
+
 ### Get an address string from a postal code
 
 ```ruby
@@ -165,9 +215,11 @@ end
 shop.postal_address # => "東京都世田谷区上馬"
 ```
 
+`basho_postal :column` (without mapping options) defines a `postal_address` method that returns `"#{prefecture_name}#{city_name}#{town}"` or `nil`.
+
 ### Auto-save address columns from a postal code
 
-When you pass mapping options to `basho_postal`, it registers a `before_save` callback that auto-fills address columns from the postal code.
+When you pass mapping options to `basho_postal`, it registers a `before_save` callback that auto-fills address columns whenever the postal code column changes.
 
 ```ruby
 class User < ApplicationRecord
@@ -179,29 +231,44 @@ class User < ApplicationRecord
 end
 ```
 
-- Resolution runs only when `postal_code` changes
+Available mapping keys:
+
+| Key | Resolved value |
+|-----|---------------|
+| `prefecture:` | Prefecture name (e.g. "東京都") |
+| `city:` | City name (e.g. "世田谷区") |
+| `town:` | Town name (e.g. "上馬") |
+| `prefecture_code:` | Prefecture code (e.g. 13) |
+| `city_code:` | 6-digit municipality code (e.g. "131130") |
+
+- Resolution runs only when the postal code column will change on save
 - Partial mappings are supported (e.g. `prefecture:` only)
-- Without options, only the `postal_address` method is defined (backward compatible)
+- The `postal_address` method is always defined regardless of mapping options
 
 ## Hotwire Engine
 
-A built-in Rails Engine providing postal code auto-fill and prefecture-city cascade select via Turbo Frame + Stimulus. No custom controllers needed.
+A built-in Rails Engine providing postal code auto-fill via Turbo Frame + Stimulus.
 
 ### Setup
 
-```ruby
-# config/application.rb
-require "basho/engine"
-```
+Mount the Engine in your routes:
 
 ```ruby
 # config/routes.rb
 mount Basho::Engine, at: "/basho"
 ```
 
+The Engine provides a single route:
+
+| Method | Path | Controller#Action |
+|--------|------|------------------|
+| GET | `/basho/postal_codes/lookup?code=1540011` | `Basho::PostalCodesController#lookup` |
+
+The Stimulus controller and form helper are automatically registered via importmap and `ActionView` initializers.
+
 ### Postal Code Auto-fill
 
-Automatically fills in prefecture, city, and town fields when a postal code is entered.
+Automatically fills in prefecture, city, and town fields when a 7-digit postal code is entered.
 
 ```erb
 <%= form_with(model: @shop) do |f| %>
@@ -213,80 +280,111 @@ Automatically fills in prefecture, city, and town fields when a postal code is e
                   "basho--auto-fill-target": "input" } %>
 
     <turbo-frame id="basho-result"
-                 data-basho--auto-fill-target="frame"></turbo-frame>
-
-    <%= f.text_field :prefecture,
-          data: { "basho--auto-fill-target": "prefecture" } %>
-    <%= f.text_field :city,
-          data: { "basho--auto-fill-target": "city" } %>
-    <%= f.text_field :town,
-          data: { "basho--auto-fill-target": "town" } %>
+                 data-basho--auto-fill-target="frame"
+                 data-action="turbo:frame-load->basho--auto-fill#fill"></turbo-frame>
+
+    <div data-basho--auto-fill-target="fields" hidden>
+      <%= f.text_field :prefecture, disabled: true,
+            data: { "basho--auto-fill-target": "prefecture" } %>
+      <%= f.text_field :city, disabled: true,
+            data: { "basho--auto-fill-target": "city" } %>
+      <%= f.text_field :town, disabled: true,
+            data: { "basho--auto-fill-target": "town" } %>
+    </div>
   </div>
 <% end %>
 ```
 
+How it works:
+
 1. User enters a 7-digit postal code
-2. After a 300ms debounce, a Turbo Frame request is sent to the server
-3. Stimulus auto-fills the prefecture, city, and town fields
+2. A Turbo Frame request is sent to the Engine's lookup endpoint
+3. Stimulus fills the prefecture, city, and town fields and shows the `fields` container
+4. When the postal code is cleared or incomplete, the fields are hidden
 
-### Prefecture-City Cascade Select
+The `fields` target is optional. Without it, the fields remain visible and are simply cleared.
 
-Selecting a prefecture dynamically loads the corresponding cities via JSON API.
+You can use the `basho_autofill_frame_tag` helper instead of writing the `<turbo-frame>` tag manually:
 
 ```erb
-<%= form_with(model: @shop) do |f| %>
-  <div data-controller="basho--cascade-select"
-       data-basho--cascade-select-prefectures-url-value="<%= basho.prefectures_path %>"
-       data-basho--cascade-select-cities-url-template-value="<%= basho.cities_prefecture_path(':code') %>">
-
-    <select data-basho--cascade-select-target="prefecture"
-            data-action="change->basho--cascade-select#prefectureChanged">
-      <option value="">Select prefecture</option>
-    </select>
-
-    <select data-basho--cascade-select-target="city">
-      <option value="">Select city</option>
-    </select>
-  </div>
-<% end %>
+<%= basho_autofill_frame_tag %>
 ```
 
-Use the `basho_cascade_data` helper for concise data attributes.
+This renders:
 
-```erb
-<div <%= tag.attributes(data: basho_cascade_data) %>>
-  ...
-</div>
+```html
+<turbo-frame id="basho-result"
+             data-basho--auto-fill-target="frame"
+             data-action="turbo:frame-load->basho--auto-fill#fill"></turbo-frame>
 ```
 
-1. On page load, if the prefecture select is empty, all 47 prefectures are fetched from the API
-2. Selecting a prefecture rebuilds the city select from the API
-3. Changing the prefecture resets and re-fetches the city select
+#### Stimulus Controller Targets and Values
 
-### JSON API Endpoints
+| Type | Name | Description |
+|------|------|-------------|
+| Value | `url` (String) | Lookup endpoint URL (required) |
+| Target | `input` | Postal code input field |
+| Target | `frame` | Turbo Frame for server response |
+| Target | `prefecture` | Prefecture output field |
+| Target | `city` | City output field |
+| Target | `town` | Town output field |
+| Target | `fields` | Container to show/hide (optional) |
 
-Mounting the Engine exposes the following endpoints.
+### Prefecture-City Cascade Select
+
+Basho provides the data -- build the UI in your app using Turbo Frame.
 
+```ruby
+# app/controllers/cities_controller.rb
+class CitiesController < ApplicationController
+  def index
+    @cities = Basho::City.where(prefecture_code: params[:prefecture_code].to_i)
+  end
+end
 ```
-GET /basho/prefectures           # => [{"code":1,"name":"北海道"}, ...]
-GET /basho/prefectures/13/cities  # => [{"code":"131016","name":"千代田区"}, ...]
-GET /basho/postal_codes/lookup?code=1540011  # => Turbo Frame HTML
+
+```erb
+<%# app/views/cities/index.html.erb %>
+<turbo-frame id="city-select">
+  <%= f.select :city_code,
+        @cities.map { |c| [c.name, c.code] },
+        { include_blank: "Select city" } %>
+</turbo-frame>
+```
+
+```erb
+<%# In your form %>
+<%= f.select :prefecture_code,
+      Basho::Prefecture.all.map { |p| [p.name, p.code] },
+      { include_blank: "Select prefecture" },
+      data: { action: "change->auto-submit#submit",
+              turbo_frame: "city-select" } %>
+
+<turbo-frame id="city-select">
+  <%= f.select :city_code, [], include_blank: "Select city" %>
+</turbo-frame>
 ```
 
-## Without the Engine
+This keeps the HTML and styling in your app where it belongs.
+
+## Without Hotwire
 
-You can skip the Engine and build your own endpoints using `PostalCode.find`.
+The data API and ActiveRecord integration work without Hotwire. If you don't mount the Engine, no routes or Stimulus controllers are loaded.
 
 ```ruby
-# JSON API
-class PostalCodesController < ApplicationController
-  def lookup
-    results = Basho::PostalCode.find(params[:code])
-
-    render json: results.map { |r|
-      { prefecture: r.prefecture_name, city: r.city_name, town: r.town }
-    }
-  end
+# Just the data API -- works in any Ruby app
+require "basho"
+
+Basho::PostalCode.find("154-0011").town         # => "上馬"
+Basho::Prefecture.find(13).name                 # => "東京都"
+Basho::City.where(prefecture_code: 13)          # => Array<City>
+```
+
+```ruby
+# ActiveRecord integration -- works in any Rails app, Hotwire or not
+class Shop < ApplicationRecord
+  include Basho
+  basho_postal :postal_code, city_code: :city_code, town: :town
 end
 ```
 
@@ -297,7 +395,7 @@ end
 | Prefectures | Ministry of Internal Affairs, JIS X 0401 | Rarely changes |
 | Cities | Ministry of Internal Affairs, Local Government Codes | A few times per year |
 | Postal codes | Japan Post KEN_ALL.csv | Monthly (auto-updated via GitHub Actions) |
-| Regions | 8 regions (hardcoded) | Never changes |
+| Regions | 9 regions (hardcoded) | Never changes |
 
 ## Development
 

data/app/assets/javascripts/controllers/basho/auto_fill_controller.js

@@ -1,34 +1,29 @@
 import { Controller } from "@hotwired/stimulus"
 
 export default class extends Controller {
-  static targets = ["input", "frame", "prefecture", "city", "town"]
-  static values = { url: String, delay: { type: Number, default: 300 } }
-
-  connect() {
-    this.frameTarget.addEventListener("turbo:frame-load", this.#fillFields)
-  }
-
-  disconnect() {
-    this.frameTarget.removeEventListener("turbo:frame-load", this.#fillFields)
-    clearTimeout(this.timeout)
-  }
+  static targets = ["input", "frame", "fields", "prefecture", "city", "town"]
+  static values = { url: String }
 
   lookup() {
-    clearTimeout(this.timeout)
     const code = this.inputTarget.value.replace(/-/g, "")
-    if (code.length < 7) return
 
-    this.timeout = setTimeout(() => {
-      this.frameTarget.src = `${this.urlValue}?code=${code}`
-    }, this.delayValue)
+    if (code.length < 7) {
+      this.#setAddress()
+      return
+    }
+
+    this.frameTarget.src = `${this.urlValue}?code=${encodeURIComponent(code)}`
   }
 
-  #fillFields = () => {
-    const data = this.frameTarget.querySelector("[data-address]")
-    if (!data) return
+  fill() {
+    const el = this.frameTarget.querySelector("[data-address]")
+    if (el) this.#setAddress(el.dataset)
+  }
 
-    if (this.hasPrefectureTarget) this.prefectureTarget.value = data.dataset.prefecture || ""
-    if (this.hasCityTarget) this.cityTarget.value = data.dataset.city || ""
-    if (this.hasTownTarget) this.townTarget.value = data.dataset.town || ""
+  #setAddress(data) {
+    if (this.hasPrefectureTarget) this.prefectureTarget.value = data?.prefecture || ""
+    if (this.hasCityTarget) this.cityTarget.value = data?.city || ""
+    if (this.hasTownTarget) this.townTarget.value = data?.town || ""
+    if (this.hasFieldsTarget) this.fieldsTarget.hidden = !data
   }
 }

data/app/controllers/basho/postal_codes_controller.rb

@@ -4,8 +4,7 @@ module Basho
   # 郵便番号からTurbo Frame形式で住所を返すコントローラー
   class PostalCodesController < ActionController::Base
     def lookup
-      code = params[:code].to_s.delete("-")
-      @postal = PostalCode.find(code).first if code.match?(/\A\d{7}\z/)
+      @postal = PostalCode.find(params[:code])
 
       render layout: false
     end

data/app/helpers/basho/form_helper.rb

@@ -1,22 +1,12 @@
 # frozen_string_literal: true
 
 module Basho
-  # 自動入力・カスケードセレクト用のフォームヘルパー
+  # 郵便番号自動入力用のフォームヘルパー
   module FormHelper
     def basho_autofill_frame_tag
       content_tag("turbo-frame", nil, id: "basho-result",
-                                      data: { "basho--auto-fill-target" => "frame" })
-    end
-
-    def basho_cascade_data
-      prefectures_url = basho.prefectures_path
-      cities_template = basho.cities_prefecture_path(":code")
-
-      {
-        controller: "basho--cascade-select",
-        "basho--cascade-select-prefectures-url-value" => prefectures_url,
-        "basho--cascade-select-cities-url-template-value" => cities_template
-      }
+                                      data: { "basho--auto-fill-target" => "frame",
+                                              action: "turbo:frame-load->basho--auto-fill#fill" })
     end
   end
 end

data/config/routes.rb

@@ -2,7 +2,4 @@
 
 Basho::Engine.routes.draw do
   get "postal_codes/lookup", to: "postal_codes#lookup", as: :postal_code_lookup
-  resources :prefectures, only: [:index], param: :code do
-    get :cities, on: :member
-  end
 end

data/data/cities/06.json

@@ -255,7 +255,7 @@
     "prefecture_code": 6,
     "name": "庄内町",
     "capital": false,
-    "name_kana": "シヨウナイマチ",
+    "name_kana": "ショウナイマチ",
     "district": "東田川郡"
   },
   {

data/data/cities/10.json

@@ -144,7 +144,7 @@
     "prefecture_code": 10,
     "name": "中之条町",
     "capital": false,
-    "name_kana": "ナカノジヨウマチ",
+    "name_kana": "ナカノジョウマチ",
     "district": "吾妻郡"
   },
   {

data/data/cities/11.json

@@ -102,7 +102,7 @@
     "prefecture_code": 11,
     "name": "行田市",
     "capital": false,
-    "name_kana": "ギヨウダシ"
+    "name_kana": "ギョウダシ"
   },
   {
     "code": "112071",
@@ -137,7 +137,7 @@
     "prefecture_code": 11,
     "name": "本庄市",
     "capital": false,
-    "name_kana": "ホンジヨウシ"
+    "name_kana": "ホンジョウシ"
   },
   {
     "code": "112127",
@@ -165,7 +165,7 @@
     "prefecture_code": 11,
     "name": "羽生市",
     "capital": false,
-    "name_kana": "ハニユウシ"
+    "name_kana": "ハニュウシ"
   },
   {
     "code": "112178",

data/data/cities/12.json

@@ -345,7 +345,7 @@
     "prefecture_code": 12,
     "name": "九十九里町",
     "capital": false,
-    "name_kana": "クジユウクリマチ",
+    "name_kana": "クジュウクリマチ",
     "district": "山武郡"
   },
   {
@@ -425,7 +425,7 @@
     "prefecture_code": 12,
     "name": "御宿町",
     "capital": false,
-    "name_kana": "オンジユクマチ",
+    "name_kana": "オンジュクマチ",
     "district": "夷隅郡"
   },
   {
@@ -433,7 +433,7 @@
     "prefecture_code": 12,
     "name": "鋸南町",
     "capital": false,
-    "name_kana": "キヨナンマチ",
+    "name_kana": "キョナンマチ",
     "district": "安房郡"
   }
 ]

data/data/cities/14.json

@@ -413,7 +413,7 @@
     "prefecture_code": 14,
     "name": "真鶴町",
     "capital": false,
-    "name_kana": "マナツルマチ",
+    "name_kana": "マナヅルマチ",
     "district": "足柄下郡"
   },
   {

data/data/cities/23.json

@@ -4,8 +4,7 @@
     "prefecture_code": 23,
     "name": "名古屋市",
     "capital": true,
-    "name_kana": "ナゴヤシ",
-    "district": "北"
+    "name_kana": "ナゴヤシ"
   },
   {
     "code": "231011",

data/data/cities/25.json

@@ -103,7 +103,7 @@
     "prefecture_code": 25,
     "name": "竜王町",
     "capital": false,
-    "name_kana": "リユウオウチョウ",
+    "name_kana": "リュウオウチョウ",
     "district": "蒲生郡"
   },
   {