hecks 0.2.0 → 0.3.0

data/lib/hecks/forms/app.rb

@@ -0,0 +1,300 @@
+require "json"
+require "rack"
+require_relative "page"
+require_relative "field_shape"
+require_relative "index_renderer"
+require_relative "record_renderer"
+require_relative "command_form_renderer"
+require_relative "query_form_renderer"
+require_relative "params"
+require_relative "../facade/command_request"
+require_relative "../facade/json_door"
+
+module Hecks
+  module Forms
+    # The content-negotiated router: `GET /Banking/Account/Overdrawn.html`
+    # renders the query view built in this directory; the identical path
+    # with no extension (or `.json`) dispatches the SAME ask through
+    # `Runtime::Dispatcher#query` and answers with its raw result — one
+    # route, two representations, exactly the "change the file format on
+    # the route" mechanism this was built around
+    # (docs/command-form-and-query-form-bluebook.md).
+    #
+    # A plain Rack app (`#call(env)`) — no Sinatra, no Rails. `rack` itself
+    # is a LAZY dependency the same way `pg`/`oauth2`/`aws-sdk-lambda` are
+    # for their own adapters (see the Gemfile's own comment) : a project
+    # that never boots this file never needs it installed.
+    class App
+      def self.for(registry:, app_name:)
+        config = Forms.config(app_name) ||
+                 raise(ArgumentError, "no app #{app_name.inspect} configured — " \
+                                      "call Hecks::Forms.configure(#{app_name.inspect}) { expose \"...\" } first")
+        new(registry: registry, exposed: config.exposes)
+      end
+
+      def initialize(registry:, exposed:, dispatcher: nil)
+        @registry   = registry
+        @exposed    = exposed
+        @dispatcher = dispatcher || Runtime::Dispatcher.new(registry)
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        route(request)
+      rescue RouteNotFound => e
+        respond(404, "text/plain", e.message)
+      end
+
+      class RouteNotFound < StandardError; end
+
+      private
+
+      def route(request)
+        segments = request.path_info.split("/").reject(&:empty?)
+        return home(request) if segments.empty?
+
+        domain = segments[0]
+        refuse_unexposed(domain)
+        chapter = @registry.bluebook(domain) || raise(RouteNotFound, "no domain #{domain.inspect} loaded")
+
+        return aggregate_route(request, chapter, *split_format(segments[1])) if segments.size == 2
+
+        return verb_or_record_route(request, chapter, segments[1], *split_format(segments[2])) if segments.size == 3
+
+        if segments.size == 4
+          aggregate = chapter.aggregate(segments[1])
+          entity = aggregate&.entities&.find { |candidate| candidate.hecks_name == segments[2] }
+          entity_command = entity&.command(split_format(segments[3]).first)
+          if entity_command
+            raise RouteNotFound,
+                  "entity command routes are not supported by Forms; use a command door with " \
+                  "to.aggregate and to.entity"
+          end
+        end
+
+        respond(404, "text/plain", "no route for #{request.path_info}")
+      end
+
+      def refuse_unexposed(domain)
+        return if @exposed.include?(domain)
+
+        raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared chapters: #{@exposed.join(', ')}"
+      end
+
+      def split_format(segment)
+        name, format = segment.to_s.split(".", 2)
+        [name, format || "json"]
+      end
+
+      # ---- home -------------------------------------------------------
+
+      def home(request)
+        format = request.params["format"] || "html"
+        chapters = @exposed.to_h { |name| [name, @registry.bluebook(name)] }.compact
+        return json(200, chapters.transform_values { |c| { aggregates: c.aggregates.map(&:hecks_name) } }) if format != "html"
+
+        html("Exposed domains", IndexRenderer.render(chapters))
+      end
+
+      # ---- /:domain/:aggregate.:format ---------------------------------
+
+      def aggregate_route(request, chapter, aggregate_name, format)
+        aggregate = find_aggregate(chapter, aggregate_name)
+        return respond(405, "text/plain", "GET only") unless request.get?
+
+        if format == "html"
+          html("#{chapter.name}::#{aggregate.hecks_name}", RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
+               breadcrumbs: [[chapter.name, "/"], [aggregate.hecks_name, nil]])
+        else
+          instances = @registry.repository(chapter.name, aggregate).all
+          # id LAST — see Instance#to_h's own comment: an aggregate free
+          # to declare its own attribute literally named `id` has that
+          # attribute's own wrapped value sitting in `i.state[:id]`
+          # already, which used to silently clobber the correct bare
+          # identity when merged first.
+          json(200, instances.map { |i| i.state.merge(id: i.id) })
+        end
+      end
+
+      # ---- /:domain/:aggregate/:verb_or_id.:format ----------------------
+
+      def verb_or_record_route(request, chapter, aggregate_name, verb_or_id, format)
+        aggregate = find_aggregate(chapter, aggregate_name)
+        domain = chapter.name
+
+        if (command = aggregate.command(verb_or_id))
+          return command_route(request, domain, aggregate, command, format)
+        end
+
+        if (query = aggregate.query(verb_or_id))
+          return query_route(request, domain, aggregate, query, format)
+        end
+
+        record_route(request, domain, aggregate, verb_or_id, format)
+      end
+
+      def command_route(request, domain, aggregate, command, format)
+        action = "/#{domain}/#{aggregate.hecks_name}/#{command.hecks_name}.html"
+        return command_json(request, domain, aggregate, command) if format != "html"
+        if request.get?
+          return command_form(domain, aggregate, command, action,
+                              prefill: receiver_compatibility(request.GET, command))
+        end
+        return respond(405, "text/plain", "GET or POST only") unless request.post?
+
+        submit_command(request, domain, aggregate, command, action)
+      end
+
+      def command_form(domain, aggregate, command, action, status: 200, values: nil, error: nil, prefill: {})
+        html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}",
+             CommandFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, command: command,
+                                        action: action, values: values, error: error, prefill: prefill),
+             breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
+                           [command.hecks_name, nil]],
+             status:      status)
+      end
+
+      def submit_command(request, domain, aggregate, command, action)
+        raw, envelope = submitted_command(request, aggregate, command)
+        result = @dispatcher.dispatch("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", **envelope)
+        redirect("/#{domain}/#{aggregate.hecks_name}/#{result.id}.html")
+      rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
+        status = e.is_a?(Runtime::NotFound) ? 404 : 422
+        command_form(domain, aggregate, command, action, status: status, values: raw, error: e)
+      end
+
+      def command_json(request, domain, aggregate, command)
+        return json(200, command.to_h) if request.get? && request.GET.reject { |k, _| k == "format" }.empty?
+        return respond(405, "text/plain", "GET or POST only") unless request.post?
+
+        _, envelope = submitted_command(request, aggregate, command)
+        result = @dispatcher.dispatch("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", **envelope)
+        # id LAST — same reasoning as the other JSON-serializing call
+        # sites in this file (see aggregate_route's own comment).
+        json(201, result.state.merge(id: result.id))
+      rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
+        status = e.is_a?(Runtime::NotFound) ? 404 : 422
+        json(status, { error: e.class.name.split("::").last, message: e.message })
+      end
+
+      def query_route(request, domain, aggregate, query, format)
+        return respond(405, "text/plain", "GET only") unless request.get?
+
+        params = request.GET
+        asked = params.reject { |k, _| k == "format" }
+        return query_json(domain, aggregate, query, asked) if format != "html"
+
+        query_html(domain, aggregate, query, asked)
+      end
+
+      def query_html(domain, aggregate, query, asked)
+        action = "/#{domain}/#{aggregate.hecks_name}/#{query.hecks_name}.html"
+        fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
+        results, error = asked.empty? ? [nil, nil] : run_query(domain, aggregate, query, fields, asked)
+        html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}",
+             QueryFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, query: query,
+                                      action: action, params: asked, results: results, error: error),
+             breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
+                           [query.hecks_name, nil]],
+             status:      error ? 422 : 200)
+      end
+
+      def query_json(domain, aggregate, query, asked)
+        return json(200, query.to_h) if asked.empty?
+
+        fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
+        results, error = run_query(domain, aggregate, query, fields, asked)
+        return json(422, { error: error.class.name.split("::").last, message: error.message }) if error
+
+        # id LAST — same reasoning as the other JSON-serializing call
+        # sites in this file (see aggregate_route's own comment).
+        json(200, results.map { |i| i.state.merge(id: i.id) })
+      end
+
+      # `Dispatcher#query` answers an array of plain hashes
+      # (`{id:}.merge(state)`, flattened by `QueryInterpreter#call` on
+      # every path it can take — native pushdown or the in-memory
+      # fallback alike), not `Runtime::Instance`. Wrapped into `Record`
+      # here, once, so every renderer downstream reads one shape whether
+      # its records came from a query or straight off a repository.
+      def run_query(domain, aggregate, query, fields, asked)
+        args = Params.extract(fields, asked)
+        rows = @dispatcher.query("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}", **args)
+        [rows.map { |row| Record.new(row[:id], row.reject { |k, _| k == :id }) }, nil]
+      rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError => e
+        [nil, e]
+      end
+
+      def record_route(request, domain, aggregate, id, format)
+        return respond(405, "text/plain", "GET only") unless request.get?
+
+        instance = @registry.repository(domain, aggregate).find(id)
+        return not_found(aggregate, id, format) unless instance
+        # id LAST — same reasoning as the other JSON-serializing call
+        # sites in this file (see aggregate_route's own comment).
+        return json(200, instance.state.merge(id: instance.id)) if format != "html"
+
+        html("#{domain}::#{aggregate.hecks_name} #{id}", RecordRenderer.show(registry: @registry, domain: domain, aggregate: aggregate, id: id),
+             breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"], [id, nil]])
+      end
+
+      def not_found(aggregate, id, format)
+        return json(404, { error: "NotFound", message: "no #{aggregate.hecks_name} #{id}" }) if format != "html"
+
+        respond(404, "text/html; charset=utf-8",
+                Page.render(title: "not found", body: "<h1>Not found</h1><p>No #{Escape.html(aggregate.hecks_name)} #{Escape.html(id)}.</p>"))
+      end
+
+      def find_aggregate(chapter, name)
+        chapter.aggregate(name) || raise(RouteNotFound, "#{chapter.name} has no aggregate #{name.inspect}")
+      end
+
+      def command_envelope(command, args)
+        Facade::CommandRequest.normalize(args, receiver: command_receiver(command), legacy_receiver: :id)
+      end
+
+      def command_receiver(command) = command.creates? ? nil : :aggregate
+
+      def submitted_command(request, aggregate, command)
+        if request.media_type == "application/json"
+          raw = Facade::JsonDoor.parse(request.body.read)
+          envelope = Facade::JsonDoor.command_request(raw, receiver:        command_receiver(command),
+                                                           legacy_receiver: :id)
+          return [raw, envelope]
+        end
+
+        raw = receiver_compatibility(request.POST, command)
+        fields = CommandFormRenderer.fields_for(aggregate, command)
+        args = Params.extract(fields, raw)
+        [raw, command_envelope(command, args)]
+      end
+
+      # Existing integrations may still submit id. It remains an accepted
+      # edge spelling, but new forms expose only the receiver name to.
+      def receiver_compatibility(raw, command)
+        return raw if command.creates?
+        return raw unless raw.key?("id") && !raw.key?("to")
+
+        raw.merge("to" => raw["id"])
+      end
+
+      # ---- rendering ----------------------------------------------------
+
+      def html(title, body, breadcrumbs: [], status: 200)
+        respond(status, "text/html; charset=utf-8", Page.render(title: title, body: body, breadcrumbs: breadcrumbs))
+      end
+
+      def json(status, payload)
+        respond(status, "application/json", JSON.pretty_generate(payload))
+      end
+
+      def redirect(location)
+        [302, { "location" => location }, []]
+      end
+
+      def respond(status, content_type, body)
+        [status, { "content-type" => content_type }, [body]]
+      end
+    end
+  end
+end

data/lib/hecks/forms/command_form_renderer.rb

@@ -0,0 +1,113 @@
+require "json"
+require_relative "html"
+require_relative "field_shape"
+require_relative "field_renderer"
+require_relative "reference_options"
+require_relative "params"
+
+module Hecks
+  module Forms
+    # Command -> the page body for its HTML form — the working half of
+    # what `command_form.bluebook` names (see docs/command-form-and-query-
+    # form-bluebook.md). Every command in every loaded, exposed bluebook
+    # renders through here — nothing here is per-command code; see that
+    # doc for the 1:1 rule this deliberately holds to for now.
+    module CommandFormRenderer
+      # `registry` is only used to populate a `:reference` field's
+      # `<select>` with real records (including the identity picker itself,
+      # for a non-creating command — see `identity_field` below). `values`/
+      # `error` carry a sticky re-render after a refused submission; leave
+      # both nil/`{}` for a fresh form. `prefill` carries values a caller
+      # arrived WITH (typically `?to=...` off a record's own detail page) —
+      # kept separate from `values` because a prefill is not an error retry
+      # and should not be treated as one by a future reader of this code.
+      # The SAME field list a POST handler needs to cast raw params against
+      # (params.rb's `Params.extract`) — one derivation, so a page never
+      # renders an input the submit handler doesn't also expect.
+      def self.fields_for(aggregate, command)
+        addressing = command.creates? ? [] : [identity_field(aggregate)]
+        addressing + command.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
+      end
+
+      def self.render(registry:, domain:, aggregate:, command:, action:, values: nil, error: nil, prefill: {})
+        all_fields = fields_for(aggregate, command)
+        reference_options = ReferenceOptions.collect(registry, domain, all_fields)
+        shown_values = values || prefill
+
+        <<~HTML
+          #{header(domain, aggregate, command)}
+          #{error_banner(error)}
+          <form method="post" action="#{Escape.attr(action)}" novalidate>
+            #{all_fields.map { |f| FieldRenderer.render(f, values: shown_values, errors: field_errors(error), reference_options: reference_options) }.join}
+            <div class="actions">
+              <button type="submit">#{Escape.html(command.hecks_name)}</button>
+              <a class="button secondary" href="#{Escape.attr("/#{domain}/#{aggregate.hecks_name}")}">Cancel</a>
+            </div>
+          </form>
+          #{inspect_panel(domain, aggregate, command, action, all_fields)}
+        HTML
+      end
+
+      def self.identity_field(aggregate)
+        Field.new(path: "to", label: "#{aggregate.hecks_name} (#{aggregate.identity_paths.join(', ')})",
+                  kind: :reference, html_type: "text", target_aggregate: aggregate,
+                  help: "The record this command acts on.")
+      end
+
+      def self.header(domain, aggregate, command)
+        <<~HTML
+          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}")}</h1>
+          #{command.role ? %(<span class="badge role">role: #{Escape.html(command.role)}</span>) : ''}
+          #{command.creates? ? %(<span class="badge">creates a new #{Escape.html(aggregate.hecks_name)}</span>) : ''}
+          #{command.goal ? %(<p class="goal">#{Escape.html(command.goal)}</p>) : ''}
+          #{givens_callout(command)}
+        HTML
+      end
+
+      def self.givens_callout(command)
+        return "" if command.givens.empty?
+
+        items = command.givens.map { |given| "<li>#{Escape.html(given.description)}</li>" }
+        %(<div class="callout"><strong>Preconditions</strong> — refused if any fail:<ul>#{items.join}</ul></div>)
+      end
+
+      def self.error_banner(error)
+        return "" unless error
+
+        <<~HTML
+          <div class="error-banner" role="alert">
+            <p><strong>#{Escape.html(error.class.name.split('::').last)}</strong> — #{Escape.html(error.message)}</p>
+          </div>
+        HTML
+      end
+
+      # No structured field attribution exists on a domain refusal today
+      # (it is a typed exception with a rendered message — see
+      # docs/command-form-and-query-form-bluebook.md's note on
+      # `RefusalWording`), so this returns empty rather than guessing which
+      # field a message meant; the banner above carries the real text
+      # instead of a misattributed hint.
+      def self.field_errors(_error) = {}
+
+      def self.inspect_panel(domain, aggregate, command, action, fields)
+        verb = "#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}"
+        paths = Params.paths(fields)
+        curl = <<~SH.strip
+          curl -X POST '#{action}' \\
+            #{paths.map { |path| "-d '#{path}=...'" }.join(" \\\n  ")}
+        SH
+        <<~HTML
+          <details class="inspect">
+            <summary>Inspect — #{Escape.html(verb)}</summary>
+            <p>Emits: #{command.emits.empty? ? '<em>nothing declared</em>' : command.emits.map { |e| "<code>#{Escape.html(e)}</code>" }.join(', ')}</p>
+            <p>Equivalent request (as <code>curl</code>) — every field is <code>#{Escape.html('name.path')}</code>-encoded, form or JSON alike:</p>
+            <div class="link-row"><code id="curl-snippet">#{Escape.html(curl)}</code><button type="button" class="copy" data-copy="#curl-snippet">copy</button></div>
+            <p>Fields this command takes: #{paths.map { |p| "<code>#{Escape.html(p)}</code>" }.join(', ')}</p>
+            <p>The command's own declaration, as the runtime holds it:</p>
+            <pre>#{Escape.html(JSON.pretty_generate(command.to_h))}</pre>
+          </details>
+        HTML
+      end
+    end
+  end
+end

data/lib/hecks/forms/examples/banking_console.bluebook

@@ -0,0 +1,3 @@
+Hecks::Forms.configure "BankingConsole" do
+  expose "Banking"
+end

data/lib/hecks/forms/field_renderer.rb

@@ -0,0 +1,170 @@
+require_relative "html"
+require_relative "field_shape"
+require_relative "../naming"
+
+module Hecks
+  module Forms
+    # A Field (field_shape.rb) -> the `<div class="field">...</div>` or
+    # `<fieldset>...</fieldset>` markup for it. One renderer, called
+    # recursively for a group's children, shared by CommandFormRenderer
+    # (POST) and QueryFormRenderer (GET) — the same attribute shape asks
+    # for the same input either way; only the surrounding `<form>`'s
+    # method differs.
+    module FieldRenderer
+      # `values` is the nested hash a sticky re-render (a rejected command,
+      # a submitted query) carries back — read with the SAME dotted path a
+      # Field already carries, via `dig`. `reference_options` maps a
+      # `:reference` field's own path to `[[id, label], ...]`, built by the
+      # caller (it needs a repository; this module stays pure markup).
+      def self.render(field, values: {}, errors: nil, reference_options: {})
+        case field.kind
+        when :group  then group(field, values, errors, reference_options, tag: "fieldset")
+        when :money  then group(field, values, errors, reference_options, tag: "fieldset", css: "money")
+        when :list   then list(field, values, errors)
+        else              leaf(field, values, errors, reference_options)
+        end
+      end
+
+      def self.group(field, values, errors, reference_options, tag:, css: nil)
+        inner = field.children.map { |child| render(child, values: values, errors: errors, reference_options: reference_options) }
+        <<~HTML
+          <#{tag}#{css ? %( class="#{css}") : ""}>
+            <legend>#{Escape.html(field.label)}#{required_mark(field)}</legend>
+            #{inner.join("\n")}
+          </#{tag}>
+        HTML
+      end
+
+      def self.list(field, values, _errors)
+        item = field.children.first
+        current = Array(dig(values, field.path)).join("\n")
+        <<~HTML
+          <div class="field">
+            <label for="#{dom_id(field.path)}">#{Escape.html(field.label)}#{required_mark(field)}</label>
+            <textarea id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}"
+              #{aria(field)} placeholder="one #{Escape.attr(item.label.downcase)} per line">#{Escape.html(current)}</textarea>
+            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{item.leaf? ? '' : ' — each line is one JSON object'}.</span>
+          </div>
+        HTML
+      end
+
+      def self.leaf(field, values, errors, reference_options)
+        value = dig(values, field.path)
+        error = errors && errors[field.path]
+        body = case field.kind
+               when :boolean  then checkbox(field, value)
+               when :radio    then radio_group(field, value)
+               when :select   then select(field, value)
+               when :textarea then textarea(field, value)
+               when :reference then reference_select(field, value, reference_options[field.path])
+               else input(field, value)
+               end
+        wrap(field, body, error)
+      end
+
+      def self.wrap(field, body, error)
+        <<~HTML
+          <div class="field#{error ? ' has-error' : ''}">
+            #{field.kind == :boolean ? '' : %(<label for="#{dom_id(field.path)}">#{Escape.html(field.label)}#{required_mark(field)}</label>)}
+            #{body}
+            #{field.help ? %(<span class="help" id="#{dom_id(field.path)}-help">#{Escape.html(field.help)}</span>) : ''}
+            #{error ? %(<span class="help" role="alert">#{Escape.html(error)}</span>) : ''}
+          </div>
+        HTML
+      end
+
+      def self.input(field, value)
+        money = field.kind == :number && field.help.to_s.include?("cents")
+        tag = Tag.void("input", id: dom_id(field.path), name: field.path, type: field.html_type,
+                        value: value || field.default, step: field.step, pattern: leaf_pattern(field),
+                        placeholder: field.default, **aria_attrs(field),
+                        **(money ? { data_money_cents: money_preview_target(field) } : {}))
+        return tag unless money
+
+        %(#{tag} <span id="#{dom_id(field.path)}-preview" class="mono help" aria-live="polite"></span>)
+      end
+
+      def self.textarea(field, value)
+        %(<textarea id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{Escape.html(value)}</textarea>)
+      end
+
+      def self.checkbox(field, value)
+        checked = value.nil? ? field.default == true : [true, "true", "on", "1"].include?(value)
+        <<~HTML
+          <div class="checkbox-row">
+            <input type="hidden" name="#{Escape.attr(field.path)}" value="0">
+            #{Tag.void('input', id: dom_id(field.path), name: field.path, type: 'checkbox', value: '1', checked: checked)}
+            <label for="#{dom_id(field.path)}">#{Escape.html(field.label)}</label>
+          </div>
+        HTML
+      end
+
+      def self.radio_group(field, value)
+        selected = value || field.default
+        options = field.options.map do |option_value, option_label|
+          checked = option_value.to_s == selected.to_s
+          id = "#{dom_id(field.path)}-#{Naming.snake(option_value)}"
+          <<~HTML
+            <label>#{Tag.void('input', id: id, type: 'radio', name: field.path, value: option_value, checked: checked)} #{Escape.html(option_label)}</label>
+          HTML
+        end
+        %(<div class="radio-group" role="radiogroup">#{options.join}</div>)
+      end
+
+      def self.select(field, value)
+        selected = value || field.default
+        options = field.options.map do |option_value, option_label|
+          %(<option value="#{Escape.attr(option_value)}"#{option_value.to_s == selected.to_s ? ' selected' : ''}>#{Escape.html(option_label)}</option>)
+        end
+        blank = field.optional? ? %(<option value="">—</option>) : ""
+        %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{options.join}</select>)
+      end
+
+      def self.reference_select(field, value, options)
+        return input(field.tap { |f| f.html_type = "text" }, value) unless options && !options.empty?
+
+        rendered = options.map do |id, label|
+          %(<option value="#{Escape.attr(id)}"#{id.to_s == value.to_s ? ' selected' : ''}>#{Escape.html(label)}</option>)
+        end
+        blank = field.optional? ? %(<option value="">—</option>) : %(<option value="" disabled#{value ? '' : ' selected'}>choose one…</option>)
+        %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{rendered.join}</select>)
+      end
+
+      def self.required_mark(field) = field.required? ? %(<span class="required-mark" title="required">*</span>) : ""
+      def self.dom_id(path) = "f-#{path.to_s.tr('.', '-')}"
+      def self.leaf_pattern(field) = field.kind == :reference ? nil : field.pattern
+      def self.money_preview_target(field) = "##{dom_id(field.path)}-preview"
+
+      def self.aria(field)
+        Tag.attrs(required: field.required?, aria_describedby: field.help ? "#{dom_id(field.path)}-help" : nil)
+      end
+
+      def self.aria_attrs(field)
+        { required: field.required?, aria_describedby: field.help ? "#{dom_id(field.path)}-help" : nil }
+      end
+
+      # `values` is a nested hash; `path` a dotted string using the SAME
+      # segment spelling the hash keys are built from (`leaf_key` in
+      # params.rb) — symbols one level down from a group, strings at the
+      # flat top when a sticky POST re-render hands raw params back untouched.
+      def self.dig(values, path)
+        return nil unless values.is_a?(Hash)
+
+        # A sticky re-render after a refused submission hands back the RAW
+        # flat params (`{"amount.cents"=>"1050"}` — the same shape the form
+        # posted, string values and all, dotted key intact) ; a prefill from
+        # an existing record's own state hands back a NESTED hash instead
+        # (`{amount: {cents: 1050}}`). Flat wins when both would answer,
+        # since only the raw form is ever what the caller actually typed.
+        flat = values[path.to_s] || values[path.to_sym]
+        return flat unless flat.nil?
+
+        path.to_s.split(".").reduce(values) do |acc, segment|
+          break nil unless acc.is_a?(Hash)
+
+          acc[segment.to_sym] || acc[segment]
+        end
+      end
+    end
+  end
+end