@profoundry-us/loco_motion 0.0.5 → 0.0.7

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
@@ -42,9 +44,10 @@ your solution is aligned with our goals.
 - [LocoMotion Components](#locomotion-components)
   - [Install](#install)
   - [Using Components](#using-components)
-  - [Setting a Base Component Class](#setting-a-base-component-class)
-- [Tooling](#tooling)
-- [Next Steps](#next-steps)
+- [Developing](#developing)
+  - [Tooling](#tooling)
+- [TODO / Next Steps](#todo--next-steps)
+
 
 ## About
 
@@ -458,16 +461,23 @@ 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.
 
 ## Authentication
 
@@ -668,9 +678,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
 
@@ -679,25 +689,63 @@ 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 line to the `contents` section of your
-`tailwind.config.js` file (make sure to change the version number to the one
-you install):
+Next add the following lines to the `contents` section of your
+`tailwind.config.js` to import / build the proper files:
 
 ```js
-  content:[
-    `${process.env.GEM_HOME}/loco_motion-0.0.4/app/components/**/*.{rb,js,html.haml}`,
+  const { execSync } = require('child_process');
 
-    // ...
-  ]
+  let locoBundlePath = execSync('bundle show loco_motion').toString().trim();
+
+  module.exports = {
+    content:[
+      `${locoBundlePath}/app/components/**/*.{rb,js,html.haml}`,
+
+      // ...
+    ]
+  }
 ```
 
 > [!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
+those controllers in your `application.js` file.
+
+```sh
+npm add @profoundry-us/loco_motion
+```
+
+or
+
+```sh
+yarn add @profoundry-us/loco_motion
+```
+
+Then inside your `application.js` file, make sure to import and register the
+relevant controllers.
+
+```js
+import { Application } from "@hotwired/stimulus"
+
+import { CountdownController } from "@profoundry-us/loco_motion"
+
+const application = Application.start()
+
+application.register("countdown", CountdownController)
+
+export { application }
+```
 
 ### Using Components
 
@@ -707,64 +755,70 @@ the following code and refresh your page.
 ```haml
   %body
     .m-2.p-2.rounded.bg-red-400
-      = yield
-
-    .btn
-      = LocoMotion.hello_world
+      = session[:user_info].inspect
 
     %div
-      = render(LocoMotion::Buttons::ButtonComponent.new)
+      = render(Daisy::Actions::ButtonComponent.new(title: "Click Me"))
 
     %div
-      = render(LocoMotion::Buttons::FabComponent.new)
+      = daisy_button(css: "btn-primary") do
+        Click Me Too
 
-    %div
-      = session[:user_info].inspect
+    = yield
 ```
 
-You should see a gray button that says "Hello World!" and the user info that
-we saved from OmniAuth represented as a Ruby hash! You should also see the
-example Button and Fab components.
+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
+## Developing
 
-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.
+To work on LocoMotion, first clone the repository and make sure you have Docker
+installed and running on your machine.
 
-This allows you to define a class that inherits from `LocoMotion::BaseComponent`
-and then adds any special methods or overrides to our default components.
+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).
 
-Create a file called `app/components/application_component.rb` with the following
-contents:
-
-```ruby
-class ApplicationComponent < LocoMotion::BaseComponent
-end
+```.env
+# .env.local
+UNSPLASH_ACCESS_KEY="<< INSERT ACCESS KEY >>"
+UNSPLASH_SECRET_KEY="<< INSERT SECRET KEY >>"
 ```
 
-Then add the following to `config/initializers/loco_motion.rb`.
+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 `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.
 
-```ruby
-LocoMotion.configure do |config|
+From here, you can access the demo site at http://localhost:3000 and the YARD
+docs at http://localhost:8808/docs/yard
 
-  # 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
+You can type `make demo-shell` to open a shell inside the demo Docker container,
+or `make loco-shell` to get a shell inside the gem's Docker container.
 
-end
-```
+See the `Makefile` for all available commands.
 
-> [!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`.
+> [!WARNING]
+>
+> Right now, Rails doesn't auto-reload the LocoMotion library files when they
+> change, so you might have to restart your server to get it to pickup the
+> changes.
+>
+> ```sh
+> make demo-restart
+> ```
 
-## Tooling
+### Tooling
 
 For VSCode, you may want to add the following to your settings to get
 TailwindCSS Intellisense working properly.
@@ -786,24 +840,69 @@ TailwindCSS Intellisense working properly.
   ],
 ```
 
-## Next Steps
+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
+  }
+```
 
-TODO: Expand upon loco_motion components, Daisy-rails gems, icons, pagination
-gems, etc
+Alternatively, if your component is simple enough, moving the template inside
+the `_component.rb` file's `call` method can also alleviate this problem.
 
-- [ ] Get YARD docs rendering with (better) Markdown
-- [x] Extract relevant pieces into a yard-loco_motion plugin
-- [ ] Publish Gem and NPM packages with only the files those need
-- [ ] Create a new YARD plugin to document `@part`s
-- [ ] Extract alerts into a doc component (and / or the Daisy component)
+So instead of
 
-# Developing
+```haml
+- # This file has a newline at the bottom which can cause problems
+= part(:component) do
+  = content
 
-Might need to `make demo-shell` and then `cd /home/loco_motion` and `yard link`.
+```
 
-Then, `cd /home/loco_demo` and run `yarn link "loco_motion"` so that you can
-more easily do development on the various parts without having to re-run `yarn`
-every time.
+you could do something like this:
 
-Also may need to run `yarn` on the top level directory. Maybe we can move this
-into the Docker install / setup?
+```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
+you feel very strongly that you'd like to contribute, please reach out through
+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
+- [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] Extract relevant pieces into a yard-loco_motion plugin
+- [x] Publish Gem
+- [x] Publish NPM package
+- [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, 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] 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
+
+[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.5",
+  "version": "0.0.7",
   "description": "Crazy fast Rails development!",
   "main": "index.js",
   "repository": {