basho 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11901f37562fae58d8b52881acb27f5d12d47de6aa21b156bb36fd2a87e1af28
+  data.tar.gz: f33b54817ef286e36a88daca0384fbb51b0d46c528a0be640949f816011b9c4a
+SHA512:
+  metadata.gz: ecaa8057ece273aaf1ed46e9d66d56195935b94b55d1bf45667b1da9af9e05e4bfa7d9c6ea772f325f0c82c698440983f731583eca56dbb770cf7e4f836c2d06
+  data.tar.gz: 27260c4b272179a7db0f7fafc8f1b1f5de53b88341fbe1b4399b65d954154a55ce550414ec765280d94acd3ed90d0bec1088a73c01555c94e0e6a3fd5918a981

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-08
+
+### Added
+
+- `Basho::Prefecture` - 47都道府県の検索（コード・日本語名・英語名）、地方での絞り込み
+- `Basho::City` - 市区町村の検索（6桁JISコード）、都道府県コードでの絞り込み
+- `Basho::PostalCode` - 郵便番号の検索（ハイフン有無対応、1対多マッピング）
+- `Basho::Region` - 8地方区分の検索（日本語/英語名）
+- `Basho::CodeValidator` - JIS X 0401 チェックディジット検証
+- `Basho::Data::Loader` - JSONデータの遅延読み込みとキャッシュ
+- `Basho::ActiveRecord::Base` - `basho` / `basho_postal` マクロ
+- 都道府県・市区町村・郵便番号のJSONデータ同梱
+- GitHub Actions CI（Ruby 3.2/3.3/3.4）
+- 月次データ自動更新ワークフロー
+
+[0.1.0]: https://github.com/wagai/basho/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Hirotaka Wagai
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,311 @@
+# Basho
+
+日本の住所データ（都道府県・市区町村・郵便番号・地方区分）を統一的に扱うRuby gem。
+
+## なぜ作ったか
+
+日本の住所まわりは扱いが面倒です。
+
+- 郵便番号から住所を引きたいだけなのに、CSVを自前でパースしてDBに入れる必要がある
+- 都道府県・市区町村のマスタデータを持つためにマイグレーションを書かされる
+- 郵便番号の自動入力、都道府県→市区町村の連動セレクトは毎回同じコードを書いている
+- 既存gemはRails依存が強い、データが古い、Hotwire非対応、など
+
+Bashoはこれらをまとめて解決します。
+
+- **DBマイグレーション不要** — 全データをJSON同梱。`gem install`だけで使える
+- **ActiveRecord統合** — `include Basho` + 1行のマクロで郵便番号→住所の自動保存
+- **Hotwire対応** — 郵便番号自動入力・カスケードセレクトをビルトインEngine提供
+- **軽量** — `Data.define`によるイミュータブルモデル、遅延読み込み、外部依存なし
+
+## 対応バージョン
+
+- Ruby 3.2 / 3.3 / 3.4 / 4.0
+
+## インストール
+
+```ruby
+# Gemfile
+gem "basho"
+```
+
+```bash
+bundle install
+```
+
+## クイックスタート
+
+### 郵便番号から住所を引く
+
+```ruby
+postal = Basho::PostalCode.find("154-0011").first
+postal.prefecture_name  # => "東京都"
+postal.city_name        # => "世田谷区"
+postal.town             # => "上馬"
+```
+
+### モデルで郵便番号→住所を自動保存
+
+```ruby
+class User < ApplicationRecord
+  include Basho
+  basho_postal :postal_code,
+    prefecture: :pref_name,
+    city: :city_name,
+    town: :town_name
+end
+
+user = User.new(postal_code: "154-0011")
+user.save
+user.pref_name  # => "東京都"
+user.city_name  # => "世田谷区"
+user.town_name  # => "上馬"
+```
+
+### 都道府県・市区町村を検索
+
+```ruby
+Basho::Prefecture.find(13).name           # => "東京都"
+Basho::Prefecture.where(region: "関東")    # => 7件
+Basho::City.find("131016").name            # => "千代田区"
+```
+
+## 使い方
+
+### Prefecture（都道府県）
+
+```ruby
+Basho::Prefecture.find(13)             # コードで検索
+Basho::Prefecture.find(name: "東京都")  # 名前で検索
+Basho::Prefecture.all                   # 全47件
+Basho::Prefecture.where(region: "関東") # 地方で絞り込み
+
+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（県庁所在地）
+```
+
+### City（市区町村）
+
+```ruby
+Basho::City.find("131016")              # 自治体コードで検索
+Basho::City.where(prefecture_code: 13)  # 都道府県で絞り込み
+Basho::City.valid_code?("131016")       # チェックディジット検証
+
+city = Basho::City.find("131016")
+city.code             # => "131016"
+city.prefecture_code  # => 13
+city.name             # => "千代田区"
+city.name_kana        # => "チヨダク"
+city.capital?         # => false
+city.prefecture       # => Prefecture
+```
+
+### PostalCode（郵便番号）
+
+```ruby
+results = Basho::PostalCode.find("154-0011")  # 常にArrayを返す
+results = Basho::PostalCode.find("1540011")    # ハイフンなしも可
+
+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
+```
+
+### Region（地方区分）
+
+```ruby
+Basho::Region.all                # 8地方
+Basho::Region.find("関東")       # 名前で検索
+
+region = Basho::Region.find("関東")
+region.name             # => "関東"
+region.name_en          # => "Kanto"
+region.prefectures      # => Array<Prefecture>
+region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]
+```
+
+## ActiveRecord統合
+
+### 自治体コードから都道府県・市区町村を引く
+
+```ruby
+class Shop < ApplicationRecord
+  include Basho
+  basho :local_gov_code
+end
+
+shop.prefecture   # => Prefecture
+shop.city         # => City
+shop.full_address # => "東京都千代田区"
+```
+
+### 郵便番号から住所文字列を取得
+
+```ruby
+class Shop < ApplicationRecord
+  include Basho
+  basho_postal :postal_code
+end
+
+shop.postal_address # => "東京都世田谷区上馬"
+```
+
+### 郵便番号から住所カラムを自動保存
+
+`basho_postal`にマッピングオプションを渡すと、`before_save`で郵便番号から住所カラムを自動入力します。
+
+```ruby
+class User < ApplicationRecord
+  include Basho
+  basho_postal :postal_code,
+    prefecture: :pref_name,
+    city: :city_name,
+    town: :town_name
+end
+```
+
+- `postal_code`が変更された時だけ解決を実行
+- マッピングは部分指定可能（`prefecture:`だけでもOK）
+- オプションなしの場合は`postal_address`メソッドのみ定義（後方互換）
+
+## Hotwire Engine
+
+Turbo Frame + Stimulusによる住所自動入力・カスケードセレクトをビルトインで提供するRails Engineです。自前でコントローラーを書かずに使えます。
+
+### セットアップ
+
+```ruby
+# config/application.rb
+require "basho/engine"
+```
+
+```ruby
+# config/routes.rb
+mount Basho::Engine, at: "/basho"
+```
+
+### 郵便番号自動入力
+
+郵便番号を入力すると都道府県・市区町村・町域フィールドを自動入力します。
+
+```erb
+<%= form_with(model: @shop) do |f| %>
+  <div data-controller="basho--auto-fill"
+       data-basho--auto-fill-url-value="<%= basho.postal_code_lookup_path %>">
+
+    <%= f.text_field :postal_code,
+          data: { action: "input->basho--auto-fill#lookup",
+                  "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" } %>
+  </div>
+<% end %>
+```
+
+1. ユーザーが郵便番号を入力（7桁）
+2. 300msデバウンス後、Turbo Frameでサーバーに問い合わせ
+3. Stimulusが都道府県・市区町村・町域フィールドを自動入力
+
+### 都道府県・市区町村カスケードセレクト
+
+都道府県を選択すると、対応する市区町村がJSON APIで動的に読み込まれます。
+
+```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="">都道府県を選択</option>
+    </select>
+
+    <select data-basho--cascade-select-target="city">
+      <option value="">市区町村を選択</option>
+    </select>
+  </div>
+<% end %>
+```
+
+`basho_cascade_data`ヘルパーでdata属性を簡潔に書けます。
+
+```erb
+<div <%= tag.attributes(data: basho_cascade_data) %>>
+  ...
+</div>
+```
+
+1. ページ読み込み時、都道府県セレクトが空ならAPIから47件を取得
+2. 都道府県を選択すると、市区町村セレクトをAPIから再構築
+3. 都道府県を変更すると、市区町村セレクトがリセットされ再取得
+
+### JSON APIエンドポイント
+
+Engineをマウントすると以下のエンドポイントが利用可能になります。
+
+```
+GET /basho/prefectures           # => [{"code":1,"name":"北海道"}, ...]
+GET /basho/prefectures/13/cities  # => [{"code":"131016","name":"千代田区"}, ...]
+GET /basho/postal_codes/lookup?code=1540011  # => Turbo Frame HTML
+```
+
+## Engine不要の場合
+
+Engineを使わず、`PostalCode.find`で自由にエンドポイントを作ることもできます。
+
+```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
+end
+```
+
+## データソース
+
+| データ | ソース | 更新頻度 |
+|--------|--------|----------|
+| 都道府県 | 総務省 JIS X 0401 | ほぼ変わらない |
+| 市区町村 | 総務省 全国地方公共団体コード | 年に数回 |
+| 郵便番号 | 日本郵便 KEN_ALL.csv | 月次（GitHub Actions自動更新） |
+| 地方区分 | 8地方（ハードコード） | 変わらない |
+
+## 開発
+
+```bash
+git clone https://github.com/wagai/basho.git
+cd basho
+bin/setup
+bundle exec rspec
+```
+
+## ライセンス
+
+MIT License

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

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

