hecks 0.2.0 → 0.3.0

data/lib/hecks/forms/field_shape.rb

@@ -0,0 +1,232 @@
+require_relative "../bluebook/attribute"
+require_relative "value_object_shape"
+
+module Hecks
+  module Forms
+    # One resolved field, ready for a renderer to turn into markup. A LEAF
+    # scalar carries `kind`/`options`/etc; a `:group` or `:list` carries
+    # `children` instead and nothing else on itself.
+    #
+    # `path` is the DOTTED field path this attribute is reached at —
+    # `"email.address"`, `"amount.cents"` — the same convention the language
+    # already uses for a query's own cross-object `where` clauses
+    # (`where(:"customer.status" => ...)`), not a fresh one invented here. A
+    # command receives its arguments as nested hashes
+    # (`email: {address: "..."}`), so `Params.unflatten` (params.rb) walks
+    # this same dotted spelling back apart on submit — one convention, two
+    # directions.
+    Field = Struct.new(
+      :path, :label, :kind, :html_type, :options, :children, :default, :optional,
+      :pattern, :step, :help, :target_aggregate, keyword_init: true
+    ) do
+      def leaf? = kind != :group && kind != :list
+      def optional? = optional
+      def required? = !optional
+    end
+
+    module Humanize
+      # "given" -> "Given", "daily_limit" -> "Daily limit", "end_to_end" ->
+      # "End to end" — the label a plain reader wants, not the wire spelling.
+      def self.label(text)
+        # Split on "." FIRST, alone, to take only the last path segment —
+        # "daily_limit" is one segment (the underscore is a word break
+        # inside it, not a path hop) and must keep both its words; only a
+        # genuinely dotted path ("amount.cents") drops everything before
+        # the last ".".
+        segment = text.to_s.split(".").last.to_s
+        words = segment.split("_")
+        return segment if words.empty?
+
+        ([words.first.capitalize] + words.drop(1)).join(" ")
+      end
+
+      # The full dotted path, each segment humanized and joined with
+      # " → " for a fieldset legend spanning more than one hop
+      # ("Amount → Cents") — a group's own legend, not a leaf's label.
+      def self.breadcrumb(path)
+        path.to_s.split(".").map { |part| label(part) }.join(" → ")
+      end
+    end
+
+    # Attribute -> Field. The one mapping every renderer in this
+    # directory reads instead of re-deriving its own — see
+    # docs/command-form-and-query-form-bluebook.md's survey of the gap this closes (the
+    # prior generic-console attempt fell back to `type="text"` for anything
+    # that wasn't a number or an enum; a `pattern` naming an email shape, or a
+    # closed set another aggregate declares, went unread).
+    module FieldShape
+      PRIMITIVES = Bluebook::Attribute::PRIMITIVES
+
+      # `aggregate:` is the Aggregate that OWNS this attribute (a
+      # command's, a query's, or — recursively — a value object's) —
+      # needed to resolve `reference_to`, `admits:`, and a same-chapter
+      # value object by name. `path:` defaults to the attribute's own name;
+      # a caller resolving a nested value object's attribute passes the
+      # dotted path so far.
+      def self.resolve(attribute, aggregate:, path: attribute.name.to_s)
+        return list_field(attribute, aggregate, path) if attribute.list?
+
+        common = { path: path, label: Humanize.label(path), default: attribute.default,
+                   optional: attribute.optional?, pattern: attribute.pattern }
+
+        return reference_field(attribute, common) if attribute.reference?
+        return admitted_field(attribute, aggregate, common) if attribute.admits
+        return value_object_field(attribute, aggregate, common) unless PRIMITIVES.include?(attribute.type)
+
+        primitive_field(attribute, common)
+      end
+
+      def self.list_field(attribute, aggregate, path)
+        # The scalar shape one element of this list would take, so a
+        # renderer can say what belongs on each line without a second
+        # mapping table. `list:` is the only thing that differs.
+        scalar = Bluebook::Attribute.new(
+          name: attribute.name, type: attribute.type, list: false,
+          default: nil, optional: true, pattern: attribute.pattern, admits: attribute.admits
+        )
+        Field.new(path: path, label: Humanize.label(path), kind: :list, optional: attribute.optional?,
+                  children: [resolve(scalar, aggregate: aggregate, path: path)])
+      end
+
+      def self.reference_field(attribute, common)
+        target = attribute.type.resolve
+        Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target,
+                            help: target ? "References an existing #{target.hecks_name} by id." :
+                                  "References an aggregate in another domain — enter its id.")
+      end
+
+      # `admits:` names a closed set declared ELSEWHERE (`"Account::
+      # LedgerDirection"`) that the value must belong to — see
+      # Runtime::Value::Admission#admitted_members, which this mirrors
+      # exactly (same split, same chapter walk, same discriminant rule) so
+      # a rendered `<select>` never offers a member the runtime would then
+      # refuse.
+      def self.admitted_field(attribute, aggregate, common)
+        set_aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
+        chapter = aggregate.hecks_owner
+        set = set_name && chapter&.aggregate(set_aggregate_name)&.value_object(set_name)
+        return primitive_field(attribute, common) unless set # undeclared — refuse-at-dispatch stays the backstop
+
+        options = select_or_radio(common, closed_set_options(set))
+        # The attribute's OWN type still has to be built the shape coercion
+        # expects (`Value::Coercion#fields_for` refuses anything that
+        # isn't a Hash or a Value for a value-object-typed attribute) — a
+        # plain String attribute stays a bare scalar, but a value object
+        # like `MovementDirection { value }` still needs the ".value" hop
+        # even though the SET it's checked against (`admits:`) is declared
+        # somewhere else entirely. Same unwrap `value_object_field` does,
+        # kept separate because an admitted set changes the OPTIONS, not
+        # which field the hop lands on.
+        own_shape = own_value_object(attribute, aggregate)
+        inner = own_shape && ValueObjectShape.sole_attribute(own_shape)
+        return options unless inner
+
+        options.path = "#{common[:path]}.#{inner.name}"
+        options
+      end
+
+      def self.own_value_object(attribute, aggregate)
+        aggregate.value_object(attribute.type) || cross_aggregate_value_object(aggregate, attribute.type)
+      end
+
+      def self.value_object_field(attribute, aggregate, common)
+        shape = own_value_object(attribute, aggregate)
+        return primitive_field(attribute, common) unless shape
+
+        return closed_set_field(shape, common) if shape.closed_set?
+        return money_field(shape, common) if ValueObjectShape.money?(shape)
+
+        # A single-attribute value object (EmailAddress{address}, CustomerNumber{value})
+        # is a NAME for a scalar, not a genuine group — unwrap it so the form
+        # asks for one thing ("Email address") instead of a one-item fieldset,
+        # and so the inner attribute's OWN pattern (the real email regex,
+        # declared on `address`, not on the outer `email` attribute) drives
+        # the input type. [[feedback_name_the_scalar_field]] says the same
+        # thing about Ruby call sites; a form asks the identical question.
+        if (inner = ValueObjectShape.sole_attribute(shape))
+          return resolve(inner, aggregate: aggregate, path: "#{common[:path]}.#{inner.name}")
+                 .tap { |field| field.optional = common[:optional] || field.optional }
+        end
+
+        group_field(shape, aggregate, common)
+      end
+
+      def self.cross_aggregate_value_object(aggregate, type_name)
+        aggregate.hecks_owner&.aggregates&.each do |sibling|
+          found = sibling.value_object(type_name)
+          return found if found
+        end
+        nil
+      end
+
+      def self.group_field(shape, aggregate, common)
+        children = shape.attributes.map { |inner| resolve(inner, aggregate: aggregate, path: "#{common[:path]}.#{inner.name}") }
+        Field.new(path: common[:path], label: common[:label], kind: :group, optional: common[:optional], children: children)
+      end
+
+      def self.money_field(shape, common)
+        cents = Field.new(path: "#{common[:path]}.cents", label: "Amount (cents)", kind: :number,
+                          html_type: "number", step: "1", optional: common[:optional],
+                          default: shape.attribute(:cents)&.default, help: "Whole cents — 1050 is $10.50.")
+        currency = Field.new(path: "#{common[:path]}.currency", label: "Currency", kind: :text, html_type: "text",
+                             optional: true, default: shape.attribute(:currency)&.default || "USD",
+                             help: "Three-letter code.")
+        Field.new(path: common[:path], label: common[:label], kind: :money, optional: common[:optional],
+                  children: [cents, currency])
+      end
+
+      def self.closed_set_options(value_object)
+        discriminant = value_object.attributes.first.name
+        value_object.members.map { |member| member[discriminant].to_s }
+      end
+
+      # A `one_of` shape (`AccountKind{name}`, `LedgerDirection{value}`) is
+      # ALWAYS single-attribute in this language — the discriminant IS the
+      # whole value object — so the field's own path always gains that one
+      # hop; nothing to branch on the way `admitted_field` has to (a set
+      # named by `admits:` may sit on a multi-field value object it doesn't
+      # itself define the members of).
+      def self.closed_set_field(shape, common)
+        discriminant = shape.attributes.first.name
+        select_or_radio(common.merge(path: "#{common[:path]}.#{discriminant}"), closed_set_options(shape))
+      end
+
+      def self.select_or_radio(common, options)
+        kind = options.size <= 4 ? :radio : :select
+        Field.new(**common, kind: kind, html_type: "text", options: options.map { |value| [value, value] })
+      end
+
+      def self.primitive_field(attribute, common)
+        case attribute.type.to_s
+        when "Integer" then Field.new(**common, kind: :number, html_type: "number", step: "1")
+        when "Float"   then Field.new(**common, kind: :number, html_type: "number", step: "any")
+        when "TrueClass", "FalseClass"
+          Field.new(**common, kind: :boolean, html_type: "checkbox")
+        else
+          text_field(attribute, common)
+        end
+      end
+
+      EMAIL_HINT = /email/i
+      URL_HINT   = /\b(url|uri|website|link)\b/i
+      TEL_HINT   = /phone|\btel(ephone)?\b/i
+      TEXTAREA_HINT = /\b(text|body|note|notes|description|message|comment)\b/i
+
+      def self.text_field(attribute, common)
+        name = attribute.name.to_s
+        pattern = attribute.pattern.to_s
+        html_type = if pattern.include?("@") || name.match?(EMAIL_HINT)
+                      "email"
+                    elsif pattern.match?(/https?/i) || name.match?(URL_HINT)
+                      "url"
+                    elsif name.match?(TEL_HINT)
+                      "tel"
+                    else
+                      "text"
+                    end
+        kind = html_type == "text" && name.match?(TEXTAREA_HINT) ? :textarea : :text
+        Field.new(**common, kind: kind, html_type: html_type)
+      end
+    end
+  end
+end

