better_ui 0.3.0 → 0.7.0

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Drawer
+    # A navigation group component for sidebar menus with a title and collection of items.
+    #
+    # @example Basic usage
+    #   <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Main") do |group| %>
+    #     <% group.with_item(label: "Dashboard", href: "/dashboard", active: true) do |item| %>
+    #       <% item.with_icon do %><svg>...</svg><% end %>
+    #     <% end %>
+    #     <% group.with_item(label: "Settings", href: "/settings") do |item| %>
+    #       <% item.with_icon do %><svg>...</svg><% end %>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example Without title
+    #   <%= render BetterUi::Drawer::NavGroupComponent.new do |group| %>
+    #     <% group.with_item(label: "Home", href: "/") %>
+    #   <% end %>
+    #
+    # @example With variant for dark sidebar
+    #   <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Menu", variant: :dark) do |group| %>
+    #     <% group.with_item(label: "Dashboard", href: "/") %>
+    #   <% end %>
+    class NavGroupComponent < ApplicationComponent
+      # Visual variant configurations for title
+      VARIANTS = {
+        light: {
+          title: "text-grayscale-500"
+        },
+        dark: {
+          title: "text-grayscale-400"
+        },
+        primary: {
+          title: "text-primary-200"
+        }
+      }.freeze
+
+      # @!method with_item
+      #   Slot for rendering navigation items.
+      #   All parameters are passed to NavItemComponent.
+      #   @param label [String] the item label text
+      #   @param href [String] the link URL
+      #   @param active [Boolean] whether the item is currently active
+      #   @param method [Symbol, nil] HTTP method for non-GET requests
+      #   @yieldparam [NavItemComponent] item the nav item component instance
+      renders_many :items, ->(label:, href:, active: false, method: nil, container_classes: nil, **options, &block) {
+        NavItemComponent.new(
+          label: label,
+          href: href,
+          active: active,
+          method: method,
+          variant: @variant,
+          container_classes: container_classes,
+          **options,
+          &block
+        )
+      }
+
+      # Initializes a new nav group component.
+      #
+      # @param title [String, nil] the group title (optional)
+      # @param variant [Symbol] color variant (:light, :dark, :primary), default: :light
+      # @param container_classes [String, nil] additional CSS classes
+      # @param options [Hash] additional HTML attributes
+      #
+      # @raise [ArgumentError] if variant is not one of the allowed values
+      def initialize(
+        title: nil,
+        variant: :light,
+        container_classes: nil,
+        **options
+      )
+        @title = title
+        @variant = validate_variant(variant)
+        @container_classes = container_classes
+        @options = options
+      end
+
+      # Returns the title text.
+      #
+      # @return [String, nil] the title
+      attr_reader :title
+
+      private
+
+      # Returns CSS classes for the group container.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          @container_classes
+        ].compact)
+      end
+
+      # Returns CSS classes for the title.
+      #
+      # @return [String] CSS classes for the title
+      # @api private
+      def title_classes
+        config = VARIANTS[@variant]
+        css_classes([
+          "px-4",
+          "text-xs",
+          "font-semibold",
+          "uppercase",
+          "tracking-wider",
+          config[:title]
+        ])
+      end
+
+      # Returns CSS classes for the items container.
+      #
+      # @return [String] CSS classes for items wrapper
+      # @api private
+      def items_wrapper_classes
+        css_classes([
+          @title ? "mt-2" : nil,
+          "space-y-1"
+        ].compact)
+      end
+
+      # Returns HTML attributes for the group element.
+      #
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        @options
+      end
+
+      # Whether to render the title.
+      #
+      # @return [Boolean] true if title should be rendered
+      # @api private
+      def render_title?
+        @title.present?
+      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.key?(variant)
+          raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{VARIANTS.keys.join(', ')}"
+        end
+        variant
+      end
+    end
+  end
+end

data/app/components/better_ui/drawer/nav_item_component/nav_item_component.html.erb

