loco_motion-rails 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a020015ecb6d9ee0a705d25830f1951b00c60be6ee4046939b878d3a720bfbda
-  data.tar.gz: c9bc31844a168d4427423912be65f354387aba43f2c6d6711998cee947e2311d
+  metadata.gz: 7d4d1891389f5b0a860f930a6d4e6dbb9053b6a77e349cd0f43b9de22740482b
+  data.tar.gz: 2f99a232731636bfaeca166092c0fb4ca51ddae6300e420951d0c0791997e1d7
 SHA512:
-  metadata.gz: f88796625ae5f6f7c7690563d0a687ed2d8932924d305cb12da0985fdcfdb00f629e6a25618afe5498ec6932af0e8c45b1cc3008a9f68d28940563f9f41f1fb0
-  data.tar.gz: 5f09dacd5dab790708428cb3e853e40fa59a5d20da58b4d11f9e99cca76bf940b1d3d311e55e8396b140acb2271eddb3df202175164ba59306acc041427d65cd
+  metadata.gz: ad963fe072e997ad83879704d8a5d9285f2e964371ee9c7418dfe7377db7950b09f43e3ff8555fad25aee3d141b7b6927ba5e70f965684d749057aaa1d6223c8
+  data.tar.gz: 367ecb0bf6b3b9d3ff77e6f596b12322fe1b1026bcecc619032c70e59ed94d344f3b18907e8dc8caf63b4d95343e351a808254b50da0db14c8a98b8282cb5a18

data/README.md

