loco_motion-rails 0.0.6 → 0.0.8

data/app/components/daisy/data_display/card_component.rb

@@ -1,53 +1,89 @@
-class Daisy::DataDisplay::CardComponent < LocoMotion.configuration.base_component_class
-
-  Figure = LocoMotion::BasicComponent.build do
-    define_part :image, tag_name: :img, css: "card-image"
-
-    def initialize(*args, **kws, &block)
-      super
-
-      @src = kws[:src]
-    end
-
-    def before_render
-      set_tag_name(:component, :figure)
-      add_html(:image, src: @src) if @src
-    end
-
-    def call
-      part(:component) do
-        if @src
-          part(:image)
-        else
-          content
-        end
-      end
-    end
-  end
-
-  define_parts :body, :title
+#
+# The Card component is a flexible container for displaying content with a
+# consistent style. It can include images, titles, text, and actions.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @part body The main content area of the card.
+# @part title The title text container when using the simple title option.
+#
+# @slot title A custom title section, typically rendered as an `h2` element.
+# @slot top_figure {Daisy::DataDisplay::FigureComponent} An optional figure
+#   (usually an image) to display at the top of the card.
+# @slot bottom_figure {Daisy::DataDisplay::FigureComponent} An optional figure
+#   (usually an image) to display at the bottom of the card.
+# @slot actions A container for action buttons or links, typically displayed at
+#   the bottom of the card.
+#
+# @loco_example Basic Usage
+#   = daisy_card(title: "Simple Card") do
+#     This is a basic card with just a title and some content.
+#
+# @loco_example With Top Image
+#   = daisy_card do |card|
+#     - card.with_top_figure(src: "example.jpg")
+#     - card.with_title { "Card with Image" }
+#     A card with an image at the top and a custom title.
+#
+# @loco_example With Actions
+#   = daisy_card do |card|
+#     - card.with_title { "Interactive Card" }
+#     This card has buttons for user interaction.
+#     - card.with_actions do
+#       = daisy_button("Learn More")
+#       = daisy_button("Share")
+#
+# @loco_example Complex Layout
+#   = daisy_card do |card|
+#     - card.with_top_figure(src: "header.jpg")
+#     - card.with_title do
+#       .flex.items-center.gap-2
+#         = heroicon_tag "star"
+#         Featured Article
+#     %p{ class: "text-base-content/70" } A beautifully designed card with rich content.
+#     - card.with_bottom_figure(src: "footer.jpg")
+#     - card.with_actions do
+#       .flex.justify-between.w-full
+#         = daisy_button("Read More")
+#         .flex.gap-2
+#           = daisy_button(icon: "heart", tip: "Like")
+#           = daisy_button(icon: "share", tip: "Share")
+#
+class Daisy::DataDisplay::CardComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
 
   renders_one :title, LocoMotion::BasicComponent.build(tag_name: :h2, css: "card-title")
-  renders_one :top_figure, Figure
-  renders_one :bottom_figure, Figure
+  renders_one :top_figure, Daisy::DataDisplay::FigureComponent.build(css: "card-image")
+  renders_one :bottom_figure, Daisy::DataDisplay::FigureComponent.build(css: "card-image")
   renders_one :actions, LocoMotion::BasicComponent.build(css: "card-actions")
 
-  def initialize(*args, **kws, &block)
+  # @return [String] The title text when using the simple title option.
+  attr_reader :simple_title
+
+  # Creates a new card component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws title [String] Optional simple title text. For more complex
+  #   titles, use the `with_title` method instead.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Image Side: `image-full` (image becomes background)
+  #   - Borders: `bordered`
+  #   - Compact: `compact` (less padding)
+  #   - Colors: `bg-base-100`, `bg-primary`, `bg-secondary`
+  #
+  def initialize(**kws, &block)
     super
 
     @simple_title = kws[:title]
-  end
-
-  def before_render
-    setup_component
-    setup_body
-  end
 
-  def setup_component
     add_css(:component, "card")
   end
 
-  def setup_body
-    add_css(:body, "card-body")
+  def before_render
+    with_title { simple_title } if simple_title && !title?
   end
 end

data/app/components/daisy/data_display/carousel_component.rb

