loco_motion-rails 0.0.6 → 0.0.8

data/app/components/daisy/navigation/menu_component.rb

@@ -1,25 +1,80 @@
-class Daisy::Navigation::MenuComponent < LocoMotion.configuration.base_component_class
+#
+# Creates a menu component for displaying a list of items, optionally with group titles.
+#
+# @slot items+ {Daisy::Navigation::MenuItemComponent} The menu items to display.
+#
+# @example Basic menu with items
+#   = daisy_menu do |menu|
+#     - menu.with_item do
+#       = link_to "Item 1", "#"
+#     - menu.with_item do
+#       = link_to "Item 2", "#"
+#
+# @example Menu with group titles
+#   = daisy_menu do |menu|
+#     - menu.with_item(title: "Group 1") do
+#       = link_to "Item 1-1", "#"
+#       = link_to "Item 1-2", "#"
+#     - menu.with_item("Group 2") do
+#       = link_to "Item 2-1", "#"
+#       = link_to "Item 2-2", "#"
+#
+# @example Menu with disabled items
+#   = daisy_menu do |menu|
+#     - menu.with_item do
+#       = link_to "Active Item", "#"
+#     - menu.with_item(disabled: true) do
+#       Disabled Item
+#
+class Daisy::Navigation::MenuComponent < LocoMotion::BaseComponent
 
   #
-  # The items for the MenuComponent.
+  # A menu item component that can optionally have a title and be disabled.
   #
+  # @part title The title element for the menu item.
   #
-  class Daisy::Navigation::MenuItemComponent < LocoMotion.configuration.base_component_class
+  # @example Basic menu item
+  #   = menu.with_item do
+  #     = link_to "Item", "#"
+  #
+  # @example Menu item with title
+  #   = menu.with_item(title: "Group") do
+  #     = link_to "Item", "#"
+  #
+  # @example Disabled menu item
+  #   = menu.with_item(disabled: true) do
+  #     = link_to "Item", "#"
+  #
+  class Daisy::Navigation::MenuItemComponent < LocoMotion::BaseComponent
     define_part :title
 
-    #
     # Create a new instance of the MenuItemComponent.
     #
-    # @param title [String] (Optional) Shows an additional title above the item.
-    # @param disabled [Boolean] (Optional) Sets the item in a disabled state.
+    # @param args [Array] If provided, the first argument is considered the
+    #   `title`.
+    #
+    # @param kws [Hash] The keyword arguments for the component.
     #
-    def initialize(*args, **kws, &block)
-      super
+    # @option kws title [String] Shows an additional title above the item.
+    #
+    # @option kws disabled [Boolean] Sets the item in a disabled state.
+    #
+    # @option kws css [String] Additional CSS classes for styling. Common
+    #   options include:
+    #   - Text: `text-sm`, `text-base-content`
+    #   - Spacing: `mt-4`, `mb-2`
+    #
+    def initialize(*args, **kws)
+      super(**kws)
 
-      @simple_title = config_option(:title)
+      @simple_title = config_option(:title, args[0])
       @disabled = config_option(:disabled)
     end
 
+    #
+    # Adds the relevant Daisy classes and applies the disabled state if
+    # provided (utilizes Tailwind pointer-events-none).
+    #
     def before_render
       set_tag_name(:component, :li)
       add_css(:component, "disabled pointer-events-none") if @disabled
@@ -28,6 +83,9 @@ class Daisy::Navigation::MenuComponent < LocoMotion.configuration.base_component
       add_css(:title, "menu-title")
     end
 
+    #
+    # Renders the menu item component including a title if present.
+    #
     def call
       part(:component) do
         concat(part(:title) { @simple_title }) if @simple_title
@@ -38,10 +96,24 @@ class Daisy::Navigation::MenuComponent < LocoMotion.configuration.base_component
 
   renders_many :items, Daisy::Navigation::MenuItemComponent
 
-  def initialize(*args, **kws, &block)
-    super
+  # Create a new instance of the MenuComponent.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Size: `w-56`, `max-w-xs`
+  #   - Background: `bg-base-100`, `bg-neutral`
+  #   - Border: `border`, `rounded-box`
+  #   - Shadow: `shadow`, `shadow-lg`
+  #
+  def initialize(**kws)
+    super(**kws)
   end
 
