loco_motion-rails 0.0.7 → 0.4.0

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+#
+# The TextInput component renders a DaisyUI styled text input field.
+# It can be used standalone or with a form builder, and supports
+# various styling options including different types, sizes and variants.
+#
+# The component provides slots to add content before and after the input field,
+# making it easy to add icons, buttons, or other elements.
+#
+# @part input The actual input element that users can type into.
+#
+# @slot start Content to display before the input field.
+# @slot end+ Content to display after the input field.
+#
+# @loco_example Basic Usage
+#   = daisy_text_input(name: "username", id: "username")
+#
+# @loco_example With Placeholder
+#   = daisy_text_input(name: "email", id: "email", placeholder: "Enter your email")
+#
+# @loco_example Different Types
+#   = daisy_text_input(name: "password", id: "password", type: "password")
+#   = daisy_text_input(name: "email", id: "email", type: "email")
+#
+# @loco_example With Icons
+#   = daisy_text_input(name: "search", placeholder: "Search...") do |text_input|
+#     - text_input.with_start do
+#       = hero_icon("magnifying-glass", size: 5, css: "text-gray-400")
+#
+# @loco_example With Start and End Content
+#   = daisy_text_input(name: "email", placeholder: "Email address") do |text_input|
+#     - text_input.with_start do
+#       = hero_icon("envelope", size: 5, css: "text-gray-400")
+#     - text_input.with_end do
+#       = daisy_button(title: "Verify", css: "h-full rounded-l-none")
+#
+# @loco_example Disabled Text Input
+#   = daisy_text_input(name: "username", id: "username", disabled: true)
+#
+class Daisy::DataInput::TextInputComponent < LocoMotion::BaseComponent
+  define_part :input
+
+  renders_one :start
+  renders_one :end
+
+  attr_reader :name, :id, :value, :placeholder, :type, :disabled, :required, :readonly
+
+  #
+  # Instantiate a new TextInput component.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws name [String] The name attribute for the text input.
+  #
+  # @option kws id [String] The ID attribute for the text input.
+  #
+  # @option kws value [String] The initial value of the text input.
+  #
+  # @option kws placeholder [String] Placeholder text for the text input.
+  #
+  # @option kws type [String] The type of input (text, password, email, etc.).
+  #   Defaults to "text".
+  #
+  # @option kws disabled [Boolean] Whether the text input is disabled. Defaults to
+  #   false.
+  #
+  # @option kws required [Boolean] Whether the text input is required for form
+  #   validation. Defaults to false.
+  #
+  # @option kws readonly [Boolean] Whether the text input is read-only. Defaults to
+  #   false.
+  #
+  def initialize(**kws)
+    super
+
+    @name = config_option(:name)
+    @id = config_option(:id)
+    @value = config_option(:value, nil)
+    @placeholder = config_option(:placeholder, nil)
+    @type = config_option(:type, "text")
+    @disabled = config_option(:disabled, false)
+    @required = config_option(:required, false)
+    @readonly = config_option(:readonly, false)
+  end
+
+  #
+  # Calls the {setup_component} method before rendering the component.
+  #
+  def before_render
+    setup_component
+    setup_input
+  end
+
+  #
+  # Sets up the component by configuring the tag name, CSS classes, and HTML
+  # attributes. Sets the tag to input with appropriate type and adds the 'input'
+  # CSS class.
+  #
+  # This configures various attributes of the text input including name, id, value,
+  # placeholder, type, and states like disabled, required, and readonly.
+  #
+  def setup_component
+    set_tag_name(:component, :label)
+
+    add_css(:component, "input [:where(&)]:flex [:where(&)]:items-center [:where(&)]:gap-2")
+  end
+
+  #
+  # Sets up the input part by configuring the tag name, CSS classes, and HTML
+  # attributes. Sets the tag to input with appropriate type and adds the grow
+  # styling to ensure the input expands to fill available space.
+  #
+  # This configures basic input attributes like name, id, value, placeholder,
+  # and states like disabled, required, and readonly.
+  #
+  def setup_input
+    set_tag_name(:input, :input)
+    add_css(:input, "[:where(&)]:grow")
+    add_html(:input, {
+      type: @type,
+      name: @name,
+      id: @id,
+      value: @value,
+      placeholder: @placeholder,
+      disabled: @disabled,
+      required: @required,
+      readonly: @readonly
+    })
+  end
+
+  # Returns the end section content.
+  #
+  # Since `end` is a reserved word in Ruby, we need to use a different method
+  # name in the template.
+  #
+  def end_content
+    self.end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+#
+# The Toggle component renders a DaisyUI styled toggle switch.
+# It can be used standalone or with a form builder, and provides a visual way
+# to toggle between two states (on/off).
+#
+# @loco_example Basic Usage
+#   = daisy_toggle(name: "notifications", id: "notifications")
+#
+# @loco_example Checked Toggle
+#   = daisy_toggle(name: "notifications", id: "notifications", checked: true)
+#
+# @loco_example Colored Toggle
+#   = daisy_toggle(name: "theme", id: "theme", css: "toggle-primary", checked: true)
+#
+# @loco_example Disabled Toggle
+#   = daisy_toggle(name: "disabled", id: "disabled", disabled: true)
+#
+class Daisy::DataInput::ToggleComponent < Daisy::DataInput::CheckboxComponent
+  #
+  # Instantiate a new Toggle component.
+  #
+  # This component accepts the same options as {Daisy::DataInput::CheckboxComponent},
+  # but always sets `toggle: true` to render the checkbox as a toggle switch.
+  #
+  # @param kws [Hash] The keyword arguments for the component. See
+  #   {Daisy::DataInput::CheckboxComponent#initialize} for available options.
+  #
+  def initialize(**kws)
+    # Always force toggle to be true
+    kws[:toggle] = true
+
+    super(**kws)
+  end
+end

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,20 +1,56 @@
 #
