bullet_train 1.0.51 → 1.0.52

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e120bbb8234554fc860e6bbdbf9376e1899e8c4c3e024075eb84a4dc60b9a10
-  data.tar.gz: 5f144328a9c105ad2b434fe0fccbf514973f54c41c698910fa36c5932ba6fd5e
+  metadata.gz: 1684991a84caecbd6443e86aee17ac146ff70e71bec64607205e3266642c7af5
+  data.tar.gz: 9e00e826c90b30ac09e5daf147b0d10e29e036ff29b039f321a6c9de04441936
 SHA512:
-  metadata.gz: 382b6f890fa62609c0600b533958e89d67679bd6ff0c2a71e3c871566d878db20b405970e3dbb8353138e17c9c886df19e502914df51b45908c2091467631268
-  data.tar.gz: d0c09be2dc04291ed0bbe9d94857980e13a72823dea16f85e29edd9596ff8b5e890e46f60bf555bc24e5d8fc04b982bc3b5236711ef21976f1b73bcdf675d2e4
+  metadata.gz: 44d566105ccc88677771b87a23e0fd11b9ac8548bff4d6a26bed538a5ac94fdb57bfde0c0f8222fded9afbcf7c3d6de5e2bf04f8b7603eb9c92507ebd529bb36
+  data.tar.gz: b72dfdb3f0369bf6829ba8e47bddf50781bd33e39ac21f877923b389cb2fb690572f479107eaa83e120fd88dcfdd240e7cd18ad7ed18f42b98f87d5a79e46ced

data/app/views/layouts/docs.html.erb

@@ -104,6 +104,12 @@
                     <i class="fal fa-bolt ti ti-bolt"></i>
                   <% end %>
                 <% end %>
+
+                <%= render 'account/shared/menu/item', url: '/docs/javascript', label: 'JavaScript' do |p| %>
+                  <% p.content_for :icon do %>
+                  <i class="fa-brands fa-js ti ti-pulse"></i>
+                  <% end %>
+                <% end %>
               <% end %>
 
               <%= render 'account/shared/menu/section', title: 'Developer Tools' do %>

data/docs/getting-started.md

@@ -51,5 +51,5 @@ If you're using Bullet Train for the first time, begin by learning these five im
     And then paste any input, e.g.:
 
     ```
-    <!-- BEGIN /Users/andrewculver/.rbenv/versions/3.1.1/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/commentary/_box.html.erb -->
+    <!-- BEGIN /Users/andrewculver/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/commentary/_box.html.erb -->
     ```

data/docs/index.md

@@ -12,6 +12,7 @@
  - [Dealing with Indirection](/docs/indirection.md)
  - [Overriding the Framework](/docs/overriding.md)
  - [Setting up a Tunnel](/docs/tunneling.md)
+ - [JavaScript](/docs/javascript.md)
 
 ## Developer Tools
  - [Super Scaffolding](/docs/super-scaffolding.md)

data/docs/indirection.md

@@ -35,7 +35,7 @@ bin/resolve shared/box
 If you're looking at a rendered view in the browser, it can be hard to know which file to open in order to make a change. To help, Bullet Train enables `config.action_view.annotate_rendered_view_with_filenames` by default, so you can right click on any element you see, select "Inspect Element", and you'll see comments in the HTML source telling you which file is powering a particular portion of the view, like this:
 
 ```
-<!-- BEGIN /Users/andrewculver/.rbenv/versions/3.1.1/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/workflow/_box.html.erb -->
+<!-- BEGIN /Users/andrewculver/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/workflow/_box.html.erb -->
 ```
 
 Note that in the example above, the view in question isn't actually coming from the application repository. Instead, it's being included from the `bullet_train-themes-light` package. For instructions on how to customize it, see [Overriding Framework Defaults](/docs/overriding.md).

data/docs/javascript.md

