### Set Up Better UI Gem for Local Development

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

This bash script outlines the steps to clone the Better UI repository, install Ruby and npm dependencies, build the assets, run tests, and start the dummy application server for local development. It requires Git, Bundler, Yarn, and Ruby.

```bash
# Clone the repository
git clone https://github.com/umbertopeserico/better_ui.git
cd better_ui

# Install Ruby dependencies
bundle install

# Install npm dependencies and build
cd assets
yarn install
yarn build
cd ..

# Run tests
bundle exec rake test

# Start the dummy app server
cd test/dummy
bundle exec rails server
```

--------------------------------

### Import BetterUi Pre-built CSS

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Includes the pre-built CSS for BetterUi in your main CSS file. This option is the simplest way to get started with BetterUi's styling. It also configures Tailwind CSS to scan gem and application files for class usage.

```css
@import "@pandev-srl/better-ui/css";

/* Scan gem templates for Tailwind classes */
@source "../../../vendor/bundle/**/*.{rb,erb}";

/* Scan application files for Tailwind classes */
@source "../../**/*.{erb,html,rb}";
@source "../javascript/**/*.js";
```

--------------------------------

### Run BetterUi Install Generator

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Executes the BetterUi installation generator in a Rails application. This command can optionally copy the theme CSS for customization using the '--copy-theme' flag.

```bash
bin/rails generate better_ui:install

# Use --copy-theme flag to copy the theme CSS for customization:
bin/rails generate better_ui:install --copy-theme
```

--------------------------------

### Start Development Server with Lookbook Previews

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Starts a dummy Rails application server to view component previews using Lookbook. This is useful for developing and testing UI components in isolation.

```bash
# Start dummy Rails app with Lookbook previews
cd test/dummy
bundle exec rails server

# View components at http://localhost:3000/rails/view_components
# Preview classes in spec/components/previews/better_ui/
```

--------------------------------

### Direct Render Drawer Layout Example (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/layout.md

Demonstrates how to directly render the `BetterUi::Drawer::LayoutComponent` using the `render` method, providing an alternative to the helper syntax. This example includes header, sidebar, and main content configuration.

```erb
<%= render BetterUi::Drawer::LayoutComponent.new do |layout| %>
  <% layout.with_header(sticky: true) do |header| %>
    <% header.with_logo { image_tag("logo.svg") } %>
    <% header.with_mobile_menu_button do %>
      <button data-action="click->better-ui--drawer--layout#toggle">
        <svg class="w-6 h-6"><!-- Menu icon --></svg>
      </button>
    <% end %>
  <% end %>

  <% layout.with_sidebar do |sidebar| %>
    <% sidebar.with_navigation { render "shared/nav" } %>
  <% end %>

  <% layout.with_main do %>
    <%= yield %>
  <% end %>
<% end %>
```

--------------------------------

### Full Card Structure with Header, Body, and Footer (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/card.md

Illustrates a comprehensive CardComponent setup including a header, body, and footer. This example shows how to add titles, main content, and action buttons.

```erb
<%= bui_card(size: :lg, shadow: true) do |c| %>
  <% c.with_header do %>
    <h3 class="text-lg font-semibold">Card Title</h3>
  <% end %>

  <% c.with_body do %>
    <p>Main content area with automatic padding based on size.</p>
  <% end %>

  <% c.with_footer do %>
    <div class="flex justify-end gap-2">
      <%= bui_button(style: :ghost) { "Cancel" } %>
      <%= bui_button { "Save" } %>
    </div>
  <% end %>
<% end %>
```

--------------------------------

### Install Dependencies Command (Bash)

Source: https://github.com/pandev-srl/better_ui/blob/main/README.md

Installs all project dependencies using Bundler.

```bash
bundle install
```

--------------------------------

### Install Ruby Gem Dependencies

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Installs Ruby gem dependencies using Bundler. This command is essential for setting up the development environment for the Better UI gem.

```bash
# Ruby gem dependencies
bundle install
```

--------------------------------

### Install BetterUi npm Package

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Installs the BetterUi npm package, which provides JavaScript Stimulus Controllers and CSS theme files. This can be done using either yarn or npm. It's recommended to use yarn for installation.

```bash
# Using yarn (recommended)
yarn add @pandev-srl/better-ui

# Or using npm
npm install @pandev-srl/better-ui
```

--------------------------------

### ButtonComponent Direct Render Example 2 (Ruby)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/button.md

Shows direct rendering of a styled submit button with various parameters. This example highlights the flexibility in configuring the button's appearance and behavior.

```ruby
<%= render BetterUi::ButtonComponent.new(
  label: "Submit Form",
  variant: :success,
  style: :solid,
  type: :submit,
  size: :lg
) %>
```

--------------------------------

### Complete Admin Layout Example (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/CONTEXT7.md

An example of a complete admin layout using Better UI's Drawer::LayoutComponent. This showcases advanced configuration with a dark theme header, custom logo, actions, a detailed sidebar with navigation groups and items, and main content.

