loco_motion-rails 0.0.6 → 0.0.8

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.
 #
-# @!parse class Daisy::DataDisplay::TableComponent < LocoMotion::BaseComponent; end
-class Daisy::DataDisplay::TableComponent < LocoMotion.configuration.base_component_class
+# @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" }
+#
+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.configuration.base_compone
     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.configuration.base_compone
     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.configuration.base_compone
 
     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.configuration.base_compone
     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.configuration.base_compone
 
   #
   # 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,4 +1,49 @@
-class Daisy::DataDisplay::TimelineComponent < LocoMotion.configuration.base_component_class
+#
+# 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
 
   def before_render

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

@@ -1,4 +1,28 @@
-class Daisy::DataDisplay::TimelineEventComponent < LocoMotion.configuration.base_component_class
+#
+# A component for rendering individual events within a timeline. Each event can
+# have three sections: start (typically a date or time), middle (an icon or
+# marker), and end (the event description).
+#
+# @part start The container for the start content (e.g., date/time).
+# @part middle The container for the middle content.
+# @part middle_icon Container for a simple icon when not using custom middle
+#   content.
+# @part end The container for the end content (e.g., description).
+# @part separator The line connecting this event to the next one.
+#
+# @slot start Custom content for the start section. You can also provide
+#   simple text via the start option.
+#
+# @slot middle Custom content for the middle section. You can also provide
+#   simple text via the middle option, or an icon via the middle_icon option.
+#
+# @slot end Custom content for the end section. You can also provide simple
+#   text via the end option.
+#
+# @note The middle and middle_icon options are mutually exclusive. If both are
+#   provided, middle takes precedence.
+#
+class Daisy::DataDisplay::TimelineEventComponent < LocoMotion::BaseComponent
   renders_one :start, LocoMotion::BasicComponent.build(css: "timeline-start")
   renders_one :middle, LocoMotion::BasicComponent.build(css: "timeline-middle")
   renders_one :end, LocoMotion::BasicComponent.build(css: "timeline-end")
@@ -6,7 +30,21 @@ class Daisy::DataDisplay::TimelineEventComponent < LocoMotion.configuration.base
   define_parts :start, :middle, :middle_icon, :end, :separator
 
   #
-  # middle and middle_icon are mutually exclusive, middle takes presedence
+  # Creates a new timeline event component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws [String] :start Text to display in the start section. You can
+  #   also provide custom content using the start slot.
+  #
+  # @option kws [String] :middle Text to display in the middle section. You
+  #   can also provide custom content using the middle slot.
+  #
+  # @option kws [String] :middle_icon Name of a heroicon to display in the
+  #   middle section. Ignored if middle is provided.
+  #
+  # @option kws [String] :end Text to display in the end section. You can
+  #   also provide custom content using the end slot.
   #
   def initialize(*args, **kws, &block)
     super(*args, **kws, &block)

data/app/components/daisy/feedback/alert_component.rb

@@ -1,9 +1,54 @@
 #
-# The AlertComponent displays an important message to users.
+# The AlertComponent displays an important message to users. It can be used to
+# show information, success messages, warnings, or errors. Alerts can include
+# an optional icon at the start and customizable content.
 #
-class Daisy::Feedback::AlertComponent < LocoMotion.configuration.base_component_class
+# @part icon             [Heroicon] An optional icon displayed at the start of
+#   the alert. Uses the Heroicon system.
+#
+# @part content_wrapper  [HTML] A wrapper for the main content of the alert.
+#   This allows for proper spacing and alignment with the icon.
+#
+# @loco_example Basic Alert
+#   = daisy_alert do
+#     This is a standard alert message.
+#
+# @loco_example Alert with Icon
+#   = daisy_alert(icon: "information-circle", icon_html: { variant: :outline }) do
+#     Here's some important information!
+#
+# @loco_example Alert Types
+#   = daisy_alert(icon: "information-circle", css: "alert-info", icon_html: { variant: :outline }) do
+#     Information alert.
+#
+#   = daisy_alert(icon: "check-circle", css: "alert-success", icon_html: { variant: :outline }) do
+#     Success alert.
+#
+#   = daisy_alert(icon: "exclamation-triangle", css: "alert-warning", icon_html: { variant: :outline }) do
+#     Warning alert.
+#
+#   = daisy_alert(icon: "exclamation-circle", css: "alert-error", icon_html: { variant: :outline }) do
+#     Error alert.
+#
+class Daisy::Feedback::AlertComponent < LocoMotion::BaseComponent
   define_parts :icon, :content_wrapper
 
+  #
+  # Creates a new Alert component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the alert.
+  #
+  # @option kws icon      [String] The name of the Heroicon to display at the
+  #   start of the alert.
+  #
+  # @option kws icon_html [Hash] Additional HTML attributes for the icon
+  #   element. Options include `variant: :outline` or `variant: :solid`.
+  #
+  # @option kws css      [String] Additional CSS classes for the alert. Use
+  #   `alert-info`, `alert-success`, `alert-warning`, or `alert-error` for
+  #   different alert types.
+  #
   def initialize(*args, **kws, &block)
     super
 

