loco_motion-rails 0.0.7 → 0.4.0

data/app/components/daisy/layout/divider_component.rb

@@ -1,29 +1,69 @@
 #
-# The divider component is a simple horizontal or vertical line that separates
-# content. It can be colored and have a label.
+# The DividerComponent creates a visual separator between content sections,
+# either horizontally or vertically. It can include optional text or content
+# in the center and supports various colors to match your theme.
 #
-# @loco_example Basic Usage
+# Common use cases include:
+# - Separating sections of a page.
+# - Creating visual breaks between cards or content blocks.
+# - Providing alternative options with "OR" text.
+# - Organizing form sections.
+#
+# @loco_example Basic Dividers
 #   = daisy_divider
 #
-# @loco_example With Text
 #   = daisy_divider do
-#     Hello Dividers!
+#     OR
+#
+# @loco_example Vertical Dividers
+#   .flex.grow
+#     = daisy_card(css: "h-48") do
+#       Left Content
+#
+#     = daisy_divider(css: "divider-horizontal") do
+#       OR
+#
+#     = daisy_card(css: "h-48") do
+#       Right Content
+#
+# @loco_example Colored Dividers
+#   = daisy_divider(css: "divider-primary") do
+#     Primary
+#
+#   = daisy_divider(css: "divider-accent") do
+#     Accent
 #
-# @loco_example Horizontal Accented With Text
-#   = daisy_divider(css: "divider-horizontal divider-accent") do
-#     Accent Divider
+#   = daisy_divider(css: "divider-success") do
+#     Success
 #
 class Daisy::Layout::DividerComponent < LocoMotion::BaseComponent
 
   #
-  # Add the `divider` CSS class to the component.
+  # Creates a new Divider component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the divider.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Orientation: `divider-horizontal` for vertical divider
+  #   - Colors: `divider-neutral`, `divider-primary`, `divider-secondary`,
+  #     `divider-accent`, `divider-info`, `divider-success`,
+  #     `divider-warning`, `divider-error`
+  #
+  def initialize(*args, **kws, &block)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes.
   #
   def before_render
     add_css(:component, "divider")
   end
 
   #
-  # Render the component and it's content.
+  # Renders the component and its content.
   #
   def call
     part(:component) { content }

data/app/components/daisy/layout/drawer_component.rb

@@ -1,23 +1,60 @@
 #
-# The DrawerComponent shows a sidebar that can be toggled open and closed.
+# The DrawerComponent provides a sliding sidebar panel that can be toggled
+# open and closed. It's commonly used for:
+# - Navigation menus
+# - Filter panels
+# - Additional information panels
+# - Mobile-friendly navigation
 #
-# @part input [LocoMotion::BaseComponent] The input checkbox that toggles the
-#   sidebar.
-# @part content_wrapper [LocoMotion::BaseComponent] The wrapper for the page
-#   content.
-# @part overlay [LocoMotion::BaseComponent] The overlay that covers the page
-#   when the sidebar is open.
+# The drawer includes an overlay that covers the main content when open and
+# can be configured to slide in from either the left or right side.
 #
-# @slot sidebar [Daisy::Layout::DrawerSidebarComponent] The sidebar that is
-#   shown when the drawer is toggled open. Renders the overlay inside of itself.
+# @part input            [LocoMotion::BaseComponent] The input checkbox that
+#   toggles the sidebar visibility.
 #
-# @loco_example Basic Usage
+# @part content_wrapper  [LocoMotion::BaseComponent] The wrapper for the main
+#   page content that remains visible when the drawer is closed.
+#
+# @part overlay         [LocoMotion::BaseComponent] The semi-transparent
+#   overlay that covers the main content when the drawer is open. Clicking it
+#   closes the drawer.
+#
+# @slot sidebar        [Daisy::Layout::DrawerSidebarComponent] The sidebar
+#   panel that slides in when the drawer is opened. Contains the overlay
+#   within itself.
+#
+# @loco_example Basic Left Drawer
 #   = daisy_drawer do |drawer|
 #     - drawer.with_sidebar do
 #       .bg-base-100.p-4.w-40
-#         Hello sidebar!
+#         Menu Items
+#
+#     = daisy_button(tag_name: "label",
+#       css: "btn btn-primary",
+#       title: "Open Menu",
+#       html: { for: drawer.id })
+#
+# @loco_example Right Drawer
+#   = daisy_drawer(css: "drawer-end") do |drawer|
+#     - drawer.with_sidebar do
+#       .bg-base-100.p-4.w-40
+#         Filter Options
+#
+#     = daisy_button(tag_name: "label",
+#       css: "btn btn-secondary",
+#       title: "Show Filters",
+#       html: { for: drawer.id })
 #
