plutonium 0.49.1 → 0.50.0

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Grid
+      # Renders a paginated collection of records as a responsive grid of
+      # Card components. Mirrors the structure of Table::Resource (filter
+      # panel, scopes pills, bulk actions, footer) so view-switching is
+      # purely a render-shape change.
+      class Resource < Plutonium::UI::Component::Base
+        attr_reader :collection, :resource_fields, :resource_definition
+
+        def initialize(collection, resource_fields:, resource_definition:)
+          @collection = collection
+          @resource_fields = resource_fields
+          @resource_definition = resource_definition
+        end
+
+        def view_template
+          div(data: filter_panel_controller_data) do
+            render_scopes_pills
+            render_toolbar
+
+            div(data: bulk_actions_controller_data) do
+              render_filter_pills
+              render_bulk_actions_toolbar
+              collection.empty? ? render_empty_card : render_grid
+            end
+
+            render_filter_slideover if current_query_object.filter_definitions.present?
+          end
+
+          render_footer
+        end
+
+        private
+
+        def render_scopes_pills
+          TableScopesPills() if current_query_object.scope_definitions.any?
+        end
+
+        def render_toolbar
+          TableToolbar(
+            query: current_query_object,
+            search_url: request.path,
+            search_value: params.dig(:q, :search) || params[:search],
+            views: resource_definition.defined_views,
+            current_view: :grid,
+            view_cookie_name: Plutonium::UI::Page::Index.view_cookie_name(resource_class),
+            view_cookie_path: Plutonium::UI::Page::Index.view_cookie_path(request)
+          )
+        end
+
+        def render_filter_pills
+          TableFilterPills(query: current_query_object, total_count: pagy_instance&.count)
+        end
+
+        def render_bulk_actions_toolbar
+          return unless bulk_actions.any?
+          BulkActionsToolbar(bulk_actions:)
+        end
+
+        def render_empty_card
+          EmptyCard("No #{resource_name_plural(resource_class).downcase} available") {
+            action = resource_definition.defined_actions[:new]
+            if action&.permitted_by?(current_policy)
+              url = route_options_to_url(action.route_options, resource_class)
+              ActionButton(action, url:)
+            end
+          }
+        end
+
+        def render_grid
+          div(class: grid_class) do
+            collection.each do |record|
+              render Plutonium::UI::Grid::Card.new(record, resource_definition:, resource_fields:)
+            end
+          end
+        end
+
+        # Default responsive: 1 / 2 / 3 / 4 columns at sm/md/lg/xl. When
+        # the definition pins a fixed `grid_columns N`, use that on lg+ so
+        # mobile still gets sensible single-column.
+        def grid_class
+          if resource_definition.defined_grid_columns
+            n = resource_definition.defined_grid_columns
+            "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-#{n} gap-4 mt-4"
+          else
+            "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4 mt-4"
+          end
+        end
+
+        def bulk_actions
+          @bulk_actions ||= resource_definition.defined_actions
+            .select { |k, a| a.bulk_action? }
+            .values
+        end
+
+        def bulk_actions_controller_data
+          {controller: "bulk-actions"}
+        end
+
+        def filter_panel_controller_data
+          {controller: "filter-panel"}
+        end
+
+        def render_filter_slideover
+          div(
+            class: "fixed inset-0 z-40 bg-black/40 opacity-0 pointer-events-none " \
+                   "transition-opacity duration-200 " \
+                   "data-[open]:opacity-100 data-[open]:pointer-events-auto",
+            data: {filter_panel_target: "backdrop", action: "click->filter-panel#close"}
+          )
+          aside(
+            class: "fixed top-0 right-0 bottom-0 z-50 w-full sm:w-[420px] max-w-full " \
+                   "bg-[var(--pu-surface)] border-l border-[var(--pu-border)] " \
+                   "translate-x-full transition-transform duration-300 ease-out " \
+                   "data-[open]:translate-x-0 " \
+                   "flex flex-col",
+            role: "dialog",
+            aria: {label: "Filters", hidden: "true", modal: "true"},
+            data: {filter_panel_target: "panel"}
+          ) do
+            render Plutonium::UI::Table::Components::FilterForm.new(
+              filter_form_values,
+              query_object: current_query_object,
+              search_url: request.path,
+              search_value: params.dig(:q, :search) || params[:search]
+            )
+          end
+        end
+
+        def filter_form_values
+          raw = params[:q]
+          return {} unless raw
+          hash = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw.to_h
+          hash.deep_symbolize_keys.except(:search, :scope, :sort_fields, :sort_directions)
+        end
+
+        def render_footer
+          div(class: "lg:sticky bottom-[-2px] mt-1 p-4 pb-6 w-full z-30 bg-[var(--pu-body)]") {
+            TableInfo(pagy_instance)
+            TablePagination(pagy_instance)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -36,9 +36,45 @@ module Plutonium
             render_title
             render_metatags
             render_assets
+            render_pre_paint_scripts
           }
         end
 
