@profoundry-us/loco_motion 0.0.6 → 0.0.8

package/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
 
@@ -681,7 +727,11 @@ Add the following to your `Gemfile` and re-run `bundle`:
 ```Gemfile
 # Gemfile
 
-gem "loco_motion", github: "profoundry-us/loco_motion", branch: "main"
+gem "loco_motion", github: "profoundry-us/loco_motion", branch: "main", require: "loco_motion"
+
+# or
+
+gem "loco_motion-rails", "0.0.7", require: "loco_motion"
 ```
 
 Next add the following lines to the `contents` section of your
@@ -703,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
@@ -758,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
@@ -850,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
@@ -859,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/loco_motion",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Crazy fast Rails development!",
   "main": "index.js",
   "repository": {