bullet_train 1.0.35 → 1.0.38

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf30474fa5f48c2365c9a4c10439870ada7afeebc830122d8789fc11fe27708f
-  data.tar.gz: c7486e57abca9d509b0865c912caabed1b391c0ae6ec1ad35cb8f9bf62f1a592
+  metadata.gz: 0dcb39f530a513954bbf81e5776d8dfa80bcb5337d06006c60ed785fe753938d
+  data.tar.gz: 17a0381fe935017c676fcb300c6b7e77e2d13cb0db995732c8bf927a6010880c
 SHA512:
-  metadata.gz: 408956ef34bdde97f9ed66506f9e6a1f3aaba977e83663417e2ea4ce53b8ce2e2d96e64b2291026e0f3859f62ffb794edd99ff3ef2acbe01cd4177f5ee77bae2
-  data.tar.gz: 75cf7bcca374f6d1fb0bac044891deba140aa08303d70351b28c7091a9f5b853b9a8dfea7b8e912ad50267eaaf2288c31014d934011ea7e5b4844c4747d73f21
+  metadata.gz: 33f012230c149f0db16994bc23e779d0650abfa210b0f986173e0c2adae19e4511cb0184b90b1963393becb7d48805a705d969b05c3a6aa34f6dbe5853d488d3
+  data.tar.gz: 9c2c749b3ebc93c990961a46d666b5273774b12a53f6ee37f8e5cb080863d9b5a62714a9dac4955ead6347fb43b8654331373471614a2ed3e5c7aec206cf0bfc

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

@@ -5,7 +5,7 @@
     <%
     # we're going to use the
     body = Nokogiri::HTML(@body)
-    title = body.css('h1').first.text.presence || t('bullet_train.tagline')
+    title = body.css('h1').first&.text.presence || t('bullet_train.tagline')
     first_paragraph = body.css('p').first
     preceding_heading = first_paragraph&.xpath("preceding-sibling::h2")
     description = [preceding_heading&.text, first_paragraph&.text].select(&:present?).join(" — ") || t('bullet_train.description')
@@ -73,41 +73,43 @@
                   <% end %>
                 <% end %>
 
-                <%= render 'account/shared/menu/item', url: '/docs/philosophy', label: 'Philosophy' do |p| %>
+                <%= render 'account/shared/menu/item', url: '/docs/upgrades', label: 'Upgrades' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-lightbulb-on ti ti-light-bulb"></i>
+                    <i class="fal fa-sparkles ti ti-arrow-up"></i>
                   <% end %>
                 <% end %>
+              <% end %>
 
-                <%= render 'account/shared/menu/item', url: '/docs/upgrades', label: 'Upgrades' do |p| %>
+              <%= render 'account/shared/menu/section', title: 'General Topics' do %>
+                <%= render 'account/shared/menu/item', url: '/docs/modeling', label: 'Domain Modeling' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-sparkles ti ti-arrow-up"></i>
+                    <i class="fal fa-bolt ti ti-ruler-pencil"></i>
                   <% end %>
                 <% end %>
 
-                <%= render 'account/shared/menu/item', url: '/docs/tunneling', label: 'Tunneling' do |p| %>
+                <%= render 'account/shared/menu/item', url: '/docs/indirection', label: 'Indirection' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-bolt ti ti-bolt"></i>
+                    <i class="fal fa-bolt ti ti-direction"></i>
                   <% end %>
                 <% end %>
-              <% end %>
 
-              <%= render 'account/shared/menu/section', title: 'Developer Tools' do %>
-                <%= render 'account/shared/menu/item', url: '/docs/super-scaffolding', label: 'Super Scaffolding' do |p| %>
+                <%= render 'account/shared/menu/item', url: '/docs/overriding', label: 'Overriding' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-magic ti ti-wand"></i>
+                    <i class="fal fa-bolt ti ti-spray"></i>
                   <% end %>
                 <% end %>
 
-                <%= render 'account/shared/menu/item', url: '/docs/field-partials', label: 'Field Partials' do |p| %>
+                <%= render 'account/shared/menu/item', url: '/docs/tunneling', label: 'Tunneling' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-i-cursor ti ti-text"></i>
+                    <i class="fal fa-bolt ti ti-bolt"></i>
                   <% end %>
                 <% end %>
