plutonium 0.60.1 → 0.60.3

data/docs/reference/resource/definition.md

@@ -511,7 +511,12 @@ section :advanced, :seo_title, :notes,
   label: -> { object.new_record? ? "Set up" : "Advanced" }
 ```
 
-Empty sections (all fields filtered by the policy, or none assigned) are **not** hidden automatically. Use `condition:` to hide a section conditionally.
+A section that resolves to **zero fields** — every declared field filtered out by the permitted set, or no field assigned — renders nothing at all (no heading, no grid). This keeps forms clean when fewer attributes are permitted than declared (notably `+ New`, where the create policy often permits a subset). The check is purely "are there fields to render"; it does **not** evaluate per-field `condition:` procs (those run later, at field render). So if you want a whole section to appear only under some state, gate it with the section's own `condition:` rather than relying on every field inside it being hidden:
+
+```ruby
+section :shipping, :address, :city, :postcode,
+  condition: -> { object.requires_shipping? }   # hide the section as a unit
+```
 
 ### `ungrouped(**opts)`
 
@@ -564,7 +569,7 @@ end
 
 ### Fields not in the permitted set are skipped
 
-A `section` only renders the fields that are actually in the form's permitted set for the current request. A key it lists that isn't there — a typo, or a field excluded by policy, per-action `permitted_attributes`, entity scoping, or nesting — is **silently dropped**, never an error. This lets a single `form_layout` reference conditionally-permitted fields without crashing the form in the contexts where they're filtered out.
+A `section` only renders the fields that are actually in the form's permitted set for the current request. A key it lists that isn't there — a typo, or a field excluded by policy, per-action `permitted_attributes`, entity scoping, or nesting — is **silently dropped**, never an error. This lets a single `form_layout` reference conditionally-permitted fields without crashing the form in the contexts where they're filtered out. And when every field a section lists is dropped this way, the section's chrome is dropped with it (see the zero-fields note above) — so the same layout can serve a richly-permitted `edit` and a minimal `new` without leaving empty headings behind.
 
 ### On interactions
 

data/docs/reference/ui/layouts.md

@@ -18,15 +18,44 @@ If you're starting fresh, use `:modern`. `:classic` exists so apps upgrading fro
 
 ## Shell variants & the icon rail
 
-`config.shell` selects the chrome for the whole app:
+The shell variant selects the page chrome:
 
 - `:modern` (default) — Topbar plus the desktop icon rail.
-- `:plain` — Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the whole app is rail-less.
+- `:plain` — Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the surface is rail-less.
 - `:classic` — legacy Header/Sidebar (upgrade paths only).
 
-### Per-controller / per-portal override
+### Resolving the shell (global → engine → controller)
 
-Any Plutonium resource controller exposes a class-level `rail` DSL that overrides the shell default. It's a `class_attribute`, so it's inherited: a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern.
+The shell resolves across three layers, each overriding the one above it:
+
+```ruby
+# 1. Global default (config/initializers/plutonium.rb)
+Plutonium.configure { |config| config.shell = :modern }
+
+# 2. Per-engine — set it on a portal engine (lib/engine.rb)
+module CustomerPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      shell :plain   # this whole portal is rail-less
+    end
+  end
+end
+
+# 3. Per-controller — overrides the engine/global default for one controller (and subclasses)
+class DashboardController < ResourceController
+  shell :modern   # opt this controller back into the rail
+end
+```
+
+`shell` takes a plain symbol, so it's safe in the class body too — but the generated engine already has a `config.after_initialize` block (where `scope_to_entity` lives), so keeping it there is the consistent home.
+
+An unset engine/controller value (`nil`) falls through to the next layer. Read the resolved value with the `shell` helper (`controller.shell`).
+
+### `rail` — a controller-level rail toggle
+
+Alongside `shell`, any resource controller exposes a class-level `rail` DSL that flips just the icon rail without changing the shell. It's a `class_attribute`, so it's inherited — a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern:
 
 ```ruby
 module CustomerPortal