```erb
<%= render BetterUi::Drawer::LayoutComponent.new(sidebar_breakpoint: :lg) do |layout| %>
  <% layout.with_header(variant: :dark, sticky: true) do |header| %>
    <% header.with_logo { "Admin Panel" } %>
    <% header.with_mobile_menu_button do %>
      <button data-action="click->better-ui--drawer--layout#toggle" class="text-white p-2">
        <svg class="w-6 h-6"><!-- Hamburger --></svg>
      </button>
    <% end %>
    <% header.with_actions do %>
      <%= render "shared/user_menu" %>
    <% end %>
  <% end %>

  <% layout.with_sidebar(variant: :dark, width: :md) do |sidebar| %>
    <% sidebar.with_navigation do %>
      <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Dashboard", variant: :dark) do |group| %>
        <% group.with_item(label: "Overview", href: admin_path, active: true) %>
        <% group.with_item(label: "Analytics", href: admin_analytics_path) %>
      <% end %>

      <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Management", variant: :dark) do |group| %>
        <% group.with_item(label: "Users", href: admin_users_path, badge: "12", badge_variant: :danger) %>
        <% group.with_item(label: "Settings", href: admin_settings_path) %>
      <% end %>
    <% end %>

    <% sidebar.with_footer do %>
      <p class="text-sm text-gray-400">v1.0.0</p>
    <% end %>
  <% end %>

  <% layout.with_main do %>
    <div class="p-8">
      <%= yield %>
    </div>
  <% end %>
<% end %>
```

--------------------------------

### Full Card Structure Example

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/CONTEXT7.md

Demonstrates a fully structured card with header, body, and footer. Supports various parameters like size and shadow.

```erb
<%= render BetterUi::CardComponent.new(size: :lg, shadow: true) do |c| %>
  <% c.with_header do %>
    <h3 class="text-lg font-semibold">Card Title</h3>
  <% end %>

  <% c.with_body do %>
    <p>Main content area.</p>
  <% end %>

  <% c.with_footer do %>
    <div class="flex justify-end gap-2">
      <%= render BetterUi::ButtonComponent.new(label: "Cancel", style: :ghost) %>
      <%= render BetterUi::ButtonComponent.new(label: "Save") %>
    </div>
  <% end %>
<% end %>
```

--------------------------------

### Install BetterUi Gem and NPM Package

Source: https://context7.com/pandev-srl/better_ui/llms.txt

Instructions for installing the BetterUi Ruby gem and its corresponding npm package. This involves adding the gem to the Gemfile, running bundle install, and adding the npm package via yarn.

```bash
# Add to Gemfile
gem "better_ui"

# Install dependencies
bundle install
yarn add @pandev-srl/better-ui
```

--------------------------------

### Component Unit Test Example

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

An example of a component unit test using Ruby and ViewComponent::TestHelpers. This test renders a ButtonComponent with a specific variant and asserts that the correct CSS class is applied to the rendered button element.

```ruby
def test_renders_with_variant
  render_inline(BetterUi::ButtonComponent.new(label: "Test", variant: :success))
  assert_selector("button.bg-success-600")
end
```

--------------------------------

### UiFormBuilder Setup with Form Components

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/CONTEXT7.md

Demonstrates setting up and using the UiFormBuilder for creating form inputs like text, password, textarea, number, and checkbox fields.

```erb
<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_text_input :email %>
  <%= f.bui_password_input :password %>
  <%= f.bui_textarea :bio %>
  <%= f.bui_number_input :age %>
  <%= f.bui_checkbox :terms %>
  <%= render BetterUi::ButtonComponent.new(label: "Submit", type: :submit) %>
<% end %>
```

--------------------------------

### Registration Form Example

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/password_input.md

A comprehensive example of a registration form using the Better UI form builder, including text and password inputs, and a submit button.

```erb
<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_text_input :email %>

  <%= f.bui_password_input :password,
    hint: "Use at least 8 characters with a mix of letters, numbers, and symbols" %>

  <%= f.bui_password_input :password_confirmation %>

  <%= bui_button(type: :submit) { "Create Account" } %>
<% end %>
```

--------------------------------

### Full Sidebar with All Sections and Icons

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/sidebar.md

A comprehensive example showcasing a sidebar with header, navigation, and footer sections, including navigation items with icons and badges. This demonstrates advanced usage patterns.

```erb
<%= bui_drawer_sidebar(variant: :light) do |sidebar| %>
  <% sidebar.with_header do %>
    <div class="flex items-center gap-3 px-4">
      <%= image_tag "logo.svg", class: "h-10" %>
      <span class="text-lg font-semibold">My App</span>
    </div>
  <% end %>

  <% sidebar.with_navigation do %>
    <%= bui_drawer_nav_group(title: "Overview") do |group| %>
      <% group.with_item(label: "Dashboard", href: dashboard_path, active: current_page?(dashboard_path)) do |item| %>
        <% item.with_icon do %>
          <svg class="w-5 h-5"><!-- Home icon --></svg>
        <% end %>
      <% end %>

      <% group.with_item(label: "Analytics", href: analytics_path) do |item| %>
        <% item.with_icon do %>
          <svg class="w-5 h-5"><!-- Chart icon --></svg>
        <% end %>
      <% end %>
    <% end %>

    <%= bui_drawer_nav_group(title: "Management") do |group| %>
      <% group.with_item(label: "Users", href: users_path) do |item| %>
        <% item.with_icon do %>
          <svg class="w-5 h-5"><!-- Users icon --></svg>
        <% end %>
        <% item.with_badge { User.count } %>
      <% end %>

      <% group.with_item(label: "Settings", href: settings_path) do |item| %>
        <% item.with_icon do %>
          <svg class="w-5 h-5"><!-- Cog icon --></svg>
        <% end %>
      <% end %>
    <% end %>
  <% end %>

  <% sidebar.with_footer do %>
    <div class="flex items-center gap-3 px-4 py-3 border-t">
      <%= image_tag current_user.avatar_url, class: "w-10 h-10 rounded-full" %>
      <div>
        <p class="font-medium"><%= current_user.name %></p>
        <p class="text-sm text-gray-500"><%= current_user.email %></p>
      </div>
    </div>
  <% end %>
<% end %>
```