data/app/components/daisy/feedback/loading_component.rb

@@ -0,0 +1,50 @@
+#
+# The LoadingComponent displays an animated indicator to show that a process is
+# running in the background. It supports multiple animation styles and can be
+# customized with different colors and sizes.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @loco_example Basic Loading Spinners
+#   = daisy_loading(css: "loading-spinner text-primary")
+#   = daisy_loading(css: "loading-dots text-secondary")
+#   = daisy_loading(css: "loading-ring text-accent")
+#
+# @loco_example Other Loading Styles
+#   = daisy_loader(css: "loading-ball text-info")
+#   = daisy_loader(css: "loading-bars text-success")
+#   = daisy_loader(css: "loading-infinity text-error")
+#
+# @note The helper method is also aliased as `daisy_loader` for better
+#   readability, but CSS classes must still use the `loading-*` prefix.
+#
+class Daisy::Feedback::LoadingComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
+  #
+  # Creates a new Loading component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the loader.
+  #
+  # @option kws css   [String] Additional CSS classes for the loader. Available
+  #   styles include: `loading-spinner`, `loading-dots`, `loading-ring`,
+  #   `loading-ball`, `loading-bars`, and `loading-infinity`. Can be combined
+  #   with color classes like `text-primary` or `text-success`.
+  #
+  # @option kws tip   [String] Optional tooltip text to display when hovering
+  #   over the loader. Added by the TippableComponent module.
+  #
+  def initialize(*args, **kws, &block)
+    super
+  end
+
+  def before_render
+    add_css(:component, "loading")
+  end
+
+  def call
+    part(:component)
+  end
+end

data/app/components/daisy/feedback/progress_component.rb

@@ -0,0 +1,58 @@
+#
+# The ProgressComponent displays a horizontal bar that indicates the completion
+# status of a process. It can show determinate progress with a specific value
+# or indeterminate progress with an animated bar.
+#
+# The component renders as an HTML `<progress>` element and supports various
+# colors and styles through CSS classes.
+#
+# @loco_example Basic Progress Bars
+#   = daisy_progress(value: 25)
+#   = daisy_progress(css: "progress-primary", value: 50)
+#   = daisy_progress(css: "progress-secondary", value: 75)
+#   = daisy_progress(css: "progress-accent", value: 100)
+#
+# @loco_example Indeterminate Progress Bars
+#   = daisy_progress(css: "progress-info")
+#   = daisy_progress(css: "progress-success ![animation-delay:250ms]")
+#   = daisy_progress(css: "progress-warning ![animation-delay:500ms]")
+#   = daisy_progress(css: "progress-error ![animation-delay:750ms]")
+#
+class Daisy::Feedback::ProgressComponent < LocoMotion::BaseComponent
+
+  #
+  # Creates a new Progress component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the progress bar.
+  #
+  # @option kws value [Integer, nil] The current progress value. Set to `nil`
+  #   for an indeterminate progress bar that animates continuously. Defaults
+  #   to `nil`.
+  #
+  # @option kws max   [Integer] The maximum value for the progress bar.
+  #   Defaults to `100` to easily work with percentage values.
+  #
+  # @option kws css   [String] Additional CSS classes for the progress bar.
+  #   Available styles include: `progress-primary`, `progress-secondary`,
+  #   `progress-accent`, `progress-info`, `progress-success`,
+  #   `progress-warning`, and `progress-error`. Can be combined with utility
+  #   classes like `![animation-delay:250ms]` for staggered animations.
+  #
+  def initialize(*args, **kws, &block)
+    super
+
+    @value = config_option(:value, nil)
+    @max = config_option(:max, 100)
+  end
+
+  def before_render
+    set_tag_name(:component, :progress)
+    add_css(:component, "progress")
+    add_html(:component, { value: @value, max: @max }) if @value != nil
+  end
+
+  def call
+    part(:component)
+  end
+end

data/app/components/daisy/feedback/radial_progress_component.rb

