bullet_train 1.6.30 → 1.6.31

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba0cb9d6382c0e48ac482c91eb3f207e449d0bed6c9f6f3f890fdf877aa0524f
-  data.tar.gz: bee546685c3ec81e9f6709792ae7c0ec68573ce3ada9828d3dd3fc2385826e9a
+  metadata.gz: 4f095a907ffb4c58ff8e8f719eea4b1e4f4b800cf0784e54578ce0373485b2cd
+  data.tar.gz: 14d1cc067198dce1abc19bbc3edbf6c79007a9f73b073e97ed9d6ad3ccab5839
 SHA512:
-  metadata.gz: 78a0773b19059db32d5b2e3ce35a0b53a185b4acff90b9908149e6446d5252d7b069cdecf4124793a468d4469a1e27a2d136a5ba5dc6937121badfdb2d786798
-  data.tar.gz: fc58e373848016ac408541771b382c08ae252151e3ef07a88dfee9fb860de22f91e6fc9da074695277e18958431a545e1859258c0ecd84171ed177d1ea8f0777
+  metadata.gz: 57f1ed1e18979735a4801a02fe386e252c7b10c52d5619ab2c065b0a56aa0510c0c2bbfc81a43200ad4f88f644705ec9478cde3d09ef898a5ea60c42f85611a4
+  data.tar.gz: 9792cf9800fcbfe7c72a80ccf07723447ad2444fd084097632c31dd5292c033c71d20aabc441419ac8e700380d8c774cf1f5b266e591355ff49ed1f0c1380ee1

data/app/mailers/concerns/mailers/base.rb

@@ -12,6 +12,6 @@ module Mailers::Base
     helper "account/users"
     helper "account/locale"
     helper "fields/trix_editor"
-    helper "theme"
+    helper "current_theme"
   end
 end

data/docs/themes/on-jumpstart-pro-projects.md

