loco_motion-rails 0.0.7 → 0.0.8

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

@@ -1,19 +1,49 @@
 #
-# 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.
+#
+# @slot footer A footer section below the message bubbles, often used for
+#   message status or metadata.
+#
+# @slot bubble+ One or more message bubbles containing the actual message
+#   content.
 #
 # @loco_example Basic Usage
-#   = daisy_chat(css: "border rounded-lg", html: { title: message.short_desc }) do |chat|
+#   = 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
-#       I can't believe it's not the weekend yet!
+#       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")

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

@@ -1,3 +1,44 @@
+#
+# 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
 
@@ -5,8 +46,24 @@ class Daisy::DataDisplay::CollapseComponent < LocoMotion::BaseComponent
 
   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,9 +1,58 @@
+#
+# 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 @@
+#
+# 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,10 +1,58 @@
-# This is the Kbd (Keyboard) component.
+#
+# 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
 

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

@@ -1,4 +1,45 @@
-# This is the stats component.
+#
+# 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
 
@@ -10,10 +51,31 @@ class Daisy::DataDisplay::StatComponent < LocoMotion::BaseComponent
   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
 
@@ -35,9 +97,5 @@ class Daisy::DataDisplay::StatComponent < LocoMotion::BaseComponent
     add_css(:value, "stat-value")
     add_css(:description, "stat-desc")
     add_css(:figure, "stat-figure")
-
-    if @src.nil?
-
-    end
   end
 end

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

@@ -1,15 +1,85 @@
 #
-# The Table component is used to render HTML tables with rows, columns, and headers.
+# The Table component creates structured data tables with support for headers,
+# multiple sections, and complex layouts. It provides a clean, semantic way to
+# display tabular data while maintaining proper HTML structure.
+#
+# @slot head A header section containing column titles.
+# @slot body A body section containing rows of data.
+# @slot row+ Individual rows that can be added directly to the table.
+# @slot section+ Multiple sections, each with its own header and body, for
+#   complex table layouts.
+#
+# @loco_example Basic Usage
+#   = daisy_table do |table|
+#     - table.with_head do |head|
+#       - head.with_column { "Name" }
+#       - head.with_column { "Role" }
+#       - head.with_column { "Department" }
+#
+#     - table.with_row do |row|
+#       - row.with_column { "John Smith" }
+#       - row.with_column { "Developer" }
+#       - row.with_column { "Engineering" }
+#
+#     - table.with_row do |row|
+#       - row.with_column { "Jane Doe" }
+#       - row.with_column { "Designer" }
+#       - row.with_column { "Product" }
+#
+# @loco_example With Body Container
+#   = daisy_table do |table|
+#     - table.with_head do |head|
+#       - head.with_column { "Product" }
+#       - head.with_column { "Price" }
+#
+#     - table.with_body do |body|
+#       - body.with_row do |row|
+#         - row.with_column { "Basic Plan" }
+#         - row.with_column { "$10/mo" }
+#       - body.with_row do |row|
+#         - row.with_column { "Pro Plan" }
+#         - row.with_column { "$20/mo" }
+#
+# @loco_example With Multiple Sections
+#   = daisy_table do |table|
+#     - table.with_section do |section|
+#       - section.with_head do |head|
+#         - head.with_column { "Active Users" }
+#         - head.with_column { "Status" }
+#
+#       - section.with_body do |body|
+#         - body.with_row do |row|
+#           - row.with_column { "Alice" }
+#           - row.with_column { "Online" }
+#
+#     - table.with_section do |section|
+#       - section.with_head do |head|
+#         - head.with_column { "Inactive Users" }
+#         - head.with_column { "Last Seen" }
+#
+#       - section.with_body do |body|
+#         - body.with_row do |row|
+#           - row.with_column { "Bob" }
+#           - row.with_column { "2 days ago" }
 #
-# @!parse class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent; end
 class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent
 
+  #
+  # A component for rendering individual header cells (`<th>`) within a table
+  # header row.
+  #
   class HeadColumnComponent < LocoMotion::BasicComponent
     def before_render
       set_tag_name :component, :th
     end
   end
 
+  #
+  # A component for rendering the table header (`<thead>`) section. Contains
+  # header columns that define the structure of the table.
+  #
+  # @slot column+ Individual header cells within the header row.
+  #
   class HeadComponent < LocoMotion::BasicComponent
     renders_many :columns, HeadColumnComponent
 
@@ -28,12 +98,20 @@ class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent
     end
   end
 
+  #
+  # A component for rendering individual data cells (`<td>`) within a table row.
+  #
   class BodyColumnComponent < LocoMotion::BasicComponent
     def before_render
       set_tag_name :component, :td
     end
   end
 