data/lib/hecks/forms/html.rb

@@ -0,0 +1,53 @@
+module Hecks
+  module Forms
+    # Hand-rolled, on purpose — the repo has no ERB anywhere and no template
+    # engine dependency (see docs/command-form-and-query-form-bluebook.md's survey). Every
+    # other generator in this codebase (bin/reference's markdown, the IR's own
+    # `to_h`) builds output as plain Ruby strings; this does the same for HTML,
+    # with exactly one job: nothing that reaches `Escape.html` ever becomes a
+    # tag. A feature developer's own domain data — a customer's name, an
+    # account number a support rep typed into a form and got wrong — flows
+    # through here on every render, so escaping is not optional decoration.
+    module Escape
+      # Order matters — `&` first, or every escape this method itself just
+      # wrote (`&`, `<`, ...) gets re-escaped a second time.
+      def self.html(value)
+        value.to_s
+             .gsub("&", "&")
+             .gsub("<", "&lt;")
+             .gsub(">", "&gt;")
+             .gsub('"', "&quot;")
+             .gsub("'", "&#39;")
+      end
+
+      # Safe inside a double-quoted HTML attribute specifically — `html`
+      # already covers this (it escapes `"`), kept as a named alias so a
+      # call site reads "this value fills an attribute" rather than repeating
+      # the same escaping and leaving the reader to check they match.
+      def self.attr(value) = html(value)
+    end
+
+    # A tiny attribute-hash -> string helper, shared by every renderer in
+    # this directory so `<input ...>` doesn't get hand-assembled five
+    # different ways with five different escaping bugs waiting in each.
+    # `true` renders as a bare boolean attribute (`required`, not
+    # `required="true"`); `nil`/`false` are dropped entirely.
+    module Tag
+      def self.attrs(pairs)
+        pairs.filter_map do |name, value|
+          next if value.nil? || value == false
+          next name.to_s.tr("_", "-") if value == true
+
+          %(#{name.to_s.tr("_", "-")}="#{Escape.attr(value)}")
+        end.join(" ")
+      end
+
+      def self.open(name, **pairs)
+        rendered = attrs(pairs)
+        rendered.empty? ? "<#{name}>" : "<#{name} #{rendered}>"
+      end
+
+      def self.void(name, **pairs) = open(name, **pairs) # self-closing tags read the same; HTML5 needs no slash
+    end
+  end
+end

data/lib/hecks/forms/index_renderer.rb

@@ -0,0 +1,35 @@
+require_relative "html"
+
+module Hecks
+  module Forms
+    # The home page: every exposed chapter, every aggregate on it — the
+    # entry point into what would otherwise be a URL you'd have to already
+    # know. `chapters` is `{domain_name => Bluebook}`, in `expose` order
+    # (see config.rb).
+    module IndexRenderer
+      def self.render(chapters)
+        sections = chapters.map { |name, chapter| chapter_section(name, chapter) }
+        <<~HTML
+          <h1>Exposed domains</h1>
+          #{sections.join}
+        HTML
+      end
+
+      def self.chapter_section(name, chapter)
+        items = chapter.aggregates.map do |aggregate|
+          counts = "#{aggregate.commands.size} command#{'s' unless aggregate.commands.size == 1}, " \
+                   "#{aggregate.queries.size} quer#{aggregate.queries.size == 1 ? 'y' : 'ies'}"
+          <<~HTML
+            <li><a href="/#{Escape.attr(name)}/#{Escape.attr(aggregate.hecks_name)}.html">
+              <span>#{Escape.html(aggregate.hecks_name)}</span><span class="kind">#{Escape.html(counts)}</span>
+            </a></li>
+          HTML
+        end
+        <<~HTML
+          <h2>#{Escape.html(name)}#{chapter.vision ? %( <span class="badge">#{Escape.html(chapter.vision)}</span>) : ''}</h2>
+          <ul class="verb-list">#{items.join}</ul>
+        HTML
+      end
+    end
+  end
+end

data/lib/hecks/forms/page.rb

@@ -0,0 +1,157 @@
+require_relative "html"
+
+module Hecks
+  module Forms
+    # The one HTML shell every page in this app renders inside — nav,
+    # typography, form/table/badge styles, all inline (no CDN, no build
+    # step: this ships inside the `hecks` gem, and a project that
+    # embeds it gets one dependency-free response per request). Themed via
+    # `prefers-color-scheme` alone; nothing here reads a cookie or a query
+    # param for it, so it is never wrong for the browser rendering it.
+    module Page
+      def self.render(title:, body:, breadcrumbs: [])
+        <<~HTML
+          <!doctype html>
+          <html lang="en">
+          <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>#{Escape.html(title)} · hecks forms</title>
+          <style>#{STYLE}</style>
+          </head>
+          <body>
+          <header class="site-header">
+            <a class="brand" href="/">hecks forms</a>
+            #{breadcrumbs_html(breadcrumbs)}
+          </header>
+          <main>
+          #{body}
+          </main>
+          <footer class="site-footer">
+            <p>Generated straight from the loaded bluebook IR — nothing here is hand-authored per page. See <code>docs/command-form-and-query-form-bluebook.md</code>.</p>
+          </footer>
+          <script>#{SCRIPT}</script>
+          </body>
+          </html>
+        HTML
+      end
+
+      def self.breadcrumbs_html(crumbs)
+        return "" if crumbs.empty?
+
+        items = crumbs.map do |label, href|
+          href ? %(<a href="#{Escape.attr(href)}">#{Escape.html(label)}</a>) : %(<span aria-current="page">#{Escape.html(label)}</span>)
+        end
+        %(<nav class="breadcrumbs" aria-label="Breadcrumb">#{items.join(' <span class="sep">/</span> ')}</nav>)
+      end
+
+      STYLE = <<~CSS
+        :root {
+          --bg: #fbfaf8; --surface: #ffffff; --border: #e2ddd3; --text: #24211c;
+          --muted: #6b6355; --accent: #8a5a2b; --accent-contrast: #fff8ef;
+          --danger-bg: #fdeceb; --danger-border: #e2a49c; --danger-text: #7a2419;
+          --focus: #2b6cb0; --code-bg: #f1ede4; --radius: 8px;
+          --mono: "SF Mono", "JetBrains Mono", ui-monospace, Menlo, Consolas, monospace;
+          --sans: -apple-system, "Segoe UI", Helvetica, Arial, sans-serif;
+        }
+        @media (prefers-color-scheme: dark) {
+          :root {
+            --bg: #17140f; --surface: #201c15; --border: #3a3327; --text: #ece6d9;
+            --muted: #a89d87; --accent: #d99a52; --accent-contrast: #241a0c;
+            --danger-bg: #341613; --danger-border: #7a352b; --danger-text: #f3a99c;
+            --focus: #6ab0ff; --code-bg: #241f17;
+          }
+        }
+        * { box-sizing: border-box; }
+        body { background: var(--bg); color: var(--text); font-family: var(--sans); margin: 0; line-height: 1.5; }
+        a { color: var(--accent); }
+        a:focus-visible, button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-visible {
+          outline: 2px solid var(--focus); outline-offset: 2px;
+        }
+        .site-header { display: flex; align-items: baseline; gap: 1rem; padding: .9rem 1.5rem;
+          border-bottom: 1px solid var(--border); background: var(--surface); flex-wrap: wrap; }
+        .brand { font-family: var(--mono); font-weight: 600; text-decoration: none; color: var(--text); }
+        .breadcrumbs { font-size: .9rem; color: var(--muted); }
+        .breadcrumbs .sep { padding: 0 .3rem; }
+        main { max-width: 46rem; margin: 0 auto; padding: 2rem 1.5rem 4rem; }
+        .site-footer { max-width: 46rem; margin: 0 auto; padding: 1rem 1.5rem 3rem; color: var(--muted); font-size: .82rem; }
+        h1 { font-size: 1.5rem; margin: 0 0 .25rem; }
+        h2 { font-size: 1.1rem; margin: 2rem 0 .6rem; }
+        .goal { color: var(--muted); margin: 0 0 1rem; }
+        .badge { display: inline-block; font-family: var(--mono); font-size: .72rem; padding: .15rem .5rem;
+          border-radius: 999px; border: 1px solid var(--border); color: var(--muted); margin: 0 .3rem .3rem 0; }
+        .badge.role { color: var(--accent); border-color: var(--accent); }
+        .callout { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius);
+          padding: .8rem 1rem; margin: 0 0 1.2rem; font-size: .92rem; }
+        .callout ul { margin: .3rem 0 0; padding-left: 1.2rem; }
+        .error-banner { background: var(--danger-bg); border: 1px solid var(--danger-border); color: var(--danger-text);
+          border-radius: var(--radius); padding: .8rem 1rem; margin: 0 0 1.2rem; }
+        .error-banner p { margin: 0; }
+        fieldset { border: 1px solid var(--border); border-radius: var(--radius); margin: 0 0 1.1rem; padding: .8rem 1rem 1rem; }
+        legend { font-size: .85rem; color: var(--muted); padding: 0 .4rem; }
+        .field { margin: 0 0 1.1rem; }
+        .field > label { display: block; font-weight: 600; font-size: .9rem; margin-bottom: .3rem; }
+        .field .required-mark { color: var(--accent); }
+        .field .help { display: block; color: var(--muted); font-size: .8rem; margin-top: .3rem; }
+        .field input[type=text], .field input[type=email], .field input[type=url], .field input[type=tel],
+        .field input[type=number], .field select, .field textarea {
+          width: 100%; padding: .5rem .6rem; border: 1px solid var(--border); border-radius: var(--radius);
+          background: var(--surface); color: var(--text); font: inherit;
+        }
+        .field textarea { min-height: 4.5rem; font-family: var(--mono); font-size: .85rem; }
+        .radio-group { display: flex; flex-wrap: wrap; gap: .3rem 1rem; }
+        .radio-group label { font-weight: 400; display: flex; align-items: center; gap: .35rem; }
+        .checkbox-row { display: flex; align-items: center; gap: .5rem; }
+        button, .button { font: inherit; border-radius: var(--radius); border: 1px solid var(--accent);
+          background: var(--accent); color: var(--accent-contrast); padding: .55rem 1.1rem; cursor: pointer; }
+        button.secondary, .button.secondary { background: transparent; color: var(--text); border-color: var(--border); }
+        button.copy { font-size: .75rem; padding: .2rem .5rem; }
+        table { width: 100%; border-collapse: collapse; font-size: .88rem; }
+        .table-scroll { overflow-x: auto; margin: 0 0 1.2rem; }
+        th, td { text-align: left; padding: .45rem .6rem; border-bottom: 1px solid var(--border); white-space: nowrap; }
+        thead th { color: var(--muted); font-weight: 600; position: sticky; top: 0; background: var(--bg); }
+        tbody tr:hover { background: var(--surface); }
+        code, pre, .mono { font-family: var(--mono); font-size: .82rem; }
+        pre { background: var(--code-bg); border-radius: var(--radius); padding: .8rem 1rem; overflow-x: auto; margin: 0; }
+        .link-row { display: flex; gap: .5rem; align-items: center; margin: 0 0 .8rem; }
+        .link-row code { flex: 1; overflow-x: auto; padding: .4rem .6rem; background: var(--code-bg); border-radius: var(--radius); }
+        .example-links { display: flex; flex-wrap: wrap; gap: .4rem; margin: 0 0 1rem; }
+        .example-links a { border: 1px solid var(--border); border-radius: 999px; padding: .25rem .7rem;
+          text-decoration: none; font-family: var(--mono); font-size: .82rem; }
+        details.inspect { margin: 2rem 0 0; border-top: 1px dashed var(--border); padding-top: 1rem; }
+        details.inspect summary { cursor: pointer; color: var(--muted); font-size: .85rem; }
+        .verb-list { list-style: none; padding: 0; margin: 0; }
+        .verb-list li { border-bottom: 1px solid var(--border); }
+        .verb-list a { display: flex; justify-content: space-between; gap: 1rem; padding: .7rem .2rem;
+          text-decoration: none; color: var(--text); }
+        .verb-list .kind { color: var(--muted); font-family: var(--mono); font-size: .78rem; }
+        .actions { display: flex; flex-wrap: wrap; gap: .5rem; margin: .6rem 0 1.4rem; }
+      CSS
+
+      # Decorative only — every form here already works with JS disabled
+      # (plain `<form method=post>`/`method=get`), matching this repo's own
+      # "no ERB, nothing scripted" bar for the domain layer itself.
+      SCRIPT = <<~JS
+        document.addEventListener("click", (event) => {
+          const button = event.target.closest("[data-copy]");
+          if (!button) return;
+          const text = document.querySelector(button.getAttribute("data-copy"))?.textContent ?? "";
+          navigator.clipboard?.writeText(text.trim());
+          const original = button.textContent;
+          button.textContent = "copied";
+          setTimeout(() => { button.textContent = original; }, 1200);
+        });
+        document.querySelectorAll("[data-money-cents]").forEach((input) => {
+          const preview = document.querySelector(input.getAttribute("data-money-cents"));
+          if (!preview) return;
+          const update = () => {
+            const cents = parseInt(input.value, 10);
+            preview.textContent = Number.isFinite(cents) ? "= " + (cents / 100).toFixed(2) : "";
+          };
+          input.addEventListener("input", update);
+          update();
+        });
+      JS
+    end
+  end
+end

data/lib/hecks/forms/params.rb

@@ -0,0 +1,132 @@
+require "json"
+require "uri"
+require_relative "field_renderer"
+
+module Hecks
+  module Forms
+    # The two directions between a flat, dotted, ALL-STRINGS web payload
+    # (`{"amount.cents"=>"1050", "amount.currency"=>"USD"}`, whether it came
+    # off a POST form body or a GET query string — Rack hands back the same
+    # flat shape for both as long as nothing uses `[]` bracket names) and the
+    # nested, typed hash `Dispatcher#dispatch`/`#query` actually take
+    # (`{amount: {cents: 1050, currency: "USD"}}`).
+    #
+    # `extract` NEEDS the Field tree, not just the raw params — a numeric
+    # leaf's own runtime check (`Value::Coercion#check_numeric_fields`)
+    # requires an actual `Integer`/`Float`, not a String that merely looks
+    # like one (`given.is_a?(expected)`, no coercion attempted there); a web
+    # form can only ever hand back strings, so the cast has to happen here,
+    # once, using the SAME shape `FieldShape` already resolved for
+    # rendering the input in the first place — one reading of the IR, not
+    # two that could disagree.
+    module Params
+      # Every LEAF field carries its own full dotted path regardless of how
+      # deep `FieldShape` nested it to get there — a single-attribute value
+      # object unwraps to a leaf sitting at the TOP of the fields array with
+      # a two-segment path (`"reference.value"`), the exact same shape a
+      # `:group`'s own child carries. So this collects every leaf as
+      # (full path -> value) FIRST, and nests by the path's OWN segments
+      # last — one nesting rule, blind to how a field arrived at its path.
+      def self.extract(fields, raw)
+        pairs = {}
+        fields.each { |field| collect(field, raw, pairs) }
+        nest(pairs)
+      end
+
+      def self.collect(field, raw, pairs)
+        case field.kind
+        when :group, :money then field.children.each { |child| collect(child, raw, pairs) }
+        when :list then (value = extract_list(field, raw)) == SKIP || pairs[field.path] = value
+        else (value = extract_leaf(field, raw)) == SKIP || pairs[field.path] = value
+        end
+      end
+
+      def self.nest(pairs)
+        pairs.each_with_object({}) do |(path, value), result|
+          segments = path.to_s.split(".").map(&:to_sym)
+          leaf = segments.pop
+          node = segments.reduce(result) { |acc, segment| acc[segment] ||= {} }
+          node[leaf] = value
+        end
+      end
+
+      SKIP = Object.new.freeze
+      private_constant :SKIP
+
+      # One line of the textarea per element. A line that itself needs
+      # several fields (a multi-attribute value object as a list element)
+      # is read as JSON on that one line — the honest fallback documented in
+      # docs/command-form-and-query-form-bluebook.md rather than a second
+      # widget this prototype doesn't build yet.
+      def self.extract_list(field, raw)
+        text = raw[field.path]
+        return SKIP if text.nil? || text.strip.empty?
+
+        item = field.children.first
+        text.each_line.map(&:strip).reject(&:empty?).map do |line|
+          item.leaf? ? cast_scalar(item, line) : JSON.parse(line, symbolize_names: true)
+        end
+      end
+
+      def self.extract_leaf(field, raw)
+        return checkbox(raw[field.path]) if field.kind == :boolean
+
+        text = raw[field.path]
+        return SKIP if (text.nil? || text.empty?) && field.optional?
+
+        cast_scalar(field, text)
+      end
+
+      def self.checkbox(raw_value)
+        %w[on 1 true].include?(raw_value.to_s.downcase)
+      end
+
+      def self.cast_scalar(field, text)
+        case field.kind
+        when :number then field.step == "1" ? Integer(text) : Float(text)
+        else text
+        end
+      end
+
+      # The other direction — a nested value hash back to the flat dotted
+      # pairs a GET link's query string carries, so a query view's
+      # "shareable link" and its filter FORM stay two renderings of the
+      # SAME data rather than two formats that can drift. Reads with
+      # `FieldRenderer.dig` — the identical full-path lookup a re-rendered
+      # input's own value comes from — for the same reason `extract` above
+      # nests by full path rather than by tree shape.
+      def self.flatten(fields, values, into: {})
+        fields.each do |field|
+          case field.kind
+          when :group, :money then flatten(field.children, values, into: into)
+          when :list then into[field.path] = Array(FieldRenderer.dig(values, field.path)).join("\n")
+          else
+            value = FieldRenderer.dig(values, field.path)
+            into[field.path] = value.to_s unless value.nil?
+          end
+        end
+        into
+      end
+
+      # Every leaf/list path a field tree carries, independent of any
+      # values — what `command_form_renderer.rb`'s inspect panel wants
+      # ("which fields does this command take"), where `flatten` above wants
+      # "what does THIS submission look like" and returns nothing for a
+      # field nothing was entered for.
+      def self.paths(fields, into: [])
+        fields.each do |field|
+          case field.kind
+          when :group, :money then paths(field.children, into: into)
+          else into << field.path
+          end
+        end
+        into
+      end
+
+      def self.to_query_string(fields, values)
+        pairs = flatten(fields, values)
+        pairs.map { |key, value| "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(value)}" }.join("&")
+      end
+    end
+  end
+end