@@ -0,0 +1,488 @@
+# Installing Bullet-Train Themes on Jumpstart PRO Projects
+
+Bullet Train themes can be installed on Jumpstart PRO projects, giving you native `erb` partials and Hotwire-powered UI components.
+
+Like Jumpstart PRO, Bullet Train themes are built using `tailwindcss` and use `esbuild` and `postcss` for JavaScript and style sheets.
+
+To get a quick sense of the UI components, we encourage you to spin up a Bullet Train project and navigate through the screens to create a "Creative Concept" and "Tangible Thing" resources.
+
+In addition to providing a nice set of UI components, you'll get access to [`nice_partials`](https://github.com/bullet-train-co/nice_partials), Bullet-Train's own lightweight answer for creating `erb` partials with ad-hoc named content areas, which we think is just the right amount of magic for making `erb`-based components.
+
+Note: we also have [instructions for installing themes on other Rails projects](on-other-rails-projects.md).
+
+**Contents:**
+
+1. Installation Instructions
+2. Optional Configurations for switching colors, theme gems
+3. Using Locales for fields on new models
+4. Partials that require special instructions, exclusions
+5. Modifying ejected partials
+
+## 1. Installation Instructions
+
+### Add the theme gem
+
+These instructions assume you're installing the `Light` theme bundled with Bullet Train.
+
+```
+bundle add bullet_train-themes-light
+```
+
+Or add the following to your `Gemfile`:
+
+```
+gem "bullet_train-themes-light"
+```
+
+And then run:
+
+```
+bundle install
+```
+
+### Add `npm` packages
+
+The `Light` theme requires the following npm packages to be installed
+
+```
+yarn add @bullet-train/bullet-train @bullet-train/fields autoprefixer @rails/actiontext postcss-extend-rule
+```
+
+Update your `app/javascript/controllers/index.js` with the following lines:
+
+```js
+import { controllerDefinitions as bulletTrainControllers } from "@bullet-train/bullet-train"
+import { controllerDefinitions as bulletTrainFieldControllers } from "@bullet-train/fields"
+
+application.load(bulletTrainControllers)
+application.load(bulletTrainFieldControllers)
+```
+
+### Add `bin/theme` and `bin/link` bin stubs
+
+```
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/bin/theme" -o bin/theme
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/bin/link" -o bin/link
+chmod +x bin/theme bin/link
+```
+
+### Update `esbuild.config.mjs`
+
+Replace it with these contents.
+
+```js
+#!/usr/bin/env node
+
+// Esbuild is configured with 3 modes:
+//
+// `yarn build` - Build JavaScript and exit
+// `yarn build --watch` - Rebuild JavaScript on change
+// `yarn build --reload` - Reloads page when views, JavaScript, or stylesheets change. Requires a PORT to listen on. Defaults to 3200 but can be specified with PORT env var
+//
+// Minify is enabled when "RAILS_ENV=production"
+// Sourcemaps are enabled in non-production environments
+
+import * as esbuild from "esbuild"
+import path from "path"
+import { execSync } from "child_process"
+import rails from "esbuild-rails"
+import chokidar from "chokidar"
+import http from "http"
+import { setTimeout } from "timers/promises"
+
+let themeFile = ""
+if (process.env.THEME) {
+  themeFile = execSync(`bundle exec bin/theme javascript ${process.env.THEME}`).toString().trim()
+}
+
+const themeEntrypoints = {}
+if (process.env.THEME) {
+  themeEntrypoints[`application.${process.env.THEME}`] = themeFile
+}
+
+const clients = []
+const entryPoints = {
+  "application": path.join(process.cwd(), "app/javascript/application.js"),
+  "administrate": path.join(process.cwd(), "app/javascript/administrate.js"),
+  ...themeEntrypoints,
+}
+const watchDirectories = [
+  "./app/javascript/**/*.js",
+  "./app/views/**/*.html.erb",
+  "./app/assets/builds/**/*.css", // Wait for cssbundling changes
+  "./config/locales/**/*.yml",
+]
+const config = {
+  absWorkingDir: path.join(process.cwd(), "app/javascript"),
+  bundle: true,
+  entryPoints: entryPoints,
+  minify: process.env.RAILS_ENV == "production",
+  outdir: path.join(process.cwd(), "app/assets/builds"),
+  plugins: [rails()],
+  sourcemap: process.env.RAILS_ENV != "production",
+  define: {
+    global: "window"
+  },
+  loader: {
+    ".png": "file",
+    ".jpg": "file",
+    ".svg": "file",
+    ".woff": "file",
+    ".woff2": "file",
+    ".ttf": "file",
+    ".eot": "file",
+  }
+}
+
+async function buildAndReload() {
+  // Foreman & Overmind assign a separate PORT for each process
+  const port = parseInt(process.env.PORT || 3200)
+  console.log(`Esbuild is listening on port ${port}`)
+  const context = await esbuild.context({
+    ...config,
+    banner: {
+      js: ` (() => new EventSource("http://localhost:${port}").onmessage = () => location.reload())();`,
+    }
+  })
+
+  // Reload uses an HTTP server as an even stream to reload the browser
+  http
+    .createServer((req, res) => {
+      return clients.push(
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          "Access-Control-Allow-Origin": "*",
+          Connection: "keep-alive",
+        })
+      )
+    })
+    .listen(port)
+
+  await context.rebuild()
+  console.log("[reload] initial build succeeded")
+
+  let ready = false
+  chokidar
+    .watch(watchDirectories)
+    .on("ready", () => {
+      console.log("[reload] ready")
+      ready = true
+    })
+    .on("all", async (event, path) => {
+      if (ready === false)  return
+
+      if (path.includes("javascript")) {
+        try {
+          await setTimeout(20)
+          await context.rebuild()
+          console.log("[reload] build succeeded")
+        } catch (error) {
+          console.error("[reload] build failed", error)
+        }
+      }
+      clients.forEach((res) => res.write("data: update\n\n"))
+      clients.length = 0
+    })
+}
+
+if (process.argv.includes("--reload")) {
+  buildAndReload()
+} else if (process.argv.includes("--watch")) {
+  let context = await esbuild.context({...config, logLevel: 'info'})
+  context.watch()
+} else {
+  esbuild.build(config)
+}
+```
+
+### Update `tailwind.config.js`
+
+Replace with these contents, which merge the Bullet Train-specific tailwind configs with those of Jumpstart PRO.
+
+_Note: After this step, you might get an error on build about a missing `process.env.THEME`. Follow with the next step to fix this error._
+
+```js
+const path = require('path');
+const { execSync } = require("child_process");
+const glob  = require('glob').sync
+
+if (!process.env.THEME) {
+  throw "tailwind.config.js: missing process.env.THEME"
+  process.exit(1)
+}
+  
+const themeConfigFile = execSync(`bundle exec bin/theme tailwind-config ${process.env.THEME}`).toString().trim()
+let themeConfig = require(themeConfigFile)
+
+const colors = require('tailwindcss/colors')
+const defaultTheme = require('tailwindcss/defaultTheme')
+
+themeConfig.darkMode = 'class'
+
+themeConfig.plugins.push(require('@tailwindcss/aspect-ratio'))
+
+themeConfig.content = [
+  ...new Set([
+    ...themeConfig.content,
+    './app/components/**/*.rb',
+    './app/helpers/**/*.rb',
+    './app/javascript/**/*.js',
+    './app/views/**/*.erb',
+    './app/views/**/*.haml',
+    './app/views/**/*.slim',
+    './lib/jumpstart/app/views/**/*.erb',
+    './lib/jumpstart/app/helpers/**/*.rb'
+  ])
+]
+
+themeConfig.theme.extend.colors = {
+  ...themeConfig.theme.extend.colors,
+  primary: colors.blue,
+  secondary: colors.emerald,
+  tertiary: colors.gray,
+  danger: colors.red,
+  gray: colors.neutral,
+  "code-400": "#fefcf9",
+  "code-600": "#3c455b",
+}
+
+themeConfig.theme.extend.fontFamily = {
+  ...themeConfig.theme.extend.fontFamily,
+  sans: ['Inter', ...defaultTheme.fontFamily.sans],
+}
+
+module.exports = themeConfig
+```
+
+### Update `build:css` in `package.json`
+
+In `package.json`, replace the `build` and `build:css` entries under `scripts` with:
+
+```json
+"build": "THEME=\"light\" node esbuild.config.mjs",
+"build:css": "bin/link; THEME=\"light\" tailwindcss --postcss --minify -c ./tailwind.config.js -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.tailwind.css",
+```
+
+### Add `stylesheet_link_tag` to `<head>`
+
+Make sure you have the following three lines in your `<head>`, which should be defined in `app/views/layouts/application.html.erb`:
+
+```erb
+<%= stylesheet_link_tag "application", media: "all", "data-turbo-track": "reload" %>
+<%= stylesheet_link_tag "application.tailwind", media: "all", "data-turbo-track": "reload" %>
+<%= javascript_include_tag 'application.light', 'data-turbo-track': 'reload' %>
+```
+
+### Update `postcss.config.js`
+
+Replace with these contents:
+
+```js
+const { execSync } = require("child_process");
+
+const postcssImportConfigFile = execSync(`bundle exec bin/theme postcss-import-config ${process.env.THEME}`).toString().trim()
+const postcssImportConfig = require(postcssImportConfigFile)
+
+module.exports = {
+  plugins: [
+    require('postcss-import')(postcssImportConfig),
+    require('postcss-extend-rule'),
+    require('tailwindcss/nesting'),
+    require('tailwindcss'),
+    require('autoprefixer')
+  ]
+}
+```
+
+### Import the Theme Style Sheet
+
+To your `application.tailwind.css` file, add the following line:
+
+```css
+@import "$ThemeStylesheetsDir/application.css";
+```
+
+### Add Themify Icons, jQuery (for now) and trix editor support
+
+Note: jQuery is needed for some of our components, but defining `window.$` won't be required soon. See PR https://github.com/bullet-train-co/bullet_train-core/pull/765
+
+```
+yarn add @icon/themify-icons jquery
+```
+
+To your `application.js`, add the following line:
+
+```js
+import jquery from "jquery"
+window.jQuery = jquery
+window.$ = jquery
+
+require("@icon/themify-icons/themify-icons.css")
+
+import { trixEditor } from "@bullet-train/fields"
+trixEditor()
+```
+
+### Add Locale Strings
+
+Add these to your `config/locales/en.yml` under `en:`
+
+```yml
+  date:
+    formats:
+      date_field: "%m/%d/%Y"
+      date_and_time_field: "%m/%d/%Y %l:%M %p"
+      date_controller: "MM/DD/YYYY"
+  time:
+    am: AM
+    pm: PM
+    formats:
+      date_field: "%m/%d/%Y"
+      date_and_time_field: "%m/%d/%Y %l:%M %p"
+      date_controller: "MM/DD/YYYY h:mm A"
+  daterangepicker:
+    firstDay: 1
+    separator: " - "
+    applyLabel: "Apply"
+    cancelLabel: "Cancel"
+    fromLabel: "From"
+    toLabel: "To"
+    customRangeLabel: "Custom"
+    weekLabel: "W"
+    daysOfWeek:
+    - "Su"
+    - "Mo"
+    - "Tu"
+    - "We"
+    - "Th"
+    - "Fr"
+    - "Sa"
+    monthNames:
+    - "January"
+    - "February"
+    - "March"
+    - "April"
+    - "May"
+    - "June"
+    - "July"
+    - "August"
+    - "September"
+    - "October"
+    - "November"
+    - "December"
+  date_range_controller:
+    today: Today
+    yesterday: yesterday
+    last7Days: Last 7 Days
+    last30Days: Last 30 Days
+    thisMonth: This Month
+    lastMonth: Last Month
+  global:
+    buttons:
+      other: Other
+      cancel: Cancel
+    bulk_select:
+      all: All
+```
+
+### Disable `display: block` on `label` elements
+
+In `app/assets/stylesheets/components/forms.css`, find the line under `label {`:
+
+```css
+@apply block text-sm font-medium leading-5 text-gray-700 mb-1;
+```
+
+And remove the `block` token:
+
+```css
+@apply text-sm font-medium leading-5 text-gray-700 mb-1;
+```
+
+## 2. Optional Configurations for switching colors, theme gems
+
+### For Setting the Active Color
+
+```
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/initializers/theme.rb" -o initializers/theme.rb
+```
+
+Add the following classes to your `html` tag for your layout:
+
+```erb
+<html class="theme-<%= BulletTrain::Themes::Light.color %> <%= "theme-secondary-#{BulletTrain::Themes::Light.secondary_color}" if BulletTrain::Themes::Light.secondary_color %>"
+```
+
+### For Switching Between Installed Themes
+
+If you'd like to create your own theme but would still like to build on top of `:light`, you'll need to have both gems installed and you'll be able to switch the current theme this way.
+
+Define `current_theme` in `app/helpers/application_helper.rb`
+
+```
+module ApplicationHelper
+  def current_theme
+    :light
+  end
+end
+```
+
+To change to use a different theme:
+
+1. Change the value returned by `current_theme` to the new theme name
+2. Change the name of the `THEME` env var defined in `build` and `build:css` in `package.json`
+3. Change the name of the theme in the `javascript_include_tag` in the `<head>`.
+
+## 3. Using Locales for fields on new models
+
+The theme's field partials work best with locale strings that are defined for the model you're creating.
+
+Example: you've created a Project model. Here we'll create a `projects.en.yml`
+
+1. Run `curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train-core/main/bullet_train-super_scaffolding/config/locales/en/scaffolding/completely_concrete/tangible_things.en.yml" -o config/locales/projects.en.yml`
+2. Search and replace `projects.en.yml` for `scaffolding/completely_concrete/tangible_things`, `Tangible Things`, `Tangible Thing`, `tangible_things` and `tangible_thing`. Replace with `projects`, `Projects`, `Project`, `projects` and `project` respectively.
+3. Remove strings you won't be using. In particular, look for comments with "skip" or "scaffolding".
+
+Some fields use locale strings to drive their `options`. In the `tangible_things.en.yml` template file, look for `super_select_value`, `multiple_option_values` and others.
+
+You'll notice `&` and `*` symbols prefixing some special keys in the `yml` file. Those are anchors and aliases and they help you reduce repetition in your locale strings.
+
+To learn more about how these locales are generated in Bullet Train, see the documentation on [Bullet Train's Super Scaffolding](/docs/super-scaffolding.md)
+
+## 4. Partials that require special instructions, exclusions
+
+### For using boolean-type fields (options, buttons)
+
+In `ApplicationController`, add this:
+
+```ruby
+include Fields::ControllerSupport
+```
+
+### For the file_field partial
+
+```ruby
+# in the model
+has_one_attached :file_field_value
+after_validation :remove_file_field_value, if: :file_field_value_removal?
+attr_accessor :file_field_value_removal
+def file_field_value_removal?
+def remove_file_field_value
+```
+
+```ruby
+# in the controller's strong_params
+:file_field_value,
+:file_field_value_removal,
+```
+
+### For `image`, `active_storage_image`
+
+See [`account/users_helper` in BT core repo](https://github.com/bullet-train-co/bullet_train-core/blob/main/bullet_train/app/helpers/account/users_helper.rb) for implementing `photo_url_for_active_storage_attachment`
+
+## 5. Modifying ejected partials
+
+### For ejecting a theme partial and modifying it
+
+We recommend firing up a Bullet-Train project and using its `bin/resolve` (see docs on [Indirection](indirection)) to get a copy of the partial field locally to modify.

data/docs/themes/on-other-rails-projects.md

@@ -0,0 +1,301 @@
+# Installing Bullet-Train Themes on Other Rails Projects
+
+Bullet Train themes can be installed on Vanilla Rails projects.
+
+Our main theme, called `Light`, uses `erb` partials to give you native Rails views with Hotwire-powered components. It's built on `tailwindcss`, uses `postcss` to allow for local CSS overrides and uses `esbuild` for fast javascript compilation and to support javascript-side CSS imports.
+
+In addition to providing a nice set of UI components, you'll get access to [`nice_partials`](https://github.com/bullet-train-co/nice_partials), Bullet-Train's own lightweight answer for creating `erb` partials with ad-hoc named content areas, which we think is just the right amount of magic for making `erb`-based components.
+
+Note: we have [special instructions for installing themes on Jumpstart PRO projects](on-jumpstart-pro-projects.md).
+
+**Contents:**
+
+1. Installation Instructions
+2. Optional Configurations for switching colors, theme gems
+3. Using Locales for fields on new models
+4. Partials that require special instructions, exclusions
+5. Modifying ejected partials
+
+## 1. Installation Instructions
+
+### Ensure your Rails Project uses `esbuild` and `tailwindcss` with `postcss`
+
+You'll need to make sure your Rails project is set up to use `esbuild`, `tailwindcss` and `postcss`.
+
+The easiest way to see what your project should include is to create a separate project, for reference, generated via this command:
+
+```
+rails new rails-new-esbuild-tailwind-postcss --css tailwind --javascript esbuild
+```
+
+### Add the theme gem
+
+These instructions assume you're installing the `Light` theme bundled with Bullet Train.
+
+```
+bundle add bullet_train-themes-light
+```
+
+Or add the following to your `Gemfile`:
+
+```
+gem "bullet_train-themes-light"
+```
+
+And then run:
+
+```
+bundle install
+```
+
+### Add `npm` packages
+
+The `Light` theme requires the following npm packages to be installed
+
+```
+yarn add @bullet-train/bullet-train @bullet-train/fields autoprefixer @rails/actiontext postcss-extend-rule postcss-import
+```
+
+Update your `app/javascript/controllers/index.js` with the following lines:
+
+```js
+import { controllerDefinitions as bulletTrainControllers } from "@bullet-train/bullet-train"
+import { controllerDefinitions as bulletTrainFieldControllers } from "@bullet-train/fields"
+
+application.load(bulletTrainControllers)
+application.load(bulletTrainFieldControllers)
+```
+
+### Overwrite tailwind and esbuild config files, add bin stubs from Bullet Train
+
+```
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/esbuild.config.js" -o esbuild.config.js
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/postcss.config.js" -o postcss.config.js
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/tailwind.config.js" -o tailwind.config.js
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/bin/theme" -o bin/theme
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/bin/link" -o bin/link
+chmod +x bin/theme bin/link
+
+```
+
+### Update `build:css` in `package.json`
+
+In `package.json`, replace the `build` and `build:css` entries under `scripts` with:
+
+```json
+"build": "THEME=\"light\" node esbuild.config.js",
+"build:css": "bin/link; THEME=\"light\" tailwindcss --postcss --minify -c ./tailwind.config.js -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.tailwind.css"
+```
+### Update esbuild.config.js
+
+Remove or comment out the following line from `esbuild.config.js`:
+
+```js
+"intl-tel-input-utils": path.join(process.cwd(), "app/javascript/intl-tel-input-utils.js"),
+```
+
+### Add `stylesheet_link_tag` to `<head>`
+
+Make sure you have the following three lines in your `<head>`, which should be defined in `app/views/layouts/application.html.erb`:
+
+```erb
+<%= stylesheet_link_tag "application", media: "all", "data-turbo-track": "reload" %>
+<%= stylesheet_link_tag "application.tailwind", media: "all", "data-turbo-track": "reload" %>
+<%= javascript_include_tag 'application.light', 'data-turbo-track': 'reload' %>
+```
+
+### Import the Theme Style Sheet
+
+To your `application.tailwind.css` file, add the following line:
+
+```css
+@import "$ThemeStylesheetsDir/application.css";
+```
+
+Also be sure to replace the following lines:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+To the following lines:
+
+```css
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";
+```
+
+Unless this is done, `postcss-import` doesn't work correctly.
+
+### Add Themify Icons, jQuery (for now) and trix editor support
+
+Note: jQuery is needed for some of our components, but defining `window.$` won't be required soon. See PR https://github.com/bullet-train-co/bullet_train-core/pull/765
+
+```
+yarn add @icon/themify-icons jquery
+```
+
+To your `application.js`, add the following line:
+
+```js
+import jquery from "jquery"
+window.jQuery = jquery
+window.$ = jquery
+
+require("@icon/themify-icons/themify-icons.css")
+
+import { trixEditor } from "@bullet-train/fields"
+trixEditor()
+```
+
+### Add Locale Strings
+
+Add these to your `config/locales/en.yml` under `en:`
+
+```yml
+  date:
+    formats:
+      date_field: "%m/%d/%Y"
+      date_and_time_field: "%m/%d/%Y %l:%M %p"
+      date_controller: "MM/DD/YYYY"
+  time:
+    am: AM
+    pm: PM
+    formats:
+      date_field: "%m/%d/%Y"
+      date_and_time_field: "%m/%d/%Y %l:%M %p"
+      date_controller: "MM/DD/YYYY h:mm A"
+  daterangepicker:
+    firstDay: 1
+    separator: " - "
+    applyLabel: "Apply"
+    cancelLabel: "Cancel"
+    fromLabel: "From"
+    toLabel: "To"
+    customRangeLabel: "Custom"
+    weekLabel: "W"
+    daysOfWeek:
+    - "Su"
+    - "Mo"
+    - "Tu"
+    - "We"
+    - "Th"
+    - "Fr"
+    - "Sa"
+    monthNames:
+    - "January"
+    - "February"
+    - "March"
+    - "April"
+    - "May"
+    - "June"
+    - "July"
+    - "August"
+    - "September"
+    - "October"
+    - "November"
+    - "December"
+  date_range_controller:
+    today: Today
+    yesterday: yesterday
+    last7Days: Last 7 Days
+    last30Days: Last 30 Days
+    thisMonth: This Month
+    lastMonth: Last Month
+  global:
+    buttons:
+      other: Other
+      cancel: Cancel
+    bulk_select:
+      all: All
+```
+
+## 2. Optional Configurations for switching colors, theme gems
+
+### For Setting the Active Color
+
+```
+curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train/main/initializers/theme.rb" -o initializers/theme.rb
+```
+
+Add the following classes to your `html` tag for your layout:
+
+```erb
+<html class="theme-<%= BulletTrain::Themes::Light.color %> <%= "theme-secondary-#{BulletTrain::Themes::Light.secondary_color}" if BulletTrain::Themes::Light.secondary_color %>"
+```
+
+### For Switching Between Installed Themes
+
+If you'd like to create your own theme but would still like to build on top of `:light`, you'll need to have both gems installed and you'll be able to switch the current theme this way.
+
+Define `current_theme` in `app/helpers/application_helper.rb`
+
+```
+module ApplicationHelper
+  def current_theme
+    :light
+  end
+end
+```
+
+To change to use a different theme:
+
+1. Change the value returned by `current_theme` to the new theme name
+2. Change the name of the `THEME` env var defined in `build` and `build:css` in `package.json`
+3. Change the name of the theme in the `javascript_include_tag` in the `<head>`.
+
+## 3. Using Locales for fields on new models
+
+The theme's field partials work best with locale strings that are defined for the model you're creating.
+
+Example: you've created a Project model. Here we'll create a `projects.en.yml`
+
+1. Run `curl -L "https://raw.githubusercontent.com/bullet-train-co/bullet_train-core/main/bullet_train-super_scaffolding/config/locales/en/scaffolding/completely_concrete/tangible_things.en.yml" -o config/locales/projects.en.yml`
+2. Search and replace `projects.en.yml` for `scaffolding/completely_concrete/tangible_things`, `Tangible Things`, `Tangible Thing`, `tangible_things` and `tangible_thing`. Replace with `projects`, `Projects`, `Project`, `projects` and `project` respectively.
+3. Remove strings you won't be using. In particular, look for comments with "skip" or "scaffolding".
+
+Some fields use locale strings to drive their `options`. In the `tangible_things.en.yml` template file, look for `super_select_value`, `multiple_option_values` and others.
+
+You'll notice `&` and `*` symbols prefixing some special keys in the `yml` file. Those are anchors and aliases and they help you reduce repetition in your locale strings.
+
+To learn more about how these locales are generated in Bullet Train, see the documentation on [Bullet Train's Super Scaffolding](/docs/super-scaffolding.md)
+
+## 4. Partials that require special instructions, exclusions
+
+### For using boolean-type fields (options, buttons)
+
+In `ApplicationController`, add this:
+
+```ruby
+include Fields::ControllerSupport
+```
+
+### For the file_field partial
+
+```ruby
+# in the model
+has_one_attached :file_field_value
+after_validation :remove_file_field_value, if: :file_field_value_removal?
+attr_accessor :file_field_value_removal
+def file_field_value_removal?
+def remove_file_field_value
+```
+
+```ruby
+# in the controller's strong_params
+:file_field_value,
+:file_field_value_removal,
+```
+
+### For `image`, `active_storage_image`
+
+See [`account/users_helper` in BT core repo](https://github.com/bullet-train-co/bullet_train-core/blob/main/bullet_train/app/helpers/account/users_helper.rb) for implementing `photo_url_for_active_storage_attachment`
+
+## 5. Modifying ejected partials
+
+### For ejecting a theme partial and modifying it
+
+We recommend firing up a Bullet-Train project and using its `bin/resolve` (see docs on [Indirection](indirection)) to get a copy of the partial field locally to modify.

data/docs/themes.md

@@ -79,3 +79,8 @@ This allows the theme engine to resolve which theme in the inheritance chain wil
 ### Let your designer name their theme.
 
 You're going to have to call your theme something and there are practical reasons to not call it something generic. If you're pursuing a heavily customized design, consider allowing the designer or designers who are creating the look-and-feel of your application to name their own masterpiece. Giving it a distinct name will really help differentiate things when you're ready to start introducing additional facets to your application or a totally new look-and-feel down the road.
+
+## Additional Themes Documentation
+
+* [Installing Bullet-Train Themes on Other Rails Projects](/docs/themes/on-other-rails-projects.md)
+* [Installing Bullet-Train Themes on Jumpstart PRO Projects](/docs/themes/on-jumpstart-pro-projects.md)

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.6.30"
+  VERSION = "1.6.31"
 end

data/lib/tasks/bullet_train_tasks.rake

@@ -1,32 +1,5 @@
 require "io/wait"
 
-namespace :bt do
-  desc "Symlink registered gems in `./tmp/gems` so their views, etc. can be inspected by Tailwind CSS."
-  task link: :environment do
-    if Dir.exist?("tmp/gems")
-      puts "Removing previously linked gems."
-      `rm -f tmp/gems/*`
-    else
-      if File.exist?("tmp/gems")
-        raise "A file named `tmp/gems` already exists? It has to be removed before we can create the required directory."
-      end
-
-      puts "Creating 'tmp/gems' directory."
-      `mkdir tmp/gems`
-    end
-
-    `touch tmp/gems/.keep`
-
-    BulletTrain.linked_gems.each do |linked_gem|
-      target = `bundle show #{linked_gem}`.chomp
-      if target.present?
-        puts "Linking '#{linked_gem}' to '#{target}'."
-        `ln -s #{target} tmp/gems/#{linked_gem}`
-      end
-    end
-  end
-end
-
 namespace :bullet_train do
   desc "Figure out where something is coming from."
   task :resolve, [:all_options] => :environment do |t, arguments|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.6.30
+  version: 1.6.31
 platform: ruby
 authors:
 - Andrew Culver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-07 00:00:00.000000000 Z
+date: 2024-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard
@@ -539,8 +539,6 @@ files:
 - app/controllers/registrations_controller.rb
 - app/controllers/sessions_controller.rb
 - app/helpers/account/buttons_helper.rb
-- app/helpers/account/dates_helper.rb
-- app/helpers/account/forms_helper.rb
 - app/helpers/account/invitations_helper.rb
 - app/helpers/account/locale_helper.rb
 - app/helpers/account/markdown_helper.rb
@@ -549,11 +547,9 @@ files:
 - app/helpers/account/role_helper.rb
 - app/helpers/account/teams_helper.rb
 - app/helpers/account/users_helper.rb
-- app/helpers/attributes_helper.rb
 - app/helpers/base_helper.rb
 - app/helpers/concerns/helpers/base.rb
 - app/helpers/email_helper.rb
-- app/helpers/images_helper.rb
 - app/helpers/invitation_only_helper.rb
 - app/helpers/invitations_helper.rb
 - app/javascript/controllers/bulk_action_form_controller.js
@@ -757,6 +753,8 @@ files:
 - docs/teams.md
 - docs/testing.md
 - docs/themes.md
+- docs/themes/on-jumpstart-pro-projects.md
+- docs/themes/on-other-rails-projects.md
 - docs/trademark.md
 - docs/tunneling.md
 - docs/upgrades.md

data/app/helpers/account/dates_helper.rb

@@ -1,70 +0,0 @@
-module Account::DatesHelper
-  def display_date(timestamp, custom_date_format = nil, format: :default, date_format: nil)
-    return nil unless timestamp
-    format = date_format if date_format
-
-    if format && format == :default
-      # e.g. October 11, 2018
-      if custom_date_format
-        local_time(timestamp).strftime(custom_date_format)
-      elsif local_time(timestamp).year == local_time(Time.now).year
-        local_time(timestamp).strftime("%B %-d")
-      else
-        local_time(timestamp).strftime("%B %-d, %Y")
-      end
-    else
-      localize(local_time(timestamp).to_date, format: format)
-    end
-  end
-
-  def display_time(timestamp, custom_time_format = nil, format: :default, time_format: nil)
-    return nil unless timestamp
-    format = time_format if time_format
-
-    if format && format == :default
-      # e.g. 4:22 PM
-      local_time(timestamp).strftime(custom_time_format || "%l:%M %p")
-    else
-      localize(local_time(timestamp).to_time, format: format)
-    end
-  end
-
-  def display_date_and_time(timestamp, custom_date_format = nil, custom_time_format = nil, format: :default, date_format: nil, time_format: nil)
-    return nil unless timestamp
-    format = "#{date_format} #{time_format}" if date_format && time_format
-
-    if format && format == :default
-      # e.g. Today at 4:22 PM
-      # e.g. Yesterday at 2:12 PM
-      # e.g. April 24 at 7:39 AM
-      # today?
-      if local_time(timestamp).to_date == local_time(Time.now).to_date
-        "Today at #{display_time(timestamp, custom_time_format)}"
-      # yesterday?
-      elsif (local_time(timestamp).to_date) == (local_time(Time.now).to_date - 1.day)
-        "Yesterday at #{display_time(timestamp, custom_time_format)}"
-      else
-        "#{display_date(timestamp, custom_date_format)} at #{display_time(timestamp, custom_time_format)}"
-      end
-    else
-      localize(local_time(timestamp).to_datetime, format: format)
-    end
-  end
-
-  def local_time(timestamp)
-    timestamp&.in_time_zone(current_user.time_zone)
-  end
-
-  def am_pm?
-    !"#{I18n.t("time.am", fallback: false, default: "")}#{I18n.t("time.pm", fallback: false, default: "")}".empty?
-  end
-
-  def time_zone_name_to_id
-    ActiveSupport::TimeZone.all.map { |tz| {tz.name.to_s => tz.tzinfo.name} }.reduce({}, :merge)
-  end
-
-  def current_time_zone
-    current_time_zone_name = current_user&.time_zone || current_user&.current_team&.time_zone || "UTC"
-    ActiveSupport::TimeZone.find_tzinfo(current_time_zone_name).name
-  end
-end

data/app/helpers/account/forms_helper.rb

@@ -1,65 +0,0 @@
-module Account::FormsHelper
-  PRESENCE_VALIDATORS = [ActiveRecord::Validations::PresenceValidator, ActiveModel::Validations::PresenceValidator]
-
-  def presence_validated?(object, attribute)
-    validators = object.class.validators
-    validators.select! do |validator|
-      PRESENCE_VALIDATORS.include?(validator.class) && validator.attributes.include?(attribute)
-    end
-    validators.any?
-  end
-
-  def flush_content_for(name)
-    content_for name, flush: true do
-      ""
-    end
-  end
-
-  def options_with_labels(options, namespace)
-    hash = {}
-    options.each do |option|
-      hash[option] = t([namespace, option].join("."))
-    end
-    hash
-  end
-
-  def if_present(string)
-    string.present? ? string : nil
-  end
-
-  def model_key(form)
-    form.object.class.name.pluralize.underscore
-  end
-
-  def labels_for(form, method)
-    keys = [:placeholder, :label, :help, :options_help]
-    path = [model_key(form), (current_fields_namespace || :fields), method].compact
-    Struct.new(*keys).new(*keys.map { |key| t((path + [key]).join("."), default: "").presence })
-  end
-
-  def options_for(form, method)
-    # e.g. "scaffolding/completely_concrete/tangible_things.fields.text_area_value.options"
-    path = [model_key(form), (current_fields_namespace || :fields), method, :options]
-    options = t(path.compact.join("."))
-    return options unless options.is_a?(Hash)
-    options.stringify_keys
-  end
-
-  def legacy_label_for(form, method)
-    # e.g. 'scaffolding/things.labels.name'
-    key = "#{model_key(form)}.labels.#{method}"
-    #  e.g. 'scaffolding/things.labels.name' or 'scaffolding.things.labels.name' or nil
-    t(key, default: "").presence || t(key.tr("/", "."), default: "").presence
-  end
-
-  def within_fields_namespace(namespace)
-    @fields_namespaces ||= []
-    @fields_namespaces << namespace
-    yield
-    @fields_namespaces.pop
-  end
-
-  def current_fields_namespace
-    @fields_namespaces&.last
-  end
-end

data/app/helpers/attributes_helper.rb

@@ -1,17 +0,0 @@
-module AttributesHelper
-  def current_attributes_object
-    @_current_attribute_settings&.dig(:object)
-  end
-
-  def current_attributes_strategy
-    @_current_attribute_settings&.dig(:strategy)
-  end
-
-  def with_attribute_settings(object: current_attributes_object, strategy: current_attributes_strategy)
-    old_attribute_settings = @_current_attribute_settings
-    @_current_attribute_settings = {object: object, strategy: strategy}
-    yield
-  ensure
-    @_current_attribute_settings = old_attribute_settings
-  end
-end

data/app/helpers/images_helper.rb

@@ -1,7 +0,0 @@
-module ImagesHelper
-  def image_width_for_height(filename, target_height)
-    source_width, source_height = FastImage.size("#{Rails.root}/app/assets/images/#{filename}")
-    ratio = source_width.to_f / source_height.to_f
-    (target_height * ratio).to_i
-  end
-end