+  #
+  # A component for rendering table rows (`<tr>`) containing data cells.
+  #
+  # @slot column+ Individual data cells within the row.
+  #
   class BodyRowComponent < LocoMotion::BasicComponent
     renders_many :columns, BodyColumnComponent
 
@@ -50,6 +128,12 @@ class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent
     end
   end
 
+  #
+  # A component for rendering the table body (`<tbody>`) section. Contains rows
+  # of data.
+  #
+  # @slot row+ Individual rows of data within the body.
+  #
   class BodyComponent < LocoMotion::BasicComponent
     renders_many :rows, BodyRowComponent
 
@@ -59,15 +143,21 @@ class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent
 
     def call
       part(:component) do
-        content_tag(:tr) do
-          rows.each do |row|
-            concat(row)
-          end
+        rows.each do |row|
+          concat(row)
         end
       end
     end
   end
 
+  #
+  # A component for grouping related table content into sections. Each section
+  # can have its own header and body, allowing for complex table layouts.
+  #
+  # @slot head A header section for this group of data.
+  # @slot body A body section for this group of data.
+  # @slot row+ Individual rows that can be added directly to this section.
+  #
   class SectionComponent < LocoMotion::BasicComponent
     renders_one :head, HeadComponent
     renders_one :body, BodyComponent
@@ -78,7 +168,7 @@ class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent
     end
 
     def call
-      # Sections can't be rendered inside a <table> tag, so we don't render the
+      # Sections can't be rendered inside a `<table>` tag, so we don't render the
       # typical `part(:component)` here.
       concat(head) if head?
 
@@ -103,33 +193,8 @@ class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent
 
   #
   # Instantiate a new Table component. This component takes no content, but
-  # requires you to utilize the optional <code>head</code> slot, and one of the
-  # <code>body</code> or <code>rows</code> slots.
-  #
-  # @example
-  #  = daisy_table do |table|
-  #    - table.head do |head|
-  #      - head.with_column do
-  #        Column 1
-  #      - head.with_column do
-  #        Column 2
-  #
-  #    - table.with_row do |row|
-  #      - row.with_column do
-  #        Row 1 - Column 1
-  #      - row.with_column do
-  #        Row 1 - Column 2
-  #    - table.with_row do |row|
-  #      - row.with_column do
-  #        Row 2 - Column 1
-  #      - row.with_column do
-  #        Row 2 - Column 2
-  #
-  # For more complex tables, you can use the <code>section</code> slot which
-  # takes a <code>head</code> and <code>body</code> slot allowing you to build a
-  # table with multiple headers and bodies.
-  #
-  # Please see the demo for more examples of usage.
+  # requires you to utilize the optional `head` slot, and one of the `body` or
+  # `rows` slots.
   #
   def initialize(*args, **kws, &block)
     super

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

@@ -1,3 +1,48 @@
+#
+# The Timeline component displays a list of events in chronological order,
+# either vertically or horizontally. It's perfect for showing history,
+# progress, or any sequence of events that should be displayed in order.
+#
+# @slot event+ Individual events in the timeline. Each event can have start,
+#   middle, and end sections.
+#
+# @loco_example Basic Vertical Timeline
+#   = daisy_timeline do |timeline|
+#     - timeline.with_event(start: "2023", end: "Launched product") do |event|
+#       - event.with_middle { "🚀" }
+#
+#     - timeline.with_event(start: "2024", end: "1M users") do |event|
+#       - event.with_middle { "🎉" }
+#
+# @loco_example Horizontal Timeline
+#   = daisy_timeline(css: "timeline-horizontal") do |timeline|
+#     - timeline.with_event(start: "Q1", end: "Planning") do |event|
+#       - event.with_middle { "📋" }
+#
+#     - timeline.with_event(start: "Q2", end: "Development") do |event|
+#       - event.with_middle { "💻" }
+#
+#     - timeline.with_event(start: "Q3", end: "Testing") do |event|
+#       - event.with_middle { "🧪" }
+#
+#     - timeline.with_event(start: "Q4", end: "Launch") do |event|
+#       - event.with_middle { "🚀" }
+#
+# @loco_example Custom Content (Vertical)
+#   = daisy_timeline do |timeline|
+#     - timeline.with_event do |event|
+#       - event.with_start do
+#         .font-bold Jan 2024
+#         %div{ class: "text-sm text-base-content/70" } Q1
+#
+#       - event.with_middle do
+#         .bg-primary.text-primary-content.p-2.rounded-full
+#           = heroicon_tag "star"
+#
+#       - event.with_end do
+#         %h3.font-bold Milestone Reached
+#         %div{ class: "text-base-content/70" } Exceeded quarterly goals
+#
 class Daisy::DataDisplay::TimelineComponent < LocoMotion::BaseComponent
   renders_many :events, Daisy::DataDisplay::TimelineEventComponent