plutonium 0.60.5 → 0.62.0

data/lib/plutonium/definition/form_layout.rb

@@ -33,6 +33,59 @@ module Plutonium
       # filtering). Produced by #resolve_form_sections (a later task).
       ResolvedSection = Struct.new(:section, :fields)
 
+      # First-section-wins ownership, shared by every layout resolver (the resource
+      # form via {#resolve_form_sections}, and the wizard's {StepAdapter} /
+      # {FieldImporter}). Each field is claimed by the FIRST explicit section that
+      # lists it, restricted to the currently-permitted `fields`; a listed field
+      # outside that set is simply skipped (never renders, never an error).
+      #
+      # @param layout [Array<Section>]
+      # @param fields [Array<Symbol,String>] the permitted field set, in order
+      # @return [Array(Hash, Array<Symbol>)] `[owner_by_field, leftover_fields]`
+      def self.assign_ownership(layout, fields)
+        fields = fields.map(&:to_sym)
+        known = fields.to_set
+        owner = {}
+        layout.each do |section|
+          next if section.ungrouped?
+          section.fields.map(&:to_sym).each { |f| owner[f] ||= section.key if known.include?(f) }
+        end
+        leftovers = fields.reject { |f| owner.key?(f) }
+        [owner, leftovers]
+      end
+
+      # The canonical resolution: first-section-wins ownership, with unclaimed
+      # permitted fields falling into the (explicit, or a synthesized trailing)
+      # ungrouped bucket so nothing silently disappears. Every declared section is
+      # kept (empty ones are dropped at render). Shared by {#resolve_form_sections}
+      # and the wizard {StepAdapter}'s raw-layout path so the two never drift.
+      #
+      # @param layout [Array<Section>]
+      # @param fields [Array<Symbol,String>] the permitted field set, in order
+      # @return [Array<ResolvedSection>]
+      def self.resolve_sections(layout, fields)
+        owner, leftovers = assign_ownership(layout, fields)
+
+        resolved = layout.map do |section|
+          section_fields =
+            if section.ungrouped?
+              leftovers
+            else
+              section.fields.map(&:to_sym).select { |f| owner[f] == section.key }
+            end
+          ResolvedSection.new(section:, fields: section_fields)
+        end
+
+        unless layout.any?(&:ungrouped?)
+          resolved.push(ResolvedSection.new(
+            section: Section.new(key: UNGROUPED_KEY, fields: [].freeze, options: {}.freeze),
+            fields: leftovers
+          ))
+        end
+
+        resolved
+      end
+
       # Collects section/ungrouped calls from a form_layout block in order.
       class Builder
         attr_reader :sections
@@ -102,41 +155,7 @@ module Plutonium
         layout = defined_form_layout
         return nil unless layout
 
-        resource_fields = resource_fields.map(&:to_sym)
-        known = resource_fields.to_set
-
-        # First-section-wins assignment: each field is claimed by the first
-        # section that lists it. A field a section lists but that isn't in the
-        # currently-permitted set (policy, per-action, entity scoping, nesting)
-        # is simply skipped — it never renders and is never an error.
-        owner = {}
-        layout.each do |section|
-          next if section.ungrouped?
-          section.fields.each do |f|
-            owner[f] ||= section.key if known.include?(f)
-          end
-        end
-        leftovers = resource_fields.reject { |f| owner.key?(f) }
-
-        resolved = layout.map do |section|
-          fields =
-            if section.ungrouped?
-              leftovers
-            else
-              section.fields.select { |f| owner[f] == section.key }
-            end
-          ResolvedSection.new(section:, fields:)
-        end
-
-        unless layout.any?(&:ungrouped?)
-          implicit = ResolvedSection.new(
-            section: Section.new(key: UNGROUPED_KEY, fields: [].freeze, options: {}.freeze),
-            fields: leftovers
-          )
-          resolved.push(implicit)
-        end
-
-        resolved
+        FormLayout.resolve_sections(layout, resource_fields)
       end
     end
   end

