nitro_kit 2.0.0.beta.1 → 2.0.0.beta.3

data/docs/customization.md

@@ -4,17 +4,16 @@
 themes or composing application-owned UI. The first sections are task guidance;
 the final token tables are exhaustive reference.
 
-Nitro Kit owns component Ruby, markup, behavior, and default CSS. Applications customize the system by overriding the public `--nk-*` custom properties, composing components into application UI, and occasionally creating a narrow subclass. Applications do not copy or edit Nitro components.
+Nitro Kit owns component Ruby, markup, behavior, and default CSS. Applications normally customize public `--nk-*` properties and compose application UI. When source-level changes are necessary, explicitly [eject one component](eject.md); that isolated snapshot becomes application-owned and stops receiving component updates.
 
 ## Stylesheet order
 
 Load browser styles in this order:
 
 1. Optional third-party base styles, such as Lexxy.
-2. The optional `nitro_kit-tailwind-v4` adapter.
-3. The generated `nitro_kit` distribution stylesheet.
-4. The application's compiled Tailwind CSS, when present.
-5. Application styles, including Nitro token overrides.
+2. The generated `nitro_kit` distribution stylesheet.
+3. The application's compiled Tailwind CSS, when present.
+4. Application styles, including Nitro token overrides.
 
 `NitroKit::AppearanceBootstrap` precedes every entry in this list. The install
 generator applies this order when it can identify conventional layout entries
@@ -34,14 +33,35 @@ A Rails application without Tailwind can use:
 A Tailwind CSS v4 application can use:
 
 ```erb
-<%= stylesheet_link_tag \
-  "nitro_kit-tailwind-v4", \
-  "nitro_kit", \
-  "tailwind", \
-  "application", \
-  "data-turbo-track": "reload" %>
+<%= stylesheet_link_tag "nitro_kit", "tailwind", "application", "data-turbo-track": "reload" %>
 ```
 
+`nitro_kit.css` opens with the global cascade-layer order
+`properties, theme, base, nitro-kit, components, utilities` and aliases Nitro
+tokens onto Tailwind's theme variables, so it must load before the compiled
+Tailwind stylesheet. The separate `nitro_kit-tailwind-v4` adapter from earlier
+2.0 betas no longer exists; `nitro_kit:doctor` reports a leftover link.
+
+A Tailwind CSS v4 application using `tailwindcss-rails` can instead ship one
+stylesheet. Nitro Kit provides the engine entry `tailwindcss-rails` looks for,
+`app/assets/tailwind/nitro_kit/engine.css`, and `tailwindcss:build` or
+`tailwindcss:watch` generates `app/assets/builds/tailwind/nitro_kit.css` in the
+application. Import it before Tailwind in `app/assets/tailwind/application.css`:
+
+```css
+@import "../builds/tailwind/nitro_kit";
+@import "tailwindcss";
+```
+
+Then the layout loads only the compiled Tailwind stylesheet:
+
+```erb
+<%= stylesheet_link_tag "tailwind", "application", "data-turbo-track": "reload" %>
+```
+
+`nitro_kit:doctor` recognizes the import and reports a separate `nitro_kit`
+link as a duplicate.
+
 Keep overrides unlayered in application CSS and load them after Nitro Kit. Nitro's selectors use `:where()` inside named cascade layers, so an ordinary application rule can override a token without selector escalation or `!important`.
 
 Do not edit `app/assets/stylesheets/nitro_kit.css` in the gem or a bundled copy of it. That file is generated from `src/stylesheets/nitro_kit/` and is replaced on upgrade. Variables named `--_nk-*` are private component mechanics and may change without notice. Only the `--nk-*` variables listed below are the customization contract.
@@ -472,9 +492,9 @@ This registers Nitro's `controllers/nk/*` modules together with application cont
 For the resulting behavior when those modules are not registered, use the
 canonical no-JavaScript matrix in [`browser_support.md`](browser_support.md).
 
-## Optional Tailwind CSS v4 adapter
+## Tailwind CSS v4 theme aliases
 
