plutonium 0.55.0 → 0.56.0

data/config/initializers/rabl.rb

@@ -2,9 +2,25 @@ require "rabl"
 
 # https://github.com/nesquena/rabl#configuration
 
+# RABL encodes its result hash with stdlib JSON by default, which serializes
+# Time/Date/BigDecimal via #to_s — e.g. a datetime becomes
+# "2026-06-04 13:46:18 UTC" instead of the ISO 8601 "2026-06-04T13:46:18.000Z"
+# that JSON clients expect. Routing values through ActiveSupport's #as_json
+# first yields JSON-optimized values (ISO 8601 datetimes, "YYYY-MM-DD" dates,
+# numeric-safe decimals, true/false booleans), then stdlib JSON.generate
+# encodes the now-primitive hash without escaping HTML entities in strings.
+module Plutonium
+  module RablJsonEngine
+    def self.dump(object)
+      JSON.generate(object.as_json)
+    end
+  end
+end
+
 Rabl.configure do |config|
   config.cache_sources = !Rails.env.development? # Defaults to false
   config.raise_on_missing_attribute = !Rails.env.production? # Defaults to false
+  config.json_engine = Plutonium::RablJsonEngine
 
   # config.cache_all_output = false
   # config.cache_engine = Rabl::CacheEngine.new # Defaults to Rails cache

data/docs/.vitepress/config.ts

