nitro_kit 0.9.0 → 2.0.0.alpha.2

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

@@ -0,0 +1,60 @@
+---
+name: nitro-kit-rails
+description: "Build or refactor Nitro Kit 2 Rails application features on one conventional path: REST noun resources, tenant-scoped records, rich domain models, state records, standard forms and responses, Minitest fixtures, and server-rendered HTML. Use for CRUD, authentication-adjacent application structure, teams or accounts, publication and other lifecycle state, controllers, models, routes, authorization boundaries, and tests in an application that uses Nitro Kit."
+---
+
+# Nitro Kit Rails
+
+Use the Rails conventions shipped with the application's installed Nitro Kit
+version. Treat them as the greenfield default, not a reason to rewrite an
+established application outside the requested scope.
+
+## Load the installed path
+
+1. Work from the Rails application root.
+2. Confirm `nitro_kit` appears in `Gemfile.lock` at version 2.x.
+3. Run `bundle show nitro_kit` and treat its output as `NITRO_KIT_ROOT`.
+4. Read `NITRO_KIT_ROOT/docs/agent_guide.md` completely.
+5. Read `NITRO_KIT_ROOT/docs/rails_conventions.md` completely.
+6. For a complete product resource, read
+   `NITRO_KIT_ROOT/docs/patterns/crud_resource.md` completely.
+7. For authentication, teams, application navigation, or settings, read
+   `NITRO_KIT_ROOT/docs/patterns/application_foundation.md` completely.
+8. Read the matching Hotwire recipe before implementing an interaction.
+
+Never use a Nitro Kit 1.x helper, copied component, controller, or Tailwind
+contract as a substitute for the installed API.
+
+## Follow the application grammar
+
+- 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.
+- Model meaningful lifecycle state as a record and expose it through a noun
+  resource instead of a custom controller verb.
+- Keep controllers focused on scoped loading, one domain operation, and one
+  conventional response.
+- Use Rails `form_with` with `NitroKit::FormBuilder`.
+- In an existing application, replace a form control only when Nitro Kit has a
+  genuine semantic and behavioral equivalent. Otherwise preserve it as
+  application-owned Rails and semantic HTML, including its names, values,
+  errors, accessibility, uploads, and browser behavior. Do not retain copied
+  Nitro Kit 1.x source as the fallback.
+- Redirect successful mutations with `303`; render invalid models with `422`.
+- Render HTML on the server and add Hotwire progressively.
+- Test with Minitest and fixtures, including tenancy and unhappy paths.
+- In authenticated admin areas, default to a hybrid `AppShell` with the route's
+  one `h1` and basic actions in its `Toolbar`. Keep one page gutter and avoid
+  repeated headings or automatic Card wrappers.
+- In a new team-aware application, create the first user's `Team` and owner
+  `Membership` together. Put roles on memberships and scope product records
+  through `Current.team`.
+
+Preserve a clear ownership boundary: Rails owns product policy and records;
+Nitro Kit owns component contracts and focused progressive behavior.
+
+## Verify
+
+Run focused model and request tests first. Add a system test only where browser
+behavior is part of the contract. Assert status, visibility, authorization,
+and stable DOM boundaries rather than implementation trivia.

data/plugins/nitro-kit/skills/nitro-kit-rails/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Nitro Kit Rails"
+  short_description: "Build conventional Rails applications with Nitro Kit"
+  default_prompt: "Use $nitro-kit-rails to build this feature on the Nitro Kit Rails path."

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