@@ -39,7 +68,7 @@ module CustomerPortal
 end
 ```
 
-`rail nil` (the default) inherits the shell default — the rail shows when `config.shell == :modern`. Read the resolved value with the `rail?` predicate.
+`rail nil` (the default) inherits the resolved shell — the rail shows when the resolved `shell == :modern`. Read the resolved value with the `rail?` predicate.
 
 ### Stable CSS hooks
 

data/lib/plutonium/core/controller.rb

@@ -47,7 +47,8 @@ module Plutonium
         helper_method :registered_resources
 
         class_attribute :_rail_enabled, instance_writer: false, default: nil
-        helper_method :rail?
+        class_attribute :_shell, instance_writer: false, default: nil
+        helper_method :rail?, :shell
       end
 
       class_methods do
@@ -56,6 +57,12 @@ module Plutonium
         def rail(enabled)
           self._rail_enabled = enabled
         end
+
+        # Set the shell variant for this controller and its subclasses,
+        # overriding the engine/global default. nil (default) inherits.
+        def shell(value)
+          self._shell = value
+        end
       end
 
       # Whether the modern icon rail is active for this request. Resolves the
@@ -63,7 +70,14 @@ module Plutonium
       # Public: the resource layout calls `controller.rail?`.
       def rail?
         return _rail_enabled unless _rail_enabled.nil?
-        Plutonium.configuration.shell == :modern
+        shell == :modern
+      end
+
+      def shell
+        return _shell unless _shell.nil?
+
+        engine = current_engine
+        (engine == Rails.application.class) ? Plutonium.configuration.shell : engine.shell
       end
 
       private

data/lib/plutonium/portal/engine.rb

@@ -10,6 +10,17 @@ module Plutonium
       included do
         isolate_namespace to_s.deconstantize.constantize
       end
+
+      class_methods do
+        # Shell variant for this portal's controllers (:modern / :plain /
+        # :classic). When unset it cascades live to the global
+        # Plutonium.configuration.shell; a controller's own `shell` overrides
+        # this in turn. Set with `shell :plain`, read with `shell`.
+        def shell(value = nil)
+          @shell = value unless value.nil?
+          @shell.nil? ? Plutonium.configuration.shell : @shell
+        end
+      end
     end
   end
 end

data/lib/plutonium/ui/form/components/section.rb

@@ -13,16 +13,26 @@ module Plutonium
             @grid_class = grid_class
           end
 
-          SECTION_CLASS = "space-y-4 border-t border-[var(--pu-border-muted)] pt-6 first:border-t-0 first:pt-0"
-          HEADING_CLASS = "text-base font-semibold text-[var(--pu-text)]"
-          SUMMARY_CLASS = "#{HEADING_CLASS} cursor-pointer select-none"
-          DESCRIPTION_CLASS = "text-sm text-[var(--pu-text-muted)]"
+          SECTION_CLASS = "space-y-5 border-t border-[var(--pu-border)] pt-7 first:border-t-0 first:pt-0"
+          # A short primary accent rule to the left of the heading — anchors the
+          # section and adds a touch of brand. Shared by the grouped <div> header
+          # and the collapsible <summary> so both read the same.
+          ACCENT_CLASS = "border-l-[3px] border-primary-500 pl-3.5"
+          HEADING_CLASS = "text-base font-semibold tracking-tight text-[var(--pu-text)]"
+          SUMMARY_CLASS = "#{HEADING_CLASS} #{ACCENT_CLASS} cursor-pointer select-none"
+          # font-normal resets the semibold inherited from a <summary> parent.
+          DESCRIPTION_CLASS = "mt-1 text-sm font-normal text-[var(--pu-text-muted)]"
 
           def view_template(&fields_block)
             if @section.collapsible?
               details(open: !@section.collapsed?, class: SECTION_CLASS) do
-                summary(class: SUMMARY_CLASS) { heading_text }
-                describe
+                # <summary> must be the first child of <details> and can't be
+                # wrapped, so the title text and its description both live inside
+                # it — keeping the description hugging the title under one accent.
+                summary(class: SUMMARY_CLASS) do
+                  plain heading_text
+                  describe
+                end
                 grid(&fields_block)
               end
             else
@@ -35,10 +45,15 @@ module Plutonium
 
           private
 
+          # Title + description grouped under one accented header so the
+          # description hugs the heading (mt-1) instead of inheriting the
+          # section's larger vertical rhythm.
           def header_block
             return if @section.ungrouped? && @section.options[:label].nil?
-            h3(class: HEADING_CLASS) { heading_text }
-            describe
+            div(class: ACCENT_CLASS) do
+              h3(class: HEADING_CLASS) { heading_text }
+              describe
+            end
           end
 
           def heading_text = @section.label

data/lib/plutonium/ui/form/resource.rb

@@ -122,6 +122,16 @@ module Plutonium
             condition = section.condition
             next if condition && !instance_exec(&condition)
 
+            # Drop sections left with no fields — e.g. every declared field was
+            # filtered out by the permitted set (policy, per-action, scoping,
+            # nesting). Rendering the chrome (heading + empty grid) for these
+            # litters the form with empty headings (notably on `+ New`, where
+            # fewer attributes are permitted than declared). Field-level
+            # `condition:` is evaluated later, at render — a section whose fields
+            # are all condition-hidden is the author's call to gate via the
+            # section's own `condition:`.
+            next if resolved.fields.empty?
+
             # `columns` stays a validated literal; everything else may be a proc.
             options = section.options.to_h do |key, value|
               [key, (key != :condition && value.is_a?(Proc)) ? instance_exec(&value) : value]

data/lib/plutonium/ui/layout/base.rb

@@ -52,7 +52,7 @@ module Plutonium
         #   signal) for non-classic shells, since Turbo Drive does not update
         #   <html> attributes across cross-URL visits.
         def render_pre_paint_scripts
-          manage_no_rail = Plutonium.configuration.shell != :classic
+          manage_no_rail = pre_paint_shell != :classic
           script do
             raw(safe(<<~JS))
               (function () {
@@ -80,6 +80,11 @@ module Plutonium
           end
         end
 
+        # Shell variant used by pre-paint scripts. Base uses the global config
+        # (safe for non-resource layouts whose controllers lack #shell);
+        # ResourceLayout overrides this to the resolved shell.
+        def pre_paint_shell = Plutonium.configuration.shell
+
         def render_body(&)
           body(**body_attributes) {
             render_before_main

data/lib/plutonium/ui/layout/resource_layout.rb

@@ -8,6 +8,12 @@ module Plutonium
         # the controller's resolution (shell default + per-controller `rail`).
         def rail? = controller.rail?
 
+        def shell = controller.shell
+
+        # Override Base's seam so all pre-paint shell logic uses the resolved
+        # (controller/engine/global) shell rather than only the global config.
+        def pre_paint_shell = shell
+
         # Sets pu-rail-pinned immediately on initial page load so the rail
         # renders in its pinned state from the first frame. Turbo navigations
         # are handled by the turbo:before-render listener in Base. Skipped
@@ -34,13 +40,13 @@ module Plutonium
         # Scoped to the modern family — :classic keeps its own offsets.
         def html_attributes
           attrs = super
-          return attrs if Plutonium.configuration.shell == :classic
+          return attrs if shell == :classic
 
           rail? ? attrs : mix(attrs, {class: "pu-no-rail"})
         end
 
         def main_attributes
-          classes = if Plutonium.configuration.shell == :classic
+          classes = if shell == :classic
             "pt-20 lg:ml-64"
           else
             rail? ? "pt-16 pb-6 px-6 lg:pl-20" : "pt-16 pb-6 px-6"

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.60.1"
+  VERSION = "0.60.3"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radioactive-labs/plutonium",
-  "version": "0.60.1",
+  "version": "0.60.3",
   "description": "Build production-ready Rails apps in minutes, not days. Convention-driven, fully customizable, AI-ready.",
   "type": "module",
   "main": "src/js/core.js",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.60.1
+  version: 0.60.3
 platform: ruby
 authors:
 - Stefan Froelich