-#     = daisy_button(tag_name: "label", css: "btn btn-primary", title: "Open Drawer", html: { for: drawer.id })
+# @loco_example Styled Drawer
+#   = daisy_drawer do |drawer|
+#     - drawer.with_sidebar do
+#       .bg-base-200.p-4.w-80.h-full
+#         .flex.justify-between.items-center.mb-4
+#           %h2.text-xl Settings
+#           = daisy_button(tag_name: "label",
+#             css: "btn btn-ghost btn-circle",
+#             icon: "x-mark",
+#             html: { for: drawer.id })
 #
 class Daisy::Layout::DrawerComponent < LocoMotion::BaseComponent
   #
@@ -26,14 +63,14 @@ class Daisy::Layout::DrawerComponent < LocoMotion::BaseComponent
   #
   class Daisy::Layout::DrawerSidebarComponent < LocoMotion::BaseComponent
     #
-    # Add the `drawer-side` CSS class to the component.
+    # Sets up the component's CSS classes.
     #
     def before_render
       add_css(:component, "drawer-side")
     end
 
     #
-    # Render the sidebar, the overlay, and the content.
+    # Renders the sidebar, the overlay, and its content.
     #
     def call
       part(:component) do
@@ -55,10 +92,18 @@ class Daisy::Layout::DrawerComponent < LocoMotion::BaseComponent
   attr_reader :id
 
   #
-  # Create a new instance of the DrawerComponent.
+  # Creates a new Drawer component.
+  #
+  # @param kws [Hash] Keyword arguments for customizing the drawer.
+  #
+  # @option kws id  [String] The ID of the drawer. Defaults to a random UUID.
+  #   This is used to connect the toggle button with the drawer.
   #
-  # @param kws [Hash] The keyword arguments passed to the component.
-  # @option kws [String] :id The ID of the drawer. Defaults to a random UUID.
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Position: `drawer-end` to slide from right instead of left
+  #   - Responsive: `lg:drawer-open` to keep drawer open on large screens
+  #   - Z-index: `z-[100]` to control stacking order
   #
   def initialize(**kws)
     super

data/app/components/daisy/layout/footer_component.rb

@@ -1,27 +1,67 @@
 #
-# The footer component is a simple container for the footer of a page. It can be
-# used to hold copyright information, links to other pages, or any other
-# information that should be displayed at the bottom of a page.
+# The FooterComponent creates a responsive container for page footer content.
+# Common use cases include:
+# - Site navigation and sitemap links.
+# - Copyright and legal information.
+# - Contact details and social media links.
+# - Newsletter signup forms.
 #
-# @loco_example Basic Usage
-#   = daisy_footer(css: "bg-neutral text-neutral-content") do
+# The component is responsive by default and will stack content on smaller
+# screens.
+#
+# @loco_example Basic Navigation Footer
+#   = daisy_footer(css: "bg-neutral text-neutral-content p-10") do
+#     %nav
+#       %h6.footer-title Company
+#       = link_to "About", "/about", class: "link-hover"
+#       = link_to "Contact", "/contact", class: "link-hover"
+#       = link_to "Jobs", "/careers", class: "link-hover"
+#
+# @loco_example Multi-Column Footer
+#   = daisy_footer(css: "bg-base-200 text-base-content p-10") do
 #     %nav
-#       = link_to "Home", root_path
+#       %h6.footer-title Products
+#       = link_to "Features", "#", class: "link-hover"
+#       = link_to "Pricing", "#", class: "link-hover"
 #
-# @loco_example With Text
-#   = daisy_footer(css: "bg-neutral text-neutral-content p-10 text-center text-sm") do
-#     Copyright © 2024
+#     %nav
+#       %h6.footer-title Support
+#       = link_to "Documentation", "#", class: "link-hover"
+#       = link_to "Help Center", "#", class: "link-hover"
+#
+# @loco_example Copyright Footer
+#   = daisy_footer(css: "bg-neutral text-neutral-content p-4 text-center") do
+#     %small
+#       Copyright © 2024 Company Name.
+#       All rights reserved.
 #
 class Daisy::Layout::FooterComponent < LocoMotion::BaseComponent
   #
