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

data/lib/nitro_kit/migration_inventory.rb

@@ -141,13 +141,13 @@ module NitroKit
 
         def inspect_table(node)
           constructor = positional_arguments(node).first
-          return unless node.name == :render && table_constructor?(constructor) && node.block
+          return unless node.name == :render && table_constructor?(constructor)
 
-          parameter = node.block.parameters&.parameters&.requireds&.first
-          return unless parameter.is_a?(Prism::RequiredParameterNode)
-          return if parameter.name == :table
+          receiver_name = required_block_parameter_name(node)
+          return unless receiver_name
+          return if receiver_name == :table
 
-          visitor = TableCompoundVisitor.new(parameter.name)
+          visitor = TableCompoundVisitor.new(receiver_name)
           visitor.visit(node.block.body) if node.block.body
           issues.concat(visitor.issues)
         end
@@ -166,14 +166,21 @@ module NitroKit
           component = constructor.receiver.full_name.delete_prefix("NitroKit::")
           return unless %w[Dropdown Sheet].include?(component)
 
-          parameter = node.block.parameters&.parameters&.requireds&.first
-          return unless parameter.is_a?(Prism::RequiredParameterNode)
+          receiver_name = required_block_parameter_name(node)
+          return unless receiver_name
 
-          visitor = IconTriggerVisitor.new(parameter.name, component)
+          visitor = IconTriggerVisitor.new(receiver_name, component)
           visitor.visit(node.block.body) if node.block.body
           issues.concat(visitor.issues)
         end
 
+        def required_block_parameter_name(node)
+          return unless node.block.is_a?(Prism::BlockNode)
+
+          parameter = node.block.parameters&.parameters&.requireds&.first
+          parameter.name if parameter.is_a?(Prism::RequiredParameterNode)
+        end
+
         def table_constructor?(node)
           node.is_a?(Prism::CallNode) && node.name == :new &&
             node.receiver&.respond_to?(:full_name) && node.receiver.full_name == "NitroKit::Table"

data/lib/nitro_kit/version.rb

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

data/plugins/nitro-kit/skills/nitro-kit-rails/SKILL.md

@@ -29,6 +29,13 @@ contract as a substitute for the installed API.
 
 ## Follow the application grammar
 
+- In a greenfield application, run `bin/rails generate phlex:install` and use
+  Phlex for the application layout, route-level views, and reusable UI. Render
+  `Views::*` objects from controllers instead of creating ERB wrappers around
+  Phlex. In an established application, preserve its view architecture and
+  introduce Phlex only at the requested boundary unless an application-wide
+  migration is explicitly authorized. Judge this from existing view code, not
+  the Rails version or apparent age.
 - Scope tenant data through `Current.team` or `Current.account`; record
   `Current.user` as the actor.
 - Put domain behavior on the model before introducing another abstraction.

data/plugins/nitro-kit/skills/nitro-kit-ui/SKILL.md

@@ -31,19 +31,26 @@ If the gem is not installed, say that the skill requires Nitro Kit and follow th
 
 ## Build the interface
 