@@ -0,0 +1,72 @@
+#
+# The RadialProgressComponent displays a circular progress indicator that can be
+# customized with different sizes, thicknesses, and colors. The component can
+# also contain content within its circular display.
+#
+# The progress is always displayed as a percentage (0-100) due to the way the
+# component is rendered using CSS custom properties.
+#
+# @loco_example Basic Usage
+#   = daisy_radial(value: 66) do
+#     66%
+#
+# @loco_example With Icons
+#   = daisy_radial(value: 68) do
+#     = hero_icon("beaker", css: "size-8 text-purple-500")
+#
+#   = daisy_radial(value: 52, css: "text-success") do
+#     52%
+#
+# @loco_example Custom Size and Styling
+#   = daisy_radial(value: 19, size: "15rem", thickness: "4px",
+#     css: "bg-primary text-primary-content text-3xl") do
+#     19%
+#
+class Daisy::Feedback::RadialProgressComponent < LocoMotion::BaseComponent
+
+  #
+  # Creates a new Radial Progress component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the radial progress.
+  #
+  # @option kws value      [Integer] The current progress value as a
+  #   percentage (0-100). Required for the progress to be displayed.
+  #
+  # @option kws size       [String] The size of the radial progress component.
+  #   Must include CSS units (e.g., "5rem", "100px"). Defaults to "5rem".
+  #
+  # @option kws thickness [String] The thickness of the progress ring. Must
+  #   include CSS units (e.g., "4px", "0.5rem"). Defaults to one-tenth of
+  #   the size.
+  #
+  # @option kws css       [String] Additional CSS classes for styling. Common
+  #   options include color classes like `text-success` or `text-error`,
+  #   background colors like `bg-primary`, and text sizing like `text-3xl`.
+  #
+  def initialize(*args, **kws, &block)
+    super
+
+    @value = config_option(:value)
+    @size = config_option(:size)
+    @thickness = config_option(:thickness)
+  end
+
+  def before_render
+    add_css(:component, "radial-progress")
+
+    styles = []
+
+    styles << "--value: #{@value}" if @value != nil
+    styles << "--size: #{@size}" if @size != nil
+    styles << "--thickness: #{@thickness}" if @thickness != nil
+
+    add_html(:component, { role: "progressbar" })
+    add_html(:component, { style: styles.join(";") }) if styles.present?
+  end
+
+  def call
+    part(:component) { content }
+  end
+
+end

data/app/components/daisy/feedback/skeleton_component.rb

@@ -0,0 +1,53 @@
+#
+# The SkeletonComponent creates loading placeholder elements that mimic the
+# shape and size of content that is being loaded. This provides users with a
+# visual indication of the content's layout before it arrives, reducing
+# perceived loading times and improving user experience.
+#
+# Skeletons can be used in two ways:
+# 1. As standalone shapes with custom dimensions.
+# 2. As a modifier class on existing components to create component-specific
+#    loading states.
+#
+# @loco_example Basic Shapes
+#   = daisy_skeleton(css: "w-24 h-24 rounded-full")
+#   = daisy_skeleton(css: "w-36 h-20")
+#   = daisy_skeleton(css: "w-48 h-5")
+#
+# @loco_example Component Loading States
+#   = daisy_badge(css: "badge-lg skeleton text-slate-400") do
+#     Loading...
+#
+#   = daisy_button(css: "skeleton text-transparent") do
+#     Loading...
+#
+#   = daisy_alert(css: "skeleton")
+#
+#   = daisy_chat do |chat|
+#     - chat.with_avatar(wrapper_css: "skeleton")
+#     - chat.with_bubble(css: "skeleton text-transparent") do
+#       Loading...
+#
+class Daisy::Feedback::SkeletonComponent < LocoMotion::BaseComponent
+  #
+  # Creates a new Skeleton component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the skeleton.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Dimensions: `w-24`, `h-20`
+  #   - Shapes: `rounded-full`, `rounded-lg`
+  #   - Colors: `bg-base-200`
+  #   When using with other components, combine with `text-transparent` to
+  #   hide placeholder text.
+  #
+  def before_render
+    add_css(:component, "skeleton")
+  end
+
+  def call
+    part(:component) { content }
+  end
+end

data/app/components/daisy/feedback/toast_component.rb

@@ -0,0 +1,45 @@
+#
+# The ToastComponent provides a container for displaying non-critical messages
+# to users, typically positioned at the edges of the viewport. Toasts are
+# commonly used for temporary notifications, success messages, or error alerts
+# that don't require immediate user action.
+#
+# @note Currently, this component only handles positioning. JavaScript
+#   functionality for showing/hiding toasts will be implemented in a future
+#   Stimulus ToastController.
+#
+# @loco_example Basic Toast with Alert
+#   = daisy_toast do
+#     = daisy_alert(icon: "check-circle", css: "alert-success text-white") do
+#       Yay! Something went well!
+#
+# @loco_example Multiple Alerts in Toast
+#   = daisy_toast do
+#     = daisy_alert(icon: "check-circle", css: "alert-success text-white") do
+#       Operation successful!
+#
+#     = daisy_alert(icon: "exclamation-circle", css: "alert-error text-white") do
+#       An error occurred.
+#
+class Daisy::Feedback::ToastComponent < LocoMotion::BaseComponent
+  #
+  # Creates a new Toast component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the toast.
+  #
+  # @option kws css [String] Additional CSS classes for styling. By default,
+  #   toasts are positioned in the bottom-right corner of the viewport.
+  #   Common options include:
+  #   - Position modifiers: `toast-top`, `toast-bottom`, `toast-center`,
+  #     `toast-start`, `toast-end`
+  #   - Stack order: `z-50`
+  #
+  def before_render
+    add_css(:component, "toast")
+  end
+
+  def call
+    part(:component) { content }
+  end
+end