@@ -0,0 +1,62 @@
+---
+name: nitro-kit-ui
+description: Build or refactor Rails interfaces with Nitro Kit 2's Phlex components, layouts, blocks, FormBuilder, and theme tokens. Use when an application has nitro_kit 2.x in its bundle, mentions Nitro Kit, or asks for a Rails interface that should follow the installed component contract instead of Nitro Kit 1.x helpers, custom markup, CSS overrides, or copied component code.
+---
+
+# Nitro Kit UI
+
+Use the documentation shipped with the application's installed gem as the source of truth. Compose application-owned product UI from gem-owned components.
+
+## Load the matching contract
+
+1. Work from the Rails application root.
+2. Confirm `nitro_kit` appears in `Gemfile.lock`.
+3. Run `bundle show nitro_kit` and treat its output as `NITRO_KIT_ROOT`.
+4. Read `NITRO_KIT_ROOT/docs/agent_guide.md` completely.
+5. Read the relevant sections of `NITRO_KIT_ROOT/docs/component_contracts.md`. Read `customization.md` only for themes, tokens, or application composition.
+6. Inspect the installed component source when constructor or compound-slot details remain unclear. Never guess a component API from memory.
+
+For a Nitro Kit 1.x migration, read
+`NITRO_KIT_ROOT/docs/migration_1_to_2.md` before editing. Inventory product
+flows and behavior first. If the Nitro Kit MCP catalog is available, search it
+by workflow rather than old component name, then select high-level
+compositions before replacing atoms.
+
+If the gem is not installed, say that the skill requires Nitro Kit and follow the application's requested installation scope. Do not substitute APIs from an older Nitro Kit release.
+
+## 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. Use documented `--nk-*` properties for theming and Nitro layout primitives for layout.
+6. Verify closed options and required compound declarations before rendering.
+7. 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.
+8. For team administration and account settings, read
+   `docs/patterns/application_foundation.md`. Put Settings after an
+   `AppNavigation` spacer and use `SettingsLayout` with plain `FormSection`
+   regions instead of a stack of Cards.
+
+## Preserve the boundary
+
+- Do not copy Nitro components into the application.
+- During migration, replace an existing control only when the installed catalog
+  provides a genuine semantic and behavioral equivalent. Otherwise keep or
+  re-express it as application-owned Rails and semantic HTML, optionally inside
+  a custom `form.field` composition. Preserve names, IDs, values, errors,
+  accessibility, uploads, and browser behavior; report the missing equivalent
+  as a Nitro Kit coverage gap.
+- Never downgrade a specialized control to a generic Nitro control for visual
+  consistency, and never retain copied Nitro Kit 1.x source as the fallback.
+- Do not introduce `nk_*` helpers, a general ERB bridge, or generated variant helpers.
+- Do not pass `class:` or `style:`. Prefer component options, composition, or theme tokens. Use `desperately_need_a_class:` only for a genuine external integration boundary.
+- Do not add application-specific behavior to Nitro-owned Stimulus controllers.
+- Do not recreate a Nitro component with raw HTML unless the installed catalog cannot express the semantics.
+
+## Verify
+
+Run the smallest relevant application tests. For component rendering, assert semantic elements and owned `data-nk` or slot attributes rather than private implementation helpers. Exercise invalid and empty states when the UI accepts user input or collections.

data/plugins/nitro-kit/skills/nitro-kit-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Nitro Kit UI"
+  short_description: "Build Rails interfaces with Nitro Kit components"
+  default_prompt: "Use $nitro-kit-ui to build this Rails interface with the installed Nitro Kit components."

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

