better_ui 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64c0ed9d31f8392770eaedb20fe0727444877a4fa8886b6241bf70c5d093b03e
-  data.tar.gz: bbf85b45c167057d13b403d3270eb0bf744cab5d1b2646ee3c6ed88c6cdfceca
+  metadata.gz: 8b3c7255ce65e6a53ed2ee42174475f656461303920e1a4e6c9912fe3ecd4d4a
+  data.tar.gz: 4c4c5063560d6edcb534fd1856869928e4b3f0456e7d86dea76f216bb3c4ae2e
 SHA512:
-  metadata.gz: 9fa81ccba17b2fc8bf7922ebb4e41a38328cd8439d851008dce1eb1a9b06e47b0481db570f2377ca4a69b65ae91814306584ec24f0d1514e2114763b34db4d89
-  data.tar.gz: 92ac9e0d3d760f148f25c0b0fa11e2d57aa7d56d8cf367df637b2521deb8f7bdc11b59063e8fd523e11db0c3de4d8276e824ef1388fada0c71199c4fe05d5395
+  metadata.gz: b06273f6f5fbdd050f7f1fcdc20b1a15663af200f25d076472d31c77bc953e39a68db31633de2f64c888e0a0f0459c1fa8b75cefd4dc919bb4a18f2397da09de
+  data.tar.gz: 1ecb849cc505cda578e2c93493dcc8464e52ca3e64d55a618cb3d4181b1d6eb55130c0a3173c93d3761539ac0fd402e0c52a4a3a050b8df291f5dece55095739

data/README.md

@@ -44,13 +44,9 @@ registerControllers(application)
 /* @import "@pandev-srl/better-ui/utilities"; */
 ```
 
+**Start using components** - `bui_*` helpers are available automatically:
 ```erb
-<!-- In your views -->
-<%= render BetterUi::ButtonComponent.new(
-  label: "Get Started",
-  variant: "primary",
-  size: "lg"
-) %>
+<%= bui_button(label: "Get Started", variant: :primary, size: :lg) %>
 ```
 
 ## Features
@@ -59,6 +55,7 @@ registerControllers(application)
 - **ViewComponent Architecture**: Encapsulated, testable, and reusable components
 - **Tailwind CSS v4**: Leverages the latest Tailwind features with OKLCH color space
 - **Fully Customizable**: 9 semantic color variants with complete theme control
+- **View Helpers**: Concise `bui_*` helpers available automatically (no setup required)
 - **Form Builder Integration**: Seamless integration with Rails forms via `UiFormBuilder`
 - **Stimulus Controllers**: Interactive components with built-in JavaScript behaviors
 - **Accessible by Default**: ARIA attributes and keyboard navigation support
@@ -86,11 +83,7 @@ A versatile button component with multiple styles, sizes, and states.
 - **Features**: Loading states, icons, disabled states
 
 ```erb
-<%= render BetterUi::ButtonComponent.new(
-  label: "Save Changes",
-  variant: "success",
-  style: "solid"
-) do |c| %>
+<%= bui_button(label: "Save Changes", variant: :success, style: :solid) do |c| %>
   <% c.with_icon_before { "💾" } %>
 <% end %>
 ```
@@ -103,7 +96,7 @@ A flexible container component with customizable padding and optional slots.
 - **Slots**: header, body, footer
 
 ```erb
-<%= render BetterUi::CardComponent.new(size: :lg, style: :bordered) do |c| %>
+<%= bui_card(size: :lg, style: :bordered) do |c| %>
   <% c.with_header { "Card Title" } %>
   <% c.with_body { "Card content goes here" } %>
   <% c.with_footer { "Footer content" } %>
@@ -117,8 +110,8 @@ Display notifications, alerts, and validation messages with style.
 - **Features**: Dismissible, auto-dismiss, titles, icons
 
 ```erb
-<%= render BetterUi::ActionMessagesComponent.new(
-  variant: "danger",
+<%= bui_action_messages(
+  variant: :danger,
   title: "Validation Errors",
   messages: @model.errors.full_messages,
   dismissible: true,
@@ -132,7 +125,7 @@ Display notifications, alerts, and validation messages with style.
 Standard text input with error handling and icon support.
 
 ```erb
