nitro_kit 2.0.0.alpha.3 → 2.0.0.alpha.4

data/docs/patterns/crud_resource.md

@@ -1,147 +1,62 @@
-# A complete product resource
+# 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.
+**Audience:** Coding agents and developers implementing a full Rails CRUD
+resource with Nitro Kit.
 
 ## 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.
-- At narrow widths, trailing actions stack below the Back affordance and title;
-  do not clip the title or hide persistent actions to keep the header short.
-- One responsive padding rule on the main wrapper owns the page gutter;
-  data-heavy hybrid CRUD content uses the full available width.
+- Define the resource, tenant boundary, actor, lifecycle, visibility, and
+  states before writing views.
+- Build index, form, detail, destructive action, and tests as one product
+  surface.
+- Use one shell toolbar title and one application-owned page gutter; do not
+  repeat hierarchy across nested components.
+- Scope every lookup through the current tenant and model meaningful lifecycle
+  transitions as noun resources.
 
-## Use the hybrid application frame
+## Resource map
 
-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.
+Use `AppShell(layout: :hybrid)` for an authenticated product area. Put the
+route's one `h1` and persistent actions in the topbar `Toolbar`. Child routes
+place one compact Back link before the title. One wrapper inside `shell.main`
+owns page padding; child pages add no outer gutter.
 
-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. Nitro Kit stacks the regions at narrow
-widths so a Back affordance, long title, and several actions remain legible.
+| Route                 | Composition                                                                                                             |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Index                 | Optional short introduction, then Table or EmptyState and pagination. Use DataSection only for multiple named datasets. |
+| New/Edit              | One `SettingsSection` and one shared form component. A toolbar submit targets the form's stable `form:` ID.             |
+| Show                  | Status or metadata, then the resource. Keep lifecycle actions in the normal detail flow.                                |
+| Edit destructive area | One `DangerZone` with a safe escape. Do not put permanent deletion on every show page.                                  |
 
-```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 `SettingsSection`
-regions. Settings destinations are links with `aria-current`, not action
-Buttons. Read `application_foundation.md` for the complete application frame.
+Use one primary action. Do not render the same Save or Create action in both
+the toolbar and form body. Use Card only for a bounded object that benefits
+from its own surface.
 
-## Spend hierarchy once
+See [Resource form](resource_form.md),
+[Destructive action](destructive_action.md), and
+[Queryable collection](queryable_collection.md) for complete interaction
+contracts.
 
-- 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.
+## Lifecycle and responses
 
-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 `SettingsSection`. 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:
+Scope lookups through `Current.team` or `Current.account`. Use
+`Current.user` as actor. When state has timing, provenance, or behavior, model
+it as a noun resource:
 
 ```ruby
-namespace :admin do
-  resources :posts do
-    resource :publication,
-      only: %i[create destroy],
-      module: :posts
-  end
+resources :posts do
+  resource :publication, only: %i[create destroy], module: :posts
 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.
+Keep the main controller to REST actions. Successful mutations redirect with
+`303 See Other`; invalid forms render the same model with `422 Unprocessable
+Entity`. Public controllers query only publicly visible records.
 
-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.
+## Acceptance checklist
 
-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.
+Test tenant isolation, authorization, public visibility, lifecycle resources,
+pagination, `303` redirects, and `422` validation. Protect the high-level
+composition: one title, one primary action, the correct form association,
+Table or EmptyState, and edit-owned destructive confirmation. Inspect
+populated, empty, invalid, narrow, draft, published, and destructive states.

data/docs/patterns/destructive_action.md

@@ -1,82 +1,58 @@
 # 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.
-
-Nitro keeps the declarative dialog command as the native path and supplies a
-capability-detected JavaScript bridge for supported browsers that lack Invoker
-Commands. The bridge changes only disclosure; it never intercepts or recreates
-the form request.
+**Audience:** Coding agents and developers implementing delete, revoke,
+archive, or similarly destructive Rails actions.
 
 ## 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.
+- Use `NitroKit::Dialog` when the user must review impact or type confirmation;
+  use Turbo's native browser confirmation for a one-sentence consequence.
+- A real Rails form owns the request, and the server owns authorization.
+- Put permanent deletion on the edit route, not the operational show route.
+- Use a server-rendered review route when confirmation must work without
+  JavaScript or Invoker Commands.
 
-## Reviewed deletion
+## Choose one confirmation path
 
-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.
+| Need                                            | Pattern                                                         |
+| ----------------------------------------------- | --------------------------------------------------------------- |
+| One-sentence confirmation                       | Real form with `data: { turbo_confirm: "Delete permanently?" }` |
+| Reviewed impact or typed confirmation           | `DangerZone` containing a Dialog and real form                  |
+| Confirmation required without client JavaScript | Ordinary link to a server-rendered review page                  |
 
