loco_motion-rails 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cfe2882401b7bdfd08a844df9df854c145e89889bacc1e283102e4aad59d6d3
-  data.tar.gz: df1222834a5606b7ffa9135bf90fb4d59e1fc699eea8d2bf52686e7f039d0c3f
+  metadata.gz: 7d4d1891389f5b0a860f930a6d4e6dbb9053b6a77e349cd0f43b9de22740482b
+  data.tar.gz: 2f99a232731636bfaeca166092c0fb4ca51ddae6300e420951d0c0791997e1d7
 SHA512:
-  metadata.gz: 3f1ef92f5d9315db44ac50cb7c1be90f0924391c29b247d36930ae1758572dee93edafc0ba9f28ed496a8d29cb583c438ec77b50a08d73807cd79ca77d67aa38
-  data.tar.gz: 6ba44670ccdd89349da146dc31e15dbeff3e5753f6bf55fc3531b8bbcb4505d72dcbdb895b3abed018cf84ce8c4d44ce173d922d7ab4ea559ca9878863ec23b3
+  metadata.gz: ad963fe072e997ad83879704d8a5d9285f2e964371ee9c7418dfe7377db7950b09f43e3ff8555fad25aee3d141b7b6927ba5e70f965684d749057aaa1d6223c8
+  data.tar.gz: 367ecb0bf6b3b9d3ff77e6f596b12322fe1b1026bcecc619032c70e59ed94d344f3b18907e8dc8caf63b4d95343e351a808254b50da0db14c8a98b8282cb5a18

data/README.md

@@ -4,7 +4,7 @@
 Crazy fast Rails development with modern tools and components leveraging
 ViewComponent, TailwindCSS, DaisyUI and more!
 
-![image](./docs/assets/images/loco-chats.png)
+<img src="//loco-motion-docs.profoundry.us/images/loco-chats.png" width="500px" style="border: 1px solid #bbb; padding: 2px; border-radius: 10px;">
 
 _**DISCLAIMER**_
 
