loco_motion-rails 0.0.6 → 0.0.8

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

@@ -1,14 +1,81 @@
-# This is a Modal component.
-# @!parse class Daisy::Actions::ModalComponent < LocoMotion::BaseComponent; end
-class Daisy::Actions::ModalComponent < LocoMotion.configuration.base_component_class
+#
+# The Modal component renders a modal dialog that can be opened and closed. It
+# provides a structured way to display content that requires user attention or
+# interaction, such as forms, confirmations, or detailed information.
+#
+# Note that the modal uses the HTML `<dialog>` element and its native methods
+# (`showModal()` and `close()`). This provides better accessibility and keyboard
+# navigation compared to div-based modals.
+#
+# @part dialog The main `<dialog>` container that wraps the modal content.
+# @part box The container for the modal content, providing padding and layout.
+# @part close_icon_wrapper The container for the close icon, positioned in the
+#   top-right corner.
+# @part close_icon The default close icon button.
+# @part backdrop The semi-transparent backdrop that covers and dims the main
+# content.
+# @part title Container for the modal title, styled for prominence.
+# @part actions Container for all modal action buttons.
+# @part start_actions Container for left (start) aligned action buttons.
+# @part end_actions Container for right (end) aligned action buttons.
+#
+# @slot activator A custom element that opens the modal. Automatically adds
+#   `role="button"` and `tabindex="0"` attributes for accessibility.
+# @slot button The button that opens the modal. Defaults to a standard Daisy
+#   button with the modal's title.
+# @slot close_icon A custom close button to replace the default 'X' icon.
+# @slot title Custom title content, replacing the default text title.
+# @slot start_actions Left (start) aligned buttons, typically for secondary actions
+#   like "Cancel".
+# @slot end_actions Right (end) aligned buttons, typically for primary actions
+#   like "Submit" or "Save".
+#
+# @loco_example Basic Modal
+#   = daisy_modal(title: "Simple Modal") do |modal|
+#     - modal.with_button(css: "btn-primary") { "Open Modal" }
+#     %p This is a basic modal with some content.
+#     - modal.with_end_actions do
+#       %form{ method: :dialog }
+#         = daisy_button { "Close" }
+#
+# @loco_example Form Modal
+#   = daisy_modal(title: "Edit Profile") do |modal|
+#     - modal.with_button { "Edit Profile" }
+#     = form_with(model: @user) do |f|
+#       .space-y-4
+#         = f.text_field :name, class: "input input-bordered w-full"
+#         = f.email_field :email, class: "input input-bordered w-full"
+#     - modal.with_start_actions do
+#       %form{ method: :dialog }
+#         = daisy_button { "Cancel" }
+#     - modal.with_end_actions do
+#       = daisy_button(css: "btn-primary", type: "submit") { "Save Changes" }
+#
+# @loco_example Custom Activator
+#   = daisy_modal(title: "User Details") do |modal|
+#     - modal.with_activator do
+#       .flex.items-center.gap-2.cursor-pointer
+#         = heroicon_tag "user-circle"
+#         %span View Details
+#
+#     %dl.space-y-2
+#       %dt Name
+#       %dd John Doe
+#       %dt Email
+#       %dd john@example.com
+#
+#     - modal.with_end_actions do
+#       %form{ method: :dialog }
+#         = daisy_button { "Close" }
+#
+class Daisy::Actions::ModalComponent < LocoMotion::BaseComponent
   set_component_name :modal
 
-  define_parts :dialog, :box, :actions,
-    :activator, :close_icon_wrapper, :close_icon,
-    :backdrop,
-    :title, :start_actions, :end_actions
+  define_parts :dialog, :box, :actions, :close_icon_wrapper, :close_icon,
+    :backdrop, :title, :start_actions, :end_actions
 
-  renders_one :activator
+  renders_one :activator, LocoMotion::BasicComponent.build(html: { role: "button", tabindex: 0 })
+  renders_one :button, Daisy::Actions::ButtonComponent
   renders_one :close_icon
   renders_one :title
   renders_one :start_actions
@@ -26,28 +93,35 @@ class Daisy::Actions::ModalComponent < LocoMotion.configuration.base_component_c
   attr_reader :simple_title
 
   #
-  # Instantiate a new Modal component. All options are expected to be passed as
-  # keyword arguments.
+  # Creates a new instance of the ModalComponent.
   #
