nitro_kit 0.9.0 → 2.0.0.alpha.1

data/docs/patterns/application_foundation.md

@@ -0,0 +1,136 @@
+# A durable application foundation
+
+Start a small authenticated application with the same records and page grammar
+it will need after the second person joins. The first-user case should be the
+smallest instance of the team model, not a separate personal mode that must be
+replaced later.
+
+## Summary
+
+- Model `User`, `Team`, and `Membership` from the first signup; role belongs to
+  `Membership`, and every team-owned record loads through `Current.team`.
+- One hybrid `AppShell` frames the authenticated product: `AppNavigation` owns
+  brand and destinations, the shell `Toolbar` owns route titles and persistent
+  basic actions.
+- One wrapper immediately inside `shell.main` owns responsive page padding for
+  every route; the shell owns viewport height and scrolling.
+- Infrequent account destinations go after `navigation.spacer`; settings
+  compose with `SettingsLayout` and plain `FormSection` regions.
+- When destination count warrants search, compose one `CommandPalette` in the
+  shell and render only routes the current membership may visit.
+- Centralize cross-cutting feedback in one flash-driven toast region rendered
+  by the layout.
+
+## Use memberships from the first user
+
+Use `User`, `Team`, and `Membership` even when signup creates exactly one of
+each. Put the role on `Membership`, not `User`, because authority belongs to a
+person's relationship with a team. Create the first team and owner membership
+in the same transaction as signup.
+
+Set `Current.user`, `Current.membership`, and `Current.team` from the session.
+Load every team-owned record through `Current.team`; use `Current.user` for
+authorship and audit fields. Start with the smallest role vocabulary the
+product needs, usually owner, administrator, and member. Protect the last owner
+in the domain model rather than only hiding a button.
+
+Invitations should belong to a team, record the inviter and intended role,
+expire, match the invited email, and be consumed when accepted. An existing
+user accepts into a new membership; a new user completes signup and then uses
+the same acceptance path.
+
+## Compose one authenticated frame
+
+Use one hybrid `AppShell` for the authenticated product. Keep the brand and
+primary destinations in `AppNavigation`; place route titles and persistent
+basic actions in the shell `Toolbar`. One wrapper immediately inside
+`shell.main` owns responsive page padding for every route. The topbar and
+sidebar header should use the shell's shared height and border tokens rather
+than independent padding guesses.
+
+Put infrequent account navigation after `navigation.spacer`, near the account
+controls at the bottom of the sidebar:
+
+```ruby
+shell.navigation do
+  AppNavigation(label: "Workspace navigation") do |navigation|
+    navigation.body do
+      navigation.item("Inventory", href: assets_path, icon: :archive)
+      navigation.item("Team", href: team_path, icon: :users)
+      navigation.spacer
+      navigation.item("Settings", href: settings_profile_path, icon: :settings)
+    end
+  end
+end
+```
+
+Application code owns destinations and current-route policy. Nitro owns shell
+layout, mobile disclosure, focus management, and navigation semantics.
+For larger products, place one `CommandPalette` in the shell. Its native links
+remain the navigation authority while Command-K or Control-K adds fast
+filtering. Render the same authorized destination set the user can reach in
+ordinary navigation; do not use the palette to bypass route policy.
+When the destination set is too large or dynamic to render eagerly, pass
+`search_url:` and return `CommandPalette::Results` from that endpoint. Keep the
+same authorization scope on the initial links and every remote query.
+Let the shell own viewport height and scrolling; do not add `min-height: 100vh`
+to its main region or page wrapper. Put brand and destination icons through the
+navigation slots so they share the same left alignment.
+
+Team is an administration surface, not merely a roster. Include pending
+invitations and the complete invite, role-change, removal, and revoke paths,
+with last-owner protection in the model and authorization on every mutation.
+
+Authentication is a standalone form surface. Inside `AuthShell`, use Rails
+`form_with` with `NitroKit::FormBuilder` and put the visible fields, submit
+control, and related recovery link in one `form.group`. The group owns their
+vertical rhythm; `AuthShell` owns only the page container and spacing between
+its major regions.
+
+## Keep settings plain
+
+Use `SettingsLayout` inside the normal shell main region. Its navigation lists
+stable subsections such as Profile, Notifications, Appearance, and Password;
+its content renders the selected form. Use `FormSection` for genuinely distinct
+form regions and ordinary whitespace or dividers between them.
+
+Render subsection destinations as links and mark the active link with
+`aria-current="page"`. They navigate between routes; Buttons and ButtonGroup
+would incorrectly present them as in-page actions. Small preferences may
+submit on change through a tiny application Stimulus controller that calls the
+form's native `requestSubmit`. Keep a submit control in `noscript` so the form
+still works without JavaScript.
+
+The route still has one `h1` in the shell toolbar. Do not repeat “Settings” in
+the page body, wrap each subsection in a Card, or give every form its own outer
+padding. A toolbar Save button can submit the selected form with the native
+`form:` attribute, so the action stays in the same place at narrow and wide
+widths without JavaScript.
+
+## Centralize cross-cutting feedback
+
+Render `Toast::FlashMessages` once in the application layout. Keep using
+ordinary Rails flash and `303 See Other` redirects from controllers.
+
+Compact destructive actions should continue to declare
+`data: { turbo_confirm: "…" }` and use Turbo's native browser confirmation.
+When the user needs branded review UI or more context than one sentence,
+compose a dedicated native Nitro `Dialog` at the action's call site. The
+browser's top layer keeps that inline dialog clear of ancestor clipping and
+stacking contexts. Put record deletion on the edit route rather than adding a
+danger surface to every operational show page.
+
+## Baseline acceptance path
+
+Before polishing empty-state illustration or dashboard summaries, verify:
+
+- signup or sign-in selects the current membership and team;
+- another team cannot load the current team's records;
+- owner, administrator, and member policy differs where intended;
+- populated, empty, invalid, narrow, and destructive states work;
+- settings forms preserve validation and use one content gutter;
+- successful mutations redirect with `303` and invalid forms render with
+  `422`;
+- confirmation has both cancel and confirm coverage;
+- the shell, headings, tables, and forms remain usable without custom request
+  JavaScript.