-```ruby
-module UI
-  class DeleteProject < Phlex::HTML
-    include Phlex::Rails::Helpers::DOMID
-    include Phlex::Rails::Helpers::FormWith
-    include Phlex::Rails::Helpers::Routes
+Never stack `turbo_confirm` inside a Dialog.
 
-    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
+```ruby
+render NitroKit::DangerZone.new(
+  title: "Delete project",
+  description: "This permanently removes the project.",
+  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}?") do
+        form_with(
+          model: project,
+          method: :delete,
+          data: { turbo_frame: "_top" }
+        ) do
+          render NitroKit::Button.new(
+            "Delete project",
+            type: :submit,
+            variant: :destructive
+          )
         end
-        zone.escape NitroKit::Button.new("Keep project", href: project_path(project))
+        dialog.close_button(label: "Cancel deletion")
       end
     end
-
-    private
-      attr_reader :project
   end
+  zone.escape NitroKit::Button.new("Keep project", href: project_path(project))
 end
 ```
 
-The top-level target makes a successful redirect navigate the page rather than trying to render the destination inside the surrounding settings frame.
+The `_top` target keeps the redirect out of a surrounding frame. The dialog is
+not a security boundary; load and authorize the record on the server.
 
 ```ruby
 def destroy
@@ -86,45 +62,12 @@ def destroy
 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.
-
-## Browser fallback
-
-The reviewed flow depends on Dialog opening in the user's browser. Nitro owns
-the compatibility path when its packaged controller is installed, but no
-client-side dialog can guarantee confirmation when both JavaScript and the
-required native dialog invocation API are unavailable. Applications that must
-support that case should link to a server-rendered review route with an ordinary
-deletion form.
-
-`data-turbo-confirm` is a compact Turbo enhancement, not that no-JavaScript
-fallback. Without Turbo it does not display a confirmation, although the real
-form can still submit. When confirmation must be unavoidable, make review a
-server-owned step rather than stacking both client confirmation surfaces.
+Without JavaScript, a form inside a closed Dialog is reachable only where
+Invoker Commands are supported. `data-turbo-confirm` also requires Turbo. Use
+the server-owned review route when confirmation must be unavoidable. See
+[Browser support](../browser_support.md).
 
 ## 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.
-
-The successful `DELETE` response must redirect with `303 See Other`, including
-when Turbo submits the form. Without JavaScript the real form still provides a
-request path, but a form placed only inside a closed dialog is reachable only
-where Invoker Commands are supported; provide an ordinary server-rendered link
-to a review page when deletion must remain reachable across that baseline.
+Request-test authorization, mutation, flash, and the `303` redirect. For a
+reviewed flow, system-test open, cancel with focus restoration, and confirm.

data/docs/patterns/flash_and_toast.md

@@ -1,57 +1,39 @@
 # 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.
+**Audience:** Coding agents and developers presenting Rails server feedback.
 
 ## 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.
+- Rails flash is the server-side feedback contract; render
+  `NitroKit::Toast::FlashMessages` once in the application layout.
+- Use redirect flash for navigation and `flash.now` when rendering the current
+  request.
+- Toast items are Turbo-temporary so cached pages do not replay them; the
+  region keeps a stable address for stream updates.
+- Do not add 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
+body do
+  render NitroKit::Toast::FlashMessages.new(flash: flash)
+  yield
 end
 ```
 
-Controllers set ordinary flash while redirecting:
+Controllers use ordinary Rails flash:
 
 ```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.
+`notice` uses the default presentation; `alert` and `error` map to error;
+`success`, `warning`, and `info` map to matching variants. A request-scoped
+Turbo Stream may update the same stable Toast list, but must keep an HTML
+branch and flash fallback.
 
 ## 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.
+Assert flash severity and message in request tests. One layout or integration
+test should prove rendering through `section[data-nk=toast]`.

data/docs/patterns/inline_edit.md

@@ -1,59 +1,36 @@
 # 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.
+**Audience:** Coding agents and developers editing one resource region in
+place with Turbo Frames.
 
 ## 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.
+- Wrap the complete resource region in one stable Turbo Frame.
+- Show, edit, validation failure, success, and Cancel return the same frame ID.
+- Invalid updates render with `422`; successful updates redirect with `303`.
+- Use a Turbo Stream only when the update changes another region too.
 
 ```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
+turbo_frame_tag(dom_id(project)) do
+  if editing
+    render UI::ProjectForm.new(project)
+  else
+    div do
+      h2 { project.name }
+      render NitroKit::Button.new("Edit", href: edit_project_path(project))
     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.
+The edit form submits inside the frame. Cancel links to the show action, whose
+response contains the same `turbo_frame_tag(dom_id(project))`. Invalid updates
+render the editing frame with `status: :unprocessable_entity`. Success redirects
+with `status: :see_other`; Turbo follows it and extracts the matching read-only
+frame.
 
 ## 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.
+Assert the same frame ID on every endpoint, submitted values and errors at
+`422`, success at `303`, and Cancel restoring the read-only view. Add a system
+test only when focus, scroll, or multi-region behavior matters.