@@ -1,4 +1,42 @@
-class Daisy::DataDisplay::CarouselComponent < LocoMotion.configuration.base_component_class
+#
+# The Carousel component displays a horizontal scrolling list of items, such as
+# images, cards, or any other content. It's useful for showcasing multiple
+# items in a space-efficient manner.
+#
+# @slot item+ Multiple items to display in the carousel. Each item will be
+#   displayed side by side and can be scrolled horizontally.
+#
+# @loco_example Basic Usage with Images
+#   = daisy_carousel do |carousel|
+#     - carousel.with_item do
+#       %img{ src: "image1.jpg", class: "w-full" }
+#     - carousel.with_item do
+#       %img{ src: "image2.jpg", class: "w-full" }
+#     - carousel.with_item do
+#       %img{ src: "image3.jpg", class: "w-full" }
+#
+# @loco_example With Cards
+#   = daisy_carousel do |carousel|
+#     - carousel.with_item do
+#       = daisy_card(title: "Card 1") do
+#         First card content
+#     - carousel.with_item do
+#       = daisy_card(title: "Card 2") do
+#         Second card content
+#
+# @loco_example With Custom Styling
+#   = daisy_carousel(css: "h-96 rounded-box") do |carousel|
+#     - carousel.with_item(css: "w-1/2") do
+#       .bg-primary.text-primary-content.p-4.h-full
+#         %h2.text-2xl First Slide
+#         %p Some content for the first slide
+#     - carousel.with_item(css: "w-1/2") do
+#       .bg-secondary.text-secondary-content.p-4.h-full
+#         %h2.text-2xl Second Slide
+#         %p Some content for the second slide
+#
+class Daisy::DataDisplay::CarouselComponent < LocoMotion::BaseComponent
+  # A component for rendering individual items within the carousel.
   class ItemComponent < LocoMotion::BasicComponent
     def before_render
       add_css(:component, "carousel-item")

data/app/components/daisy/data_display/chat_component.rb

@@ -1,24 +1,51 @@
 #
-# The {ChatComponent} renders a bubble-like chat interface with an optional
-# avatar, header, and footer.
+# The Chat component renders a messaging interface with support for avatars,
+# message bubbles, and optional header and footer content. It's perfect for
+# displaying conversations, comments, or any message-based interactions.
 #
-# @slot   avatar Renders an {AvatarComponent}. Common options include:
-# @option avatar [String] src The URL of the image to display.
-# @option avatar [String] icon A heroicon to be displayed instead of an image.
+# @slot avatar An optional avatar for the message sender. Uses the
+#   {AvatarComponent} with preset styling for chat messages.
 #
-# @slot header [LocoMotion::BasicComponent] Renders a single header.
-# @slot footer [LocoMotion::BasicComponent] Renders a single footer.
-# @slot bubble [LocoMotion::BasicComponent] Renders one or more bubbles.
+# @slot header A header section above the message bubbles, typically used for
+#   sender name or timestamp.
 #
-# ## Examples
+# @slot footer A footer section below the message bubbles, often used for
+#   message status or metadata.
 #
-# ```language-haml
-# = daisy_chat(css: "border rounded-lg", html: { title: message.short_desc }) do |chat|
-#   - chat.with_bubble do
-#     I can't believe it's not the weekend yet!
-# ```
+# @slot bubble+ One or more message bubbles containing the actual message
+#   content.
 #
-class Daisy::DataDisplay::ChatComponent < LocoMotion.configuration.base_component_class
+# @loco_example Basic Usage
+#   = daisy_chat do |chat|
+#     - chat.with_bubble do
+#       Hello! How can I help you today?
+#
+# @loco_example With Avatar
+#   = daisy_chat do |chat|
+#     - chat.with_avatar(src: "avatar.jpg")
+#     - chat.with_bubble do
+#       Hi there! I'm your assistant.
+#
+# @loco_example Complete Message
+#   = daisy_chat do |chat|
+#     - chat.with_avatar(icon: "user")
+#     - chat.with_header do
+#       .font-bold John Doe
+#       .text-xs 2 minutes ago
+#     - chat.with_bubble do
+#       Can you help me with my account?
+#     - chat.with_bubble do
+#       I can't seem to find the settings page.
+#     - chat.with_footer do
+#       .text-xs Sent from Web App
+#
+# @loco_example End-aligned Chat
+#   = daisy_chat(css: "chat-end") do |chat|
+#     - chat.with_avatar(src: "user.jpg")
+#     - chat.with_bubble do
+#       Sure! The settings page is under your profile menu.
+#
+class Daisy::DataDisplay::ChatComponent < LocoMotion::BaseComponent
   renders_one :avatar, Daisy::DataDisplay::AvatarComponent.build(css: "chat-image", icon_css: "size-6 text-base-100", wrapper_css: "w-10 rounded-full")
   renders_one :header, LocoMotion::BasicComponent.build(css: "chat-header [:where(&)]:text-neutral-500")
   renders_one :footer, LocoMotion::BasicComponent.build(css: "chat-footer [:where(&)]:text-neutral-500")