@@ -0,0 +1,34 @@
+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)
+  }
+
+  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)
+  }
+
+  #fillFields = () => {
+    const data = this.frameTarget.querySelector("[data-address]")
+    if (!data) return
+
+    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 || ""
+  }
+}

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

@@ -0,0 +1,77 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["prefecture", "city"]
+  static values = {
+    prefecturesUrl: String,
+    citiesUrlTemplate: String
+  }
+
+  connect() {
+    this.abortController = new AbortController()
+
+    if (this.prefectureTarget.options.length <= 1) {
+      this.#loadPrefectures()
+    }
+  }
+
+  disconnect() {
+    this.abortController.abort()
+  }
+
+  prefectureChanged() {
+    const code = this.prefectureTarget.value
+    this.#clearOptions(this.cityTarget)
+
+    if (!code) return
+
+    this.#loadCities(code)
+  }
+
+  async #loadPrefectures() {
+    try {
+      const response = await fetch(this.prefecturesUrlValue, {
+        signal: this.abortController.signal
+      })
+      if (!response.ok) return
+
+      const prefectures = await response.json()
+      prefectures.forEach(({ code, name }) => {
+        this.prefectureTarget.appendChild(new Option(name, code))
+      })
+    } catch (error) {
+      if (error.name !== "AbortError") {
+        this.dispatch("error", { detail: { message: "Failed to load prefectures", error } })
+      }
+    }
+  }
+
+  async #loadCities(code) {
+    if (!/^\d{1,2}$/.test(code)) return
+
+    try {
+      const url = this.citiesUrlTemplateValue.replace(":code", encodeURIComponent(code))
+      const response = await fetch(url, {
+        signal: this.abortController.signal
+      })
+      if (!response.ok) return
+
+      const cities = await response.json()
+      cities.forEach(({ code, name }) => {
+        this.cityTarget.appendChild(new Option(name, code))
+      })
+    } catch (error) {
+      if (error.name !== "AbortError") {
+        this.dispatch("error", { detail: { message: "Failed to load cities", error } })
+      }
+    }
+  }
+
+  #clearOptions(select) {
+    const hasPlaceholder = select.options[0] && !select.options[0].value
+    const start = hasPlaceholder ? 1 : 0
+    while (select.options.length > start) {
+      select.remove(start)
+    }
+  }
+}