+  #
+  # Sets the tag name to `<ul>` and adds the relevant Daisy classes.
+  #
   def before_render
     set_tag_name(:component, :ul)
     add_css(:component, "menu")

data/app/components/daisy/navigation/navbar_component.html.haml

@@ -1,4 +1,4 @@
 = part(:component) do
   = start if start?
   = center if center?
-  = tail if tail?
+  = end_content if end?

data/app/components/daisy/navigation/navbar_component.rb

@@ -1,12 +1,73 @@
-class Daisy::Navigation::NavbarComponent < LocoMotion.configuration.base_component_class
+#
+# Creates a navigation bar component typically used at the top of a page to
+# organize navigation links and branding elements.
+#
+# @slot start {LocoMotion::BasicComponent} The left section of the navbar.
+#   Automatically gets the `navbar-start` CSS class.
+#
+# @slot center {LocoMotion::BasicComponent} The center section of the navbar.
+#   Automatically gets the `navbar-center` CSS class.
+#
+# @slot end {LocoMotion::BasicComponent} The right section of the navbar.
+#   Automatically gets the `navbar-end` CSS class.
+#
+# @example Basic navbar with logo and GitHub link
+#   = daisy_navbar(css: "bg-base-100") do |navbar|
+#     - navbar.with_start do
+#       = image_tag("logo.png", class: "h-8")
+#       %span.font-bold Company Name
+#
+#     - navbar.with_end do
+#       = link_to "GitHub", "https://github.com", target: "_blank"
+#
+# @example Navbar with all sections and dropdown
+#   = daisy_navbar(css: "bg-base-100") do |navbar|
+#     - navbar.with_start do
+#       %span.text-lg.italic Brand
+#
+#     - navbar.with_center do
+#       = hero_icon("code-bracket", css: "size-14")
+#
+#     - navbar.with_end do
+#       = daisy_dropdown do |dropdown|
+#         - dropdown.with_button(title: "Menu")
+#         - dropdown.with_item do
+#           = link_to "Item 1", "#"
+#
+class Daisy::Navigation::NavbarComponent < LocoMotion::BaseComponent
   renders_one :start, LocoMotion::BasicComponent.build(css: "navbar-start")
 
   renders_one :center, LocoMotion::BasicComponent.build(css: "navbar-center")
 
-  # End is a reserved word in Ruby
-  renders_one :tail, LocoMotion::BasicComponent.build(css: "navbar-end")
+  renders_one :end, LocoMotion::BasicComponent.build(css: "navbar-end")
+
+  # Create a new instance of the NavbarComponent.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Background: `bg-base-100`, `bg-neutral`
+  #   - Border: `border`, `border-base-200`, `rounded-lg`
+  #   - Shadow: `shadow`, `shadow-lg`
+  #   - Min Height: `min-h-8`, `min-h-16`
+  #
+  def initialize(**kws)
+    super(**kws)
+  end
 
   def before_render
     add_css(:component, "navbar")
   end
+
+  private
+
+  # Returns the end section content.
+  #
+  # Since `end` is a reserved word in Ruby, we need to use a different method
+  # name in the template.
+  #
+  def end_content
+    self.end
+  end
 end

data/app/components/daisy/navigation/steps_component.rb

@@ -1,7 +1,69 @@
-class Daisy::Navigation::StepsComponent < LocoMotion.configuration.base_component_class
+#
+# Creates a component for displaying a series of steps that users can follow to
+# complete a task. Useful for onboarding, form completion, and progress tracking.
+#
+# @note Steps are automatically numbered and connected with lines. You can use
+#   colors to indicate progress through the steps.
+#
+# @slot steps+ {Daisy::Navigation::StepsComponent::StepComponent} The individual
+#   steps to display.
+#
+# @example Basic steps with progress
+#   = daisy_steps do |steps|
+#     - steps.with_step(title: "Write Code", css: "step-primary")
+#     - steps.with_step(title: "Release Code", css: "step-primary")
+#     - steps.with_step(title: "Profit", css: "step-secondary")
+#     - steps.with_step(title: "Rule the World")
+#
+# @example Vertical steps
+#   = daisy_steps(css: "steps-vertical") do |steps|
+#     - steps.with_step(title: "Write Code", css: "step-primary")
+#     - steps.with_step(title: "Release Code", css: "step-primary")
+#     - steps.with_step(title: "Profit", css: "step-secondary")
+#     - steps.with_step(title: "Rule the World")
+#
+# @example Custom step content
+#   = daisy_steps do |steps|
+#     - steps.with_step(number: "AB")
+#     - steps.with_step(number: "★")
+#     - steps.with_step(number: "✓", css: "after:!text-green-500")
+#
+class Daisy::Navigation::StepsComponent < LocoMotion::BaseComponent
 