data/app/components/daisy/data_display/collapse_component.rb

@@ -1,10 +1,69 @@
-class Daisy::DataDisplay::CollapseComponent < LocoMotion.configuration.base_component_class
+#
+# The Collapse component creates an expandable/collapsible section of content
+# with a title that toggles visibility. It's similar to the Accordion component
+# but designed for standalone use rather than groups.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @part title The clickable title bar that toggles the content visibility.
+# @part wrapper The container for the collapsible content.
+#
+# @slot title Custom content for the title bar. You can also provide a simple
+#   title string via the title option.
+#
+# @loco_example Basic Usage
+#   = daisy_collapse(title: "Click to expand") do
+#     This content can be shown or hidden.
+#
+# @loco_example With Custom Title
+#   = daisy_collapse do |collapse|
+#     - collapse.with_title do
+#       .flex.items-center.gap-2
+#         = heroicon_tag "chevron-down"
+#         Advanced Settings
+#     %p These are some advanced configuration options.
+#     = daisy_button("Apply Settings")
+#
+# @loco_example With Focus Mode
+#   = daisy_collapse(checkbox: false) do |collapse|
+#     - collapse.with_title do
+#       Click or use keyboard to toggle
+#     This content can be focused and toggled with the keyboard.
+#
+# @loco_example With Arrow
+#   = daisy_collapse(title: "Expandable Section", css: "collapse-arrow") do
+#     This section has an arrow indicator.
+#
+# @loco_example With Plus/Minus
+#   = daisy_collapse(title: "Expandable Section", css: "collapse-plus") do
+#     This section has a plus/minus indicator.
+#
+class Daisy::DataDisplay::CollapseComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
   define_parts :title, :wrapper
 
   renders_one :title
 
-  attr_reader :simple_title, :checkbox
+  # @return [String] The title text when using the simple title option.
+  attr_reader :simple_title
+
+  # @return [Boolean] Whether to use a checkbox for toggle state (true) or
+  #   focus/tabindex mode (false).
+  attr_reader :checkbox
 
+  #
+  # Creates a new collapse component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws title [String] The text to display in the title bar. You can
+  #   also provide custom title content using the title slot.
+  #
+  # @option kws checkbox [Boolean] Whether to use a checkbox for toggle state
+  #   (true) or focus/tabindex mode (false). Defaults to true.
+  #
   def initialize(*args, **kws, &block)
     super
 

data/app/components/daisy/data_display/countdown_component.rb

@@ -1,8 +1,58 @@
-class Daisy::DataDisplay::CountdownComponent < LocoMotion.configuration.base_component_class
+#
+# The Countdown component displays a timer that counts down to or up from a
+# specific duration. It can show days, hours, minutes, and seconds with
+# customizable separators and formats.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @part days The container for the days value.
+# @part hours The container for the hours value.
+# @part minutes The container for the minutes value.
+# @part seconds The container for the seconds value.
+#
+# @loco_example Basic Usage
+#   = daisy_countdown(1.day + 2.hours + 30.minutes)
+#
+# @loco_example With Word Separators
+#   = daisy_countdown(5.days + 12.hours + 45.minutes, modifier: :words) do |cd|
+#     1 day 12 hours 45 minutes remaining
+#
+# @loco_example With Letter Separators
+#   = daisy_countdown(24.hours + 59.minutes + 59.seconds, modifier: :letters) do |cd|
+#     24h 59m 59s left
+#
+# @loco_example With Custom Separator
+#   = daisy_countdown(3.hours + 30.minutes, separator: " → ")
+#
+class Daisy::DataDisplay::CountdownComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
 
   define_parts :days, :hours, :minutes, :seconds
   define_modifiers :words, :letters
 