@@ -119,6 +119,7 @@ export default defineConfig(withMermaid({
             { text: "Packages", link: "/reference/app/packages" },
             { text: "Portals", link: "/reference/app/portals" },
             { text: "Generators", link: "/reference/app/generators" },
+            { text: "Lite (SQLite) Generators", link: "/reference/generators/lite" },
           ]
         },
         {

data/docs/public/templates/lite.rb

@@ -4,6 +4,10 @@ after_bundle do
   git add: "."
   git commit: %( -m 'setup sqlite') if `git status --porcelain`.present?
 
+  generate "pu:lite:tune"
+  git add: "."
+  git commit: %( -m 'tune sqlite pragmas') if `git status --porcelain`.present?
+
   unless ENV["SKIP_SOLID_QUEUE"]
     generate "pu:lite:solid_queue"
     git add: "."
@@ -39,4 +43,10 @@ after_bundle do
     git add: "."
     git commit: %( -m 'add rails_pulse') if `git status --porcelain`.present?
   end
+
+  unless ENV["SKIP_SQLITE_MAINTENANCE"]
+    generate "pu:lite:maintenance"
+    git add: "."
+    git commit: %( -m 'add sqlite maintenance job') if `git status --porcelain`.present?
+  end
 end

data/docs/reference/generators/lite.md

@@ -0,0 +1,65 @@
+# Lite (SQLite) Generators
+
+The `pu:lite:*` generators configure a SQLite-first production stack. This page
+covers the two tuning/maintenance generators; the solid_queue / solid_cache /
+solid_cable / solid_errors / litestream / rails_pulse generators are run the
+same way (`rails g pu:lite:<name>`).
+
+## `pu:lite:tune`
+
+Adds tuned performance pragmas to the `default: &default` block of
+`config/database.yml`.
+
+```bash
+rails g pu:lite:tune
+```
+
+It writes a `pragmas:` mapping:
+
+- `cache_size: -64000` — 64 MB page cache (the ~2 MB default is too small).
+- `temp_store: 2` — MEMORY; sorts and temp indexes stay off disk.
+- `mmap_size: 536870912` — 512 MB memory-mapped I/O.
+- `wal_autocheckpoint: 10000` — checkpoint roughly every 40 MB of WAL.
+
+On Rails &lt; 8.1 it also writes the baseline pragmas (`journal_mode: WAL`,
+`synchronous: NORMAL`, `foreign_keys: true`, `journal_size_limit`) that Rails 8.1+
+already sets by default.
+
+**Why no `busy_timeout`?** Rails routes the `timeout:` key to the sqlite3 gem's
+constant-poll busy handler (`busy_handler_timeout`), which has better tail-latency
+than SQLite's internal exponential backoff. Setting a busy-timeout pragma would
+replace the better handler with the worse one, so this generator never emits it.
+
+The generator is idempotent — re-running it detects the existing pragmas and skips.
+It only ever touches the `default:` block, so a `pragmas:` mapping nested under
+another environment is left untouched.
+
+## `pu:lite:maintenance`
+
+Installs `app/jobs/sqlite_maintenance_job.rb` and (when `solid_queue` is present)
+schedules it in `config/recurring.yml`.
+
+```bash
+rails g pu:lite:maintenance
+# custom schedule:
+rails g pu:lite:maintenance --schedule="every day at 4am"
+```
+
+The job runs `PRAGMA optimize` on every configured SQLite database and `VACUUM`
+only on databases without live 24/7 writers (`primary`, `errors`, `rails_pulse`
+by default — edit `VACUUM_DBS` in the generated job to suit your app).
+
+**Why VACUUM only some databases?** SolidQueue, Solid Cache and Solid Cable write
+to their databases constantly. `VACUUM` takes a global *exclusive* lock for its
+whole duration, which stalls and errors those processes (e.g. SolidQueue process
+deregistration failing with "database is locked"). They also barely benefit: in
+WAL mode, freed pages land on the freelist and are reused, so a churning database
+stays at a steady-state size without nightly reclamation. `PRAGMA optimize`, which
+only takes a brief shared lock, still runs everywhere.
+
+Databases listed in the job that don't exist in `config/database.yml` are skipped
+at runtime, so the same job is safe regardless of which `pu:lite:*` generators you
+have run.
+
+If `solid_queue` is not installed, the job file is still created but not scheduled —
+add a `sqlite_maintenance` entry to whatever scheduler you use.

data/docs/reference/resource/definition.md

@@ -102,7 +102,7 @@ end
 | Text | `:string`, `:text`, `:email`, `:url`, `:tel`, `:password` |
 | Rich text | `:markdown` (EasyMDE editor) |
 | Numeric | `:number`, `:integer`, `:decimal`, `:range` |
-| Boolean | `:boolean` |
+| Boolean | `:toggle` / `:switch` (switch — **default** for boolean columns), `:boolean` (plain checkbox) |
 | Date/Time | `:date`, `:time`, `:datetime` |
 | Selection | `:select`, `:slim_select`, `:radio_buttons`, `:check_boxes` |
 | Files | `:file`, `:uppy`, `:attachment` |
@@ -111,7 +111,23 @@ end
 
 ### Display types (show / index)
 
-`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:color`
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:badge`, `:currency`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:color`
+
+#### Auto-inferred display formatting
+
+These render automatically — declare an `as:` only to override or pass options:
+
+| Column | Renders as | Notes |
+|---|---|---|
+| `boolean` | Yes/No pill (`:boolean`) | green "Yes" / neutral "No"; override with `true_label:` / `false_label:` |
+| `enum` | status badge (`:badge`) | known statuses auto-colored; unknown values get a stable decorative color; override per-value with `colors:` |
+| `has_cents` decimal | currency (`:currency`) | delimited, 2 decimals, **no symbol** unless you pass `unit:` (a literal `"£"` or a Symbol read off the record) |
+
+```ruby
+display :status, as: :badge, colors: {archived: :neutral, vip: :accent}
+display :price,  as: :currency, unit: "£"
+display :active, as: :boolean, true_label: "Live", false_label: "Off"
+```
 
 ## Field options
 

data/docs/reference/ui/assets.md

@@ -290,8 +290,22 @@ Ready-to-use styled components in `src/css/components.css`. **Prefer these over
 .pu-label / -required
 .pu-hint / .pu-error
 .pu-checkbox
+.pu-toggle                         (switch-styled checkbox)
 ```
 
+### Badges (status pills)
+
+```
+.pu-badge                          (base)
+.pu-badge-neutral / -primary / -secondary / -success / -danger / -warning / -info / -accent
+```
+
+```erb
+<span class="pu-badge pu-badge-success">Active</span>
+```
+
+Rendered automatically by the `:badge` display (enums) and `:boolean` display (Yes/No pills). See [Displays](./displays#built-in-display-components).
+
 ### Cards, panels, tables, toolbars, empty states
 
 ```

data/docs/reference/ui/displays.md

@@ -67,6 +67,30 @@ end
 
 See [Resource › Definition › Custom rendering](/reference/resource/definition#custom-rendering) for the full per-field rendering surface.
 
+## Built-in display components
+
+Some types render with richer components automatically — you only declare an `as:` to override or pass options.
+
+| `as:` | Renders | Auto-inferred for | Options |
+|-------|---------|-------------------|---------|
+| `:boolean` | green "Yes" / neutral "No" pill | `boolean` columns | `true_label:`, `false_label:` |
+| `:badge` | colored status pill | `enum` columns | `colors:` (per-value override) |
+| `:currency` | delimited, 2-decimal money | `has_cents` decimal accessors | `unit:`, `options:` |
+| `:color` | swatch + value | — | — |
+
+```ruby
+class OrderDefinition < ResourceDefinition
+  display :status,  as: :badge, colors: {refunded: :neutral, vip: :accent}
+  display :total,   as: :currency, unit: "£"
+  display :total,   as: :currency, unit: :currency_symbol   # Symbol → read off each record
+  display :shipped, as: :boolean,  true_label: "Sent", false_label: "Pending"
+end
+```
+
+**Badge colors.** Known statuses (`active`, `pending`, `failed`, …) are auto-colored by meaning. Unknown values get a stable decorative color (same value → same color). Override per-value with `colors:`; valid variants: `:neutral`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:accent`.
+
+**Currency.** No symbol is shown unless you pass `unit:` — a literal string (`"£"`) or a Symbol read off the record for per-row currencies. `has_cents` decimal accessors infer `:currency` automatically (still symbol-less until you set `unit:`).
+
 ## Theming
 
 Override the theme via a nested `Theme` class:
@@ -90,7 +114,9 @@ end
 
 ### Theme keys
 
-`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`.
+`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`, `boolean`, `badge`, `currency`, `color`.
+
+(`boolean` and `badge` apply their pill variant in the component, so their theme value stays empty — restyle the pills via the `.pu-badge*` classes instead.)
 
 ## Metadata panel
 

data/docs/reference/ui/forms.md

@@ -122,6 +122,7 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | `input_tag` | text (auto-detected type) |
 | `string_tag`, `text_tag`, `number_tag`, `email_tag`, `password_tag`, `url_tag`, `tel_tag`, `hidden_tag` | standard HTML inputs |
 | `checkbox_tag`, `select_tag`, `radio_button_tag` | standard |
+| `toggle_tag` / `switch_tag` | switch-styled boolean (`as: :toggle` / `:switch`) — the **default** for boolean columns; same behavior as a checkbox. Use `checkbox_tag` (`as: :boolean`) for a plain checkbox. |
 
 ### Plutonium-enhanced tags
 
@@ -239,7 +240,7 @@ Don't replace the theme wholesale — Plutonium's defaults handle invalid states
 
 ### Theme keys
 
-`base`, `fields_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `select`.
+`base`, `fields_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `toggle`, `select`.
 
 See [Assets › Phlexi component themes](./assets#phlexi-component-themes) for the underlying theme system.
 

data/docs/reference/ui/layouts.md

@@ -26,6 +26,39 @@ rails generate pu:eject:layout
 
 `pu:eject:layout` copies `layouts/resource.html.erb` for layout-level edits.
 
+## Navigation menu
+
+The sidebar/icon-rail navigation is built with `Phlexi::Menu::Builder` in the ejected `_resource_sidebar.html.erb`. Each `item` takes a `label`, plus `url:`, `icon:`, and optional `leading_badge:` / `trailing_badge:`:
+
+```erb
+<%= render Plutonium::UI::Layout::IconRail.new(
+      menu: Phlexi::Menu::Builder.new do |m|
+        m.item "Dashboard", url: root_path, icon: Phlex::TablerIcons::Home
+
+        m.item "Resources", icon: Phlex::TablerIcons::GridDots do |n|
+          registered_resources.each do |resource|
+            n.item resource_label(resource), url: resource_url_for(resource, parent: nil)
+          end
+        end
+      end
+    ) %>
+```
+
+### Per-item link attributes
+
+Any extra options you pass to `item` are spread straight onto the rendered `<a>` — so a menu entry can opt into `target`, `rel`, `data-*`, `aria-*`, etc. Useful for items that open in their own tab or drive a Stimulus/Turbo behavior:
+
+```ruby
+m.item "Inbox",
+  url: inbox_path,
+  icon: Phlex::TablerIcons::Mail,
+  target: "_blank",
+  rel: "noopener",
+  data: {turbo_frame: "_top"}
+```
+
+This works across both shells — the `:modern` icon-rail (leaf items, parent flyout triggers, and flyout children) and the `:classic` sidebar. Framework attributes always win on conflict: a custom `class:` is **merged** with the component's base classes, and on a parent trigger your `data:` / `aria:` merge with the flyout's own wiring (so you can't accidentally break the toggle). The `:active` key is reserved by Phlexi for [custom active-state logic](https://github.com/radioactive-labs/phlexi-menu) and is never emitted as an attribute.
+
 ## Custom layout class
 
 For full Phlex-level control over the layout: