stimulus-coder

Stimulus Coder

対象者： Stimulus.js と Hotwire を使ってインタラクティブな UI を構築する開発者。

目標： 状態を HTML に保持し、コントローラーで動作を追加する、保守しやすい Stimulus コントローラーを作成します。

基本概念

• コントローラー は HTML 要素に動作を割り当てます
• アクション は DOM イベントに応答します
• ターゲット は重要な要素を参照します
• 値 は data 属性を通じて状態を管理します

コントローラー設計の原則

コントローラーを小さく、再利用可能に保つ

// Good: Generic, reusable controller
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["content"]
  static values = { open: Boolean }

  toggle() { this.openValue = !this.openValue }

  openValueChanged() {
    this.contentTarget.classList.toggle("hidden", !this.openValue)
  }
}

設定には Data 属性を使う

export default class extends Controller {
  static values = {
    delay: { type: Number, default: 300 },
    event: { type: String, default: "input" }
  }

  connect() {
    this.element.addEventListener(this.eventValue, this.submit.bind(this))
  }

  submit() {
    clearTimeout(this.timeout)
    this.timeout = setTimeout(() => this.element.requestSubmit(), this.delayValue)
  }
}

<%= form_with data: { controller: "auto-submit", auto_submit_delay_value: 500 } %>

複数のコントローラーを組み合わせる

<div data-controller="toggle clipboard" data-toggle-open-value="false">
  <button data-action="toggle#toggle">Show</button>
  <div data-toggle-target="content" class="hidden">
    <code data-clipboard-target="source">secret-code</code>
    <button data-action="clipboard#copy">Copy</button>
  </div>
</div>

ターゲットと値

要素の参照にはターゲットを使う

export default class extends Controller {
  static targets = ["tab", "panel"]
  static values = { index: { type: Number, default: 0 } }

  select(event) { this.indexValue = this.tabTargets.indexOf(event.currentTarget) }

  indexValueChanged() {
    this.panelTargets.forEach((panel, i) => panel.classList.toggle("hidden", i !== this.indexValue))
    this.tabTargets.forEach((tab, i) => tab.setAttribute("aria-selected", i === this.indexValue))
  }
}

アクションの処理

<button data-action="click->toggle#toggle">Toggle</button>
<input data-action="input->search#update focus->search#expand">
<button data-action="modal#open" data-modal-id-param="confirm-dialog">Open</button>
<input data-action="keydown.enter->form#submit keydown.escape->form#cancel">

アクションパラメーター

open(event) {
  const modalId = event.params.id
  document.getElementById(modalId)?.showModal()
}

よくあるコントローラーパターン

ドロップダウンコントローラー

export default class extends Controller {
  static targets = ["menu"]
  static values = { open: Boolean }

  toggle() { this.openValue = !this.openValue }

  close(event) {
    if (!this.element.contains(event.target)) this.openValue = false
  }

  openValueChanged() {
    this.menuTarget.classList.toggle("hidden", !this.openValue)
    if (this.openValue) document.addEventListener("click", this.close.bind(this), { once: true })
  }
}

クリップボードコントローラー

export default class extends Controller {
  static targets = ["source", "button"]
  static values = { successMessage: { type: String, default: "Copied!" } }

  async copy() {
    const text = this.sourceTarget.value || this.sourceTarget.textContent
    await navigator.clipboard.writeText(text)
    this.showSuccess()
  }

  showSuccess() {
    const original = this.buttonTarget.textContent
    this.buttonTarget.textContent = this.successMessageValue
    setTimeout(() => this.buttonTarget.textContent = original, 2000)
  }
}

Turbo との連携

export default class extends Controller {
  connect() {
    document.addEventListener("turbo:before-visit", this.dismiss.bind(this))
    this.timeout = setTimeout(() => this.dismiss(), 5000)
  }

  disconnect() { clearTimeout(this.timeout) }
  dismiss() { this.element.remove() }
}

アーキテクチャパターン

コントローラーを設定可能にする

ハードコードされた値は data 属性に外部化します。CSS クラス、セレクター、しきい値をコントローラーのロジックに埋め込まないでください。

// Bad: hardcoded
export default class extends Controller {
  toggle() { this.element.classList.toggle("hidden") }
}

// Good: configurable
export default class extends Controller {
  static classes = ["toggle"]
  toggle() { this.element.classList.toggle(this.toggleClass) }
}

深い継承よりミックスイン

動作を共有するものの、特殊化を表すわけではない場合はミックスインを使います。

判断基準：

• 「〜である」 → 継承（クラスが BaseController を拡張する）
• 「〜として振る舞う」 → ミックスイン（connect 時に動作を適用する）
• 「〜を持つ」 → コンポジション（別個のコントローラー＋アウトレット）

// Mixin pattern
const Sortable = (controller) => {
  const original = controller.prototype.connect
  controller.prototype.connect = function() {
    if (original) original.call(this)
    this.sortable = new Sortable(this.element, this.sortableOptions)
  }
}

ターゲットを持たないコントローラー

コントローラーが要素レベルとターゲットレベルの両方の関心事を扱う場合は、分割します。this.element に作用することと、ターゲットに作用することは、それぞれ別の責務です。

分割したコントローラー間では、カスタムイベントまたはアウトレットを使って連携します。

名前空間付き属性

各値を明示的に定義せず、柔軟なパラメーターセットを使う場合：

