loco_motion-rails 0.0.7 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a020015ecb6d9ee0a705d25830f1951b00c60be6ee4046939b878d3a720bfbda
-  data.tar.gz: c9bc31844a168d4427423912be65f354387aba43f2c6d6711998cee947e2311d
+  metadata.gz: 767e282b6b6bdd3838a976a9ee4b75e2b89d0e42282955076b00ffa9de3c092b
+  data.tar.gz: d87d11791dee9d2b92d1273d39f7eebbeffd9ff20b947ba208ae48692497d45d
 SHA512:
-  metadata.gz: f88796625ae5f6f7c7690563d0a687ed2d8932924d305cb12da0985fdcfdb00f629e6a25618afe5498ec6932af0e8c45b1cc3008a9f68d28940563f9f41f1fb0
-  data.tar.gz: 5f09dacd5dab790708428cb3e853e40fa59a5d20da58b4d11f9e99cca76bf940b1d3d311e55e8396b140acb2271eddb3df202175164ba59306acc041427d65cd
+  metadata.gz: 949e31fa02cbf137771872b6c35c3abfc1ccbaebe065ae74076693a2b19861bd274bb00c55688c7d688dd4e92f01ae72886e9945a7b95d1f634bde95d4b67f87
+  data.tar.gz: 2072ec0b0557723d23df2d1b41af5aaa48e786f81a95715e29833aa9b33cb3b78e90a4625568756f33ec5cfcbb3624e681518aa66a329f6c38003f91791741fb

data/README.md

@@ -6,19 +6,45 @@ ViewComponent, TailwindCSS, DaisyUI and more!
 
 <img src="//loco-motion-docs.profoundry.us/images/loco-chats.png" width="500px" style="border: 1px solid #bbb; padding: 2px; border-radius: 10px;">
 
-_**DISCLAIMER**_
+<!-- omit from toc -->
+## DISCLAIMER / CURRENT STATUS
 
 This project is in active development and many changes occur with every release!
-In particular, new Daisy components are being added frequently and older
-components are being updated with new features meaning the APIs are very likely
-to change!
+
+We've added a very basic / untested version of all DaisyUI 4 components. While
+we originally intended to take some time to flesh out and attempt to use these
+components, with the recent release of Tailwind 4 and DaisyUI 5, we feel our
+time is best spent updating all of the components and dependencies for these
+new releases.
+
+This means that we will **NOT** be making any bug fixes to the current branch
+(0.4.0), and will instead include any bug fixes / improvements into the 0.5.0
+branch which will also upgrade to Tailwind 4 and DaisyUI 5.
+
+ - Current Release **(0.4.0)** - Works with DaisyUI 4 and Tailwind 3
+ - Next Release **(0.5.0)** - Will work with DaisyUI 5 and Tailwind 4
+
+<!-- omit from toc -->
+## Additional Notes
+
+### DataInput Components
+
+Many of the DataInput elements (file input, text input, select dropdown, etc)
+were built rather hastily so that we would have a base version to start from.
+
+However, the new DaisyUI 5 components are implemented in a much cleaner way and
+we didn't want to invest too much time building these out and making them more
+ideal since we're about to change them.
+
+### Hosting / Sites
 
 We expect to settle on and purchase a real domain name in the near future, but
 for the time being, the latest documentation is available at the links below.
 
- - [Docs / Demo (Latest Release)][1]
- - [API Docs (Latest Release)][2]
- - [Docs / Demo (Main Branch / Staging)][3]
+ - [Latest Release][1]
+ - [Main / Staging][3]
+
+### Getting Help
 
 Please reach out by opening an
 [Issue](https://github.com/profoundry-us/loco_motion/issues) if you've found a
@@ -33,11 +59,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)
@@ -45,6 +73,8 @@ your solution is aligned with our goals.
   - [Install](#install)
   - [Using Components](#using-components)
 - [Developing](#developing)
+  - [Contributing](#contributing)
+  - [Releasing](#releasing)
   - [Tooling](#tooling)
 - [TODO / Next Steps](#todo--next-steps)
 
@@ -203,6 +233,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 +523,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
@@ -818,6 +884,20 @@ See the `Makefile` for all available commands.
 > make demo-restart
 > ```
 
+### Contributing
+
+If you're interested in contributing to LocoMotion, please check out our
+[CONTRIBUTING guide](docs/dev_guides/CONTRIBUTING.md) which provides detailed
+information about the contribution process, code standards, documentation
+requirements, and testing procedures.
+
+### Releasing
+
+For core team members who need to release new versions of LocoMotion, please
+refer to our [RELEASING guide](docs/dev_guides/RELEASING.md) for step-by-step
+instructions on version updates, building, testing, and publishing both the Ruby
+gem and NPM package.
+
 ### Tooling
 
 For VSCode, you may want to add the following to your settings to get
@@ -881,10 +961,10 @@ the GitHub Discussions feature and let us know!
 - [x] Basic versions of DaisyUI Data Display
 - [x] Basic versions of DaisyUI Navigation
 - [x] Basic versions of DaisyUI Feedback
-- [ ] 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] Basic versions of DaisyUI Data Input
+- [x] Basic versions of DaisyUI Layout
+- [x] Basic versions of DaisyUI Mockup
+- [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
@@ -894,14 +974,21 @@ the GitHub Discussions feature and let us know!
 - [ ] Choose, recommend, and document a pagination gem
 - [ ] Discuss caching techniques / setup
 - [x] Create / publish a staging version of the demo site ([Demo Staging][2])
-- [ ] Create / publish a staging version of the docs site
-- [ ] Create / publish a production version of the demo site
-- [ ] Create / publish a production version of the docs site
+- [x] Create / publish a staging version of the docs site
+- [x] Create / publish a production version of the demo site
+- [x] Create / publish a production version of the docs site
 - [x] Update demo site to allow for a different docs site using ENV var
 - [x] Update README to suggest Playwright
 - [ ] 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
+- [ ] Update to Tailwind 4 and DaisyUI 5
 
 [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