plutonium 0.28.0 → 0.30.0

data/docs/guide/theming.md

@@ -0,0 +1,431 @@
+# Theming Guide
+
+Plutonium uses a semantic design token system built on Tailwind CSS, making it easy to customize the appearance of your application while maintaining design consistency.
+
+## Design Philosophy
+
+Plutonium's theming system is built on these principles:
+
+- **Semantic tokens** - Colors and spacing have meaningful names (e.g., `surface`, `elevated`) rather than generic values
+- **Cross-property consistency** - The same size name means the same value across all utilities (`p-md` = `gap-md` = `my-md`)
+- **Minimal, modern aesthetic** - Subtle corners, clean lines, and restrained use of shadows
+- **Easy customization** - Override tokens in your Tailwind config to theme the entire application
+
+## Semantic Design Tokens
+
+### Spacing Scale
+
+Plutonium extends Tailwind's spacing scale with semantic values:
+
+```javascript
+spacing: {
+  'xs': '0.5rem',    // 8px - extra small spacing
+  'sm': '0.75rem',   // 12px - small spacing (inputs, buttons, small gaps)
+  'md': '1rem',      // 16px - medium spacing (cards, tabs, standard gaps)
+  'lg': '1.5rem',    // 24px - large spacing (forms, displays, large spacing)
+  'xl': '2rem',      // 32px - extra large spacing
+  '2xl': '2.5rem',   // 40px - 2x extra large spacing
+  '3xl': '3rem',     // 48px - 3x extra large spacing
+}
+```
+
+These work across **all** spacing utilities:
+- Padding: `p-md`, `px-sm`, `py-lg`
+- Margin: `m-md`, `mx-sm`, `my-lg`
+- Gap: `gap-md`, `gap-x-sm`, `gap-y-lg`
+- Space: `space-x-md`, `space-y-sm`
+
+### Background Colors
+
+Semantic background colors provide consistent theming across light and dark modes:
+
+```javascript
+colors: {
+  // Semantic background colors
+  surface: {
+    DEFAULT: '#ffffff',   // Light mode: cards, forms, tables, panels
+    dark: '#1f2937',      // Dark mode: gray-800
+  },
+  page: {
+    DEFAULT: 'rgb(248 248 248)',  // Light mode: page background
+    dark: '#111827',              // Dark mode: gray-900
+  },
+  elevated: {
+    DEFAULT: 'rgb(244 244 245)',  // Light mode: subtle elevation
+    dark: '#374151',              // Dark mode: gray-700
+  },
+  interactive: {
+    DEFAULT: 'rgb(244 244 245)',  // Light mode: hover states
+    dark: '#374151',              // Dark mode: gray-700
+  },
+}
+```
+
+**Where each color is used:**
+- `surface` - Cards, forms, tables, panels, modals
+- `page` - Main page background
+- `elevated` - Slightly elevated elements like dropdowns, selected items
+- `interactive` - Hover and focus states
+
+### Border Radius
+
+Plutonium uses subtle border radius values for a modern, minimal look:
+
+- `rounded-sm` (2px) - Most UI elements (buttons, inputs, cards)
+- `rounded` (4px) - Slightly larger elements
+- `rounded-lg` (8px) - Special cases needing more rounding
+
+## Getting Started
+
+By default, Plutonium is completely self-contained and uses its own bundled assets - you don't need to do anything to get started. The gem includes pre-compiled CSS and JavaScript that work out of the box.
+
+### When to Integrate Assets
+
+You only need to integrate Plutonium's assets into your application if you want to:
+- Customize the theme (colors, spacing, fonts)
+- Override component styles
+- Extend Tailwind with your own utilities
+
+To integrate Plutonium's assets with your Rails application, run:
+
+```bash
+rails generate pu:core:assets
+```
+
+This generator will:
+- Install required npm packages (`@radioactive-labs/plutonium`, Tailwind CSS, PostCSS)
+- Create a `tailwind.config.js` that loads Plutonium's theme configuration
+- Configure your application to import Plutonium's CSS and register its Stimulus controllers
+- Set up the build pipeline to compile everything together
+
+After running the generator, you can customize the theme as described below.
+
+## Customizing Your Theme
+
+To customize Plutonium's theme, you need to extend the Tailwind configuration in your application (created by `rails generate pu:core:assets`):
+
+```javascript
+// tailwind.config.js
+const { execSync } = require('child_process');
+const plutoniumGemPath = execSync("bundle show plutonium").toString().trim();
+const plutoniumTailwindConfig = require(`${plutoniumGemPath}/tailwind.options.js`)
+const tailwindPlugin = require('tailwindcss/plugin')
+
+module.exports = {
+  darkMode: 'class',
+  plugins: [
+    // Add your custom plugins here
+  ].concat(plutoniumTailwindConfig.plugins.map(function (plugin) {
+    switch (typeof plugin) {
+      case "function":
+        return tailwindPlugin(plugin)
+      case "string":
+        return require(plugin)
+      default:
+        throw Error(`unsupported plugin: ${plugin}: ${(typeof plugin)}`)
+    }
+  })),
+  theme: plutoniumTailwindConfig.merge(
+    plutoniumTailwindConfig.theme,
+    {
+      extend: {
+        colors: {
+          // Override brand colors - example using blue
+          primary: {
+            50: '#eff6ff',
+            100: '#dbeafe',
+            200: '#bfdbfe',
+            300: '#93c5fd',
+            400: '#60a5fa',
+            500: '#3b82f6',
+            600: '#2563eb',
+            700: '#1d4ed8',
+            800: '#1e40af',
+            900: '#1e3a8a',
+            950: '#172554',
+          },
+        },
+      },
+    },
+  ),
+  content: [
+    `${__dirname}/app/**/*.{erb,haml,html,slim,rb}`,
+    `${__dirname}/app/javascript/**/*.js`,
+  ].concat(plutoniumTailwindConfig.content),
+}
+```
+
+### Dark Mode Customization
+
+Customize just the dark mode colors:
+
+```javascript
+theme: plutoniumTailwindConfig.merge(
+  plutoniumTailwindConfig.theme,
+  {
+    extend: {
+      colors: {
+        surface: {
+          dark: '#1e293b',  // slate-800 for a cooler dark mode
+        },
+        page: {
+          dark: '#0f172a',  // slate-900
+        },
+        elevated: {
+          dark: '#334155',  // slate-700
+        },
+        interactive: {
+          dark: '#475569',  // slate-600 for more contrast on hover
+        },
+      },
+    },
+  }
+)
+```
+
+### Brand Color Customization
+
+Replace Plutonium's turquoise/navy palette with your brand colors:
+
+```javascript
+theme: plutoniumTailwindConfig.merge(
+  plutoniumTailwindConfig.theme,
+  {
+    extend: {
+      colors: {
+        primary: {
+          // Your primary brand color scale
+          50: '#fef2f2',
+          100: '#fee2e2',
+          500: '#ef4444',  // Your primary color
+          900: '#7f1d1d',
+        },
+        secondary: {
+          // Your secondary brand color scale
+          50: '#f0fdf4',
+          100: '#dcfce7',
+          500: '#22c55e',  // Your secondary color
+          900: '#14532d',
+        },
+      },
+    },
+  }
+)
+```
+
+### Component-Level Theming
+
+Every Plutonium component supports CSS class customization through the theme system. Component classes follow the pattern:
+
+```
+pu-{component}[-{variant}][-{element}]
+```
+
+#### Available Component Classes
+
+**Forms:**
+- `pu-form` - Form container
+- `pu-form-input` - Text input fields
+- `pu-form-label` - Input labels
+- `pu-form-hint` - Help text below inputs
+- `pu-form-error` - Validation error messages
+- `pu-form-button` - Primary form button
+- `pu-form-button_secondary` - Secondary form button
+- `pu-form-fieldset` - Field grouping container
+- `pu-form-fields` - Fields wrapper
+
+**Tables:**
+- `pu-table` - Table container
+- `pu-table-wrapper` - Scrollable wrapper
+- `pu-table-header` - Table header row
+- `pu-table-header-cell` - Header cell
+- `pu-table-body` - Table body
+- `pu-table-row` - Table row
+- `pu-table-cell` - Table cell
+- `pu-table-footer` - Footer with pagination
+
+**Display (Detail Views):**
+- `pu-display` - Display container
+- `pu-display-fields` - Fields grid wrapper
+- `pu-display-field` - Individual field wrapper
+- `pu-display-label` - Field label
+- `pu-display-value` - Field value
+
+**Layout:**
+- `pu-layout-body` - Main layout body
+- `pu-layout-main` - Main content area
+- `pu-layout-header` - Page header
+- `pu-layout-sidebar` - Sidebar navigation
+
+**Navigation:**
+- `pu-breadcrumbs` - Breadcrumb navigation
+- `pu-nav-menu` - Navigation menu
+- `pu-nav-user` - User menu dropdown
+- `pu-sidebar-menu` - Sidebar menu items
+
+**Panels:**
+- `pu-panel` - Generic panel container
+- `pu-panel-header` - Panel header
+- `pu-panel-body` - Panel content
+
+#### Customization Examples
+
+```css
+/* Custom form styling */
+.pu-form {
+  @apply shadow-xl border-2;
+}
+
+.pu-form-input {
+  @apply text-lg rounded-lg;
+}
+
+.pu-form-error {
+  @apply text-sm font-semibold;
+}
+
+/* Custom table styling */
+.pu-table-row:hover {
+  @apply bg-primary-50 dark:bg-primary-950;
+}
+
+.pu-table-header-cell {
+  @apply font-bold uppercase tracking-wider;
+}
+
+/* Custom display styling */
+.pu-display-field {
+  @apply border-l-4 border-primary-500 pl-4;
+}
+
+.pu-display-label {
+  @apply text-xs uppercase tracking-wide text-gray-500;
+}
+```
+
+You can also use Ruby to customize theme classes programmatically:
+
+```ruby
+# In your resource controller or view
+class Admin::UsersController < Plutonium::ResourceController
+  def self.form_theme
+    {
+      input: "pu-form-input w-full rounded-lg border-2 border-primary-300"
+    }
+  end
+end
+```
+
+## Common Theming Scenarios
+
+### Warmer Color Palette
+
+```javascript
+theme: plutoniumTailwindConfig.merge(
+  plutoniumTailwindConfig.theme,
+  {
+    extend: {
+      colors: {
+        surface: {
+          DEFAULT: '#fefefe',
+          dark: '#1c1917',  // stone-900
+        },
+        page: {
+          DEFAULT: '#fafaf9',  // stone-50
+          dark: '#0c0a09',     // stone-950
+        },
+        elevated: {
+          DEFAULT: '#f5f5f4',  // stone-100
+          dark: '#292524',     // stone-800
+        },
+      },
+    },
+  }
+)
+```
+
+### High Contrast Mode
+
+```javascript
+theme: plutoniumTailwindConfig.merge(
+  plutoniumTailwindConfig.theme,
+  {
+    extend: {
+      colors: {
+        surface: {
+          DEFAULT: '#ffffff',
+          dark: '#000000',  // Pure black
+        },
+        page: {
+          DEFAULT: '#fafafa',
+          dark: '#0a0a0a',  // Almost black
+        },
+        elevated: {
+          DEFAULT: '#f0f0f0',
+          dark: '#1a1a1a',
+        },
+        interactive: {
+          DEFAULT: '#e5e5e5',
+          dark: '#2a2a2a',
+        },
+      },
+    },
+  }
+)
+```
+
+### Monochrome Theme
+
+```javascript
+theme: plutoniumTailwindConfig.merge(
+  plutoniumTailwindConfig.theme,
+  {
+    extend: {
+      colors: {
+        primary: {
+          50: '#fafafa',
+          100: '#f5f5f5',
+          500: '#737373',
+          900: '#171717',
+        },
+        secondary: {
+          50: '#f5f5f5',
+          100: '#e5e5e5',
+          500: '#525252',
+          900: '#0a0a0a',
+        },
+      },
+    },
+  }
+)
+```
+
+## Tips and Best Practices
+
+1. **Use semantic tokens** - Prefer `bg-surface` over `bg-white` so dark mode works automatically
+2. **Test both modes** - Always verify your changes in both light and dark mode
+3. **Maintain contrast** - Ensure text remains readable against your background colors
+4. **Extend, don't replace** - Use the `merge` helper to extend rather than replace the theme
+5. **Stay consistent** - Use the same spacing scale throughout your application
+
+## Migration from Hardcoded Values
+
+If you have existing components using hardcoded Tailwind values, migrate them to semantic tokens:
+
+**Before:**
+```ruby
+div(class: "bg-white dark:bg-gray-800 p-4 rounded-lg")
+```
+
+**After:**
+```ruby
+div(class: "bg-surface dark:bg-surface-dark p-md rounded-sm")
+```
+
+This ensures your components automatically adapt to theme changes.
+
+## Further Resources
+
+- [Tailwind CSS Customization](https://tailwindcss.com/docs/configuration)
+- [Dark Mode Guide](https://tailwindcss.com/docs/dark-mode)
+- [Color Palette Generator](https://uicolors.app/create)

data/lib/plutonium/core/controller.rb

@@ -100,6 +100,11 @@ module Plutonium
           url_args[scoped_entity_param_key] = current_scoped_entity
         end
 
+        # Preserve the request format unless explicitly specified
+        if !url_args.key?(:format) && request.present? && request.format.present? && request.format.symbol != :html
+          url_args[:format] = request.format.symbol
+        end
+
         url_args
       end
 

data/lib/plutonium/interaction/response/redirect.rb

@@ -17,6 +17,14 @@ module Plutonium
           redirect_options = @options
 
           controller.instance_eval do
+            # Preserve the request format unless explicitly specified
+            url_options = redirect_args.last.is_a?(Hash) ? redirect_args.last : {}
+            if !url_options.key?(:format) && request.format.symbol != :html
+              url_options = url_options.merge(format: request.format.symbol)
+              redirect_args = [*redirect_args[0...-1], url_options] if redirect_args.last.is_a?(Hash)
+              redirect_args = [*redirect_args, url_options] unless redirect_args.last.is_a?(Hash)
+            end
+
             url = url_for(*redirect_args)
 
             respond_to do |format|

data/lib/plutonium/resource/controllers/crud_actions.rb

@@ -54,6 +54,7 @@ module Plutonium
                   notice: "#{resource_class.model_name.human} was successfully created."
               end
               format.any do
+                @current_policy = nil # Reset cached policy so it uses the instance instead of class
                 render :show,
                   status: :created,
                   location: redirect_url_after_submit

data/lib/plutonium/ui/action_button.rb

@@ -70,23 +70,29 @@ module Plutonium
           base_classes,
           color_classes,
           size_classes,
-          -> { @action.icon && @variant != :table } => "space-x-1"
+          -> { @action.icon && @variant != :table } => "space-x-xs"
         )
       end
 
       def base_classes
         if @variant == :table
-          "inline-flex items-center justify-center py-1 px-2 rounded-lg focus:outline-none focus:ring-2"
+          tokens(
+            theme_class(:button, variant: :table),
+            "inline-flex items-center justify-center py-xs px-sm rounded-sm focus:outline-none focus:ring-2"
+          )
         else
-          "flex items-center justify-center px-4 py-2 text-sm font-medium rounded-lg focus:outline-none focus:ring-4"
+          tokens(
+            theme_class(:button),
+            "flex items-center justify-center px-md py-sm text-sm font-medium rounded-sm focus:outline-none focus:ring-4"
+          )
         end
       end
 
       def icon_classes
         if @variant == :table
-          "h-4 w-4 mr-1"
+          "h-4 w-4 mr-xs"
         else
-          "h-3.5 w-3.5 -ml-1"
+          "h-3.5 w-3.5 -ml-xs"
         end
       end
 

data/lib/plutonium/ui/block.rb

@@ -4,7 +4,10 @@ module Plutonium
       def view_template(&)
         raise ArgumentError, "Block requires a content block" unless block_given?
 
-        div class: "relative bg-white dark:bg-gray-800 shadow-md sm:rounded-lg my-3" do
+        div class: tokens(
+          theme_class(:block),
+          "relative bg-surface dark:bg-surface-dark shadow-md sm:rounded-sm my-sm"
+        ) do
           yield
         end
       end

data/lib/plutonium/ui/breadcrumbs.rb

@@ -6,13 +6,15 @@ module Plutonium
 
       def view_template
         nav(
-          class:
-            "flex py-3 text-gray-700 mb-2",
+          class: tokens(
+            theme_class(:breadcrumbs),
+            "flex py-sm text-gray-700 mb-sm"
+          ),
           aria_label: "Breadcrumb"
         ) do
           ol(
             class:
-              "inline-flex items-center space-x-1 md:space-x-2 rtl:space-x-reverse"
+              "inline-flex items-center space-x-xs md:space-x-sm rtl:space-x-reverse"
           ) do
             # Dashboard
             li(class: "inline-flex items-center") do
@@ -42,7 +44,7 @@ module Plutonium
               # Parent Resource
               li(class: "flex items-center") do
                 svg(
-                  class: "rtl:rotate-180 block w-3 h-3 mx-1 text-gray-400",
+                  class: "rtl:rotate-180 block w-3 h-3 mx-xs text-gray-400",
                   aria_hidden: "true",
                   xmlns: "http://www.w3.org/2000/svg",
                   fill: "none",
@@ -65,7 +67,7 @@ module Plutonium
               # Parent Itself
               li(class: "flex items-center") do
                 svg(
-                  class: "rtl:rotate-180 block w-3 h-3 mx-1 text-gray-400",
+                  class: "rtl:rotate-180 block w-3 h-3 mx-xs text-gray-400",
                   aria_hidden: "true",
                   xmlns: "http://www.w3.org/2000/svg",
                   fill: "none",
@@ -92,7 +94,7 @@ module Plutonium
                 # Record Resource
                 li(class: "flex items-center") do
                   svg(
-                    class: "rtl:rotate-180 block w-3 h-3 mx-1 text-gray-400",
+                    class: "rtl:rotate-180 block w-3 h-3 mx-xs text-gray-400",
                     aria_hidden: "true",
                     xmlns: "http://www.w3.org/2000/svg",
                     fill: "none",
@@ -117,7 +119,7 @@ module Plutonium
               if resource_record!.persisted? && action_name != "show"
                 li(class: "flex items-center") do
                   svg(
-                    class: "rtl:rotate-180 block w-3 h-3 mx-1 text-gray-400",
+                    class: "rtl:rotate-180 block w-3 h-3 mx-xs text-gray-400",
                     aria_hidden: "true",
                     xmlns: "http://www.w3.org/2000/svg",
                     fill: "none",
@@ -142,7 +144,7 @@ module Plutonium
             # Trailing Caret
             li(class: "flex items-center") do
               svg(
-                class: "rtl:rotate-180 block w-3 h-3 mx-1 text-gray-400",
+                class: "rtl:rotate-180 block w-3 h-3 mx-xs text-gray-400",
                 aria_hidden: "true",
                 xmlns: "http://www.w3.org/2000/svg",
                 fill: "none",

data/lib/plutonium/ui/color_mode_selector.rb

@@ -8,8 +8,8 @@ module Plutonium
     class ColorModeSelector < Plutonium::UI::Component::Base
       # Common CSS classes used across the component
       COMMON_CLASSES = {
-        button: "inline-flex justify-center items-center p-2 text-gray-500 rounded cursor-pointer dark:hover:text-white dark:text-gray-200 hover:text-gray-900 hover:bg-gray-100 dark:hover:bg-gray-600 transition-colors duration-200",
-        icon: "w-5 h-5"
+        button: "pu-color-mode-button inline-flex justify-center items-center p-2 text-gray-500 rounded cursor-pointer dark:hover:text-white dark:text-gray-200 hover:text-gray-900 hover:bg-interactive dark:hover:bg-interactive-dark transition-colors duration-200",
+        icon: "pu-color-mode-icon w-5 h-5"
       }.freeze
 
       # Available color modes with their associated icons and actions

data/lib/plutonium/ui/component/behaviour.rb

@@ -10,6 +10,14 @@ module Plutonium
         include Kit
         include Tokens
 
+        # Generate custom CSS class for theming
+        # @example
+        #   theme_class(:button) # => "pu-button"
+        #   theme_class(:button, variant: :table) # => "pu-button-table"
+        def theme_class(component, variant: nil, element: nil)
+          Theme.custom_class(component, variant:, element:)
+        end
+
         if Rails.env.development?
           def around_template(&)
             comment { "open:#{self.class.name}" }

data/lib/plutonium/ui/component/kit.rb

@@ -15,7 +15,7 @@ module Plutonium
       #     def view_template
       #       PageHeader(title: "Dashboard")
       #       TabList(items: tabs)
-      #       Panel(class: "mt-4") do
+      #       Panel(class: "mt-md") do
       #         content
       #       end
       #     end

data/lib/plutonium/ui/component/theme.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Component
+      # Provides custom CSS class names for Plutonium UI components
+      # to enable CSS-based theming without overriding components
+      #
+      # Users can customize via:
+      # 1. Tailwind config (for ALL design tokens - radius, shadows, spacing, colors, etc.)
+      # 2. CSS overrides using custom classes (e.g., .pu-button, .pu-card)
+      #
+      # @example Customizing via Tailwind config
+      #   // tailwind.config.js
+      #   module.exports = {
+      #     theme: {
+      #       extend: {
+      #         borderRadius: {
+      #           'lg': '1rem',  // Makes all rounded-sm bigger
+      #         },
+      #         boxShadow: {
+      #           'md': '0 8px 16px rgba(0,0,0,0.1)',  // Customize shadow-md
+      #         }
+      #       }
+      #     }
+      #   }
+      #
+      # @example Customizing specific components via CSS
+      #   .pu-button {
+      #     text-transform: uppercase;
+      #   }
+      #
+      #   .pu-card {
+      #     border-radius: 0; /* Sharp corners only on cards */
+      #   }
+      #
+      module Theme
+        # Custom class names for CSS targeting
+        # Format: pu-{component}[-{variant}][-{element}]
+        def self.custom_class(component, variant: nil, element: nil)
+          parts = ["pu", component, variant, element].compact
+          parts.join("-")
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/display/components/attachment.rb

@@ -34,12 +34,12 @@ module Plutonium
             return unless attachment.url.present?
 
             div(
-              class: "w-full aspect-square bg-white border border-gray-200 rounded-lg shadow hover:bg-gray-50 dark:bg-gray-800 dark:border-gray-700 dark:hover:bg-gray-700 transition-all duration-300",
+              class: "w-full aspect-square bg-white border border-gray-200 rounded-sm shadow hover:bg-gray-50 dark:bg-gray-800 dark:border-gray-700 dark:hover:bg-gray-700 transition-all duration-300",
               data: {attachment_preview_target: "thumbnail"}
             ) do
               a(
                 href: attachment.url,
-                class: "block aspect-square overflow-hidden rounded-lg",
+                class: "block aspect-square overflow-hidden rounded-sm",
                 target: :blank,
                 data: {attachment_preview_target: "thumbnailLink"}
               ) do