-<%= render BetterUi::Forms::TextInputComponent.new(
+<%= bui_text_input(
   name: "user[email]",
   label: "Email Address",
   hint: "We'll never share your email",
@@ -146,7 +139,7 @@ Standard text input with error handling and icon support.
 Numeric input with min/max validation and optional spinners.
 
 ```erb
-<%= render BetterUi::Forms::NumberInputComponent.new(
+<%= bui_number_input(
   name: "product[price]",
   label: "Price",
   min: 0,
@@ -161,7 +154,7 @@ Numeric input with min/max validation and optional spinners.
 Password field with visibility toggle functionality.
 
 ```erb
-<%= render BetterUi::Forms::PasswordInputComponent.new(
+<%= bui_password_input(
   name: "user[password]",
   label: "Password",
   hint: "Minimum 8 characters"
@@ -172,7 +165,7 @@ Password field with visibility toggle functionality.
 Multi-line text input with resizing options.
 
 ```erb
-<%= render BetterUi::Forms::TextareaComponent.new(
+<%= bui_textarea(
   name: "post[content]",
   label: "Content",
   rows: 6,
@@ -185,7 +178,7 @@ Multi-line text input with resizing options.
 Single checkbox with color variants and label positioning.
 
 ```erb
-<%= render BetterUi::Forms::CheckboxComponent.new(
+<%= bui_checkbox(
   name: "user[terms]",
   label: "I agree to the terms and conditions",
   variant: :primary
@@ -196,7 +189,7 @@ Single checkbox with color variants and label positioning.
 Multiple checkboxes for selecting from a collection.
 
 ```erb
-<%= render BetterUi::Forms::CheckboxGroupComponent.new(
+<%= bui_checkbox_group(
   name: "user[roles]",
   collection: [["Admin", "admin"], ["Editor", "editor"]],
   legend: "User Roles",
@@ -215,13 +208,13 @@ BetterUi provides a complete drawer layout system for building responsive admin
 - **NavGroupComponent**: Grouped navigation with titles
 
 ```erb
-<%= render BetterUi::Drawer::LayoutComponent.new do |layout| %>
+<%= bui_drawer_layout do |layout| %>
   <% layout.with_header do |header| %>
     <% header.with_logo { "MyApp" } %>
   <% end %>
   <% layout.with_sidebar do |sidebar| %>
     <% sidebar.with_navigation do %>
-      <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Menu") do |group| %>
+      <%= bui_drawer_nav_group(title: "Menu") do |group| %>
         <% group.with_item(label: "Dashboard", href: "/", active: true) %>
         <% group.with_item(label: "Settings", href: "/settings") %>
       <% end %>
@@ -247,6 +240,27 @@ BetterUi includes a custom form builder for seamless Rails form integration:
 <% end %>
 ```
 
+## Available View Helpers
+
+| Helper | Component |
+|--------|-----------|
+| `bui_button` | ButtonComponent |
+| `bui_card` | CardComponent |
+| `bui_action_messages` | ActionMessagesComponent |
+| `bui_text_input` | Forms::TextInputComponent |
+| `bui_number_input` | Forms::NumberInputComponent |
+| `bui_password_input` | Forms::PasswordInputComponent |
+| `bui_textarea` | Forms::TextareaComponent |
+| `bui_checkbox` | Forms::CheckboxComponent |
+| `bui_checkbox_group` | Forms::CheckboxGroupComponent |
+| `bui_drawer_layout` | Drawer::LayoutComponent |
+| `bui_drawer_sidebar` | Drawer::SidebarComponent |
+| `bui_drawer_header` | Drawer::HeaderComponent |
+| `bui_drawer_nav_item` | Drawer::NavItemComponent |
+| `bui_drawer_nav_group` | Drawer::NavGroupComponent |
+
+> **Note**: You can also use ViewComponent directly with `render BetterUi::*Component.new(...)` if you prefer the explicit rendering syntax.
+
 ## Documentation
 
 - [**Installation Guide**](doc/INSTALLATION.md) - Detailed setup and configuration instructions
@@ -343,4 +357,4 @@ Powered by:
 
 ## Acknowledgments
 
-Special thanks to the Ruby on Rails community and all contributors who help make BetterUi better.
+Special thanks to the Ruby on Rails community and all contributors who help make BetterUi better.

data/app/components/better_ui/drawer/sidebar_component.rb

@@ -183,6 +183,7 @@ module BetterUi
           "flex-1",
           "overflow-y-auto",
           "p-4",
+          "space-y-6",
           @navigation_classes
         ].compact)
       end

data/app/components/better_ui/tabs/container_component/container_component.html.erb

@@ -0,0 +1,40 @@
+<div class="<%= component_classes %>" <%= tag.attributes(html_attributes) %>>
+  <%# Tab list %>
+  <div role="tablist"
+       aria-label="Tabs"
+       class="<%= tablist_classes %> <%= tablist_order_class %>">
+    <% tabs.each do |tab| %>
+      <%= tab %>
+    <% end %>
+  </div>
+
+  <%# Panels container (only for JS mode) %>
+  <% if mode == :js && panels.any? %>
+    <div class="<%= panels_classes %> <%= panels_order_class %>">
+      <% panels.each do |panel| %>
+        <%= panel %>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%# Loading overlay for Turbo mode %>
+  <% if mode == :turbo && show_loading %>
+    <div data-<%= controller_name %>-target="loader"
+         class="hidden fixed inset-0 z-50 pointer-events-none"
+         aria-hidden="true"
+         aria-live="polite">
+      <% if loader? %>
+        <%= loader %>
+      <% else %>
+        <div class="absolute bg-white/80 dark:bg-grayscale-900/80 flex items-center justify-center"
+             data-<%= controller_name %>-target="loaderOverlay">
+          <svg class="animate-spin h-8 w-8 <%= spinner_color_class %>" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+            <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+            <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+          </svg>
+          <span class="sr-only">Caricamento...</span>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+</div>

data/app/components/better_ui/tabs/container_component.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Tabs
+    # A flexible tabs container component with two operating modes.
+    #
+    # This component provides a tabbed interface with support for:
+    # - **JS mode**: Client-side tab switching (all content in DOM)
+    # - **Turbo mode**: Server-rendered content via Turbo Frames
+    #
+    # @example Basic JS mode tabs
+    #   <%= render BetterUi::Tabs::ContainerComponent.new(mode: :js) do |tabs| %>
+    #     <% tabs.with_tab(id: "profile", label: "Profile", active: true) %>
+    #     <% tabs.with_tab(id: "settings", label: "Settings") %>
+    #     <% tabs.with_panel(id: "profile", active: true) { "Profile content" } %>
+    #     <% tabs.with_panel(id: "settings") { "Settings content" } %>
+    #   <% end %>
+    #
+    # @example Turbo mode with Turbo Frames
+    #   <%= render BetterUi::Tabs::ContainerComponent.new(mode: :turbo, frame_id: "tab-content") do |tabs| %>
+    #     <% tabs.with_tab(id: "profile", label: "Profile", href: profile_path, active: true) %>
+    #     <% tabs.with_tab(id: "settings", label: "Settings", href: settings_path) %>
+    #   <% end %>
+    #   <turbo-frame id="tab-content"><%= yield %></turbo-frame>
+    class ContainerComponent < ApplicationComponent
+      # Valid operating modes
+      MODES = %i[js turbo].freeze
+
+      # Tab visual styles
+      STYLES = %i[underline pills bordered].freeze
+
+      # Size configurations with tab-specific styling
+      SIZES = %i[xs sm md lg xl].freeze
+
+      # Tab alignment options
+      ALIGNMENTS = %i[start center end stretch].freeze
+
+      # Tab list positions
+      POSITIONS = %i[top bottom left right].freeze
+
+      # @!method with_tab
+      #   Slot for rendering tab buttons/links
+      #   @yieldparam [BetterUi::Tabs::TabComponent] tab the tab component instance
+      #   @yieldreturn [String] the HTML content for the tab
+      renders_many :tabs, lambda { |**args|
+        TabComponent.new(
+          **args,
+          mode: @mode,
+          style: @style,
+          variant: @variant,
+          size: @size,
+          frame_id: @frame_id,
+          container_id: container_id
+        )
+      }
+
+      # @!method with_panel
+      #   Slot for rendering tab panels (JS mode only)
+      #   @yieldparam [BetterUi::Tabs::PanelComponent] panel the panel component instance
+      #   @yieldreturn [String] the HTML content for the panel
+      renders_many :panels, lambda { |**args|
+        PanelComponent.new(**args, container_id: container_id)
+      }
+
+      # @!method with_loader
+      #   Slot for rendering a custom loader (Turbo mode only)
+      #   @yieldreturn [String] the HTML content for the custom loader
+      renders_one :loader
+
+      # Initializes a new tabs container component.
+      #
+      # @param mode [Symbol] operating mode (:js, :turbo), defaults to :js
+      # @param style [Symbol] visual style (:underline, :pills, :bordered), defaults to :underline
+      # @param variant [Symbol] color variant from VARIANTS, defaults to :primary
+      # @param size [Symbol] size (:xs, :sm, :md, :lg, :xl), defaults to :md
+      # @param alignment [Symbol] tab alignment (:start, :center, :end, :stretch), defaults to :start
+      # @param position [Symbol] tab list position (:top, :bottom, :left, :right), defaults to :top
+      # @param frame_id [String, nil] Turbo Frame ID (required for turbo mode)
+      # @param default_tab [String, nil] ID of the default active tab
+      # @param persist [Boolean] persist active tab in URL hash or localStorage
+      # @param persist_key [String, nil] localStorage key for persistence
+      # @param show_loading [Boolean, nil] show loading indicator in turbo mode (default: true for turbo)
+      # @param loader_delay [Integer] delay in milliseconds before showing the loader (default: 1000)
+      # @param id [String, nil] explicit ID for the container (auto-generated if nil)
+      # @param options [Hash] additional HTML attributes
+      #
+      # @raise [ArgumentError] if mode is invalid
+      # @raise [ArgumentError] if style is invalid
+      # @raise [ArgumentError] if size is invalid
+      # @raise [ArgumentError] if alignment is invalid
+      # @raise [ArgumentError] if position is invalid
+      # @raise [ArgumentError] if turbo mode is used without frame_id
+      def initialize(
+        mode: :js,
+        style: :underline,
+        variant: :primary,
+        size: :md,
+        alignment: :start,
+        position: :top,
+        frame_id: nil,
+        default_tab: nil,
+        persist: false,
+        persist_key: nil,
+        show_loading: nil,
+        loader_delay: 1000,
+        id: nil,
+        **options
+      )
+        @mode = validate_mode(mode)
+        @style = validate_style(style)
+        @variant = validate_variant(variant)
+        @size = validate_size(size)
+        @alignment = validate_alignment(alignment)
+        @position = validate_position(position)
+        @frame_id = frame_id
+        @default_tab = default_tab
+        @persist = persist
+        @persist_key = persist_key
+        @show_loading = show_loading.nil? ? (@mode == :turbo) : show_loading
+        @loader_delay = loader_delay
+        @explicit_id = id
+        @options = options
+
+        validate_turbo_requirements!
+      end
+
+      # Returns the operating mode.
+      # @return [Symbol] the mode (:js or :turbo)
+      attr_reader :mode
+
+      # Returns the visual style.
+      # @return [Symbol] the style (:underline, :pills, or :bordered)
+      attr_reader :style
+
+      # Returns the color variant.
+      # @return [Symbol] the variant
+      attr_reader :variant
+
+      # Returns the size.
+      # @return [Symbol] the size
+      attr_reader :size
+
+      # Returns the tab alignment.
+      # @return [Symbol] the alignment
+      attr_reader :alignment
+
+      # Returns the tab list position.
+      # @return [Symbol] the position
+      attr_reader :position
+
+      # Returns the Turbo Frame ID.
+      # @return [String, nil] the frame_id
+      attr_reader :frame_id
+
+      # Returns the default active tab ID.
+      # @return [String, nil] the default_tab
+      attr_reader :default_tab
+
+      # Returns whether persistence is enabled.
+      # @return [Boolean] the persist flag
+      attr_reader :persist
+
+      # Returns the persistence key for localStorage.
+      # @return [String, nil] the persist_key
+      attr_reader :persist_key
+
+      # Returns whether loading indicator is shown in turbo mode.
+      # @return [Boolean] the show_loading flag
+      attr_reader :show_loading
+
+      # Returns the loader delay in milliseconds.
+      # @return [Integer] the loader_delay value
+      attr_reader :loader_delay
+
+      # Generates a unique container ID.
+      # @return [String] the container ID
+      def container_id
+        @container_id ||= @explicit_id || "tabs-#{SecureRandom.hex(4)}"
+      end
+
+      private
+
+      # Returns the complete CSS classes for the container.
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          "bui-tabs",
+          position_layout_class,
+          @options[:class]
+        ].compact)
+      end
+
+      # Returns layout class based on position.
+      # @return [String] the layout class
+      # @api private
+      def position_layout_class
+        case @position
+        when :left, :right then "flex"
+        else ""
+        end
+      end
+
+      # Returns CSS classes for the tab list container.
+      # @return [String] the merged CSS class string
+      # @api private
+      def tablist_classes
+        css_classes([
+          "bui-tabs__list",
+          "flex",
+          tablist_direction_class,
+          alignment_class,
+          style_container_class
+        ].compact)
+      end
+
+      # Returns flex direction based on position.
+      # @return [String] the direction class
+      # @api private
+      def tablist_direction_class
+        case @position
+        when :left, :right then "flex-col"
+        else "flex-row"
+        end
+      end
+
+      # Returns alignment classes.
+      # @return [String] the alignment class
+      # @api private
+      def alignment_class
+        case @alignment
+        when :start then "justify-start"
+        when :center then "justify-center"
+        when :end then "justify-end"
+        when :stretch then "justify-stretch"
+        end
+      end
+
+      # Returns style-specific container classes.
+      # @return [String] the style container class
+      # @api private
+      def style_container_class
+        case @style
+        when :underline then border_class_for_position
+        when :pills then "gap-1"
+        when :bordered then "gap-0"
+        end
+      end
+
+      # Returns border class based on position.
+      # @return [String] the border class
+      # @api private
+      def border_class_for_position
+        case @position
+        when :bottom then "border-t border-grayscale-200"
+        when :left then "border-r border-grayscale-200"
+        when :right then "border-l border-grayscale-200"
+        else "border-b border-grayscale-200"
+        end
+      end
+
+      # Returns CSS classes for the panels container.
+      # @return [String] the merged CSS class string
+      # @api private
+      def panels_classes
+        css_classes([
+          "bui-tabs__panels",
+          "flex-1"
+        ])
+      end
+
+      # Returns order classes for tab list based on position.
+      # @return [String] the order class
+      # @api private
+      def tablist_order_class
+        case @position
+        when :bottom then "order-2"
+        when :right then "order-2"
+        else ""
+        end
+      end
+
+      # Returns order classes for panels based on position.
+      # @return [String] the order class
+      # @api private
+      def panels_order_class
+        case @position
+        when :bottom then "order-1"
+        when :right then "order-1"
+        else ""
+        end
+      end
+
+      # Returns the Stimulus controller identifier.
+      # @return [String] the controller name
+      # @api private
+      def controller_name
+        "better-ui--tabs--container"
+      end
+
+      # Returns HTML attributes for the container element.
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        @options.except(:class).merge(
+          id: container_id,
+          data: data_attributes
+        )
+      end
+
+      # Returns data attributes for Stimulus controller.
+      # @return [Hash] data attributes hash
+      # @api private
+      def data_attributes
+        attrs = {
+          controller: controller_name,
+          "#{controller_name}-mode-value": @mode,
+          "#{controller_name}-default-tab-value": @default_tab,
+          "#{controller_name}-persist-value": @persist,
+          "#{controller_name}-persist-key-value": @persist_key,
+          "#{controller_name}-frame-id-value": @frame_id,
+          "#{controller_name}-show-loading-value": @show_loading,
+          "#{controller_name}-loader-delay-value": @loader_delay
+        }.compact
+        (@options[:data] || {}).merge(attrs)
+      end
+
+      # Validates the mode parameter.
+      # @param mode [Symbol] the mode to validate
+      # @return [Symbol] the validated mode
+      # @raise [ArgumentError] if mode is invalid
+      # @api private
+      def validate_mode(mode)
+        unless MODES.include?(mode)
+          raise ArgumentError, "Invalid mode: #{mode}. Must be one of: #{MODES.join(', ')}"
+        end
+        mode
+      end
+
+      # Validates the style parameter.
+      # @param style [Symbol] the style to validate
+      # @return [Symbol] the validated style
+      # @raise [ArgumentError] if style is invalid
+      # @api private
+      def validate_style(style)
+        unless STYLES.include?(style)
+          raise ArgumentError, "Invalid style: #{style}. Must be one of: #{STYLES.join(', ')}"
+        end
+        style
+      end
+
+      # Validates the variant parameter.
+      # @param variant [Symbol] the variant to validate
+      # @return [Symbol] the validated variant
+      # @raise [ArgumentError] if variant is invalid
+      # @api private
+      def validate_variant(variant)
+        unless VARIANTS.keys.include?(variant)
+          raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{VARIANTS.keys.join(', ')}"
+        end
+        variant
+      end
+
+      # Validates the size parameter.
+      # @param size [Symbol] the size to validate
+      # @return [Symbol] the validated size
+      # @raise [ArgumentError] if size is invalid
+      # @api private
+      def validate_size(size)
+        unless SIZES.include?(size)
+          raise ArgumentError, "Invalid size: #{size}. Must be one of: #{SIZES.join(', ')}"
+        end
+        size
+      end
+
+      # Validates the alignment parameter.
+      # @param alignment [Symbol] the alignment to validate
+      # @return [Symbol] the validated alignment
+      # @raise [ArgumentError] if alignment is invalid
+      # @api private
+      def validate_alignment(alignment)
+        unless ALIGNMENTS.include?(alignment)
+          raise ArgumentError, "Invalid alignment: #{alignment}. Must be one of: #{ALIGNMENTS.join(', ')}"
+        end
+        alignment
+      end
+
+      # Validates the position parameter.
+      # @param position [Symbol] the position to validate
+      # @return [Symbol] the validated position
+      # @raise [ArgumentError] if position is invalid
+      # @api private
+      def validate_position(position)
+        unless POSITIONS.include?(position)
+          raise ArgumentError, "Invalid position: #{position}. Must be one of: #{POSITIONS.join(', ')}"
+        end
+        position
+      end
+
+      # Validates turbo mode requirements.
+      # @raise [ArgumentError] if turbo mode is used without frame_id
+      # @api private
+      def validate_turbo_requirements!
+        if @mode == :turbo && @frame_id.nil?
+          raise ArgumentError, "frame_id is required when mode is :turbo"
+        end
+      end
+
+      # Returns the spinner color class for the loading indicator.
+      # Uses literal strings for Tailwind JIT compatibility.
+      # @return [String] the text color class
+      # @api private
+      def spinner_color_class
+        case @variant
+        when :primary   then "text-primary-600"
+        when :secondary then "text-secondary-600"
+        when :accent    then "text-accent-600"
+        when :success   then "text-success-600"
+        when :danger    then "text-danger-600"
+        when :warning   then "text-warning-600"
+        when :info      then "text-info-600"
+        when :light     then "text-grayscale-600"
+        when :dark      then "text-grayscale-800"
+        end
+      end
+    end
+  end
+end

data/app/components/better_ui/tabs/panel_component/panel_component.html.erb

@@ -0,0 +1,3 @@
+<div <%= tag.attributes(html_attributes) %>>
+  <%= content %>
+</div>

data/app/components/better_ui/tabs/panel_component.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Tabs
+    # A tab panel component that contains the content for a single tab.
+    #
+    # This component renders the panel content with proper ARIA attributes
+    # for accessibility. Used in JS mode where all panel content is present
+    # in the DOM.
+    #
+    # @example Basic panel
+    #   <%= render BetterUi::Tabs::PanelComponent.new(id: "profile") do %>
+    #     <p>Profile content here</p>
+    #   <% end %>
+    #
+    # @example Active panel
+    #   <%= render BetterUi::Tabs::PanelComponent.new(id: "profile", active: true) do %>
+    #     <p>This panel is initially visible</p>
+    #   <% end %>
+    class PanelComponent < ApplicationComponent
+      # Initializes a new panel component.
+      #
+      # @param id [String] unique identifier matching the corresponding tab
+      # @param active [Boolean] whether this panel is initially visible
+      # @param container_id [String] parent container ID for ARIA
+      # @param options [Hash] additional HTML attributes
+      def initialize(
+        id:,
+        active: false,
+        container_id: nil,
+        **options
+      )
+        @id = id
+        @active = active
+        @container_id = container_id
+        @options = options
+      end
+
+      # Returns the panel ID.
+      # @return [String] the id
+      attr_reader :id
+
+      # Returns whether this panel is active (visible).
+      # @return [Boolean] the active state
+      attr_reader :active
+
+      # Returns the panel element ID.
+      # @return [String] the panel element ID
+      def panel_element_id
+        "#{@container_id}-panel-#{@id}"
+      end
+
+      # Returns the corresponding tab element ID.
+      # @return [String] the tab element ID
+      def tab_element_id
+        "#{@container_id}-tab-#{@id}"
+      end
+
+      private
+
+      # Returns the complete CSS classes for the panel.
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          "bui-tabs__panel",
+          visibility_classes,
+          @options[:class]
+        ].compact)
+      end
+
+      # Returns visibility classes based on active state.
+      # @return [String] visibility classes
+      # @api private
+      def visibility_classes
+        @active ? "" : "hidden"
+      end
+
+      # Returns HTML attributes for the panel element.
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        @options.except(:class).merge(
+          id: panel_element_id,
+          class: component_classes,
+          role: "tabpanel",
+          "aria-labelledby": tab_element_id,
+          tabindex: "0",
+          data: data_attributes
+        )
+      end
+
+      # Returns data attributes for Stimulus.
+      # @return [Hash] data attributes hash
+      # @api private
+      def data_attributes
+        attrs = {
+          "better-ui--tabs--container-target": "panel",
+          "panel-id": @id
+        }
+        (@options[:data] || {}).merge(attrs)
+      end
+    end
+  end
+end

data/app/components/better_ui/tabs/tab_component/tab_component.html.erb

@@ -0,0 +1,9 @@
+<%= content_tag(element_tag, html_attributes) do %>
+  <% if icon? %>
+    <span class="bui-tabs__tab-icon"><%= icon %></span>
+  <% end %>
+  <span class="bui-tabs__tab-label"><%= label %></span>
+  <% if badge? %>
+    <span class="bui-tabs__tab-badge"><%= badge %></span>
+  <% end %>
+<% end %>

data/app/components/better_ui/tabs/tab_component.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Tabs
+    # A single tab component rendered as a button (JS mode) or link (Turbo mode).
+    #
+    # This component renders the clickable tab element with proper ARIA attributes
+    # and styling based on the parent container's configuration.
+    #
+    # @example Basic tab
+    #   <%= render BetterUi::Tabs::TabComponent.new(id: "profile", label: "Profile") %>
+    #
+    # @example Tab with icon and badge
+    #   <%= render BetterUi::Tabs::TabComponent.new(id: "messages", label: "Messages") do |tab| %>
+    #     <% tab.with_icon { icon_svg } %>
+    #     <% tab.with_badge { "3" } %>
+    #   <% end %>
+    class TabComponent < ApplicationComponent
+      # @!method with_icon
+      #   Slot for rendering an icon before the label
+      #   @yieldreturn [String] the HTML content for the icon
+      renders_one :icon
+
+      # @!method with_badge
+      #   Slot for rendering a badge after the label
+      #   @yieldreturn [String] the HTML content for the badge
+      renders_one :badge
+
+      # Initializes a new tab component.
+      #
+      # @param id [String] unique identifier for this tab
+      # @param label [String] display text for the tab
+      # @param href [String, nil] URL for Turbo mode navigation
+      # @param active [Boolean] whether this tab is initially active
+      # @param disabled [Boolean] whether this tab is disabled
+      # @param mode [Symbol] operating mode passed from container (:js, :turbo)
+      # @param style [Symbol] visual style passed from container
+      # @param variant [Symbol] color variant passed from container
+      # @param size [Symbol] size passed from container
+      # @param frame_id [String, nil] Turbo Frame ID passed from container
+      # @param container_id [String] parent container ID for ARIA
+      # @param options [Hash] additional HTML attributes
+      def initialize(
+        id:,
+        label:,
+        href: nil,
+        active: false,
+        disabled: false,
+        mode: :js,
+        style: :underline,
+        variant: :primary,
+        size: :md,
+        frame_id: nil,
+        container_id: nil,
+        **options
+      )
+        @id = id
+        @label = label
+        @href = href
+        @active = active
+        @disabled = disabled
+        @mode = mode
+        @style = style
+        @variant = variant
+        @size = size
+        @frame_id = frame_id
+        @container_id = container_id
+        @options = options
+      end
+
+      # Returns the tab ID.
+      # @return [String] the id
+      attr_reader :id
+
+      # Returns the tab label.
+      # @return [String] the label
+      attr_reader :label
+
+      # Returns whether this tab is active.
+      # @return [Boolean] the active state
+      attr_reader :active
+
+      # Returns whether this tab is disabled.
+      # @return [Boolean] the disabled state
+      attr_reader :disabled
+
+      # Returns the associated panel ID.
+      # @return [String] the panel element ID
+      def panel_id
+        "#{@container_id}-panel-#{@id}"
+      end
+
+      # Returns the tab element ID.
+      # @return [String] the tab element ID
+      def tab_element_id
+        "#{@container_id}-tab-#{@id}"
+      end
+
+      private
+
+      # Returns the complete CSS classes for the tab.
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          "bui-tabs__tab",
+          base_classes,
+          size_classes,
+          style_classes,
+          state_classes,
+          @options[:class]
+        ].compact)
+      end
+
+      # Returns base classes for all tabs.
+      # @return [String] base classes
+      # @api private
+      def base_classes
+        "inline-flex items-center gap-2 font-medium transition-colors duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2"
+      end
+
+      # Returns size-specific classes.
+      # @return [String] size classes
+      # @api private
+      def size_classes
+        case @size
+        when :xs then "px-2 py-1 text-xs"
+        when :sm then "px-3 py-1.5 text-sm"
+        when :md then "px-4 py-2 text-sm"
+        when :lg then "px-5 py-2.5 text-base"
+        when :xl then "px-6 py-3 text-lg"
+        end
+      end
+
+      # Returns style-specific classes.
+      # @return [String] style classes
+      # @api private
+      def style_classes
+        case @style
+        when :underline then underline_style_classes
+        when :pills then pills_style_classes
+        when :bordered then bordered_style_classes
+        end
+      end
+
+      # Returns underline style classes.
+      # @return [String] style classes
+      # @api private
+      def underline_style_classes
+        if @active
+          active_underline_classes
+        else
+          "border-b-2 border-transparent text-grayscale-600 hover:text-grayscale-900 hover:border-grayscale-300"
+        end
+      end
+
+      # Returns active underline classes based on variant.
+      # @return [String] style classes
+      # @api private
+      def active_underline_classes
+        base = "border-b-2"
+        case @variant
+        when :primary then "#{base} border-primary-600 text-primary-600"
+        when :secondary then "#{base} border-secondary-600 text-secondary-600"
+        when :accent then "#{base} border-accent-600 text-accent-600"
+        when :success then "#{base} border-success-600 text-success-600"
+        when :danger then "#{base} border-danger-600 text-danger-600"
+        when :warning then "#{base} border-warning-600 text-warning-600"
+        when :info then "#{base} border-info-600 text-info-600"
+        when :light then "#{base} border-grayscale-400 text-grayscale-700"
+        when :dark then "#{base} border-grayscale-900 text-grayscale-900"
+        end
+      end
+
+      # Returns pills style classes.
+      # @return [String] style classes
+      # @api private
+      def pills_style_classes
+        if @active
+          active_pills_classes
+        else
+          "rounded-lg text-grayscale-600 hover:text-grayscale-900 hover:bg-grayscale-100"
+        end
+      end
+
+      # Returns active pills classes based on variant.
+      # @return [String] style classes
+      # @api private
+      def active_pills_classes
+        base = "rounded-lg"
+        case @variant
+        when :primary then "#{base} bg-primary-600 text-white"
+        when :secondary then "#{base} bg-secondary-600 text-white"
+        when :accent then "#{base} bg-accent-600 text-white"
+        when :success then "#{base} bg-success-600 text-white"
+        when :danger then "#{base} bg-danger-600 text-white"
+        when :warning then "#{base} bg-warning-500 text-white"
+        when :info then "#{base} bg-info-600 text-white"
+        when :light then "#{base} bg-grayscale-200 text-grayscale-800"
+        when :dark then "#{base} bg-grayscale-800 text-white"
+        end
+      end
+
+      # Returns bordered style classes.
+      # @return [String] style classes
+      # @api private
+      def bordered_style_classes
+        if @active
+          active_bordered_classes
+        else
+          "border border-transparent text-grayscale-600 hover:text-grayscale-900 rounded-t-lg -mb-px"
+        end
+      end
+
+      # Returns active bordered classes based on variant.
+      # @return [String] style classes
+      # @api private
+      def active_bordered_classes
+        base = "border border-grayscale-200 rounded-t-lg -mb-px bg-white"
+        border_bottom = "border-b-white"
+        case @variant
+        when :primary then "#{base} #{border_bottom} text-primary-600"
+        when :secondary then "#{base} #{border_bottom} text-secondary-600"
+        when :accent then "#{base} #{border_bottom} text-accent-600"
+        when :success then "#{base} #{border_bottom} text-success-600"
+        when :danger then "#{base} #{border_bottom} text-danger-600"
+        when :warning then "#{base} #{border_bottom} text-warning-600"
+        when :info then "#{base} #{border_bottom} text-info-600"
+        when :light then "#{base} #{border_bottom} text-grayscale-700"
+        when :dark then "#{base} #{border_bottom} text-grayscale-900"
+        end
+      end
+
+      # Returns state classes for disabled or focus.
+      # @return [String] state classes
+      # @api private
+      def state_classes
+        if @disabled
+          "opacity-50 cursor-not-allowed"
+        else
+          "cursor-pointer"
+        end
+      end
+
+      # Returns the element tag (button for JS mode, anchor for Turbo mode).
+      # @return [Symbol] the tag name
+      # @api private
+      def element_tag
+        @mode == :turbo ? :a : :button
+      end
+
+      # Returns HTML attributes for the tab element.
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        attrs = @options.except(:class).merge(
+          id: tab_element_id,
+          class: component_classes,
+          role: "tab",
+          "aria-selected": @active.to_s,
+          "aria-controls": panel_id,
+          tabindex: @active ? "0" : "-1",
+          data: data_attributes
+        )
+
+        if @mode == :turbo
+          attrs[:href] = @href
+          attrs["data-turbo-frame"] = @frame_id if @frame_id
+        else
+          attrs[:type] = "button"
+        end
+
+        attrs[:disabled] = true if @disabled && @mode == :js
+        attrs["aria-disabled"] = "true" if @disabled
+
+        attrs
+      end
+
+      # Returns data attributes for Stimulus.
+      # @return [Hash] data attributes hash
+      # @api private
+      def data_attributes
+        attrs = {
+          "better-ui--tabs--container-target": "tab",
+          "tab-id": @id,
+          "active-classes": active_style_classes_for_data,
+          "inactive-classes": inactive_style_classes_for_data,
+          action: "click->better-ui--tabs--container#selectTab keydown->better-ui--tabs--container#handleKeydown"
+        }
+        (@options[:data] || {}).merge(attrs)
+      end
+
+      # Returns active style classes for storing in data attribute.
+      # @return [String] active classes
+      # @api private
+      def active_style_classes_for_data
+        case @style
+        when :underline then active_underline_classes
+        when :pills then active_pills_classes
+        when :bordered then active_bordered_classes
+        end
+      end
+
+      # Returns inactive style classes for storing in data attribute.
+      # @return [String] inactive classes
+      # @api private
+      def inactive_style_classes_for_data
+        case @style
+        when :underline then "border-b-2 border-transparent text-grayscale-600 hover:text-grayscale-900 hover:border-grayscale-300"
+        when :pills then "rounded-lg text-grayscale-600 hover:text-grayscale-900 hover:bg-grayscale-100"
+        when :bordered then "border border-transparent text-grayscale-600 hover:text-grayscale-900 rounded-t-lg -mb-px"
+        end
+      end
+    end
+  end
+end

data/app/helpers/better_ui/application_helper.rb

@@ -325,5 +325,79 @@ module BetterUi
     def bui_drawer_nav_group(**options, &block)
       render BetterUi::Drawer::NavGroupComponent.new(**options), &block
     end
+
+    # ============================================
+    # Tabs Components
+    # ============================================
+
+    # Renders a tabs container component.
+    #
+    # @param options [Hash] Options passed to Tabs::ContainerComponent
+    # @option options [Symbol] :mode Operating mode (:js, :turbo)
+    # @option options [Symbol] :style Visual style (:underline, :pills, :bordered)
+    # @option options [Symbol] :variant Color variant (:primary, :secondary, etc.)
+    # @option options [Symbol] :size Size (:xs, :sm, :md, :lg, :xl)
+    # @option options [Symbol] :alignment Tab alignment (:start, :center, :end, :stretch)
+    # @option options [Symbol] :position Tab list position (:top, :bottom, :left, :right)
+    # @option options [String, nil] :frame_id Turbo Frame ID (required for turbo mode)
+    # @option options [String, nil] :default_tab ID of the default active tab
+    # @option options [Boolean] :persist Persist active tab state
+    # @option options [String, nil] :persist_key localStorage key for persistence
+    # @yield [tabs] Block with tabs slots
+    # @yieldparam tabs [BetterUi::Tabs::ContainerComponent] The tabs container
+    # @return [String] Rendered HTML
+    #
+    # @example JS mode tabs
+    #   <%= bui_tabs(mode: :js, style: :underline) do |tabs| %>
+    #     <% tabs.with_tab(id: "profile", label: "Profile", active: true) %>
+    #     <% tabs.with_tab(id: "settings", label: "Settings") %>
+    #     <% tabs.with_panel(id: "profile", active: true) { "Profile content" } %>
+    #     <% tabs.with_panel(id: "settings") { "Settings content" } %>
+    #   <% end %>
+    #
+    # @example Turbo mode tabs
+    #   <%= bui_tabs(mode: :turbo, frame_id: "tab-content") do |tabs| %>
+    #     <% tabs.with_tab(id: "profile", label: "Profile", href: profile_path, active: true) %>
+    #     <% tabs.with_tab(id: "settings", label: "Settings", href: settings_path) %>
+    #   <% end %>
+    def bui_tabs(**options, &block)
+      render BetterUi::Tabs::ContainerComponent.new(**options), &block
+    end
+
+    # Renders a standalone tab component (used outside container context).
+    #
+    # @param id [String] Unique identifier for this tab
+    # @param label [String] Display text for the tab
+    # @param options [Hash] Options passed to Tabs::TabComponent
+    # @option options [String, nil] :href URL for Turbo mode navigation
+    # @option options [Boolean] :active Whether this tab is initially active
+    # @option options [Boolean] :disabled Whether this tab is disabled
+    # @yield [tab] Block with tab slots
+    # @return [String] Rendered HTML
+    #
+    # @example Tab with icon
+    #   <%= bui_tab(id: "messages", label: "Messages") do |tab| %>
+    #     <% tab.with_icon { icon_svg } %>
+    #     <% tab.with_badge { "3" } %>
+    #   <% end %>
+    def bui_tab(id:, label:, **options, &block)
+      render BetterUi::Tabs::TabComponent.new(id: id, label: label, **options), &block
+    end
+
+    # Renders a standalone tab panel component (used outside container context).
+    #
+    # @param id [String] Unique identifier matching the corresponding tab
+    # @param options [Hash] Options passed to Tabs::PanelComponent
+    # @option options [Boolean] :active Whether this panel is initially visible
+    # @yield Panel content
+    # @return [String] Rendered HTML
+    #
+    # @example Basic panel
+    #   <%= bui_tab_panel(id: "profile", active: true) do %>
+    #     <p>Profile content here</p>
+    #   <% end %>
+    def bui_tab_panel(id:, **options, &block)
+      render BetterUi::Tabs::PanelComponent.new(id: id, **options), &block
+    end
   end
 end

data/lib/better_ui/engine.rb

@@ -40,5 +40,12 @@ module BetterUi
         Lookbook.config.preview_srcdoc = true
       end
     end
+
+    # Auto-include view helpers in host application
+    initializer "better_ui.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include BetterUi::ApplicationHelper
+      end
+    end
   end
 end

data/lib/better_ui/version.rb

@@ -1,3 +1,3 @@
 module BetterUi
-  VERSION = "0.7.2"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_ui
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Umberto Peserico
@@ -114,6 +114,12 @@ files:
 - app/components/better_ui/forms/text_input_component/text_input_component.html.erb
 - app/components/better_ui/forms/textarea_component.rb
 - app/components/better_ui/forms/textarea_component/textarea_component.html.erb
+- app/components/better_ui/tabs/container_component.rb
+- app/components/better_ui/tabs/container_component/container_component.html.erb
+- app/components/better_ui/tabs/panel_component.rb
+- app/components/better_ui/tabs/panel_component/panel_component.html.erb
+- app/components/better_ui/tabs/tab_component.rb
+- app/components/better_ui/tabs/tab_component/tab_component.html.erb
 - app/controllers/better_ui/application_controller.rb
 - app/form_builders/better_ui/ui_form_builder.rb
 - app/helpers/better_ui/application_helper.rb