@@ -13,10 +13,12 @@ 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 plan to publish the docs site to a publicly available URL soon, but until
-then, you can run the docs by cloning the repository and running `make all` (or
-`make all-quick` if you've already run `make all` or `make rebuild` previously)
-and visiting http://localhost:3000/ in your browser.
+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]
 
 Please reach out by opening an
 [Issue](https://github.com/profoundry-us/loco_motion/issues) if you've found a
@@ -31,18 +33,19 @@ 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)
 - [LocoMotion Components](#locomotion-components)
   - [Install](#install)
   - [Using Components](#using-components)
-  - [Setting a Base Component Class](#setting-a-base-component-class)
 - [Developing](#developing)
   - [Tooling](#tooling)
 - [TODO / Next Steps](#todo--next-steps)
@@ -202,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
@@ -460,16 +477,45 @@ recommned Rspec with [factory_bot](https://github.com/thoughtbot/factory_bot)
 and [Shoulda Matchers](https://github.com/thoughtbot/shoulda-matchers).
 
 Finally, although both libraries offer some functionality for testing your user
-interface, we recommend utilizing [Cypress](https://www.cypress.io/) instead as
-it more closely mimics the real user experience in a browser and it allows you
-to see in real-time what is happening, including in-browser debugging!
+interface, we recommend utilizing [Playwright](https://playwright.dev/) instead
+as it more closely mimics the real user experience in a browser and it allows
+you to see in real-time what is happening, including in-browser debugging!
+
+Although the common setup is to write your specs in JavaScript or TypeScript,
+you can actually write your End to End tests in Ruby / Rspec by utilizing the
+[playwright-ruby-client](https://playwright-ruby-client.vercel.app/)!
+
+We'll have some guides and examples for this coming soon!
 
 > [!NOTE]
-> One thing to note about Cypress, however, is that it is Javascript-based and
-> thus requires you to write tests in Javascript. If you are only famililar with
-> Ruby, you might want to stick with Rspec or Minitest when you first start your
-> project, and expand into using Cypress once you are comfortable learning a new
-> lanugage / framework.
+> We used to recommend [Cypress](https://www.cypress.io) for End-to-End tests,
+> but it's reliance on JavaScript and sometimes flakey tests caused us to search
+> out a new solution / recommendation.
+>
+> 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
 
@@ -670,9 +716,9 @@ a full set of UI components to help you build robust and full-featured apps.
 
 > [!CAUTION]
 > The LocoMotion components are being actively developed and are NOT ready for
-> production / public use (currently they are just some example components while
-> I get everything setup). I'm mainly adding the docs here so that I remember
-> how to set them up properly when they are ready for release.
+> production / public use! We have finished basic versions of the DaisyUI
+> Actions, DataDisplay, Navigation, and Feedback components, but we expect these
+> to change (possibly quite a bit) as we begin to use them in projects.
 
 ### Install
 
@@ -685,7 +731,7 @@ gem "loco_motion", github: "profoundry-us/loco_motion", branch: "main", require:
 
 # or
 
-gem "loco_motion-rails", "0.0.6", require: "loco_motion"
+gem "loco_motion-rails", "0.0.7", require: "loco_motion"
 ```
 
 Next add the following lines to the `contents` section of your
@@ -707,8 +753,8 @@ Next add the following lines to the `contents` section of your
 
 > [!WARNING]
 > Note that this will not output anything if it fails to find the right
-> directory, so your CSS may stop working if you update the gem and forget to
-> update this setting.
+> directory, so your CSS may not compile properly if this command fails or finds
+> the wrong gem or an older gem.
 
 Next, if you're using any of the components that require JavaScript (like the
 Countdown component), you'll need to add the library as a dependency and include
@@ -762,57 +808,35 @@ the following code and refresh your page.
 You should see a few buttons and the user info that we saved from OmniAuth
 represented as a Ruby hash! Any other content you have will be rendered below.
 
-### Setting a Base Component Class
-
-Sometimes, you may want to override the way that LocoMotion handles things, or
-provide some functionality yourself in a sub-class of our components. Since you
-can't have a class inherit from two classes, we give you a way to override the
-base class that all of our components inherit from.
-
-This allows you to define a class that inherits from `LocoMotion::BaseComponent`
-and then adds any special methods or overrides to our default components.
-
-Create a file called `app/components/application_component.rb` with the following
-contents:
-
-```ruby
-class ApplicationComponent < LocoMotion::BaseComponent
-end
-```
-
-Then add the following to `config/initializers/loco_motion.rb`.
-
-
-```ruby
-LocoMotion.configure do |config|
-
-  # Override the base component class to inherit from our ApplicationComponent
-  # so that we can add our own overrides / methods.
-  Rails.application.config.after_initialize do
-    config.base_component_class = ApplicationComponent
-  end
-
-end
-```
-
-> [!NOTE]
-> It doesn't have to inherit from `ApplicationComponent`, you can use any class
-> you want, so you could create a separate `CustomizedLocoMotionComponent` class
-> so that you don't have any conflicts with your `ApplicationComponent`.
-
 ## Developing
 
 To work on LocoMotion, first clone the repository and make sure you have Docker
 installed and running on your machine.
 
+Next, create a `.env.local` file with the following contents, making sure to
+replace the Unsplash keys with real ones (you can create your own account or ask
+Topher for his keys).
+
+```.env
+# .env.local
+UNSPLASH_ACCESS_KEY="<< INSERT ACCESS KEY >>"
+UNSPLASH_SECRET_KEY="<< INSERT SECRET KEY >>"
+```
+
 You should then be able to run `make rebuild` in the project directory and then
 `make all-quick` to start the services.
 
 > [!NOTE]
 >
-> We use `npm link` within the `docs/demo/bin/dev` script to enable quick
-> editing of the JavaScript library files so you don't have to publish a new
-> package during testing.
+> We use `yarn link` in the `docs/demo/bin/setup` script to enable quick editing
+> of the Javascript files so you don't have to publish new packages during
+> testing.
+>
+> For the Ruby gem, we point directly to it via the `:path` option in the
+> `Gemfile`. This means that we have a custom Heroku buildpack when we publish
+> the demo site to move the files into the appropriate places.
+>
+> See https://github.com/profoundry-us/loco_motion-buildpack for more info.
 
 From here, you can access the demo site at http://localhost:3000 and the YARD
 docs at http://localhost:8808/docs/yard
@@ -854,6 +878,37 @@ TailwindCSS Intellisense working properly.
   ],
 ```
 
+And because whitespace is important when developing inline components, you
+should also add the following which prevents VSCode from adding a newline to the
+bottom of your HAML files. This helps ensure that inline components don't have
+trailing whitespace when using something like the `succeed` helper.
+
+```json
+  "[haml]": {
+      "editor.formatOnSave": false
+  }
+```
+
+Alternatively, if your component is simple enough, moving the template inside
+the `_component.rb` file's `call` method can also alleviate this problem.
+
+So instead of
+
+```haml
+- # This file has a newline at the bottom which can cause problems
+= part(:component) do
+  = content
+
+```
+
+you could do something like this:
+
+```ruby
+def call
+  part(:component) { content }
+end
+```
+
 ## TODO / Next Steps
 
 There is a LOT left to be done. We're not currently seeking assistance, but if
@@ -863,18 +918,35 @@ the GitHub Discussions feature and let us know!
 - [x] Basic versions of DaisyUI Actions
 - [x] Basic versions of DaisyUI Data Display
 - [x] Basic versions of DaisyUI Navigation
-- [ ] Basic versions of DaisyUI Feedback
+- [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
+- [x] ~~Get YARD docs rendering with (better) Markdown~~ _**Working for now**_
 - [x] Extract relevant pieces into a yard-loco_motion plugin
-- [ ] Publish Gem
+- [x] Publish Gem
 - [x] Publish NPM package
-- [ ] Update YARD plugin to add `@part`s
+- [x] Update YARD plugin to add `@part`s
+- [x] Update YARD plugin to add `@loco_example`s with language support
 - [x] Extract doc callouts into a doc component (and / or the Daisy component)
-- [ ] Choose and recommend / document a pagination gem
+- [ ] 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
-- [ ] Update demo site to allow for a different docs site using ENV var
+- [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
+
+[1]: https://loco-motion.profoundry.us/
+[2]: https://loco-motion-demo-staging.profoundry.us/
+[3]: https://loco-motion-demo-staging.profoundry.us/api-docs

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

@@ -1,10 +1,97 @@
-# Here are the Button docs!
-class Daisy::Actions::ButtonComponent < LocoMotion.configuration.base_component_class
-  set_component_name :btn
+#
+# 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
 
-  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)
 
@@ -20,15 +107,22 @@ class Daisy::Actions::ButtonComponent < LocoMotion.configuration.base_component_
     @right_icon_css = config_option(:right_icon_css, @icon_css)
     @right_icon_html = config_option(:right_icon_html, @icon_html)
 
-    @simple_title = config_option(:title, @left_icon || @right_icon ? nil : "Submit")
+    default_title = @left_icon || @right_icon ? nil : "Submit"
+    @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)
@@ -39,13 +133,23 @@ class Daisy::Actions::ButtonComponent < LocoMotion.configuration.base_component_
 
     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!
-class Daisy::Actions::DropdownComponent < LocoMotion.configuration.base_component_class
+#
+# 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