+        # Inline scripts that run before paint to prevent FOUC on user
+        # preferences read from localStorage:
+        # - Color mode: applies `dark` class on <html> so dark theme renders
+        #   from the first frame instead of flashing light.
+        # - Rail-pin: applies `pu-rail-pinned` on <body> (when present) and
+        #   on every incoming body via turbo:before-render, so a
+        #   Turbo.visit (e.g. the redirect after a form submit) doesn't
+        #   flash the rail into its collapsed state before the
+        #   icon-rail Stimulus controller can restore it.
+        def render_pre_paint_scripts
+          script do
+            raw(safe(<<~JS))
+              (function () {
+                try {
+                  var theme = localStorage.getItem("theme");
+                  var dark = theme === "dark" ||
+                    ((theme !== "light") &&
+                     window.matchMedia("(prefers-color-scheme: dark)").matches);
+                  document.documentElement.classList.toggle("dark", dark);
+                } catch (e) {}
+
+                try {
+                  if (localStorage.getItem("pu_rail_pinned") !== "true") return;
+                  if (document.body) document.body.classList.add("pu-rail-pinned");
+                  document.addEventListener("turbo:before-render", function (event) {
+                    if (localStorage.getItem("pu_rail_pinned") === "true") {
+                      event.detail.newBody.classList.add("pu-rail-pinned");
+                    }
+                  });
+                } catch (e) {}
+              })();
+            JS
+          end
+        end
+
         def render_body(&)
           body(**body_attributes) {
             render_before_main
@@ -68,7 +104,7 @@ module Plutonium
         end
 
         def render_after_main
-          turbo_frame_tag("remote_modal")
+          turbo_frame_tag(Plutonium::REMOTE_MODAL_FRAME)
         end
 
         def render_content(&)

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

@@ -36,8 +36,7 @@ module Plutonium
         #   @yield The block containing each action's content
         slot :action, collection: true
 
-        # Renders the header component with all its configured elements
-        # @note The header is fixed positioned and includes responsive design considerations
+        # Renders the classic full-width header.
         # @return [void]
         def view_template
           nav(

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

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "phlexi-menu"
+require "phlex/slotable"
+
+module Plutonium
+  module UI
+    module Layout
+      # A fixed 56px-wide icon-only navigation rail for the app shell.
+      # Renders nav items as icon buttons with tooltips; falls back to a 2-letter
+      # abbreviation when an item has no icon.
+      #
+      # When items have children:
+      # - Collapsed (default): hovering the parent shows a CSS flyout to the right
+      # - Pinned (body.pu-rail-pinned): rail expands to 220px, children collapse inline
+      #
+      # @example Basic usage
+      #   render IconRail.new(menu: @menu) do |rail|
+      #     rail.with_brand { image_tag("logo.svg", class: "w-8 h-8") }
+      #   end
+      class IconRail < Plutonium::UI::Component::Base
+        include Phlex::Slotable
+
+        # @!method brand
+        #   Slot for the brand mark rendered at the top of the rail.
+        slot :brand
+
+        DEFAULT_MAX_DEPTH = 2
+
+        # @param menu [Phlexi::Menu::Builder, nil] Menu structure (same shape as SidebarMenu)
+        # @param max_depth [Integer] Maximum rendering depth (depth 2 supports parent+children)
+        def initialize(menu: nil, max_depth: DEFAULT_MAX_DEPTH)
+          @menu = menu
+          @max_depth = max_depth
+        end
+
+        def view_template
+          aside(
+            id: "sidebar-navigation",
+            data: {controller: "sidebar icon-rail"},
+            aria: {label: "Sidebar Navigation"},
+            class: "fixed top-0 left-0 z-40 h-screen " \
+                   "bg-[var(--pu-surface)] border-r border-[var(--pu-border)] " \
+                   "flex flex-col transition-[width] duration-200 overflow-x-hidden " \
+                   "-translate-x-full lg:translate-x-0"
+          ) do
+            render_brand_section
+            render_nav_section
+            render_footer_section
+          end
+        end
+
+        private
+
+        def render_brand_section
+          div(class: "h-12 flex items-center justify-center border-b border-[var(--pu-border)] shrink-0") do
+            render brand_slot if brand_slot?
+          end
+        end
+
+        def render_nav_section
+          div(
+            id: "sidebar-navigation-content",
+            data: {sidebar_target: "scroll"},
+            class: "flex-1 overflow-y-auto py-3 flex flex-col items-center gap-1"
+          ) do
+            render_items(@menu.items, 0) if @menu&.items
+          end
+        end
+
+        def render_footer_section
+          div(class: "h-14 flex items-center justify-center border-t border-[var(--pu-border)] shrink-0") do
+            render_pin_button
+          end
+        end
+
+        def render_pin_button
+          button(
+            type: "button",
+            title: "Toggle sidebar",
+            aria: {label: "Toggle sidebar pin"},
+            data: {action: "icon-rail#togglePin"},
+            class: "flex items-center justify-center w-10 h-10 rounded-md transition-colors " \
+                   "text-[var(--pu-text-muted)] hover:text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)]"
+          ) do
+            # Collapse icon: shown when pinned (body.pu-rail-pinned)
+            span(class: "icon-rail-pin-collapse hidden") do
+              render Phlex::TablerIcons::LayoutSidebarLeftCollapse.new(class: "w-5 h-5")
+            end
+            # Expand icon: shown when collapsed (default)
+            span(class: "icon-rail-pin-expand") do
+              render Phlex::TablerIcons::LayoutSidebarLeftExpand.new(class: "w-5 h-5")
+            end
+          end
+        end
+
+        # Renders nav items up to @max_depth.
+        def render_items(items, depth = 0)
+          return if depth >= @max_depth || items.nil? || items.empty?
+
+          items.each { |item| render_item_link(item, depth) }
+        end
+
+        def render_item_link(item, depth)
+          if item.items.any?
+            render_parent_item(item, depth)
+          else
+            render_leaf_item(item, depth)
+          end
+        end
+
+        def render_leaf_item(item, depth)
+          a(
+            href: item.url,
+            title: item.label,
+            aria: {label: item.label},
+            class: "icon-rail-leaf #{leaf_classes(item, depth)}"
+          ) do
+            render_item_icon(item)
+            span(class: "icon-rail-label hidden") { item.label }
+          end
+        end
+
+        def render_parent_item(item, depth)
+          div(
+            class: "icon-rail-parent relative w-full flex flex-col items-center",
+            data: {
+              controller: "icon-rail-flyout",
+              action:
+                "mouseenter->icon-rail-flyout#open " \
+                "mouseleave->icon-rail-flyout#scheduleClose " \
+                "focusin->icon-rail-flyout#open " \
+                "focusout->icon-rail-flyout#scheduleClose " \
+                "keydown.esc@window->icon-rail-flyout#closeOnEsc"
+            }
+          ) do
+            a(
+              href: item.url || "#",
+              title: item.label,
+              aria: {label: item.label, haspopup: "menu", expanded: "false"},
+              data: {
+                "icon-rail-flyout-target": "trigger",
+                action: "click->icon-rail-flyout#toggle"
+              },
+              class: "icon-rail-parent-trigger #{parent_trigger_classes(item, depth)}"
+            ) do
+              render_item_icon(item)
+              span(class: "icon-rail-label") { item.label }
+              span(class: "icon-rail-chevron", aria_hidden: "true") do
+                render Phlex::TablerIcons::ChevronRight.new(class: "w-full h-full")
+              end
+            end
+
+            div(
+              class: "icon-rail-flyout",
+              role: "menu",
+              data: {"icon-rail-flyout-target": "panel"}
+            ) do
+              div(class: "icon-rail-flyout-inner") do
+                div(class: "icon-rail-flyout-label") { item.label }
+                item.items.each do |child|
+                  a(href: child.url, class: "icon-rail-flyout-item", role: "menuitem") { child.label }
+                end
+              end
+            end
+          end
+        end
+
+        def render_item_icon(item)
+          if item.icon
+            render item.icon.new(class: "w-5 h-5 shrink-0")
+          else
+            span(class: "text-xs font-semibold leading-none shrink-0") { abbreviate(item.label) }
+          end
+        end
+
+        def leaf_classes(item, depth = 0)
+          base = "flex items-center justify-center w-10 h-10 rounded-md transition-colors"
+          if active?(item)
+            "#{base} bg-primary-100 text-primary-700 dark:bg-primary-900/40 dark:text-primary-300"
+          else
+            "#{base} text-[var(--pu-text-muted)] hover:text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)]"
+          end
+        end
+
+        def parent_trigger_classes(item = nil, depth = 0)
+          base = "relative flex items-center justify-center w-10 h-10 rounded-md transition-colors"
+          if item && parent_active?(item)
+            "#{base} bg-primary-100 text-primary-700 dark:bg-primary-900/40 dark:text-primary-300"
+          else
+            "#{base} text-[var(--pu-text-muted)] hover:text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)]"
+          end
+        end
+
+        # A parent item is "active" if itself or any descendant is active —
+        # so the highlight follows the user into nested children.
+        def parent_active?(item)
+          active?(item) || item.items.any? { |child| active?(child) }
+        end
+
+        # Returns the first 2 letters of the label (letters only, capitalised).
+        def abbreviate(label)
+          label.to_s.gsub(/[^a-zA-Z]/, "").first(2).capitalize
+        end
+
+        def active?(item)
+          item.active?(self)
+        end
+      end
+    end
+  end
+end

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

@@ -4,9 +4,16 @@ module Plutonium
       class ResourceLayout < Base
         private
 
-        def main_attributes = mix(super, {
-          class: "pt-20 lg:ml-64"
-        })
+        def main_attributes
+          classes = case Plutonium.configuration.shell
+          when :modern
+            "pt-16 pb-6 px-6 lg:pl-20"
+          else
+            "pt-20 lg:ml-64"
+          end
+
+          mix(super, {class: classes})
+        end
 
         def page_title
           make_page_title(

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

@@ -3,42 +3,30 @@
 module Plutonium
   module UI
     module Layout
-      # A sidebar navigation component that provides a responsive layout with light/dark mode toggle
+      # A classic sidebar navigation component that provides a wide, labelled navigation panel.
+      #
       # @example Basic usage with navigation content
       #   render Sidebar.new do
-      #     ...
+      #     render SidebarMenu.new(menu)
       #   end
       class Sidebar < Base
         # Renders the sidebar navigation template
         # @yield [void] The block containing sidebar content
         # @return [void]
         def view_template(&)
-          render_sidebar_container do
-            render_content(&) if block_given?
-          end
-        end
-
-        private
-
-        # @private
-        def render_sidebar_container(&)
           aside(
             data: {controller: "sidebar"},
             id: "sidebar-navigation",
             aria: {label: "Sidebar Navigation"},
-            class: "fixed top-0 left-0 z-40 w-64 h-screen pt-14 transition-transform -translate-x-full lg:translate-x-0",
-            &
-          )
-        end
-
-        # @private
-        def render_content(&)
-          div(
-            id: "sidebar-navigation-content",
-            data: {turbo_permanent: true, sidebar_target: "scroll"},
-            class: "overflow-y-auto py-5 px-3 h-full bg-[var(--pu-surface)] border-r border-[var(--pu-border)]",
-            &
-          )
+            class: "fixed top-0 left-0 z-40 w-64 h-screen pt-14 transition-transform -translate-x-full lg:translate-x-0"
+          ) do
+            div(
+              id: "sidebar-navigation-content",
+              data: {turbo_permanent: true, sidebar_target: "scroll"},
+              class: "overflow-y-auto py-5 px-3 h-full bg-[var(--pu-surface)] border-r border-[var(--pu-border)]",
+              &
+            )
+          end
         end
       end
     end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "phlex/slotable"
+
+module Plutonium
+  module UI
+    module Layout
+      # A sticky 48px topbar with breadcrumbs (left), search (center), and actions (right).
+      # Pairs with IconRail — offset by `lg:left-14` on desktop to clear the rail.
+      # The brand mark lives in IconRail's `with_brand` slot, not here.
+      #
+      # @example
+      #   render Topbar.new do |bar|
+      #     bar.with_breadcrumbs { render BreadcrumbComponent.new }
+      #     bar.with_search      { render SearchComponent.new }
+      #     bar.with_action      { render UserMenuComponent.new }
+      #   end
+      class Topbar < Plutonium::UI::Component::Base
+        include Phlex::Slotable
+        include Phlex::Rails::Helpers::Routes
+
+        # @!method breadcrumbs
+        #   Slot for breadcrumb navigation rendered on the left.
+        slot :breadcrumbs
+
+        # @!method search
+        #   Slot for a search widget rendered in the center (max-w-[360px]).
+        slot :search
+
+        # @!method action
+        #   Collection slot for icon buttons / dropdowns rendered on the right.
+        slot :action, collection: true
+
+        def view_template
+          nav(
+            class: "fixed top-0 right-0 left-0 lg:left-14 z-30 h-12 " \
+                   "bg-[var(--pu-surface)] border-b border-[var(--pu-border)] " \
+                   "flex items-center gap-3 px-4",
+            data: {
+              controller: "resource-header",
+              resource_header_sidebar_outlet: "#sidebar-navigation"
+            }
+          ) do
+            render_hamburger
+            render_breadcrumbs_section
+            render_search_section
+            render_actions_section
+          end
+        end
+
+        private
+
+        def render_hamburger
+          button(
+            type: "button",
+            data_action: "resource-header#toggleDrawer",
+            aria_controls: "#sidebar-navigation",
+            aria_label: "Toggle sidebar",
+            class: "p-1.5 -ml-1.5 text-[var(--pu-text-muted)] rounded-md " \
+                   "hover:text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)] " \
+                   "lg:hidden transition-colors"
+          ) do
+            render_hamburger_icons
+          end
+        end
+
+        def render_hamburger_icons
+          span(data_resource_header_target: "openIcon") do
+            render Phlex::TablerIcons::Menu.new(class: "w-5 h-5")
+          end
+          span(data_resource_header_target: "closeIcon", class: "hidden", aria_hidden: "true") do
+            render Phlex::TablerIcons::X.new(class: "w-5 h-5")
+          end
+          span(class: "sr-only") { "Toggle sidebar" }
+        end
+
+        def render_breadcrumbs_section
+          return unless breadcrumbs_slot?
+          div(class: "flex items-center min-w-0 flex-shrink") do
+            render breadcrumbs_slot
+          end
+        end
+
+        def render_search_section
+          return unless search_slot?
+          div(class: "flex-1 flex justify-center") do
+            div(class: "w-full max-w-[360px]") { render search_slot }
+          end
+        end
+
+        def render_actions_section
+          return unless action_slots?
+          div(class: "ml-auto flex items-center gap-1.5") do
+            action_slots.each { |action| render action }
+          end
+        end
+      end
+    end
+  end
+end