@@ -0,0 +1,119 @@
+@layer nitro-kit.base {
+  :where([data-nk="accordion"]) {
+    inline-size: 100%;
+    color: var(--nk-color-foreground);
+  }
+
+  :where([data-nk="accordion"] > [data-slot="accordion-item"]) {
+    border-block-end: var(--nk-border-width) solid var(--nk-color-border);
+  }
+
+  :where([data-nk="accordion"] > [data-slot="accordion-item"]:first-child) {
+    border-block-start: var(--nk-border-width) solid var(--nk-color-border);
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"]
+      > [data-slot="accordion-trigger"]
+  ) {
+    display: flex;
+    width: 100%;
+    min-height: 2.75rem;
+    align-items: center;
+    justify-content: space-between;
+    gap: calc(var(--nk-space) * 3);
+    padding: calc(var(--nk-space) * 3) 0;
+    font: inherit;
+    font-weight: var(--nk-font-weight-medium);
+    color: inherit;
+    text-align: start;
+    cursor: pointer;
+    background: transparent;
+    border: 0;
+    list-style: none;
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"]
+      > [data-slot="accordion-trigger"]
+  )::-webkit-details-marker {
+    display: none;
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"]
+      > [data-slot="accordion-trigger"]
+      > [data-slot="accordion-label"]
+  ) {
+    flex: 1;
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"]
+      > [data-slot="accordion-trigger"]
+      > [data-slot="accordion-icon"]
+  ) {
+    flex: none;
+    width: 1rem;
+    height: 1rem;
+    color: var(--nk-color-muted-foreground);
+    transition:
+      color var(--nk-duration-fast) var(--nk-ease),
+      transform var(--nk-duration-fast) var(--nk-ease);
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"][open]
+      > [data-slot="accordion-trigger"]
+      > [data-slot="accordion-icon"]
+  ) {
+    transform: rotate(180deg);
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"]
+      > [data-slot="accordion-content"]
+  ) {
+    padding-block-end: calc(var(--nk-space) * 4);
+    line-height: var(--nk-leading-normal);
+    color: var(--nk-color-muted-foreground);
+  }
+}
+
+@layer nitro-kit.state {
+  @media (hover: hover) {
+    :where(
+      [data-nk="accordion"]
+        > [data-slot="accordion-item"]
+        > [data-slot="accordion-trigger"]:hover
+    ) {
+      color: var(--nk-color-primary);
+    }
+  }
+
+  :where(
+    [data-nk="accordion"]
+      > [data-slot="accordion-item"]
+      > [data-slot="accordion-trigger"]:focus-visible
+  ) {
+    outline: var(--nk-focus-width) solid var(--nk-color-focus);
+    outline-offset: var(--nk-focus-offset);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where(
+      [data-nk="accordion"]
+        > [data-slot="accordion-item"]
+        > [data-slot="accordion-trigger"]
+        > [data-slot="accordion-icon"]
+    ) {
+      transition-duration: 0.01ms;
+    }
+  }
+}

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

@@ -0,0 +1,82 @@
+@layer nitro-kit.base {
+  :where([data-nk="alert"]) {
+    --_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;
+    width: 100%;
+    gap: calc(var(--nk-space) * 2);
+    padding: calc(var(--nk-space) * 4);
+    font-size: var(--nk-text-sm);
+    line-height: var(--nk-leading-normal);
+    color: var(--_nk-alert-foreground);
+    background-color: var(--_nk-alert-background);
+    border-width: var(--nk-border-width);
+    border-color: var(--_nk-alert-border);
+    border-radius: var(--nk-radius-lg);
+  }
+
+  :where([data-nk="alert"] > [data-slot="alert-title"]) {
+    font-size: var(--nk-text-base);
+    font-weight: var(--nk-font-weight-semibold);
+    line-height: var(--nk-leading-tight);
+    text-wrap: balance;
+  }
+
+  :where([data-nk="alert"]:has(> [data-slot="alert-icon"])) {
+    grid-template-columns: auto minmax(0, 1fr);
+  }
+
+  :where([data-nk="alert"] > [data-slot="alert-icon"]) {
+    grid-row: 1 / -1;
+    width: 1.25rem;
+    height: 1.25rem;
+    margin-block-start: 0.0625rem;
+  }
+
+  :where(
+    [data-nk="alert"]:has(> [data-slot="alert-icon"])
+      > [data-slot="alert-title"],
+    [data-nk="alert"]:has(> [data-slot="alert-icon"])
+      > [data-slot="alert-description"]
+  ) {
+    grid-column: 2;
+  }
+
+  :where([data-nk="alert"] > [data-slot="alert-description"]) {
+    max-width: var(--nk-content-lg);
+    color: var(--_nk-alert-foreground);
+    text-wrap: pretty;
+  }
+}
+
+@layer nitro-kit.variant {
+  :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%;
+    }
+  }
+}

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