-# A component that displays a tooltip when the user hovers over it.
+# The TooltipComponent displays informative text when users hover over an
+# element. It can be used in two ways:
+# 1. As a wrapper component around any HTML content.
+# 2. Through the TippableComponent concern, which many components include.
+#
+# This component is also aliased as `daisy_tip` for convenience.
 #
 # @loco_example Basic Usage
-#   = daisy_tooltip "This is a tooltip" do
-#     %span Hover over me
+#   = daisy_tip "Helpful information" do
+#     %span Need help?
+#
+#   = daisy_tip "Delete this item", css: "tooltip-error" do
+#     = hero_icon("trash", css: "size-5 text-error")
+#
+# @loco_example Positioned Tips
+#   = daisy_tip "Opens settings menu", css: "tooltip-left" do
+#     = daisy_button(title: "Settings", icon: "cog-6-tooth")
+#
+#   = daisy_tip "View user profile", css: "tooltip-bottom tooltip-info" do
+#     = daisy_avatar(src: image_path("avatars/user.jpg"))
+#
+# @loco_example Component Integration
+#   = daisy_button(title: "Save Changes",
+#     css: "btn-primary",
+#     tip: "Save your current progress")
+#
+#   = daisy_chat do |chat|
+#     - chat.with_avatar(css: "tooltip-left tooltip-info",
+#       tip: "Online",
+#       src: image_path("avatars/user.jpg"))
+#     - chat.with_bubble do
+#       Hello!
 #
 class Daisy::Feedback::TooltipComponent < LocoMotion::BaseComponent
 
   #
-  # Create a new instance of the Tooltip.
+  # Creates a new Tooltip component.
+  #
+  # @param args [Array] If provided, the first argument is used as the `tip`
+  #   text.
+  # @param kws  [Hash]  Keyword arguments for customizing the tooltip.
   #
-  # @param args [Array] If provided, the first argument is considered the `tip`.
-  # @param kws [Hash] The keyword arguments for the component.
+  # @option kws tip [String] The text to display in the tooltip. Can be
+  #   passed as the first positional argument or as a keyword argument.
   #
-  # @option kws tip [String] The text to display in the tooltip. Can be passed
-  #   as the first positional argument, or as a keyword argument.
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Position modifiers: `tooltip-top`, `tooltip-bottom`,
+  #     `tooltip-left`, `tooltip-right`
+  #   - Colors: `tooltip-primary`, `tooltip-secondary`, `tooltip-accent`,
+  #     `tooltip-info`, `tooltip-success`, `tooltip-warning`, `tooltip-error`
+  #   - Open state: `tooltip-open`
   #
   def initialize(*args, **kws, &block)
     super
@@ -24,7 +60,7 @@ class Daisy::Feedback::TooltipComponent < LocoMotion::BaseComponent
   end
 
   #
-  # Sets up the components CSS and HTML attributes.
+  # Sets up the component's CSS and HTML attributes.
   #
   def before_render
     add_css(:component, "tooltip")
@@ -32,7 +68,7 @@ class Daisy::Feedback::TooltipComponent < LocoMotion::BaseComponent
   end
 
   #
-  # Renders the component and it's content (inline).
+  # Renders the component and its content (inline).
   #
   def call
     part(:component) { content }

data/app/components/daisy/layout/artboard_component.rb

@@ -1,9 +1,57 @@
+#
+# The ArtboardComponent provides a fixed-size container that mimics mobile
+# device screens. It's particularly useful for:
+# - Prototyping mobile interfaces.
+# - Displaying responsive design examples.
+# - Creating device-specific mockups.
+#
+# The component includes preset sizes for common mobile devices and supports
+# both portrait and landscape orientations.
+#
+# @loco_example Portrait Mode
+#   = daisy_artboard(css: "phone-4") do
+#     = daisy_hero do
+#       iPhone 13 (375×812)
+#
+# @loco_example Landscape Mode
+#   = daisy_artboard(css: "phone-4 artboard-horizontal") do
+#     = daisy_hero do
+#       iPhone 13 (812×375)
+#
+# @loco_example Custom Demo Style
+#   = daisy_artboard(css: "phone-1 artboard-demo") do
+#     iPhone SE (320×568)
+#
 class Daisy::Layout::ArtboardComponent < LocoMotion::BaseComponent
 
+  #
+  # Creates a new Artboard component.
+  #
+  # @param args [Array] Positional arguments passed to the parent class.
+  # @param kws  [Hash]  Keyword arguments for customizing the artboard.
+  #
+  # @option kws css [String] Additional CSS classes for styling. Common
+  #   options include:
+  #   - Device sizes: `phone-1` (320×568), `phone-2` (375×667),
+  #     `phone-3` (414×736), `phone-4` (375×812), `phone-5` (414×896),
+  #     `phone-6` (320×1024)
+  #   - Orientation: `artboard-horizontal` for landscape mode
+  #   - Demo style: `artboard-demo` for visible borders and background
+  #
+  def initialize(*args, **kws, &block)
+    super
+  end
+
+  #
+  # Sets up the component's CSS classes.
+  #
   def before_render
     add_css(:component, "artboard")
   end
 
+  #
+  # Renders the component and its content.
+  #
   def call
     part(:component) { content }
   end