plutonium 0.60.5 → 0.61.0

data/lib/plutonium/wizard/dsl.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # The author-facing class macros: `step`, `review`, `anchored`, `navigation`,
+    # `cleanup_after`, `concurrency_key`, `one_time`, `encrypt_data`, `anonymous`.
+    # Mixed into {Base}.
+    module DSL
+      extend ActiveSupport::Concern
+
+      # Sentinel distinguishing `cleanup_after` (read) from `cleanup_after nil`.
+      UNSET = Object.new
+      private_constant :UNSET
+
+      # The default concurrency key an anchored wizard gets when it declares no
+      # explicit `concurrency_key`: one in-progress run per (anchor, user). The
+      # tenant folds in automatically (§4.4), and the anchor's GlobalID is already
+      # globally unique, so this is the full identity. Evaluated in the wizard
+      # instance context (where `anchor`/`current_user` live).
+      IMPLIED_ANCHOR_KEY = -> { [anchor, current_user] }
+      private_constant :IMPLIED_ANCHOR_KEY
+
+      class_methods do
+        def steps
+          @steps ||= []
+        end
+
+        # Declare an ordered step.
+        #
+        # `using:` is a step OPTION (never a block method — avoids Ruby's
+        # `Module#using` refinements clash). The block, when present, adds inline
+        # fields on top. Selector options for `using:` (only:/except:/fields:/etc.)
+        # are captured and merged in Task 3.
+        def step(key, label: nil, description: nil, condition: nil, using: nil, **using_opts, &block)
+          assert_not_after_review!(key)
+
+          capture = FieldCapture.build(using:, using_opts:, &block)
+
+          steps << Step.new(
+            key:,
+            label:,
+            description:,
+            condition:,
+            fields: capture,
+            on_submit: capture.delete_hook(:on_submit),
+            on_rollback: capture.delete_hook(:on_rollback),
+            using_spec: capture.using_spec
+          )
+        end
+
+        # Declare the terminal review step (§2.5). Must be last.
+        #
+        # `summary:` (default true) controls the auto-summary of completed steps in
+        # the COMPLETE state: with no custom block, `summary: true` renders the
+        # per-step summary, `summary: false` renders the built-in "ready to
+        # complete" panel instead — for a fully author-owned review. (The summary
+        # always renders in the INCOMPLETE state, where it's the review-and-fix
+        # view, regardless of this flag.)
+        #
+        # `header:` (default true) controls the step-header section (the label +
+        # the "check everything over" prompt). `header: false` drops it entirely,
+        # leaving just the review body in the card — for a chromeless finish.
+        def review(label: "Review", description: nil, condition: nil, summary: true, header: true, &block)
+          assert_not_after_review!(:review)
+          steps << ReviewStep.new(label:, description:, condition:, summary:, header:, block:)
+        end
+
+        # --- anchoring (§3) ---
+
+        # Declare that this wizard runs against an anchor record. Two anchoring
+        # strategies (which may combine):
+        #
+        # - `anchored with: Company` — a TYPE anchor. The anchor is resolved from
+        #   the URL `:id` via the resource controller's scoped, policy-gated
+        #   `resource_record!` (resource-mounted member route). IDOR-safe because
+        #   the record is scoped+authorized.
+        # - `anchored via: :current_scoped_entity` — a CONTEXT anchor. The anchor
+        #   is resolved by calling that method on the controller at request time
+        #   (`:current_user`, `:current_scoped_entity`, or any host method). No
+        #   `:id`, IDOR-safe (trusted context). Mounted portal-level via
+        #   `register_wizard`.
+        # - combined `anchored via: :current_scoped_entity, with: Organization` —
+        #   resolve via the method, then assert the result is an Organization.
+        #
+        # A resolved anchor that is nil raises (anchored-ness is declared).
+        def anchored(with: nil, via: nil, &resolver)
+          @anchored = true
+          @anchor_types = Array(with).presence
+          @anchor_via = via
+          @anchor_resolver = resolver
+        end
+
+        def anchored? = !!@anchored
+
+        def anchor_types = @anchor_types
+
+        # The controller method used to resolve a CONTEXT anchor, or nil for a
+        # TYPE (`with:`-only) anchor.
+        def anchor_via = @anchor_via
+
+        # Whether this wizard's anchor is a CONTEXT anchor (resolved via a method),
+        # as opposed to a TYPE anchor (resolved from the URL `:id`).
+        def anchored_via? = !@anchor_via.nil?
+
+        def anchor_resolver = @anchor_resolver
+
+        # --- navigation (§7) ---
+
+        def navigation(mode = nil)
+          if mode
+            @navigation = mode
+          else
+            @navigation || :linear
+          end
+        end
+
+        # Whether the top rail (the step indicator, §7) is shown. On by default;
+        # `stepper false` hides it for a chromeless flow. Uses UNSET so the `false`
+        # value reads back correctly (a plain `|| true` would re-enable it).
+        def stepper(flag = UNSET)
+          return (@stepper = flag) unless flag.equal?(UNSET)
+          return @stepper unless @stepper.nil?
+          true
+        end
+
+        def stepper? = stepper
+
+        # What a bare launch does when the user already has pending (in-progress)
+        # runs of this wizard. `:prompt` (default) renders a "resume or start new"
+        # chooser so the user's in-progress work isn't silently discarded; `:new`
+        # is the explicit opt-out for wizards that always start fresh, minting a new
+        # run every time. Only meaningful for authenticated TOKENED wizards — keyed
+        # wizards already auto-resume their single keyed run, and `anonymous` runs
+        # are session-keyed; the driving layer no-ops the prompt for both. The
+        # chooser only appears when a pending run actually exists, so `:prompt` is a
+        # safe superset of `:new` (with no pending run it mints fresh either way).
+        def on_relaunch(mode = nil)
+          return @on_relaunch || :prompt if mode.nil?
+          @on_relaunch = mode
+        end
+
+        # Whether a bare launch should show the resume-or-new chooser (§4.5).
+        def relaunch_prompt? = on_relaunch == :prompt
+
+        # --- cleanup (§2.3) ---
+
+        def cleanup_after(ttl = UNSET)
+          if ttl.equal?(UNSET)
+            return @cleanup_after_set ? @cleanup_after : Plutonium.configuration.wizards.cleanup_after
+          end
+          @cleanup_after_set = true
+          @cleanup_after = (ttl == :never) ? nil : ttl
+        end
+
+        # --- concurrency (§4.2) ---
+
+        # Declare the run's CONCURRENCY KEY — the value(s) a run is keyed by
+        # (Solid Queue-style). The keyed session row is created at start
+        # (`in_progress`) and IS the lock: a second launch with the same key
+        # resumes that row instead of forking (at most one in-progress run per
+        # key). Omit → unlimited concurrent runs, each identified by a fresh
+        # `wizard_token` (§4.3).
+        #
+        # The resolver runs in the wizard instance context (where `current_user`,
+        # `current_scoped_entity`, `anchor`, and `wizard_token` are available) and
+        # returns the value(s): records → GlobalID, scalars → to_s, arrays joined.
+        # The portal tenant (`current_scoped_entity`) is ALWAYS folded in
+        # automatically (§4.4) — authors never thread it.
+        #
+        #   concurrency_key { current_user }                 # ≤1 in-progress per user
+        #   concurrency_key { anchor }                        # ≤1 per anchored record (any user)
+        #   concurrency_key { wizard_token }                  # per-run id → tokened/repeatable
+        #   concurrency_key :current_user                     # method shorthand
+        #
+        # An `anchored` (authenticated) wizard with NO explicit key DEFAULTS to
+        # `{ [anchor, current_user] }` — one draft per user per record (see
+        # {IMPLIED_ANCHOR_KEY}). To make an anchored wizard repeatable instead
+        # (a fresh run per launch), declare `concurrency_key { wizard_token }`.
+        def concurrency_key(method = nil, &block)
+          reject_anonymous_keying!("concurrency_key") if anonymous?
+          @concurrency_key =
+            if block
+              block
+            elsif method
+              m = method.to_sym
+              -> { public_send(m) }
+            else
+              raise ArgumentError, "concurrency_key requires a block or a method name"
+            end
+        end
+
+        # Whether this wizard is keyed (keyed/singleton runs) — an explicit
+        # `concurrency_key` OR the implied anchored default.
+        def concurrency_key? = !@concurrency_key.nil? || implied_anchor_key?
+
+        # The resolver proc, or nil when the wizard is tokened. Falls back to the
+        # implied `{ [anchor, current_user] }` for an anchored wizard with no
+        # explicit key.
+        def concurrency_key_resolver
+          @concurrency_key || (implied_anchor_key? ? IMPLIED_ANCHOR_KEY : nil)
+        end
+
+        # Whether the implied anchored key applies: the wizard is `anchored`, isn't
+        # `anonymous` (a guest has no real user to key by — it stays session-keyed),
+        # and declared no explicit `concurrency_key`.
+        def implied_anchor_key? = anchored? && !anonymous? && @concurrency_key.nil?
+
+        # --- repeatability / one-time (§4.3 / §9) ---
+
+        # Opt a wizard into being ONE-TIME: on successful completion the completed
+        # row is RETAINED at its concurrency_key, permanently blocking a restart
+        # (and is what the gate, §9, checks). Without `one_time` the row is DELETED
+        # on completion → repeatable.
+        #
+        # Requires a `concurrency_key` (that's the stable row to retain); a run
+        # with no concurrency_key is tokened and always repeatable. The
+        # requirement is enforced lazily in {#one_time?} so subclass timing and
+        # declaration order don't matter.
+        def one_time
+          reject_anonymous_keying!("one_time") if anonymous?
+          @one_time = true
+        end
+
+        # Whether this wizard is one-time. Raises if `one_time` was declared
+        # without a `concurrency_key` (only keyed runs can be retained). The
+        # `one_time` + `anonymous` conflict is rejected eagerly in the macros
+        # (whichever is declared last raises), so it can't reach here.
+        def one_time?
+          return false unless @one_time
+          unless concurrency_key?
+            raise ArgumentError,
+              "#{name || "wizard"} declares `one_time` without a `concurrency_key`; " \
+              "one-time retention needs a stable key to retain (§4.3)"
+          end
+          true
+        end
+
+        # A custom body for the "already completed" page shown when a finished
+        # ONE-TIME wizard is re-opened (§9). The completion marker is retained but
+        # its `data` is cleared, so there's nothing to review — just a confirmation.
+        # The block renders in the {Plutonium::UI::Page::WizardCompleted} Phlex
+        # context (with the wizard yielded) and REPLACES the default body entirely
+        # (icon/title/message/button — the author supplies their own). Omit for the
+        # built-in confirmation page.
+        #
+        #   completed do |wizard|
+        #     h1 { "You're all set up!" }
+        #     a(href: "/dashboard") { "Go to your dashboard" }
+        #   end
+        def completed(&block)
+          @completed_block = block
+        end
+
+        # The custom completed-page block, or nil for the built-in default.
+        def completed_block = @completed_block
+
+        # --- authentication (§4.5) ---
+
+        # Opt this wizard into GUEST (unauthenticated) access. By default a wizard
+        # requires a `current_user` to enter — entry without one is rejected. An
+        # `anonymous` wizard may run with no `current_user`; its identity is the
+        # server-minted `wizard_token` (httponly/secure/same_site cookie), and it
+        # may authenticate ONLY at its terminal `execute` (e.g. a signup flow). It
+        # NEVER crosses the auth boundary mid-flow (§4.5).
+        def anonymous
+          reject_anonymous_keying!("anonymous") if @concurrency_key || @one_time
+          @anonymous = true
+        end
+
+        def anonymous? = !!@anonymous
+
+        # `anonymous` is mutually exclusive with `concurrency_key`/`one_time`: a
+        # guest's only sound identity is its session token, so the wizard stays
+        # session-keyed and repeatable. A custom `concurrency_key` resolved in a
+        # guest context (`current_user` → nil) would collide every guest on one
+        # run, and `one_time` has no durable principal to retain a completion
+        # against. Rejected eagerly so whichever macro is declared LAST raises,
+        # regardless of order.
+        def reject_anonymous_keying!(macro)
+          raise ArgumentError,
+            "#{name || "wizard"} declares `#{macro}` together with `anonymous`, which are " \
+            "mutually exclusive: a guest's identity is its session token, so the wizard is " \
+            "already session-keyed and repeatable. A `concurrency_key` would collide all " \
+            "guests on one run, and `one_time` has no durable identity to retain against. " \
+            "Drop `anonymous`, or drop `concurrency_key`/`one_time` (§4.5)."
+        end
+
+        # --- encryption (§8.1) ---
+
+        # Opt this wizard's staged `data` into at-rest encryption (§8.1). Pass
+        # `false` to opt OUT explicitly when the app encrypts everything by default
+        # (`config.wizards.encrypt_data`). Left unset, the wizard inherits that
+        # global default.
+        def encrypt_data(flag = true)
+          @encrypt_data = flag
+        end
+
+        # Effective at-rest encryption for this wizard: an explicit `encrypt_data`
+        # (true) / `encrypt_data false` wins; unset inherits the global default
+        # (`config.wizards.encrypt_data`, off unless the app opts in).
+        def encrypt_data?
+          return !!@encrypt_data unless @encrypt_data.nil?
+          Plutonium.configuration.wizards.encrypt_data
+        end
+
+        private
+
+        def assert_not_after_review!(key)
+          return unless steps.any?(&:review?)
+          raise ArgumentError,
+            "`review` must be the last step; cannot declare step :#{key} after it"
+        end
+
+        # Class-level state must not leak into subclasses by reference.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@steps, steps.dup)
+          subclass.instance_variable_set(:@anchored, @anchored)
+          subclass.instance_variable_set(:@anchor_types, @anchor_types)
+          subclass.instance_variable_set(:@anchor_via, @anchor_via)
+          subclass.instance_variable_set(:@anchor_resolver, @anchor_resolver)
+          subclass.instance_variable_set(:@navigation, @navigation)
+          subclass.instance_variable_set(:@stepper, @stepper)
+          subclass.instance_variable_set(:@on_relaunch, @on_relaunch)
+          subclass.instance_variable_set(:@cleanup_after, @cleanup_after)
+          subclass.instance_variable_set(:@cleanup_after_set, @cleanup_after_set)
+          subclass.instance_variable_set(:@concurrency_key, @concurrency_key)
+          subclass.instance_variable_set(:@one_time, @one_time)
+          subclass.instance_variable_set(:@completed_block, @completed_block)
+          subclass.instance_variable_set(:@encrypt_data, @encrypt_data)
+          subclass.instance_variable_set(:@anonymous, @anonymous)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Raised when a wizard requires an anchor record but none is available.
+    class NotAnchoredError < StandardError; end
+
+    # Raised when the `wizard_class` route default does not resolve to a
+    # Plutonium::Wizard::Base subclass (a misconfigured mount, or a tampered
+    # path parameter).
+    class UnknownWizardError < StandardError; end
+
+    # Raised when a wizard step fails. Carries the attribute the error should be
+    # attached to (defaults to +:base+) so it can be surfaced on a form.
+    class StepError < StandardError
+      # @return [Symbol] the attribute the error applies to
+      attr_reader :attribute
+
+      # @param message [String, nil] the error message
+      # @param attribute [Symbol] the attribute the error applies to
+      def initialize(message = nil, attribute: :base)
+        @attribute = attribute
+        super(message)
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/field_capture.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Records the field surface declared inside a `step` block.
+    #
+    # A step block reuses Plutonium's existing field DSL — `attribute`, `input`,
+    # `validates`, `structured_input`, `form_layout` — plus the per-step hooks
+    # `on_submit` and `on_rollback`. This object captures all of it by
+    # `instance_exec`-ing the block against itself.
+    #
+    # The union `data` schema (§2.6) is built from inline `attribute name, type`
+    # declarations recorded here as `attribute_schema` ({name => type}).
+    #
+    # `using:` import (a model — see FieldImporter) is recorded as a marker
+    # (`using_spec`) and merged lazily; this object only captures inline
+    # declarations and composes them over the resolved import (inline wins).
+    class FieldCapture
+      include Plutonium::Definition::DefineableProps
+      include Plutonium::Definition::StructuredInputs
+      include Plutonium::Definition::FormLayout
+
+      defineable_props :field, :input
+
+      attr_reader :validations, :hooks, :using_spec
+
+      def self.build(using: nil, using_opts: {}, &block)
+        capture = new
+        capture.record_using(using, using_opts) if using
+        capture.instance_exec(&block) if block
+        capture
+      end
+
+      def initialize
+        @inline_attribute_schema = {}
+        @inline_attribute_options = {}
+        @validations = []
+        @hooks = {}
+      end
+
+      # Inline `attribute :name, :type` — records the union-schema type and any
+      # options (default:, etc.), which are threaded into the typed `data`
+      # snapshot so e.g. `default:` applies (§2.6).
+      def attribute(name, type = :string, **options)
+        key = name.to_sym
+        @inline_attribute_schema[key] = type
+        @inline_attribute_options[key] = options unless options.empty?
+        self
+      end
+
+      # The effective union-schema types for this step ({name => type}), composing
+      # a `using:` import with inline `attribute` declarations — **inline wins on a
+      # name conflict** (§2.4). The imported surface is resolved lazily.
+      def attribute_schema
+        imported_spec ? imported_spec.attribute_schema.merge(@inline_attribute_schema) : @inline_attribute_schema
+      end
+
+      # The effective per-attribute options ({name => {default:, ...}}). Imports
+      # contribute none (types come from the source; options stay inline); inline
+      # declarations are returned as-is.
+      def attribute_options
+        @inline_attribute_options
+      end
+
+      # The effective input config ({name => {options:, block:}}) — imported inputs
+      # composed with inline `input`/`field` declarations, inline winning on
+      # conflict. Drives the step form (Task 6).
+      def inputs
+        imported = imported_spec ? imported_spec.inputs : {}
+        imported.merge(defined_inputs)
+      end
+
+      # The form_layout for this step (§7.1 resolution order): an inline
+      # `form_layout` wins; else the layout inherited from a `using:` source
+      # (already filtered to the imported fields); else nil (default single grid).
+      def form_layout_sections
+        @form_layout || imported_spec&.form_layout
+      end
+
+      # The imported validation runner ({attribute => [messages]} over a data
+      # slice), or nil when there's no `using:` import or `validate: false`. The
+      # runner (Task 4) combines this with inline `validates`.
+      def imported_validate_fn
+        imported_spec&.validate_fn
+      end
+
+      # The imported model's form-relevant validators ([[name], options] pairs),
+      # replayed onto the typed data class so imported fields render their
+      # required/length/etc. metadata. Empty without a `using:` import. Distinct
+      # from `validations` (inline, runner-bound) so imports aren't double-validated.
+      def imported_form_validators
+        imported_spec&.form_validators || []
+      end
+
+      # The resolved `using:` import surface, or nil. Memoized.
+      def imported_spec
+        return @imported_spec if defined?(@imported_spec)
+        @imported_spec =
+          if @using_spec
+            FieldImporter.resolve(using: @using_spec[:using], opts: @using_spec[:opts])
+          end
+      end
+
+      # Inline `validates` — recorded as raw args for the runner (Task 4) to apply.
+      def validates(*args, **options)
+        @validations << [args, options]
+        self
+      end
+
+      # Instance-level structured_input: the step block runs at instance level,
+      # but the StructuredInputs concern only exposes a class method. Record into
+      # a per-instance registry mirroring `defined_structured_inputs`.
+      def structured_input(name, **options, &block)
+        unless block || options[:using] || options[:fields]
+          raise ArgumentError,
+            "`structured_input :#{name}` needs a block, `using:`, or `fields:`"
+        end
+        instance_structured_inputs[name] = {options:, block:}.compact
+      end
+
+      def defined_structured_inputs
+        instance_structured_inputs
+      end
+
+      def on_submit(&block)
+        @hooks[:on_submit] = block
+      end
+
+      def on_rollback(&block)
+        @hooks[:on_rollback] = block
+      end
+
+      # form_layout is provided by the FormLayout concern as a class method; the
+      # step block runs at instance level, so expose an instance-level shim that
+      # records onto this capture's own builder.
+      def form_layout(&block)
+        raise ArgumentError, "`form_layout` requires a block" unless block
+        builder = Plutonium::Definition::FormLayout::Builder.new
+        builder.instance_exec(&block)
+        @form_layout = builder.sections.freeze
+      end
+
+      def record_using(using, opts)
+        @using_spec = {using:, opts: opts || {}}
+      end
+
+      # Pop a recorded hook (used by the DSL when building the Step).
+      def delete_hook(name) = @hooks.delete(name)
+
+      private
+
+      def instance_structured_inputs
+        @instance_structured_inputs ||= {}
+      end
+    end
+  end
+end