-  class Daisy::Navigation::StepComponent < LocoMotion.configuration.base_component_class
+  #
+  # A step within a StepsComponent.
+  #
+  # @example Basic step with title
+  #   = steps.with_step(title: "Step 1")
+  #
+  # @example Step with custom number
+  #   = steps.with_step(number: "★", title: "Special Step")
+  #
+  # @example Step with custom content
+  #   = steps.with_step(number: "1") do
+  #     .flex.gap-2
+  #       = hero_icon("check")
+  #       Complete
+  #
+  class Daisy::Navigation::StepComponent < LocoMotion::BaseComponent
     attr_reader :simple
+
+    # Create a new instance of the StepComponent.
+    #
+    # @param args [Array] Not used.
+    #
+    # @param kws [Hash] The keyword arguments for the component.
+    #
+    # @option kws title [String] The text to display in the step.
+    #
+    # @option kws number [String] Custom content to display in the step's
+    #   circle. Can be text, numbers, or emoji.
+    #
+    # @option kws css [String] Additional CSS classes for styling. Common
+    #   options include:
+    #   - Progress: `step-primary`, `step-secondary`, `step-accent`
+    #   - Circle Content: `after:!text-green-500`, `after:!bg-black`
+    #
     def initialize(*args, **kws, &block)
       super
 
@@ -25,6 +87,20 @@ class Daisy::Navigation::StepsComponent < LocoMotion.configuration.base_componen
 
   renders_many :steps, Daisy::Navigation::StepComponent
 
+  # Create a new instance of the StepsComponent.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Direction: `steps-vertical`
+  #   - Size: `steps-mini`, `steps-sm`, `steps-md`, `steps-lg`
+  #   - Width: `w-full`, `max-w-xs`
+  #
+  def initialize(**kws)
+    super(**kws)
+  end
+
   def before_render
     set_tag_name(:component, :ul)
     add_css(:component, "steps")

data/app/components/daisy/navigation/tabs_component.rb

@@ -1,18 +1,103 @@
-# This is the Tabs component.
-class Daisy::Navigation::TabsComponent < LocoMotion.configuration.base_component_class
-
+#
+# Creates a tabbed navigation component that can be used either as links or radio
+# buttons with associated content.
+#
+# @note When using radio button tabs, the titles must be simple strings and cannot
+#   contain HTML elements or icons.
+#
+# @slot tabs+ {Daisy::Navigation::TabsComponent::TabComponent} The individual
+#   tabs to display.
+#
+# @example Basic tabs with links
+#   = daisy_tabs(css: "tabs-bordered") do |tabs|
+#     - tabs.with_tab(title: "Home", active: true)
+#     - tabs.with_tab(title: "Click Me", html: { onclick: "alert('Clicked!')" })
+#     - tabs.with_tab(title: "Google", href: "https://google.com", target: "_blank")
+#
+# @example Radio button tabs with content
+#   = daisy_tabs(css: "tabs-lifted", radio: true) do |tabs|
+#     - tabs.with_tab(title: "Tab 1", checked: true) do
+#       %p Tab 1 content
+#     - tabs.with_tab(title: "Tab 2") do
+#       %p Tab 2 content
+#
+# @example Tabs with custom titles and content
+#   = daisy_tabs(css: "tabs-lifted") do |tabs|
+#     - tabs.with_tab do |tab|
+#       - tab.with_title do
+#         .flex.gap-2
+#           = hero_icon("home")
+#           Home
+#       - tab.with_custom_content(css: "tab-content p-4") do
+#         %p Welcome home!
+#
+class Daisy::Navigation::TabsComponent < LocoMotion::BaseComponent
+
+  #
+  # A tab within a TabsComponent that can be either a link or a radio button.
+  #
+  # @part content_wrapper The wrapper for the tab's content when not using
+  #   custom content.
+  #
+  # @slot title The title content for the tab. Only used if no `title` option
+  #   is provided.
+  #
+  # @slot custom_content Custom content to be rendered after the tab. Use this
+  #   instead of the block content for complete control over the content's HTML.
+  #
+  # @example Basic tab with title
+  #   = tabs.with_tab(title: "Home")
+  #
+  # @example Tab with custom title
+  #   = tabs.with_tab do |tab|
+  #     - tab.with_title do
+  #       .flex.gap-2
+  #         = hero_icon("home")
+  #         Home
+  #
+  # @example Tab with content
+  #   = tabs.with_tab(title: "Content") do
+  #     %p This is the tab's content
+  #
+  # @example Tab with custom content
+  #   = tabs.with_tab do |tab|
+  #     - tab.with_custom_content(css: "tab-content p-4") do
+  #       %p Custom content with custom wrapper
+  #
   class TabComponent < LocoMotion::BasicComponent
     define_parts :content_wrapper
 
     renders_one :title
     renders_one :custom_content
 