@@ -0,0 +1,18 @@
+# JavaScript
+Bullet Train leans into the use of [Stimulus](https://stimulus.hotwired.dev) for custom JavaScript. If you haven't read it already, we consider [the original introductory blog post for Stimulus](https://medium.com/signal-v-noise/stimulus-1-0-a-modest-javascript-framework-for-the-html-you-already-have-f04307009130) to be a seminal work in the Rails ecosystem and consider it required reading for understanding the philosophy of JavaScript in Bullet Train.
+
+## Writing Custom JavaScript
+The happy path for writing new custom JavaScript is to [write it as a Stimulus controller](https://stimulus.hotwired.dev/handbook/building-something-real) in `app/javascript/controllers` and invoke it by augmenting the HTML in your views. If you name the file `*_controller.js`, it will be automatically picked up and compiled as part of your application's JavaScript bundle.
+
+## npm Packages
+npm packages are managed by [Yarn](https://yarnpkg.com) and any required importing can be done in `app/javascript/application.js`.
+
+## Compilation
+Bullet Train uses [esbuild](https://esbuild.github.io) to compile all local JavaScript and npm package dependencies. If you haven't used esbuild before, it's blazing fast compared to older options like Webpack. Honestly, it makes JavaScript development and deployment in complex applications a joy again, in a way it hasn't been for years.
+
+In development, the esbuild process that compiles JavaScript is defined as `yarn build` in `package.json`. This script also has an entry in `Procfile.dev`, so it runs automatically when you start your application with `bin/dev`, and when run in this context, it watches the filesystem and automatically recompiles anytime JavaScript files change on disk.
+
+The resulting JavaScript bundle is output to the `app/assets/builds` directory where it is picked up by the traditional Rails asset pipeline. This directory is listed in `.gitignore`, so the compiled bundles are never committed to the repository.
+
+## React, Vue.js, etc.
+We're not against the use of front-end JavaScript frameworks in the specific contexts where they're the best tool for the job, but we solidly subscribe to the "heavy machinery" philosophy put forward in [the original Stimulus blog post](https://medium.com/signal-v-noise/stimulus-1-0-a-modest-javascript-framework-for-the-html-you-already-have-f04307009130), and have no interest in actually supporting them.

data/docs/permissions.md

@@ -4,7 +4,7 @@
 Bullet Train leans heavily on [CanCanCan](https://github.com/CanCanCommunity/cancancan) for implementing authorization and permissions. (We’re also proud sponsors of its ongoing maintenance.) The original CanCan library by Ryan Bates was, in our opinion, a masterpiece and a software engineering marvel that has stood the test of time. It's truly a diamond among Ruby Gems. If you're not already familiar with CanCanCan, you should [read its documentation](https://github.com/CanCanCommunity/cancancan) to get familiar with its features and DSL.
 
 ## Bullet Train Roles
-Over many years of successfully implementing applications with CanCanCan, it became apparent to us that a supplemental level of abstraction could help streamline and simplify the definition of many common permissions, especially in large applications. We've since extracted this functionality into [a standalone Ruby Gem](https://github.com/bullet-train-co/bullet_train-roles) and moved the documentation that used to be here into [the README for that project](https://github.com/bullet-train-co/bullet_train-roles/blob/main/README.md). Should you encounter situations where this abstraction doesn't meet your specific needs, you can always implement the permissions you need using standard CanCanCan directives in `app/models/ability.rb`.
+Over many years of successfully implementing applications with CanCanCan, it became apparent to us that a supplemental level of abstraction could help streamline and simplify the definition of many common permissions, especially in large applications. We've since extracted this functionality into [a standalone Ruby Gem](https://github.com/bullet-train-co/bullet_train-roles) and moved the documentation that used to be here into [the README for that project](https://github.com/bullet-train-co/bullet_train-roles). Should you encounter situations where this abstraction doesn't meet your specific needs, you can always implement the permissions you need using standard CanCanCan directives in `app/models/ability.rb`.
 
 ## Additional Notes
 

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.0.51"
+  VERSION = "1.0.52"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.0.51
+  version: 1.0.52
 platform: ruby
 authors:
 - Andrew Culver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-15 00:00:00.000000000 Z
+date: 2022-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard
@@ -576,6 +576,7 @@ files:
 - docs/i18n.md
 - docs/index.md
 - docs/indirection.md
+- docs/javascript.md
 - docs/modeling.md
 - docs/namespacing.md
 - docs/oauth.md