-Nitro Kit does not require Tailwind, Tailwind configuration, or Tailwind Preflight — it ships its own global preflight in the `nitro-kit.reset` cascade layer, which unlayered application CSS always overrides. The optional `nitro_kit-tailwind-v4.css` asset only establishes compatible cascade-layer order and maps Nitro tokens to common Tailwind v4 theme variables, including background, foreground, primary, destructive, radii, shadows, fonts, spacing, and transition defaults.
+Nitro Kit does not require Tailwind, Tailwind configuration, or Tailwind Preflight — it ships its own global preflight in the `nitro-kit.reset` cascade layer, which unlayered application CSS always overrides. For applications that do compile Tailwind, `nitro_kit.css` establishes a compatible cascade-layer order and maps Nitro tokens to common Tailwind v4 theme variables, including background, foreground, primary, destructive, radii, shadows, fonts, spacing, and transition defaults. The aliases live in `src/stylesheets/nitro_kit/tailwind.css` inside the `nitro-kit.tokens` layer; without Tailwind they are inert custom properties.
 
 Tailwind remains compiled and configured by the application. An application can add further aliases in its Tailwind CSS source with the v4 CSS-first API:
 
@@ -488,7 +508,7 @@ Tailwind remains compiled and configured by the application. An application can
 }
 ```
 
-Use `@theme inline` when a Tailwind theme variable references another custom property so generated utilities resolve the live Nitro value. The adapter does not make Tailwind a Nitro runtime dependency, configure source detection, generate utility classes, or permit Tailwind classes inside Nitro component APIs.
+Use `@theme inline` when a Tailwind theme variable references another custom property so generated utilities resolve the live Nitro value. The aliases do not make Tailwind a Nitro runtime dependency, configure source detection, generate utility classes, or permit Tailwind classes inside Nitro component APIs.
 
 ## Public token reference
 
@@ -517,7 +537,7 @@ The following variables are the complete public token set. Theme-independent tok
 | `--nk-title-page-weight`    | Page title weight.                                                   |
 | `--nk-title-section-size`   | Section title size: data, settings, and danger sections.             |
 | `--nk-title-section-weight` | Section title weight.                                                |
-| `--nk-title-surface-size`   | Surface title size: cards, dialogs, sheets, empty states, fieldsets. |
+| `--nk-title-surface-size`   | Surface title size: dialogs, sheets, empty states, fieldsets.        |
 | `--nk-title-surface-weight` | Surface title weight.                                                |
 | `--nk-title-compact-size`   | Compact title size: legends, alert and toast titles.                 |
 | `--nk-title-compact-weight` | Compact title weight.                                                |

data/docs/eject.md

@@ -0,0 +1,86 @@
+# Eject one component
+
+Gem-owned components, token overrides, and composition remain the default.
+Eject is an explicit source-level customization opt-out, never an installation
+step. Free eject turns a gem component into your code; Pro exemplars are already
+your code when retrieved.
+
+```sh
+bin/rails generate nitro_kit:eject Button
+```
+
+Use the ordinary Phlex constructor:
+
+```ruby
+render Ui::EjectedButton::Button.new("Save", icon: :check)
+```
+
+## Files and integration
+
+- `app/components/ui/ejected_button/`: Button, nested slot classes, transitive
+  Ruby component/support dependencies (such as Icon), and an application-owned
+  Component adapter with a snapshot of base component-level helpers.
+- `app/assets/stylesheets/ejected_button.css`: those components' CSS plus shared
+  palette/layout rules where needed, with explicit cascade-layer order.
+- `app/javascript/controllers/ui/ejected_button/`: referenced Stimulus
+  controllers and their local JavaScript imports.
+- `config/nitro_kit/ejected/button.json`: source version, component, namespace,
+  and generated file inventory. Every source file also records the version.
+
+Keep Nitro Kit installed. The attribute/render kernel (`NitroKit::Component`),
+public `--nk-*` tokens, global reset, translations, appearance document runtime,
+and third-party integrations (Phlex, Lucide, Turbo, Active Storage) stay shared.
+This is not a standalone replacement for the gem. Pin the gem and test kernel
+upgrades even after ejecting.
+
+Load the generated CSS after Nitro Kit and before application overrides:
+
+```erb
+<%= stylesheet_link_tag "nitro_kit", "ejected_button", "application",
+  "data-turbo-track": "reload" %>
+```
+
+In Phlex, use the Rails `stylesheet_link_tag` adapter with the same asset names;
+CSS bundlers may import the generated file instead. The generator reports this
+manual step rather than guessing which of your layouts or CSS entrypoints owns
+the page. Keep the app's normal Stimulus loader enabled. Standard Rails importmap
+apps already pin `app/javascript/controllers` recursively; bundler apps must
+include the generated controllers in their controller loader/build as usual.
+
+Dropzone's copied controller imports Active Storage's JavaScript even when
+`direct_upload: false`. If the app omits Active Storage, its JavaScript asset
+must still be available; eject does not install third-party integrations.
+
+## Isolation and composition
+
+Each ejection has its own dependency snapshot. Ruby uses `Ui::EjectedButton`,
+not `NitroKit` or an existing `Ui::Button`. Root/slot identities use
+`ui-ejected-button-*`; controller identifiers follow Rails filename conventions
+(`ui--ejected-button--button`); CSS layers, private variables, and keyframes
+are renamed. Public tokens and the global reset deliberately remain shared.
+Gem Buttons and ejected Buttons can render on the same page without sharing
+component CSS or controller identifiers.
+
+Namespace spelling follows the host application's inflections (for example,
+an app with the `UI` acronym gets `UI::EjectedButton`). Use the constructor
+printed by the generator.
+
+For typed slots, construct children from the same snapshot, for example
+`Ui::EjectedEmptyState::Button`. Arbitrary content blocks may still compose gem
+components, but snapshot-specific contextual styling targets snapshot children.
+Separate ejections do not silently share mutable dependencies.
+
+## Existing files and updates
+
+Unknown names fail with a list of supported names before writing. CamelCase,
+snake_case, and `NitroKit::Button` names are accepted. If any snapshot file
+already exists, the entire operation skips without changing anything (including
+with `--skip`). `--force` explicitly replaces the entire generated snapshot;
+commit your modifications first. Stale files from older dependency graphs are
+not deleted automatically.
+
+Bundler updates do not update ejected component implementations, styles, or
+controllers. Compare the recorded version to the changelog and port fixes
+yourself, or generate a new snapshot in a disposable application and diff it.
+The manifest enables future update notices; no updater or notice UI ships yet.
+Commit all generated files and the stylesheet integration together.

data/docs/migration_1_to_2.md

@@ -12,7 +12,7 @@ Treat a 1.x migration as a product-flow review, not a helper rename. Nitro Kit
 Add the 2.0 prerelease to the application's Gemfile:
 
 ```ruby
