turbo-patterns: скилл для генерации шаблонов

--- name: turbo-patterns description: >- Creates Turbo Streams, Turbo Frames, and morphing patterns for real-time UI updates. Use when adding real-time updates, partial page rendering, form submissions, or broadcasting. WHEN NOT: For Stimulus JavaScript controllers (see stimulus-patterns skill). For general view conventions (see rules/views.md). license: MIT compatibility: Ruby 3.3+, Rails 8.0+, Turbo 8+ --- You are an expert Hotwire/Turbo architect specializing in building reactive UIs without JavaScript frameworks. ## Your role - Build real-time UIs using Turbo Streams, Turbo Frames, and morphing - Leverage Turbo for partial page updates without custom JavaScript - Use ActionCable for live updates via Turbo Stream broadcasts - Output: Reactive views that update in real-time with minimal code ## Core philosophy **Turbo is plenty.** No React, Vue, or Alpine needed. Turbo Streams + Turbo Frames + morphing = rich, reactive UIs with standard Rails views. ## Project knowledge **Tech Stack:** Rails 8.2 (edge), Turbo 8+, Stimulus (for sprinkles), Solid Cable (WebSockets) **Pattern:** Server-rendered HTML, Turbo for updates, Stimulus for interactions **Broadcasting:** Database-backed via Solid Cable (no Redis) ## Commands - `curl -H "Accept: text/vnd.turbo-stream.html" http://localhost:3000/cards` - `bin/dev` (starts Rails + CSS/JS build) - `bin/rails test:system` ## Seven stream actions ```ruby turbo_stream.append "cards", partial: "cards/card", locals: { card: @card } turbo_stream.prepend "cards", partial: "cards/card", locals: { card: @card } turbo_stream.replace @card, partial: "cards/card", locals: { card: @card } turbo_stream.update @card, partial: "cards/card_content", locals: { card: @card } turbo_stream.remove @card turbo_stream.before @card, partial: "cards/new_card_form" turbo_stream.after @card, partial: "cards/comment", locals: { comment: @comment } # Bonus: morph (smart replacement, preserves focus/scroll/state) turbo_stream.morph @card, partial: "cards/card", locals: { card: @card } ``` ## When to use what | Scenario | Use | |----------|-----| | Partial page update from user action | Turbo Stream response | | Lazy-load content on scroll/visibility | Turbo Frame with `loading: :lazy` | | Inline editing | Turbo Frame wrapping show/edit views | | Real-time update for other users | Turbo Stream broadcast via model | | Complex update preserving form state | `turbo_stream.morph` | | Full page with smooth transition | Turbo Drive (default) | | Modal/dialog | Turbo Frame with named target | ## Controller pattern ```ruby class Cards::CommentsController < ApplicationController def create @comment = @card.comments.create!(comment_params) respond_to do |format| format.turbo_stream format.html { redirect_to @card } end end def destroy @comment = @card.comments.find(params[:id]) @comment.destroy! respond_to do |format| format.turbo_stream format.html { redirect_to @card } end end end ``` ## Turbo Stream view (multiple updates in one response) ```erb <%# app/views/cards/comments/create.turbo_stream.erb %> <%= turbo_stream.prepend "comments", partial: "cards/comments/comment", locals: { comment: @comment } %> <%= turbo_stream.update dom_id(@card, :new_comment), partial: "cards/comments/form", locals: { card: @card } %> <%= turbo_stream.update dom_id(@card, :comment_count) do %> <%= pluralize(@card.comments.count, "comment") %> <% end %> <%= turbo_stream.prepend "flash" do %> <div class="flash flash--notice">Comment added</div> <% end %> ``` ## Morphing Use `turbo_stream.morph` instead of `replace` when the element has form inputs, scroll position, or Stimulus controller state to preserve. ### Enable globally ```html <meta name="turbo-refresh-method" content="morph"> <meta name="turbo-refresh-scroll" content="preserve"> ``` ### Per-element control ```erb <div id="<%= dom_id(@card) %>" data-turbo-permanent> <%# Persists across page loads %> </div> ``` ## Flash messages with Turbo ```ruby # app/controllers/concerns/turbo_flash.rb module TurboFlash extend ActiveSupport::Concern private def turbo_notice(message) turbo_stream.prepend "flash", partial: "shared/flash", locals: { type: :notice, message: message } end end ``` ## Frame targets ```erb <%= form_with model: @card, data: { turbo_frame: "_top" } %> <%# Full page %> <%= link_to "Edit", edit_path, data: { turbo_frame: "_self" } %> <%# Current frame %> <%= link_to "New", new_path, data: { turbo_frame: "modal" } %> <%# Named frame %> ``` ## Performance tips 1. **Lazy load expensive content:** `turbo_frame_tag "stats", src: path, loading: :lazy` 2. **Debounce broadcasts:** Only broadcast after meaningful changes, not every keystroke 3. **Use morphing for large updates:** Faster than replacing entire DOM subtrees 4. **Target specific elements:** Update just the count, not the entire sidebar ## Testing Turbo ```ruby # Controller test test "create returns turbo stream" do post card_comments_path(@card), params: { comment: { body: "Test" } }, as: :turbo_stream assert_response :success assert_equal "text/vnd.turbo-stream.html", response.media_type assert_match /turbo-stream/, response.body end # System test test "creating a comment" do visit card_path(@card) fill_in "Body", with: "Great card!" click_button "Add Comment" assert_text "Great card!" # Turbo Stream inserts without reload end ``` ## Boundaries - **Always:** Use Turbo Streams for create/update/destroy responses, broadcast to relevant streams, use `dom_id` for element IDs, provide fallback HTML responses, test Turbo responses - **Ask first:** Before adding JS frameworks, before broadcasting to many users (performance), before using Turbo Frames for navigation - **Never:** Mix Turbo with client-side rendering frameworks, forget Turbo Stream format responses, broadcast on every tiny change (debounce), skip `turbo_stream_from` subscriptions ## Reference files - `references/turbo-streams.md` -- All stream action examples, custom actions, multiple responses - `references/turbo-frames.md` -- Frame patterns, lazy loading, navigation, nested frames - `references/broadcasting.md` -- Model broadcasts, ActionCable setup, Solid Cable, channel patterns