data/docs/patterns/crud_resource.md

@@ -0,0 +1,144 @@
+# A complete product resource
+
+Build CRUD as one coherent product surface, not independent generated screens.
+Before writing the views, name the resource, tenant boundary, actor, lifecycle,
+visibility rules, and states. Implement index, form, detail, destructive action,
+and their tests together.
+
+## Summary
+
+- Build index, form, detail, destructive action, and their tests as one
+  surface; name the resource, tenant boundary, actor, lifecycle, and states
+  before writing views.
+- `AppShell(layout: :hybrid)` frames the admin area, and a `Toolbar` in
+  `shell.topbar` carries the route's single `h1` plus its basic actions.
+- Spend hierarchy once: one route, one `h1`, an `h2` only for a genuinely
+  separate region, and no resource name repeated across toolbar, `PageHeader`,
+  `DataSection`, Card, and caption.
+- Child routes add one compact icon Back link before the title instead of a
+  trailing Cancel action.
+- One responsive padding rule on the main wrapper owns the page gutter;
+  data-heavy hybrid CRUD content uses the full available width.
+
+## Use the hybrid application frame
+
+An authenticated admin area defaults to `AppShell(layout: :hybrid)`. Nitro Kit
+owns the desktop sidebar, mobile menu button, navigation dialog, focus behavior,
+and responsive transition. The application provides destinations and current
+state.
+
+Put a `Toolbar` in `shell.topbar`. Its leading region contains the route's one
+`h1`; its trailing region contains basic actions such as New, Edit, Cancel,
+Save, Publish, or View. A Button outside a form can submit it through the
+native `form:` attribute. This keeps the same action hierarchy on narrow and
+wide screens without custom JavaScript.
+
+```ruby
+AppShell(id: "admin", layout: :hybrid) do |shell|
+  shell.navigation { render admin_navigation }
+  shell.topbar do
+    Toolbar do |toolbar|
+      toolbar.leading { h1 { page_title } }
+      toolbar.trailing do
+        Button(
+          "Save",
+          type: :submit,
+          form: dom_id(@post, :form),
+          variant: :primary
+        )
+      end
+    end
+  end
+  shell.main do
+    div(data: { ui: "admin-main" }) do
+      render page
+    end
+  end
+end
+```
+
+Child routes add one compact Back link before the title. Prefer an icon-only
+Button with an explicit label such as `aria: { label: "Back to projects" }`.
+Do not repeat that navigation as a trailing Cancel action.
+
+The application stylesheet gives `admin-main` one responsive padding rule.
+Child pages do not add another outer gutter. Keep data-heavy hybrid CRUD
+content full width; constrain only a specific content-led region whose measure
+benefits from it.
+
+Do not add viewport height or another outer padding rule to `admin-main`; the
+shell owns viewport geometry and the wrapper owns the one page gutter. Use the
+same shell and gutter on team administration and settings routes.
+Place a bottom-anchored Settings destination after `AppNavigation#spacer`, then
+compose settings subsections with `SettingsLayout` and plain `FormSection`
+regions. Settings destinations are links with `aria-current`, not action
+Buttons. Read `application_foundation.md` for the complete application frame.
+
+## Spend hierarchy once
+
+- One route, one `h1`, normally in the shell toolbar.
+- Add an `h2` only for a genuinely separate region.
+- Do not repeat “Posts” in the toolbar, `PageHeader`, `DataSection`, Card, and
+  visible table caption.
+- Use `PageHeader` for a content-led introduction, not as mandatory CRUD
+  ceremony under an existing toolbar.
+- Prefer whitespace and dividers. Use Card only for a bounded object that
+  benefits from its own surface. Never default to Card inside Card.
+
+An index begins with a short introduction only if it adds useful context, then
+renders its table and pagination directly. Use `DataSection` when a page has
+multiple independently named datasets. At zero records, replace the data region
+with one intentional `EmptyState`; keep the primary New action in the toolbar.
+
+A new or edit page begins with `FormSection`. Use one form component for new,
+edit, and invalid renders. Put the primary submit in the toolbar by setting the
+button's `form:` to the form's stable DOM ID. Invalid submissions render the
+same model and form with `422 Unprocessable Entity`. The toolbar owns that
+action: do not render a second Save or Create submit inside the form body.
+
+A detail page begins with status or stable metadata, then the resource itself.
+Keep status inside that normal details flow instead of detaching it into a
+second side panel.
+Use the authenticated `show` route as the operational detail or draft preview.
+Put lifecycle forms in the page and associate their toolbar buttons with
+`form:`. Put destructive confirmation in one separate `DangerZone` on edit,
+with a safe escape back to the record. Do not make every show page end in a
+large deletion surface.
+
+## Model and route the lifecycle
+
+Scope every lookup through `Current.team` or `Current.account`. Record
+`Current.user` as author, creator, or publisher. If a state has provenance,
+timing, or behavior, model it as a record and expose it as a noun resource:
+
+```ruby
+namespace :admin do
+  resources :posts do
+    resource :publication,
+      only: %i[create destroy],
+      module: :posts
+  end
+end
+```
+
+The main controller keeps the seven REST actions. Successful mutations redirect
+with `303 See Other`. Publication create and destroy invoke domain methods and
+redirect. Public controllers query published records only. Ordinary Rails forms
+and Turbo Drive are the default; do not add fetch code for CRUD submissions.
+
+## Ship the acceptance path
+
+Request tests cover tenant isolation, public visibility, successful `303`
+redirects, invalid `422` renders, pagination, and lifecycle resources. Rendering
+assertions should also protect the high-level composition: hybrid AppShell,
+one `h1`, navigation, toolbar action, actual form association, table or empty
+state, and destructive confirmation. Add one browser test for the meaningful
+end-to-end path, using Capybara waiting assertions instead of sleeps.
+
+Assert that each primary action has one visible control. A toolbar-associated
+form submit plus an identical body submit is duplication, even when both invoke
+the same valid form.
+
+Before finishing, inspect a populated index, empty index, invalid form, narrow
+form, draft detail, published detail, and edit-owned destructive dialog. Remove any extra
+heading, surface, wrapper, or page gutter that does not communicate information.

