frontend-patterns

フロントエンドのパターン

Slim テンプレート、Simple Form、Stimulus コントローラー、Optics CSS を使用して Rails のフロントエンドを構築します。

技術スタック： Slim（HTML） • Simple Form（フォーム） • Stimulus（JavaScript） • Optics（CSS）

詳しいコード例は references/EXAMPLES.md を参照してください。

Slim テンプレート

基本的な規約

• Ruby 3 以降の構文を使用します（例：: を使ったキーワード引数）
• ビューのロジックは最小限にし、ヘルパーやパーシャルに切り出します
• アクションの周囲には必ずポリシーチェックを追加します（例：編集／削除リンク）
• インラインスタイルは使用しないでください
• 繰り返し使用するマークアップはパーシャルに切り出します（DRY 原則）
• キーワード引数を使って必ずローカル変数を渡します：render 'partial', user:, active: true

ヘルパーとパーシャル

ヘルパーを使うケース：

• 条件に応じてテキストやクラスが変わる単一要素
• データのフォーマット（日時、通貨）
• ステートレスなロジック
• 例：status_badge(status)

パーシャルを使うケース：

• 複数要素で構成される構造
• 再利用可能な UI コンポーネント
• コレクションのレンダリング
• 例：_form.html.slim、_user_card.html.slim

ルール： 単一要素にはヘルパーを使い、構造やレイアウトにはパーシャルを使います。

パーシャルの構成

app/views/
  resource_name/
    index.html.slim           # Main views
    _form.html.slim           # Forms (shared by new/edit)
    _resource_name.html.slim  # Individual item
  shared/
    _status_badge.html.slim   # Cross-feature components

よく使うパターン

-# Conditional classes
.card class=class_names('card--active': active, 'card--urgent': urgent)

-# Partial with locals
= render 'user_card', user:, show_actions: true

-# Collection rendering
= render partial: 'item', collection: @items

-# Conditional rendering
- if policy(@resource).update?
  = link_to 'Edit', edit_path(@resource)

Simple Form

Simple Form を必ず使用してください。 form_with や form_for は使用しないでください。

基本的なフォーム

モデルフォーム：

= simple_form_for @user do |f|
  = f.input :name
  = f.input :email, required: true
  
  .form__actions
    = link_to 'Cancel', :back, class: 'btn btn--outline'
    = f.submit 'Save', class: 'btn btn--primary'

非モデルフォーム（検索、フィルター、一括操作）：

= simple_form_for :search, url: search_path, method: :get do |f|
  = f.input :query
  = f.submit 'Search', class: 'btn btn--primary'

重要： :symbol フォームではパラメーターがネストされます：params.dig(:search, :query)

よく使う入力タイプ

タイプ	例
テキスト	= f.input :name
テキストエリア	= f.input :description, as: :text, input_html: { rows: 4 }
関連付け	= f.association :project, collection: @projects, prompt: 'Select...'
選択	= f.input :type, collection: @project_types, prompt: 'Select...'
真偽値	= f.input :active, as: :boolean
日付	= f.input :start_date, as: :date
非表示	= f.hidden_field :organization_id, value: current_user.organization_id

入力オプション

• placeholder: - プレースホルダーテキスト
• label: - カスタムラベル
• hint: - 入力欄の下に表示するヘルプテキスト
• required: true - 必須として設定
• disabled: true - 入力欄を無効化
• input_html: {} - 入力要素の HTML 属性
• wrapper_html: {} - ラッパー div の HTML 属性

コレクション

/ Basic collection
= f.input :category_id, collection: @categories

/ Custom label/value methods
= f.input :project_id, 
  collection: @projects,
  label_method: :name,
  value_method: :id,
  prompt: 'Select project...'

特殊なフォームパターン

一括操作フォーム：

= simple_form_for :bulk_action, url: bulk_path, method: :post, html: { id: 'bulk-form' } do |f|
  = f.button 'Approve Selected', class: 'btn btn--primary'

-# Checkboxes reference form
= check_box_tag 'entry_ids[]', entry.id, false, form: 'bulk-form'

外部送信ボタンを使うモーダルフォーム：

= simple_form_for @record, html: { id: 'modal-form' }, data: { turbo_frame: '_top' } do |f|
  = f.input :reason, as: :text, input_html: { rows: 3, required: true }

-# In modal footer
= button_tag 'Submit', type: 'submit', form: 'modal-form', class: 'btn btn--primary'

フォームオプション

• html: {} - フォーム要素の HTML 属性
• data: {} - データ属性（例：Turbo、Stimulus）
• url: - フォームの送信先 URL（:symbol フォームでは必須）
• method: - HTTP メソッド（:get、:post、:patch、:delete）

複雑なフォームの例は references/EXAMPLES.md を参照してください。

Stimulus コントローラー

Stimulus フレームワークを使用した JavaScript のインタラクションです。

コントローラーの構造

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["output", "input"]
  static values = { url: String, delay: Number }
  static classes = ["hidden", "active"]

  connect() {
    // Initialization when controller connects to DOM
  }

  disconnect() {
    // Cleanup when controller disconnects
  }

  action(event) {
    // Action methods called from HTML
  }
}

Slim での使用方法

.component data-controller="example" data-example-url-value="/api/endpoint"
  input data-example-target="input" data-action="input->example#search"
  .results data-example-target="output"

ベストプラクティス

• 動作ごとにコントローラーを 1 つ作成します（役割を絞り、組み合わせ可能にします）
• 設定にはデータ属性を使用します
• HTML ではコントローラー名をケバブケースにします
• コントローラーはシンプルでテスト可能な状態に保ちます
• disconnect() で後処理を行います（タイマー、リスナー）

コントローラーの完全な例は references/EXAMPLES.md を参照してください。

CSS と Optics

ガイドライン

• カスタム CSS は最小限にし、コンポーネントのスコープ内に限定します
• インラインスタイルは使用しないでください
• ユーティリティクラスの使用は強く推奨されません。代わりに BEM（Block Element Modifier）構造を使用してください。
• 条件付きクラスには class_names ヘルパーを使用します

よく使うパターン

/ Custom component with BEM
.time-entry.time-entry--running
  .time-entry__header
    h3.time-entry__title = entry.description
  .time-entry__body
    span.time-entry__duration = entry.duration

条件付きクラス

/ Using class_names helper
.card class=class_names(
  'card--active': @record.active?,
  'card--featured': @record.featured?
)

クイックリファレンス

フォームアクションのパターン：

.form__actions
  = link_to 'Cancel', :back, class: 'btn btn--outline'
  = f.submit 'Save', class: 'btn btn--primary'

空の状態：

- if @items.empty?
  = render 'shared/empty_state', title: 'No items', message: 'Create your first item.'

認可チェック：

- if policy(@resource).update?
  = link_to 'Edit', edit_path(@resource), class: 'btn'

Turbo の確認：

= button_to 'Delete', path, method: :delete, data: { turbo_confirm: 'Are you sure?' }