nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.4

data/docs/patterns/queryable_collection.md

@@ -1,187 +1,91 @@
 # 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.
+**Audience:** Coding agents and developers implementing filters, sorting, and
+pagination with Turbo Frames.
 
 ## 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.
+- One GET-driven Turbo Frame owns filters, sorting, results, and pagination;
+  URL parameters are the state.
+- An application query object owns allowlists, defaults, tenant scope, and page
+  bounds; `NitroKit::Table` owns no query policy.
+- Pagination advances browser history; filters, reset, and sorting replace the
+  current history entry.
+- Every response contains the same frame, including empty results; links that
+  leave the collection target `_top`.
+
+## Query contract
+
+Build the query from a tenant-scoped relation:
 
 ```ruby
-class ProjectsController < ApplicationController
-  def index
-    @query = ProjectsQuery.new(Project.all, params: params.fetch(:q, {}), page: params[:page])
-  end
+def index
+  @query = ProjectsQuery.new(
+    Current.account.projects,
+    params: params.fetch(:q, {}),
+    page: params[:page]
+  )
 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.
+The query object owns parameter allowlists, default ordering, page bounds, and
+query URL generation. It may expose `records`, `filters`, `current_sort`,
+`direction`, `sort_url(key)`, `pagination`, and `summary`. Ransack is one
+possible implementation, not a Nitro dependency.
 
-## Phlex region
+## Frame composition
 
 ```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
+FRAME_ID = "projects-results"
+
+turbo_frame_tag(FRAME_ID, data: { turbo_action: "advance" }) do
+  form_with(
+    scope: :q,
+    url: projects_path,
+    method: :get,
+    builder: NitroKit::FormBuilder,
+    data: { turbo_frame: FRAME_ID, turbo_action: "replace" }
+  ) do |form|
+    form.group do
+      form.field(:name_cont, as: :search, label: "Search")
+      form.submit("Apply filters")
     end
+  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
+  render NitroKit::Table.new(
+    sort: query.current_sort,
+    direction: query.direction
+  ) do |table|
+    table.caption("Projects")
+    table.thead do
+      table.tr do
+        table.th(:name, sort: :name, href: query.sort_url(:name),
+          sort_data: { turbo_action: "replace" })
       end
     end
+    table.tbody do
+      query.records.each { |project| render_project_row(table, project) }
+    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
+  render NitroKit::PaginationBar.new do |bar|
+    bar.summary(query.summary)
+    bar.pagination(query.pagination)
   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.
+Reset with the plain collection URL so stale parameters disappear. Sort and
+filter controls use `turbo_action: "replace"`; pagination inherits the frame's
+`advance`. Give View, Edit, and New links
+`data: { turbo_frame: "_top" }` or place them outside the frame.
 
-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.”
+No Stimulus controller is required. Optional autosubmit may call the same GET
+form's `requestSubmit`; the URL remains the source of truth.
 
 ## 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.
+Request-test parameter preservation, safe fallback for invalid sort keys, and
+the stable frame in populated and empty responses. System-test filter → sort →
+paginate → Back/Forward, address-bar changes, and a row link leaving the frame.
+Use Capybara waiting assertions, not sleeps.

data/docs/patterns/resource_form.md

@@ -1,126 +1,78 @@
 # 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.
+**Audience:** Coding agents and developers implementing model-backed create
+and update forms.
 
 ## 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.
+- One model-backed Phlex component renders initial and invalid states.
+- Rails owns names, values, and errors; Nitro owns presentation.
+- Invalid mutations render the same model with `422`; success redirects with
+  `303`.
+- Use one primary submit: the shell toolbar owns it, or a standalone form keeps
+  it inside `form.group`.
+- Wrap the form in a Turbo Frame only when it needs an independent lifecycle.
 
-## Phlex form
+## Form
 
 ```ruby
 module UI
   class ProjectForm < Phlex::HTML
     include Phlex::Rails::Helpers::FormWith
 
-    def initialize(
-      project,
-      form_id: ActionView::RecordIdentifier.dom_id(project, :form)
-    )
+    def initialize(project, form_id:)
       @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|
+      render NitroKit::SettingsSection.new(title: "Project details") do |section|
         section.form do
           form_with(
-            model: project,
+            model: @project,
             builder: NitroKit::FormBuilder,
-            id: form_id
+            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(:name, required: true)
+              form.field(:status, as: :select, options: Project.statuses.keys)
               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`:
+In an application shell, render one toolbar submit associated through the
+native form ID:
 
 ```ruby
-Button(
-  project.persisted? ? "Save project" : "Create project",
-  type: :submit,
-  form: form_id,
-  variant: :primary,
-  data: { turbo_submits_with: "Saving…" }
-)
+Button("Save project", type: :submit, form: form_id, variant: :primary)
 ```
 
-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
+Do not also call `form.submit` in the body. A standalone form without a toolbar
+keeps its submit in the same `form.group` as its visible fields.
 
-Render the same invalid object with 422. Redirect successful HTML submissions with 303.
+## Responses
 
 ```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
+if @project.update(project_params)
+  redirect_to @project, status: :see_other, notice: "Project updated"
+else
+  render UI::ProjectForm.new(@project, form_id:),
+    status: :unprocessable_entity
 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.
+Wrap the component in a stable frame only when embedded in a larger screen.
+Use a Turbo Stream only when success updates multiple regions. See
+[Inline edit](inline_edit.md).
 
 ## 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.
+Assert redirect and flash at `303`; submitted values and model errors at `422`;
+and the stable frame ID when embedded. Add a system test for focus or
+multi-region behavior, not to repeat controller coverage.

data/docs/rails_conventions.md

@@ -1,95 +1,58 @@
-# The Nitro Kit Rails path
+# Rails conventions for Nitro Kit applications
 
-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.
+**Audience:** Coding agents and developers building Rails application features
+with Nitro Kit. These are greenfield defaults; preserve established application
+conventions unless the task explicitly changes them.
 
-## Model the domain with Rails
+## Domain and tenancy
 
-- 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.
+- Put business rules on domain models. Add service, form, command, or policy
+  objects only when a real boundary requires one.
+- Scope tenant-owned records through `Current.team` or `Current.account`. Use
+  `Current.user` as the actor, not the tenancy boundary.
+- For team-aware products, model `User`, `Team`, and `Membership`; roles belong
+  to memberships. See [Application foundation](patterns/application_foundation.md).
+- Model lifecycle state as a record when it has identity, timing, provenance,
+  or behavior.
 
-## Route nouns, not commands
+## Routes and responses
 
-Map controllers to REST resources. When an action does not fit the seven
-standard actions, look for the missing noun:
+Use REST resources. When an action does not fit the seven standard actions,
+find the missing noun:
 
 ```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
 ```
 
-`Admin::Posts::PublicationsController#create` publishes and `#destroy`
-unpublishes. Keep controllers thin: load through the tenant boundary, invoke a
-domain method, then render or redirect.
+Keep controllers thin: load through the tenant boundary, invoke the model, and
+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`.
+- Use `form_with(..., builder: NitroKit::FormBuilder)` for model-backed forms.
+- Redirect successful mutations with `status: :see_other`.
 - Render the same invalid model with `status: :unprocessable_entity`.
-- Keep an HTML response for every Turbo-enhanced flow.
+- Keep an HTML response for Turbo-enhanced flows.
 - Keep filtering, sorting, and pagination in GET parameters.
-- Set flash on the server and render it through
+- Set Rails flash on the server and render it once 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
+See [Browser support](browser_support.md) for native month and week input
+limitations, and [Hotwire](hotwire.md) for transport choices.
 
-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.
+## Page composition
 
-## Test the contract
+Use one route title, normally the shell toolbar's `h1`. Add another heading
+only for a genuinely separate region. Do not repeat the title across a toolbar,
+PageHeader, section, Card, and table caption.
 
-Use Minitest and fixtures. Cover:
+Use Card for a bounded object that needs a surface, not as a default wrapper.
+Use one application-owned content gutter inside the shell main region. See
+[Complete product resource](patterns/crud_resource.md) for CRUD composition.
 
-- 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.
+## Tests
 
-Prefer a small complete test over layers of factories, mocks, and helper DSLs.
+Use Minitest and fixtures. Cover tenant isolation, authorization differences,
+lifecycle resources, public visibility, `303` success, `422` validation, and
+the HTML fallback. Add browser tests for behavior that request tests cannot
+prove, using Capybara waiting assertions instead of sleeps.