data/docs/patterns/destructive_action.md

@@ -0,0 +1,105 @@
+# Destructive action
+
+Use a native Nitro Dialog when the user needs to review impact or type confirmation. The dialog only owns accessible disclosure and focus behavior; a real Rails form owns the destructive request.
+
+## Summary
+
+- Use a native Nitro `Dialog` only when the user must review impact or type a
+  confirmation; a real Rails form owns the destructive request.
+- Place the reviewed deletion on the resource's edit page, not on the
+  operational show page.
+- The delete form targets `_top` so a successful redirect navigates the page
+  instead of resolving inside the surrounding frame.
+- Authorize and load the record on the server. The confirmation UI is not a
+  security boundary.
+- When the consequence fits in one sentence, use Turbo's native `turbo_confirm`
+  instead. Never stack both confirmation surfaces.
+
+## Reviewed deletion
+
+Place this composition on the resource's edit page. A show page is the
+operational home; it should not advertise permanent deletion on every visit.
+
+```ruby
+module UI
+  class DeleteProject < Phlex::HTML
+    include Phlex::Rails::Helpers::DOMID
+    include Phlex::Rails::Helpers::FormWith
+    include Phlex::Rails::Helpers::Routes
+
+    def initialize(project)
+      @project = project
+    end
+
+    def view_template
+      render NitroKit::DangerZone.new(
+        title: "Delete project",
+        description: "This permanently removes the project and its activity.",
+        id: dom_id(project, :danger_zone)
+      ) do |zone|
+        zone.confirmation do
+          render NitroKit::Dialog.new(id: dom_id(project, :delete_dialog)) do |dialog|
+            dialog.trigger("Review deletion", variant: :destructive)
+            dialog.panel(
+              title: "Delete #{project.name}?",
+              description: "This action cannot be undone."
+            ) do
+              form_with(
+                model: project,
+                url: project_path(project),
+                method: :delete,
+                data: { turbo_frame: "_top" }
+              ) do
+                render NitroKit::Button.new(
+                  "Delete project",
+                  type: :submit,
+                  variant: :destructive,
+                  data: { turbo_submits_with: "Deleting…" }
+                )
+              end
+              dialog.close_button(label: "Cancel deletion")
+            end
+          end
+        end
+        zone.escape NitroKit::Button.new("Keep project", href: project_path(project))
+      end
+    end
+
+    private
+      attr_reader :project
+  end
+end
+```
+
+The top-level target makes a successful redirect navigate the page rather than trying to render the destination inside the surrounding settings frame.
+
+```ruby
+def destroy
+  project = Current.account.projects.find(params[:id])
+  project.destroy!
+  redirect_to projects_path, status: :see_other, notice: "Project deleted"
+end
+```
+
+Authorize and load the record on the server even when the dialog is open. The confirmation UI is not a security boundary.
+
+## Compact confirmation
+
+When the consequence fits in one sentence and needs no review UI, keep the ordinary request and use Turbo's native browser confirmation:
+
+```ruby
+form_with(model: project, url: project_path(project), method: :delete) do
+  render NitroKit::Button.new(
+    "Delete",
+    type: :submit,
+    variant: :destructive,
+    data: { turbo_confirm: "Delete this project permanently?" }
+  )
+end
+```
+
+Do not stack `turbo_confirm` inside a Dialog. Choose one confirmation surface.
+
+## Tests
+
+Request-test authorization, deletion, 303 redirect, and flash. System-test the dialog only when the reviewed flow matters: trigger opens it, Cancel closes and restores focus, and the destructive submit removes the record.

