ariadna 1.2.0 → 1.2.2

data/data/guides/frontend.md

@@ -2,7 +2,7 @@
 
 **View Layer Conventions for Rails Applications**
 
-This guide covers the frontend and view layer patterns used in Rails applications. Currently focused on the Presenter Pattern, with future sections planned for Turbo, Stimulus, and view templates.
+This guide covers the frontend and view layer patterns used in Rails applications: the Presenter Pattern, Turbo (Drive, Frames, Streams), Stimulus controllers, and view template conventions.
 
 **Related guides:**
 - [Backend Patterns](backend.md) — Architecture, models, controllers, jobs, style guide
@@ -22,9 +22,27 @@ This guide covers the frontend and view layer patterns used in Rails application
   - [1.7 View Usage](#17-view-usage)
   - [1.8 Testing Presenters](#18-testing-presenters)
   - [1.9 Real Examples](#19-real-examples)
-- [2. Turbo Streams & Turbo Frames](#2-turbo-streams--turbo-frames) *(planned)*
-- [3. Stimulus Controllers](#3-stimulus-controllers) *(planned)*
-- [4. View Templates & Partials](#4-view-templates--partials) *(planned)*
+- [2. Turbo Streams & Turbo Frames](#2-turbo-streams--turbo-frames)
+  - [2.1 Turbo Drive Essentials](#21-turbo-drive-essentials)
+  - [2.2 Turbo Frames](#22-turbo-frames)
+  - [2.3 Turbo Streams](#23-turbo-streams)
+  - [2.4 Optimistic UI](#24-optimistic-ui)
+  - [2.5 HTTP Response Conventions](#25-http-response-conventions)
+  - [2.6 View Transitions](#26-view-transitions)
+- [3. Stimulus Controllers](#3-stimulus-controllers)
+  - [3.1 Controller Architecture](#31-controller-architecture)
+  - [3.2 Lifecycle](#32-lifecycle)
+  - [3.3 Values (Reactive State)](#33-values-reactive-state)
+  - [3.4 Targets (DOM References)](#34-targets-dom-references)
+  - [3.5 Outlets (Controller-to-Controller Communication)](#35-outlets-controller-to-controller-communication)
+  - [3.6 Actions & Parameters](#36-actions--parameters)
+  - [3.7 Common Patterns](#37-common-patterns)
+- [4. View Templates & Partials](#4-view-templates--partials)
+  - [4.1 ERB Conventions](#41-erb-conventions)
+  - [4.2 Partial Extraction Rules](#42-partial-extraction-rules)
+  - [4.3 Turbo Frame Wrapping in Views](#43-turbo-frame-wrapping-in-views)
+  - [4.4 Template-Based DOM Patterns](#44-template-based-dom-patterns)
+  - [4.5 Cache-Safe Views](#45-cache-safe-views)
 
 ---
 
@@ -423,22 +441,1039 @@ Presenter pattern:
 
 # 2. Turbo Streams & Turbo Frames
 
-*Section planned. Will cover Turbo Stream actions, Turbo Frame conventions, broadcast patterns, and real-time update strategies.*
+## 2.1 Turbo Drive Essentials
+
+**Turbo Drive** intercepts link clicks and form submissions, replacing full page loads with fetch requests and DOM swaps. These lifecycle events are the integration points.
+
+**`turbo:submit-start`** / **`turbo:submit-end`** — Form activity indicators:
+
+```javascript
+document.addEventListener("turbo:submit-start", (event) => {
+  const btn = event.target.querySelector("[type=submit]")
+  btn.disabled = true
+  btn.textContent = "Saving..."
+})
+```
+
+**`turbo:before-render`** — Intercept rendering. **Pausable** via `preventDefault()` + `detail.resume()`. Always guard against `data-turbo-preview` to skip animations on cached snapshots:
+
+```javascript
+document.addEventListener("turbo:before-render", (event) => {
+  if (document.documentElement.hasAttribute("data-turbo-preview")) return
+  event.preventDefault()
+  document.documentElement.classList.add("page-leaving")
+  document.documentElement.addEventListener("animationend", () => event.detail.resume(), { once: true })
+})
+```
+
+**`turbo:before-cache`** — Clean transient UI before Turbo snapshots the page. Reset widgets, close dropdowns, clear flash messages:
+
+```javascript
+document.addEventListener("turbo:before-cache", () => {
+  document.querySelectorAll("[data-dropdown-open]").forEach((el) => el.removeAttribute("data-dropdown-open"))
+  document.querySelectorAll(".flash-message").forEach((el) => el.remove())
+})
+```
+
+**`turbo:load`** — Page fully loaded and rendered. Equivalent to `DOMContentLoaded` for Turbo navigations.
+
+**Progress bar** — Reuse Turbo's built-in bar; style with CSS:
+
+```css
+.turbo-progress-bar { height: 3px; background-color: var(--color-accent); }
+```
+
+## 2.2 Turbo Frames
+
+A **Turbo Frame** (`<turbo-frame>`) scopes navigation to a region of the page. Only the matching frame swaps on navigation.
+
+**Wrapping conventions** — Scope frame boundaries to the **smallest rerenderable unit**. Use `dom_id` for IDs:
+
+```erb
+<turbo-frame id="<%= dom_id(card) %>">
+  <%= render "cards/card", card: card %>
+</turbo-frame>
+```
+
+**Lazy loading** — Set `loading="lazy"` with `src` to defer until the frame enters the viewport:
+
+```erb
+<turbo-frame id="activity_feed" src="<%= activity_feed_path %>" loading="lazy">
+  <p class="loading-placeholder">Loading activity...</p>
+</turbo-frame>
+```
+
+**Tabbed navigation** — Drive a content frame from nav links with `data-turbo-frame` and `data-turbo-action="advance"` for history:
+
+```erb
+<a href="<%= project_tab_path(@project, tab) %>"
+   data-turbo-frame="tab_content"
+   data-turbo-action="advance">
+  <%= tab.titlecase %>
+</a>
+
+<turbo-frame id="tab_content"><%= yield %></turbo-frame>
+```
+
+Update active state on **`turbo:frame-load`** (NOT `turbo:click` — click fires before the response):
+
+```javascript
+document.addEventListener("turbo:frame-load", (event) => {
+  if (event.target.id !== "tab_content") return
+  document.querySelectorAll("[data-turbo-frame='tab_content']").forEach((link) => {
+    link.classList.toggle("active", link.href === event.target.src)
+  })
+})
+```
+
+**Pagination with history** — Add `data-turbo-action="advance"` to pagination links so page numbers push to browser history.
+
+**Forms in frames** — HTTP status determines behavior:
+- **422** — Turbo swaps the response into the frame (validation errors rendered in place)
+- **303** — Turbo follows the redirect
+
+```ruby
+def create
+  if @card.save
+    redirect_to @card, status: :see_other
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+**External form controls** — Use the HTML `form` attribute on inputs outside the `<form>` tag:
+
+```erb
+<form id="search_form" action="<%= search_path %>">
+  <input type="text" name="query">
+</form>
+<select name="category" form="search_form">...</select>
+```
+
+**Loading states** — Style with the `[busy]` attribute Turbo adds automatically:
+
+```css
+turbo-frame[busy] { opacity: 0.5; pointer-events: none; }
+```
+
+## 2.3 Turbo Streams
+
+**Turbo Streams** deliver targeted DOM updates via `<turbo-stream>` elements.
+
+**Default actions** — Prefer the 8 built-in actions before writing custom ones: `append`, `prepend`, `replace`, `update`, `remove`, `before`, `after`, `refresh` (Turbo 8 morph).
+
+**Custom stream actions** — Register on `StreamActions`. Inside the function, **`this`** is the `<turbo-stream>` element:
+
+```javascript
+import { StreamActions } from "@hotwired/turbo"
+
+StreamActions.flash = function () {
+  const flash = document.createElement("div")
+  flash.className = `flash flash--${this.getAttribute("type") || "notice"}`
+  flash.textContent = this.getAttribute("message")
+  document.getElementById("flash_container").appendChild(flash)
+}
+```
+
+**Inline stream tags** — A `<turbo-stream>` appended to the DOM **executes immediately and self-removes**. Store in a `<template>` to prevent premature execution; clone + modify + append:
+
+```html
+<template id="optimistic_card_template">
+  <turbo-stream action="append" target="cards">
+    <template>
+      <div id="card_PLACEHOLDER" class="card card--optimistic">
+        <span data-title></span>
+      </div>
+    </template>
+  </turbo-stream>
+</template>
+```
+
+```javascript
+function appendOptimisticCard(id, title) {
+  const stream = document.getElementById("optimistic_card_template").content.cloneNode(true)
+  stream.querySelector("[id^='card_']").id = `card_${id}`
+  stream.querySelector("[data-title]").textContent = title
+  document.body.appendChild(stream)
+}
+```
+
+**Broadcast patterns** — Use `after_create_commit` callbacks with broadcast helpers:
+
+```ruby
+class Card < ApplicationRecord
+  after_create_commit -> { broadcast_append_to board, target: "cards" }
+  after_update_commit -> { broadcast_replace_to board }
+  after_destroy_commit -> { broadcast_remove_to board }
+end
+```
+
+**Turbo 8 morphing** — `turbo_stream.refresh` triggers a full-page morph reconciling the DOM with the server. Use after optimistic UI:
+
+```ruby
+format.turbo_stream { render turbo_stream: turbo_stream.refresh }
+```
+
+## 2.4 Optimistic UI
+
+Render the expected outcome on the client before server confirmation, then reconcile.
+
+**Pattern:** Store markup in a `<template>` containing `<turbo-stream>`. On `turbo:submit-start`, clone and append. Server responds with `turbo_stream.refresh` to correct discrepancies.
+
+```javascript
+document.addEventListener("turbo:submit-start", (event) => {
+  if (event.target.id !== "new_card_form") return
+  const title = event.target.querySelector("[name='card[title]']").value
+  appendOptimisticCard(generateULID(), title)
+  event.target.reset()
+})
+```
+
+**Client-side ULID generation** for optimistic record IDs (time-ordered, collision-resistant):
+
+```javascript
+function generateULID() {
+  const time = Date.now().toString(36).padStart(10, "0")
+  const rand = Array.from(crypto.getRandomValues(new Uint8Array(10)))
+    .map((b) => b.toString(36).padStart(2, "0")).join("").slice(0, 16)
+  return (time + rand).toUpperCase()
+}
+```
+
+**Reconciliation** — Turbo 8 diffs server-rendered DOM against client state. Matching optimistic elements are preserved; mismatches are corrected.
+
+## 2.5 HTTP Response Conventions
+
+- **422 Unprocessable Entity** — Validation failures. Turbo re-renders the form frame with errors.
+- **303 See Other** — Successful submissions. Turbo follows redirect with GET.
+- **Never return 200** for form submissions expecting a redirect.
+- **Always use 303** (not 301/302) — guarantees GET follow-up, prevents resubmission.
+
+```ruby
+def update
+  if @card.update(card_params)
+    redirect_to @card, status: :see_other
+  else
+    render :edit, status: :unprocessable_entity
+  end
+end
+```
+
+## 2.6 View Transitions
+
+Use the **View Transitions API** with Turbo for animated page transitions. Enable globally:
+
+```erb
+<meta name="view-transition" content="same-origin">
+```
+
+```css
+::view-transition-old(root) { animation: fade-out 150ms ease-in; }
+::view-transition-new(root) { animation: fade-in 150ms ease-out; }
+```
+
+**Direction-aware transitions** — Capture direction in `turbo:click`, apply in `turbo:before-render`, clean up in `turbo:load`:
+
+```javascript
+let direction = "forward"
+
+document.addEventListener("turbo:click", (event) => {
+  direction = event.target.closest("[data-direction]")?.dataset.direction || "forward"
+})
+
+document.addEventListener("turbo:before-render", (event) => {
+  if (document.documentElement.hasAttribute("data-turbo-preview")) return
+  document.documentElement.dataset.transitionDirection = direction
+})
+
+document.addEventListener("turbo:load", () => {
+  delete document.documentElement.dataset.transitionDirection
+})
+```
+
+```css
+[data-transition-direction="forward"]::view-transition-old(root)  { animation: slide-out-left 200ms ease-in; }
+[data-transition-direction="forward"]::view-transition-new(root)  { animation: slide-in-right 200ms ease-out; }
+[data-transition-direction="backward"]::view-transition-old(root) { animation: slide-out-right 200ms ease-in; }
+[data-transition-direction="backward"]::view-transition-new(root) { animation: slide-in-left 200ms ease-out; }
+```
+
+### Summary
+
+- **Turbo Drive events** — `turbo:before-cache` for cleanup, `turbo:before-render` for animations (pausable), guard against `data-turbo-preview`
+- **Frame boundaries** match the smallest rerenderable unit; use `dom_id` for IDs
+- **Lazy frames** defer with `loading="lazy"` + `src`; post-load setup via `turbo:frame-load`
+- **Tabs and pagination** use `data-turbo-frame` + `data-turbo-action="advance"` for history
+- **HTTP status codes** — 422 for errors, 303 for redirects, never 200 for redirect-expecting forms
+- **Prefer built-in stream actions** before custom; register custom actions on `StreamActions`
+- **Inline streams** execute on DOM insertion and self-remove; store in `<template>` to control timing
+- **Optimistic UI** clones stream templates on `turbo:submit-start`, uses ULIDs, reconciles via morph
+- **Broadcasts** use `after_create_commit` + `broadcast_append_to` / `broadcast_replace_to`
+- **View Transitions** integrate through `turbo:before-render` with direction-aware CSS
 
 ---
 
 # 3. Stimulus Controllers
 
-*Section planned. Will cover Stimulus controller conventions, naming patterns, data attribute usage, and common controller patterns.*
+## 3.1 Controller Architecture
+
+**File naming** follows the Stimulus convention: `app/javascript/controllers/{name}_controller.js`. Multi-word names use kebab-case in filenames and camelCase in class names:
+
+| File | Class | Identifier |
+|------|-------|------------|
+| `upload_preview_controller.js` | `UploadPreviewController` | `upload-preview` |
+| `broadcast_channel_controller.js` | `BroadcastChannelController` | `broadcast-channel` |
+| `media_player_controller.js` | `MediaPlayerController` | `media-player` |
+
+**Registration** is automatic via `esbuild` or `importmap` conventions. Controllers placed in `app/javascript/controllers/` are auto-discovered and registered. No manual `application.register()` calls needed.
+
+**Contract-first declaration** means every controller declares its full interface at the top, before any methods. This makes controllers self-documenting and lets agents understand the API without reading implementation:
+
+```javascript
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values  = { url: String, refreshInterval: Number, active: Boolean }
+  static targets = ["output", "spinner", "emptyState"]
+  static outlets = ["filter", "notification"]
+  static classes = ["loading", "hidden"]
+
+  // Lifecycle methods
+  connect() { }
+  disconnect() { }
+
+  // Action methods
+  refresh() { }
+  toggle() { }
+}
+```
+
+**Single-purpose controllers.** Each controller owns one behavior. A `clipboard_controller.js` copies text. A `toggle_controller.js` shows/hides elements. Compose multiple controllers on the same element rather than building one large controller:
+
+```html
+<div data-controller="clipboard toggle tooltip"
+     data-clipboard-text-value="https://example.com/share/abc123"
+     data-toggle-class="hidden">
+  <button data-action="clipboard#copy toggle#toggle">Copy Link</button>
+  <span data-toggle-target="content" class="hidden">Copied!</span>
+</div>
+```
+
+## 3.2 Lifecycle
+
+**Symmetric setup and teardown.** Every resource acquired in `connect()` must be released in `disconnect()`. Turbo navigations and morphs trigger these repeatedly, so leaks accumulate fast:
+
+```javascript
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = { channel: String }
+
+  connect() {
+    this.broadcast = new BroadcastChannel(this.channelValue)
+    this.broadcast.onmessage = this.handleMessage.bind(this)
+
+    this.resizeObserver = new ResizeObserver(this.handleResize.bind(this))
+    this.resizeObserver.observe(this.element)
+
+    this.refreshTimer = setInterval(() => this.refresh(), 30000)
+  }
+
+  disconnect() {
+    this.broadcast.close()
+
+    this.resizeObserver.disconnect()
+
+    clearInterval(this.refreshTimer)
+  }
+}
+```
+
+**Common teardown checklist:**
+
+| Resource | Setup | Teardown |
+|----------|-------|----------|
+| BroadcastChannel | `new BroadcastChannel()` | `.close()` |
+| Blob URL | `URL.createObjectURL()` | `URL.revokeObjectURL()` |
+| Third-party player | `WaveSurfer.create()` | `.destroy()` |
+| Timer | `setInterval()` / `setTimeout()` | `clearInterval()` / `clearTimeout()` |
+| Observer | `.observe()` | `.disconnect()` |
+| EventListener (window/document) | `addEventListener()` | `removeEventListener()` |
+
+**Guard `valueChanged` callbacks.** Value callbacks can fire before `connect()` completes, which means targets or instance properties may not exist yet. Always guard:
+
+```javascript
+export default class extends Controller {
+  static values  = { url: String }
+  static targets = ["frame"]
+
+  urlValueChanged(url) {
+    // Guard — target may not be connected yet
+    this.frameTarget?.src = url
+  }
+}
+```
+
+Alternatively, use an early return:
+
+```javascript
+urlValueChanged(url) {
+  if (!this.hasFrameTarget) return
+  this.frameTarget.src = url
+}
+```
+
+## 3.3 Values (Reactive State)
+
+**Declaration** uses `static values` with type constructors. Stimulus handles serialization, type coercion, and default values:
+
+```javascript
+export default class extends Controller {
+  static values = {
+    url:       String,     // default: ""
+    count:     Number,     // default: 0
+    active:    Boolean,    // default: false
+    filters:   Object,     // default: {}
+    items:     Array,      // default: []
+  }
+}
+```
+
+```html
+<div data-controller="dashboard"
+     data-dashboard-url-value="/api/stats"
+     data-dashboard-count-value="42"
+     data-dashboard-active-value="true"
+     data-dashboard-filters-value='{"status":"open"}'>
+</div>
+```
+
+**React with `{name}ValueChanged` callbacks.** These fire whenever the value changes, including the initial set from HTML attributes:
+
+```javascript
+export default class extends Controller {
+  static values  = { page: Number }
+  static targets = ["list", "counter"]
+
+  pageValueChanged(current, previous) {
+    if (previous !== undefined) {
+      this.fetchPage(current)
+    }
+    this.counterTarget.textContent = `Page ${current}`
+  }
+
+  next() {
+    this.pageValue++   // Triggers pageValueChanged automatically
+  }
+}
+```
+
+**Bridge third-party libraries through value callbacks.** The value becomes the single source of truth. The callback translates it into library-specific API calls:
+
+```javascript
+import { Controller } from "@hotwired/stimulus"
+import Chart from "chart.js/auto"
+
+export default class extends Controller {
+  static values  = { type: String, data: Object, options: Object }
+  static targets = ["canvas"]
+
+  connect() {
+    this.chart = new Chart(this.canvasTarget, {
+      type: this.typeValue,
+      data: this.dataValue,
+      options: this.optionsValue
+    })
+  }
+
+  dataValueChanged(data) {
+    if (!this.chart) return
+    this.chart.data = data
+    this.chart.update()
+  }
+
+  optionsValueChanged(options) {
+    if (!this.chart) return
+    this.chart.options = options
+    this.chart.update()
+  }
+
+  disconnect() {
+    this.chart.destroy()
+  }
+}
+```
+
+**Values as the single source of truth.** Never duplicate state in DOM attributes, instance variables, or dataset entries alongside values. If a controller needs state, declare a value. Read state from `this.{name}Value`, mutate via `this.{name}Value = x`, and react in the callback. This keeps the data flow unidirectional and predictable.
+
+## 3.4 Targets (DOM References)
+
+**Declaration** registers named references to child elements:
+
+```javascript
+export default class extends Controller {
+  static targets = ["input", "output", "submitButton"]
+}
+```
+
+```html
+<form data-controller="search">
+  <input data-search-target="input" type="text">
+  <div data-search-target="output"></div>
+  <button data-search-target="submitButton">Search</button>
+</form>
+```
+
+Access via `this.inputTarget` (first match), `this.inputTargets` (all matches), and `this.hasInputTarget` (existence check).
+
+**Target callbacks** fire when the DOM changes. These are essential for Turbo Stream integration — when elements are appended or removed, the controller reacts automatically:
+
+```javascript
+export default class extends Controller {
+  static targets = ["item", "counter", "emptyState"]
+
+  itemTargetConnected(element) {
+    this.updateCount()
+    element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 200 })
+  }
+
+  itemTargetDisconnected(element) {
+    this.updateCount()
+  }
+
+  updateCount() {
+    this.counterTarget.textContent = this.itemTargets.length
+    this.emptyStateTarget.hidden = this.itemTargets.length > 0
+  }
+}
+```
+
+**Keep target callbacks idempotent.** Turbo morphs and reconnections can trigger `TargetConnected` multiple times for the same element. Avoid additive side effects:
+
+```javascript
+// Bad — adds duplicate listeners on reconnect
+itemTargetConnected(element) {
+  element.addEventListener("click", this.handleClick)
+}
+
+// Good — safe across repeated connect/disconnect cycles
+itemTargetConnected(element) {
+  element.handleClick ||= this.handleClick.bind(this)
+  element.removeEventListener("click", element.handleClick)
+  element.addEventListener("click", element.handleClick)
+}
+```
+
+**Derive computed state from targets** rather than tracking counts or flags in separate values:
+
+```javascript
+get isEmpty() {
+  return this.itemTargets.length === 0
+}
+
+get selectedItems() {
+  return this.itemTargets.filter(el => el.dataset.selected === "true")
+}
+
+get selectedCount() {
+  return this.selectedItems.length
+}
+```
+
+## 3.5 Outlets (Controller-to-Controller Communication)
+
+**Outlets** let one controller access another controller's instance directly. Declare with `static outlets`:
+
+```javascript
+// dashboard_controller.js
+export default class extends Controller {
+  static outlets = ["chart", "filter"]
+
+  apply() {
+    const filters = this.filterOutlet.currentFilters
+    this.chartOutlets.forEach(chart => chart.reload(filters))
+  }
+}
+```
+
+```html
+<div data-controller="dashboard"
+     data-dashboard-chart-outlet=".chart-widget"
+     data-dashboard-filter-outlet="#main-filter">
+
+  <div id="main-filter" data-controller="filter">...</div>
+  <div class="chart-widget" data-controller="chart">...</div>
+  <div class="chart-widget" data-controller="chart">...</div>
+</div>
+```
+
+**Access patterns:**
+
+| Accessor | Returns | Throws if missing |
+|----------|---------|-------------------|
+| `this.chartOutlet` | First matching controller | Yes |
+| `this.chartOutlets` | Array of all matching controllers | No (empty array) |
+| `this.hasChartOutlet` | Boolean | No |
+
+**Outlet callbacks** notify when outlets connect or disconnect:
+
+```javascript
+export default class extends Controller {
+  static outlets = ["player"]
+
+  playerOutletConnected(controller, element) {
+    controller.mute()  // Direct method call on connected controller
+  }
+
+  playerOutletDisconnected(controller, element) {
+    // Cleanup references
+  }
+}
+```
+
+**Prefer outlets** over `this.application.getControllerForElementAndIdentifier()` or custom events for direct controller-to-controller communication. Outlets are declarative, observable, and automatically managed by Stimulus.
+
+## 3.6 Actions & Parameters
+
+**Action parameters** pass data from HTML to action methods without manual `dataset` parsing. Declare parameters with `data-{controller}-{param}-param`:
+
+```html
+<div data-controller="cart">
+  <button data-action="cart#add"
+          data-cart-id-param="42"
+          data-cart-name-param="Widget"
+          data-cart-price-param="19.99">
+    Add to Cart
+  </button>
+</div>
+```
+
+```javascript
+export default class extends Controller {
+  add({ params: { id, name, price } }) {
+    // id = 42 (Number), name = "Widget" (String), price = 19.99 (Number)
+    // Types are automatically inferred from the value
+    this.addItem(id, name, price)
+  }
+}
+```
+
+**Keyboard filters** let you bind actions to specific key combinations:
+
+```html
+<div data-controller="editor">
+  <textarea data-action="keydown.ctrl+s->editor#save
+                         keydown.meta+s->editor#save
+                         keydown.esc->editor#cancel
+                         keydown.ctrl+enter->editor#submit">
+  </textarea>
+</div>
+```
+
+**Supported keyboard filters:**
+
+| Category | Filters |
+|----------|---------|
+| Modifiers | `ctrl`, `alt`, `shift`, `meta` |
+| Navigation | `enter`, `tab`, `esc`, `space`, `up`, `down`, `left`, `right` |
+| Letters | `a` through `z` |
+| Numbers | `0` through `9` |
+| Combinations | `ctrl+s`, `shift+enter`, `meta+k`, `ctrl+shift+p` |
+
+**Non-focusable elements** need `tabindex="0"` to receive keyboard events:
+
+```html
+<div data-controller="shortcuts"
+     data-action="keydown.ctrl+z->shortcuts#undo"
+     tabindex="0">
+  <!-- Content that needs keyboard shortcuts -->
+</div>
+```
+
+## 3.7 Common Patterns
+
+### Image Upload Preview
+
+Use `URL.createObjectURL()` for instant client-side previews. Always revoke the URL after the image loads to free memory:
+
+```javascript
+export default class extends Controller {
+  static targets = ["input", "preview"]
+
+  preview() {
+    const file = this.inputTarget.files[0]
+    if (!file) return
+
+    const url = URL.createObjectURL(file)
+    this.previewTarget.src = url
+    this.previewTarget.onload = () => URL.revokeObjectURL(url)
+    this.previewTarget.hidden = false
+  }
+}
+```
+
+```html
+<div data-controller="upload-preview">
+  <input type="file" accept="image/*"
+         data-upload-preview-target="input"
+         data-action="change->upload-preview#preview">
+  <img data-upload-preview-target="preview" hidden>
+</div>
+```
+
+### Inter-Tab Communication
+
+**BroadcastChannel** API enables communication across browser tabs. Create in `connect()`, close in `disconnect()`, and scope channels by purpose:
+
+```javascript
+export default class extends Controller {
+  static values = { channel: { type: String, default: "notifications" } }
+
+  connect() {
+    this.channel = new BroadcastChannel(this.channelValue)
+    this.channel.onmessage = this.handleMessage.bind(this)
+  }
+
+  handleMessage({ data }) {
+    if (data.type === "logout") {
+      window.location.href = "/session/new"
+    }
+  }
+
+  broadcast(type, payload = {}) {
+    this.channel.postMessage({ type, ...payload })
+  }
+
+  disconnect() {
+    this.channel.close()
+  }
+}
+```
+
+### Intersection Observer
+
+Use `stimulus-use` `useIntersection` for viewport-based behavior like lazy loading or picture-in-picture triggers:
+
+```javascript
+import { Controller } from "@hotwired/stimulus"
+import { useIntersection } from "stimulus-use"
+
+export default class extends Controller {
+  static values = { loaded: Boolean }
+
+  connect() {
+    useIntersection(this, { threshold: 0.25 })
+  }
+
+  appear() {
+    if (this.loadedValue) return
+    this.loadedValue = true
+    this.element.src = this.element.dataset.lazySrc
+  }
+}
+```
+
+### MutationObserver
+
+Watch DOM attribute changes for reactivity. Useful for observing Turbo Frame `busy` attribute changes:
+
+```javascript
+export default class extends Controller {
+  static targets = ["frame", "spinner"]
+
+  connect() {
+    this.observer = new MutationObserver(this.handleMutation.bind(this))
+    this.observer.observe(this.frameTarget, { attributes: true, attributeFilter: ["busy"] })
+  }
+
+  handleMutation(mutations) {
+    const isBusy = this.frameTarget.hasAttribute("busy")
+    this.spinnerTarget.hidden = !isBusy
+  }
+
+  disconnect() {
+    this.observer.disconnect()
+  }
+}
+```
+
+### Feature Detection
+
+Always check browser API availability before exposing functionality. Hide or disable UI that depends on unsupported APIs:
+
+```javascript
+export default class extends Controller {
+  static targets = ["pipButton", "shareButton"]
+  static classes = ["unsupported"]
+
+  connect() {
+    if (!document.pictureInPictureEnabled) {
+      this.pipButtonTarget.hidden = true
+    }
+
+    if (!navigator.share) {
+      this.shareButtonTarget.hidden = true
+    }
+
+    if (!("mediaSession" in navigator)) {
+      this.element.classList.add(this.unsupportedClass)
+    }
+  }
+}
+```
+
+## Summary
+
+Stimulus controller conventions:
+
+- **Contract-first** — declare `static values`, `targets`, `outlets`, `classes` before any methods
+- **Single-purpose** — one behavior per controller, compose via multiple `data-controller` bindings
+- **Symmetric lifecycle** — every `connect()` setup has a matching `disconnect()` teardown
+- **Guard value callbacks** — use optional chaining or `hasTarget` checks since callbacks fire before `connect()`
+- **Values as single source of truth** — bridge third-party libraries through `{name}ValueChanged` callbacks
+- **Target callbacks for Turbo** — use `TargetConnected` / `TargetDisconnected` to react to DOM changes from Turbo Streams
+- **Outlets over events** — prefer declared outlets for direct controller communication
+- **Action parameters over dataset** — use `data-{controller}-{param}-param` to pass typed data to actions
+- **Feature detection** — check API availability before exposing UI that depends on browser capabilities
+- **Idempotent callbacks** — target and outlet callbacks must be safe across repeated connect/disconnect cycles
 
 ---
 
 # 4. View Templates & Partials
 
-*Section planned. Will cover ERB template conventions, partial extraction rules, layout patterns, and component-like partial usage.*
+## 4.1 ERB Conventions
+
+**Templates are rendering surfaces, not logic containers.** Keep them thin by delegating decisions to presenters or model methods. A template should read like a layout blueprint: structure and data slots, nothing more.
+
+**Rules:**
+- No conditionals deeper than one level in a template
+- No query calls (`where`, `find`, `count`) in ERB — use presenters
+- Use `content_for` to inject section-specific content into layouts
+- Prefer `tag.div` helpers inside presenters over inline ERB for complex HTML
+
+### `content_for` for Section-Specific Content
+
+Use `content_for` to push page-specific content into layout slots:
+
+```erb
+<%# app/views/messages/show.html.erb %>
+<% content_for :title, @message.subject %>
+<% content_for :head do %>
+  <%= javascript_include_tag "trix" %>
+<% end %>
+
+<div class="message">
+  <%= render partial: "message", locals: { message: @message } %>
+</div>
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<head>
+  <title><%= content_for(:title) || "App" %></title>
+  <%= yield :head %>
+</head>
+```
+
+### Delegating Logic to Presenters
+
+When a template starts accumulating conditionals, extract them:
+
+```erb
+<%# Bad — logic in template %>
+<% if user.avatar.attached? && user.avatar.variable? %>
+  <%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %>
+<% else %>
+  <%= image_tag "default_avatar.png" %>
+<% end %>
+
+<%# Good — delegate to presenter %>
+<%= presenter.avatar_tag %>
+```
+
+## 4.2 Partial Extraction Rules
+
+**Extract a partial when:** the same markup appears in 2+ templates, or you identify a clear UI component boundary (card, form group, nav item). A partial is the smallest reusable rendering unit.
+
+### Naming and Organization
+
+- Name with a leading underscore: `_card.html.erb`
+- Place cross-controller partials in `app/views/shared/`: `shared/_flash.html.erb`
+- Name partials after the UI concept, not the model: `_card.html.erb`, not `_message_display.html.erb`
+
+### Pass Data Explicitly
+
+**Never rely on instance variables inside partials.** Always pass data via `locals:`:
+
+```erb
+<%# Good — explicit locals %>
+<%= render partial: "messages/card", locals: { message: message, show_actions: true } %>
+
+<%# Also good — short form for collections %>
+<%= render partial: "messages/message", collection: @messages, as: :message %>
+
+<%# Bad — instance variable dependency %>
+<%= render partial: "messages/card" %>
+<%# partial internally references @message — fragile and implicit %>
+```
+
+### Cross-Controller Partials
+
+For UI components shared across controllers, use the `shared/` directory:
+
+```erb
+<%# From any controller %>
+<%= render partial: "shared/empty_state", locals: { message: "No results found", icon: "search" } %>
+<%= render partial: "shared/pagination", locals: { pagy: @pagy } %>
+```
+
+## 4.3 Turbo Frame Wrapping in Views
+
+**Wrap the rerenderable unit, not the entire page.** A Turbo Frame defines the boundary of what gets swapped on navigation or form submission. Frame IDs must match between the source page and the server response.
+
+### Frame ID Conventions
+
+Use `dom_id` for consistent, collision-free frame and target IDs:
+
+```erb
+<%# app/views/messages/show.html.erb %>
+<%= turbo_frame_tag dom_id(message) do %>
+  <h2><%= message.subject %></h2>
+  <p><%= message.body %></p>
+  <%= link_to "Edit", edit_message_path(message) %>
+<% end %>
+
+<%# app/views/messages/edit.html.erb %>
+<%= turbo_frame_tag dom_id(message) do %>
+  <%= render "form", message: message %>
+<% end %>
+```
+
+The frame IDs match (`message_123`), so clicking "Edit" swaps only the frame content.
+
+### Lazy-Loaded Frames
+
+Use the `src` attribute to load frame content on demand:
+
+```erb
+<%= turbo_frame_tag "comments", src: message_comments_path(message), loading: :lazy do %>
+  <p>Loading comments...</p>
+<% end %>
+```
+
+The frame renders placeholder content immediately, then fetches and replaces it when the frame enters the viewport.
+
+## 4.4 Template-Based DOM Patterns
+
+**Store Turbo Stream markup in `<template>` elements** to prevent premature execution by the browser. This is essential for optimistic UI patterns where you prepare stream actions in the DOM and dispatch them from Stimulus controllers.
+
+### Clone-and-Append Pattern
+
+```html
+<%# Embed a hidden template in the page %>
+<template data-optimistic-stream>
+  <turbo-stream action="append" target="messages">
+    <template>
+      <div class="message message--pending" id="pending_message">
+        <p data-placeholder>Sending...</p>
+      </div>
+    </template>
+  </turbo-stream>
+</template>
+```
+
+```javascript
+// app/javascript/controllers/optimistic_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["template"]
+
+  submit() {
+    const template = this.templateTarget.content.cloneNode(true)
+    const id = `pending_${Date.now()}`
+    template.querySelector(".message").id = id
+    document.body.append(template)
+  }
+}
+```
+
+The `<template>` element prevents the `<turbo-stream>` from executing on page load. Cloning and appending triggers the stream action on demand.
+
+## 4.5 Cache-Safe Views
+
+**Turbo caches pages before navigating away.** If transient UI states (open dropdowns, flash messages, active modals) are cached, they reappear as stale artifacts on restoration visits. Clean them up before the cache snapshot.
+
+### Cleaning Transient UI
+
+```javascript
+// app/javascript/controllers/cache_cleanup_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    document.addEventListener("turbo:before-cache", this.cleanup)
+  }
+
+  disconnect() {
+    document.removeEventListener("turbo:before-cache", this.cleanup)
+  }
+
+  cleanup = () => {
+    // Close dropdowns
+    this.element.querySelectorAll("[data-expanded]").forEach(el => {
+      el.removeAttribute("data-expanded")
+    })
+    // Clear flash messages
+    this.element.querySelectorAll(".flash").forEach(el => el.remove())
+    // Reset form states
+    this.element.querySelectorAll("form").forEach(form => form.reset())
+  }
+}
+```
+
+### Guard Against Preview Rendering
+
+When Turbo restores a cached page, it adds `data-turbo-preview` to the `<html>` element. Use this to guard rendering that depends on fresh data:
+
+```erb
+<% unless request.headers["Purpose"] == "preview" %>
+  <div class="live-metrics" data-controller="polling">
+    <%= render partial: "dashboard/metrics", locals: { stats: @stats } %>
+  </div>
+<% end %>
+```
+
+### Fragment Caching with Presenter Keys
+
+Use presenter cache keys to invalidate fragments when underlying data changes:
+
+```erb
+<% cache presenter.cache_key do %>
+  <div class="filtering-panel">
+    <%= render partial: "filters/tags", locals: { tags: presenter.tags } %>
+    <%= render partial: "filters/users", locals: { users: presenter.users } %>
+  </div>
+<% end %>
+```
+
+### Summary
+
+View templates and partials:
+- **Keep templates thin** — delegate conditionals and queries to presenters
+- **Use `content_for`** to inject page-specific content into layouts
+- **Extract partials** when markup repeats or a clear component boundary exists
+- **Pass data via `locals:`** — never rely on instance variables in partials
+- **Use `dom_id`** for Turbo Frame IDs to ensure consistency between page and response
+- **Lazy-load frames** with `src` for deferred content
+- **Store Turbo Streams in `<template>` elements** to prevent premature execution
+- **Clean transient UI** in `turbo:before-cache` to avoid stale cached states
+- **Guard preview rendering** with `data-turbo-preview` checks
+- **Use presenter cache keys** for fragment caching invalidation
 
 ---
 
-**Document Version**: 1.0
-**Last Updated**: 2026-02-15
+**Document Version**: 2.0
+**Last Updated**: 2026-02-17
 **Maintainer**: Development Team