better_ui 0.6.0 → 0.7.1

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

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Drawer
+    # A flexible header component for drawer layouts with support for logo, navigation, and actions.
+    #
+    # This component provides a responsive header with slots for logo, navigation, actions,
+    # and mobile menu button. It supports sticky positioning and multiple visual variants.
+    #
+    # @example Basic header
+    #   <%= render BetterUi::Drawer::HeaderComponent.new do |header| %>
+    #     <% header.with_logo { image_tag("logo.svg") } %>
+    #     <% header.with_actions { "User Menu" } %>
+    #   <% end %>
+    #
+    # @example Header with navigation
+    #   <%= render BetterUi::Drawer::HeaderComponent.new(sticky: true, variant: :light) do |header| %>
+    #     <% header.with_logo { "Brand" } %>
+    #     <% header.with_navigation do %>
+    #       <nav>Navigation links</nav>
+    #     <% end %>
+    #     <% header.with_mobile_menu_button do %>
+    #       <button>Menu</button>
+    #     <% end %>
+    #     <% header.with_actions { "Actions" } %>
+    #   <% end %>
+    class HeaderComponent < ApplicationComponent
+      # Height configurations
+      HEIGHTS = {
+        sm: "h-12",
+        md: "h-16",
+        lg: "h-20"
+      }.freeze
+
+      # Visual variant configurations
+      HEADER_VARIANTS = {
+        light: {
+          bg: "bg-white",
+          border: "border-b border-grayscale-200",
+          text: "text-grayscale-900"
+        },
+        dark: {
+          bg: "bg-grayscale-900",
+          border: "border-b border-grayscale-700",
+          text: "text-white"
+        },
+        transparent: {
+          bg: "bg-transparent",
+          border: "",
+          text: "text-grayscale-900"
+        },
+        primary: {
+          bg: "bg-primary-600",
+          border: "border-b border-primary-700",
+          text: "text-white"
+        }
+      }.freeze
+
+      # @!method with_logo
+      #   Slot for rendering the logo/brand section (left side).
+      #   @yieldreturn [String] the HTML content for the logo
+      renders_one :logo
+
+      # @!method with_navigation
+      #   Slot for rendering the main navigation (center or after logo).
+      #   Hidden on mobile by default.
+      #   @yieldreturn [String] the HTML content for navigation
+      renders_one :navigation
+
+      # @!method with_actions
+      #   Slot for rendering actions section (right side).
+      #   Typically contains user menu, notifications, etc.
+      #   @yieldreturn [String] the HTML content for actions
+      renders_one :actions
+
+      # @!method with_mobile_menu_button
+      #   Slot for rendering the mobile menu toggle button.
+      #   Only visible on mobile screens.
+      #   @yieldreturn [String] the HTML content for the mobile menu button
+      renders_one :mobile_menu_button
+
+      # Initializes a new header component.
+      #
+      # @param variant [Symbol] the visual variant (:light, :dark, :transparent, :primary), defaults to :light
+      # @param sticky [Boolean] whether the header is sticky/fixed at top, defaults to true
+      # @param height [Symbol] the height variant (:sm, :md, :lg), defaults to :md
+      # @param container_classes [String, nil] additional CSS classes for the container
+      # @param options [Hash] additional HTML attributes passed to the header element
+      #
+      # @raise [ArgumentError] if variant is not one of the allowed values
+      # @raise [ArgumentError] if height is not one of the allowed values
+      def initialize(
+        variant: :light,
+        sticky: true,
+        height: :md,
+        container_classes: nil,
+        **options
+      )
+        @variant = validate_variant(variant)
+        @sticky = sticky
+        @height = validate_height(height)
+        @container_classes = container_classes
+        @options = options
+      end
+
+      private
+
+      # Returns the complete CSS classes for the header container.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          "w-full",
+          height_class,
+          variant_classes,
+          sticky_classes,
+          "flex",
+          "items-center",
+          "justify-between",
+          "px-4",
+          "z-40",
+          @container_classes
+        ].flatten.compact)
+      end
+
+      # Returns CSS class for the height.
+      #
+      # @return [String] the height class
+      # @api private
+      def height_class
+        HEIGHTS[@height]
+      end
+
+      # Returns CSS classes for the variant.
+      #
+      # @return [Array<String>] array of CSS classes for the variant
+      # @api private
+      def variant_classes
+        config = HEADER_VARIANTS[@variant]
+        [ config[:bg], config[:border], config[:text] ]
+      end
+
+      # Returns CSS classes for sticky positioning.
+      #
+      # @return [String, nil] sticky class or nil
+      # @api private
+      def sticky_classes
+        @sticky ? "sticky top-0" : nil
+      end
+
+      # Returns CSS classes for the logo section.
+      #
+      # @return [String] CSS classes for logo wrapper
+      # @api private
+      def logo_classes
+        css_classes([
+          "flex",
+          "items-center",
+          "shrink-0"
+        ])
+      end
+
+      # Returns CSS classes for the navigation section.
+      #
+      # @return [String] CSS classes for navigation wrapper
+      # @api private
+      def navigation_classes
+        css_classes([
+          "hidden",
+          "lg:flex",
+          "flex-1",
+          "items-center",
+          "justify-center",
+          "px-4"
+        ])
+      end
+
+      # Returns CSS classes for the actions section.
+      #
+      # @return [String] CSS classes for actions wrapper
+      # @api private
+      def actions_classes
+        css_classes([
+          "flex",
+          "items-center",
+          "gap-2"
+        ])
+      end
+
+      # Returns CSS classes for the mobile menu button.
+      #
+      # @return [String] CSS classes for mobile menu button wrapper
+      # @api private
+      def mobile_menu_button_classes
+        css_classes([
+          "lg:hidden",
+          "flex",
+          "items-center"
+        ])
+      end
+
+      # Returns HTML attributes for the header element.
+      #
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        @options
+      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 HEADER_VARIANTS.key?(variant)
+          raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{HEADER_VARIANTS.keys.join(', ')}"
+        end
+        variant
+      end
+
+      # Validates the height parameter.
+      #
+      # @param height [Symbol] the height to validate
+      # @return [Symbol] the validated height
+      # @raise [ArgumentError] if height is invalid
+      # @api private
+      def validate_height(height)
+        unless HEIGHTS.key?(height)
+          raise ArgumentError, "Invalid height: #{height}. Must be one of: #{HEIGHTS.keys.join(', ')}"
+        end
+        height
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+<div class="<%= component_classes %>" <%= tag.attributes(html_attributes) %>>
+  <%# Header section (always visible) %>
+  <% if header? %>
+    <%= header %>
+  <% end %>
+
+  <%# Body wrapper (sidebar + main) %>
+  <div class="<%= body_wrapper_classes %>">
+    <%# Overlay for mobile drawer %>
+    <div class="<%= overlay_classes %>"
+         data-<%= controller_name %>-target="overlay"
+         data-action="click-><%= controller_name %>#close">
+    </div>
+
+    <%# Desktop sidebar (always visible on desktop) %>
+    <% if sidebar? %>
+      <% if sidebar_position == :left %>
+        <div class="<%= sidebar_wrapper_classes %>">
+          <%= sidebar %>
+        </div>
+      <% end %>
+    <% end %>
+
+    <%# Mobile sidebar (drawer) %>
+    <% if sidebar? %>
+      <div class="<%= mobile_sidebar_wrapper_classes %>"
+           data-<%= controller_name %>-target="sidebar">
+        <%= sidebar %>
+      </div>
+    <% end %>
+
+    <%# Main content area %>
+    <main class="<%= main_wrapper_classes %>">
+      <%= main? ? main : content %>
+    </main>
+
+    <%# Desktop sidebar on right (if positioned right) %>
+    <% if sidebar? && sidebar_position == :right %>
+      <div class="<%= sidebar_wrapper_classes %>">
+        <%= sidebar %>
+      </div>
+    <% end %>
+  </div>
+</div>

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

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Drawer
+    # A responsive layout component that composes header and sidebar with mobile drawer support.
+    #
+    # This component provides a complete page layout with a sticky header, responsive sidebar,
+    # and main content area. On mobile, the sidebar becomes a slide-out drawer that can be
+    # toggled via a menu button.
+    #
+    # @example Basic layout
+    #   <%= render BetterUi::Drawer::LayoutComponent.new do |layout| %>
+    #     <% layout.with_header(sticky: true) do |header| %>
+    #       <% header.with_logo { "Logo" } %>
+    #       <% header.with_mobile_menu_button { "☰" } %>
+    #     <% end %>
+    #     <% layout.with_sidebar do |sidebar| %>
+    #       <% sidebar.with_navigation { render "nav" } %>
+    #     <% end %>
+    #     <% layout.with_main do %>
+    #       Main content here
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example Right-positioned sidebar
+    #   <%= render BetterUi::Drawer::LayoutComponent.new(sidebar_position: :right) do |layout| %>
+    #     <% layout.with_sidebar(position: :right) do |sidebar| %>
+    #       <% sidebar.with_navigation { "Nav" } %>
+    #     <% end %>
+    #     <% layout.with_main { "Content" } %>
+    #   <% end %>
+    class LayoutComponent < ApplicationComponent
+      # Breakpoint configurations for desktop mode
+      BREAKPOINTS = {
+        md: "md:flex",
+        lg: "lg:flex",
+        xl: "xl:flex"
+      }.freeze
+
+      # Position configurations
+      POSITIONS = %i[left right].freeze
+
+      # @!method with_header
+      #   Slot for rendering the HeaderComponent.
+      #   @yieldparam [BetterUi::Drawer::HeaderComponent] header the header component instance
+      #   @yieldreturn [String] the HTML content for the header
+      renders_one :header, HeaderComponent
+
+      # @!method with_sidebar
+      #   Slot for rendering the SidebarComponent.
+      #   @yieldparam [BetterUi::Drawer::SidebarComponent] sidebar the sidebar component instance
+      #   @yieldreturn [String] the HTML content for the sidebar
+      renders_one :sidebar, SidebarComponent
+
+      # @!method with_main
+      #   Slot for rendering the main content area.
+      #   @yieldreturn [String] the HTML content for the main area
+      renders_one :main
+
+      # Initializes a new layout component.
+      #
+      # @param sidebar_position [Symbol] the sidebar position (:left, :right), defaults to :left
+      # @param sidebar_breakpoint [Symbol] the breakpoint for desktop sidebar (:md, :lg, :xl), defaults to :lg
+      # @param container_classes [String, nil] additional CSS classes for the outer container
+      # @param main_classes [String, nil] additional CSS classes for the main content area
+      # @param options [Hash] additional HTML attributes passed to the layout element
+      #
+      # @raise [ArgumentError] if sidebar_position is not one of the allowed values
+      # @raise [ArgumentError] if sidebar_breakpoint is not one of the allowed values
+      def initialize(
+        sidebar_position: :left,
+        sidebar_breakpoint: :lg,
+        container_classes: nil,
+        main_classes: nil,
+        **options
+      )
+        @sidebar_position = validate_position(sidebar_position)
+        @sidebar_breakpoint = validate_breakpoint(sidebar_breakpoint)
+        @container_classes = container_classes
+        @main_classes = main_classes
+        @options = options
+      end
+
+      # Returns the sidebar position.
+      #
+      # @return [Symbol] the position (:left or :right)
+      attr_reader :sidebar_position
+
+      # Returns the sidebar breakpoint.
+      #
+      # @return [Symbol] the breakpoint (:md, :lg, or :xl)
+      attr_reader :sidebar_breakpoint
+
+      private
+
+      # Returns the complete CSS classes for the outer layout container.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes([
+          "h-screen",
+          "overflow-hidden",
+          "flex",
+          "flex-col",
+          @container_classes
+        ].compact)
+      end
+
+      # Returns CSS classes for the body wrapper (contains sidebar + main).
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def body_wrapper_classes
+        css_classes([
+          "flex",
+          "flex-1",
+          "overflow-hidden",
+          "relative"
+        ])
+      end
+
+      # Returns CSS classes for the sidebar wrapper (desktop visibility).
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def sidebar_wrapper_classes
+        css_classes([
+          "hidden", # Hidden on mobile by default
+          "h-full", # Full height to pass to sidebar
+          BREAKPOINTS[@sidebar_breakpoint] # Show on desktop breakpoint
+        ])
+      end
+
+      # Returns CSS classes for the mobile sidebar wrapper (overlay drawer).
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def mobile_sidebar_wrapper_classes
+        css_classes([
+          "fixed",
+          "inset-y-0",
+          mobile_position_class,
+          "z-50",
+          "transform",
+          "transition-transform",
+          "duration-300",
+          "ease-in-out",
+          initial_transform_class,
+          desktop_hidden_class
+        ])
+      end
+
+      # Returns the position class for mobile sidebar.
+      #
+      # @return [String] the position class
+      # @api private
+      def mobile_position_class
+        @sidebar_position == :right ? "right-0" : "left-0"
+      end
+
+      # Returns the initial transform class for hidden state.
+      #
+      # @return [String] the transform class
+      # @api private
+      def initial_transform_class
+        @sidebar_position == :right ? "translate-x-full" : "-translate-x-full"
+      end
+
+      # Returns CSS class to hide on desktop.
+      #
+      # @return [String] the hidden class for desktop
+      # @api private
+      def desktop_hidden_class
+        case @sidebar_breakpoint
+        when :md then "md:hidden"
+        when :lg then "lg:hidden"
+        when :xl then "xl:hidden"
+        end
+      end
+
+      # Returns CSS classes for the overlay.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def overlay_classes
+        css_classes([
+          "fixed",
+          "inset-0",
+          "bg-black/50",
+          "z-40",
+          "hidden", # Initially hidden
+          "opacity-0",
+          "transition-opacity",
+          "duration-300",
+          desktop_hidden_class
+        ])
+      end
+
+      # Returns CSS classes for the main content area.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def main_wrapper_classes
+        css_classes([
+          "flex-1",
+          "overflow-auto",
+          @main_classes
+        ].compact)
+      end
+
+      # Returns the Stimulus controller identifier.
+      #
+      # @return [String] the controller name
+      # @api private
+      def controller_name
+        "better-ui--drawer--layout"
+      end
+
+      # Returns HTML attributes for the layout element.
+      #
+      # @return [Hash] HTML attributes hash
+      # @api private
+      def html_attributes
+        @options.merge(
+          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}-position-value": @sidebar_position,
+          "#{controller_name}-breakpoint-value": @sidebar_breakpoint
+        }
+        (@options[:data] || {}).merge(attrs)
+      end
+
+      # Validates the sidebar_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 sidebar_position: #{position}. Must be one of: #{POSITIONS.join(', ')}"
+        end
+        position
+      end
+
+      # Validates the sidebar_breakpoint parameter.
+      #
+      # @param breakpoint [Symbol] the breakpoint to validate
+      # @return [Symbol] the validated breakpoint
+      # @raise [ArgumentError] if breakpoint is invalid
+      # @api private
+      def validate_breakpoint(breakpoint)
+        unless BREAKPOINTS.key?(breakpoint)
+          raise ArgumentError, "Invalid sidebar_breakpoint: #{breakpoint}. Must be one of: #{BREAKPOINTS.keys.join(', ')}"
+        end
+        breakpoint
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+<div class="<%= component_classes %>" <%= tag.attributes(html_attributes) %>>
+  <% if render_title? %>
+    <h3 class="<%= title_classes %>"><%= title %></h3>
+  <% end %>
+  <div class="<%= items_wrapper_classes %>">
+    <% items.each do |item| %>
+      <%= item %>
+    <% end %>
+  </div>
+</div>