+  #
+  # Creates a new countdown component.
+  #
+  # @param duration [ActiveSupport::Duration] The duration to count down from.
+  #   Can be created using Rails duration helpers like 1.day, 2.hours, etc.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws [ActiveSupport::Duration] :duration The duration to count down
+  #   from. Alternative to providing it as the first argument.
+  #
+  # @option kws [Symbol] :modifier Optional display modifier. Use :words for
+  #   "days", "hours", etc., or :letters for "d", "h", etc.
+  #
+  # @option kws [String] :separator The separator to use between time parts.
+  #   Defaults to ":". Ignored when using :words or :letters modifiers.
+  #
+  # @option kws [String] :parts_css CSS classes to apply to all time parts
+  #   (days, hours, minutes, seconds).
+  #
+  # @option kws [Hash] :parts_html HTML attributes to apply to all time parts.
+  #
   def initialize(*args, **kws, &block)
     super
 

data/app/components/daisy/data_display/diff_component.rb

@@ -1,4 +1,41 @@
-class Daisy::DataDisplay::DiffComponent < LocoMotion.configuration.base_component_class
+#
+# The Diff component displays two items side by side with a resizable divider
+# between them. It's perfect for comparing content or showing before/after
+# states. The component requires exactly two items to function properly.
+#
+# @part resizer The draggable divider between items that allows resizing.
+#
+# @slot item Two items to be compared. Exactly two items must be provided.
+#
+# @loco_example Basic Usage
+#   = daisy_diff do |diff|
+#     - diff.with_item do
+#       %img{ src: "before.jpg", alt: "Before" }
+#     - diff.with_item do
+#       %img{ src: "after.jpg", alt: "After" }
+#
+# @loco_example With Text Content
+#   = daisy_diff do |diff|
+#     - diff.with_item do
+#       .p-4.prose
+#         %h3 Original Text
+#         %p Here is the first version of the text...
+#     - diff.with_item do
+#       .p-4.prose
+#         %h3 Revised Text
+#         %p Here is the improved version...
+#
+# @loco_example With Custom Resizer
+#   = daisy_diff(resizer_css: "bg-primary hover:bg-primary-focus") do |diff|
+#     - diff.with_item do
+#       %img{ src: "before.jpg", alt: "Before" }
+#     - diff.with_item do
+#       %img{ src: "after.jpg", alt: "After" }
+#
+class Daisy::DataDisplay::DiffComponent < LocoMotion::BaseComponent
+  #
+  # A component for rendering individual items within the diff comparison.
+  #
   class ItemComponent < LocoMotion::BasicComponent
     def set_index(index)
       @index = index

data/app/components/daisy/data_display/figure_component.rb

@@ -0,0 +1,49 @@
+#
+# The FigureComponent is used to display images with optional captions. It is
+# commonly used within cards and other content containers.
+#
+# @part image The image element when a source URL is provided.
+#
+# @loco_example Basic Usage
+#   = daisy_figure(src: "example.jpg")
+#
+# @loco_example With Caption
+#   = daisy_figure(src: "example.jpg") do
+#     A beautiful landscape
+#
+# @loco_example Without Image
+#   = daisy_figure do
+#     Content when no image is provided
+#
+class Daisy::DataDisplay::FigureComponent < LocoMotion::BaseComponent
+  define_part :image, tag_name: :img
+
+  # Creates a new figure component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws src [String] URL of the image to display in the figure.
+  #
+  # @option kws css [String] Additional CSS classes for styling.
+  #
+  def initialize(**kws, &block)
+    super
+
+    @src = kws[:src]
+  end
+
+  def before_render
+    set_tag_name(:component, :figure)
+    add_html(:image, src: @src) if @src
+  end
+
+  def call
+    part(:component) do
+      if @src
+        part(:image)
+      else
+        content
+      end
+    end
+  end
+end

data/app/components/daisy/data_display/kbd_component.rb

