loco_motion-rails 0.0.7 → 0.0.8

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

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

@@ -0,0 +1,144 @@
+#
+# The CodeComponent creates stylized code blocks for displaying code snippets,
+# terminal output, or any text that benefits from monospace formatting.
+# Common use cases include:
+# - Displaying code examples.
+# - Showing terminal commands and output.
+# - Highlighting important configuration settings.
+# - Creating interactive tutorials.
+#
+# The component supports line prefixes (e.g., for line numbers or command
+# prompts), syntax highlighting via CSS classes, and multi-line code blocks.
+#
+# @slot lines+ [Daisy::Mockup::CodeLineComponent] Individual lines of code,
+#   each with optional prefix and styling.
+#
+# @loco_example Basic Command with Prefix
+#   = daisy_code(prefix: "$") do
+#     yarn add @profoundry-us/loco_motion
+#
+# @loco_example Multi-line Terminal Output
+#   = daisy_code do |code|
+#     - code.with_line(prefix: "$") do
+#       npm install
+#     - code.with_line(prefix: ">", css: "text-warning") do
+#       Installing packages...
+#     - code.with_line(prefix: ">", css: "text-success") do
+#       Done in 2.45s
+#
+# @loco_example Code Block with Highlighting
+#   = daisy_code do |code|
+#     - code.with_line(prefix: "1") do
+#       def hello_world
+#     - code.with_line(prefix: "2", css: "bg-warning") do
+#       puts "Hello, world!"
+#     - code.with_line(prefix: "3") do
+#       end
+#
+# @loco_example Plain Code Block
+#   = daisy_code do
+#     :plain
+#       class Example
+#         def initialize
+#           @value = 42
+#         end
+#       end
+#
+class Daisy::Mockup::CodeComponent < LocoMotion::BaseComponent
+
+  #
+  # A component for rendering individual lines within a code block.
+  #
+  # @part code The code content for this line.
+  #
+  class Daisy::Mockup::CodeLineComponent < LocoMotion::BaseComponent
+    define_parts :code
+
+    #
+    # Creates a new code line.
+    #
+    # @option kws prefix [String] Optional prefix for the line (e.g., "$",
+    #   ">", or line numbers).
+    # @option kws css [String] Additional CSS classes for styling the line.
+    #
+    def initialize(**kws)
+      super(**kws)
+
+      @prefix = config_option(:prefix)
+    end
+
+    #
+    # Sets up the component's HTML tags and attributes.
+    #
+    def before_render
+      set_tag_name(:component, :pre)
+      set_tag_name(:code, :code)
+
+      add_html(:component, { "data-prefix": @prefix }) if @prefix
+    end
+
+    #
+    # Renders the line with its code content.
+    #
+    def call
+      part(:component) do
+        part(:code) do
+          content
+        end
+      end
+    end
+  end
+
+  define_parts :pre, :code
+  renders_many :lines, Daisy::Mockup::CodeLineComponent
+
+  #
+  # Creates a new code block component.
+  #
+  # @option kws prefix [String] Optional prefix for all lines (if not using
+  #   individual line prefixes).
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Size: `w-full`, `max-w-3xl`
+  #   - Background: `bg-base-300`, `bg-neutral`
+  #   - Text: `text-sm`, `text-base-content`
+  #
+  def initialize(**kws)
+    super(**kws)
+
+    @prefix = config_option(:prefix)
+  end
+
+  #
+  # Sets up the component's CSS classes and HTML attributes.
+  #
+  def before_render
+    add_css(:component, "mockup-code")
+
+    set_tag_name(:pre, :pre)
+    set_tag_name(:code, :code)
+
+    add_html(:pre, { "data-prefix": @prefix }) if @prefix
+
+    # If the prefix is blank, add some left margin and hide the :before
+    # pseudo-element used for the prefix
+    add_css(:pre, "before:!hidden ml-6") if @prefix.blank?
+  end
+
+  #
+  # Renders the code block with its lines or direct content.
+  #
+  def call
+    part(:component) do
+      if lines.any?
+        lines.each { |line| concat(line) }
+      else
+        part(:pre) do
+          part(:code) do
+            content
+          end
+        end
+      end
+    end
+  end
+end