data/docs/patterns/flash_and_toast.md

@@ -0,0 +1,57 @@
+# Flash and toast
+
+Rails flash is the server-side feedback contract. Render it once in the application layout with Nitro's toast adapter so redirects, Turbo visits, and full-page fallbacks all use the same path.
+
+## Summary
+
+- Render `NitroKit::Toast::FlashMessages` once in the application layout; Rails
+  flash stays the single server-side feedback contract.
+- `notice` maps to the default presentation, `alert` and `error` to error, and
+  `success`, `warning`, and `info` to their matching variants.
+- Every toast item is Turbo-temporary so a cached page never replays old
+  feedback, while the region itself survives and stays addressable.
+- Use `flash.now` when rendering the current request; a Turbo Stream that does
+  not redirect updates the same stable notification region.
+- Do not introduce a client-side notification store for server outcomes.
+
+```ruby
+class UI::ApplicationLayout < Phlex::HTML
+  include Phlex::Rails::Layout
+  include Phlex::Rails::Helpers::Flash
+
+  def view_template
+    doctype
+    html do
+      head do
+        stylesheet_link_tag("nitro_kit", data: { turbo_track: "reload" })
+      end
+      body do
+        render NitroKit::Toast::FlashMessages.new(flash: flash)
+        yield
+      end
+    end
+  end
+end
+```
+
+Controllers set ordinary flash while redirecting:
+
+```ruby
+redirect_to projects_path, status: :see_other, notice: "Project created"
+redirect_to billing_path, status: :see_other, alert: "Payment method was declined"
+```
+
+`notice` maps to the default presentation, `alert` and `error` to error, and `success`, `warning`, and `info` to their matching variants. Every toast item is Turbo-temporary so a cached page does not replay old feedback, dismissible or not. The region itself survives, so `#{toast id}-list` stays addressable.
+
+Use `flash.now` only when rendering in the current request:
+
+```ruby
+flash.now[:alert] = "Import failed"
+render UI::ImportForm.new(@import), status: :unprocessable_entity
+```
+
+For a request-scoped Turbo Stream that does not redirect, update a stable notification region in the same stream response. Keep the HTML branch and flash fallback. Do not introduce a client-side notification store for server outcomes.
+
+## Tests
+
+Controller tests assert the flash severity and message. One layout or integration test should prove the flash renders through `section[data-nk=toast]`. Nitro's own tests cover timers and dismissal behavior.