data/app/controllers/basho/postal_codes_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+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/)
+
+      render layout: false
+    end
+  end
+end

data/app/controllers/basho/prefectures_controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Basho
+  # 都道府県・市区町村のJSON APIコントローラー
+  class PrefecturesController < ActionController::API
+    CACHE_MAX_AGE = 86_400 # 24時間
+
+    def index
+      expires_in CACHE_MAX_AGE, public: true
+
+      prefectures = Prefecture.all.map { |p| { code: p.code, name: p.name } }
+      render json: prefectures
+    end
+
+    def cities
+      prefecture = find_prefecture
+      return render json: [], status: :not_found unless prefecture
+
+      expires_in CACHE_MAX_AGE, public: true
+
+      cities = City.where(prefecture_code: prefecture.code).map { |c| { code: c.code, name: c.name } }
+      render json: cities
+    end
+
+    private
+
+    def find_prefecture
+      code = params[:code].to_s
+      return nil unless code.match?(/\A[1-9]\d?\z/)
+
+      Prefecture.find(code.to_i)
+    end
+  end
+end

data/app/helpers/basho/form_helper.rb

@@ -0,0 +1,22 @@
+# 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
+      }
+    end
+  end
+end

data/app/views/basho/postal_codes/lookup.html.erb

@@ -0,0 +1,9 @@
+<turbo-frame id="basho-result">
+  <% if @postal %>
+    <span data-address
+          data-prefecture="<%= @postal.prefecture_name %>"
+          data-city="<%= @postal.city_name %>"
+          data-town="<%= @postal.town %>"
+          hidden></span>
+  <% end %>
+</turbo-frame>

data/config/importmap.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+pin_all_from Basho::Engine.root.join("app/assets/javascripts/controllers/basho"),
+             under: "controllers/basho"

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+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