loco_motion-rails 0.0.7 → 0.0.8

data/app/components/daisy/actions/swap_component.rb

@@ -1,3 +1,67 @@
+#
+# The Swap component allows toggling between two states, "on" and "off", with an
+# optional indeterminate state. It provides a flexible way to create animated
+# toggles, switches, or any other element that needs to alternate between
+# different visual states. The component supports both simple text/emoji swaps
+# and complex HTML content swaps.
+#
+# It also includes built-in animations that can be enabled through CSS classes
+# like `swap-rotate` or `swap-flip`.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @part checkbox The checkbox input element that handles the toggle state.
+# @part on Wraps the HTML content displayed when the swap is in the "on" state.
+# @part off Wraps the HTML content displayed when the swap is in the "off" state.
+# @part indeterminate Wraps the HTML content displayed when the swap is in an
+#   indeterminate state. Only shown when the checkbox is in an indeterminate
+#   state.
+#
+# @slot on The HTML content to be displayed when the swap is in the "on" state.
+# @slot off The HTML content to be displayed when the swap is in the "off" state.
+# @slot indeterminate The HTML content to be displayed when the swap is in an
+#   indeterminate state.
+#
+# @loco_example Basic Text Swap
+#   = daisy_swap(checked: true, on: "✅ On", off: "❌ Off", css: "swap-rotate")
+#
+# @loco_example Basic Usage with Args
+#   = daisy_swap("✅ On", "❌ Off", true, css: "swap-rotate")
+#
+# @loco_example Icon Swap with Tooltip
+#   = daisy_swap(tip: "Toggle Theme") do |swap|
+#     - swap.with_on do
+#       = heroicon_tag "sun", css: "size-6"
+#     - swap.with_off do
+#       = heroicon_tag "moon", css: "size-6"
+#
+# @loco_example Complex Content with Animation
+#   = daisy_swap(css: "swap-flip") do |swap|
+#     - swap.with_on do
+#       .bg-primary.text-primary-content.p-4.rounded-lg
+#         .font-bold Subscribed
+#         %p You're all set!
+#     - swap.with_off do
+#       .bg-base-200.p-4.rounded-lg
+#         .font-bold Subscribe
+#         %p Click to join
+#
+# @loco_example With Indeterminate State
+#   = daisy_swap(css: "swap-flip", tip: "Task Status") do |swap|
+#     - swap.with_on do
+#       .text-success
+#         = heroicon_tag "check-circle"
+#         %span Complete
+#     - swap.with_off do
+#       .text-error
+#         = heroicon_tag "x-circle"
+#         %span Failed
+#     - swap.with_indeterminate do
+#       .text-warning
+#         = heroicon_tag "clock"
+#         %span Processing
+#
 class Daisy::Actions::SwapComponent < LocoMotion::BaseComponent
   prepend LocoMotion::Concerns::TippableComponent
 
@@ -25,32 +89,77 @@ class Daisy::Actions::SwapComponent < LocoMotion::BaseComponent
   renders_one :off, SwapOff
   renders_one :indeterminate, SwapIndeterminate
 
-  attr_reader :simple_on, :simple_off
+  # @return [String] The value of the `on` option. Usually text or emoji.
+  attr_reader :simple_on
 
-  def initialize(*args, **kwargs, &block)
+  # @return [String] The value of the `off` option. Usually text or emoji.
+  attr_reader :simple_off
+
+  #
+  # Creates a new instance of the SwapComponent.
+  #
+  # @param on [String] Simple text/emoji to display in the "on" state. If provided
+  #   along with `off`, enables simple text swap mode.
+  #
+  # @param off [String] Simple text/emoji to display in the "off" state. If provided
+  #   along with `on`, enables simple text swap mode.
+  #
+  # @param checked [Boolean] Whether the swap should start in the checked ("on")
+  #   state. Defaults to false.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws on [String] Simple text/emoji for the "on" state. Alternative to
+  #   providing it as the first argument.
+  #
+  # @option kws off [String] Simple text/emoji for the "off" state. Alternative to
+  #   providing it as the second argument.
+  #
+  # @option kws checked [Boolean] Whether the swap should start checked. Alternative
+  #   to providing it as the third argument.
+  #
+  # @option kws indeterminate [Boolean] If true, starts the swap in an indeterminate
+  #   state. Requires the indeterminate slot to be meaningful.
+  #
+  def initialize(on = nil, off = nil, checked = nil, **kws, &block)
     super
 