-    attr_reader :active
-
-    # @return [String] Accessor for the `title` string passed via the component
-    #   config.
-    attr_reader :simple_title
-
+    attr_reader :active, :simple_title
+
+    # Create a new instance of the TabComponent.
+    #
+    # @param args [Array] Not used.
+    #
+    # @param kws [Hash] The keyword arguments for the component.
+    #
+    # @option kws title [String] The text to display in the tab.
+    #
+    # @option kws active [Boolean] Whether this tab is active (default: false).
+    #
+    # @option kws checked [Boolean] Whether this tab is checked (default: false).
+    #
+    # @option kws disabled [Boolean] Whether this tab is disabled (default: false).
+    #
+    # @option kws href [String] The URL to visit when the tab is clicked.
+    #
+    # @option kws target [String] The target attribute for the tab (e.g., "_blank").
+    #
+    # @option kws value [String] The value attribute when using radio buttons.
+    #
+    # @option kws css [String] Additional CSS classes for styling. Common
+    #   options include:
+    #   - Size: `tab-lg`, `tab-md`, `tab-sm`, `tab-xs`
+    #   - Width: `w-full`, `!w-14`
+    #   - Cursor: `cursor-pointer`, `!cursor-auto`
+    #
     def initialize(*args, **kws, &block)
       super
 
@@ -88,6 +173,24 @@ class Daisy::Navigation::TabsComponent < LocoMotion.configuration.base_component
 
   attr_reader :name, :radio
 
+  # Create a new instance of the TabsComponent.
+  #
+  # @param args [Array] Not used.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws name [String] The name attribute for radio button tabs
+  #   (default: auto-generated UUID).
+  #
+  # @option kws radio [Boolean] Whether to use radio buttons instead of links
+  #   (default: false).
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Style: `tabs-bordered`, `tabs-lifted`
+  #   - Size: `tabs-lg`, `tabs-md`, `tabs-sm`, `tabs-xs`
+  #   - Width: `w-full`, `w-[500px]`
+  #
   def initialize(*args, **kws, &block)
     super
 

data/app/components/hero/icon_component.rb