data/docs/patterns/inline_edit.md

@@ -0,0 +1,59 @@
+# Inline edit
+
+Wrap one complete resource region in a stable Turbo Frame. Show, edit, validation failure, success, and Cancel all return that same frame ID.
+
+## Summary
+
+- One complete resource region lives in a stable Turbo Frame; show, edit,
+  invalid, success, and Cancel all return that same frame ID.
+- Invalid updates render the editing frame with 422; success redirects with 303
+  and Turbo extracts the matching read-only frame.
+- The show response must contain the same `turbo_frame_tag(dom_id(record))` as
+  the edit response.
+- Use a Turbo Stream only when the update also changes another region, such as
+  a page title or a summary count.
+
+```ruby
+module UI
+  class ProjectPanel < Phlex::HTML
+    include Phlex::Rails::Helpers::DOMID
+    include Phlex::Rails::Helpers::TurboFrameTag
+
+    def initialize(project, editing: false)
+      @project = project
+      @editing = editing
+    end
+
+    def view_template
+      turbo_frame_tag(dom_id(project)) do
+        if editing
+          render UI::ProjectFormFields.new(project)
+        else
+          render NitroKit::Card.new do |card|
+            card.title(project.name)
+            card.body { project.description }
+            card.footer do
+              render NitroKit::Button.new("Edit", href: "/projects/#{project.id}/edit")
+            end
+          end
+        end
+      end
+    end
+
+    private
+      attr_reader :project, :editing
+  end
+end
+```
+
+The edit form submits normally within the frame. Its Cancel link targets the resource show action, which returns the read-only frame. Invalid updates render the editing frame with 422. A successful update redirects with 303 to the resource action; Turbo follows the redirect and extracts the matching read-only frame:
+
+```ruby
+redirect_to @project, status: :see_other, notice: "Project updated"
+```
+
+The show response must contain `turbo_frame_tag(dom_id(project))` just like the edit response. If success renders directly instead, return frame-shaped HTML rather than labeling a bare frame as a Turbo Stream. Use a stream only when the update also changes another region, such as a page title or summary count.
+
+## Tests
+
+Assert every endpoint returns the same `turbo-frame` ID. Cover invalid values remaining visible at 422 and Cancel restoring the read-only view. Add a system test when focus or scroll preservation is important.