--------------------------------

### ButtonComponent Direct Render Example 1 (Ruby)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/button.md

Demonstrates direct rendering of the ButtonComponent in Ruby, passing parameters like `label` and `variant`. This method is used when integrating the component within a Ruby context.

```ruby
<%= render BetterUi::ButtonComponent.new(
  label: "Click me",
  variant: :primary
) %>
```

--------------------------------

### Render BetterUi Button and Card Components

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Demonstrates how to directly render BetterUi's ButtonComponent and CardComponent within Rails ERB templates. This showcases basic usage with common attributes like label, variant, and size.

```erb
<%= render BetterUi::ButtonComponent.new(
  label: "Click me",
  variant: "primary",
  size: "lg"
) %>

<%= render BetterUi::CardComponent.new(size: "lg") do |c|
  c.with_header { "Card Title" }
  c.with_body { "Card content" }
end %>
```

--------------------------------

### Comment Form Example (Ruby)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/textarea.md

An example of a comment form using the TextareaComponent for the comment body. It highlights setting required fields, maxlength, and placeholders, along with a submit button.

```erb
<%= form_with model: @comment, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_textarea :body,
    label: "Comment",
    rows: 4,
    maxlength: 1000,
    placeholder: "Share your thoughts...",
    required: true %>

  <%= bui_button(type: :submit, size: :sm) { "Post Comment" } %>
<% end %>
```

--------------------------------

### Change Password Form Example

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/password_input.md

An example demonstrating a change password form, utilizing the PasswordInputComponent for current password, new password, and confirmation fields.

```erb
<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_password_input :current_password,
    label: "Current Password" %>

  <%= f.bui_password_input :password,
    label: "New Password",
    hint: "Must be different from current password" %>

  <%= f.bui_password_input :password_confirmation,
    label: "Confirm New Password" %>

  <%= bui_button(type: :submit) { "Update Password" } %>
<% end %>
```

--------------------------------

### Dark Sidebar Configuration with Helper Syntax

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/sidebar.md

Illustrates how to create a dark-themed sidebar using the helper syntax. This example includes custom styling for the header and navigation sections to match the dark variant.

```erb
<%= bui_drawer_sidebar(variant: :dark) do |sidebar| %>
  <% sidebar.with_header do %>
    <div class="flex items-center gap-2 text-white">
      <%= image_tag "logo-white.svg", class: "h-8" %>
      <span class="font-bold">Admin</span>
    </div>
  <% end %>

  <% sidebar.with_navigation do %>
    <%= bui_drawer_nav_group(title: "Menu", variant: :dark) do |group| %>
      <% group.with_item(label: "Dashboard", href: "/") %>
      <% group.with_item(label: "Users", href: "/users") %>
    <% end %>
  <% end %>
<% end %>
```

--------------------------------

### Standalone Number Input Helper

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/number_input.md

Provides an example of using the standalone bui_number_input helper to create a price input field with a prefix icon, min/max values, step, and placeholder.

```erb
<%= bui_number_input("product[price]",
  label: "Price",
  min: 0,
  max: 99999,
  step: 0.01,
  placeholder: "0.00"
) do |c|
%>
  <% c.with_prefix_icon { "$" } %>
<% end %>
```

--------------------------------

### Install npm Package Dependencies

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Installs npm package dependencies within the 'assets' directory using Yarn. This is required for building the JavaScript and CSS assets for the Better UI npm package.

```bash
# npm package dependencies (for building JS/CSS)
cd assets
yarn install
```

--------------------------------

### Layout with Different Breakpoint Example (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/layout.md

Shows how to adjust the responsive breakpoint for the sidebar drawer using the `sidebar_breakpoint` parameter. The sidebar will collapse into a drawer on screens smaller than the specified breakpoint.

```erb
<%= bui_drawer_layout(sidebar_breakpoint: :xl) do |layout| %>
  <%# Sidebar will become a drawer on screens smaller than xl (1280px) %>
  <% layout.with_header { ... } %>
  <% layout.with_sidebar { ... } %>
  <% layout.with_main { ... } %>
<% end %>
```

--------------------------------

### Direct Render Text Input Component

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/text_input.md

Provides an example of rendering the `TextInputComponent` directly using the `render` method. This approach is suitable for more complex component compositions or when not using form builders.

```erb
<%= render BetterUi::Forms::TextInputComponent.new(
  name: "user[email]",
  label: "Email Address",
  hint: "We'll never share your email",
  placeholder: "you@example.com",
  required: true
) %>
```