-  # Add the `footer` CSS class to the component.
+  # Creates a new Footer component.
+  #
+  # @param kws [Hash] Keyword arguments for customizing the footer.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Background: `bg-neutral`, `bg-base-200`
+  #   - Text color: `text-neutral-content`, `text-base-content`
+  #   - Spacing: `p-4`, `p-10`
+  #   - Layout: `text-center`, `grid grid-cols-2 gap-4`
+  #
+  def initialize(**kws)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes and HTML tag.
   #
   def before_render
     add_css(:component, "footer")
+    set_tag_name(:component, :footer)
   end
 
   #
-  # Render the component and it's content (inline).
+  # Renders the component and its content.
   #
   def call
     part(:component) { content }

data/app/components/daisy/layout/hero_component.rb

@@ -1,10 +1,45 @@
 #
-# The HeroComponent is a layout component that is used to create a hero section.
+# The HeroComponent creates an eye-catching, full-width section typically used
+# at the top of a page. Common use cases include:
+# - Landing page introductions.
+# - Feature showcases.
+# - Call-to-action sections.
+# - Image-rich banners.
 #
-# @part content_wrapper The wrapper for the content of the hero.
+# The component is responsive by default and provides flexible layout options
+# for content positioning and image integration.
 #
-# @slot overlay [LocoMotion::BasicComponent] An optional `<div>` positioned to
-#   overlay underneath the hero and allow for styling behind it.
+# @part content_wrapper [LocoMotion::BaseComponent] The wrapper for the hero
+#   content, providing flex-based layout control.
+#
+# @slot overlay [LocoMotion::BasicComponent] An optional `<div>` positioned
+#   behind the content for background effects like semi-transparency or blur.
+#
+# @loco_example Basic Hero
+#   = daisy_hero(css: "bg-base-200 text-center") do
+#     %div
+#       %h1.text-5xl.font-bold Welcome
+#       %p.my-6 Discover amazing features.
+#       = daisy_button(css: "btn btn-primary",
+#         title: "Get Started")
+#
+# @loco_example Hero with Image
+#   = daisy_hero(css: "bg-base-200",
+#     content_wrapper_css: "flex-col md:flex-row") do
+#     %img.h-40.rounded{
+#       src: image_path("hero-image.jpg"),
+#       alt: "Hero Image" }
+#     %div
+#       %h1.text-5xl.font-bold Features
+#       %p.my-6 Explore what we offer.
+#
+# @loco_example Hero with Background Overlay
+#   = daisy_hero(css: "min-h-96",
+#     html: { style: "background-image: url('bg.jpg')" }) do |hero|
+#     - hero.with_overlay(css: "bg-black/50 backdrop-blur")
+#     %div.text-white
+#       %h1.text-5xl.font-bold Discover
+#       %p.my-6 Start your journey today.
 #
 class Daisy::Layout::HeroComponent < LocoMotion::BaseComponent
   define_part :content_wrapper
@@ -12,7 +47,34 @@ class Daisy::Layout::HeroComponent < LocoMotion::BaseComponent
   renders_one :overlay, LocoMotion::BasicComponent.build(css: "hero-overlay")
 
   #
-  # Adds the necessary CSS classes to the component.
+  # Creates a new Hero component.
+  #
+  # @param kws [Hash] Keyword arguments for customizing the hero.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Height: `min-h-screen`, `min-h-[50vh]`
+  #   - Background: `bg-base-200`, `bg-primary`
+  #   - Text: `text-center`, `text-primary-content`
+  #
+  # @option kws content_wrapper_css [String] CSS classes for the content
+  #   wrapper. Common options include:
+  #   - Layout: `flex-col`, `flex-col md:flex-row`
+  #   - Spacing: `gap-4`, `space-y-4`
+  #   - Alignment: `items-center`, `justify-between`
+  #
+  # @option kws html [Hash] HTML attributes for the hero container.
+  #   Commonly used for background images:
+  #   ```ruby
+  #   html: { style: "background-image: url('image.jpg')" }
+  #   ```
+  #
+  def initialize(**kws)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes.
   #
   def before_render
     add_css(:component, "hero")

data/app/components/daisy/layout/indicator_component.rb

@@ -1,28 +1,75 @@
 #
-# The IndicatorComponent provides items positioned around it's content with the
-# intention of indicating a callout or something needing attention.
+# The IndicatorComponent positions notification elements around its content to
+# draw attention to important information. Common use cases include:
+# - Notification badges on avatars.
+# - Cart item counters.
+# - "New" badges on features.
+# - Status indicators on elements.
 #
-# @slot item The items to be rendered around the content. Allows multiple.
+# By default, indicators are positioned in the top-right corner, but they can
+# be positioned anywhere around the content using CSS classes.
 #