-    @checked = config_option(:checked, false)
-    @simple_on = config_option(:on)
-    @simple_off = config_option(:off)
+    @checked = config_option(:checked, checked || false)
+    @simple_on = config_option(:on, on)
+    @simple_off = config_option(:off, off)
   end
 
+  #
+  # Sets up the component with various CSS classes and HTML attributes.
+  #
   def before_render
     setup_component
     setup_checkbox
     setup_on_off
   end
 
+  private
+
+  #
+  # Sets up the main component structure. The component is rendered as a label
+  # element to allow clicking anywhere on it to toggle the checkbox.
+  #
   def setup_component
     set_tag_name(:component, :label)
     add_css(:component, "swap")
   end
 
+  #
+  # Sets up the checkbox input element that handles the toggle state.
+  #
   def setup_checkbox
     set_tag_name(:checkbox, :input)
     add_html(:checkbox, { type: "checkbox", checked: @checked })
   end
 
+  #
+  # Sets up the CSS classes for the "on" and "off" states.
+  #
   def setup_on_off
     add_css(:on, "swap-on")
     add_css(:off, "swap-off")

data/app/components/daisy/actions/theme_controller_component.html.haml

@@ -1,5 +1,5 @@
 = part(:component) do
-  - SOME_THEMES.map do |theme|
+  - @themes.map do |theme|
     %label.label.cursor-pointer.gap-4
       %span.label-text= theme.titleize
       %input.radio.theme-controller{ name: "theme", type: "radio", value: theme, checked: theme == "light"}

data/app/components/daisy/actions/theme_controller_component.rb

@@ -1,7 +1,42 @@
-# Renders a very basic radio-button theme controller.
+#
+# The Theme Controller component provides a simple interface for switching
+# between different DaisyUI themes. It renders a set of radio buttons that
+# allow users to select from a predefined list of themes.
+#
+# The component is designed to work with DaisyUI's theme system and
+# automatically updates the `data-theme` attribute on the HTML element when
+# a theme is selected.
+#
+# @loco_example Basic Usage
+#   = daisy_theme_controller
+#
+# @loco_example Custom Theme List
+#   = daisy_theme_controller(themes: ["light", "dark", "cyberpunk"])
+#
+# @loco_example With Custom Styling
+#   = daisy_theme_controller(css: "gap-6 p-4 bg-base-200 rounded-lg")
+#
 class Daisy::Actions::ThemeControllerComponent < LocoMotion::BaseComponent
+  # Default list of themes to display in the controller
   SOME_THEMES = ["light", "dark", "synthwave", "retro", "cyberpunk", "wireframe"].freeze
 
+  #
+  # Creates a new instance of the ThemeControllerComponent.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws themes [Array<String>] List of DaisyUI theme names to include
+  #   in the controller. Defaults to {SOME_THEMES}.
+  #
+  def initialize(**kws, &block)
+    super
+
+    @themes = config_option(:themes, SOME_THEMES)
+  end
+
+  #
+  # Sets up the component's CSS classes for proper layout and spacing.
+  #
   def before_render
     add_css(:component, "flex flex-col lg:flex-row gap-4 items-center")
   end

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