data/lib/plutonium/definition/index_views.rb

@@ -18,7 +18,7 @@ module Plutonium
     module IndexViews
       extend ActiveSupport::Concern
 
-      KNOWN_VIEWS = %i[table grid].freeze
+      KNOWN_VIEWS = %i[table grid kanban].freeze
       GRID_SLOTS = %i[image header subheader body meta footer].freeze
       GRID_LAYOUTS = %i[compact media].freeze
 
@@ -28,6 +28,8 @@ module Plutonium
         class_attribute :defined_grid_fields, default: {}, instance_accessor: false
         class_attribute :defined_grid_layout, default: :compact, instance_accessor: false
         class_attribute :defined_grid_columns, default: nil, instance_accessor: false
+        class_attribute :defined_kanban_block, default: nil, instance_accessor: false
+        class_attribute :defined_kanban_board, default: nil, instance_accessor: false
       end
 
       class_methods do
@@ -83,6 +85,71 @@ module Plutonium
         def grid_columns(value)
           self.defined_grid_columns = Integer(value)
         end
+
+        # Declares a kanban board for this resource and enables the :kanban
+        # index view (mirrors how grid_fields enables :grid). The block is the
+        # kanban DSL, compiled lazily into a Plutonium::Kanban::Board later.
+        #
+        # ## Column action auto-registration
+        #
+        # Each column action declared inside the block is automatically registered
+        # as an interactive resource action (via `action name, interaction:`) so
+        # the existing bulk_actions/:key route resolves and
+        # `interactive_resource_actions` look-up succeeds at request time.
+        #
+        # Only STATIC columns (declared with `column :key …`) can be introspected
+        # at class-load time. Dynamic boards (`columns do … end`) must declare
+        # any column-action interactions as top-level definition `action` calls
+        # separately (the constraint is structural: the block is only evaluated at
+        # request time with a live context object, so its columns are unknown here).
+        def kanban(&block)
+          self.defined_kanban_block = block
+          self.defined_index_views = defined_index_views + [:kanban] unless defined_index_views.include?(:kanban)
+
+          # Eagerly compile the board to extract static column actions and
+          # register each one as an interactive resource action.
+          #
+          # Safety of compiling at class-load time:
+          #   * The board DSL never accesses the database.
+          #   * BUT interaction constants referenced in column action blocks
+          #     (e.g. `interaction: ArchiveTasksInteraction`) ARE resolved here,
+          #     at definition class-load time. They must therefore be autoloadable
+          #     WITHOUT a circular dependency back on this definition class — an
+          #     interaction that references the definition at its own load time
+          #     would deadlock the autoloader. In practice interactions depend only
+          #     on their model, so this constraint is naturally satisfied.
+          board = Plutonium::Kanban::DSL.build(&block)
+          # Cache the compiled board so the controller can reuse it instead of
+          # recompiling per request (see KanbanActions#current_kanban_board).
+          self.defined_kanban_board = board
+          board.columns.each do |col|
+            col.actions.each do |col_action|
+              action(
+                col_action.key,
+                interaction: col_action.interaction,
+                label: col_action.label,
+                icon: col_action.icon,
+                confirmation: col_action.confirmation
+              )
+            end
+
+            # Register each column's enter_interaction as an interactive record
+            # action too, so its form and params extraction exist and route the
+            # standard way. It is flagged `kanban_drop: true` so it is excluded
+            # from the normal show/row/index toolbars — it is reachable only by
+            # dropping a card. The key is column-scoped (enter_interaction_key →
+            # :<column>_enter_interaction), so it is unique by construction and
+            # never collides with another column's interaction. It carries NO
+            # policy method of its own — the drop is authorized by kanban_move?.
+            if col.enter_interaction?
+              action(
+                col.enter_interaction_key,
+                interaction: col.enter_interaction,
+                kanban_drop: true
+              )
+            end
+          end
+        end
       end
 
       def defined_index_views = self.class.defined_index_views