-# @loco_example Basic Usage
+# @slot item+ [LocoMotion::BasicComponent] The items to be rendered around
+#   the content. Multiple items can be added and positioned independently.
+#
+# @loco_example Basic Badge Indicator
 #   = daisy_indicator do |indicator|
 #     - indicator.with_item do
-#       = daisy_badge(title: "New!", css: "badge-accent")
+#       = daisy_badge(title: "8",
+#         css: "badge-secondary")
+#
+#     = daisy_avatar(src: "avatar.jpg")
+#
+# @loco_example Multiple Indicators
+#   = daisy_indicator do |indicator|
+#     - indicator.with_item(css: "indicator-top indicator-start") do
+#       = daisy_badge(title: "New",
+#         css: "badge-accent")
+#
+#     - indicator.with_item(css: "indicator-bottom indicator-end") do
+#       = daisy_badge(title: "Sale",
+#         css: "badge-secondary")
+#
+#     = daisy_button(title: "View Item")
+#
+# @loco_example Custom Positioning
+#   = daisy_indicator do |indicator|
+#     - # Center of left edge
+#     - indicator.with_item(css: "indicator-middle indicator-start") do
+#       Online
 #
-#     = daisy_button(title: "Checkout", left_icon: "shopping-cart")
+#     - # Center of right edge
+#     - indicator.with_item(css: "indicator-middle indicator-end") do
+#       Available
+#
+#     .w-40.h-40.bg-base-200
 #
 class Daisy::Layout::IndicatorComponent < LocoMotion::BaseComponent
   renders_many :items, LocoMotion::BasicComponent.build(css: "indicator-item")
 
   #
-  # Adds the `indicator` CSS to the component
+  # Creates a new Indicator component.
+  #
+  # @param kws [Hash] Keyword arguments for customizing the indicator.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Spacing: `p-2`, `m-4`
+  #   - Alignment: `inline-flex`, `inline-grid`
+  #
+  def initialize(**kws)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes.
   #
   def before_render
     add_css(:component, "indicator")
   end
 
   #
-  # Renders the component, all of the items, and any user-provided content.
+  # Renders the component, all indicator items, and the main content.
   #
   def call
     part(:component) do

data/app/components/daisy/layout/join_component.rb

@@ -1,10 +1,81 @@
+#
+# The JoinComponent combines multiple elements into a cohesive group without
+# gaps between them. Common use cases include:
+# - Button groups for toolbars.
+# - Input fields with prefix/suffix elements.
+# - Segmented navigation controls.
+# - Pagination controls.
+#
+# Note: Each joined item must include the `join-item` CSS class manually, as
+# automatic application could cause rendering issues in complex scenarios.
+#
+# @slot item+ [LocoMotion::BaseComponent] The elements to be joined together.
+#   Each item should include the `join-item` CSS class.
+#
+# @loco_example Basic Button Group
+#   = daisy_join do |join|
+#     - join.with_item do
+#       = daisy_button(title: "Previous",
+#         css: "join-item")
+#     - join.with_item do
+#       = daisy_button(title: "Current",
+#         css: "join-item btn-active")
+#     - join.with_item do
+#       = daisy_button(title: "Next",
+#         css: "join-item")
+#
+# @loco_example Icon Button Group
+#   = daisy_join do |join|
+#     - join.with_item do
+#       = daisy_button(icon: "chevron-left",
+#         css: "join-item")
+#     - join.with_item do
+#       = daisy_button(icon: "home",
+#         css: "join-item")
+#     - join.with_item do
+#       = daisy_button(icon: "chevron-right",
+#         css: "join-item")
+#
+# @loco_example Vertical Join
+#   = daisy_join(css: "join-vertical") do |join|
+#     - join.with_item do
+#       = daisy_button(title: "Menu",
+#         css: "w-full join-item")
+#     - join.with_item do
+#       = daisy_button(title: "Settings",
+#         css: "w-full join-item")
+#     - join.with_item do
+#       = daisy_button(title: "Account",
+#         css: "w-full join-item")
+#
 class Daisy::Layout::JoinComponent < LocoMotion::BaseComponent
   renders_many :items
 
+  #
+  # Creates a new Join component.
+  #
+  # @param kws [Hash] Keyword arguments for customizing the join.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Direction: `join-vertical` for vertical stacking
+  #   - Size: `min-w-32`, `w-full`
+  #   - Spacing: `gap-0`, `gap-px` (if gaps are needed)
+  #
+  def initialize(**kws)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes.
+  #
   def before_render
     add_css(:component, "join")
   end
 
+  #
+  # Renders all joined items in sequence.
+  #
   def call
     part(:component) do
       items.each do |item|