@@ -1,8 +1,55 @@
-# The Accordion component shows sections that can be expanded or collapsed.
+#
+# The Accordion component shows collapsible sections of content, with only one
+# section open at a time. Each section has a title that can be clicked to show
+# or hide its content.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @slot section+ Multiple sections that can be expanded or collapsed. Each
+#   section can have a title and content.
+#
+# @loco_example Basic Usage
+#   = daisy_accordion do |accordion|
+#     - accordion.with_section(title: "Section 1") do
+#       This is the content of section 1
+#     - accordion.with_section(title: "Section 2") do
+#       This is the content of section 2
+#
+# @loco_example With Arrow Icons
+#   = daisy_accordion(:arrow) do |accordion|
+#     - accordion.with_section(title: "Section 1") do
+#       This is the content of section 1
+#     - accordion.with_section(title: "Section 2") do
+#       This is the content of section 2
+#
+# @loco_example With Plus Icons
+#   = daisy_accordion(:plus) do |accordion|
+#     - accordion.with_section(title: "Section 1") do
+#       This is the content of section 1
+#     - accordion.with_section(title: "Section 2") do
+#       This is the content of section 2
+#
+# @loco_example With Custom Title Content
+#   = daisy_accordion do |accordion|
+#     - accordion.with_section do |section|
+#       - section.with_title do
+#         .flex.items-center.gap-2
+#           = heroicon_tag "star"
+#           Featured Section
+#       This is the content of the featured section
+#
 class Daisy::DataDisplay::AccordionComponent < LocoMotion::BaseComponent
   prepend LocoMotion::Concerns::TippableComponent
 
   # Renders a single section of the accordion.
+  #
+  # @part radio_button The radio input that controls the section's state.
+  # @part title The title bar that can be clicked to expand/collapse the section.
+  # @part content The container for the section's content.
+  #
+  # @slot title Custom content for the section's title bar.
+  #
   class AccordionSectionComponent < LocoMotion::BasicComponent
     define_parts :radio_button, :title, :content
 
@@ -12,7 +59,23 @@ class Daisy::DataDisplay::AccordionComponent < LocoMotion::BaseComponent
     #   config.
     attr_reader :simple_title
 
-    def initialize(*args, **kws, &block)
+    # Creates a new accordion section.
+    #
+    # @param kws [Hash] The keyword arguments for the component.
+    #
+    # @option kws title [String] The text to display in the section's title bar.
+    #   You can also provide a custom title content using the title slot.
+    #
+    # @option kws value [String] The value for the radio button that controls
+    #   this section. Defaults to a random string.
+    #
+    # @option kws checked [Boolean] Whether this section should start expanded.
+    #   Defaults to false.
+    #
+    # @option kws name [String] The name attribute for the radio button group.
+    #   Usually provided by the parent accordion.
+    #
+    def initialize(**kws, &block)
       super
 
       @value        = config_option(:value)
@@ -73,9 +136,22 @@ class Daisy::DataDisplay::AccordionComponent < LocoMotion::BaseComponent
 
   renders_many :sections, AccordionSectionComponent
 
+  # @return [String] The name attribute for all radio buttons in this accordion.
   attr_reader :name
 
-  def initialize(*args, **kws, &block)
+  #
+  # Creates a new accordion component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws name [String] The name attribute for all radio buttons in this
+  #   accordion. Defaults to a random string.
+  #
+  # @option kws modifier [Symbol] Optional modifier for the accordion's appearance.
+  #   Use `:arrow` to show arrow indicators, or `:plus` to show plus/minus
+  #   indicators.
+  #
+  def initialize(**kws, &block)
     super
 
     @name = config_option(:name, "accordion-#{SecureRandom.uuid}")

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

@@ -1,27 +1,37 @@
-# The Avatar Component displays in image, icon, or placeholder text to represent
-# a user.
+# The Avatar component displays an image, icon, or placeholder text to represent
+# a user or entity. It provides a consistent, circular display with fallback
+# options when an image is not available.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
 #
 # It utilizes the CSS `where()` pseudo-class to reduce the specificity to 0 to
 # allow for easy overriding while giving you some sane defaults.
 #
-# - Width: <code>w-24</code> (can override with w-10, h-10, etc.)
-# - Corners: `rounded-full`
+# @part wrapper The outer container that maintains the avatar's shape and size.
+# @part img The image element when an image source is provided.
+# @part icon The icon element when an icon is specified.
+# @part placeholder The container for placeholder content when no image or icon
+#   is provided.
+#
+# @loco_example Basic Usage with Image
+#   = daisy_avatar(src: "https://example.com/avatar.jpg")
 #
-# If no image is provided, these additional classes will be added so that any
-# text or icons are visible.
+# @loco_example With Icon
+#   = daisy_avatar(icon: "user")
 #
-# - Background: +bg-neutral+
-# - Text Color: `text-neutral-content`
+# @loco_example With Custom Icon Styling
+#   = daisy_avatar(icon: "user", icon_css: "text-yellow-400")
 #
