plutonium 0.60.5 → 0.62.0

data/lib/plutonium/ui/wizard/review.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Wizard
+      # The terminal review step's body (§2.5), a small state machine (see
+      # {#render_mode}):
+      #
+      #   - INCOMPLETE (a visible step is unvisited/invalid) → a "fix this" jump
+      #     link per outstanding step + an auto-summary of what's entered so far.
+      #   - COMPLETE + custom block → the author's block, rendered bare.
+      #   - COMPLETE + no block, `summary: true` (default) → the auto-summary of
+      #     every visible step's collected `data` (via SummaryDisplay).
+      #   - COMPLETE + no block, `summary: false` → the built-in "ready to
+      #     complete" panel (for a fully author-owned / chromeless review).
+      #
+      # The Finish button is rendered by the page (gated: disabled while any
+      # visible step is incomplete); this component only renders the body.
+      class Review < Plutonium::UI::Component::Base
+        # @param runner  [Plutonium::Wizard::Runner]
+        # @param step_url [Proc] step_key → GET url, for the fix-this links.
+        def initialize(runner:, step_url:)
+          @runner = runner
+          @step_url = step_url
+        end
+
+        def view_template
+          render_outstanding if show_outstanding?
+          render_summary if show_summary?
+          render_custom_block if show_custom?
+          render_ready if show_ready?
+        end
+
+        private
+
+        # The review body composes from these pieces (see the `review summary:`
+        # macro). Order of render: outstanding → summary → custom → ready.
+        #
+        #   - outstanding banner — while any visible step is incomplete.
+        #   - summary cards      — whenever the auto-summary is on: the
+        #     review-and-fix view when incomplete, the check-before-finish view
+        #     when complete.
+        #   - custom block       — author content, ONLY once complete; sits BELOW
+        #     the summary when summary is on, and REPLACES it when summary is off.
+        #   - ready panel        — complete + summary off + no custom block: the
+        #     built-in "ready to complete" confirmation (chromeless finish).
+        def show_outstanding? = !complete?
+
+        def show_summary? = summary?
+
+        def show_custom? = complete? && !custom_block.nil?
+
+        def show_ready? = complete? && !summary? && custom_block.nil?
+
+        def complete? = @runner.incomplete_visible_steps.empty?
+
+        def summary? = @runner.current_step.summary?
+
+        def custom_block = @runner.current_step.block
+
+        def steps = @runner.visible_path.reject(&:review?)
+
+        # The step's typed `data` sub-object (`data.<step>`), the summary's source.
+        def step_data(step) = @runner.wizard.data[step.key]
+
+        def render_outstanding
+          incomplete = @runner.incomplete_visible_steps
+          return if incomplete.empty?
+
+          div(class: "pu-wizard-review-outstanding rounded-lg border border-warning-300 bg-warning-50 dark:border-warning-800 dark:bg-warning-950/30 p-4 mb-6", role: "alert") do
+            p(class: "text-sm font-medium text-[var(--pu-text)] mb-2") do
+              "Some steps still need attention before you can finish:"
+            end
+            ul(class: "space-y-1") do
+              incomplete.each do |step|
+                li do
+                  a(
+                    href: @step_url.call(step.key),
+                    class: "text-sm font-medium text-primary-600 dark:text-primary-400 hover:underline",
+                    data: {wizard_review_fix: step.key}
+                  ) { "Fix #{step.label}" }
+                end
+              end
+            end
+          end
+        end
+
+        def render_summary
+          div(class: "space-y-4") do
+            steps.each do |step|
+              fields = summary_fields(step)
+              structured = step.structured_inputs
+              next if fields.empty? && structured.empty?
+
+              render_step_card(step, fields, structured)
+            end
+          end
+        end
+
+        # One step rendered as a card: a titled header strip (label + Edit) over a
+        # body that holds the scalar summary and any structured collections.
+        def render_step_card(step, fields, structured)
+          section(
+            class: "pu-wizard-review-step overflow-hidden rounded-[var(--pu-radius-lg)] border border-[var(--pu-border)] bg-[var(--pu-surface)] shadow-[var(--pu-shadow-sm)]",
+            data: {wizard_review_step: step.key}
+          ) do
+            div(class: "flex items-center justify-between gap-3 border-b border-[var(--pu-border)] bg-[var(--pu-surface-alt)] px-5 py-3") do
+              h3(class: "text-sm font-semibold text-[var(--pu-text)]") { step.label.to_s }
+              a(
+                href: @step_url.call(step.key),
+                class: "shrink-0 text-xs font-medium text-primary-600 dark:text-primary-400 hover:underline"
+              ) { "Edit" }
+            end
+            div(class: "px-5 py-4") do
+              # Decorate so attachment fields resolve to displayable attachments —
+              # the SummaryDisplay then renders them through the normal attachment
+              # display component, not the raw token string.
+              if fields.any?
+                render SummaryDisplay.new(
+                  Plutonium::Wizard::AttachmentData.wrap(step_data(step), step),
+                  fields:, inputs: step.inputs
+                )
+              end
+              render_structured(step) if structured.any?
+            end
+          end
+        end
+
+        def summary_fields(step)
+          step.attribute_schema.keys.map(&:to_sym)
+        end
+
+        # Repeatable `structured_input` collections aren't scalar `data` attributes,
+        # so the SummaryDisplay can't render them — summarise each collection as a
+        # labelled list of its non-empty rows (blank trailing rows are dropped).
+        def render_structured(step)
+          data = step_data(step)
+          step.structured_inputs.each_key do |name|
+            rows = Array(data.public_send(name))
+              .map(&:to_h)
+              .reject { |row| row.values.all?(&:blank?) }
+
+            div(class: "pu-wizard-review-collection mt-4 first:mt-0", data: {wizard_review_collection: name}) do
+              h4(class: "mb-2 text-xs font-semibold uppercase tracking-wide text-[var(--pu-text-muted)]") do
+                name.to_s.humanize
+              end
+              if rows.empty?
+                p(class: "text-sm text-[var(--pu-text-subtle)]") { "None" }
+              else
+                ul(class: "space-y-1.5") do
+                  rows.each do |row|
+                    li(class: "flex flex-wrap items-center gap-x-2 gap-y-0.5 rounded-[var(--pu-radius-md)] bg-[var(--pu-surface-alt)] px-3 py-2 text-sm text-[var(--pu-text)]") do
+                      row.each do |key, value|
+                        span do
+                          span(class: "text-[var(--pu-text-muted)]") { "#{key.to_s.humanize}: " }
+                          plain value.to_s
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        # The review step's custom block, rendered BARE — just a spacing + targeting
+        # wrapper, no surface/border/typography of its own — so the author has full
+        # control over the body's look.
+        def render_custom_block
+          div(class: "pu-wizard-review-custom", data: {wizard_review_custom: true}) do
+            instance_exec(@runner.wizard, &custom_block)
+          end
+        end
+
+        # The built-in "ready to complete" panel: shown when everything is valid,
+        # there's no custom block, and the auto-summary is turned off (`summary:
+        # false`). A clean confirmation so a chromeless review still reads as done.
+        def render_ready
+          div(
+            class: "pu-wizard-review-ready flex flex-col items-center text-center py-6",
+            data: {wizard_review_ready: true}
+          ) do
+            div(class: "mb-4 flex h-14 w-14 items-center justify-center rounded-full bg-success-100 text-success-600 dark:bg-success-900/30 dark:text-success-400") do
+              render Phlex::TablerIcons::Check.new(class: "h-7 w-7")
+            end
+            h3(class: "text-lg font-semibold tracking-tight text-[var(--pu-text)]") { "You're all set" }
+            p(class: "mt-1.5 max-w-prose text-sm text-[var(--pu-text-muted)]") do
+              "Everything looks good. Click Finish to complete."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/wizard/stepper.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Wizard
+      # The horizontal step indicator (§7). Renders the visible step path with a
+      # completed / current / upcoming state per step. Navigation mode gates which
+      # steps are clickable:
+      #
+      #   - :linear → only already-visited steps link back (no forward jumps).
+      #   - :free   → any visited step links (still no forward jumps to unvisited).
+      #
+      # Branch-hidden steps are simply absent from `visible_path`, so they never
+      # appear here.
+      class Stepper < Plutonium::UI::Component::Base
+        # @param steps     [Array<Step>] the visible path.
+        # @param current   [Step] the current step.
+        # @param visited   [Array<String>] visited (reached) step keys.
+        # @param complete  [Array<String>] keys of steps that are actually complete
+        #   (submitted AND valid) — distinct from `visited`. A step can be reached
+        #   (e.g. the cursor landed on a branch step) without being completed.
+        # @param navigation [Symbol] :linear or :free.
+        # @param step_url   [Proc] step_key → GET url.
+        def initialize(steps:, current:, visited:, navigation:, step_url:, complete: [])
+          @steps = steps
+          @current = current
+          @visited = visited.map(&:to_s)
+          @complete = complete.map(&:to_s).to_set
+          @navigation = navigation
+          @step_url = step_url
+        end
+
+        def view_template
+          nav(class: "pu-wizard-stepper mb-7", aria_label: "Progress") do
+            ol(class: "pu-wizard-steps") do
+              @steps.each_with_index do |step, index|
+                render_step(step, index)
+              end
+            end
+          end
+        end
+
+        private
+
+        # One step: a numbered node on the connector track + a label beneath. Both
+        # are wrapped in a link when the step is reachable (CSS draws the track,
+        # node states, and the done check via [data-state]).
+        def render_step(step, index)
+          state = step_state(step)
+          # `data-terminal` marks the review node so the CSS suppresses the
+          # "completed" checkmark for it — it's the finish flag, never a done-check.
+          li(data: {state:, wizard_stepper_state: state, terminal: step.review? ? "true" : nil}) do
+            if clickable?(step, state)
+              a(href: @step_url.call(step.key), class: "pu-step-link",
+                aria_current: (state == :current) ? "step" : nil) do
+                render_node(step, index)
+                span(class: "pu-step-label") { step.label.to_s }
+              end
+            else
+              span(class: "pu-step-link") do
+                render_node(step, index)
+                span(class: "pu-step-label",
+                  aria_current: (state == :current) ? "step" : nil) { step.label.to_s }
+              end
+            end
+          end
+        end
+
+        # The node: a numbered badge for a real step. The terminal review step isn't
+        # a numbered step (it's the "finish line"), so it shows a flag icon instead —
+        # no step number, here or in the card header (see Page::Wizard).
+        def render_node(step, index)
+          span(class: "pu-step-node") do
+            if step.review?
+              render_review_icon
+            else
+              # Review is always last, so a real step's index in the full path is
+              # also its position among real steps → a clean 1-based badge.
+              span(class: "pu-step-number") { (index + 1).to_s }
+            end
+          end
+        end
+
+        def render_review_icon
+          render Phlex::TablerIcons::Flag.new(class: "pu-step-flag w-4 h-4")
+        end
+
+        # A step's visual state. `:completed` (the done-check) means actually
+        # complete — submitted AND valid — NOT merely reached: a branch step the
+        # cursor landed on but that was never submitted (or is now invalid) is
+        # `:incomplete`, so the rail never claims a step is done when the review
+        # still lists it under "needs attention". The terminal review node is the
+        # finish flag, so it reads `:completed` once reached (its check is suppressed
+        # by `data-terminal`).
+        def step_state(step)
+          return :current if step.key.to_s == @current&.key.to_s
+          if @visited.include?(step.key.to_s)
+            return :completed if step.review? || @complete.include?(step.key.to_s)
+            return :incomplete
+          end
+          :upcoming
+        end
+
+        # Which step headers link. Mirrors the engine's `Runner#go_to` reachability
+        # so the stepper never offers (or withholds) a jump the engine would reject:
+        #
+        #   - the current step never links to itself;
+        #   - the terminal review step links once the flow has started (any step
+        #     visited) — it's never itself "visited" (you Finish from it, you don't
+        #     advance past it), so without this it would be permanently unclickable,
+        #     stranding a user who navigated back from it;
+        #   - every other step links once visited. Forward jumps to unvisited steps
+        #     stay disallowed.
+        def clickable?(step, state)
+          return false if state == :current
+          return @visited.any? if step.review?
+          @visited.include?(step.key.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/wizard/summary_display.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    module Wizard
+      # A tiny read-only display over the wizard's typed `data` snapshot, used by
+      # the review step's auto-summary (§2.5). Reuses the Plutonium display
+      # pipeline (`Display::Base` + its inferred-type builder + `field(...).wrapped`)
+      # so each field's label and value formatting match the rest of the app,
+      # rather than re-implementing value rendering.
+      class SummaryDisplay < Plutonium::UI::Display::Base
+        # @param object [Object] the wizard `data` snapshot.
+        # @param fields [Array<Symbol>] scalar field names to summarize.
+        # @param inputs [Hash] the step's input config ({name => {options:}}), so a
+        #   field's declared `as:` informs the display component (e.g. a `:text`
+        #   input renders via the markdown/text display tag).
+        def initialize(object, fields:, inputs: {}, **options)
+          options[:key] = :wizard
+          @summary_fields = fields
+          @summary_inputs = inputs
+          super(object, **options)
+        end
+
+        def display_template
+          dl(class: "grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-3") do
+            @summary_fields.each { |name| render_summary_field(name) }
+          end
+        end
+
+        private
+
+        def render_summary_field(name)
+          input_options = @summary_inputs[name]&.dig(:options) || {}
+          field_options = input_options[:label] ? {label: input_options[:label]} : {}
+
+          # A currency input stages a plain decimal; the data snapshot carries no
+          # has_cents reflection, so inference would render it as a bare number.
+          # Force the currency display and thread the declared `unit:` so the
+          # recap reads "$1,234.56", matching the input's prefix.
+          if input_options[:as]&.to_sym == :currency
+            return render field(name, **field_options).wrapped { |f|
+              render f.send(:create_component, Plutonium::UI::Display::Components::Currency, :currency, unit: input_options[:unit])
+            }
+          end
+
+          # A choice input (select/radio_buttons) stages the raw value; its
+          # value -> label map lives only in `choices:`. Resolve it and render the
+          # label as a string, rather than inferring a plain-string tag off the
+          # raw value (which would show "female" instead of "Female").
+          if input_options[:choices]
+            label = resolve_choice_label(name, input_options)
+            return render field(name, value: label, **field_options).wrapped { |f| render f.string_tag }
+          end
+
+          render field(name, **field_options).wrapped do |f|
+            render instance_exec(f, &summary_tag_block(name))
+          end
+        end
+
+        # Map the raw value(s) to their choice label(s) using the SAME mapper the
+        # form's select uses, so summary labels always match the form. Falls back
+        # to the raw value for anything not in `choices:`; nil for an empty field
+        # (so the display renders its placeholder).
+        def resolve_choice_label(name, input_options)
+          mapper = Phlexi::Form::SimpleChoicesMapper.new(
+            input_options[:choices],
+            label_method: input_options[:label_method],
+            value_method: input_options[:value_method]
+          )
+          raw = Phlexi::Field::Support::Value.from(object, name)
+          Array(raw).map { |value| mapper[value] || value }.join(", ").presence
+        end
+
+        # Pick the display component the same way a resource display does — infer it
+        # from the value's TYPE (date, boolean, number, currency, …) instead of
+        # stringifying everything. The one override: an attachment field stages a
+        # string TOKEN, so inference can't tell it's an attachment — force it (the
+        # data object is decorated upstream to resolve the token to an attachment).
+        def summary_tag_block(name)
+          ->(f) {
+            tag = Plutonium::Wizard::Attachments.field?(@summary_inputs[name]) ? :attachment : f.inferred_field_component
+            if tag.is_a?(Class)
+              f.send(:create_component, tag, tag.name.demodulize.underscore.sub(/component$/, "").to_sym)
+            else
+              f.send(:"#{tag}_tag")
+            end
+          }
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.60.5"
+  VERSION = "0.62.0"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/lib/plutonium/wizard/attachment_data.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Decorates a step's typed `data` so ATTACHMENT fields READ as resolved,
+    # displayable attachments ({Attachments::Resolved}) rather than the raw staged
+    # token string — so the step form's `Uppy` preview rehydrates on Back/resume
+    # (it calls `.url`/`.signed_id`/`.filename`, which a bare token string can't
+    # answer). Every other field delegates unchanged.
+    #
+    # Read-only: the SUBMITTED value is still the token the hidden preview field
+    # re-posts (`Resolved#signed_id` == the original token), so staging is
+    # unaffected.
+    class AttachmentData < SimpleDelegator
+      # Wrap only when the step actually has an attachment field — otherwise return
+      # the data untouched, so the overwhelming majority of steps are unaffected.
+      def self.wrap(data, step)
+        attachment_fields = step.inputs.select { |_name, config| Attachments.field?(config) }
+        attachment_fields.any? ? new(data, attachment_fields) : data
+      end
+
+      def initialize(data, attachment_fields)
+        super(data)
+        attachment_fields.each do |name, config|
+          multiple = config.dig(:options, :multiple)
+          define_singleton_method(name) do
+            resolved = Attachments.resolve(__getobj__.public_send(name))
+            multiple ? resolved : resolved.first
+          end
+        end
+      end
+
+      # Masquerade as the wrapped object's class so phlexi still infers field
+      # affordances (required marker, maxlength, …) from its validators — it reads
+      # `object.class.validators_on(...)`, and a `SimpleDelegator` would otherwise
+      # report its own class and drop every marker on the step.
+      def class
+        __getobj__.class
+      end
+    end
+  end
+end