-  # @overload initialize(dialog_id: nil, closable: true, title: nil)
-  #   @param dialog_id [String] A specific ID you would like the dialog to use.
-  #     Auto-generates a random ID using `SecureRandom.uuid` if not provided.
+  # @param title [String] The title of the modal. Used in both the modal header
+  #   and the default trigger button.
   #
-  #   @param closable [Boolean] Whether or not the modal should allow closing.
+  # @param kws [Hash] The keyword arguments for the component.
   #
-  #   @param title [String] A simple title that you would like the component to
-  #     render above the main content of the modal. Accessible through the
-  #     {simple_title} accessor.
+  # @option kws title [String] The title of the modal. You can also pass this as
+  #   the first argument.
   #
-  def initialize(*args, **kws, &block)
+  # @option kws closable [Boolean] If true (default), shows a close icon in the
+  #   top-right corner.
+  #
+  # @option kws dialog_id [String] A custom ID for the dialog element. If not
+  #   provided, a unique ID will be generated.
+  #
+  def initialize(title = nil, **kws, &block)
     super
 
-    @dialog_id ||= SecureRandom.uuid
+    @dialog_id = config_option(:dialog_id, SecureRandom.uuid)
     @closable = config_option(:closable, true)
-    @simple_title = config_option(:title)
+    @simple_title = config_option(:title, title)
   end
 
+  #
+  # Sets up the component with various CSS classes and HTML attributes.
+  #
   def before_render
+    setup_activator_or_button
     setup_component
     setup_backdrop
     setup_box
@@ -58,6 +132,18 @@ class Daisy::Actions::ModalComponent < LocoMotion.configuration.base_component_c
 
   private
 
+  def setup_activator_or_button
+    onclick = "document.getElementById('#{dialog_id}').showModal()"
+
+    element = if activator?
+      activator
+    else
+      button || default_button
+    end
+
+    element.add_html(:component, { onclick: onclick })
+  end
+
   def setup_component
     set_tag_name(:component, :dialog)
     add_html(:component, id: dialog_id)
@@ -89,4 +175,9 @@ class Daisy::Actions::ModalComponent < LocoMotion.configuration.base_component_c
   def setup_actions
     add_css(:actions, "mt-2 flex flex-row items-center justify-between")
   end
+
+  # Provide a default button if no button is supplied.
+  def default_button
+    with_button(simple_title)
+  end
 end

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

@@ -1,4 +1,70 @@
-class Daisy::Actions::SwapComponent < LocoMotion.configuration.base_component_class
+#
+# 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
+
   class SwapOn < LocoMotion::BasicComponent
     def before_render
       add_css(:component, "swap-on")
@@ -23,32 +89,77 @@ class Daisy::Actions::SwapComponent < LocoMotion.configuration.base_component_cl
   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
+
+  # @return [String] The value of the `off` option. Usually text or emoji.
+  attr_reader :simple_off
 
-  def initialize(*args, **kwargs, &block)
+  #
+  # 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.
-class Daisy::Actions::ThemeControllerComponent < LocoMotion.configuration.base_component_class
+#
+# 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,7 +1,55 @@
-# The Accordion component shows sections that can be expanded or collapsed.
-class Daisy::DataDisplay::AccordionComponent < LocoMotion.configuration.base_component_class
+#
+# 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
 
@@ -11,7 +59,23 @@ class Daisy::DataDisplay::AccordionComponent < LocoMotion.configuration.base_com
     #   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)
@@ -72,9 +136,22 @@ class Daisy::DataDisplay::AccordionComponent < LocoMotion.configuration.base_com
 
   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,35 +1,57 @@
-# 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.configuration.base_component_class
+class Daisy::DataDisplay::AvatarComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
   set_component_name :avatar
 
   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,27 +1,71 @@
 #
-# 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.configuration.base_component_class
+class Daisy::DataDisplay::BadgeComponent < LocoMotion::BaseComponent
+  prepend LocoMotion::Concerns::TippableComponent
+
   set_component_name :badge
 
   #
   # 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
 
-    set_tag_name(:component, :span)
+    @title = config_option(:title, title)
   end
 
   def before_render
     setup_component
   end
 
+  #
+  # Renders the badge component.
+  #
+  # Because this is an inline component which might be utlized alongside text,
+  # we utilize the `call` method instead of a template to ensure that no
+  # additional whitespace gets added to the output.
+  #
+  def call
+    part(:component) { content || @title }
+  end
+
   private
 
   def setup_component
+    set_tag_name(:component, :span)
     add_css(:component, "badge")
   end
 end

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?