@@ -90,6 +157,8 @@ module Plutonium
       def defined_grid_fields = self.class.defined_grid_fields
       def defined_grid_layout = self.class.defined_grid_layout
       def defined_grid_columns = self.class.defined_grid_columns
+      def defined_kanban_block = self.class.defined_kanban_block
+      def defined_kanban_board = self.class.defined_kanban_board
     end
   end
 end

data/lib/plutonium/definition/wizards.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # The `wizard` definition macro (§5.1) — sugar over the Action system, mirroring
+    # {Plutonium::Definition::Actions}. It registers a launching action for a
+    # wizard auto-mounted on the resource's own controller (see
+    # {Plutonium::Resource::Controllers::WizardActions}):
+    #
+    #   class CompanyDefinition < Plutonium::Resource::Definition
+    #     wizard :configure, ConfigureCompanyWizard                # anchored → record action (show + list)
+    #     wizard :configure, ConfigureCompanyWizard, collection_record_action: false  # show page only
+    #     wizard :onboard,   CompanyOnboardingWizard               # no anchor → resource action
+    #   end
+    #
+    # Placement is dictated by the wizard, mirroring interactions: an **anchored**
+    # wizard is a **record** action (the anchor is the URL `:id`, resolved through the
+    # resource controller's scoped, policy-gated `resource_record!`); a **non-anchored**
+    # wizard is a **resource** (collection) action. It's not overridable — a flag that
+    # doesn't apply to the kind raises. The configurable surface is where a RECORD
+    # action shows: the show page (`record_action:`) and the list rows
+    # (`collection_record_action:`), both on by default. Bulk wizards are not
+    # supported (§5.1) — wizards are per-instance flows.
+    #
+    # The macro keeps a per-definition registry (`registered_wizards`) the
+    # resource-mounted {WizardActions} concern reads to resolve the wizard class by
+    # the `:wizard_name` route segment, and synthesizes a launch action whose URL
+    # resolver targets the auto-mounted member (anchored) or collection routes.
+    module Wizards
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # @return [Hash{Symbol=>Hash}] registry of wizards declared on this
+        #   definition: `{name => {wizard_class:, record_action:}}`. Read by
+        #   {Plutonium::Resource::Controllers::WizardActions} to resolve + gate.
+        def registered_wizards
+          @registered_wizards ||= {}
+        end
+
+        # Definitions are inheritable; carry the wizard registry to subclasses.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@registered_wizards, registered_wizards.dup)
+        end
+
+        # Placement is dictated by the wizard, not chosen: an **anchored** wizard is
+        # a **record** action (it needs a record — the anchor), a **non-anchored**
+        # wizard is a **resource** (collection) action. The only configurable surface
+        # is WHERE a *record* action shows — the **show** page (`record_action:`) and
+        # the **list** rows (`collection_record_action:`), both on by default. Flags
+        # that don't apply to the wizard's kind are rejected.
+        #
+        # Like an interaction, a `wizard` action is gated by a policy predicate named
+        # after its key — `def configure? = update?` for `wizard :configure, …`. The
+        # SAME predicate drives both the launch action's visibility
+        # (`Action#permitted_by?` on index/show) and its authorization
+        # ({WizardActions#authorize_wizard_*_action!}), so the button and the action
+        # stay in lockstep. A missing predicate raises `ActionPolicy::UnknownRule`
+        # (exactly as a missing interaction predicate does) — define it.
+        #
+        # @param name [Symbol] the action key (e.g. :configure)
+        # @param wizard_class [Class] a Plutonium::Wizard::Base subclass
+        # @param opts [Hash] action overrides — chrome (`label:`/`icon:`/`position:`/
+        #   `category:`/`confirmation:`/`turbo_frame:`) plus, for a RECORD wizard, the
+        #   show/list surface flags `record_action:`/`collection_record_action:`.
+        def wizard(name, wizard_class, **opts)
+          is_record = wizard_class.anchored?
+          reject_inapplicable_surface!(name, wizard_class, is_record, opts)
+
+          registered_wizards[name.to_sym] = {wizard_class:, record_action: is_record}
+
+          resolver = wizard_launch_resolver(name, is_record)
+
+          # A record (anchored) wizard surfaces on BOTH the show page (`record_action`)
+          # AND each list row (`collection_record_action`, scoped to that row's
+          # record); a resource (non-anchored) wizard is the collection-level
+          # `resource_action`. `opts` are spliced AFTER, so a record wizard can opt out
+          # of either surface (e.g. `collection_record_action: false` → show page only).
+          action(
+            name,
+            route_options: Plutonium::Action::RouteOptions.new(
+              method: :get, url_resolver: resolver
+            ),
+            label: wizard_label(wizard_class, name),
+            icon: wizard_icon(wizard_class),
+            description: wizard_class.description,
+            category: :primary,
+            record_action: is_record,
+            collection_record_action: is_record,
+            resource_action: !is_record,
+            **opts.except(:condition),
+            condition: wizard_launch_condition(wizard_class, opts[:condition])
+          )
+        end
+
+        private
+
+        # Reject surface flags that don't apply to the wizard's kind. Placement is
+        # fixed by `anchored?`: a RECORD (anchored) wizard can only be placed on the
+        # show page / list rows (`record_action:`/`collection_record_action:`) — it
+        # can't be a `resource_action` (there's no record at the collection level); a
+        # RESOURCE (non-anchored) wizard is a collection-level action with no record,
+        # so the record/list surfaces don't apply.
+        def reject_inapplicable_surface!(name, wizard_class, is_record, opts)
+          disallowed =
+            if is_record
+              [:resource_action]
+            else
+              [:record_action, :collection_record_action]
+            end
+          bad = disallowed.select { |flag| opts.key?(flag) }
+          return if bad.empty?
+
+          kind = is_record ? "anchored (a record action)" : "not anchored (a resource action)"
+          applies = is_record ? "record_action: / collection_record_action: (show page / list rows)" : "none (it's the collection-level action)"
+          raise ArgumentError,
+            "wizard :#{name} — #{wizard_class} is #{kind}; " \
+            "#{bad.join(", ")} #{(bad.size == 1) ? "doesn't" : "don't"} apply. " \
+            "Configurable surface here: #{applies}."
+        end
+
+        # The launch action's `condition:` (§9). A **one-time** wizard's launch is
+        # hidden once the current user has already completed it: the condition
+        # recomputes the wizard's `instance_key` for the current context (same
+        # {Plutonium::Wizard.compute_instance_key} the driving layer + gate use) and
+        # returns false when a retained `completed` row exists at that key. A
+        # repeatable (non-one-time) wizard gets NO completion condition.
+        #
+        # When the author also passed a `condition:`, the two are AND-ed: the action
+        # shows only if the author's condition is met AND the wizard isn't already
+        # completed.
+        #
+        # The proc runs in a {Plutonium::Action::ConditionContext}: `object`/`record`
+        # is the anchor for a record action (nil for a resource action), view helpers
+        # (`current_user`) delegate to the view context, and `current_scoped_entity` /
+        # `scoped_to_entity?` are read off the host controller (`controller`) exactly
+        # as the gate recomputes them.
+        def wizard_launch_condition(wizard_class, author_condition)
+          return author_condition unless wizard_class.one_time?
+
+          completion_condition = proc do
+            # This runs on EVERY index/show render. The `wizard` macro is not gated
+            # on `config.wizards.enabled` (only routing is), so guard the DB query:
+            # when the subsystem is disabled its routes aren't drawn (a launch button
+            # would 404) → hide the action; when it's enabled but the sessions table
+            # hasn't been migrated yet, treat the wizard as not-yet-completed (show)
+            # rather than raising StatementInvalid mid-render.
+            next false unless Plutonium.configuration.wizards.enabled
+            next true unless Plutonium::Wizard::Session.table_exists?
+
+            scope =
+              if controller.scoped_to_entity?
+                controller.current_scoped_entity
+              end
+
+            instance_key = Plutonium::Wizard.compute_instance_key(
+              wizard_class: wizard_class,
+              current_user: current_user,
+              current_scoped_entity: scope,
+              anchor: wizard_class.anchored? ? object : nil,
+              wizard_token: nil
+            )
+
+            !Plutonium::Wizard::Store::ActiveRecord.new.completed?(instance_key: instance_key)
+          end
+
+          return completion_condition if author_condition.nil?
+
+          # AND the author's condition with the completion check; both run in the
+          # same ConditionContext, so evaluate each via instance_exec on self.
+          proc do
+            instance_exec(&author_condition) && instance_exec(&completion_condition)
+          end
+        end
+
+        def wizard_label(wizard_class, name)
+          if wizard_class.respond_to?(:label) && wizard_class.label.present?
+            wizard_class.label
+          else
+            name.to_s.humanize
+          end
+        end
+
+        def wizard_icon(wizard_class)
+          wizard_class.icon || Phlex::TablerIcons::Wand
+        end
+
+        # A url_resolver proc (§5.1). Evaluated against the controller with the
+        # subject; builds the wizard's bare LAUNCH URL on the auto-mounted resource
+        # route — the member route for an anchored wizard (id from the subject), the
+        # collection route otherwise. The launch action resolves the run and
+        # redirects to its current step (the resumed cursor for an in-progress keyed
+        # run, else the first step), with the token already in the URL — so we never
+        # hardcode a step here.
+        def wizard_launch_resolver(name, is_record)
+          wizard_name = name.to_s
+
+          proc do |subject|
+            if is_record
+              resource_url_for(subject, wizard: wizard_name)
+            else
+              resource_url_for(resource_class, wizard: wizard_name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/invites/concerns/invite_token.rb

@@ -40,6 +40,7 @@ module Plutonium
           enum :state, pending: 0, accepted: 1, expired: 2, cancelled: 3
 
           # Callbacks
+          before_validation :normalize_email
           before_validation :set_token_defaults, on: :create
           after_commit :send_invitation_email, on: :create
 
@@ -166,6 +167,14 @@ module Plutonium
           email.split("@").last&.downcase
         end
 
+        # Normalize the login to lowercase so it agrees with case-insensitive
+        # lookups (account_from_login, find_by(email:)) on a case-sensitive DB.
+        # This is the single source of truth: every creation path stores a
+        # normalized email regardless of how the record was built.
+        def normalize_email
+          self.email = email.downcase if email.present?
+        end
+
         def set_token_defaults
           self.token ||= SecureRandom.urlsafe_base64(32)
           self.expires_at ||= 1.week.from_now

data/lib/plutonium/invites/concerns/invite_user.rb

@@ -29,6 +29,15 @@ module Plutonium
           attribute :resource
           attribute :email
 
+          # Normalize the login to lowercase so the dedup guards
+          # (user_not_already_member, no_pending_invitation) and the created
+          # invite all agree on case. Lookups elsewhere downcase, and the DB may
+          # be case-sensitive. Defined on the class so it overrides the
+          # ActiveModel attribute reader; super reaches the stored value.
+          def email
+            super&.downcase
+          end
+
           validates :email, presence: true
           validate :role_is_present
           validate :user_not_already_member

data/lib/plutonium/invites/controller.rb

@@ -123,7 +123,10 @@ module Plutonium
 
       # Handle the signup form submission.
       def handle_signup_submission
-        email = @invite.enforce_email? ? @invite.email : params[:email]
+        # Normalize the login up front so the existing-account guard below and
+        # the account it creates agree on case with case-insensitive lookups
+        # (account_from_login) on a case-sensitive DB.
+        email = (@invite.enforce_email? ? @invite.email : params[:email])&.downcase
         password = params[:password]
         password_confirmation = params[:password_confirmation]
 

data/lib/plutonium/kanban/action.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Kanban
+    Action = Data.define(:key, :interaction, :on, :label, :icon, :confirmation)
+  end
+end

data/lib/plutonium/kanban/board.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Kanban
+    class Board
+      attr_reader :columns, :columns_block, :card_fields, :per_column, :position_config, :show_in
+
+      # nil means "inherit the definition's show_in"; the board only overrides
+      # when explicitly set to :modal or :page.
+      VALID_SHOW_IN = [nil, :modal, :page].freeze
+
+      def initialize(columns:, columns_block:, card_fields:, per_column:, realtime:, position_config:, lazy:, show_in: nil)
+        unless VALID_SHOW_IN.include?(show_in)
+          raise ArgumentError, "show_in must be one of #{VALID_SHOW_IN.compact.inspect} (or unset), got #{show_in.inspect}"
+        end
+
+        @columns = columns
+        @columns_block = columns_block
+        @card_fields = card_fields
+        @per_column = per_column
+        @realtime = realtime
+        @position_config = position_config
+        @lazy = lazy
+        @show_in = show_in
+        @columns.each(&:freeze)
+        @columns.freeze
+        @card_fields&.freeze
+        freeze
+      end
+
+      def realtime? = !!@realtime
+      def lazy? = !!@lazy
+      def dynamic? = !@columns_block.nil?
+
+      # Resolves the board's effective show_in, falling back to the definition's
+      # `show_in` when the board doesn't override it. Pass the resource definition.
+      def show_in_for(definition) = @show_in || definition.show_in
+    end
+  end
+end

data/lib/plutonium/kanban/broadcaster.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Kanban
+    # Builds ActionCable stream names and broadcasts Turbo Stream updates for
+    # opt-in realtime kanban boards.
+    #
+    # ## Tenant isolation
+    #
+    # The stream name is a three-segment string:
+    #
+    #   "kanban:<tenant>:<resource>"
+    #
+    # where <tenant> is the scoped entity's GID param (e.g. "Z2lkOi8vYXBwL09yZy8x")
+    # or the literal string "global" for unscoped portals.
+    #
+    # Two viewers are on the SAME stream only when they share identical
+    # resource_class AND scoped_entity — different tenants can never share a
+    # stream because their GID params are distinct by definition.
+    module Broadcaster
+      extend self
+
+      # Returns the streamables array that identifies this board's ActionCable stream.
+      #
+      # Pass the returned array directly to turbo-rails helpers:
+      #
+      #   turbo_stream_from(*Broadcaster.stream_name(resource_class: Task, scoped_entity: org))
+      #   Turbo::StreamsChannel.broadcast_stream_to(*stream_name, content:)
+      #
+      # @param resource_class [Class] the ActiveRecord model class for the board
+      # @param scoped_entity [ActiveRecord::Base, nil] the tenant record, or nil
+      #   for portals that are not entity-scoped
+      # @return [Array<String>]
+      def stream_name(resource_class:, scoped_entity:)
+        entity_segment = scoped_entity&.to_gid_param || "global"
+        ["kanban", entity_segment, resource_class.name]
+      end
+
+      # Broadcasts the Turbo Stream HTML to all ActionCable subscribers watching
+      # this board's stream.
+      #
+      # @param resource_class [Class]
+      # @param scoped_entity [ActiveRecord::Base, nil]
+      # @param content [String] the raw turbo-stream HTML (one or more
+      #   <turbo-stream> tags) to push to subscribers
+      def broadcast(resource_class:, scoped_entity:, content:)
+        Turbo::StreamsChannel.broadcast_stream_to(
+          *stream_name(resource_class:, scoped_entity:),
+          content: content
+        )
+      end
+    end
+  end
+end