@@ -0,0 +1,13 @@
+<a <%= tag.attributes(html_attributes) %>>
+  <% if icon? %>
+    <span class="<%= icon_classes %>">
+      <%= icon %>
+    </span>
+  <% end %>
+  <span><%= label %></span>
+  <% if badge? %>
+    <span class="<%= badge_classes %>">
+      <%= badge %>
+    </span>
+  <% end %>
+</a>

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

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Drawer
+    # A navigation item component for sidebar menus with icon, label, and badge support.
+    #
+    # @example Basic usage
+    #   <%= render BetterUi::Drawer::NavItemComponent.new(label: "Dashboard", href: "/dashboard") %>
+    #
+    # @example With icon and active state
+    #   <%= render BetterUi::Drawer::NavItemComponent.new(
+    #     label: "Dashboard",
+    #     href: "/dashboard",
+    #     active: true
+    #   ) do |item| %>
+    #     <% item.with_icon do %>
+    #       <svg>...</svg>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example With badge
+    #   <%= render BetterUi::Drawer::NavItemComponent.new(label: "Messages", href: "/messages") do |item| %>
+    #     <% item.with_icon do %><svg>...</svg><% end %>
+    #     <% item.with_badge do %>5<% end %>
+    #   <% end %>
+    #
+    # @example With HTTP method for logout
+    #   <%= render BetterUi::Drawer::NavItemComponent.new(
+    #     label: "Logout",
+    #     href: "/logout",
+    #     method: :delete
+    #   ) %>
+    class NavItemComponent < ApplicationComponent
+      # Visual variant configurations
+      VARIANTS = {
+        light: {
+          base: "text-grayscale-700",
+          active: "bg-primary-50 text-primary-700",
+          inactive: "hover:bg-grayscale-100",
+          badge_bg: "bg-primary-100",
+          badge_text: "text-primary-700"
+        },
+        dark: {
+          base: "text-grayscale-300",
+          active: "bg-white/10 text-white",
+          inactive: "hover:bg-white/5",
+          badge_bg: "bg-white/20",
+          badge_text: "text-white"
+        },
+        primary: {
+          base: "text-primary-100",
+          active: "bg-white/20 text-white",
+          inactive: "hover:bg-white/10",
+          badge_bg: "bg-white/20",
+          badge_text: "text-white"
+        }
+      }.freeze
+
+      # Allowed HTTP methods
+      METHODS = %i[get post put patch delete].freeze
+
+      # @!method with_icon
+      #   Slot for rendering the icon (displayed before label).
+      #   @yieldreturn [String] the SVG or icon HTML content
+      renders_one :icon
+
+      # @!method with_badge
+      #   Slot for rendering a badge/counter (displayed after label).
+      #   @yieldreturn [String] the badge content (usually a number)
+      renders_one :badge
+
+      # Initializes a new nav item component.
+      #
+      # @param label [String] the link text (required)
+      # @param href [String] the link URL (required)
+      # @param active [Boolean] whether the item is currently active (default: false)
+      # @param method [Symbol, nil] HTTP method for non-GET requests (:post, :put, :patch, :delete)
+      # @param variant [Symbol] color variant (:light, :dark, :primary), default: :light
+      # @param container_classes [String, nil] additional CSS classes
+      # @param options [Hash] additional HTML attributes passed to the link element
+      #
+      # @raise [ArgumentError] if variant is not one of the allowed values
+      # @raise [ArgumentError] if method is provided and not one of the allowed values
+      def initialize(
+        label:,
+        href:,
+        active: false,
+        method: nil,
+        variant: :light,
+        container_classes: nil,
+        **options
+      )
+        @label = label
+        @href = href
+        @active = active
+        @method = validate_method(method)
+        @variant = validate_variant(variant)
+        @container_classes = container_classes
+        @options = options
+      end
+
+      # Returns the label text.
+      #
+      # @return [String] the label
+      attr_reader :label
+
+      # Returns the href URL.
+      #
+      # @return [String] the URL
+      attr_reader :href
+
+      # Returns whether the item is active.
+      #
+      # @return [Boolean] true if active
+      def active?
+        @active
+      end
+
+      private
+
+      # Returns the complete CSS classes for the nav item link.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        config = VARIANTS[@variant]
+        css_classes([
+          "flex",
+          "items-center",
+          "px-4",
+          "py-2",
+          "rounded-md",
+          "transition-colors",
+          config[:base],
+          active? ? config[:active] : config[:inactive],
+          @container_classes
+        ].compact)
+      end
+
+      # Returns CSS classes for the icon wrapper.
+      #
+      # @return [String] CSS classes for icon
+      # @api private
+      def icon_classes
+        css_classes([
+          "w-5",
+          "h-5",
+          "mr-3",
+          "shrink-0"
+        ])
+      end
+
+      # Returns CSS classes for the badge.
+      #
+      # @return [String] CSS classes for badge
+      # @api private
+      def badge_classes
+        config = VARIANTS[@variant]
+        css_classes([
+          "ml-auto",
+          "text-xs",
+          "font-medium",
+          "px-2",
+          "py-0.5",
+          "rounded-full",
+          config[:badge_bg],
+          config[:badge_text]
+        ])
+      end
+
+      # Returns HTML attributes for the link element.
+      #
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        attrs = @options.dup
+        attrs[:href] = @href
+        attrs[:class] = component_classes
+
+        if @method && @method != :get
+          attrs[:data] ||= {}
+          attrs[:data][:turbo_method] = @method
+        end
+
+        attrs
+      end
+
+      # Whether a non-GET method is specified.
+      #
+      # @return [Boolean] true if using non-GET method
+      # @api private
+      def use_turbo_method?
+        @method && @method != :get
+      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.key?(variant)
+          raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{VARIANTS.keys.join(', ')}"
+        end
+        variant
+      end
+
+      # Validates the method parameter.
+      #
+      # @param method [Symbol, nil] the method to validate
+      # @return [Symbol, nil] the validated method
+      # @raise [ArgumentError] if method is invalid
+      # @api private
+      def validate_method(method)
+        return nil if method.nil?
+
+        unless METHODS.include?(method)
+          raise ArgumentError, "Invalid method: #{method}. Must be one of: #{METHODS.join(', ')}"
+        end
+        method
+      end
+    end
+  end
+end