--------------------------------

### Multiple Nav Groups Example

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_group.md

Demonstrates how to render multiple navigation groups on the same page to organize different sections of a sidebar menu. Each group can have its own title and items.

```erb
<%= bui_drawer_nav_group(title: "Overview") do |group| %>
  <% group.with_item(label: "Dashboard", href: dashboard_path, active: current_page?(dashboard_path)) %>
  <% group.with_item(label: "Analytics", href: analytics_path, active: current_page?(analytics_path)) %>
<% end %>

<%= bui_drawer_nav_group(title: "Management") do |group| %>
  <% group.with_item(label: "Users", href: users_path, active: current_page?(users_path)) %>
  <% group.with_item(label: "Teams", href: teams_path, active: current_page?(teams_path)) %>
  <% group.with_item(label: "Projects", href: projects_path, active: current_page?(projects_path)) %>
<% end %>

<%= bui_drawer_nav_group(title: "Settings") do |group| %>
  <% group.with_item(label: "Account", href: account_path) %>
  <% group.with_item(label: "Security", href: security_path) %>
<% end %>
```

--------------------------------

### Nav Item Helper with HTTP Method

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_item.md

Shows how to specify an HTTP method for a navigation item, useful for actions like logout. The `:delete` method is used as an example.

```erb
<%= bui_drawer_nav_item("Logout", logout_path, method: :delete) do |item| %>
  <% item.with_icon do %>
    <svg class="w-5 h-5"><!-- Logout icon --></svg>
  <% end %>
<% end %>
```

--------------------------------

### Rating Input Pattern

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/number_input.md

An example of a rating input pattern using bui_number_input, configured with specific min, max, step values, and a hint message.

```erb
<%= bui_number_input("rating",
  label: "Rating",
  min: 1,
  max: 5,
  step: 1,
  hint: "Rate from 1 to 5 stars"
) %>
```

--------------------------------

### TextareaComponent Examples

Source: https://context7.com/pandev-srl/better_ui/llms.txt

Demonstrates the usage of the TextareaComponent for multi-line text input. It supports adjustable rows, character limits, and different resize behaviors.

```erb
<%# Basic textarea %>
<%= render BetterUi::Forms::TextareaComponent.new(
  name: "post[content]",
  label: "Content",
  rows: 10,
  placeholder: "Write your content here...",
  maxlength: 5000,
  hint: "Maximum 5000 characters"
) %>

<%# Fixed size textarea (no resize) %>
<%= render BetterUi::Forms::TextareaComponent.new(
  name: "user[bio]",
  label: "Bio",
  rows: 6,
  resize: :none
) %>

<%# Short description with character limit %>
<%= render BetterUi::Forms::TextareaComponent.new(
  name: "post[excerpt]",
  label: "Excerpt",
  rows: 3,
  maxlength: 280,
  hint: "Brief summary shown in listings (max 280 characters)"
) %>

<%# Comment form %>
<%= render BetterUi::Forms::TextareaComponent.new(
  name: "comment[body]",
  label: "Comment",
  rows: 4,
  maxlength: 1000,
  placeholder: "Share your thoughts...",
  required: true
) %>
```

--------------------------------

### Direct Render Nav Item with Active State

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_item.md

Shows direct rendering of the Drawer::NavItemComponent with an active state. This method is useful for complex component setups.

```erb
<%= render BetterUi::Drawer::NavItemComponent.new(
  label: "Dashboard",
  href: dashboard_path,
  active: true
) do |item| %>
  <% item.with_icon do %>
    <svg class="w-5 h-5"><!-- icon --></svg>
  <% end %>
<% end %>
```

--------------------------------

### Add BetterUi Gem to Gemfile

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Adds the BetterUi gem dependency to your Rails application's Gemfile. Ensure you have Rails 8.1.1 or higher installed. After adding the gem, run 'bundle install' to install it.

```ruby
gem "better_ui"
```

--------------------------------

### Host App CSS Setup for Better UI

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Demonstrates two methods for integrating Better UI's CSS into a host application. Option 1 imports all pre-built CSS, while Option 2 allows for selective module imports for greater customization. Both options require scanning gem components for Tailwind classes.

```css
/* Option 1: Import pre-built CSS (includes everything) */
@import "@pandev-srl/better-ui/css";

/* Option 2: Import individual modules for customization */
@import "tailwindcss";
@import "@pandev-srl/better-ui/theme";       /* Design tokens */
@import "@pandev-srl/better-ui/typography";  /* Typography utilities */
@import "@pandev-srl/better-ui/utilities";   /* General utilities */

/* Required: Scan gem components for Tailwind classes */
@source "../../../vendor/bundle/**/*.{rb,erb}";
```

--------------------------------

### Component Testing Philosophy Example

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Demonstrates the recommended approach for testing UI components by focusing on the public API and rendered output, rather than internal implementation details. This ensures tests are robust and less prone to breaking with refactors.

```ruby
# ✅ CORRECT - Tests public API and rendered output
def test_renders_button_with_label
  render_inline(BetterUi::ButtonComponent.new(label: "Click me"))
  assert_selector("button", text: "Click me")
end

# ❌ WRONG - Tests private implementation
def test_component_classes_method
  component = BetterUi::ButtonComponent.new(label: "Test")
  assert_equal "btn-primary", component.send(:component_classes)
end
```

