# NitroKit Documentation

NitroKit is a set of generic UI components to help you build your Ruby on Rails application. Rather than being fancy it is purposefully modest. Instead of giving you a black box, it is provided as a generator and a set of components that give you a starting point to build upon.

## Quick Info
- Easy to customize, accessible, Rails native
- Components are generated into your app, not hidden in a gem
- All components accept keyword arguments passed as HTML attributes
- Special handling for `class:` (merged with Tailwind) and `data:` attributes
- Variants can be passed as `variant: :primary` or method names like `nk_primary_button`

## Requirements
1. Ruby on Rails 7.0+
2. Tailwind CSS V4
3. Stimulus (optional – only for components with JavaScript)

## Principles
1. Feel Rails native
2. Convention over configuration
3. Don't be fancy
4. Keep it simple
5. Fewest possible dependencies

## Getting Started

Installing Nitro Kit into both new and old apps takes just a few steps.

### Fully automatic installation (from new Rails app):
```shell
bin/rails app:template LOCATION="https://nitrokit.dev/t/install"
```

### Manual installation:
1. Add the gem:
```sh
bundle add nitro_kit
bundle install
```

2. Install Tailwind CSS (version 4 recommended):
```shell
bundle add tailwindcss-rails
bundle install
bin/rails tailwindcss:install
```

3. Configure Tailwind CSS by replacing `app/assets/tailwind/application.css` with:
```css
@import "tailwindcss";

@theme {
  --color-foreground: var(--color-zinc-900);
  --color-background: var(--color-white);

  --color-border: var(--color-zinc-200);
  --color-ring: var(--color-blue-600);
  --color-muted: var(--color-zinc-100);
  --color-muted-content: var(--color-zinc-500);
  --color-primary: var(--color-zinc-800);
  --color-primary-content: var(--zinc-800);
  --color-primary-foreground: var(--color-zinc-100);
  --color-destructive: var(--color-red-500);
  --color-destructive-content: var(--color-red-800);
  --color-destructive-foreground: var(--color-white);
}

@layer base {
  [data-theme="dark"] {
    --color-foreground: var(--color-zinc-100);
    --color-background: var(--color-zinc-950);

    --color-border: var(--color-zinc-700);
    --color-ring: var(--color-blue-700);
    --color-muted: var(--color-zinc-800);
    --color-muted-content: var(--color-zinc-400);
    --color-primary: var(--color-zinc-50);
    --color-primary-content: var(--color-zinc-50);
    --color-primary-foreground: var(--color-zinc-900);
    --color-destructive: var(--color-red-900);
    --color-destructive-content: var(--color-red-600);
    --color-destructive-foreground: var(--color-white);
  }
}

@variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

@layer base {
  * {
    @apply border-border min-w-0 ring-ring;
  }

  body {
    /* Nitro Kit looks great in Inter as well */
    /* https://rsms.me/inter */
    @apply bg-background text-foreground font-sans;
  }
}
```

4. Add components to your app:
```bash
bin/rails generate nitro_kit:component all # or a list of individual components
```

### Stimulus
Nitro Kit requires Stimulus if you add components that depend on JavaScript. It expects to load all Stimulus controllers from `app/javascript/controllers/`.

## Good to Know

### Make it your own
Nitro Kit exists to give you a starting point. Don't be afraid to change the components to fit your needs and tastes. Customization options:
1. Copy them to a new file and go from there
2. Subclass components and override `class` or other methods
3. Make helper methods that pass `class:` or other arguments directly

### Attributes
- Nitro Kit components accept any keyword argument, passed as HTML attributes
- `nk_button(thing: "1")` becomes `<button […] thing="1">`
- Special attributes:
  - `class:` - merged with default classes using tailwind_merge
  - `data:` - merged with special cases for `turbo.action` and `turbo.controller`

### Variants
- Different presentations for components (e.g., Button can be `primary` or `destructive`)
- Can be chosen via `variant: :primary` or special method names like `nk_primary_button`

### Text or block content
Components can accept either strings or blocks:
- `nk_button "Click me"`
- `nk_button { "Click me" }`

## Component Reference

### Button
Buttons trigger actions or navigate.

```erb
<%= nk_button "Button" %>
<%= nk_primary_button "Primary" %>
<%= nk_destructive_button "Destructive" %>
<%= nk_ghost_button "Ghost" %>
<%= nk_button("Text and icon", icon: "caravan") %>
<%= nk_button_link_to "Go home", root_path %>
<%= nk_destructive_button_to "Delete", post_path(@post), method: :delete %>
```

**API:** `nk_button(text = nil, href: nil, variant: :default, size: :md, icon: nil, icon_right: nil, **attrs)`

**Sizes:** `:xs`, `:sm`, `:md` (default), `:lg`

**Additional methods:**
- `nk_button_group` - Groups buttons together
- `nk_button_link_to` - Mimics Rails' `link_to`
- `nk_button_to` - Mimics Rails' `button_to`