+              <% end %>
 
-                <%= render 'account/shared/menu/item', url: '/docs/themes', label: 'Themes' do |p| %>
+              <%= render 'account/shared/menu/section', title: 'Developer Tools' do %>
+                <%= render 'account/shared/menu/item', url: '/docs/super-scaffolding', label: 'Super Scaffolding' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-swatchbook ti ti-palette"></i>
+                    <i class="fal fa-magic ti ti-wand"></i>
                   <% end %>
                 <% end %>
 
@@ -122,6 +124,12 @@
                     <i class="fal fa-check ti ti-check"></i>
                   <% end %>
                 <% end %>
+
+                <%= render 'account/shared/menu/item', url: 'https://github.com/bullet-train-co/magic_test', label: 'Magic Test' do |p| %>
+                  <% p.content_for :icon do %>
+                    <i class="fal fa-check ti ti-video-camera"></i>
+                  <% end %>
+                <% end %>
               <% end %>
 
               <%= render 'account/shared/menu/section', title: 'Accounts & Teams' do %>
@@ -156,6 +164,26 @@
                 <% end %>
               <% end %>
 
+              <%= render 'account/shared/menu/section', title: 'User Interface' do %>
+                <%= render 'account/shared/menu/item', url: '/docs/field-partials', label: 'Field Partials' do |p| %>
+                  <% p.content_for :icon do %>
+                    <i class="fal fa-i-cursor ti ti-text"></i>
+                  <% end %>
+                <% end %>
+
+                <%= render 'account/shared/menu/item', url: '/docs/themes', label: 'Themes' do |p| %>
+                  <% p.content_for :icon do %>
+                    <i class="fal fa-swatchbook ti ti-palette"></i>
+                  <% end %>
+                <% end %>
+
+                <%= render 'account/shared/menu/item', url: 'https://github.com/bullet-train-co/nice_partials', label: 'Nice Partials' do |p| %>
+                  <% p.content_for :icon do %>
+                    <i class="fal fa-swatchbook ti ti-widget"></i>
+                  <% end %>
+                <% end %>
+              <% end %>
+
               <%= render 'account/shared/menu/section', title: 'Billing' do %>
                 <%= render 'account/shared/menu/item', url: '/docs/billing/stripe', label: 'Stripe' do |p| %>
                   <% p.content_for :icon do %>
@@ -175,19 +203,19 @@
                   <% p.content_for :icon do %>
                     <i class="fal fa-brackets-curly ti ti-settings"></i>
                   <% end %>
-                <% end if false %>
+                <% end %>
 
                 <%= render 'account/shared/menu/item', url: '/docs/webhooks/outgoing', label: 'Outgoing Webhooks' do |p| %>
                   <% p.content_for :icon do %>
                     <i class="fal fa-outlet ti ti-pulse"></i>
                   <% end %>
-                <% end if false %>
+                <% end %>
 
                 <%= render 'account/shared/menu/item', url: '/docs/webhooks/incoming', label: 'Incoming Webhooks' do |p| %>
                   <% p.content_for :icon do %>
                     <i class="fal fa-plug ti ti-plug"></i>
                   <% end %>
-                <% end if false %>
+                <% end %>
               <% end %>
 
               <%= render 'account/shared/menu/section', title: 'Internationalization' do %>

data/app/views/public/home/docs.html.erb

@@ -1 +1,18 @@
-<%= @body = markdown(File.read(Rails.root.to_s + "/#{@file}").gsub('.md)', ')')) %>
+<% @body = markdown(File.read(Rails.root.to_s + "/#{@file}").gsub('.md)', ')')) %>
+
+<% if @file == "tmp/gems/bullet_train/docs/index.md" %>
+  <% header, groups = @body.split("<h2>", 2) %>
+  <%= header.html_safe %>
+
+  <% # Restore the leading <h2> to the groups of links. %>
+  <% groups = "<h2>#{groups}" %>
+  <div class="xl:grid grid-cols-3 gap-20">
+    <% groups.split("<h2>").select(&:present?).map { |s| "<h2>#{s}" }.in_groups(3).each do |group| %>
+        <div>
+        <%= group.join.html_safe %>
+      </div>
+    <% end %>
+  </div>
+<% else %>
+  <%= @body %>
+<% end %>

