loco_motion-rails 0.0.7 → 0.4.0

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
 

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

@@ -1,3 +1,27 @@
+#
+# 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")
@@ -6,7 +30,21 @@ class Daisy::DataDisplay::TimelineEventComponent < LocoMotion::BaseComponent
   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/data_input/checkbox_component.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+#
+# The Checkbox component renders a DaisyUI styled checkbox input.
+# It can be used standalone or with a form builder, and supports various styling
+# options including toggle mode for switch-like appearance.
+#
+# @loco_example Basic Usage
+#   = daisy_checkbox(name: "accept", id: "accept")
+#
+# @loco_example Checked Checkbox
+#   = daisy_checkbox(name: "accept", id: "accept", checked: true)
+#
+# @loco_example Toggle Checkbox
+#   = daisy_checkbox(name: "accept", id: "accept", toggle: true)
+#
+# @loco_example Disabled Checkbox
+#   = daisy_checkbox(name: "accept", id: "accept", disabled: true)
+#
+class Daisy::DataInput::CheckboxComponent < LocoMotion::BaseComponent
+  attr_reader :name, :id, :value, :checked, :toggle, :disabled, :required
+
+  #
+  # Instantiate a new Checkbox component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws name [String] The name attribute for the checkbox input.
+  #
+  # @option kws id [String] The ID attribute for the checkbox input.
+  #
+  # @option kws value [String] The value attribute for the checkbox input.
+  #   Defaults to "1".
+  #
+  # @option kws checked [Boolean] Whether the checkbox is checked. Defaults to
+  #   false.
+  #
+  # @option kws toggle [Boolean] Whether the checkbox should be styled as a
+  #   toggle switch. Defaults to false.
+  #
+  # @option kws disabled [Boolean] Whether the checkbox is disabled. Defaults to
+  #   false.
+  #
+  # @option kws required [Boolean] Whether the checkbox is required for form
+  #   validation. Defaults to false.
+  #
+  def initialize(**kws)
+    super
+
+    @name = config_option(:name)
+    @id = config_option(:id)
+    @value = config_option(:value, "1")
+    @checked = config_option(:checked, false)
+    @toggle = config_option(:toggle, false)
+    @disabled = config_option(:disabled, false)
+    @required = config_option(:required, false)
+  end
+
+  #
+  # Calls the {setup_component} method before rendering the component.
+  #
+  def before_render
+    setup_component
+  end
+
+  #
+  # Sets up the component by configuring the tag name, CSS classes, and HTML
+  # attributes.
+  #
+  def setup_component
+    set_tag_name(:component, :input)
+
+    add_css(:component, @toggle ? "toggle" : "checkbox")
+
+    add_html(:component, {
+      type: "checkbox",
+      name: @name,
+      id: @id,
+      value: @value,
+      checked: @checked,
+      disabled: @disabled,
+      required: @required
+    })
+  end
+
+  #
+  # Renders the component inline with no additional whitespace.
+  #
+  def call
+    part(:component)
+  end
+end

data/app/components/daisy/data_input/file_input_component.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+#
+# The FileInput component renders a DaisyUI styled file input.
+# It can be used standalone or with a form builder, and supports
+# various styling options including different sizes and variants.
+#
+# @loco_example Basic Usage
+#   = daisy_file_input(name: "document", id: "document")
+#
+# @loco_example With Accept Attribute
+#   = daisy_file_input(name: "image", id: "image", accept: "image/*")
+#
+# @loco_example With Multiple Files
+#   = daisy_file_input(name: "documents[]", id: "documents", multiple: true)
+#
+# @loco_example Disabled File Input
+#   = daisy_file_input(name: "document", id: "document", disabled: true)
+#
+class Daisy::DataInput::FileInputComponent < LocoMotion::BaseComponent
+  attr_reader :name, :id, :accept, :multiple, :disabled, :required
+
+  #
+  # Instantiate a new FileInput component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws name [String] The name attribute for the file input.
+  #
+  # @option kws id [String] The ID attribute for the file input.
+  #
+  # @option kws accept [String] The accept attribute for the file input,
+  #   specifying allowed file types.
+  #
+  # @option kws multiple [Boolean] Whether the file input allows multiple file
+  #   selection. Defaults to false.
+  #
+  # @option kws disabled [Boolean] Whether the file input is disabled. Defaults to
+  #   false.
+  #
+  # @option kws required [Boolean] Whether the file input is required for form
+  #   validation. Defaults to false.
+  #
+  def initialize(**kws)
+    super
+
+    @name = config_option(:name)
+    @id = config_option(:id)
+    @accept = config_option(:accept, nil)
+    @multiple = config_option(:multiple, false)
+    @disabled = config_option(:disabled, false)
+    @required = config_option(:required, false)
+  end
+
+  #
+  # Calls the {setup_component} method before rendering the component.
+  #
+  def before_render
+    setup_component
+  end
+
+  #
+  # Sets up the component by configuring the tag name, CSS classes, and HTML
+  # attributes. Sets the tag to input with type 'file' and adds the 'file-input'
+  # CSS class.
+  #
+  # This configures the name, id, accept attribute, multiple state, disabled state,
+  # and required state of the file input.
+  #
+  def setup_component
+    set_tag_name(:component, :input)
+
+    add_css(:component, "file-input")
+
+    add_html(:component, {
+      type: "file",
+      name: @name,
+      id: @id,
+      accept: @accept,
+      multiple: @multiple,
+      disabled: @disabled,
+      required: @required
+    })
+  end
+
+  #
+  # Renders the component inline with no additional whitespace.
+  #
+  def call
+    part(:component)
+  end
+end