-gem "nitro_kit", "2.0.0.beta.1"
+gem "nitro_kit", "2.0.0.beta.3"
 ```
 
 Bundler records the exact released version in `Gemfile.lock`; commit `Gemfile`

data/docs/patterns/application_foundation.md

@@ -45,6 +45,28 @@ Nitro owns responsive disclosure and focus behavior. Put infrequent account
 destinations after `navigation.spacer`. Add one `CommandPalette` only when the
 destination count warrants search, and render only authorized routes.
 
+The sidebar stays expanded by default, without a toggle or hover peek. Opt in
+with `AppShell(id: "workspace", collapsible: true)` to include the bottom
+**Pin sidebar** toggle that switches between the full sidebar and an icon rail.
+Hovering with a fine pointer or focusing within the navigation or brand
+reveals the full navigation as an overlay without moving page content.
+The pin control does not trigger peek on hover or focus, so directly pinning
+the rail starts the sidebar and content resize together.
+Clicking the toggle pins the sidebar and reserves its full layout width.
+Pointer-clicking to unpin collapses it immediately and suppresses hover peek
+until the pointer leaves the sidebar once; keyboard focus still peeks. Use
+`AppShell(id: "workspace", collapsible: true, sidebar: :collapsed)` to start with the rail, and
+give navigation items icons so they remain recognizable. Labels keep their
+accessible names and vertical positions. Touch does not hover-peek; narrow
+screens still use the modal drawer. Pin state survives Turbo morph refreshes
+of the same shell, but is not persisted across page loads.
+`sidebar_toggle_label:` overrides its name.
+
+For a brand mark that stays visible on the rail, declare
+`shell.brand(icon: :zap) { ... }`. The icon stays aligned with navigation;
+the full brand content appears on hover/focus or when pinned instead of being
+cropped to fit the rail.
+
 Use `AuthShell` with Rails `form_with` and `NitroKit::FormBuilder` for
 authentication. Put visible fields, submit, and recovery link in one
 `form.group`.

data/docs/patterns/inset_workspace.md

@@ -67,6 +67,13 @@ For `topbar`, put that Toolbar first inside `workspace-content` and omit
 `shell.topbar`. Keep one route title and one set of actions. The header and
 body in `sidebar` form one continuous canvas, not two stacked cards.
 
+The inset composition also works with `collapsible: true`. Add
+`sidebar: :expanded` to start pinned open, or `sidebar: :collapsed` to start
+as an icon rail, and give `shell.brand` an `icon:` for its compact mark.
+Pinning reserves navigation space; hover or keyboard-focus peeking overlays
+the inset canvas without moving its toolbar or content. The App shell and
+Sidebar operations galleries show static and collapsible inset examples.
+
 Load this stylesheet after Nitro Kit:
 
 ```css
