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

data/app/components/nitro_kit/accordion.rb

@@ -106,25 +106,7 @@ module NitroKit
     end
 
     def chevron
-      svg(
-        **slot_attributes(
-          :icon,
-          attributes: {
-            viewbox: "0 0 16 16",
-            width: 16,
-            height: 16,
-            fill: "none",
-            stroke: "currentColor",
-            stroke_width: 1.5,
-            stroke_linecap: "round",
-            stroke_linejoin: "round",
-            focusable: "false",
-            aria: { hidden: true }
-          }
-        )
-      ) do |svg|
-        svg.path(d: "m4 6 4 4 4-4")
-      end
+      render_in_slot(Icon.new(:chevron_down, size: :sm), :icon)
     end
 
     def trigger_id(item)

data/app/components/nitro_kit/alert.rb

@@ -2,17 +2,7 @@
 
 module NitroKit
   class Alert < Component
-    VARIANTS = %i[default info success warning error].freeze
-
-    # The palette family each semantic variant borrows in `palette.css`.
-    # Alert owns this mapping; it is not the Badge color axis.
-    VARIANT_PALETTE = {
-      default: :zinc,
-      info: :blue,
-      success: :green,
-      warning: :amber,
-      error: :red
-    }.freeze
+    VARIANTS = %i[default info success warning destructive].freeze
 
     LIVE_MODES = %i[off polite assertive].freeze
 

data/app/components/nitro_kit/app_navigation.rb

@@ -5,8 +5,8 @@ module NitroKit
     alias_method :html_header, :header
     alias_method :html_footer, :footer
 