-1. Reuse the highest-level Nitro block that matches the page region, then compose components inside it.
-2. Include `NitroKit` once in the application's base Phlex component and use capitalized Kit methods such as `Button(...)` and `Card(...)`. Use `.new` only when another API needs a component object. Keep product-specific components under the application's namespace, commonly `UI::*`.
-3. Use `NitroKit::FormBuilder` explicitly with Rails `form_with` for model-backed forms.
-4. Keep routes, authorization, records, query policy, DOM IDs, Turbo boundaries, and response semantics in the application.
-5. Translate the application's semantic theme into documented `--nk-*` properties instead of choosing similar raw palette values. Use `--nk-button-radius` when Button shape intentionally differs from inputs and surfaces.
-6. Verify closed options and required compound declarations before rendering.
-7. For authenticated CRUD, prefer a hybrid `AppShell` with a `Toolbar` that
+1. In a greenfield application, run `bin/rails generate phlex:install` and use
+   Phlex for the application layout, route-level `Views::*`, and reusable UI.
+   Do not add ERB wrappers whose only purpose is to render Phlex. In an
+   established application with meaningful view conventions, preserve them
+   and introduce Phlex and Nitro Kit only at the requested boundary unless an
+   application-wide migration is explicitly authorized. Determine this from
+   the existing view architecture, not the Rails version or apparent age.
+2. Reuse the highest-level Nitro block that matches the page region, then compose components inside it.
+3. Include `NitroKit` once in the application's base Phlex component and use capitalized Kit methods such as `Button(...)` and `Card(...)`. Use `.new` only when another API needs a component object. Keep product-specific components under the application's namespace, commonly `UI::*`.
+4. Use `NitroKit::FormBuilder` explicitly with Rails `form_with` for model-backed forms.
+5. Keep routes, authorization, records, query policy, DOM IDs, Turbo boundaries, and response semantics in the application.
+6. Translate the application's semantic theme into documented `--nk-*` properties instead of choosing similar raw palette values. Use `--nk-button-radius` when Button shape intentionally differs from inputs and surfaces.
+7. Verify closed options and required compound declarations before rendering.
+8. For authenticated CRUD, prefer a hybrid `AppShell` with a `Toolbar` that
    owns the route's single `h1` and basic actions. The shell main region owns
    one content gutter. Do not repeat that heading in `PageHeader`, or wrap each
    table, form, and detail region in another Card. At narrow widths, preserve
    the full title and persistent actions by stacking the trailing actions below
    the title rather than clipping either region.
-8. For team administration and account settings, read
+9. For team administration and account settings, read
    `docs/patterns/application_foundation.md`. Put Settings after an
    `AppNavigation` spacer and use `SettingsLayout` with plain `SettingsSection`
    regions instead of a stack of Cards.

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

@@ -18,8 +18,8 @@
         > [data-slot="accordion-trigger"]
     ) {
     display: flex;
-    width: 100%;
-    min-height: 2.75rem;
+    inline-size: 100%;
+    min-block-size: var(--nk-control-height-lg);
     align-items: center;
     justify-content: space-between;
     gap: calc(var(--nk-space) * 3);
@@ -58,8 +58,8 @@
         > [data-slot="accordion-icon"]
     ) {
     flex: none;
-    width: 1rem;
-    height: 1rem;
+    inline-size: var(--nk-icon-size-sm);
+    block-size: var(--nk-icon-size-sm);
     color: var(--nk-color-muted-foreground);
     transition:
       color var(--nk-duration-fast) var(--nk-ease),

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

@@ -3,7 +3,6 @@
     --_nk-alert-background: var(--nk-color-surface);
     --_nk-alert-border: var(--nk-color-border);
     --_nk-alert-foreground: var(--nk-color-foreground);
-    --_nk-alert-tint-strength: 12%;
 
     position: relative;
     display: grid;
@@ -20,8 +19,8 @@
   }
 
   :where([data-nk="alert"] > [data-slot="alert-title"]) {
-    font-size: var(--nk-text-base);
-    font-weight: var(--nk-font-weight-semibold);
+    font-size: var(--nk-title-compact-size);
+    font-weight: var(--nk-title-compact-weight);
     line-height: var(--nk-leading-tight);
     text-wrap: balance;
   }
@@ -30,11 +29,20 @@
     grid-template-columns: auto minmax(0, 1fr);
   }
 