@@ -1,8 +1,58 @@
-# This is the Kbd (Keyboard) component.
-class Daisy::DataDisplay::KbdComponent < LocoMotion.configuration.base_component_class
+#
+# The Kbd (Keyboard) component displays keyboard inputs or shortcuts in a
+# visually distinct way. It's perfect for showing keyboard shortcuts,
+# key combinations, or individual key presses in documentation or tutorials.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @note This is an inline component that renders as a `<span>` to avoid adding
+#   extra whitespace when used within text.
+#
+# @loco_example Basic Usage
+#   %p
+#     Press
+#     = daisy_kbd("Ctrl")
+#     = daisy_kbd("C")
+#     to copy.
+#
+# @loco_example With Tooltip
+#   %p
+#     Press
+#     = daisy_kbd("⌘", tip: "Command")
+#     = daisy_kbd("P")
+#     to print.
+#
+# @loco_example Key Combinations
+#   %p
+#     Press
+#     = daisy_kbd("Alt")
+#     + 
+#     = daisy_kbd("Shift")
+#     + 
+#     = daisy_kbd("M")
+#     to open the menu.
+#
+# @loco_example Special Keys
+#   %p
+#     Press
+#     = daisy_kbd("↵")
+#     or
+#     = daisy_kbd("Enter")
+#     to confirm.
+#
+class Daisy::DataDisplay::KbdComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
   set_component_name :kbd
 
-  # Create a new kbd component.
+  #
+  # Creates a new kbd component.
+  #
+  # @param text [String] The text to display in the keyboard component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
   def initialize(*args, **kws, &block)
     super
 
@@ -13,6 +63,17 @@ class Daisy::DataDisplay::KbdComponent < LocoMotion.configuration.base_component
     setup_component
   end
 
+  #
+  # Renders the kbd (Keyboard) 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
+    part(:component) { content }
+  end
+
   private
 
   def setup_component

data/app/components/daisy/data_display/stat_component.rb

@@ -1,5 +1,48 @@
-# This is the stats component.
-class Daisy::DataDisplay::StatComponent < LocoMotion.configuration.base_component_class
+#
+# The Stat component displays a statistic or metric with optional title,
+# description, and figure. It's perfect for dashboards, summaries, or any
+# situation where you need to highlight important numbers or metrics.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @part title The title section above the value.
+# @part value The main value or metric being displayed.
+# @part description Additional text below the value.
+# @part figure An optional figure (usually an icon or small image) to display.
+#
+# @slot title Custom content for the title section. You can also provide a
+#   simple title string via the title option.
+#
+# @slot description Custom content for the description section. You can also
+#   provide a simple description string via the description option.
+#
+# @slot figure Custom content for the figure section. You can also provide an
+#   image via the src option or an icon via the icon option.
+#
+# @loco_example Basic Usage
+#   = daisy_stat(title: "Downloads", value: "31K", css: "bg-base-200")
+#
+# @loco_example With Description
+#   = daisy_stat(title: "New Users", value: "2.6K", description: "↗︎ 400 (22%)", css: "bg-base-200")
+#
+# @loco_example With Icon
+#   = daisy_stat(title: "Page Views", value: "89,400", icon: "eye", css: "bg-base-200") do |stat|
+#     = stat.with_description do
+#       .flex.items-center.gap-1
+#         = heroicon_tag "arrow-up", class: "size-4 text-success"
+#         %span.text-success 14%
+#         from last month
+#
+# @loco_example With Custom Figure
+#   = daisy_stat(title: "Success Rate", value: "98%", css: "bg-base-200") do |stat|
+#     = stat.with_figure do
+#       .text-success
+#         = heroicon_tag "check-circle", class: "size-10"
+#
+class Daisy::DataDisplay::StatComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
   set_component_name :stat
 
   define_parts :title, :value, :description, :figure
@@ -8,10 +51,31 @@ class Daisy::DataDisplay::StatComponent < LocoMotion.configuration.base_componen
   renders_one :description
   renders_one :figure
 
+  # @return [String] The title text when using the simple title option.
   attr_reader :simple_title
+
+  # @return [String] The description text when using the simple description
+  #   option.
   attr_reader :simple_description
 
-  # Create a new stat component.
+  #
+  # Creates a new stat component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws [String] :title The text to display in the title section.
+  #   You can also provide custom title content using the title slot.
+  #
+  # @option kws [String] :description The text to display in the description
+  #   section. You can also provide custom description content using the
+  #   description slot.
+  #
+  # @option kws [String] :src URL of an image to display in the figure
+  #   section.
+  #
+  # @option kws [String] :icon Name of a heroicon to display in the figure
+  #   section.
+  #
   def initialize(*args, **kws, &block)
     super
 
@@ -33,9 +97,5 @@ class Daisy::DataDisplay::StatComponent < LocoMotion.configuration.base_componen
     add_css(:value, "stat-value")
     add_css(:description, "stat-desc")
     add_css(:figure, "stat-figure")
-
-    if @src.nil?
-
-    end
   end
 end