--------------------------------

### Basic Drawer Layout Example (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/layout.md

Demonstrates the basic usage of the `bui_drawer_layout` helper for creating a page layout with a header, sidebar, and main content area. It includes configurations for sticky headers and mobile menu buttons.

```erb
<%= bui_drawer_layout do |layout| %>
  <% layout.with_header(sticky: true) do |header| %>
    <% header.with_logo { image_tag("logo.svg") } %>
    <% header.with_mobile_menu_button do %>
      <button data-action="click->better-ui--drawer--layout#toggle">
        <svg class="w-6 h-6"><!-- Menu icon --></svg>
      </button>
    <% end %>
  <% end %>

  <% layout.with_sidebar do |sidebar| %>
    <% sidebar.with_navigation { render "shared/nav" } %>
  <% end %>

  <% layout.with_main do %>
    <%= yield %>
  <% end %>
<% end %>
```

--------------------------------

### Configure Tailwind CSS v4

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Sets up Tailwind CSS v4 in your project by installing the necessary packages and configuring the postcss.config.js file. This ensures Tailwind CSS works correctly with BetterUi.

```bash
yarn add tailwindcss@next @tailwindcss/postcss@next
```

--------------------------------

### Basic Sidebar Usage with Helper Syntax

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/sidebar.md

Demonstrates the basic usage of the sidebar component using helper syntax. It shows how to configure the variant and width, and how to add header, navigation, and footer content.

```erb
<%= bui_drawer_sidebar(variant: :light, width: :md) do |sidebar| %>
  <% sidebar.with_header { image_tag("logo.svg") } %>

  <% sidebar.with_navigation do %>
    <%= bui_drawer_nav_group(title: "Main") do |group| %>
      <% group.with_item(label: "Dashboard", href: dashboard_path, active: true) %>
      <% group.with_item(label: "Settings", href: settings_path) %>
    <% end %>
  <% end %>

  <% sidebar.with_footer { "User Info" } %>
<% end %>
```

--------------------------------

### Configure Vite for Rails with Tailwind CSS

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

This snippet shows how to configure Vite for Rails integration using `vite-plugin-ruby`. It includes setting up PostCSS with Tailwind CSS for styling. Ensure `vite-plugin-ruby` and `@tailwindcss/postcss` are installed as dependencies.

```javascript
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'

export default defineConfig({
  plugins: [RubyPlugin()],
  css: {
    postcss: {
      plugins: [require('@tailwindcss/postcss')()]
    }
  }
})
```

--------------------------------

### Basic Nav Group Example with Helper Syntax

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_group.md

Demonstrates the basic usage of the `bui_drawer_nav_group` helper to create a navigation group with a title and items. It shows how to add items with labels, links, active states, and icons.

```erb
<%= bui_drawer_nav_group(title: "Main") do |group| %>
  <% group.with_item(label: "Dashboard", href: dashboard_path, active: true) do |item| %>
    <% item.with_icon { "🏠" } %>
  <% end %>

  <% group.with_item(label: "Settings", href: settings_path) do |item| %>
    <% item.with_icon { "⚙️" } %>
  <% end %>
<% end %>
```

--------------------------------

### PostCSS Configuration for Tailwind CSS v4

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Configures the postcss.config.js file to use the '@tailwindcss/postcss' plugin, which is required for Tailwind CSS v4 integration within your project.

```javascript
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {}
  }
}
```

--------------------------------

### Use BetterUi Form Builder

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Illustrates how to utilize BetterUi's UiFormBuilder for creating forms in Rails. This builder provides enhanced form input components like ui_text_input and ui_password_input.

```erb
<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f|
  f.ui_text_input :name
  f.ui_text_input :email, hint: "We'll never share your email"
  f.ui_password_input :password
  f.ui_textarea :bio, rows: 6
end %>
```

--------------------------------

### Ruby ViewComponent Preview with Lookbook

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Demonstrates how to create a ViewComponent preview class for the ButtonComponent using Lookbook. The preview class inherits from ViewComponent::Preview and defines methods for different preview scenarios. Dependencies include the ViewComponent gem and Lookbook.

```ruby
class BetterUi::ButtonComponentPreview < ViewComponent::Preview
  # @label All Variants
  def all_variants
    # Preview implementation - returns rendered HTML or uses template
  end
end
```

--------------------------------

### Override BetterUi CSS Variables

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Customizes the BetterUi theme by overriding CSS variables directly in a custom CSS file. This allows for fine-grained control over colors and other design tokens, such as the primary color.

```css
@import "tailwindcss";
@import "@pandev-srl/better-ui/theme";       /* Design tokens */
@import "@pandev-srl/better-ui/typography";  /* Typography utilities */
@import "@pandev-srl/better-ui/utilities";   /* General utilities */

@theme inline {
  /* Override primary color to your brand */
  --color-primary-500: oklch(0.60 0.24 220);
  --color-primary-600: oklch(0.50 0.26 220);
  /* ... other overrides */
}
```

--------------------------------

