plutonium 0.60.5 → 0.61.0

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,55 @@ 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
+          end
+        end
       end
 
       def defined_index_views = self.class.defined_index_views
@@ -90,6 +141,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

data/lib/plutonium/kanban/column.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Kanban
+    class Column
+      ROLE_PRESETS = {
+        backlog: {add: true},
+        done: {color: :green, collapsed: true}
+      }.freeze
+
+      attr_reader :key, :label, :color, :wip, :scope, :on_drop, :accepts, :actions
+
+      def initialize(key, label: nil, color: nil, wip: nil, scope: nil, on_drop: nil,
+        collapsed: nil, add: nil, accepts: nil, locked: nil, role: nil)
+        preset = role ? ROLE_PRESETS.fetch(role) { raise ArgumentError, "Unknown column role: #{role.inspect}. Valid: #{ROLE_PRESETS.keys.inspect}" } : {}
+        @key = key.to_sym
+        @label = label || key.to_s.titleize
+        @color = color.nil? ? preset[:color] : color
+        @wip = wip
+        @scope = scope
+        @on_drop = on_drop
+        @collapsed = collapsed.nil? ? preset[:collapsed] : collapsed
+        @add = add.nil? ? preset[:add] : add
+        @accepts = accepts.nil? || accepts
+        @locked = locked || false
+        @actions = []
+      end
+
+      def action(key, interaction:, on: :all, label: nil, icon: nil, confirmation: nil)
+        @actions << Action.new(key: key.to_sym, interaction:, on:, label:, icon:, confirmation:)
+      end
+
+      def collapsed? = !!@collapsed
+      def add? = !!@add
+      def locked? = @locked
+
+      # Column-level accepts check — used for client-side drop hints and as the
+      # first gate in the move handler (before the record is needed).
+      # Proc accepts: is treated as permissive at the column level; call
+      # accepts_record? with the actual record to evaluate the predicate.
+      def accepts?(source_key)
+        case @accepts
+        when Array then @accepts.include?(source_key)
+        when true, false then @accepts
+        # Proc/predicate case: permit at the column level here; the move handler
+        # evaluates the predicate per-card via accepts_record? with the actual record.
+        else true
+        end
+      end
+
+      # Per-card accepts check — evaluates a Proc accepts: against the actual
+      # record.  Called by the move handler after the record is loaded.
+      #
+      # Convention for Proc accepts:
+      #   accepts: ->(card) { … }   # receives the record, returns true/false
+      #
+      # For non-Proc values the behaviour matches accepts?(source_key) exactly,
+      # so the move handler can unconditionally switch to accepts_record?.
+      def accepts_record?(record, source_key)
+        case @accepts
+        when Array then @accepts.include?(source_key)
+        when true, false then @accepts
+        when Proc then @accepts.call(record)
+        else true
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/kanban/context.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Plutonium
+  module Kanban
+    # Evaluation scope for dynamic `columns do…end` blocks at request time.
+    #
+    # Delegates everything to the request's view_context so the block can call
+    # current_user, current_scoped_entity, params, helpers, etc. directly —
+    # exactly like Plutonium::Action::ConditionContext does for action conditions.
+    class Context < SimpleDelegator
+    end
+  end
+end

data/lib/plutonium/kanban/dsl.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Kanban
+    class DSL
+      def self.build(&block)
+        dsl = new
+        dsl.instance_eval(&block) if block
+        dsl.to_board
+      end
+
+      def initialize
+        @columns = []
+        @columns_block = nil
+        @card_fields = nil
+        @per_column = nil
+        @realtime = false
+        @position_config = Positioning::Config.default
+        @lazy = true
+        @show_in = nil
+      end
+
+      def column(key, **opts, &blk)
+        col = Column.new(key, **opts)
+        col.instance_eval(&blk) if blk
+        @columns << col
+      end
+
+      # Fluent DSL setters — `attr_writer` would change the call syntax
+      # (`per_column 25` → `self.per_column = 25`), so keep them as methods.
+      # standard:disable Style/TrivialAccessors
+      def columns(&blk) = @columns_block = blk
+      def card_fields(**slots) = @card_fields = slots
+      def per_column(n) = @per_column = n
+      def realtime(v = true) = @realtime = v
+      def lazy(v = true) = @lazy = v
+      # standard:enable Style/TrivialAccessors
+
+      # Overrides where a card click opens the record's show page, for this
+      # board only:
+      #   :modal — open in a centered modal dialog
+      #   :page  — navigate the whole page to the show route
+      # When unset, the board inherits the definition's `show_in` (default :page).
+      def show_in(mode) = @show_in = mode # standard:disable Style/TrivialAccessors
+
+      def position_on(attr = :position, &blk)
+        @position_config =
+          if attr == false
+            Positioning::Config.disabled
+          elsif blk
+            Positioning::Config.with_block(attr, blk)
+          else
+            Positioning::Config.attribute(attr)
+          end
+      end
+
+      def to_board
+        Board.new(
+          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
+        )
+      end
+    end
+  end
+end

data/lib/plutonium/kanban/grouping.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Kanban
+    # Groups an already-authorized, query-applied, UN-paginated relation into
+    # ordered, per_column-capped column entries.
+    module Grouping
+      module_function
+
+      # Returns [{column:, cards: [records], total: Integer}, ...] in column order.
+      def call(board:, relation:, context:)
+        columns = resolve_columns(board, context)
+        pos = board.position_config
+        columns.map do |col|
+          scoped = apply_scope(relation, col.scope)
+          ordered = pos.order(scoped)
+          if board.per_column
+            total = ordered.count
+            cards = ordered.limit(board.per_column).to_a
+          else
+            cards = ordered.to_a
+            total = cards.size
+          end
+          {column: col, cards: cards, total: total}
+        end
+      end
+
+      # Resolves the column list from a board. For dynamic boards, evaluates
+      # the columns_block against the context (which exposes current_user,
+      # params, etc. via delegation to view_context). Public so Task 7 (move
+      # handler) can call Grouping.resolve_columns(board, context) directly.
+      def resolve_columns(board, context)
+        return board.columns unless board.dynamic?
+        Array(context.instance_exec(&board.columns_block)).flatten
+      end
+
+      # Applies a column scope to a relation.
+      #   Symbol → relation.public_send(sym)   (named scope)
+      #   Proc   → relation.instance_exec(&scope) (inline lambda, e.g. -> { where(status: "todo") })
+      #   nil    → relation unchanged
+      def apply_scope(relation, scope)
+        case scope
+        when Symbol then relation.public_send(scope)
+        when Proc then relation.instance_exec(&scope)
+        when nil then relation
+        else raise ArgumentError, "Unsupported column scope: #{scope.inspect} (expected Symbol, Proc, or nil)"
+        end
+      end
+    end
+  end
+end