loco_motion-rails 0.0.7 → 0.4.0

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

@@ -1,51 +1,81 @@
 #
 # The Modal component renders a modal dialog that can be opened and closed. It
-# includes a backdrop, a close icon, a title, and actions.
+# provides a structured way to display content that requires user attention or
+# interaction, such as forms, confirmations, or detailed information.
 #
-# @part dialog The main `<dialog>` container.
-# @part box The container for the modal content.
-# @part activator The container for the activator which opens the modal.
-# @part close_icon_wrapper The container for the close icon.
-# @part close_icon The default close icon.
-# @part backdrop The backdrop that covers the rest of the screen.
-# @part title Container for the default title for the modal.
-# @part actions Container for all modal actions.
-# @part start_actions Container for the left (start) aligned actions for the modal.
-# @part end_actions The end actions for the modal.
+# 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.
 #
-# @slot activator The activator for the modal.
-# @slot close_icon A custom close icon for the modal.
-# @slot title A custom title for the modal.
-# @slot start_actions Left (or start) aligned actions for the modal.
-# @slot end_actions Right (or end) aligned actions for the modal.
+# @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.
 #
-# @loco_example Basic Usage
+# @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
-#       - onclick = "document.getElementById('#{modal.dialog_id}').showModal()"
-#       = daisy_button(css: 'btn-primary', html: { onclick: onclick }) do
-#         Open Modal
+#       .flex.items-center.gap-2.cursor-pointer
+#         = heroicon_tag "user-circle"
+#         %span View Details
 #
-#     Here is some really long modal content that should go well past the
-#     spot where the close icon appears...
+#     %dl.space-y-2
+#       %dt Name
+#       %dd John Doe
+#       %dt Email
+#       %dd john@example.com
 #
-#     - modal.with_end_actions(css: "flex flex-row items-center gap-2") do
+#     - modal.with_end_actions do
 #       %form{ method: :dialog }
-#         = daisy_button do
-#           Cancel
-#       %form{ action: "", method: :get }
-#         %input{ type: "hidden", name: "submitted", value: "true" }
-#         = daisy_button(css: "btn-primary") do
-#           Submit
+#         = daisy_button { "Close" }
 #
 class Daisy::Actions::ModalComponent < LocoMotion::BaseComponent
   set_component_name :modal
 
-  define_parts :dialog, :box, :actions,
-    :activator, :close_icon_wrapper, :close_icon,
+  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
@@ -63,33 +93,35 @@ class Daisy::Actions::ModalComponent < LocoMotion::BaseComponent
   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.
+  #
+  # @param title [String] The title of the modal. Used in both the modal header
+  #   and the default trigger button.
   #
-  # @param args [Array] Currently unused and passed through to the
-  #   BaseComponent.
   # @param kws [Hash] The keyword arguments for the component.
   #
-  # @option kws dialog_id [String] A specific ID you would like the dialog to
-  #   use. Auto-generates a random ID using `SecureRandom.uuid` if not provided.
-  # @option kws closable [Boolean] Whether or not the modal should allow
-  #   closing.
-  # @option kws title [String] A simple title that you would like the
-  #   component to render above the main content of the modal (see
-  #   {simple_title}).
+  # @option kws title [String] The title of the modal. You can also pass this as
+  #   the first argument.
+  #
+  # @option kws closable [Boolean] If true (default), shows a close icon in the
+  #   top-right corner.
   #
-  def initialize(*args, **kws, &block)
+  # @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 = 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
@@ -100,6 +132,18 @@ class Daisy::Actions::ModalComponent < LocoMotion::BaseComponent
 
   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)
@@ -131,4 +175,9 @@ class Daisy::Actions::ModalComponent < LocoMotion::BaseComponent
   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,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?