@@ -0,0 +1,156 @@
+@layer nitro-kit.base {
+  :where([data-nk="app-navigation"]) {
+    --_nk-app-navigation-inset: calc(var(--nk-space) * 3);
+
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    min-inline-size: 0;
+    min-block-size: 0;
+    color: var(--nk-app-shell-sidebar-foreground);
+    font-size: var(--nk-text-sm);
+  }
+
+  :where(
+    [data-nk="app-navigation"] > [data-slot="app-navigation-header"],
+    [data-nk="app-navigation"] > [data-slot="app-navigation-footer"]
+  ) {
+    flex: 0 0 auto;
+  }
+
+  :where([data-nk="app-navigation"] > [data-slot="app-navigation-header"]) {
+    display: flex;
+    align-items: center;
+    min-block-size: var(--nk-app-shell-topbar-height);
+    padding-inline: calc(var(--nk-space) * 6);
+    border-block-end: var(--nk-border-width) solid var(--nk-app-shell-border);
+  }
+
+  :where([data-nk="app-navigation"] > [data-slot="app-navigation-footer"]) {
+    padding: calc(var(--nk-space) * 3);
+    border-block-start: var(--nk-border-width) solid var(--nk-app-shell-border);
+  }
+
+  :where([data-nk="app-navigation"] > [data-slot="app-navigation-body"]) {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--nk-space);
+    min-block-size: 0;
+    padding: var(--_nk-app-navigation-inset);
+    overflow: auto;
+    overscroll-behavior: contain;
+    scrollbar-gutter: stable;
+  }
+
+  :where(
+    [data-nk="app-navigation"] [data-slot="app-navigation-section"],
+    [data-nk="app-navigation"] [data-slot="app-navigation-section-list"]
+  ) {
+    display: flex;
+    flex: 0 0 auto;
+    flex-direction: column;
+    gap: var(--nk-space);
+    min-inline-size: 0;
+  }
+
+  :where(
+    [data-nk="app-navigation"] [data-slot="app-navigation-section-label"]
+  ) {
+    display: block;
+    margin: calc(var(--nk-space) * 4) calc(var(--nk-space) * 2) var(--nk-space);
+    color: var(--nk-color-muted-foreground);
+    font-size: var(--nk-text-xs);
+    font-weight: var(--nk-font-weight-semibold);
+    line-height: var(--nk-leading-tight);
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-item"]) {
+    flex: 0 0 auto;
+    min-inline-size: 0;
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-item-link"]) {
+    display: flex;
+    gap: calc(var(--nk-space) * 2);
+    align-items: center;
+    min-block-size: var(--nk-control-height-md);
+    padding: calc(var(--nk-space) * 2) calc(var(--nk-space) * 3);
+    color: inherit;
+    font-weight: var(--nk-font-weight-medium);
+    line-height: var(--nk-leading-tight);
+    text-decoration: none;
+    border-radius: var(--nk-radius-md);
+    transition:
+      color var(--nk-duration-normal) var(--nk-ease),
+      background-color var(--nk-duration-normal) var(--nk-ease);
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-item-label"]) {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  :where(
+    [data-nk="app-navigation"] [data-slot="app-navigation-item-icon"],
+    [data-nk="app-navigation"] [data-slot="app-navigation-item-badge"]
+  ) {
+    flex: 0 0 auto;
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-item-badge"]) {
+    margin-inline-start: auto;
+    font-variant-numeric: tabular-nums;
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-divider"]) {
+    flex: 0 0 auto;
+    display: block;
+    block-size: var(--nk-border-width);
+    margin-block: calc(var(--nk-space) * 2);
+    margin-inline: calc(var(--_nk-app-navigation-inset) * -1);
+    background: var(--nk-app-shell-border);
+    border: 0;
+  }
+
+  :where([data-nk="app-navigation"] [data-slot="app-navigation-spacer"]) {
+    flex: 1 1 calc(var(--nk-space) * 4);
+    min-block-size: calc(var(--nk-space) * 4);
+  }
+}
+
+@layer nitro-kit.state {
+  :where(
+    [data-nk="app-navigation"]
+      [data-slot="app-navigation-item-link"][data-state="current"]
+  ) {
+    color: var(--nk-app-shell-sidebar-accent-foreground);
+    background: var(--nk-app-shell-sidebar-accent);
+  }
+
+  @media (hover: hover) {
+    :where(
+      [data-nk="app-navigation"] [data-slot="app-navigation-item-link"]:hover
+    ) {
+      color: var(--nk-app-shell-sidebar-accent-foreground);
+      background: var(--nk-app-shell-sidebar-accent);
+    }
+  }
+
+  :where(
+    [data-nk="app-navigation"]
+      [data-slot="app-navigation-item-link"]: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"] [data-slot="app-navigation-item-link"]) {
+      transition-duration: 0.01ms;
+    }
+  }
+}