+  /* Centered on the title first line, whatever size the title role
+     resolves to, instead of a hand-tuned nudge for one size. */
   :where([data-nk="alert"] > [data-slot="alert-icon"]) {
+    --_nk-alert-icon-size: var(--nk-icon-size-md);
+
     grid-row: 1 / -1;
-    inline-size: 1.25rem;
-    block-size: 1.25rem;
-    margin-block-start: 0.0625rem;
+    inline-size: var(--_nk-alert-icon-size);
+    block-size: var(--_nk-alert-icon-size);
+    margin-block-start: calc(
+      (
+          var(--nk-title-compact-size) * var(--nk-leading-tight) -
+            var(--_nk-alert-icon-size)
+        ) / 2
+    );
   }
 
   :where(
@@ -54,29 +62,12 @@
 }
 
 @layer nitro-kit.variant {
+  /* Colour, tint strength, and appearance switching all come from the shared
+     semantic palette, so an Alert and a Toast of the same variant render
+     identically. */
   :where([data-nk="alert"][data-variant]) {
-    --_nk-alert-background: color-mix(
-      in oklab,
-      var(--_nk-palette-tint) var(--_nk-alert-tint-strength),
-      transparent
-    );
-    --_nk-alert-border: color-mix(
-      in oklab,
-      var(--_nk-palette-tint) 45%,
-      transparent
-    );
-    --_nk-alert-foreground: var(--_nk-palette-light);
-  }
-
-  :where([data-theme="dark"] [data-nk="alert"][data-variant]) {
-    --_nk-alert-foreground: var(--_nk-palette-dark);
-    --_nk-alert-tint-strength: 20%;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    :where(:root:not([data-theme]) [data-nk="alert"][data-variant]) {
-      --_nk-alert-foreground: var(--_nk-palette-dark);
-      --_nk-alert-tint-strength: 20%;
-    }
+    --_nk-alert-background: var(--_nk-semantic-surface);
+    --_nk-alert-border: var(--_nk-semantic-border);
+    --_nk-alert-foreground: var(--_nk-semantic-content);
   }
 }

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

@@ -65,6 +65,58 @@
     line-height: var(--nk-leading-tight);
   }
 