### Configure Stimulus Controllers in application.js

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Integrates BetterUi's Stimulus Controllers into your Rails application's JavaScript entry point. This involves importing necessary modules and registering the controllers with the Stimulus Application instance.

```javascript
import { Application } from "@hotwired/stimulus"
import { registerControllers } from "@pandev-srl/better-ui"

const application = Application.start()
registerControllers(application)
```

--------------------------------

### Override Component Colors with CSS

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/CUSTOMIZATION.md

Shows how to override default component colors using CSS utility classes. Examples include a gradient button (`btn-gradient`) and an outline gradient button (`btn-outline-gradient`) that utilize theme variables.

```css
/* Custom button themes */
.btn-gradient {
  @apply bg-gradient-to-r from-primary-500 to-accent-500
         hover:from-primary-600 hover:to-accent-600
         text-white font-medium;
}

.btn-outline-gradient {
  @apply relative bg-white;
  background: linear-gradient(white, white) padding-box,
              linear-gradient(to right, var(--color-primary-500), var(--color-accent-500)) border-box;
  border: 2px solid transparent;
}
```

--------------------------------

### Import BetterUi CSS Modules for Customization

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/INSTALLATION.md

Imports individual BetterUi CSS modules, allowing for greater customization of the theme. This approach requires importing Tailwind CSS first, followed by specific BetterUi theme, typography, and utility modules.

```css
@import "tailwindcss";
@import "@pandev-srl/better-ui/theme";       /* Design tokens */
@import "@pandev-srl/better-ui/typography";  /* Typography utilities */
@import "@pandev-srl/better-ui/utilities";   /* General utilities */

/* Scan gem templates for Tailwind classes */
@source "../../../vendor/bundle/**/*.{rb,erb}";

/* Scan application files for Tailwind classes */
@source "../../**/*.{erb,html,rb}";
@source "../javascript/**/*.js";
```

--------------------------------

### Install BetterUi Gem and NPM Package

Source: https://github.com/pandev-srl/better_ui/blob/main/README.md

This snippet shows how to add the BetterUi Ruby gem to your Gemfile and install the corresponding npm package. It also includes the necessary bundle install and yarn add commands.

```ruby
# Gemfile
gem "better_ui"

```

```bash
bundle install
yarn add @pandev-srl/better-ui

```

--------------------------------

### Basic Nav Item Helper

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_item.md

Renders a basic navigation item with a label and URL using the helper syntax. This is the simplest way to create a nav item.

```erb
<%= bui_drawer_nav_item("Dashboard", dashboard_path) %>
```

--------------------------------

### Basic Sidebar Rendering with Direct Syntax

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/sidebar.md

Illustrates how to render the sidebar component directly using its class and `render` method. This approach provides more explicit control over component instantiation.

```erb
<%= render BetterUi::Drawer::SidebarComponent.new(
  variant: :light,
  width: :md
) do |sidebar| %>
  <% sidebar.with_header { image_tag("logo.svg") } %>

  <% sidebar.with_navigation do %>
    <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Main") do |group| %>
      <% group.with_item(label: "Dashboard", href: dashboard_path, active: true) %>
      <% group.with_item(label: "Settings", href: settings_path) %>
    <% end %>
  <% end %>

  <% sidebar.with_footer { "User Info" } %>
<% end %>
```

--------------------------------

### Direct Render Nav Item with HTTP Method

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_item.md

Demonstrates direct rendering of the Drawer::NavItemComponent with a specified HTTP method. This is useful for actions that require a specific HTTP verb.

```erb
<%= render BetterUi::Drawer::NavItemComponent.new(
  label: "Logout",
  href: logout_path,
  method: :delete
) %>
```

--------------------------------

### Contact Form Message Example (Ruby)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/textarea.md

Demonstrates using the TextareaComponent for a contact form message field. This example shows setting label, rows, required status, and placeholder for user input.

```erb
<%= bui_textarea("message",
  label: "Message",
  rows: 6,
  required: true,
  placeholder: "How can we help you?"
) %>
```

--------------------------------

### Direct Render Drawer Header (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/header.md

Shows how to directly render the `BetterUi::Drawer::HeaderComponent` using its class name and initializing it with parameters. This provides more explicit control over component instantiation.

```erb
<%= render BetterUi::Drawer::HeaderComponent.new(
  sticky: true,
  variant: :light
) do |header| %>
  <% header.with_logo { image_tag("logo.svg", class: "h-8") } %>

  <% header.with_navigation do %>
    <nav class="flex gap-4">
      <%= link_to "Home", root_path %>
      <%= link_to "About", about_path %>
    </nav>
  <% end %>

  <% header.with_mobile_menu_button do %>
    <button class="p-2">
      <svg class="w-6 h-6"><!-- Menu icon --></svg>
    </button>
  <% end %>

  <% header.with_actions do %>
    <%= link_to "Sign In", sign_in_path %>
  <% end %>
<% end %>
```

--------------------------------

### Run All Tests with Coverage

Source: https://github.com/pandev-srl/better_ui/blob/main/CLAUDE.md

Executes all tests for the Better UI gem and generates a code coverage report. This is a comprehensive check to ensure the stability and correctness of the components.

```bash
# Run all tests with coverage
bundle exec rake test
```

--------------------------------

