plutonium 0.60.5 → 0.61.0

data/lib/plutonium/kanban/positioning.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "plutonium/positioning"
+
+module Plutonium
+  module Kanban
+    module Positioning
+      # Value object passed to Mode B blocks, carrying the full drop context.
+      Move = Data.define(:record, :column, :prev, :next, :index)
+
+      # Strategy configuration object created by the `position_on` DSL.
+      #
+      # Three modes:
+      #   Mode A (:delegate) — delegate reposition! to Plutonium::Positioning concern
+      #   Mode B (:block)    — call a user-supplied block with a Move
+      #   Mode C (:disabled) — no ordering; relation returned unchanged
+      class Config
+        # Mode A, default attribute :position
+        def self.default
+          new(:delegate, :position, nil)
+        end
+
+        # Mode A, custom attribute
+        def self.attribute(attr)
+          new(:delegate, attr.to_sym, nil)
+        end
+
+        # Mode B — orders by attr, write delegated to block
+        def self.with_block(attr, block)
+          new(:block, attr.to_sym, block)
+        end
+
+        # Mode C — disabled
+        def self.disabled
+          new(:disabled, nil, nil)
+        end
+
+        attr_reader :attribute
+
+        def initialize(mode, attribute, block)
+          @mode = mode
+          @attribute = attribute
+          @block = block
+        end
+
+        def disabled?
+          @mode == :disabled
+        end
+
+        # Apply positional ordering to a relation.
+        # Mode A/B: relation.reorder(attribute)
+        # Mode C:   return relation unchanged
+        def order(relation)
+          return relation if disabled?
+          relation.reorder(@attribute)
+        end
+
+        # Persist the new position for a dropped record.
+        # Mode A: delegate to record.reposition!(prev_record:, next_record:)
+        # Mode B: call the user block with a Move
+        # Mode C: no-op
+        def reposition!(record:, column:, prev_record:, next_record:, index:)
+          case @mode
+          when :delegate
+            record.reposition!(prev_record:, next_record:)
+          when :block
+            @block.call(Move.new(record:, column:, prev: prev_record, next: next_record, index:))
+          when :disabled
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/kanban.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "plutonium/positioning"
+require "plutonium/kanban/positioning"
+require "plutonium/kanban/action"
+require "plutonium/kanban/column"
+require "plutonium/kanban/board"
+require "plutonium/kanban/dsl"
+require "plutonium/kanban/context"
+require "plutonium/kanban/grouping"
+require "plutonium/kanban/broadcaster"