data/app/components/daisy/layout/stack_component.rb

@@ -1,8 +1,67 @@
+#
+# The StackComponent creates a 3D stacking effect by layering elements on top
+# of each other. Common use cases include:
+# - Notification cards or alerts.
+# - Photo galleries with overlap.
+# - Interactive card games.
+# - Animated content transitions.
+#
+# The component automatically positions children in a stack, with each element
+# appearing on top of the previous one. This creates depth and visual interest
+# in your layouts.
+#
+# @loco_example Basic Card Stack
+#   = daisy_stack do
+#     = daisy_card(css: "bg-base-100/80 shadow") do
+#       Top Card
+#     = daisy_card(css: "bg-base-100/80 shadow") do
+#       Middle Card
+#     = daisy_card(css: "bg-base-100/80 shadow") do
+#       Bottom Card
+#
+# @loco_example Animated Stack
+#   = daisy_stack do
+#     = daisy_card(css: "bg-primary cursor-pointer",
+#       html: { onclick: "anime({
+#         targets: this,
+#         translateY: '-100%',
+#         opacity: 0,
+#         complete: (el) => el.remove()
+#       })" }) do
+#       Click to Remove
+#
+# @loco_example Image Stack
+#   = daisy_stack(css: "w-96") do
+#     %img{ src: "image1.jpg" }
+#     %img{ src: "image2.jpg" }
+#     %img{ src: "image3.jpg" }
+#
 class Daisy::Layout::StackComponent < LocoMotion::BaseComponent
+  #
+  # Creates a new Stack component.
+  #
+  # @param kws [Hash] Keyword arguments for customizing the stack.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Size: `w-96`, `h-64`
+  #   - Spacing: `gap-2`, `space-y-4`
+  #   - Position: `relative`, `absolute`
+  #
+  def initialize(**kws)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes.
+  #
   def before_render
     add_css(:component, "stack")
   end
 
+  #
+  # Renders the component and its stacked content.
+  #
   def call
     part(:component) { content }
   end

data/app/components/daisy/mockup/browser_component.rb

@@ -0,0 +1,78 @@
+#
+# The BrowserComponent creates a realistic browser window mockup, perfect for:
+# - Showcasing web applications.
+# - Creating website previews.
+# - Demonstrating responsive designs.
+# - Building marketing materials.
+#
+# The component includes an optional toolbar for URL input and browser
+# controls, and a content area that can contain any content you wish to
+# display.
+#
+# @slot toolbar [LocoMotion::BasicComponent] An optional toolbar section,
+#   typically containing a URL input field or navigation controls.
+#
+# @loco_example Basic Browser with URL
+#   = daisy_browser(css: "w-full border border-base-300") do |browser|
+#     - browser.with_toolbar do
+#       %input.input.input-bordered{
+#         placeholder: "https://example.com" }
+#
+#     .border-t.border-base-300.p-4
+#       Your website content here
+#
+# @loco_example Styled Browser
+#   = daisy_browser(css: "bg-primary border-2") do |browser|
+#     - browser.with_toolbar do
+#       .flex.gap-2.px-4
+#         = daisy_button(icon: "chevron-left",
+#           css: "btn-circle btn-sm")
+#         = daisy_button(icon: "chevron-right",
+#           css: "btn-circle btn-sm")
+#         %input.input.input-sm.flex-1{
+#           placeholder: "Search..." }
+#
+#     .bg-base-100.p-8.text-center
+#       Professional website mockup
+#
+# @loco_example Content-Only Browser
+#   = daisy_browser(css: "border shadow-lg") do
+#     .p-4
+#       Simple browser frame without toolbar
+#
+class Daisy::Mockup::BrowserComponent < LocoMotion::BaseComponent
+
+  renders_one :toolbar, LocoMotion::BasicComponent.build(css: "mockup-browser-toolbar")
+
+  #
+  # Creates a new Browser component.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Size: `w-full`, `max-w-4xl`
+  #   - Border: `border`, `border-2`, `border-primary`
+  #   - Background: `bg-base-100`, `bg-primary`
+  #   - Shadow: `shadow`, `shadow-lg`
+  #
+  def initialize(**kws)
+    super(**kws)
+  end
+
+  #
+  # Sets up the component's CSS classes.
+  #
+  def before_render
+    add_css(:component, "mockup-browser")
+  end
+
+  #
+  # Renders the toolbar (if present) and content.
+  #
+  def call
+    part(:component) do
+      concat(toolbar) if toolbar
+      concat(content)
+    end
+  end
+
+end