+  /* A collapsible label is a row like the items around it: same height,
+     same inline padding, symmetric block margins, and the same hover
+     treatment, so the disclosure target is as easy to hit as a destination. */
+  :where(
+      [data-nk="app-navigation"]
+        summary[data-slot="app-navigation-section-label"]
+    ) {
+    display: flex;
+    gap: var(--nk-space);
+    align-items: center;
+    min-block-size: var(--nk-control-height-md);
+    margin: var(--nk-space) 0;
+    padding: calc(var(--nk-space) * 2) calc(var(--nk-space) * 3);
+    list-style: none;
+    user-select: none;
+    cursor: pointer;
+    border-radius: var(--nk-radius-lg);
+    transition:
+      color var(--nk-duration-normal) var(--nk-ease),
+      background-color var(--nk-duration-normal) var(--nk-ease);
+  }
+
+  :where(
+      [data-nk="app-navigation"]
+        summary[data-slot="app-navigation-section-label"]::-webkit-details-marker
+    ) {
+    display: none;
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-section-icon"]) {
+    flex: none;
+    inline-size: var(--nk-icon-size-xs);
+    block-size: var(--nk-icon-size-xs);
+    transition: transform var(--nk-duration-fast) var(--nk-ease);
+  }
+
+  :where(
+      [data-nk="app-navigation"]
+        [data-slot="app-navigation-section-disclosure"]:not([open])
+        [data-slot="app-navigation-section-icon"]
+    ) {
+    transform: rotate(-90deg);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where(
+        [data-nk="app-navigation"] [data-slot="app-navigation-section-icon"]
+      ) {
+      transition-duration: 0.01ms;
+    }
+  }
+
   :where([data-nk="app-navigation"] [data-slot="app-navigation-item"]) {
     flex: 0 0 auto;
     min-inline-size: 0;
@@ -80,7 +132,7 @@
     font-weight: var(--nk-font-weight-medium);
     line-height: var(--nk-leading-tight);
     text-decoration: none;
-    border-radius: var(--nk-radius-md);
+    border-radius: var(--nk-radius-lg);
     transition:
       color var(--nk-duration-normal) var(--nk-ease),
       background-color var(--nk-duration-normal) var(--nk-ease);
@@ -96,6 +148,7 @@
 
   :where(
       [data-nk="app-navigation"] [data-slot="app-navigation-item-icon"],
+      [data-nk="app-navigation"] [data-slot="app-navigation-item-icon-end"],
       [data-nk="app-navigation"] [data-slot="app-navigation-item-badge"]
     ) {
     flex: 0 0 auto;
@@ -133,13 +186,32 @@
 
   @media (hover: hover) {
     :where(
-        [data-nk="app-navigation"] [data-slot="app-navigation-item-link"]:hover
+        [data-nk="app-navigation"] [data-slot="app-navigation-item-link"]:hover,
+        [data-nk="app-navigation"]
+          summary[data-slot="app-navigation-section-label"]:hover
       ) {
       color: var(--nk-app-shell-sidebar-accent-foreground);
       background: var(--nk-app-shell-sidebar-accent);
     }
   }
 
+  :where(
+      [data-nk="app-navigation"]
+        summary[data-slot="app-navigation-section-label"]:focus-visible
+    ) {
+    outline: var(--nk-focus-width) solid var(--nk-color-focus);
+    outline-offset: calc(var(--nk-focus-offset) * -1);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where(
+        [data-nk="app-navigation"]
+          summary[data-slot="app-navigation-section-label"]
+      ) {
+      transition-duration: 0.01ms;
+    }
+  }
+
   :where(
       [data-nk="app-navigation"]
         [data-slot="app-navigation-item-link"]:focus-visible

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

@@ -24,7 +24,7 @@
     color: var(--nk-color-primary-foreground);
     text-decoration: none;
     background: var(--nk-color-primary);
-    border-radius: var(--nk-radius-md);
+    border-radius: var(--nk-radius-lg);
     outline: var(--nk-focus-width) solid var(--nk-color-focus);
     transform: translateY(calc(-100% - (var(--nk-space) * 4)));
     transition: transform var(--nk-duration-fast) var(--nk-ease);
@@ -79,7 +79,7 @@
     cursor: pointer;
     background: transparent;
     border: 0;
-    border-radius: var(--nk-radius-md);
+    border-radius: var(--nk-radius-lg);
     transition:
       background-color var(--nk-duration-fast) var(--nk-ease),
       scale var(--nk-duration-fast) var(--nk-ease);
@@ -542,7 +542,7 @@
       flex-direction: column;
       inline-size: min(
         var(--nk-app-shell-sidebar-width),
-        calc(100vw - (var(--nk-space) * 12))
+        calc(100% - (var(--nk-space) * 12))
       );
       max-inline-size: 100%;
       block-size: 100vh;

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

@@ -10,16 +10,24 @@
       [data-nk="appearance-picker"] > [data-slot="appearance-picker-legend"]
     ) {
     padding: 0;
-    font-size: var(--nk-text-sm);
-    font-weight: var(--nk-font-weight-semibold);
+    font-size: var(--nk-title-compact-size);
+    font-weight: var(--nk-title-compact-weight);
   }
 
+  /* The gap below the label exists only when there is a label. */
   :where(
       [data-nk="appearance-picker"] > [data-slot="appearance-picker-options"]
     ) {
     display: flex;
     flex-wrap: wrap;
     gap: calc(var(--nk-space) * 3);
+  }
+
+  :where(
+      [data-nk="appearance-picker"]
+        > [data-slot="appearance-picker-legend"]
+        + [data-slot="appearance-picker-options"]
+    ) {
     margin-block-start: calc(var(--nk-space) * 2);
   }
 
@@ -30,15 +38,17 @@
     display: grid;
   }
 
+  /* Like every other control, the segmented row fills its container and the
+     parent owns the available width; the segments share it equally. */
   :where(
       [data-nk="appearance-picker"][data-presentation="segmented"]
         > [data-slot="appearance-picker-options"]
     ) {
-    display: inline-flex;
+    display: flex;
     gap: 0;
     padding: var(--nk-space);
     background: var(--nk-color-muted);
-    border-radius: var(--nk-radius-md);
+    border-radius: var(--nk-radius-lg);
   }
 
   :where([data-nk="appearance-picker"] [data-slot="appearance-picker-option"]) {
@@ -53,8 +63,8 @@
   :where(
       [data-nk="appearance-picker"] [data-slot="appearance-picker-control"]
     ) {
-    inline-size: 1.125rem;
-    block-size: 1.125rem;
+    inline-size: var(--nk-choice-size-md);
+    block-size: var(--nk-choice-size-md);
     margin: 0;
     accent-color: var(--nk-color-primary);
     cursor: pointer;
@@ -65,8 +75,10 @@
         [data-slot="appearance-picker-option"]
     ) {
     position: relative;
+    flex: 1 1 0;
+    justify-content: center;
     padding-inline: calc(var(--nk-space) * 3);
-    border-radius: calc(var(--nk-radius-md) - var(--nk-space));
+    border-radius: calc(var(--nk-radius-lg) - var(--nk-space));
   }
 
   :where(
@@ -90,7 +102,7 @@
     font: inherit;
     background: var(--nk-color-surface);
     border: var(--nk-border-width) solid var(--nk-color-border);
-    border-radius: var(--nk-radius-md);
+    border-radius: var(--nk-radius-lg);
   }
 }
 

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

@@ -1,7 +1,7 @@
 @layer nitro-kit.base {
   :where([data-nk="auth-shell"]) {
-    width: 100%;
-    min-width: 0;
+    inline-size: 100%;
+    min-inline-size: 0;
     padding-block: calc(var(--nk-space) * 8);
     padding-inline: calc(var(--nk-space) * 4);
   }

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

@@ -1,11 +1,15 @@
 @layer nitro-kit.base {
   :where([data-nk="avatar"]) {
     position: relative;
+    /* The ring below carries a z-index, so without a stacking context it
+       would paint above overlapping siblings — in a stack, every ring showed
+       through the avatar covering it. Isolation keeps each avatar atomic. */
+    isolation: isolate;
     display: inline-grid;
     flex: none;
     place-items: center;
-    width: var(--_nk-avatar-size);
-    height: var(--_nk-avatar-size);
+    inline-size: var(--_nk-avatar-size);
+    block-size: var(--_nk-avatar-size);
     overflow: hidden;
     font-size: var(--_nk-avatar-font-size);
     font-weight: var(--nk-font-weight-medium);
@@ -32,8 +36,8 @@
       [data-nk="avatar"] > [data-slot="avatar-image"]
     ) {
     grid-area: 1 / 1;
-    width: 100%;
-    height: 100%;
+    inline-size: 100%;
+    block-size: 100%;
     border-radius: inherit;
   }
 
@@ -60,22 +64,22 @@
 
 @layer nitro-kit.size {
   :where([data-nk="avatar"][data-size="xs"]) {
-    --_nk-avatar-size: 1.5rem;
+    --_nk-avatar-size: var(--nk-avatar-size-xs);
     --_nk-avatar-font-size: calc(var(--nk-text-xs) * 0.875);
   }
 
   :where([data-nk="avatar"][data-size="sm"]) {
-    --_nk-avatar-size: 2rem;
+    --_nk-avatar-size: var(--nk-avatar-size-sm);
     --_nk-avatar-font-size: var(--nk-text-xs);
   }
 
   :where([data-nk="avatar"][data-size="md"]) {
-    --_nk-avatar-size: 3rem;
+    --_nk-avatar-size: var(--nk-avatar-size-md);
     --_nk-avatar-font-size: var(--nk-text-sm);
   }
 
   :where([data-nk="avatar"][data-size="lg"]) {
-    --_nk-avatar-size: 4rem;
+    --_nk-avatar-size: var(--nk-avatar-size-lg);
     --_nk-avatar-font-size: var(--nk-text-lg);
   }
 }

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

@@ -45,9 +45,9 @@
     margin-inline-start: 0;
   }
 
+  /* The chip is one of the heads: same fill as the avatar fallbacks and the
+     same hairline ring, drawn as a real border since nothing overlaps it. */
   :where([data-nk="avatar-stack"] > [data-slot="avatar-stack-overflow"]) {
-    --_nk-avatar-stack-fill: var(--nk-color-elevated);
-
     /* Preceding avatars are positioned, so the overflow chip must be too or
        their paint order covers its leading "+". */
     position: relative;
@@ -56,6 +56,8 @@
     font-weight: var(--nk-font-weight-semibold);
     line-height: 1;
     color: var(--nk-color-muted-foreground);
+    border: var(--nk-border-width) solid
+      color-mix(in oklab, var(--nk-color-foreground) 10%, transparent);
     border-radius: var(--nk-radius-full);
   }
 
@@ -63,8 +65,8 @@
       [data-nk="avatar-stack"][data-size="xs"]
         > [data-slot="avatar-stack-overflow"]
     ) {
-    width: 1.5rem;
-    height: 1.5rem;
+    inline-size: var(--nk-avatar-size-xs);
+    block-size: var(--nk-avatar-size-xs);
     font-size: calc(var(--nk-text-xs) * 0.875);
   }
 
@@ -72,8 +74,8 @@
       [data-nk="avatar-stack"][data-size="sm"]
         > [data-slot="avatar-stack-overflow"]
     ) {
-    width: 2rem;
-    height: 2rem;
+    inline-size: var(--nk-avatar-size-sm);
+    block-size: var(--nk-avatar-size-sm);
     font-size: var(--nk-text-xs);
   }
 