data/lib/plutonium/migrations.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Plutonium
+  # Registry of per-feature migration paths.
+  #
+  # Features register their migration directory against a configuration key. A
+  # path is only surfaced by {.enabled_paths} when its feature's config
+  # (+Plutonium.configuration.<feature>+) responds to +.enabled+ and it is true.
+  module Migrations
+    @registry = {}
+
+    class << self
+      # Register a migration path for a feature.
+      #
+      # @param feature [Symbol, String] the configuration key (e.g. +:wizards+)
+      # @param path [String] the absolute migration directory path
+      # @return [String] the registered path
+      def register(feature, path)
+        @registry[feature.to_sym] = path
+      end
+
+      # Clear the registry. Intended for tests.
+      #
+      # @return [Hash]
+      def reset!
+        @registry = {}
+      end
+
+      # Migration paths for features that are currently enabled.
+      #
+      # @return [Array<String>]
+      def enabled_paths
+        @registry.filter_map do |feature, path|
+          cfg = Plutonium.configuration.public_send(feature) if Plutonium.configuration.respond_to?(feature)
+          path if cfg&.respond_to?(:enabled) && cfg.enabled
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/positioning.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Plutonium
+  # Standalone decimal/fractional ordering. Kanban-independent.
+  #
+  # Including this concern and calling `positioned_on` gives a model:
+  # - automatic position assignment on create (appends to the end of its scope group)
+  # - `reposition!(prev_record:, next_record:)` for drag-and-drop reordering
+  # - `backfill_positions!` class method to number existing rows
+  #
+  # Pure math helpers are exposed as module-level methods so they can be
+  # called without an AR instance:
+  #   Plutonium::Positioning.position_between(1.0, 3.0)  # => 2.0
+  #   Plutonium::Positioning.gap_exhausted?(1.0, 1.0)    # => true
+  module Positioning
+    extend ActiveSupport::Concern
+
+    EPSILON = 1e-6
+
+    # Returns the position that sits between +prev_val+ and +next_val+.
+    #
+    # Rules:
+    #   both nil  → 0.0            (first item in an empty list)
+    #   prev nil  → next_val - 1   (prepend)
+    #   next nil  → prev_val + 1   (append)
+    #   else      → midpoint
+    def self.position_between(prev_val, next_val)
+      return 0.0 if prev_val.nil? && next_val.nil?
+      return next_val - 1 if prev_val.nil?
+      return prev_val + 1 if next_val.nil?
+      (prev_val + next_val) / 2.0
+    end
+
+    # Returns true when +prev_val+ and +next_val+ are so close together
+    # that inserting a new midpoint would produce a duplicate.
+    def self.gap_exhausted?(prev_val, next_val)
+      return false if prev_val.nil? || next_val.nil?
+      (next_val - prev_val).abs < EPSILON
+    end
+
+    included do
+      class_attribute :positioning_column, instance_accessor: false, default: :position
+      class_attribute :positioning_scope_attr, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      # Opt in to positional ordering.
+      #
+      #   positioned_on :position, scope: :status
+      #
+      # @param column [Symbol] the decimal column that stores positions
+      # @param scope  [Symbol, nil] group rows by this column; nil = single global group
+      def positioned_on(column = :position, scope: nil)
+        self.positioning_column = column
+        self.positioning_scope_attr = scope
+        before_create :assign_initial_position
+      end
+
+      # Number every row in the table per scope group as 1.0, 2.0, … in
+      # +order+ order. Safe to call on an empty table.
+      #
+      # @param order [Symbol] column to sort by when assigning positions
+      def backfill_positions!(order: :created_at)
+        groups = positioning_scope_attr ? all.group_by(&positioning_scope_attr) : {nil => all.to_a}
+        groups.each_value do |rows|
+          ActiveRecord::Base.transaction do
+            rows.sort_by { |r| r.public_send(order) }.each_with_index do |row, i|
+              row.update_column(positioning_column, (i + 1).to_f)
+            end
+          end
+        end
+      end
+    end
+
+    # Move this record so it sits between +prev_record+ and +next_record+
+    # within its scope group. Pass nil for either neighbor to move to an end.
+    #
+    # If the gap between the two neighbors is exhausted (too small to split)
+    # the scope group is rebalanced first so that fresh integer positions are
+    # available, then the record is positioned between the reloaded neighbors.
+    #
+    # @param prev_record [ActiveRecord::Base, nil]
+    # @param next_record [ActiveRecord::Base, nil]
+    def reposition!(prev_record:, next_record:)
+      col = self.class.positioning_column
+      prev_val = prev_record&.public_send(col)
+      next_val = next_record&.public_send(col)
+      if Plutonium::Positioning.gap_exhausted?(prev_val, next_val)
+        rebalance_scope_group!
+        prev_val = prev_record&.reload&.public_send(col)
+        next_val = next_record&.reload&.public_send(col)
+      end
+      update!(col => Plutonium::Positioning.position_between(prev_val, next_val))
+    end
+
+    private
+
+    def assign_initial_position
+      col = self.class.positioning_column
+      return if public_send(col).present?
+      max = positioning_group_relation.maximum(col) || 0.0
+      public_send(:"#{col}=", max + 1)
+    end
+
+    def positioning_group_relation
+      rel = self.class.all
+      attr = self.class.positioning_scope_attr
+      attr ? rel.where(attr => public_send(attr)) : rel
+    end
+
+    def rebalance_scope_group!
+      col = self.class.positioning_column
+      ActiveRecord::Base.transaction do
+        positioning_group_relation.order(col).each_with_index do |row, i|
+          row.update_column(col, (i + 1).to_f)
+        end
+      end
+    end
+
+    # Migration helper that adds a position column pre-tuned for fractional
+    # ordering. Mixed into ActiveRecord's table-definition classes by the
+    # railtie, so it is available in both create_table and change_table:
+    #
+    #   create_table :tasks do |t|
+    #     t.position                # decimal :position, precision: 16, scale: 8
+    #     t.position :sort_order    # custom column name
+    #     t.position index: true    # also add a single-column index
+    #   end
+    #
+    #   change_table :tasks do |t|
+    #     t.position
+    #   end
+    #
+    # The precision/scale give midpoints ample headroom over the rebalance
+    # threshold (EPSILON = 1e-6) — a too-small scale lets the last subdivision
+    # round to a neighbor. Pass precision:/scale: to override.
+    module MigrationHelpers
+      DEFAULT_PRECISION = 16
+      DEFAULT_SCALE = 8
+
+      def position(name = :position, **options)
+        column name, :decimal, precision: DEFAULT_PRECISION, scale: DEFAULT_SCALE, **options
+      end
+    end
+  end
+end