### Form Builder
Enhanced Rails form builder with styled fields and structured form composition.

```erb
<%= nk_form_with model: @post do |f| %>
  <%= f.fieldset(legend: "New Post", description: "Tell the world") do |fs| %>
    <%= f.group do %>
      <%= f.field :title %>
      <%= f.field :category_id, as: :select, options: Category.pluck(:name, :id) %>
      <%= f.field :body, as: :textarea, rows: 6 %>
      <%= f.field :publish, as: :checkbox, description: "Should we tell the world?" %>
      <%= f.field :kind, as: :radio_group, options: Post.kinds.map { |k| [k.capitalize, k] }, value: "article" %>
      <%= f.submit %>
    <% end %>
  <% end %>
<% end %>
```

**API:**
- `nk_form_with(**attrs, &block)` - Enhanced version of Rails' `form_with`
- `nk_form_for(record, **attrs, &block)` - Enhanced version of Rails' `form_for`
- `form.fieldset(legend: "text", description: "text", **attrs, &block)` - Groups related form fields with legend and description
- `form.field(field_name, **attrs)` - Main method for generating form fields
- `form.group(**attrs, &block)` - Groups form elements together
- `form.submit(value = "Save changes", **attrs)` - Render submit button

**Form Field Options (`field` method):**
- `as:` - Input type (`:text`, `:textarea`, `:select`, `:checkbox`, `:radio_group`, `:password`, `:email`, `:number`, `:url`, `:date`, `:datetime`, `:time`, `:file`, `:hidden`, `:boolean`)
- `options:` - Array of [display_text, value] pairs for `:select` and `:radio_group`
- `rows:` - Number of rows for `:textarea`
- `description:` - Help text below the field
- `label:` - Custom label text (defaults to humanized field_name)
- `value:` - Default/pre-selected value
- `checked:` - For checkboxes, sets default checked state
- `multiple:` - For select fields, allows multiple selections
- `placeholder:` - Placeholder text
- `required:`, `disabled:`, `readonly:` - Standard HTML attributes

### Alert
Display important messages to users.

```erb
<%= nk_alert do |a| %>
  <%= nk_icon :"ice-cream-cone" %>
  <%= a.title "Free ice cream!" %>
  <%= a.description "Better be quick everyone." %>
<% end %>
```

Variants: `:default`, `:success`, `:warning`, `:error`

### Card
Container component for grouped content.

```erb
<%= nk_card do |c| %>
  <%= c.title "Seal the deal" %>
  <%= c.body do %>
    You've worked for this moment. It's time to make it official.
  <% end %>
  <%= c.footer(class: "justify-end") do %>
    <%= nk_primary_button "Shake on it", icon: "handshake" %>
  <% end %>
<% end %>
```

### Input
Text input fields with type-specific helpers.

```erb
<%= nk_input %>
<%= nk_email_field %>
<%= nk_password_field %>
<%= nk_number_field %>
<%= nk_url_field %>
```

### Select
Dropdown selection input.

```erb
<%= nk_select "journey", "direction", %w[North East South West], value: "South" %>
```

### Checkbox
Checkbox inputs with label support.

```erb
<%= nk_checkbox %>
<%= nk_checkbox label: "Accept terms" %>
```

### Radio Button
Radio button inputs for single selection.

```erb
<%= nk_radio_button "name", "value" %>
<%= nk_radio_button_group value: "zero" do |g| %>
  <%= g.title "Choose your poison" %>
  <%= g.item name: "poison", value: "coke", label: "Coke" %>
  <%= g.item name: "poison", value: "zero", label: "Coke Zero" %>
<% end %>
```

### Switch
Toggle switch component.

```erb
<%= nk_switch %>
<%= nk_switch label: "Enable notifications", size: :sm %>
```

### Badge
Small status indicators.

```erb
<%= nk_badge("Default") %>
<%= nk_badge("Important", variant: :primary, size: :sm) %>
```

### Icon
SVG icons using Lucide icons.

```erb
<%= nk_icon "car" %>
<%= nk_icon "car", size: :lg %>
<%= nk_icon "car", class: "size-64", stroke_width: 0.2 %>
```

### Avatar
User avatars in different sizes.

```erb
<%= nk_avatar "user-photo.jpg" %>
<%= nk_avatar "user-photo.jpg", size: :lg %>
```

### Table
Display tabular data.

```erb
<%= nk_table do |t| %>
  <%= t.thead do %>
    <%= t.th "Name" %>
    <%= t.th "Email" %>
  <% end %>
  <%= t.tbody do %>
    <%= t.tr do %>
      <%= t.td "John Doe" %>
      <%= t.td "john@example.com" %>
    <% end %>
  <% end %>
<% end %>
```

### Dialog
Modal dialogs with trigger.

```erb
<%= nk_dialog do |d| %>
  <%= d.trigger "Open Dialog" %>
  <%= d.dialog do %>
    <%= d.title "Confirm Action" %>
    <%= d.description "Are you sure you want to continue?" %>
    <%= d.close_button %>
  <% end %>
<% end %>
```