@@ -81,8 +83,8 @@
       [data-nk="avatar-stack"][data-size="md"]
         > [data-slot="avatar-stack-overflow"]
     ) {
-    width: 3rem;
-    height: 3rem;
+    inline-size: var(--nk-avatar-size-md);
+    block-size: var(--nk-avatar-size-md);
     font-size: var(--nk-text-sm);
   }
 
@@ -90,8 +92,8 @@
       [data-nk="avatar-stack"][data-size="lg"]
         > [data-slot="avatar-stack-overflow"]
     ) {
-    width: 4rem;
-    height: 4rem;
+    inline-size: var(--nk-avatar-size-lg);
+    block-size: var(--nk-avatar-size-lg);
     font-size: var(--nk-text-base);
   }
 }

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

@@ -1,19 +1,18 @@
 @layer nitro-kit.base {
   :where([data-nk="badge"]) {
-    --_nk-badge-color: var(--_nk-palette-light);
     --_nk-badge-tint-strength: 20%;
 
     display: inline-flex;
     align-items: center;
-    max-width: 100%;
+    max-inline-size: 100%;
     font-weight: var(--nk-font-weight-medium);
     line-height: var(--nk-leading-tight);
-    color: var(--_nk-badge-color);
+    color: var(--_nk-semantic-content);
     white-space: nowrap;
     vertical-align: middle;
     background-color: color-mix(
       in oklab,
-      var(--_nk-palette-tint) var(--_nk-badge-tint-strength),
+      var(--_nk-semantic-accent) var(--_nk-badge-tint-strength),
       transparent
     );
     border: var(--nk-border-width) solid transparent;
@@ -21,7 +20,7 @@
   }
 
   :where([data-nk="badge"] > [data-slot="badge-label"]) {
-    min-width: 0;
+    min-inline-size: 0;
     overflow: hidden;
     white-space: nowrap;
     text-overflow: ellipsis;
@@ -31,17 +30,22 @@
 @layer nitro-kit.variant {
   :where([data-nk="badge"][data-variant="outline"]) {
     background-color: transparent;
-    border-color: color-mix(in oklab, var(--_nk-palette-tint) 50%, transparent);
+    border-color: color-mix(
+      in oklab,
+      var(--_nk-semantic-accent) 50%,
+      transparent
+    );
   }
 
+  /* Only the tint strength changes with appearance. The colours themselves come
+     from the `--nk-palette-*` roles, whose `-content` half already resolves per
+     appearance. */
   :where([data-theme="dark"] [data-nk="badge"]) {
-    --_nk-badge-color: var(--_nk-palette-dark);
     --_nk-badge-tint-strength: 40%;
   }
 
   @media (prefers-color-scheme: dark) {
     :where(:root:not([data-theme]) [data-nk="badge"]) {
-      --_nk-badge-color: var(--_nk-palette-dark);
       --_nk-badge-tint-strength: 40%;
     }
   }
@@ -60,7 +64,7 @@
 
 @layer nitro-kit.size {
   :where([data-nk="badge"][data-size="xs"]) {
-    padding: 0 calc(var(--nk-space) * 1.25);
+    padding: 0 var(--nk-space);
     font-size: var(--nk-text-xs);
   }