data/app/components/better_ui/drawer/sidebar_component/sidebar_component.html.erb

@@ -0,0 +1,17 @@
+<aside class="<%= component_classes %>" <%= tag.attributes(html_attributes) %>>
+  <% if header? %>
+    <div class="<%= header_wrapper_classes %>">
+      <%= header %>
+    </div>
+  <% end %>
+
+  <div class="<%= navigation_wrapper_classes %>">
+    <%= navigation? ? navigation : content %>
+  </div>
+
+  <% if footer? %>
+    <div class="<%= footer_wrapper_classes %>">
+      <%= footer %>
+    </div>
+  <% end %>
+</aside>

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

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Drawer
+    # A flexible sidebar component for drawer layouts with support for header, navigation, and footer.
+    #
+    # This component provides a responsive sidebar that can slide in from left or right on mobile,
+    # with configurable width and visual variants. It supports slots for header (logo/brand),
+    # main navigation, and footer sections.
+    #
+    # @example Basic sidebar
+    #   <%= render BetterUi::Drawer::SidebarComponent.new do |sidebar| %>
+    #     <% sidebar.with_navigation do %>
+    #       <nav>Navigation links</nav>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example Sidebar with all sections
+    #   <%= render BetterUi::Drawer::SidebarComponent.new(position: :left, width: :md) do |sidebar| %>
+    #     <% sidebar.with_header { image_tag("logo.svg") } %>
+    #     <% sidebar.with_navigation do %>
+    #       <nav>Main navigation</nav>
+    #     <% end %>
+    #     <% sidebar.with_footer { "User info" } %>
+    #   <% end %>
+    class SidebarComponent < ApplicationComponent
+      # Width configurations
+      WIDTHS = {
+        sm: "w-16",    # 64px - icon-only sidebar
+        md: "w-64",    # 256px - standard sidebar
+        lg: "w-80"     # 320px - wide sidebar
+      }.freeze
+
+      # Position configurations
+      POSITIONS = %i[left right].freeze
+
+      # Visual variant configurations
+      SIDEBAR_VARIANTS = {
+        light: {
+          bg: "bg-white",
+          border: "border-grayscale-200",
+          text: "text-grayscale-900"
+        },
+        dark: {
+          bg: "bg-grayscale-900",
+          border: "border-grayscale-700",
+          text: "text-white"
+        },
+        primary: {
+          bg: "bg-primary-800",
+          border: "border-primary-900",
+          text: "text-white"
+        }
+      }.freeze
+
+      # @!method with_header
+      #   Slot for rendering the sidebar header section (logo, brand).
+      #   @yieldreturn [String] the HTML content for the header
+      renders_one :header
+
+      # @!method with_navigation
+      #   Slot for rendering the main navigation content.
+      #   @yieldreturn [String] the HTML content for navigation
+      renders_one :navigation
+
+      # @!method with_footer
+      #   Slot for rendering the sidebar footer section (user info, settings).
+      #   @yieldreturn [String] the HTML content for the footer
+      renders_one :footer
+
+      # Initializes a new sidebar component.
+      #
+      # @param variant [Symbol] the visual variant (:light, :dark, :primary), defaults to :light
+      # @param position [Symbol] the sidebar position (:left, :right), defaults to :left
+      # @param width [Symbol] the width variant (:sm, :md, :lg), defaults to :md
+      # @param collapsible [Boolean] whether sidebar can be collapsed (icon-only mode), defaults to true
+      # @param container_classes [String, nil] additional CSS classes for the container
+      # @param header_classes [String, nil] additional CSS classes for the header section
+      # @param navigation_classes [String, nil] additional CSS classes for the navigation section
+      # @param footer_classes [String, nil] additional CSS classes for the footer section
+      # @param options [Hash] additional HTML attributes passed to the sidebar element
+      #
+      # @raise [ArgumentError] if variant is not one of the allowed values
+      # @raise [ArgumentError] if position is not one of the allowed values
+      # @raise [ArgumentError] if width is not one of the allowed values
+      def initialize(
+        variant: :light,
+        position: :left,
+        width: :md,
+        collapsible: true,
+        container_classes: nil,
+        header_classes: nil,
+        navigation_classes: nil,
+        footer_classes: nil,
+        **options
+      )
+        @variant = validate_variant(variant)
+        @position = validate_position(position)
+        @width = validate_width(width)
+        @collapsible = collapsible
+        @container_classes = container_classes
+        @header_classes = header_classes
+        @navigation_classes = navigation_classes
+        @footer_classes = footer_classes
+        @options = options
+      end
+
+      # Returns the sidebar position.
+      #
+      # @return [Symbol] the position (:left or :right)
+      attr_reader :position
+
+      private
+
+      # Returns the complete CSS classes for the sidebar container.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          "flex",
+          "flex-col",
+          "h-full",
+          width_class,
+          variant_classes,
+          border_classes,
+          "shrink-0",
+          @container_classes
+        ].flatten.compact)
+      end
+
+      # Returns CSS class for the width.
+      #
+      # @return [String] the width class
+      # @api private
+      def width_class
+        WIDTHS[@width]
+      end
+
+      # Returns CSS classes for the variant.
+      #
+      # @return [Array<String>] array of CSS classes for the variant
+      # @api private
+      def variant_classes
+        config = SIDEBAR_VARIANTS[@variant]
+        [ config[:bg], config[:text] ]
+      end
+
+      # Returns CSS classes for the border based on position.
+      #
+      # @return [String] the border class
+      # @api private
+      def border_classes
+        border_color = SIDEBAR_VARIANTS[@variant][:border]
+        case @position
+        when :left
+          "border-r #{border_color}"
+        when :right
+          "border-l #{border_color}"
+        end
+      end
+
+      # Returns CSS classes for the header section.
+      #
+      # @return [String] CSS classes for header wrapper
+      # @api private
+      def header_wrapper_classes
+        css_classes([
+          "shrink-0",
+          "p-4",
+          "border-b",
+          SIDEBAR_VARIANTS[@variant][:border],
+          @header_classes
+        ].compact)
+      end
+
+      # Returns CSS classes for the navigation section.
+      #
+      # @return [String] CSS classes for navigation wrapper
+      # @api private
+      def navigation_wrapper_classes
+        css_classes([
+          "flex-1",
+          "overflow-y-auto",
+          "p-4",
+          @navigation_classes
+        ].compact)
+      end
+
+      # Returns CSS classes for the footer section.
+      #
+      # @return [String] CSS classes for footer wrapper
+      # @api private
+      def footer_wrapper_classes
+        css_classes([
+          "shrink-0",
+          "p-4",
+          "border-t",
+          SIDEBAR_VARIANTS[@variant][:border],
+          @footer_classes
+        ].compact)
+      end
+
+      # Returns HTML attributes for the sidebar element.
+      #
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        @options.merge(data: data_attributes)
+      end
+
+      # Returns data attributes for the sidebar.
+      #
+      # @return [Hash] data attributes hash
+      # @api private
+      def data_attributes
+        attrs = {}
+        attrs[:position] = @position
+        attrs[:collapsible] = @collapsible
+        (@options[:data] || {}).merge(attrs)
+      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 SIDEBAR_VARIANTS.key?(variant)
+          raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{SIDEBAR_VARIANTS.keys.join(', ')}"
+        end
+        variant
+      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 the width parameter.
+      #
+      # @param width [Symbol] the width to validate
+      # @return [Symbol] the validated width
+      # @raise [ArgumentError] if width is invalid
+      # @api private
+      def validate_width(width)
+        unless WIDTHS.key?(width)
+          raise ArgumentError, "Invalid width: #{width}. Must be one of: #{WIDTHS.keys.join(', ')}"
+        end
+        width
+      end
+    end
+  end
+end