nitro_kit 0.9.0 → 2.0.0.alpha.2

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.

data/docs/patterns/resource_form.md

@@ -0,0 +1,126 @@
+# Resource form
+
+Use one model-backed component for both the initial form and validation errors. Rails owns field names and errors; Nitro owns form presentation; the response status tells Turbo whether to replace or follow a redirect.
+
+## Summary
+
+- One model-backed Phlex component renders both the initial form and its
+  validation errors.
+- Rails owns field names and errors, Nitro owns form presentation, and the
+  response status tells Turbo what to do: 422 re-renders the invalid object,
+  303 redirects on success.
+- In an application shell, render exactly one primary submit in the route
+  toolbar and associate it through the native `form:` attribute; do not also
+  call `form.submit` in the body.
+- A genuinely standalone form keeps its submit inside the same `form.group` as
+  its visible fields.
+- Parents own rhythm: stacked fields always sit inside `FieldGroup`
+  (`form.group` on the builder, or `render NitroKit::FieldGroup.new`). Fields
+  rendered as bare siblings of the `form` element stack with no gap — that is
+  an authoring mistake, not a layout the field can correct itself.
+- Wrap the form in a Turbo Frame only when it is embedded in a larger screen
+  and needs an independent lifecycle.
+
+## Phlex form
+
+```ruby
+module UI
+  class ProjectForm < Phlex::HTML
+    include Phlex::Rails::Helpers::FormWith
+
+    def initialize(
+      project,
+      form_id: ActionView::RecordIdentifier.dom_id(project, :form)
+    )
+      @project = project
+      @form_id = form_id
+    end
+
+    def view_template
+      render NitroKit::FormSection.new(
+        title: project.persisted? ? "Edit project" : "New project",
+        description: "Project details are visible to every workspace member."
+      ) do |section|
+        section.form do
+          form_with(
+            model: project,
+            builder: NitroKit::FormBuilder,
+            id: form_id
+          ) do |form|
+            form.group do
+              form.field(:name, required: true, autofocus: true)
+              form.field(
+                :status,
+                as: :select,
+                options: Project.statuses.keys.map do |value|
+                  [ value.humanize, value ]
+                end
+              )
+              form.field(:description, as: :textarea)
+            end
+          end
+        end
+      end
+    end
+
+    private
+      attr_reader :project, :form_id
+  end
+end
+```
+
+In an application shell, render exactly one primary submit in the route
+toolbar and associate it with `form_id`:
+
+```ruby
+Button(
+  project.persisted? ? "Save project" : "Create project",
+  type: :submit,
+  form: form_id,
+  variant: :primary,
+  data: { turbo_submits_with: "Saving…" }
+)
+```
+
+Do not also call `form.submit` in the form body. Use an in-form submit only
+when the form is genuinely standalone and has no toolbar action; put that
+submit inside the same `form.group` as its visible fields.
+
+## Controller
+
+Render the same invalid object with 422. Redirect successful HTML submissions with 303.
+
+```ruby
+class ProjectsController < ApplicationController
+  def create
+    @project = Current.account.projects.build(project_params)
+
+    if @project.save
+      redirect_to @project, status: :see_other, notice: "Project created"
+    else
+      render UI::ProjectForm.new(@project), status: :unprocessable_entity
+    end
+  end
+
+  def update
+    @project = Current.account.projects.find(params[:id])
+
+    if @project.update(project_params)
+      redirect_to @project, status: :see_other, notice: "Project updated"
+    else
+      render UI::ProjectForm.new(@project), status: :unprocessable_entity
+    end
+  end
+
+  private
+    def project_params
+      params.expect(project: [:name, :status, :description])
+    end
+end
+```
+
+The same response works with Turbo Drive and without it. Wrap this component in a stable Turbo Frame only when the form is embedded in a larger screen and should have an independent lifecycle; [inline edit](inline_edit.md) shows that boundary. Add a Turbo Stream branch only when success must update multiple regions instead of navigating.
+
+## Tests
+
+Assert 303 plus the redirect and flash on success. Assert 422, the submitted value, and the model error on failure. For an embedded form, also assert the stable frame ID. Add a system test for focus or multi-region effects, not merely to restate controller behavior.