### Render Button and Card Components using Helper Syntax

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/COMPONENTS.md

Demonstrates the recommended helper syntax for rendering BetterUi components like buttons and cards. This approach is concise and leverages Rails helpers for easier integration.

```erb
<%# Simple and concise %>
<%= bui_button(variant: :primary) { "Click me" } %>

<%= bui_card do |c| %>
  <% c.with_body { "Content" } %>
<% end %>
```

--------------------------------

### Form Builder Integration Example (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/README.md

Demonstrates integration with Rails' `form_with` using Better UI's custom `UiFormBuilder`. Includes examples for various input types like text, password, textarea, number, and checkboxes.

```erb
<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.ui_text_input :name %>
  <%= f.ui_text_input :email, hint: "We'll never share your email" %>
  <%= f.ui_password_input :password %>
  <%= f.ui_textarea :bio, rows: 6 %>
  <%= f.ui_number_input :age, min: 0, max: 120 %>
  <%= f.bui_checkbox :newsletter, label: "Subscribe to newsletter" %>
  <%= f.bui_checkbox_group :roles, [["Admin", "admin"], ["Editor", "editor"]] %>
<% end %>
```

--------------------------------

### Application Layout with Drawer Component (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/layout.md

An example of integrating the `bui_drawer_layout` into an application's main layout file (`application.html.erb`). This demonstrates a common pattern for creating a full-page layout with a sticky header, sidebar, and main content area.

```erb
<%# app/views/layouts/application.html.erb %>
<!DOCTYPE html>
<html>
  <head>
    <%= yield :head %>
  </head>
  <body>
    <%= bui_drawer_layout do |layout| %>
      <% layout.with_header(sticky: true, variant: :light) do |header| %>
        <% header.with_logo do %>
          <%= link_to root_path do %>
            <%= image_tag "logo.svg", class: "h-8" %>
          <% end %>
        <% end %>

        <% header.with_navigation do %>
          <nav class="hidden lg:flex gap-6">
            <%= link_to "Dashboard", dashboard_path %>
            <%= link_to "Projects", projects_path %>
          </nav>
        <% end %>

        <% header.with_mobile_menu_button do %>
          <button data-action="click->better-ui--drawer--layout#toggle" class="lg:hidden p-2">
            <svg class="w-6 h-6"><!-- Hamburger icon --></svg>
          </button>
        <% end %>

        <% header.with_actions do %>
          <%= render "shared/user_menu" %>
        <% end %>
      <% end %>

      <% layout.with_sidebar(variant: :light) do |sidebar| %>
        <% sidebar.with_navigation do %>
          <%= render "shared/sidebar_nav" %>
        <% end %>

        <% sidebar.with_footer do %>
          <%= render "shared/sidebar_footer" %>
        <% end %>
      <% end %>

      <% layout.with_main do %>
        <div class="p-6">
          <%= yield %>
        </div>
      <% end %>
    <% end %>
  </body>
</html>
```

--------------------------------

### Warning Alert Display

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/action_messages.md

Example of displaying a warning message with an outline style, a title, and a dismissible button.

```erb
<%= bui_action_messages(
  ["This action cannot be undone", "Please confirm before proceeding"],
  variant: :warning,
  style: :outline,
  title: "Warning",
  dismissible: true
) %>
```

--------------------------------

### Basic Drawer Header (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/header.md

Demonstrates the basic usage of the `bui_drawer_header` helper with logo, navigation, mobile menu button, and actions. It utilizes ERB templating for rendering.

```erb
<%= bui_drawer_header(sticky: true, variant: :light) do |header| %>
  <% header.with_logo do %>
    <%= image_tag "logo.svg", class: "h-8" %>
  <% end %>

  <% header.with_navigation do %>
    <nav class="flex gap-4">
      <%= link_to "Home", root_path %>
      <%= link_to "About", about_path %>
    </nav>
  <% end %>

  <% header.with_mobile_menu_button do %>
    <button class="p-2">
      <svg class="w-6 h-6"><!-- Menu icon --></svg>
    </button>
  <% end %>

  <% header.with_actions do %>
    <%= link_to "Sign In", sign_in_path %>
  <% end %>
<% end %>
```

--------------------------------

### ButtonComponent Danger Confirmation (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/button.md

Example of a danger button with a confirmation prompt before performing an action. It uses `data-turbo-confirm` and `data-turbo-method` for destructive actions.

```erb
<%= bui_button(
  variant: :danger,
  style: :outline,
  data: {
    turbo_confirm: "Are you sure?",
    turbo_method: "delete"
  }
) { "Delete" } %>
```

--------------------------------

### Direct Component Render - Success with Auto-Dismiss

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/action_messages.md

Example of rendering `ActionMessagesComponent` for a success message with specific styling, dismissibility, and auto-dismiss timer.

```erb
<%= render BetterUi::ActionMessagesComponent.new(
  variant: :success,
  style: :solid,
  dismissible: true,
  auto_dismiss: 5,
  messages: ["Your changes have been saved."]
) %>
```

--------------------------------

### Direct Render Number Input Component

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/number_input.md

Illustrates rendering the NumberInputComponent directly, including setting a prefix icon, min/max values, step, and placeholder.