data/docs/patterns/queryable_collection.md

@@ -0,0 +1,187 @@
+# Queryable collection
+
+Use one GET-driven Turbo Frame for filters, sorting, results, and pagination. The URL is the state: the query object reads parameters, the server renders the complete region, and browser history remains useful.
+
+## Summary
+
+- One GET-driven Turbo Frame with a stable ID owns filters, sorting, results,
+  and pagination; the URL is the state.
+- The frame carries `data-turbo-action="advance"` so pagination is a history
+  step, while filter, reset, and sort links use `turbo_action: "replace"`.
+- An application query object owns parameter allowlists, default ordering, and
+  page bounds. `NitroKit::Table` renders sortable headers but owns no query
+  policy, and Ransack is never a Nitro dependency.
+- Every response contains the same frame, including empty results. Links that
+  leave the collection use `data: { turbo_frame: "_top" }`.
+- No Stimulus controller is required. An optional autosubmit controller submits
+  the same GET form without becoming the source of truth.
+
+## Contract
+
+- The frame has one stable ID.
+- The frame promotes pagination with `data-turbo-action="advance"` so each page
+  remains a meaningful Back and Forward step.
+- Filter forms use GET, target that frame, and replace the current history entry.
+- A small filter set stays in one responsive row at wide widths and stacks on
+  narrow screens. Do not turn two fields and two actions into a full-page form.
+- Sort and pagination links preserve the active query parameters. Sort links
+  replace the current history entry; pagination inherits the frame's `advance`.
+- `NitroKit::Table` renders the sortable table contract but does not own query policy.
+- The HTML response always contains the same frame, including empty results.
+- No Stimulus controller is required for submit-based filters. An optional autosubmit controller may submit the same GET form without becoming the source of truth.
+
+## Controller
+
+Keep parameter normalization and allowlists in an application query object. Ransack is one possible implementation, not a Nitro dependency.
+
+```ruby
+class ProjectsController < ApplicationController
+  def index
+    @query = ProjectsQuery.new(Project.all, params: params.fetch(:q, {}), page: params[:page])
+  end
+end
+```
+
+The query object should expose `records`, `filters`, `current_sort`, `direction`, `sort_url(key)`, and pagination URLs. It is also the right place for Ransack allowlists, default ordering, and page bounds.
+
+## Phlex region
+
+```ruby
+module UI
+  class ProjectsTable < Phlex::HTML
+    include Phlex::Rails::Helpers::FormWith
+    include Phlex::Rails::Helpers::TurboFrameTag
+
+    FRAME_ID = "projects-results"
+
+    def initialize(query)
+      @query = query
+    end
+
+    def view_template
+      turbo_frame_tag(FRAME_ID, data: { turbo_action: "advance" }) do
+        render NitroKit::Flex.new(dir: :col, gap: 6, align: :stretch) do
+          render_filters
+          render_results
+          render_pagination
+        end
+      end
+    end
+
+    private
+      attr_reader :query
+
+      def render_filters
+        form_with(
+          scope: :q,
+          url: "/projects",
+          method: :get,
+          builder: NitroKit::FormBuilder,
+          data: {
+            turbo_frame: FRAME_ID,
+            turbo_action: "replace"
+          }
+        ) do |form|
+          form.hidden_field(:s, value: query.filters["s"])
+          render NitroKit::Grid.new(cols: "1 md:3", gap: 3) do
+            form.field(:name_cont, as: :search, label: "Search", value: query.filters["name_cont"])
+            form.field(:status_eq, as: :select, label: "Status", options: Project.statuses.keys, include_blank: "All statuses", value: query.filters["status_eq"])
+            render NitroKit::Flex.new(dir: :row, gap: 2, align: :end, justify: :end) do
+              render NitroKit::Button.new(
+                "Reset",
+                href: "/projects",
+                data: {
+                  turbo_frame: FRAME_ID,
+                  turbo_action: "replace"
+                }
+              )
+              form.submit("Apply filters", data: { turbo_submits_with: "Filtering…" })
+            end
+          end
+        end
+      end
+
+      def render_results
+        render NitroKit::Table.new(
+          sort: query.current_sort,
+          direction: query.direction
+        ) do |table|
+          table.caption("Projects")
+          table.thead do
+            table.tr do
+              table.th(
+                sort: :name,
+                href: query.sort_url(:name),
+                sort_data: { turbo_action: "replace" }
+              )
+              table.th(
+                sort: :status,
+                href: query.sort_url(:status),
+                sort_data: { turbo_action: "replace" }
+              )
+              table.th(
+                "Updated",
+                sort: :updated_at,
+                href: query.sort_url(:updated_at),
+                align: :right,
+                sort_data: { turbo_action: "replace" }
+              )
+              table.th("Actions", align: :right)
+            end
+          end
+          table.tbody do
+            if query.records.any?
+              query.records.each { |project| render_row(table, project) }
+            else
+              table.tr { table.td("No projects match these filters.", html: { colspan: 4 }) }
+            end
+          end
+        end
+      end
+
+      def render_row(table, project)
+        table.tr do
+          table.th(project.name, scope: :row)
+          table.td { render NitroKit::Badge.new(project.status.humanize) }
+          table.td(project.updated_at.to_date.to_fs(:long), align: :right)
+          table.td(align: :right) do
+            render NitroKit::Button.new(
+              "View",
+              href: project_path(project),
+              data: { turbo_frame: "_top" }
+            )
+          end
+        end
+      end
+
+      def render_pagination
+        render NitroKit::PaginationBar.new do |bar|
+          bar.summary(query.summary)
+          bar.pagination(query.pagination)
+        end
+      end
+  end
+end
+```
+
+Sorting and pagination links rendered inside the frame naturally navigate it.
+The frame's `advance` action makes pagination a browser-history step. Filters,
+reset links, and sort links override that default with `turbo_action: "replace"`
+so repeated query refinements do not fill history with disposable states. Use
+`data: { turbo_frame: FRAME_ID }` when a query control sits outside the frame.
+Reset with a plain collection URL so stale query parameters disappear.
+
+Links that leave the collection, including View, Edit, and New, are not frame
+navigations. Give them `data: { turbo_frame: "_top" }`, or place them outside
+the results frame. Otherwise Turbo will look for the collection frame in the
+destination response and replace the region with “Content missing.”
+
+## Tests
+
+Request tests should prove that query parameters survive sort and page changes,
+invalid sort keys fall back safely, and the response always contains
+`turbo-frame#projects-results`. A system test should use real clicks, scope
+result assertions to that frame, cover filter → sort → paginate → Back and
+Forward, assert the address bar after each query transition, and open a row
+action without a frame-missing error. Use Capybara's retrying assertions rather
+than sleeps or arbitrary waits.