data/docs/rails_conventions.md

@@ -0,0 +1,95 @@
+# The Nitro Kit Rails path
+
+Nitro Kit 2 follows one conventional Rails path so application code, UI, and
+agent output compose predictably. Treat this as the greenfield default. In an
+existing application, preserve established conventions unless the task
+explicitly includes changing them.
+
+## Model the domain with Rails
+
+- Put business rules on domain models. Do not introduce a service, form,
+  command, or policy object until a real boundary requires one.
+- Scope tenant-owned records through `Current.team` or `Current.account`.
+  Record `Current.user` as the actor or creator instead of using the user as
+  the tenancy boundary.
+- For a new team-aware application, use `User`, `Team`, and `Membership` from
+  the first signup. Put roles on the membership and create the first user's
+  team plus owner membership in the same transaction. Read
+  `docs/patterns/application_foundation.md` before adding authentication,
+  invitations, team administration, or account settings.
+- Represent meaningful lifecycle state with a record when the state has
+  identity, timing, provenance, or behavior. A published post has a
+  `Post::Publication`; it is not merely a `published` boolean.
+- Name capability concerns with adjectives such as `Publishable` only after
+  more than one model shares the behavior. Keep the first implementation on
+  the model that owns it.
+
+## Route nouns, not commands
+
+Map controllers to REST resources. When an action does not fit the seven
+standard actions, look for the missing noun:
+
+```ruby
+namespace :admin do
+  resources :posts do
+    resource :publication, only: %i[create destroy],
+      module: :posts
+  end
+end
+```
+
+`Admin::Posts::PublicationsController#create` publishes and `#destroy`
+unpublishes. Keep controllers thin: load through the tenant boundary, invoke a
+domain method, then render or redirect.
+
+Use the authenticated admin `show` action as the operational detail or draft
+preview unless the product truly has another independently addressable
+representation. Public controllers must query only records visible to the
+public.
+
+## Use ordinary Rails responses
+
+- Use `form_with` and `NitroKit::FormBuilder` for model-backed forms.
+- Redirect successful non-GET submissions with `status: :see_other`.
+- Render the same invalid model with `status: :unprocessable_entity`.
+- Keep an HTML response for every Turbo-enhanced flow.
+- Keep filtering, sorting, and pagination in GET parameters.
+- Set flash on the server and render it through
+  `NitroKit::Toast::FlashMessages`.
+
+## Compose CRUD as one page
+
+For an authenticated admin or product area, prefer the hybrid `AppShell` with
+a `Toolbar` in its topbar. The shell supplies responsive navigation disclosure;
+the toolbar supplies the route's one `h1` and its basic actions. The application
+owns one content gutter immediately inside the shell main region.
+
+Do not repeat the route title in a `PageHeader`, section heading, card title,
+and table caption. Use `PageHeader` inside an application shell only when the
+page needs a genuinely content-led introduction beyond the toolbar title. A
+single-table index renders the table directly. A form page begins with the
+actual `FormSection`. A detail page begins with status or metadata. Use a Card
+only for a bounded object that needs a surface, never as the automatic wrapper
+for every region.
+
+Read `docs/patterns/crud_resource.md` before building a complete resource.
+
+## Keep the browser thin
+
+Render HTML on the server. Use Turbo Drive by default, Frames for one stable
+region, request Streams for multi-target responses, broadcasts for other
+sessions, and Stimulus only for browser-owned behavior. Do not create a JSON
+API or client-side state store for an ordinary Rails screen.
+
+## Test the contract
+
+Use Minitest and fixtures. Cover:
+
+- tenant isolation and role differences;
+- public visibility of drafts and published records;
+- successful `303` redirects and invalid `422` renders;
+- the noun resource that creates or removes lifecycle state;
+- the HTML fallback before adding a system test;
+- browser behavior with Capybara waiting assertions, never sleeps.
+
+Prefer a small complete test over layers of factories, mocks, and helper DSLs.