-    Item = ::Data.define(:text, :href, :icon, :badge, :current, :html, :aria, :data, :css_class)
-    Section = ::Data.define(:label, :entries)
+    Item = ::Data.define(:text, :href, :icon, :icon_end, :badge, :current, :html, :aria, :data, :css_class)
+    Section = ::Data.define(:label, :entries, :collapsible, :expanded)
     Entry = ::Data.define(:kind)
 
     def initialize(
@@ -78,10 +78,16 @@ module NitroKit
       nil
     end
 
-    def section(label: nil, &content)
+    def section(label: nil, collapsible: false, expanded: true, &content)
       ensure_phase!(:body, :section)
       raise ArgumentError, "AppNavigation section requires a block" unless content
 
+      collapsible = validate_boolean!(:collapsible, collapsible)
+      expanded = validate_boolean!(:expanded, expanded)
+      if collapsible && label.nil?
+        raise ArgumentError, "AppNavigation collapsible section requires a label"
+      end
+
       entries = []
       previous_entries = @entry_target
       previous_phase = @phase
@@ -94,7 +100,12 @@ module NitroKit
         unless entries.any?(Item)
           raise ArgumentError, "AppNavigation section requires at least one item"
         end
-        previous_entries << Section.new(label: validate_optional_text!(:label, label), entries:)
+        previous_entries << Section.new(
+          label: validate_optional_text!(:label, label),
+          entries:,
+          collapsible:,
+          expanded:
+        )
         nil
       ensure
         @entry_target = previous_entries
@@ -106,6 +117,7 @@ module NitroKit
       text,
       href:,
       icon: nil,
+      icon_end: nil,
       badge: nil,
       badge_color: :neutral,
       current: false,
@@ -118,6 +130,7 @@ module NitroKit
       text = validate_text!(:text, text)
       href = validate_text!(:href, href)
       icon = item_icon(icon)
+      icon_end = item_icon(icon_end, name: :icon_end)
       badge = item_badge(badge, badge_color)
       current = validate_boolean!(:current, current)
 
@@ -130,6 +143,7 @@ module NitroKit
         text:,
         href:,
         icon:,
+        icon_end:,
         badge:,
         current:,
         html:,
@@ -205,13 +219,33 @@ module NitroKit
 
     def render_section(entry)
       li(**slot_attributes(:section)) do
-        span(**slot_attributes(:section_label)) { plain(entry.label) } if entry.label
-        ul(**slot_attributes(:section_list, attributes: section_list_attributes(entry))) do
-          entry.entries.each { |child| render_entry(child) }
+        if entry.collapsible
+          details(
+            **slot_attributes(:section_disclosure, attributes: { open: entry.expanded })
+          ) do
+            summary(**slot_attributes(:section_label)) do
+              plain(entry.label)
+              section_chevron
+            end
+            render_section_list(entry)
+          end
+        else
+          span(**slot_attributes(:section_label)) { plain(entry.label) } if entry.label
+          render_section_list(entry)
         end
       end
     end
 
+    def render_section_list(entry)
+      ul(**slot_attributes(:section_list, attributes: section_list_attributes(entry))) do
+        entry.entries.each { |child| render_entry(child) }
+      end
+    end
+
+    def section_chevron
+      render_in_slot(Icon.new(:chevron_down, size: :xs), :section_icon)
+    end
+
     def section_list_attributes(entry)
       entry.label ? { aria: { label: entry.label } } : {}
     end
@@ -234,6 +268,7 @@ module NitroKit
           render_in_slot(entry.icon, :item_icon) if entry.icon
           span(**slot_attributes(:item_label)) { plain(entry.text) }
           render_in_slot(entry.badge, :item_badge) if entry.badge
+          render_in_slot(entry.icon_end, :item_icon_end) if entry.icon_end
         end
       end
     end
@@ -277,10 +312,10 @@ module NitroKit
       validate_text!(name, value)
     end
 
-    def item_icon(value)
+    def item_icon(value, name: :icon)
       return if value.nil?
       unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
-        raise ArgumentError, "icon must be a non-blank String or Symbol"
+        raise ArgumentError, "#{name} must be a non-blank String or Symbol"
       end
 
       Icon.new(value, size: :sm)

data/app/components/nitro_kit/appearance_picker.rb

@@ -13,6 +13,7 @@ module NitroKit
     def initialize(
       id:,
       label: I18n.t("nitro_kit.appearance_picker.label"),
+      label_visible: true,
       presentation: :segmented,
       preference: :system,
       html: {},
@@ -22,13 +23,21 @@ module NitroKit
     )
       @identifier = validate_id!("AppearancePicker id", id)
       @label = validate_label!(label)
+      @label_visible = validate_boolean!(:label_visible, label_visible)
       @presentation = validate_choice!(:presentation, presentation, PRESENTATIONS)
       @preference = validate_choice!(:preference, preference, PREFERENCES)
+      if !@label_visible && @presentation != :segmented
+        raise ArgumentError,
+          "AppearancePicker label_visible: false requires the segmented presentation"
+      end
 
       super(
         component: :appearance_picker,
         attributes: {
           id: @identifier,
+          # Browsers give legends special layout, so a hidden label omits the
+          # element entirely and the fieldset keeps its name through ARIA.
+          aria: @label_visible ? {} : { label: @label },
           data: {
             controller: "nk--appearance",
             presentation: @presentation,
@@ -50,7 +59,7 @@ module NitroKit
       return render_dropdown if @presentation == :dropdown
 
       fieldset(**root_attributes) do
-        legend(**slot_attributes(:legend)) { plain(@label) }
+        legend(**slot_attributes(:legend)) { plain(@label) } if @label_visible
         div(**slot_attributes(:options)) do
           PREFERENCES.each { |preference| render_option(preference) }
         end

data/app/components/nitro_kit/badge.rb

@@ -4,16 +4,25 @@ module NitroKit
   class Badge < Component
     VARIANTS = %i[default outline].freeze
     SIZES = %i[xs sm md].freeze
-    COLORS = %i[
-      zinc red orange amber yellow lime green emerald teal cyan sky blue indigo
-      violet purple fuchsia pink rose neutral info success warning danger
+    # Two axes on one option, both public and both themeable.
+    #
+    # The semantic families follow the `--nk-palette-{family}` tint roles, so
+    # they move with an application's brand: retheme `--nk-palette-destructive` and
+    # every `destructive` badge follows. The decorative hues follow the
+    # `--nk-palette-{hue}` roles and stay the color they name, for categorical
+    # labelling where meaning is not the point.
+    SEMANTIC_COLORS = %i[neutral info success warning destructive].freeze
+    PALETTE_COLORS = %i[
+      red orange amber yellow lime green emerald teal cyan sky blue indigo
+      violet purple fuchsia pink rose
     ].freeze
+    COLORS = (PALETTE_COLORS + SEMANTIC_COLORS).freeze
 
     def initialize(
       text = nil,
       variant: :default,
       size: :md,
-      color: :zinc,
+      color: :neutral,
       id: nil,
       html: {},
       aria: {},

data/app/components/nitro_kit/combobox.rb

@@ -117,23 +117,7 @@ module NitroKit
           :input
         )
 
-        svg(
-          **slot_attributes(
-            :icon,
-            attributes: {
-              viewbox: "0 0 16 16",
-              width: 16,
-              height: 16,
-              fill: "none",
-              stroke: "currentColor",
-              stroke_width: 1.5,
-              stroke_linecap: "round",
-              stroke_linejoin: "round",
-              focusable: "false",
-              aria: { hidden: true }
-            }
-          )
-        ) { |svg| svg.path(d: "m4 6 4 4 4-4") }
+        render_in_slot(Icon.new(:chevron_down, size: :sm), :icon)
       end
     end
 

data/app/components/nitro_kit/command_palette.rb

@@ -254,6 +254,7 @@ module NitroKit
               nk__dialog_target: "panel",
               nk__command_palette_target: "panel",
               action: [
+                "command->nk--command-palette#guardOpen",
                 "click->nk--dialog#dismiss",
                 "cancel->nk--dialog#cancel",
                 "close->nk--dialog#restoreFocus",

data/app/components/nitro_kit/dropzone.rb

@@ -44,7 +44,7 @@ module NitroKit
       name:,
       label: I18n.t("nitro_kit.dropzone.label"),
       description: nil,
-      presentation: :input,
+      presentation: :minimal,
       direct_upload: true,
       multiple: false,
       accept: nil,

data/app/components/nitro_kit/form_builder.rb

@@ -115,7 +115,7 @@ module NitroKit
       id: nil,
       label: I18n.t("nitro_kit.dropzone.label"),
       description: nil,
-      presentation: :input,
+      presentation: :minimal,
       direct_upload: true,
       multiple: false,
       accept: nil,

data/app/components/nitro_kit/select.rb

@@ -77,20 +77,7 @@ module NitroKit
     def render_toggle_icon
       return if @multiple
 
-      svg(
-        **slot_attributes(
-          :icon,
-          attributes: {
-            viewbox: "0 0 20 20",
-            fill: "none",
-            stroke: "currentColor",
-            stroke_width: 1.5,
-            aria: { hidden: true }
-          }
-        )
-      ) do |icon|
-        icon.path(d: "m6.5 8 3.5 3.5L13.5 8", stroke_linecap: "round", stroke_linejoin: "round")
-      end
+      render_in_slot(Icon.new(:chevron_down, size: :sm), :icon)
     end
 
     def control_attributes

data/app/components/nitro_kit/tabs.rb

@@ -140,6 +140,7 @@ module NitroKit
             data: {
               key: tab.key,
               state: active ? "active" : "inactive",
+              action: "beforematch->nk--tabs#reveal",
               nk__tabs_target: "panel"
             }
           }

data/app/javascript/controllers/nk/command_palette_controller.js

@@ -68,6 +68,10 @@ export default class extends Controller {
     this.openTimer = setTimeout(() => this.#prepareOpenPanel(), 0);
   }
 
+  guardOpen(event) {
+    if (event.command === "show-modal" && !this.canOpen) event.preventDefault();
+  }
+
   shortcut(event) {
     if (
       event.defaultPrevented ||

data/app/javascript/controllers/nk/tabs_controller.js

@@ -42,6 +42,14 @@ export default class extends Controller {
     }
   }
 
+  reveal(event) {
+    const tab = this.tabTargets.find(
+      (candidate) => candidate.dataset.key === event.currentTarget.dataset.key,
+    );
+
+    if (tab && !tab.disabled) this.activeValue = tab.dataset.key;
+  }
+
   navigate(event) {
     const rightToLeft = getComputedStyle(this.element).direction === "rtl";
     const directionKeys =
@@ -143,11 +151,15 @@ export default class extends Controller {
 
     this.panelTargets.forEach((panel) => {
       const active = panel.dataset.key === value;
+      const tab = this.tabTargets.find(
+        (candidate) => candidate.dataset.key === panel.dataset.key,
+      );
 
-      panel.hidden = !active;
       if (active) {
+        panel.removeAttribute("hidden");
         panel.setAttribute("aria-hidden", "false");
       } else {
+        panel.setAttribute("hidden", tab?.disabled ? "" : "until-found");
         panel.removeAttribute("aria-hidden");
       }
       panel.dataset.state = active ? "active" : "inactive";

data/docs/agent_guide.md

@@ -1,8 +1,10 @@
-# Building applications with Nitro Kit
+# Nitro Kit application guide for coding agents
 
-This is the routing guide for coding agents working in a Rails application that uses Nitro Kit. It describes how to find the installed contract, select components, and apply the same Rails and Hotwire conventions across features.
+**Audience:** Coding agents changing a Rails application that uses Nitro Kit.
+Humans should start with the [README](../README.md) and
+[Rails integration guide](rails_integration.md).
 
-## Start from the installed version
+## Resolve the installed version
 
 From the application root, run:
 
@@ -10,145 +12,68 @@ From the application root, run:
 bundle show nitro_kit
 ```
 
-Read this guide from that directory, then consult only the reference needed for the task:
-
-| Task                                        | Read next                                 |
-| ------------------------------------------- | ----------------------------------------- |
-| Rails models, routes, CRUD, and tests       | `docs/rails_conventions.md`               |
-| Authentication, teams, shell, and settings  | `docs/patterns/application_foundation.md` |
-| Build a complete product resource           | `docs/patterns/crud_resource.md`          |
-| Choose or compose UI                        | `docs/component_contracts.md`             |
-| Rails assets, forms, and application shells | `docs/rails_integration.md`               |
-| Turbo, Frames, Streams, morphs, or Stimulus | `docs/hotwire.md`                         |
-| Browser support or progressive fallback     | `docs/browser_support.md`                 |
-| Theme tokens and application composition    | `docs/customization.md`                   |
-| Upgrade an existing Nitro Kit 1.x app       | `docs/migration_1_to_2.md`                |
-| Query, sort, filter, or paginate            | `docs/patterns/queryable_collection.md`   |
-| Create, update, and show validation         | `docs/patterns/resource_form.md`          |
-| Delete, revoke, archive, or confirm         | `docs/patterns/destructive_action.md`     |
-| Flash messages and notifications            | `docs/patterns/flash_and_toast.md`        |
-| Edit and cancel inside a page               | `docs/patterns/inline_edit.md`            |
-
-The installed component source is the final authority for constructor and compound-method details. This guide describes Nitro Kit 2.x. Do not use an API remembered from Nitro Kit 1.x or another installed version.
-
-## Select the highest-level matching component
-
-Prefer the component that owns the whole region, then compose smaller components inside it.
-
-| Product need                     | Begin with                                                    |
-| -------------------------------- | ------------------------------------------------------------- |
-| Application chrome               | `AppShell`, `AppNavigation`, `CommandPalette`                 |
-| Authentication page              | `AuthShell`                                                   |
-| Settings navigation              | `SettingsLayout`                                              |
-| Team or account administration   | `AppShell`, `Toolbar`, `Table`, `SettingsSection`             |
-| App page title and basic actions | `AppShell`, then `Toolbar`                                    |
-| Content-led page introduction    | `PageHeader`                                                  |
-| Data region                      | `DataSection`, then `Table` or `EmptyState`                   |
-| Queryable tabular data           | `Table`, `Toolbar`, `PaginationBar`                           |
-| Model-backed form                | `SettingsSection`, Rails `form_with`, `NitroKit::FormBuilder` |
-| Destructive settings             | `DangerZone`, optionally `Dialog`                             |
-| Transient server feedback        | `Toast::FlashMessages`                                        |
-| Rendered Markdown or rich text   | `Container`, then `Typeset`                                   |
-| General grouping                 | `Card`, `Flex`, `Grid`, `Container`                           |
-
-Application-specific product UI belongs under the application's namespace and composes Nitro components. Nitro owns component markup, styles, accessibility structure, and narrowly scoped progressive behavior. The application owns product policy, records, routes, authorization, queries, DOM IDs, and server responses.
-
-For admin CRUD, treat the starter and entitled flows as complete compositions:
-use toolbar Back links on child routes, keep deletion on edit, keep status in
-the details flow, implement full invitation and membership management, and use
-native links for settings destinations. Do not stop after rendering a screen
-that only looks structurally similar.
-
-## Preserve controls during migration
-
-Before changing a 1.x application, read `docs/migration_1_to_2.md`. Inventory
-user-facing flows and behavior before mapping helpers. When the Nitro Kit MCP
-catalog is available, search by product workflow rather than old component
-name, then prefer the highest-level matching composition before replacing
-atoms.
-
-After establishing that inventory, generate the host integration smoke tests
-from the currently bundled gem with `bin/rails generate
-nitro_kit:upgrade_smoke_tests`. The generator preserves existing files and
-skips missing Rails Minitest or system-test infrastructure with setup guidance.
-Keep the generated explanatory header in each test: these are host-integration
-regression checks, not substitutes for application-specific acceptance tests.
-Run supported generated tests before and after the application conversion,
-while retaining application-specific acceptance coverage for every inventoried
-flow. Customize each generated `prepare_nitro_kit_upgrade_smoke_test` method
-with host sign-in and account-selection helpers when `ApplicationController`
-requires them; do not disable the host callbacks.
-
-In an existing application, replace a form control only when the installed
-Nitro Kit catalog provides a genuine semantic and behavioral equivalent.
-Preserve its parameter name, IDs, values, errors, accessibility, uploads, and
-browser behavior. If no equivalent exists, keep or re-express the control as
-application-owned Rails and semantic HTML, optionally inside a custom
-`form.field` composition. Never downgrade an editor, autocomplete, date range,
-upload, or other specialized input to the nearest generic Nitro control merely
-for visual consistency.
-
-Do not retain copied Nitro Kit 1.x source as the fallback. Remove the legacy
-component and preserve the unsupported behavior in clearly application-owned
-code. Report the missing equivalent as a Nitro Kit coverage gap.
-
-At the end of a migration, search the whole application for
-`desperately_need_a_class:` and review every result. Aim for zero rather than
-translating old utility classes mechanically. Move application layout and
-visual treatment to wrappers, use semantic component options or native
-attributes, accept incidental Nitro defaults, and keep unmatched product UI
-application-owned. Remove generic class forwarding from shared builders.
-Retain an escape only for a named external integration that requires a class
-hook, and record that reason in the migration review.
-
-## Use one interaction grammar
-
-Choose the smallest primitive that completes the interaction:
-
-1. Ordinary Rails links and forms under Turbo Drive.
-2. A Turbo Frame for one independently navigable or replaceable region.
-3. A request-scoped Turbo Stream response when one action changes multiple regions.
-4. A broadcast only when other sessions must receive the change.
-5. Application Stimulus only for browser-only behavior the preceding layers cannot express.
-
-Successful non-GET HTML submissions redirect with `303 See Other`. Invalid form submissions render the same invalid model with `422 Unprocessable Entity`. GET parameters remain the source of truth for queryable collections. Frame identifiers come from `dom_id` or one named constant shared by rendering, responses, and tests.
-
-## Stay inside the public boundary
+Read this guide from that directory. The installed
+[component contracts](component_contracts.md) define the public API.
+
+| Task                                               | Read                                                         |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| Rails models, routes, CRUD, and tests              | [Rails conventions](rails_conventions.md)                    |
+| Authentication, teams, shell, and settings         | [Application foundation](patterns/application_foundation.md) |
+| Complete product CRUD                              | [CRUD resource](patterns/crud_resource.md)                   |
+| Components and composition                         | [Component contracts](component_contracts.md)                |
+| Installation, assets, forms, and Rails integration | [Rails integration](rails_integration.md)                    |
+| Turbo, Frames, Streams, morphs, or Stimulus        | [Hotwire](hotwire.md)                                        |
+| Browser compatibility or fallback behavior         | [Browser support](browser_support.md)                        |
+| Theme tokens and application CSS                   | [Customization](customization.md)                            |
+| Nitro Kit 1.x upgrade                              | [Migration guide](migration_1_to_2.md)                       |
+| Query, sort, filter, or paginate                   | [Queryable collection](patterns/queryable_collection.md)     |
+| Create, update, and validation                     | [Resource form](patterns/resource_form.md)                   |
+| Delete, revoke, archive, or confirm                | [Destructive action](patterns/destructive_action.md)         |
+| Flash messages and notifications                   | [Flash and toast](patterns/flash_and_toast.md)               |
+| Edit and cancel inside a page                      | [Inline edit](patterns/inline_edit.md)                       |
+
+Before changing a Nitro Kit 1.x application, read the migration guide. Do not
+infer 2.x APIs from memory or old application code.
+
+## Preserve the application's architecture
+
+For a greenfield application, run:
+
+```sh
+bin/rails generate phlex:install
+```
+
+Use Phlex for the application layout, route views, and reusable UI. In an established
+application, preserve its view architecture and introduce Phlex only at the
+requested boundary. Do not perform an application-wide migration unless it is
+explicitly authorized.
+
+## Stay within the public API
 
 - Include `NitroKit` once in the application's base Phlex component and use
-  capitalized Kit methods such as `Button(...)` and `Card(...)`.
-- Use the scoped `NitroKit::Button(...)` form when inclusion is not appropriate.
-- Use an explicit constructor such as `Button.new(...)` only when another API
-  needs a component object; Kit methods render immediately.
-- Select `NitroKit::FormBuilder` explicitly from Rails `form_with`.
-- Put a standalone form's visible fields, submit control, and related links
-  inside `form.group`; hidden fields may remain before the group.
-- Parents own rhythm. Wrap stacked fields in `FieldGroup` — as
-  `render NitroKit::FieldGroup.new { ... }`, or `form.group` inside a
-  `form_with` block. Two Fields, or a Field and its submit Button, rendered as
-  bare siblings of a `form` or a plain `div` have no gap between them at all.
-  Use `Flex` or `Grid` instead only when the arrangement is deliberately
-  inline or multi-column.
-- Use component options, compound declarations, layouts, and documented `--nk-*` theme properties.
-- Keep an HTML fallback for every Turbo form flow.
-- Treat that HTML response as a Turbo transport fallback, not automatically a
-  JavaScript-free interaction; use `docs/browser_support.md` for the canonical
-  component classifications.
-- Test semantic output and stable owned attributes.
-
-Do not copy component source, add `nk_*` helpers, invent a general ERB bridge, mutate Nitro-owned Stimulus controllers, or pass `class:` and `style:`. The intentionally loud `desperately_need_a_class:` escape exists only for external integrations that require a class hook.
-
-## Application `AGENTS.md`
-
-Install the durable project instruction and local skills from the consuming
-application root:
+  Kit methods such as `Button(...)` and `Card(...)`.
+- Use `NitroKit::Button(...)` when inclusion is inappropriate and `.new` only
+  when another API requires a component object.
+- Select `NitroKit::FormBuilder` explicitly with Rails `form_with`.
+- Put stacked fields and actions in `form.group` or `FieldGroup`.
+- Use documented component options, compound methods, native attributes, and
+  public `--nk-*` tokens.
+- Keep product policy, records, routes, authorization, queries, DOM IDs, and
+  server responses in application code.
+- Do not copy Nitro source, add `nk_*` helpers, mutate Nitro controllers, or
+  pass `class:` or `style:`. Use `desperately_need_a_class:` only for a named
+  external integration that requires a class hook.
+
+Follow the canonical [browser support policy](browser_support.md) for
+JavaScript and fallback guarantees.
+
+## Install project-local guidance
+
+From the consuming application, run:
 
 ```sh
 bin/rails generate nitro_kit:install
 ```
 
-The installer preserves application-owned content around a bounded Nitro Kit 2
-block in `AGENTS.md` and adds project-local Rails, Hotwire, and UI skills for
-supported agents. The skills deliberately resolve the installed gem first, so
-upgrading the gem upgrades the instructions they use. Re-run the generator
-after an upgrade; it never copies component or controller source.
+The installer updates its managed `AGENTS.md` block and local Nitro Kit skills
+without copying component source. Re-run it after upgrading the gem.