// Read arbitrary data-chart-* attributes
get chartOptions() {
  return Object.entries(this.element.dataset)
    .filter(([key]) => key.startsWith("chart"))
    .reduce((opts, [key, val]) => {
      opts[key.replace("chart", "").toLowerCase()] = val
      return opts
    }, {})
}

Stimulus に適用される SOLID 原則については、architecture-patterns.md を参照してください。

コントローラー間の連携

結合度の要件に応じてパターンを選びます。

パターン	結合度	方向	使用する場面
カスタムイベント	疎結合	ブロードキャスト（1→多数）	送信側が受信側を知らない場合
アウトレット	構造化	直接（1→1、1→少数）	レイアウト内の関係が既知の場合
コールバック	読み取り専用	リクエスト／レスポンス	アクションを実行せずに状態を共有する場合

カスタムイベント（デフォルトとして推奨）

// Sender
this.dispatch("submitted", { detail: { id: this.idValue }, bubbles: true })

// Receiver (in HTML)
// data-action="sender:submitted->receiver#handleSubmit"

ルール：

• コントローラー間イベントでは、必ず bubbles: true を設定します
• イベント名には名前空間を付けます：form:submitted、cart:updated
• detail の仕様を文書化します

アウトレット（構造化された関係）

export default class extends Controller {
  static outlets = ["result"]

  search() {
    const results = this.performSearch()
    this.resultOutlets.forEach(outlet => outlet.update(results))
  }

  resultOutletConnected(outlet) { /* setup */ }
  resultOutletDisconnected(outlet) { /* cleanup */ }
}

ライフサイクルのベストプラクティス

connect() を使いすぎない

connect() はサードパーティープラグインの初期化専用です。状態のセットアップ（Values API を使用）やイベントリスナー（data-action を使用）には使いません。

// Good: plugin init in connect
connect() {
  this.chart = new Chart(this.canvasTarget, this.chartConfig)
}

disconnect() {
  this.chart.destroy()
  this.chart = null
}

connect と disconnect は必ず対にする

connect() で取得したリソースはすべて、disconnect() で解放する必要があります。Turbo によるナビゲーション中、コントローラーは複数回 connect／disconnect されることがあります。

Turbo キャッシュの後処理

キャッシュされたページに戻った際の「操作済みコンテンツのちらつき」を防ぎます。

connect() {
  document.addEventListener("turbo:before-cache", this.teardown.bind(this))
  this.slider = new Swiper(this.element, this.config)
}

teardown() {
  this.slider?.destroy()
  // Restore original DOM state before caching
}

disconnect() {
  this.teardown()
}

イベントリスナーの管理

バインド済みの参照を保持する

.bind() は呼び出すたびに新しい関数を作成します。適切に削除できるよう、参照を保持します。

connect() {
  this.boundResize = this.resize.bind(this)
  window.addEventListener("resize", this.boundResize, { passive: true })
}

disconnect() {
  window.removeEventListener("resize", this.boundResize)
}

宣言的なアクションを優先する

<%# Good: Stimulus manages lifecycle %>
<div data-controller="search"
     data-action="resize@window->search#layout keydown.escape@window->search#close">

<%# Bad: manual addEventListener in connect() %>

グローバルイベントでは、data-action の接尾辞に @window または @document を使用します。

パターンの詳細については、lifecycle-and-events.md を参照してください。

アプリケーションコントローラー

共通機能の基底となる app/javascript/controllers/application_controller.js を作成します。

import { Controller } from "@hotwired/stimulus"

export default class ApplicationController extends Controller {
  handleError(error, context = {}) {
    console.error(`[${this.identifier}]`, error, context)
    // Sentry.captureException(error, { extra: context })
  }
}

ドメインコントローラーでこれを拡張します。

import ApplicationController from "./application_controller"

export default class extends ApplicationController {
  async save() {
    try {
      await this.persist()
    } catch (error) {
      this.handleError(error, { action: "save", id: this.idValue })
    }
  }
}

ルール：

• 非同期処理やサードパーティーライブラリの呼び出しには try-catch を使います
• エラーを握りつぶしてはいけません。handleError() を通じてログに記録するか、報告します
• フォームには submit() ではなく requestSubmit() を使います。バリデーションが実行され、Turbo によるインターセプトが有効になります

アンチパターン

アンチパターン	問題	解決策
DOM を大量に作成する	Stimulus の理念に反します	HTML はサーバー側でレンダリングします
JS に状態を保存する	ナビゲーション時に状態が失われます	HTML の Values を使用します
特定の用途に限定しすぎたコントローラー	再利用できません	汎用的な動作を設計します
querySelector を手動で使用する	壊れやすく、Stimulus を迂回します	ターゲットを使用します
インラインのイベントハンドラー	保守が困難です	data-action を使用します
connect() に処理を詰め込みすぎる	肥大化し、関心事が混在します	状態には Values、イベントには data-action を使用します
コントローラー間の結合が強い	壊れやすく、テストが困難です	カスタムイベントまたはアウトレットを使用します
disconnect でのクリーンアップ漏れ	メモリーリークやリスナーの重複が発生します	必ず connect と disconnect を組み合わせます
バインドされていないイベント参照	removeEventListener で削除できません	.bind() の結果を保存します

出力形式

Stimulus コントローラーを作成する際は、以下を提示してください。

1. コントローラー - 完全な JavaScript の実装
2. HTML の例 - 使用方法を示すサンプルマークアップ
3. 設定 - 使用可能な Values とターゲット
4. 統合 - 該当する場合は、Turbo との連携方法