@@ -1,4 +1,46 @@
-class Hero::IconComponent < LocoMotion.configuration.base_component_class
+#
+# Creates an icon component using Heroicons, a set of free, MIT-licensed
+# high-quality SVG icons. For a complete list of available icons, visit
+# https://heroicons.com.
+#
+# @note By default, icons are displayed with the `size-5` Tailwind class. This
+#   can be overridden without using the `!` modifier because we utilize the
+#   `:where()` pseudo-class to ensure our default classes have the lowest CSS
+#   specificity.
+#
+# @example Basic icon usage
+#   = hero_icon("academic-cap")
+#   = hero_icon(icon: "adjustments-horizontal")
+#   %span.text-blue-500
+#     = hero_icon("archive-box")
+#
+# @example Customized icons
+#   = hero_icon("no-symbol", css: "size-4 text-red-600")
+#   = hero_icon("arrow-trending-up", css: "size-10 text-green-600")
+#   = hero_icon("exclamation-triangle", css: "size-14 text-yellow-400 animate-pulse")
+#
+class Hero::IconComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
+  # Create a new instance of the IconComponent.
+  #
+  # @param args [Array] If provided, the first argument is considered the
+  #   `icon` name.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws icon [String] The name of the icon to display. See
+  #   https://heroicons.com for available icons.
+  #
+  # @option kws variant [Symbol] The variant of the icon to use
+  #   (default: :outline).
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Size: `size-4`, `size-10`, `size-14`
+  #   - Color: `text-red-600`, `text-green-600`, `text-yellow-400`
+  #   - Animation: `animate-pulse`, `animate-spin`
+  #
   def initialize(*args, **kws, &block)
     super
 
@@ -12,6 +54,13 @@ class Hero::IconComponent < LocoMotion.configuration.base_component_class
     add_css(:component, "[:where(&)]:size-5")
   end
 
+  #
+  # Renders the icon component.
+  #
+  # Because this is an inline component which might be utlized alongside text,
+  # we utilize the `call` method instead of a template to ensure that no
+  # additional whitespace gets added to the output.
+  #
   def call
     heroicon_tag(@icon, **rendered_html(:component))
   end

data/lib/daisy.rb

@@ -1,6 +1,6 @@
-require "daisy/helpers"
-require "heroicons-rails"
-
+#
+# Parent module for all Daisy components.
+#
 module Daisy
   #
   # Holds all Action-type components.
@@ -16,4 +16,19 @@ module Daisy
   # Holds all Navigation-type components.
   #
   module Navigation; end
+
+  #
+  # Holds all Feedback-type components.
+  #
+  module Feedback; end
+
+  #
+  # Holds all Layout-type components.
+  #
+  module Layout; end
+
+  #
+  # Holds all Mockup-type components.
+  #
+  module Mockup; end
 end

data/lib/hero.rb

@@ -0,0 +1,7 @@
+require "heroicons-rails"
+
+#
+# Parent module for all Hero components.
+#
+module Hero
+end

data/lib/loco_motion/basic_component.rb

@@ -3,7 +3,7 @@
 # so that users can pass in all of the same CSS and HTML options that a standard
 # component would have.
 #
-class LocoMotion::BasicComponent < LocoMotion.configuration.base_component_class
+class LocoMotion::BasicComponent < LocoMotion::BaseComponent
 
   def call
     part(:component) do

data/lib/loco_motion/concerns/tippable_component.rb

@@ -0,0 +1,26 @@
+module LocoMotion
+  module Concerns
+    #
+    # Can be included in relevant components to allow a new `tip` attibute that
+    # automatically adds the `tooltip` CSS class and the `data-tip` attribute
+    # to the component.
+    #
+    module TippableComponent
+      #
+      # Calls the parent `before_render`. Then adds the `tooltip` CSS class and
+      # the `data-tip` attribute to the component if the `tip` attribute is
+      # present.
+      #
+      def before_render
+        super
+
+        tip = config_option(:tip)
+
+        if tip
+          add_css(:component, "tooltip")
+          add_html(:component, { data: { tip: tip } })
+        end
+      end
+    end
+  end
+end

data/lib/loco_motion/configuration.rb

@@ -0,0 +1,35 @@
+module LocoMotion
+
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    #
+    # Return the current instance of the LocoMotion::Configuration or create a
+    # new one.
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    #
+    # Mostly used for internal testing; not needed in Rails
+    #
+    def require_components
+      comp_files = Dir.glob(File.dirname(__FILE__) + '/../../app/components/**/*.rb')
+
+      comp_files.each do |file|
+        require file
+      end
+    end
+  end
+
+  #
+  # Unused for now. Was previously using to setup a base class for all
+  # LocoMotion components to inherit from.
+  #
+  class Configuration
+  end
+
+end