@@ -165,7 +172,8 @@ Load this stylesheet after Nitro Kit:
 
 Navigation, mobile disclosure, and focus restoration remain Nitro-owned.
 Application code owns the destinations and the composition. The public
-Product resource gallery runs the sidebar example with this stylesheet at
+App shell, Sidebar operations application, and Product resource galleries
+run inset sidebar examples with this stylesheet at
 `test/dummy/app/assets/stylesheets/inset_workspace.css`.
 
 ## Verify the result

data/docs/rails_integration.md

@@ -12,7 +12,7 @@ There are no `nk_form_with` helpers or general ERB component bridge.
 Pin the current prerelease:
 
 ```ruby
-gem "nitro_kit", "2.0.0.beta.1"
+gem "nitro_kit", "2.0.0.beta.3"
 ```
 
 Use the released gem and commit `Gemfile` with `Gemfile.lock`. Before upgrading,
@@ -36,7 +36,9 @@ Load Nitro Kit before application styles:
 ```
 
 For third-party base CSS, Tailwind, appearance setup, and token overrides, use
-the canonical [stylesheet order](customization.md#stylesheet-order).
+the canonical [stylesheet order](customization.md#stylesheet-order). A
+`tailwindcss-rails` application can bundle Nitro Kit into its compiled Tailwind
+stylesheet through the engine entry described there.
 
 ## Stimulus
 

data/lib/generators/nitro_kit/eject_generator.rb

@@ -0,0 +1,26 @@
+require "rails/generators"
+require "nitro_kit/ejection"
+
+module NitroKit
+  class EjectGenerator < Rails::Generators::Base
+    argument :component, type: :string, desc: "Component to eject (for example Button)"
+    desc "Copy one component and its dependencies into isolated application-owned code."
+
+    def eject_component
+      ejection = Ejection.new(component)
+      files = ejection.files
+      existing = files.keys.select { |path| File.exist?(File.join(destination_root, path)) }
+      if existing.any? && !options[:force]
+        say_status :skip, "Already ejected or conflicting files: #{existing.join(', ')}. No files changed; use --force to replace the entire snapshot.", :yellow
+        return
+      end
+
+      files.each { |path, content| create_file(path, content) }
+      say "Render #{ejection.namespace}::#{ejection.component_name}.new(...)"
+      say "Load #{ejection.stylesheet_name}.css after nitro_kit.css (stylesheet_link_tag, or your CSS entrypoint)."
+      say "Keep Nitro Kit installed and keep the application's Stimulus controller loader enabled. See docs/eject.md."
+    rescue ArgumentError => error
+      raise Rails::Generators::Error, error.message
+    end
+  end
+end

data/lib/nitro_kit/ejection.rb

@@ -0,0 +1,136 @@
+require "ripper"
+require "json"
+require "nitro_kit/version"
+
+module NitroKit
+  class Ejection
+    ROOT = File.expand_path("../..", __dir__)
+    SUPPORT_FILES = %w[component layout_options responsive_value].freeze
+
+    def initialize(name)
+      @name = name.delete_prefix("NitroKit::").underscore
+      @sources = Dir["#{ROOT}/app/components/nitro_kit/*.rb"].to_h do |path|
+        [ File.basename(path, ".rb").camelize, File.read(path) ]
+      end
+      unless @sources.key?(component_name) && !SUPPORT_FILES.include?(@name)
+        raise ArgumentError, "Unknown component #{name.inspect}. Choose one of: #{(@sources.keys - SUPPORT_FILES.map(&:camelize)).sort.join(', ')}"
+      end
+    end
+
+    def component_name = @name.camelize
+    def stylesheet_name = "ejected_#{@name}"
+    def namespace = directory.camelize
+    def prefix = "ui-ejected-#{@name.dasherize}"
+    def directory = "ui/ejected_#{@name}"
+
+    def files
+      result = {}
+      ruby_names.each do |name|
+        result["app/components/#{directory}/#{name.underscore}.rb"] = header("#") + rewrite_ruby(@sources.fetch(name))
+      end
+      result["app/components/#{directory}/component.rb"] = header("#") + component_adapter
+      result["app/assets/stylesheets/#{stylesheet_name}.css"] = header("/*", " */") + stylesheet
+      javascript_paths.each do |path|
+        relative = path.delete_prefix("#{ROOT}/app/javascript/controllers/nk/")
+        source = rewrite_contracts(File.read(path))
+          .gsub("controllers/nk/", "controllers/#{directory}/")
+        result["app/javascript/controllers/#{directory}/#{relative}"] = header("//") + source
+      end
+      result["config/nitro_kit/ejected/#{@name}.json"] = JSON.pretty_generate(
+        component: component_name, version: VERSION, namespace:, files: result.keys
+      ) + "\n"
+      result
+    end
+
+    private
+      def header(open, close = "")
+        "#{open} Ejected from Nitro Kit #{VERSION}: #{component_name}. Application-owned; not automatically upgraded.#{close}\n"
+      end
+
+      def ruby_names
+        @ruby_names ||= begin
+          names = [ component_name ]
+          names.each do |name|
+            Ripper.lex(@sources.fetch(name)).each do |_, type, token, _|
+              names << token if type == :on_const && @sources.key?(token) && token != "Component" && !names.include?(token)
+            end
+          end
+          names
+        end
+      end
+
+      def stylesheet
+        names = ruby_names.map(&:underscore)
+        names << "palette" if (ruby_names & %w[Badge Alert Toast]).any?
+        names << "layout" if (ruby_names & %w[Flex Grid]).any?
+        rules = names.filter_map do |name|
+          path = "#{ROOT}/src/stylesheets/nitro_kit/components/#{name}.css"
+          rewrite_contracts(File.read(path)) if File.file?(path)
+        end
+        layers = %w[base variant size state compound].map { |layer| "#{prefix}.#{layer}" }.join(", ")
+        "@layer #{layers};\n" + rules.join("\n")
+      end
+
+      def javascript_paths
+        ruby_source = ruby_names.map { |name| @sources.fetch(name) }.join("\n")
+        paths = Dir["#{ROOT}/app/javascript/controllers/nk/*_controller.js"].select do |path|
+          name = File.basename(path, "_controller.js")
+          ruby_source.include?("nk--#{name.dasherize}") || ruby_source.include?("nk__#{name}")
+        end
+        # Shared overlay command plumbing lives in the component adapter.
+        paths |= [ "#{ROOT}/app/javascript/controllers/nk/dialog_controller.js" ] if ruby_source.include?("command_data(")
+        paths.each do |path|
+          File.read(path).scan(/(?:from\s*|import\s*)["']([^"']+)["']/).flatten.each do |import|
+            dependency = if import.start_with?("controllers/nk/")
+              "#{ROOT}/app/javascript/#{import}.js"
+            elsif import.start_with?(".")
+              File.expand_path(import.end_with?(".js") ? import : "#{import}.js", File.dirname(path))
+            end
+            paths << dependency if dependency && File.file?(dependency) && !paths.include?(dependency)
+          end
+        end
+        paths
+      end
+
+      def rewrite_ruby(source)
+        rewrite_contracts(source.gsub("module NitroKit", "module #{namespace}").gsub("NitroKit::", "#{namespace}::"))
+      end
+
+      def rewrite_contracts(source)
+        source.gsub("nk--", "ui--ejected-#{@name.dasherize}--")
+          .gsub("nk__", "ui__ejected_#{@name}__")
+          .gsub(/(data-(?:nk|slot)(?:[~|^$*]?=)["'])([^"']+)/) { "#{$1}#{prefix}-#{$2}" }
+          .gsub(/(dataset\.slot\s*=\s*["'])([^"']+)/) { "#{$1}#{prefix}-#{$2}" }
+          .gsub("--_nk-", "--_#{prefix}-")
+          .gsub(/(?<![-\w])nk-(?!-)[a-z][a-z0-9-]*/) { |name| "#{prefix}-#{name.delete_prefix('nk-')}" }
+          .gsub("nitro-kit.", "#{prefix}.")
+      end
+
+      def component_adapter
+        # Copy component helpers, not the attribute kernel or the enclosing class.
+        helpers = @sources.fetch("Component").lines
+          .drop_while { |line| !line.start_with?("    def description_id") }[...-2].join
+        <<~RUBY
+          module #{namespace}
+            class Component < NitroKit::Component
+              def initialize(component:, **attributes)
+                super(component: "#{prefix}-\#{component.to_s.tr('_', '-')}", **attributes)
+              end
+
+              private
+
+              def qualified_slot(slot)
+                name = slot.to_s.tr("_", "-")
+                original = @component_name.delete_prefix("#{prefix}-")
+                name = name.delete_prefix("\#{original}-")
+                "\#{@component_name}-\#{name}"
+              end
+
+              # Snapshot of component-level helpers; attribute/render kernel stays gem-owned.
+          #{rewrite_contracts(helpers)}
+            end
+          end
+        RUBY
+      end
+  end
+end

data/lib/nitro_kit/engine.rb

@@ -1,7 +1,12 @@
 module NitroKit
   class Engine < ::Rails::Engine
+    # Rails would otherwise derive "nitro_kit_engine". tailwindcss-rails looks up
+    # app/assets/tailwind/<engine_name>/engine.css, so the name is public.
+    engine_name "nitro_kit"
+
     IMPORTMAP_PATH = root.join("config/importmap.rb")
     JAVASCRIPT_PATHS = [ root.join("app/javascript") ].freeze
+    TAILWIND_PATH = root.join("app/assets/tailwind")
 
     initializer "nitro_kit.assets" do |app|
       next unless app.config.respond_to?(:assets)
@@ -11,6 +16,14 @@ module NitroKit
       end
     end
 
+    # The Tailwind engine entry is a build input for tailwindcss-rails, not a
+    # servable asset. Keep it out of Propshaft's load path.
+    initializer "nitro_kit.exclude_tailwind_path", before: "propshaft.append_assets_path" do |app|
+      next unless app.config.respond_to?(:assets) && app.config.assets.respond_to?(:excluded_paths)
+
+      app.config.assets.excluded_paths << TAILWIND_PATH unless app.config.assets.excluded_paths.include?(TAILWIND_PATH)
+    end
+
     initializer "nitro_kit.importmap", before: "importmap" do |app|
       next unless app.config.respond_to?(:importmap)
 

data/lib/nitro_kit/installation.rb

@@ -9,9 +9,13 @@ module NitroKit
     ROOT = Pathname.new(File.expand_path("../..", __dir__))
     SKILLS = %w[nitro-kit-hotwire nitro-kit-rails nitro-kit-ui].freeze
     SKILL_ROOTS = [ ".agents/skills", ".claude/skills" ].freeze
+    # nitro_kit-tailwind-v4 is the beta-era adapter that nitro_kit.css absorbed;
+    # it stays managed so doctor flags a leftover link instead of ignoring it.
     MANAGED_STYLESHEETS = %w[
       lexxy nitro_kit-tailwind-v4 nitro_kit tailwind application
     ].freeze
+    TAILWIND_ENTRY = "app/assets/tailwind/application.css"
+    TAILWIND_BUNDLE_IMPORT = %r{@import\s+["'](?:\.\./)+builds/tailwind/nitro_kit(?:\.css)?["']}
     AGENTS_START = "<!-- nitro-kit:start -->"
     AGENTS_END = "<!-- nitro-kit:end -->"
     AGENTS_BLOCK = <<~MARKDOWN.freeze
@@ -217,8 +221,12 @@ module NitroKit
           errors << "installer left the layout unchanged: #{edit_error}"
         end
 
-        if assets.include?("nitro_kit-tailwind-v4") && !expected.include?("tailwind")
-          errors << "remove nitro_kit-tailwind-v4 or load compiled Tailwind after nitro_kit"
+        if assets.include?("nitro_kit-tailwind-v4")
+          errors << "remove stylesheet \"nitro_kit-tailwind-v4\"; nitro_kit now includes the Tailwind v4 layer order and theme aliases"
+        end
+
+        if tailwind_bundles_nitro_kit? && assets.include?("nitro_kit")
+          errors << "remove stylesheet \"nitro_kit\"; #{TAILWIND_ENTRY} already bundles it"
         end
 
         bootstrap_position = analysis.bootstraps.first&.range&.begin
@@ -569,17 +577,20 @@ module NitroKit
         assets = managed_stylesheet_assets(analysis) - [ "nitro_kit-tailwind-v4" ]
         assets << "lexxy" if dependency?("lexxy")
         assets << "tailwind" if tailwind?(assets)
-        assets << "nitro_kit"
+        if tailwind_bundles_nitro_kit?
+          assets -= [ "nitro_kit" ]
+          assets << "tailwind"
+        else
+          assets << "nitro_kit"
+        end
         assets << "application" if assets.include?("application") || application_stylesheet_asset?
-        assets << "nitro_kit-tailwind-v4" if assets.include?("tailwind")
         ordered_stylesheets(assets.uniq)
       end
 
       def ordered_stylesheets(assets)
-        vendor = assets - %w[nitro_kit-tailwind-v4 nitro_kit tailwind application]
+        vendor = assets - %w[nitro_kit tailwind application]
         [
           *vendor,
-          *(%w[nitro_kit-tailwind-v4] & assets),
           *(%w[nitro_kit] & assets),
           *(%w[tailwind] & assets),
           *(%w[application] & assets)
@@ -597,6 +608,9 @@ module NitroKit
 
         existing = managed_stylesheet_assets(analysis)
         return "duplicate canonical stylesheet assets require manual review" if existing.uniq != existing
+        if existing.include?("nitro_kit-tailwind-v4")
+          return "drop \"nitro_kit-tailwind-v4\" from its stylesheet call without changing the call's options"
+        end
         unless existing == expected.select { existing.include?(_1) }
           return "existing canonical stylesheets are misordered; reorder their intact calls manually"
         end
@@ -657,7 +671,15 @@ module NitroKit
       end
 
       def tailwind?(assets)
-        assets.include?("tailwind") || dependency?("tailwindcss-rails") || application_root.join("app/assets/tailwind/application.css").file?
+        assets.include?("tailwind") || dependency?("tailwindcss-rails") || application_root.join(TAILWIND_ENTRY).file?
+      end
+
+      # True when the application's Tailwind source imports the engine entry
+      # that tailwindcss-rails generates from app/assets/tailwind/nitro_kit/engine.css,
+      # so the compiled "tailwind" stylesheet already contains Nitro Kit.
+      def tailwind_bundles_nitro_kit?
+        entry = application_root.join(TAILWIND_ENTRY)
+        entry.file? && entry.read.match?(TAILWIND_BUNDLE_IMPORT)
       end
 
       def application_stylesheet_asset?

data/lib/nitro_kit/version.rb

@@ -1,3 +1,3 @@
 module NitroKit
-  VERSION = "2.0.0.beta.1"
+  VERSION = "2.0.0.beta.3"
 end

data/lib/tasks/nitro_kit_tasks.rake

@@ -9,7 +9,7 @@ module NitroKit
     ROOT = Pathname.new(File.expand_path("../..", __dir__))
     SOURCE_ROOT = ROOT.join("src/stylesheets/nitro_kit")
     OUTPUT = ROOT.join("app/assets/stylesheets/nitro_kit.css")
-    FOUNDATION_SOURCES = %w[ layers.css tokens.css reset.css ].freeze
+    FOUNDATION_SOURCES = %w[ layers.css tokens.css tailwind.css reset.css ].freeze
     BANNER = <<~CSS.freeze
       /*
        * Nitro Kit 2.0

data/src/stylesheets/nitro_kit/components/app_navigation.css

@@ -78,6 +78,8 @@
     min-block-size: var(--nk-control-height-md);
     margin: var(--nk-space) 0;
     padding: calc(var(--nk-space) * 2) calc(var(--nk-space) * 3);
+    /* The label text is an anonymous flex item with a min-content floor. */
+    overflow-wrap: anywhere;
     list-style: none;
     user-select: none;
     cursor: pointer;
@@ -135,7 +137,8 @@
     border-radius: var(--nk-radius-lg);
     transition:
       color var(--nk-duration-normal) var(--nk-ease),
-      background-color var(--nk-duration-normal) var(--nk-ease);
+      background-color var(--nk-duration-normal) var(--nk-ease),
+      inline-size var(--nk-duration-fast) var(--nk-ease);
   }
 
   :where([data-nk="app-navigation"] [data-slot="app-navigation-item-label"]) {