### Dropdown
Contextual menu dropdown.

```erb
<%= nk_dropdown do |d| %>
  <%= d.trigger "Menu" %>
  <%= d.content do %>
    <%= d.title "Actions" %>
    <%= d.item_to "Edit", edit_path %>
    <%= d.separator %>
    <%= d.destructive_item_to "Delete", delete_path, data: { turbo_method: "delete" } %>
  <% end %>
<% end %>
```

### Tabs
Tabbed content navigation.

```erb
<%= nk_tabs(default: :general) do |t| %>
  <%= t.tabs do %>
    <%= t.tab(:general) { "General" } %>
    <%= t.tab(:advanced) { "Advanced" } %>
  <% end %>
  <%= t.panel(:general) do %>
    General settings content
  <% end %>
  <%= t.panel(:advanced) do %>
    Advanced settings content
  <% end %>
<% end %>
```

### Accordion
Collapsible content sections.

```erb
<%= nk_accordion do |a| %>
  <%= a.item do %>
    <%= a.trigger "Section 1" %>
    <%= a.content do %>
      Content for section 1
    <% end %>
  <% end %>
  <%= a.item do %>
    <%= a.trigger "Section 2" %>
    <%= a.content do %>
      Content for section 2
    <% end %>
  <% end %>
<% end %>
```

### Toast
Toast notifications with flash message support.

```erb
# In layout:
<html data-controller="nk--toast">
  <body>
    <%= nk_toast %>
  </body>
</html>

# Trigger from button:
<%= nk_button "Show Toast", data: { **nk_toast_action(title: "Success!", description: "Action completed") } %>

# In controller for flash messages:
<%= nk_toast_turbo_stream_refresh %>
```

### Tooltip
Hover tooltips for additional information.

```erb
<%= nk_tooltip(content: "Helpful information") do |t| %>
  <%= nk_button "Hover me" %>
<% end %>
```

### Pagination
Page navigation controls with Pagy support.

```erb
<%= nk_pagination do |p| %>
  <%= p.prev %>
  <%= p.page(1) %>
  <%= p.ellipsis %>
  <%= p.page(42) %>
  <%= p.next %>
<% end %>

# With Pagy:
<%= nk_pagy_nav(pagy) %>
```

### Combobox
Searchable dropdown with typeahead.

```erb
<%= nk_combobox "name", options: [["Mario Kart", "mario_kart"], ["Need for Speed", "need_for_speed"]] %>
```

### Datepicker
Date selection input component.

```erb
<%= nk_datepicker %>
```

### Field
Flexible form field component with label, error handling, and composable structure.

```erb
<%# Basic usage within form builder %>
<%= nk_form_for :user do |f| %>
  <%= f.field :email, as: :email, label: "Email address", description: "We'll never share your email" %>
<% end %>

<%# Standalone field usage %>
<%= nk_field name: :email, as: "email", label: "E-mail address", description: "We'll never share your email", placeholder: "[email protected]" %>

<%# Composable structure with explicit control %>
<%= nk_form_for :user do |f| %>
  <%= f.field :email, as: :email, label: "E-mail address" do |ff| %>
    <%= ff.label %>
    <%= ff.description %>
    <%= ff.control %>
    <%= ff.errors %>
  <% end %>
<% end %>
```

**API:**
- `nk_field(name:, as:, label: nil, description: nil, placeholder: nil, **attrs)` - Standalone field helper
- `f.field(field_name, **attrs, &block)` - Field within form builder
- Within composable block: `ff.label`, `ff.control`, `ff.description`, `ff.errors`

**Field Parameters:**
- `name:` - Field name (Symbol or String)
- `as:` - Input type (same options as Form Builder field method)
- `label:` - Label text
- `description:` - Help text below field
- `placeholder:` - Placeholder text
- `**attrs` - HTML attributes for the input element

### Label
Form labels.

```erb
<%= nk_label :user, :email, "Email address" %>
```

### Textarea
Multiline text input.

```erb
<%= nk_textarea %>
```

## Premium Components

Premium components are available for licensed users:
- **Layouts** - Sidebar and top navigation layout templates
- **Details Table** - Enhanced table component with advanced features
- **Dropzone** - File upload component with drag-and-drop functionality
- **Progressive Image** - Optimized image loading component
- **Ransack Table** - Advanced searchable and sortable table integration

## Tips
- All components accept any keyword argument passed as HTML attributes
- Use `class:` to merge with default Tailwind classes
- Components with JS functionality require Stimulus
- Variants can be method names (e.g., `nk_primary_button`) or parameters (`variant: :primary`)
- Many components accept either text arguments or blocks for content
- Components are generated into your app - modify them as needed!
- Make components your own - copy, subclass, or create helper methods
- Special handling for `data:` attributes with Turbo actions and controllers

## License
Visit https://nitrokit.dev for licensing information and to purchase premium components.