```erb
<%= render BetterUi::Forms::NumberInputComponent.new(
  name: "product[price]",
  label: "Price",
  min: 0,
  max: 99999,
  step: 0.01,
  placeholder: "0.00"
) do |c|
%>
  <% c.with_prefix_icon { "$" } %>
<% end %>
```

--------------------------------

### Direct Rendering of CardComponent (Ruby)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/card.md

Demonstrates how to directly render the CardComponent using the `render` helper in Ruby. This approach is common in Rails views.

```ruby
<%= render BetterUi::CardComponent.new do |c| %>
  <% c.with_body do %>
    <p>Card content goes here</p>
  <% end %>
<% end %>
```

--------------------------------

### Blog Post Editor Example (Ruby)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/textarea.md

A common pattern demonstrating a blog post editor using multiple Better UI components, including TextareaComponent for excerpt and content. It showcases integration with form builders and submit buttons.

```erb
<%= form_with model: @post, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_text_input :title %>

  <%= f.bui_textarea :excerpt,
    label: "Excerpt",
    rows: 3,
    maxlength: 300,
    hint: "Brief summary shown in listings" %>

  <%= f.bui_textarea :content,
    label: "Content",
    rows: 20,
    placeholder: "Write your post..." %>

  <%= bui_button(type: :submit) { "Publish" } %>
<% end %>
```

--------------------------------

### Direct Render Text Input with Prefix Icon

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/forms/text_input.md

Illustrates rendering the `TextInputComponent` directly with a prefix icon. This allows for programmatic control over component rendering and its associated slots.

```erb
<%= render BetterUi::Forms::TextInputComponent.new(
  name: "user[username]",
  label: "Username"
) do |c|
  <% c.with_prefix_icon { "@" } %>
<% end %>
```

--------------------------------

### ButtonComponent Group (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/button.md

Illustrates how to group multiple buttons together using flexbox for a cohesive UI element. This example shows a cancel and save button side-by-side.

```erb
<div class="flex gap-2">
  <%= bui_button(variant: :secondary, style: :ghost) { "Cancel" } %>
  <%= bui_button(variant: :primary) { "Save" } %>
</div>
```

--------------------------------

### Right-Positioned Sidebar Layout Example (ERB)

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/layout.md

Illustrates how to configure the `bui_drawer_layout` to position the sidebar on the right side of the page. This is useful for settings panels or secondary navigation.

```erb
<%= bui_drawer_layout(sidebar_position: :right) do |layout| %>
  <% layout.with_sidebar(position: :right) do |sidebar| %>
    <% sidebar.with_navigation { "Settings Panel" } %>
  <% end %>

  <% layout.with_main { "Content" } %>
<% end %>
```

--------------------------------

### Wide Sidebar Configuration with Helper Syntax

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/sidebar.md

Shows how to configure a wider sidebar using the helper syntax by setting the `width` parameter to `:lg`. This is useful for navigation requiring more space.

```erb
<%= bui_drawer_sidebar(width: :lg) do |sidebar| %>
  <% sidebar.with_navigation do %>
    <%# More space for detailed navigation %>
  <% end %>
<% end %>
```

--------------------------------

### Run Tests with Coverage Command (Bash)

Source: https://github.com/pandev-srl/better_ui/blob/main/README.md

Executes all tests and generates a code coverage report.

```bash
COVERAGE=true bundle exec rake test
```

--------------------------------

### CheckboxComponent Examples

Source: https://context7.com/pandev-srl/better_ui/llms.txt

Illustrates the CheckboxComponent for single checkbox inputs. It offers color variants, label positioning, hints, and error display capabilities.

```erb
<%# Basic checkbox %>
<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "user[terms]",
  label: "I agree to the terms and conditions"
) %>

<%# Checkbox with variant and checked state %>
<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "settings[notifications]",
  label: "Enable notifications",
  variant: :success,
  checked: true
) %>

<%# Checkbox with label on left %>
<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "user[active]",
  label: "Active",
  label_position: :left
) %>

<%# Checkbox with validation error %>
<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "user[terms]",
  label: "I agree to the terms",
  errors: ["You must agree to the terms"]
) %>

<%# Settings form pattern %>
<div class="space-y-4">
  <%= render BetterUi::Forms::CheckboxComponent.new(
    name: "settings[email_notifications]",
    label: "Email notifications",
    hint: "Receive updates via email"
  ) %>

  <%= render BetterUi::Forms::CheckboxComponent.new(
    name: "settings[push_notifications]",
    label: "Push notifications",
    hint: "Receive browser push notifications"
  ) %>
</div>
```

--------------------------------

### Ruby: Component Inheritance for Custom Variants

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/CUSTOMIZATION.md

Illustrates the concept of component inheritance in Ruby, where custom components can extend Better UI base components. This is a more structured way to create reusable, customized components.

```ruby
# Create custom components that extend BetterUi:

```

--------------------------------

### Active State Nav Item Helper

Source: https://github.com/pandev-srl/better_ui/blob/main/doc/components/drawer/nav_item.md

Demonstrates how to render a navigation item in an active state using the helper syntax. The `active: true` parameter visually highlights the item.

```erb
<%= bui_drawer_nav_item("Dashboard", dashboard_path, active: true) %>
```