data/app/components/daisy/data_input/label_component.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+#
+# The Label component renders a DaisyUI styled label for form inputs.
+# It can be used with any form input component and provides visual styling
+# consistent with other Daisy UI elements.
+#
+# @loco_example Basic Usage
+#   = daisy_label(for: "input_id") do
+#     My Label
+#
+# @loco_example With Label Title
+#   = daisy_label(for: "input_id", title: "My Label")
+#
+# @loco_example Required Label
+#   = daisy_label(for: "input_id", required: true) do
+#     My Required Label
+#
+class Daisy::DataInput::LabelComponent < LocoMotion::BaseComponent
+  attr_reader :for, :title, :required
+
+  #
+  # Instantiate a new Label component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws for [String] The ID of the input element this label is for.
+  #   This connects the label to its associated form control for accessibility.
+  #
+  # @option kws title [String] The text content of the label. If not provided,
+  #   the content block will be used. If a content block is provided, it will
+  #   take precedence over the title option.
+  #
+  # @option kws required [Boolean] Whether the label is for a required input.
+  #   Defaults to false.
+  #
+  def initialize(**kws)
+    super
+
+    @for = config_option(:for)
+    @title = config_option(:title)
+    @required = config_option(:required, false)
+  end
+
+  #
+  # Calls the {setup_component} method before rendering the component.
+  #
+  def before_render
+    setup_component
+  end
+
+  #
+  # Sets up the component by configuring the tag name, CSS classes, and HTML
+  # attributes. Sets the tag to 'label' and adds the 'label' CSS class.
+  #
+  # This configures the 'for' attribute to connect the label to its input and
+  # adds appropriate styling for required inputs when needed.
+  #
+  def setup_component
+    set_tag_name(:component, :label)
+
+    add_css(:component, "label")
+
+    add_html(:component, {
+      for: @for
+    })
+  end
+
+  #
+  # Renders the component with its content.
+  #
+  def call
+    part(:component) do
+      if content?
+        content
+      elsif @title
+        content_tag(:span, @title, class: "label-text")
+      else
+        # Fallback to empty content
+        ""
+      end
+    end
+  end
+end

data/app/components/daisy/data_input/radio_button_component.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+#
+# The Radio Button component renders a DaisyUI styled radio button input.
+# It can be used standalone or with a form builder, and is ideal for creating
+# option groups where users must select exactly one choice.
+#
+# @loco_example Basic Usage
+#   = daisy_radio(name: "option", id: "option1", value: "1")
+#
+# @loco_example Checked Radio Button
+#   = daisy_radio(name: "option", id: "option2", value: "2", checked: true)
+#
+# @loco_example Disabled Radio Button
+#   = daisy_radio(name: "option", id: "option3", value: "3", disabled: true)
+#
+class Daisy::DataInput::RadioButtonComponent < LocoMotion::BaseComponent
+  attr_reader :name, :id, :value, :checked, :disabled, :required
+
+  #
+  # Instantiate a new Radio Button component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws name [String] The name attribute for the radio button input.
+  #
+  # @option kws id [String] The ID attribute for the radio button input.
+  #
+  # @option kws value [String] The value attribute for the radio button input.
+  #
+  # @option kws checked [Boolean] Whether the radio button is checked. Defaults to
+  #   false.
+  #
+  # @option kws disabled [Boolean] Whether the radio button is disabled. Defaults to
+  #   false.
+  #
+  # @option kws required [Boolean] Whether the radio button is required for form
+  #   validation. Defaults to false.
+  #
+  def initialize(**kws)
+    super
+
+    @name = config_option(:name)
+    @id = config_option(:id)
+    @value = config_option(:value)
+    @checked = config_option(:checked, false)
+    @disabled = config_option(:disabled, false)
+    @required = config_option(:required, false)
+  end
+
+  #
+  # Calls the {setup_component} method before rendering the component.
+  #
+  def before_render
+    setup_component
+  end
+
+  #
+  # Sets up the component by configuring the tag name, CSS classes, and HTML
+  # attributes. Sets the tag to input with type 'radio' and adds the 'radio' CSS class.
+  #
+  # This configures the name, id, value, disabled state, required state, and
+  # checked state of the radio button.
+  #
+  def setup_component
+    set_tag_name(:component, :input)
+
+    add_css(:component, "radio")
+
+    add_html(:component, {
+      type: "radio",
+      name: @name,
+      id: @id,
+      value: @value,
+      checked: @checked,
+      disabled: @disabled,
+      required: @required
+    })
+  end
+
+  #
+  # Renders the component inline with no additional whitespace.
+  #
+  def call
+    part(:component)
+  end
+end