-# ## Examples
+# @loco_example With Placeholder Text
+#   = daisy_avatar do
+#     JD
 #
-# ```language-haml
-# - # Display an avatar with an image
-# = daisy_avatar src: "https://example.com/avatar.jpg"
+# @loco_example With Custom Size
+#   = daisy_avatar(src: "avatar.jpg", css: "w-16 h-16")
 #
-# - # Display an avatar with an icon
-# = daisy_avatar icon: "user", icon_css: "text-yellow-400"
-# ```
+# @loco_example With Tooltip
+#   = daisy_avatar(src: "avatar.jpg", tip: "John Doe")
 #
 class Daisy::DataDisplay::AvatarComponent < LocoMotion::BaseComponent
   prepend LocoMotion::Concerns::TippableComponent
@@ -31,7 +41,17 @@ class Daisy::DataDisplay::AvatarComponent < LocoMotion::BaseComponent
   define_parts :wrapper, :img, :icon, :placeholder
 
   # Create a new avatar component.
-  def initialize(*args, **kws, &block)
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws src [String] URL to the avatar image. If not provided, the
+  #   component will display an icon or placeholder content.
+  #
+  # @option kws icon [String] Name of the Heroicon to display when no image is
+  #   provided. If neither src nor icon is provided, placeholder content from
+  #   the block will be shown.
+  #
+  def initialize(**kws, &block)
     super
 
     @src = config_option(:src)

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

@@ -1,6 +1,28 @@
 #
-# The Badge component renders as a small, rounded element with various
-# background colors.
+# The Badge component renders as a small, rounded element used to display status,
+# labels, or notifications. It supports various background colors and can be used
+# inline with text.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @loco_example Basic Usage
+#   = daisy_badge("New!")
+#
+# @loco_example With Different Colors
+#   = daisy_badge("Primary", css: "badge-primary")
+#   = daisy_badge("Secondary", css: "badge-secondary")
+#   = daisy_badge("Accent", css: "badge-accent")
+#   = daisy_badge("Ghost", css: "badge-ghost")
+#
+# @loco_example With Tooltip
+#   = daisy_badge("Beta", tip: "This feature is in beta testing")
+#
+# @loco_example Using a Block
+#   = daisy_badge do
+#     %span.flex.items-center.gap-1
+#       = heroicon_tag "star", css: "size-4"
+#       Featured
 #
 # @!parse class Daisy::DataDisplay::BadgeComponent < LocoMotion::BaseComponent; end
 class Daisy::DataDisplay::BadgeComponent < LocoMotion::BaseComponent
@@ -11,10 +33,18 @@ class Daisy::DataDisplay::BadgeComponent < LocoMotion::BaseComponent
   #
   # Create a new Badge component.
   #
-  def initialize(*args, **kws, &block)
+  # @param title [String] The text to display in the badge. You can also pass
+  #   the title as a keyword argument or provide content via a block.
+  #
+  # @param kwargs [Hash] The keyword arguments for the component.
+  #
+  # @option kwargs title [String] The text to display in the badge. You can also
+  #   pass the title as the first argument or provide content via a block.
+  #
+  def initialize(title = nil, **kws, &block)
     super
 
-    @title = config_option(:title, args[0])
+    @title = config_option(:title, title)
   end
 
   def before_render
@@ -29,7 +59,7 @@ class Daisy::DataDisplay::BadgeComponent < LocoMotion::BaseComponent
   # additional whitespace gets added to the output.
   #
   def call
-    part(:component) { @title || content }
+    part(:component) { content || @title }
   end
 
   private

data/app/components/daisy/data_display/card_component.html.haml

@@ -1,17 +1,9 @@
 = part(:component) do
-  - if top_figure?
-    = top_figure
-
-  = part(:body) do
-    - if title?
-      = title
-    - elsif @simple_title
-      %h2.card-title= @simple_title
+  = top_figure if top_figure?
 
+  .card-body
+    = title if title?
     = content
+    = actions if actions?
 
-    - if actions?
-      = actions
-
-  - if bottom_figure?
-    = bottom_figure
+  = bottom_figure if bottom_figure?

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

@@ -1,54 +1,89 @@
+#
+# 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
 
-  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
-
   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 @@
+#
+# 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")