data/lib/plutonium/railtie.rb

@@ -39,6 +39,30 @@ module Plutonium
       load_plutonium_initializers
     end
 
+    initializer "plutonium.register_migrations" do
+      Plutonium::Migrations.register(:wizards, Plutonium.root.join("db/migrate/wizard").to_s)
+    end
+
+    # Runs after the host's config/initializers/plutonium.rb (load_config_initializers)
+    # so feature flags like config.wizards.enabled are honoured. Railtie
+    # initializers otherwise run before host initializers, leaving the flag false.
+    initializer "plutonium.migrations", after: :load_config_initializers do |app|
+      # v1 supports `config.wizards.database == :primary` only; the option is
+      # reserved for future multi-db routing of wizard sessions. Fail loudly on an
+      # unsupported value rather than silently registering on the primary database.
+      if Plutonium.configuration.wizards.enabled &&
+          Plutonium.configuration.wizards.database != :primary
+        raise ArgumentError,
+          "config.wizards.database = #{Plutonium.configuration.wizards.database.inspect} is not " \
+          "supported (only :primary). Multi-database routing for wizard sessions is a roadmap follow-up."
+      end
+
+      Plutonium::Migrations.enabled_paths.each do |path|
+        app.config.paths["db/migrate"] << path
+        ActiveRecord::Migrator.migrations_paths << path unless ActiveRecord::Migrator.migrations_paths.include?(path)
+      end
+    end
+
     initializer "plutonium.asset_server" do
       setup_development_asset_server if Plutonium.configuration.development?
     end
@@ -47,6 +71,14 @@ module Plutonium
       extend_action_dispatch
     end
 
+    # Make `t.position` available in create_table / change_table blocks.
+    initializer "plutonium.positioning" do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::ConnectionAdapters::TableDefinition.include(Plutonium::Positioning::MigrationHelpers)
+        ActiveRecord::ConnectionAdapters::Table.include(Plutonium::Positioning::MigrationHelpers)
+      end
+    end
+
     initializer "plutonium.phlexi_themes" do
       setup_phlexi_themes
     end
@@ -97,6 +129,7 @@ module Plutonium
 
     def extend_action_dispatch
       ActionDispatch::Routing::Mapper.prepend Plutonium::Routing::MapperExtensions
+      ActionDispatch::Routing::Mapper.prepend Plutonium::Routing::WizardRegistration
       ActionDispatch::Routing::RouteSet.prepend Plutonium::Routing::RouteSetExtensions
       Rails::Engine.include Plutonium::Routing::ResourceRegistration
     end

data/lib/plutonium/resource/controller.rb

@@ -14,7 +14,9 @@ module Plutonium
       include Plutonium::Resource::Controllers::Presentable
       include Plutonium::Resource::Controllers::Queryable
       include Plutonium::Resource::Controllers::CrudActions
+      include Plutonium::Resource::Controllers::KanbanActions
       include Plutonium::Resource::Controllers::InteractiveActions
+      include Plutonium::Resource::Controllers::WizardActions
       include Plutonium::Resource::Controllers::Typeahead
       include Plutonium::Resource::Controllers::ExportCsv
       include Plutonium::StructuredInputs::ParamsConcern

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

@@ -142,7 +142,7 @@ module Plutonium
                 notice: "#{resource_class.model_name.human} was successfully deleted."
             end
             format.json { head :no_content }
-          rescue ActiveRecord::InvalidForeignKey
+          rescue ActiveRecord::InvalidForeignKey, ActiveRecord::DeleteRestrictionError
             format.turbo_stream do
               flash.alert = "#{resource_class.model_name.human} is referenced by other records."
               render turbo_stream: helpers.turbo_stream_redirect(resource_url_for(resource_record!))