data/config/routes.rb

@@ -3,7 +3,7 @@ Rails.application.routes.draw do
     root to: "home#index"
     get "invitation" => "home#invitation", :as => "invitation"
 
-    if Rails.env.production? ? ENV["ENABLE_DOCS"].present? : true
+    if Rails.env.development?
       get "docs", to: "home#docs"
       get "docs/*page", to: "home#docs"
     end

data/docs/api.md

@@ -0,0 +1,3 @@
+# REST API
+
+> TODO This section needs to be written and should probably delegate a lot of details to the README of the [Bullet Train API repository](https://github.com/bullet-train-co/bullet_train-api).

data/docs/authentication.md

@@ -0,0 +1,13 @@
+# Authentication
+Bullet Train uses [Devise](https://github.com/heartcombo/devise) for authentication and we've done the work of making the related views look pretty and well-integrated with the look-and-feel of the application template.
+
+## Customizing Controllers
+Bullet Train registers its own slightly customized registration and session controllers for Devise. If you want to customize them further, you can simply eject those controllers from the framework and override them locally, like so:
+
+```
+$ bin/resolve RegistrationsController --eject --open
+$ bin/resolve SessionsController --eject --open
+```
+
+## Customizing Views
+You can customize Devise views using the same workflow you would use to customize any other Bullet Train views.

data/docs/billing/stripe.md

@@ -0,0 +1,90 @@
+# Enabling Stripe Subscriptions
+
+Bullet Train provides a base billing package and a Stripe-specific package with support for Stripe Checkout, Stripe Billing's customer portal, and incoming Stripe webhooks.
+
+## 1. Add the `bullet_train-billing-stripe` Ruby gem.
+
+> TODO Add instructions about subscribing to Bullet Train Pro.
+
+## 2. Migrate the Database
+
+```
+rake db:migrate
+```
+
+## 3. Create API Keys with Stripe
+
+ - Create a Stripe account if you don't already have one.
+ - Visit https://dashboard.stripe.com/apikeys.
+ - For your development environment, make sure you toggle the "test mode" flag to "on" in the top-right corner.
+ - Create a new secret key.
+
+## 4. Configure Stripe API Keys Locally
+
+Edit `config/application.yml` and add your Stripe publishable key and new secret key to the file, and also tell the system to use Stripe subscriptions by default:
+
+```
+BILLING_DEFAULT_SUBSCRIPTION: "Billing::Stripe::Subscription"
+STRIPE_PUBLISHABLE_KEY: pk_0CJwz5wHlKBXxDA4VO1uEoipxQob0
+STRIPE_SECRET_KEY: sk_0CJw2Iu5wwIKXUDdqphrt2zFZyOCH
+```
+
+## 5. Populate Stripe with Locally Configured Products
+
+Bullet Train defines subscription plans and other purchasable add-ons in `config/models/billing/products.yml` and comes preconfigured with some example plans. We recommend just getting started with these plans to ensure your setup is working before customizing the attributes of these plans.
+
+Before you can use Stripe Checkout or Stripe Billing's customer portal, these products will have to be defined on Stripe as well. You can have all locally defined products automatically created on Stripe by running the following:
+
+```
+rake billing:stripe:populate_products_in_stripe
+```
+
+## 6. Import Additional Environment Variables
+
+The script in the previous step will output some additional environment variables you need to copy into `config/application.yml`.
+
+## 7. Restart Rails
+
+We've modified a bunch of environment variables, so you'll have to have to restart your Rails server before you see the results in your browser.
+
+```
+rails restart
+```
+
+## 8. Test Creating a Subscription
+
+Bullet Train comes preconfigured with a "freemium" plan, so new and existing accounts will continue to work as normal. A new "billing" menu item will appear and you can test subscription creation by clicking "upgrade" and selecting one of the two plans presented.
+
+You should be in "test mode" on Stripe, so when prompted for a credit card number, you can enter `4242 4242 4242 4242`.
+
+## 9. Configuring Webhooks
+
+Basic subscription creation will work without receiving and processing Stripe's webhooks. However, advanced payment workflows like SCA payments and customer portal cancelations and plan changes require receiving webhooks and processing them.
+
+ - Stripe can't deliver webhooks to `http://localhost:3000`, so you'll need to [get an HTTP tunnel up and running](/docs/tunneling.md). For this example, we'll assume you're using ngrok.
+ - Visit https://dashboard.stripe.com/test/webhooks/create.
+ - Configure the "endpoint URL" to be `https://your-tunnel.ngrok.io/webhooks/incoming/stripe_webhooks`, replacing `your-tunnel` with whatever the subdomain of your tunnel is.
+ - When configuring which events to receive, just "select all events" for simplicity. This ensures that any webhooks Bullet Train might add support for in the future will be properly handled when you upgrade.
+ - Add the endpoint.
+ - On the page for the webhook endpoint you've just configured with Stripe, click on "reveal" under the heading "signing secret". This is a secret token that is required to authenticate that webhooks your application is receiving are actually coming from Stripe. Copy this into your `config/application.yml` like so:
+
+ ```
+ STRIPE_WEBHOOKS_ENDPOINT_SECRET: whsec_VsM3c2zeZyqAddkaPaXzf1wJsYp2fRKR
+ ```
+
+ - Restart your Rails server with `rails restart`.
+ - Trigger a test webhook just to ensure it's resulting in an HTTP status code of 201.
+
+## 10. Configure Stripe Billing's Customer Portal
+
+  - Visit https://dashboard.stripe.com/test/settings/billing/portal.
+  - Complete all required fields.
+  - Be sure to add all of your actively available plans under "products".
+
+This "products" list is what Stripe will display to users as upgrade and downgrade options in the customer portal. You shouldn't list any products here that aren't properly configured in your Rails app, otherwise the resulting webhook will fail to process. If you want to stop offering a plan, you should remove it from this list as well.
+
+## 11. Test Webhooks by Managing a Subscription
+
+In the same account where you created your first test subscription, go into the "billing" menu and click "manage" on that subscription. This will take you to the Stripe Billing customer portal.
+
+Once you're in the customer portal, you should test upgrading, downgrading, and canceling your subscription and clicking "⬅ Return to {Your Application Name}" in between each step to ensure that each change you're making is properly reflected in your Bullet Train application. This will let you know that webhooks are being properly delivered and processed and all the products in both systems are properly mapped in both directions.

data/docs/desktop.md

@@ -0,0 +1,13 @@
+# Distributing as a Desktop Application
+
+Bullet Train is fine-tuned to run well within an Electron container and the easiest way to generate code-signed, Electron-powered application bundles for Windows, macOS, and Linux is the commercial tool provided by our friends at [ToDesktop](https://www.todesktop.com).
+
+## Developing Desktop Experiences Locally
+
+To test your application's desktop experience during development, you can simply [download and install Bullet Train's own prebuilt desktop application](https://dl.todesktop.com/210204wqi0hp3xe). This example application (built by ToDesktop) points to `http://localhost:3000`, so after spinning up `rails s`, you can launch this application to tweak and tune your desktop experience in real time.
+
+This same bundle is available for the following platforms:
+
+ - [Windows](https://dl.todesktop.com/210204wqi0hp3xe/windows/nsis/x64)
+ - [macOS](https://dl.todesktop.com/210204wqi0hp3xe/mac/dmg/x64)
+ - [Linux](https://dl.todesktop.com/210204wqi0hp3xe/linux/appImage/x64)

data/docs/field-partials/buttons.md

@@ -0,0 +1,42 @@
+# Examples for the `buttons` Field Partial
+
+## Define Available Buttons via Localization Yaml
+
+If you invoke the field partial in `app/views/account/some_class_name/_form.html.erb` like so:
+
+```
+<%= render 'shared/fields/buttons', form: form, method: :enabled %>
+```
+
+You can define the available buttons in `config/locales/en/some_class_name.en.yml` like so:
+
+```
+en:
+  some_class_name:
+    fields:
+      enabled:
+        name: &enabled Enabled
+        label: Should this item be enabled?
+        heading: Enabled?
+        options:
+          yes: "Yes, this item should be enabled."
+          no: "No, this item should be disabled."
+```
+
+## Generate Buttons Programmatically
+
+You can generate the available buttons using a collection of database objects by passing the `options` option like so:
+
+```
+<%= render 'shared/fields/buttons', form: form, method: :category_id,
+  options: Category.all.map { |category| [category.id, category.label_string] } %>
+```
+
+## Allow Multiple Button Selections
+
+You can allow multiple buttons to be selected using the `multiple` option, like so:
+
+```
+<%= render 'shared/fields/buttons', form: form, method: :category_ids,
+  options: Category.all.map { |category| [category.id, category.label_string] }, multiple: true %>
+```

data/docs/field-partials/super-select.md

@@ -0,0 +1,58 @@
+# Examples for the `super_select` Field Partial
+
+The `super_select` partial provides a wonderful default UI (in contrast to the vanilla browser experience for this, which is horrible) with optional search and multi-select functionality out-of-the-box. It invokes the [Select2](https://select2.org) library to provide you these features.
+
+## Define Available Buttons via Localization Yaml
+
+If you invoke the field partial in `app/views/account/some_class_name/_form.html.erb` like so:
+
+<pre><code><%= render 'shared/fields/super_select', form: form, method: :response_behavior %></code></pre>
+
+You can define the available options in `config/locales/en/some_class_name.en.yml` like so:
+
+<pre><code>en:
+  some_class_name:
+    fields:
+      response_behavior:
+        name: &response_behavior Response Behavior
+        label: When should this object respond to new submissions?
+        heading: Responds
+        choices:
+          immediate: Immediately
+          after_10_minutes: After a 10 minute delay
+          disabled: Doesn't respond
+</code></pre>
+
+## Specify Available Choices Inline
+
+Although it's recommended to define any static list of choices in the localization Yaml file (so your application remains easy to translate into other languages), you can also specify these choices using the `choices` option from the underlying select form field helper:
+
+<pre><code><%= render 'shared/fields/super_select', form: form, method: :response_behavior,
+  choices: [['Immediately', 'immediate'], ['After a 10 minute delay', 'after_10_minutes'] ["Doesn't respond", 'disabled']] %></code></pre>
+
+## Generate Choices Programmatically
+
+You can generate the available buttons using a collection of database objects by passing the `options` option like so:
+
+<pre><code><%= render 'shared/fields/super_select', form: form, method: :category_id,
+  choices: Category.all.map { |category| [category.label_string, category.id] } %></code></pre>
+
+## Allowing Multiple Option Selections
+
+Here is an example allowing multiple team members to be assigned to a (hypothetical) `Project` model:
+
+<pre><code><%= render 'shared/fields/super_select', form: form, method: :membership_ids,
+  choices: @project.valid_memberships.map { |membership| [membership.name, membership.id] },
+  html_options: {multiple: true} %>
+</code></pre>
+
+The `html_options` key is just inherited from the underlying Rails select form field helper.
+
+## Allowing Search
+
+Here is the same example, with search enabled:
+
+<pre><code><%= render 'shared/fields/super_select', form: form, method: :membership_ids,
+  choices: @project.valid_memberships.map { |membership| [membership.name, membership.id] },
+  html_options: {multiple: true}, other_options: {search: true} %>
+</code></pre>

data/docs/field-partials.md

@@ -0,0 +1,132 @@
+# Field Partials
+Bullet Train includes a collection of view partials that are intended to [DRY-up](https://en.wikipedia.org/wiki/Don't_repeat_yourself) as much redundant presentation logic as possible for different types of form fields without taking on a third-party dependency like Formtastic.
+
+## Responsibilities
+These form field partials standardize and centralize the following behavior across all form fields that use them:
+
+ - Apply theme styling and classes.
+ - Display any error messages for a specific field inline under the field itself.
+ - Display a stylized asterisk next to the label of fields that are known to be required.
+ - Any labels, placeholder values, and help text are defined in a standardized way in the model's localization Yaml file.
+ - For fields presenting a static list of options (e.g. a list of buttons or a select field) the options can be defined in the localization Yaml file.
+
+It's a simple set of responsibilities, but putting them all together in one place cleans up a lot of form view code. One of the most compelling features of this "field partials" approach is that they're just HTML in ERB templates using standard Rails form field helpers within the standard Rails `form_with` method. That means there are no "last mile" issues if you need to customize the markup being generated. There's no library to fork or classes to override.
+
+## The Complete Package
+Each field partial can optionally include whichever of the following are required to fully support it:
+
+ - **Controller assignment helper** to be used alongside Strong Parameters to convert whatever is submitted in the form to the appropriate ActiveRecord attribute value.
+ - **Turbo-compatible JavaScript invocation** of any third-party library that helps support the field partial.
+ - **Theme-compatible styling** to ensure any third-party libraries "fit in".
+ - **Capybara testing helper** to ensure it's easy to inject values into a field partial in headless browser tests.
+
+## Basic Usage
+The form field partials are designed to be a 1:1 match for [the native Rails form field helpers](https://guides.rubyonrails.org/form_helpers.html) developers are already used to using. For example, consider the following basic Rails form field helper invocation:
+
+```
+<%= form.text_field :text_field_value, autofocus: true %>
+```
+
+Using the field partials, the same field would be implemented as follows:
+
+```
+<%= render 'shared/fields/text_field', form: form, method: :text_field_value, options: {autofocus: true} %>
+```
+
+At first blush it might look like a more verbose invocation, but that doesn't take into account that the first vanilla Rails example doesn't handle the field label or any other related functionality.
+
+Breaking down the invocation:
+
+ - `text_field` matches the name of the native Rails form field helper we want to invoke.
+ - The `form` option passes a reference to the form object the field will exist within.
+ - The `method` option specifies which attribute of the model the field represents, in the same way as the first parameter of the basic Rails `text_field` helper.
+ - The `options` option is basically a passthrough, allowing you to specify options which will passed directly to the underlying Rails form field helper.
+
+The 1:1 relationship between these field partials and their underlying Rails form helpers is an important design decision. For example, the way `options` is passed through to native Rails form field helpers means that experienced Rails developers will still be able to leverage what they remember about using Rails, while those of us who don't readily remember all the various options of those helpers can make use of [the standard Rails documentation](https://guides.rubyonrails.org/form_helpers.html) and the great wealth of Rails code examples available online and still take advantage of these field partials. That means the amount of documentation we need to maintain for these field partials is strictly for those features that are in addition to what Rails provides by default.
+
+Individual field partials might have additional options available based on the underlying Rails form field helper. Links to the documentation for individual form field partials are listed at the end of this page.
+
+## `options` vs. `other_options`
+
+Because Bullet Train field partials have more responsibilities than the underlying Rails form field helpers, there are also additional options for things like hiding labels, displaying specific error messages, etc. For these options, we pass them separately as `other_options`. This keeps them separate from the options in `options` that will be passed directly to the underlying Rails form field helper.
+
+For example, to suppress a label on any field, we can use the `hide_label` option like so:
+
+```
+<%= render 'shared/fields/text_field', form: form, method: :text_field_value, other_options: {hide_label: true} %>
+```
+
+### Globally-Available `other_options` Options
+
+| Key | Value Type | Description |
+| --- | --- | --- |
+| `help` | string | Display a specific help string. |
+| `error` | string | Display a specific error string. |
+| `hide_label` | boolean | Hide the field label. |
+
+## Reducing Repetition
+When you're including multiple fields, you can DRY up redundant settings (e.g. `form: form`) like so:
+
+```
+<% with_field_settings form: form do %>
+  <%= render 'shared/fields/text_field', method: :text_field_value, options: {autofocus: true} %>
+  <%= render 'shared/fields/buttons', method: :button_value %>
+  <%= render 'shared/fields/cloudinary_image', method: :cloudinary_image_value %>
+<% end %>
+```
+
+## Field partials that integrate with third-party service providers
+ - `cloudinary` makes it trivial to upload photos and images to [Cloudinary](https://cloudinary.com) and store their resulting Cloudinary ID as an attribute of the model backing the form.
+
+## Yaml Configuration
+The localization Yaml file (where you configure label and option values for a field) is automatically generated when you run Super Scaffolding for a model. If you haven't done this yet, the localization Yaml file for `Scaffolding::CompletelyConcrete::TangibleThing` serves as a good example. Under `en.scaffolding/completely_concrete/tangible_things.fields` you'll see definitions like this:
+
+<pre><code>text_field_value:
+  name: &text_field_value Text Field Value
+  label: *text_field_value
+  heading: *text_field_value
+</code></pre>
+
+This might look redundant at first glance, as you can see that by default the same label ("Text Field Value") is being used for both the form field label (`label`) and the heading (`heading`) of the show view and table view. It's also used when the field is referred to in a validation error message. However, having these three values defined separately gives us the flexibility of defining much more user-friendly labels in the context of a form field. In my own applications, I'll frequently configure these form field labels to be much more verbose questions (in an attempt to improve the UX), but still use the shorter label as a column header on the table view and the show view:
+
+<pre><code>text_field_value:
+  name: &text_field_value Text Field Value
+  label: "What should the value of this text field be?"
+  heading: *text_field_value
+</code></pre>
+
+You can also configure some placeholder text (displayed in the field when in an empty state) or some inline help text (to be presented to users under the form field) like so:
+
+<pre><code>text_field_value:
+  name: &text_field_value Text Field Value
+  label: "What should the value of this text field be?"
+  heading: *text_field_value
+  placeholder: "Type your response here"
+  help: "The value can be anything you want it to be!"
+</code></pre>
+
+Certain form field partials like `buttons` and `super_select` can also have their selectable options configured in this Yaml file. See their respective documentation for details, as usage varies slightly.
+
+## Available Field Partials
+
+| Field Partial | Multiple Values? | Assignment Helpers | JavaScript Library | Description | Commercial License Required |
+| --- | --- | --- | --- | --- | --- |
+| `boolean` | | `assign_boolean` | | | |
+| [`buttons`](/docs/field-partials/buttons.md) | Optionally | `assign_checkboxes` | | | |
+| `cloudinary_image` | | | | | |
+| `color_picker` | | | [pickr](https://simonwep.github.io/pickr/) | | |
+| `date_and_time_field` | | `assign_date_and_time` | [Date Range Picker](https://www.daterangepicker.com) | | |
+| `date_field` | | `assign_date` | [Date Range Picker](https://www.daterangepicker.com) | | |
+| `email_field` | | | | | |
+| `file_field` | | | [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) | | |
+| `options` | Optionally | `assign_checkboxes` | | | |
+| `password_field` | | | | | |
+| `phone_field` | | | [International Telephone Input](https://intl-tel-input.com) | Ensures telephone numbers are in a format that can be used by providers like Twilio. | |
+| [`super_select`](/docs/field-partials/super-select.md) | Optionally | `assign_select_options` | [Select2](https://select2.org) | Provides powerful option search, AJAX search, and multi-select functionality. | |
+| `text_area` | | | | | |
+| `text_field` | | | | | |
+| `trix_editor` | | | [Trix](https://github.com/basecamp/trix) | Basic HTML-powered formatting features and support for at-mentions amongst team members. | |
+
+## Additional Field Partials Documentation
+ - [`buttons`](/docs/field-partials/buttons.md)
+ - [`super_select`](/docs/field-partials/super-select.md)

data/docs/font-awesome-pro.md

@@ -0,0 +1,50 @@
+# Font Awesome Pro
+
+By default, Bullet Train ships with both [Themify Icons](https://themify.me/themify-icons) and [Font Awesome Pro's Light icons](https://fontawesome.com/icons?d=gallery&s=light) preconfigured for each menu item. However, Font Awesome Pro is a [paid product](https://fontawesome.com/plans), so by default Bullet Train falls back to showing the Themify icons.
+
+In our experience, there is no better resource than Font Awesome Pro for finding the perfect icon for every model when you're using Super Scaffolding, so we encourage you to make the investment. Once you configure Font Awesome Pro in your environment, its icons will take precedence over the Themify Icons that were provided as a fallback.
+
+## Configuring Font Awesome Pro
+
+### 1. Set Authentication Token Environment Variable
+
+Once you buy a license for Font Awesome Pro, set `FONTAWESOME_NPM_AUTH_TOKEN` in your shell environment to be equal to your key as presented [on their instructions page](https://fontawesome.com/how-to-use/on-the-web/setup/using-package-managers). Unfortunately, it's not enough to simply set `FONTAWESOME_NPM_AUTH_TOKEN` in `config/application.yml` like you might be thinking, because that value won't be picked up when you run `yarn install`.
+
+#### If you're using **Bash**:
+- Add `export FONTAWESOME_NPM_AUTH_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` in `~/.bashrc`.
+- Restart your terminal.
+
+#### If you're using **zsh**:
+- Add `export FONTAWESOME_NPM_AUTH_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` in `~/.zshrc`.
+- Restart your terminal.
+
+If you're configuring this in another type of shell, please let us know what the steps are [in a new GitHub issue](http://github.com/bullet-train-co/bullet-train-tailwind-css/issues/new) and we'll add them here for others.
+
+### 2. Add `.npmrc` Configuration
+
+Create a `.npmrc` file in the root of your project if you don't already have one, and add the following to it:
+
+```
+@fortawesome:registry=https://npm.fontawesome.com/
+//npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_AUTH_TOKEN}
+```
+
+This will pull the environment variable in, but also be compatible with the way we need to supply this value when deploying to Heroku.
+
+### 3. Add Font Awesome Pro npm Package
+
+Once you've got your Font Awesome Pro authentication token configured, you can run:
+
+```
+yarn add @fortawesome/fontawesome-pro
+```
+
+No, that's not a typo. [That's the name of their company.](https://fortawesome.com) If you receive an error at this point, be sure you restarted your terminal, and reach out for help!
+
+### 4. Add Font Awesome Pro to the Asset Pipeline
+
+In `app/javascript/application.js`, below `require("@icon/themify-icons/themify-icons.css")`, add:
+
+```
+require("@fortawesome/fontawesome-pro/css/all.css")
+```

data/docs/getting-started.md

@@ -0,0 +1,55 @@
+# Getting Started
+
+## Starting a New Project
+
+Whether you want to build a new application with Bullet Train or contribute to Bullet Train itself, you should start by following the instructions on [the starter repository](https://github.com/bullet-train-co/bullet_train).
+
+## Basic Techniques
+
+If you're using Bullet Train for the first time, begin by learning these five important techniques:
+
+1. Use `rails g model` to create and `bin/super-scaffold` to scaffold a new model:
+
+    ```
+    $ rails g model Project team:references name:string
+    $ bin/super-scaffold crud Project Team name:text_field
+    ```
+
+    In this example, `Team` refers to the immediate parent of the `Project` resource. For more details, just run `bin/super-scaffold` or [read the documentation](https://github.com/bullet-train-co/bullet_train-base/blob/main/docs/super-scaffolding.md).
+
+2. Use `rails g migration` and `bin/super-scaffold` to add a new field to a model you've already scaffolded:
+
+    ```
+    $ rails g migration add_description_to_projects description:text
+    $ bin/super-scaffold crud-field Project description:trix_editor
+    ```
+
+    These first two points about Super Scaffolding are just the tip of the iceberg, so be sure to circle around and [read the full documentation](https://github.com/bullet-train-co/bullet_train-base/blob/main/docs/super-scaffolding.md).
+
+3. Figure out which ERB views are powering something you see in the UI by:
+
+    - Right clicking the element.
+    - Selecting "Inspect Element".
+    - Looking for the `<!--XRAY START ...-->` comment above the element you've selected.
+
+4. Figure out the full I18N translation key of any string on the page by adding `?show_locales=true` to the URL.
+
+5. Use `bin/resolve` to figure out where framework or theme things are coming from and eject them if you need to customize something locally:
+
+    ```
+    $ bin/resolve Users::Base
+    $ bin/resolve en.account.teams.show.header --open
+    $ bin/resolve shared/box --open --eject
+    ```
+
+    Also, for inputs that can't be provided on the shell, there's an interactive mode where you can paste them:
+
+    ```
+    $ bin/resolve --interactive --eject --open
+    ```
+
+    And then paste any input, e.g.:
+
+    ```
+    <!--XRAY START 73 /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-->
+    ```