@@ -33,11 +33,13 @@ your solution is aligned with our goals.
 - [About](#about)
 - [Getting Started](#getting-started)
 - [Installing / Setting up Rails](#installing--setting-up-rails)
+  - [Using UUIDs by Default](#using-uuids-by-default)
   - [Install HAML (Optional)](#install-haml-optional)
   - [Install DaisyUI (Optional)](#install-daisyui-optional)
   - [Try Out Your Application](#try-out-your-application)
 - [Debugging](#debugging)
 - [Testing](#testing)
+- [Services / Service Objects](#services--service-objects)
 - [Authentication](#authentication)
 - [Web Console](#web-console)
 - [BetterErrors (Optional)](#bettererrors-optional)
@@ -203,6 +205,20 @@ Congratulations!
 You can now visit [http://localhost:3000](http://localhost:3000) in your web
 browser and see your running Rails application!
 
+### Using UUIDs by Default
+
+We believe strongly in migrating all of your primary keys to UUIDs to increase
+security as well as avoiding potential scaling issues in the future.
+
+To enable this by default, create the following file:
+
+```ruby
+# config/initializers/generators.rb
+Rails.application.config.generators do |generator|
+  generator.orm :active_record, primary_key_type: :uuid
+end
+```
+
 ### Install HAML (Optional)
 
 While you can use the default ERB templating system that comes with Rails, we
@@ -479,6 +495,28 @@ We'll have some guides and examples for this coming soon!
 > We plan to have a writeup soon (an ADR specifically) on exactly why we made
 > the switch.
 
+## Services / Service Objects
+
+It is best practice to separate your logic into Service Objects rather than
+shoving all of it into your Controllers and Models.
+
+One solution we really like is
+[ActiveInteraction](https://github.com/AaronLasseigne/active_interaction).
+
+It is very stable, has wonderful documentation, and gives you a clean way to
+build your service objects with support for things like composed interactions
+and even ActiveModel validations.
+
+Add `gem 'active_interaction', '~> 5.3'` to your `Gemfile` and create a new
+class called `ApplicationInteraction` if you want to give it a try!
+
+```
+# app/interactions/application_interaction.rb
+class ApplicationInteraction < ActiveInteraction::Base
+  # Your interactions will inherit from this class!
+end
+```
+
 ## Authentication
 
 There are a **lot** of different ways to handle user authentication in Ruby on
@@ -884,7 +922,7 @@ the GitHub Discussions feature and let us know!
 - [ ] Basic versions of DaisyUI Data Input
 - [ ] Basic versions of DaisyUI Layout
 - [ ] Basic versions of DaisyUI Mockup
-- [ ] ~~Get YARD docs rendering with (better) Markdown~~ _**Working for now**_
+- [x] ~~Get YARD docs rendering with (better) Markdown~~ _**Working for now**_
 - [x] Extract relevant pieces into a yard-loco_motion plugin
 - [x] Publish Gem
 - [x] Publish NPM package
@@ -902,6 +940,12 @@ the GitHub Discussions feature and let us know!
 - [ ] Build some have docs / guides / examples for using playwright-ruby-client
 - [x] See if we can build a `Tippable` concern that relevant components can
       include to automatically add the tooltip param and classes where possible
+- [x] Rename `tail` methods to `end` since we use that in other places
+- [x] Update CardComponent Figure to be a proper class like other components
+- [x] Create a GitHub pull request template to standardize PR submissions
+- [ ] See if we can update the Join component to auto-add the `join-item` CSS
+      under certain conditions
+- [ ] Add title and description content_for blocks to all examples for SEO purposes
 
 [1]: https://loco-motion.profoundry.us/
 [2]: https://loco-motion-demo-staging.profoundry.us/

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

@@ -1,12 +1,97 @@
-# Here are the Button docs!
+#
+# The Button component can be used to render HTML `<button>` or `<a>` elements
+# that are styled to look like a clickable element.
+#
+# Note that we do **not** use component parts for the icons since we're calling
+# `heroicon_tag` within the component. But we **do** provide custom CSS & HTML
+# options to allow overriding / customization.
+#
+# Includes the {LocoMotion::Concerns::TippableComponent} module to enable easy
+# tooltip addition.
+#
+# @loco_example Basic Usage
+#   = daisy_button("Click Me")
+#
+#   = daisy_button do
+#     Click Me Too
+#
+#   = daisy_button(icon: "heart", tip: "Love")
+#
+#   = daisy_button(title: "Button with Two Icons", left_icon: "heart", right_icon: "plus")
+#
 class Daisy::Actions::ButtonComponent < LocoMotion::BaseComponent
   prepend LocoMotion::Concerns::TippableComponent
 
-  set_component_name :btn
-
-  def initialize(*args, **kws, &block)
+  #
+  # Instantiate a new Button component.
+  #
+  # @param title  [String] The title of the button. Defaults to "Submit" if none
+  #   of title, left icon, or right icon is provided. Will be considered the
+  #   `action` parameter if **both** the title and a block are provided.
+  #
+  # @param action [String] The Stimulus action that should fire when the button
+  #   is clicked.
+  #
+  # @param kws    [Hash] The keyword arguments for the component.
+  #
+  # @option kws title           [String] The title of the button. You can also
+  #   pass the title, icons, or any other HTML content as a block.
+  #
+  # @option kws action          [String] The Stimulus action that should fire
+  #   when the button is clicked.
+  #
+  #   > **Note:** _You should use either the `action` or the `href` option, but
+  #   not both._
+  #
+  # @option kws href            [String] A path or URL to which the user will be
+  #   directed when the button is clicked. Forces the Button to use an `<a>`
+  #   tag.
+  #
+  #   > **Note:** _You should use either the `action` or the `href` option, but
+  #   not both._
+  #
+  # @option kws target          [String] The HTML `target` of for the `<a>` tag
+  #   (`_blank`, `_parent`, or a specific tab / window / iframe, etc).
+  #
+  # @option kws icon            [String] The name of Hero icon to render inside
+  #   the button.  This is an alias of `left_icon`.
+  #
+  # @option kws icon_css        [String] The CSS classes to apply to the icon.
+  #   This is an alias of `left_icon_css`.
+  #
+  # @option kws icon_html       [Hash] Additional HTML attributes to apply to
+  #   the icon. This is an alias of `left_icon_html`.
+  #
+  # @option kws left_icon       [String] The name of Hero icon to render inside
+  #   the button to the left of the text.
+  #
+  # @option kws left_icon_css   [String] The CSS classes to apply to the left
+  #   icon.
+  #
+  # @option kws left_icon_html  [Hash] Additional HTML attributes to apply to
+  #   the left icon.
+  #
+  # @option kws right_icon      [String] The name of Hero icon to render inside
+  #   the button to the right of the text.
+  #
+  # @option kws right_icon_css  [String] The CSS classes to apply to the right
+  #   icon.
+  #
+  # @option kws right_icon_html [Hash] Additional HTML attributes to apply to
+  #   the right icon.
+  #
+  def initialize(title = nil, action = nil, **kws, &block)
     super
 
+    # If both a title and a block are provided, assume the title is the action
+    action = title if title && block_given?
+
+    # Force the title to be nil if a block is given so we don't accidentally
+    # render two titles
+    title = nil if block_given?
+
+    @action = config_option(:action, action)
+
     @href = config_option(:href)
     @target = config_option(:target)
 
@@ -23,15 +108,21 @@ class Daisy::Actions::ButtonComponent < LocoMotion::BaseComponent
     @right_icon_html = config_option(:right_icon_html, @icon_html)
 
     default_title = @left_icon || @right_icon ? nil : "Submit"
-    @simple_title = config_option(:title, args[0] || default_title)
+    @simple_title = config_option(:title, title || default_title)
   end
 
+  #
+  # Calls the {setup_component} method before rendering the component.
+  #
   def before_render
     setup_component
   end
 
-  private
-
+  #
+  # Sets the tagname to `<a>` if an `href` is provided, otherwise sets it to
+  # `<button>`. Adds the `btn` CSS class to the component. Also adds
+  # `items-center` and `gap-2` CSS classes if an icon is present.
+  #
   def setup_component
     if @href
       set_tag_name(:component, :a)
@@ -42,13 +133,23 @@ class Daisy::Actions::ButtonComponent < LocoMotion::BaseComponent
 
     add_css(:component, "btn")
 
-    add_css(:component, "items-center gap-2") if @icon
+    if @icon || @left_icon || @right_icon
+      add_css(:component, "[:where(&)]:items-center [:where(&)]:gap-2")
+    end
+
+      add_html(:component, { "data-action": @action }) if @action
   end
 
+  #
+  # Returns the HTML attributes for the left icon.
+  #
   def left_icon_html
     { class: @left_icon_css }.merge(@left_icon_html)
   end
 
+  #
+  # Returns the HTML attributes for the right icon.
+  #
   def right_icon_html
     { class: @right_icon_css }.merge(@right_icon_html)
   end

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

@@ -1,13 +1,13 @@
 = part(:component) do
-  - if title?
-    = title
+  - if activator?
+    = activator
   - else
-    = part(:title) do
-      = @simple_title
+    = button
 
   - if items.any?
     = part(:menu) do
       - items.each do |item|
-        = item
+        = part(:menu_item) do
+          = item
   - else
     = content

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

@@ -1,48 +1,117 @@
-# Here are the Button docs!
+#
+# The Dropdown component shows a Button, or any other component you wish, with a
+# hovering menu that opens on click (or hover). It provides a flexible way to
+# create dropdown menus with customizable triggers and content.
+#
+# Note that the dropdown uses slots for both the activator and menu items,
+# allowing for maximum flexibility in how the dropdown is triggered and what
+# content it displays.
+#
+# @part menu The default / styled menu rendered by the dropdown. Contains all
+#   menu items and provides the dropdown's positioning and animation.
+# @part menu_item The styles for every item in the dropdown. Provides consistent
+#   spacing and hover states.
+#
+# @slot button The button that triggers the dropdown. This is the default trigger
+#   and is styled automatically.
+# @slot activator A custom (i.e. non-button) activator for the dropdown.
+#   Automatically adds the `role="button"` and `tabindex="0"` attributes.
+# @slot item+ The items in the dropdown. Each item will be styled consistently
+#   with proper spacing and hover states.
+#
+# @loco_example Basic Usage
+#   = daisy_dropdown do |dropdown|
+#     - dropdown.with_button do
+#       Click me!
+#     - dropdown.with_item do
+#       Item 1
+#     - dropdown.with_item do
+#       Item 2
+#
+# @loco_example Custom Activator
+#   = daisy_dropdown do |dropdown|
+#     - dropdown.with_activator do
+#       = heroicon_tag "bars-3", css: "size-6"
+#     - dropdown.with_item do
+#       Menu Item 1
+#     - dropdown.with_item do
+#       Menu Item 2
+#
+# @loco_example Complex Items
+#   = daisy_dropdown do |dropdown|
+#     - dropdown.with_button do
+#       User Settings
+#     - dropdown.with_item do
+#       .flex.gap-2.items-center
+#         = heroicon_tag "user-circle"
+#         Profile
+#     - dropdown.with_item do
+#       .flex.gap-2.items-center
+#         = heroicon_tag "cog-6-tooth"
+#         Settings
+#     - dropdown.with_item do
+#       .flex.gap-2.items-center.text-error
+#         = heroicon_tag "arrow-right-on-rectangle"
+#         Logout
+#
 class Daisy::Actions::DropdownComponent < LocoMotion::BaseComponent
 
-  TitleComponent = LocoMotion::BasicComponent.build do
-    def before_render
-      add_html(:component, { role: "button", tabindex: 0 })
-    end
-  end
-
-  ItemComponent = LocoMotion::BasicComponent.build do
-    def before_render
-      set_tag_name(:component, :li)
-    end
-  end
+  include ViewComponent::SlotableDefault
 
-  define_parts :title, :menu
+  define_parts :menu, :menu_item
 
-  renders_one :title, TitleComponent
-  renders_many :items, ItemComponent
+  renders_one :activator, LocoMotion::BasicComponent.build(html: { role: "button", tabindex: 0 })
+  renders_one :button, Daisy::Actions::ButtonComponent
+  renders_many :items
 
-  def initialize(*args, **kws, &block)
+  #
+  # Creates a new instance of the DropdownComponent.
+  #
+  # @param title [String] The title of the dropdown. Will be used as the button
+  #   text if no custom button or activator is provided.
+  #
+  # @param kws [Hash] The keyword arguments for the component.
+  #
+  # @option kws title [String] The title of the dropdown. You can also pass this
+  #   as the first argument.
+  #
+  def initialize(title = nil, **kws, &block)
     super
 
-    @simple_title = config_option(:title, "Submit")
+    @simple_title = config_option(:title, title)
   end
 
+  #
+  # Adds the relevant Daisy classes to the component.
+  #
   def before_render
     setup_component
-    setup_title
     setup_menu
   end
 
+  #
+  # Add the `dropdown` CSS class to the component.
+  #
   def setup_component
     add_css(:component, "dropdown")
   end
 
-  def setup_title
-    set_tag_name(:title, :div)
-    add_css(:title, "btn")
-    add_html(:title, { role: "button", tabindex: 0 })
-  end
-
+  #
+  # Make the menu a `<ul> / <li>` element and add the relevant Daisy classes.
+  #
   def setup_menu
+    # Setup menu itself
     set_tag_name(:menu, :ul)
     add_css(:menu, "dropdown-content menu bg-base-100 rounded-box shadow w-52 p-2 z-[1]")
-    add_html(:menu, { role: "menu", tabindex: 0 })
+
+    # Setup menu items
+    set_tag_name(:menu_item, :li)
+  end
+
+  #
+  # Provides a default button if no button or custom activator is provided.
+  #
+  def default_button
+    Daisy::Actions::ButtonComponent.new(title: @simple_title)
   end
 end

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

@@ -1,6 +1,7 @@
 - if activator?
-  = part(:activator) do
-    = activator
+  = activator
+- else
+  = button
 
 = part(:component) do
   = part(:box) do

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