hecks 3.4.2 → 3.6.0

data/lib/hecks/forms/field_renderer.rb

@@ -1,5 +1,6 @@
 require_relative "html"
 require_relative "field_shape"
+require_relative "field_controls"
 require_relative "../naming"
 
 module Hecks
@@ -12,16 +13,18 @@ module Hecks
       # `reference_options` is built by the caller, since it needs a repository and
       # this module stays pure markup.
       def self.render(field, values: {}, errors: nil, reference_options: {})
+        held = { values: values, errors: errors, reference_options: 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 :group  then group(field, held, tag: "fieldset")
+        when :money  then group(field, held, 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) }
+      # @param held [Hash] the `values:`, `errors:` and `reference_options:` each child renders with
+      def self.group(field, held, tag:, css: nil)
+        inner = field.children.map { |child| render(child, **held) }
         <<~HTML
           <#{tag}#{%( class="#{css}") if css}>
             <legend>#{Escape.html(field.label)}#{required_mark(field)}</legend>
@@ -33,13 +36,22 @@ module Hecks
       # One textarea, an element per line: the shape `Params.extract_list` reads back.
       def self.list(field, values, _errors)
         item = field.children.first
-        current = Array(dig(values, field.path)).join("\n")
+        list_head(field, item, Array(dig(values, field.path)).join("\n")) + list_tail(field, item)
+      end
+
+      def self.list_head(field, item, current)
+        id = dom_id(field.path)
         <<~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)}"
+            <label for="#{id}">#{Escape.html(field.label)}#{required_mark(field)}</label>
+            <textarea id="#{id}" 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#{' — each line is one JSON object' unless item.leaf?}.</span>
+        HTML
+      end
+
+      def self.list_tail(field, item)
+        <<~HTML
+            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{" — each line is one JSON object" unless item.leaf?}.</span>
           </div>
         HTML
       end
@@ -47,21 +59,24 @@ module Hecks
       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)
+        wrap(field, control(field, value, reference_options), error)
+      end
+
+      def self.control(field, value, reference_options)
+        case field.kind
+        when :boolean   then Controls.checkbox(field, value)
+        when :radio     then Controls.radio_group(field, value)
+        when :select    then Controls.select(field, value)
+        when :textarea  then Controls.textarea(field, value)
+        when :reference then Controls.reference_select(field, value, reference_options[field.path])
+        else Controls.input(field, value)
+        end
       end
 
       # A :boolean gets no label here because `checkbox` renders its own beside the box.
       def self.wrap(field, body, error)
         <<~HTML
-          <div class="field#{' has-error' if error}">
+          <div class="field#{" has-error" if error}">
             #{%(<label for="#{dom_id(field.path)}">#{Escape.html(field.label)}#{required_mark(field)}</label>) unless field.kind == :boolean}
             #{body}
             #{%(<span class="help" id="#{dom_id(field.path)}-help">#{Escape.html(field.help)}</span>) if field.help}
@@ -70,79 +85,10 @@ module Hecks
         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
-
-      # The hidden "0" input makes an unticked box still submit a value.
-      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)}"#{' selected' if option_value.to_s == selected.to_s}>) \
-            "#{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
-
-      # Falls back to a plain text id input when no records are on offer.
-      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)}"#{' selected' if id.to_s == value.to_s}>#{Escape.html(label)}</option>)
-        end
-        blank = if field.optional?
-                  %(<option value="">—</option>)
-                else
-                  %(<option value="" disabled#{' selected' unless value}>choose one…</option>)
-                end
-        %(<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>) : ""
 
       # "amount.cents" -> "f-amount-cents".
-      def self.dom_id(path) = "f-#{path.to_s.tr('.', '-')}"
-
-      # A :reference input takes a record id, so the attribute's own pattern must not apply.
-      def self.leaf_pattern(field) = field.kind == :reference ? nil : field.pattern
-
-      def self.money_preview_target(field) = "##{dom_id(field.path)}-preview"
+      def self.dom_id(path) = "f-#{path.to_s.tr(".", "-")}"
 
       # String form, for controls assembled by hand rather than through `Tag.void`.
       def self.aria(field)

data/lib/hecks/forms/field_shape.rb

@@ -2,6 +2,7 @@ require_relative "../vocabulary"
 require_relative "../bluebook/attribute"
 require_relative "../naming"
 require_relative "value_object_shape"
+require_relative "text_shape"
 
 module Hecks
   # The forms surface: the `expose` DSL, the IR->HTML renderers and the Rack app (see forms.rb).
@@ -89,9 +90,7 @@ module Hecks
       # Mirrors Runtime::Value::Admission#admitted_members (same split, chapter walk and
       # discriminant rule) so a `<select>` never offers a member the runtime would 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)
+        set = admitted_set(attribute, aggregate)
         # undeclared — refuse-at-dispatch stays the backstop
         return primitive_field(attribute, common) unless set
 
@@ -100,12 +99,15 @@ module Hecks
         # `Value::Coercion#fields_for` expects, even though `admits:` names a set elsewhere.
         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.path = "#{common[:path]}.#{inner.name}" if inner
         options
       end
 
+      def self.admitted_set(attribute, aggregate)
+        set_aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
+        set_name && aggregate.hecks_owner&.aggregate(set_aggregate_name)&.value_object(set_name)
+      end
+
       def self.own_value_object(attribute, aggregate)
         aggregate.value_object(attribute.type) || cross_aggregate_value_object(aggregate, attribute.type)
       end
@@ -177,36 +179,9 @@ module Hecks
         when "TrueClass", "FalseClass"
           Field.new(**common, kind: :boolean, html_type: "checkbox")
         else
-          text_field(attribute, common)
+          TextShape.field(attribute, common)
         end
       end
-
-      # Vocabulary::FieldHint rows (language/bluebook/vocabulary.bluebook), matched
-      # case-insensitively. hecks project_field_hints writes the Rust host's copy from the same
-      # rows.
-      HINTS = Hecks::Vocabulary.rows("FieldHint")
-                               .to_h { |row| [row["name"], Regexp.new(row["pattern"], Regexp::IGNORECASE)] }
-                               .freeze
-      EMAIL_HINT    = HINTS.fetch("email")
-      URL_HINT      = HINTS.fetch("url")
-      TEL_HINT      = HINTS.fetch("tel")
-      TEXTAREA_HINT = HINTS.fetch("textarea")
-
-      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

@@ -67,7 +67,7 @@ module Hecks
           next if value.nil? || value == false
           next name.to_s.tr("_", "-") if value == true
 
-          %(#{name.to_s.tr('_', '-')}="#{Escape.attr(value)}")
+          %(#{name.to_s.tr("_", "-")}="#{Escape.attr(value)}")
         end.join(" ")
       end
 

data/lib/hecks/forms/index_renderer.rb

@@ -25,20 +25,25 @@ module Hecks
       # @param chapter [Bluebook::Chapter] the loaded chapter
       # @return [String] HTML for the section's heading and aggregate list
       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
+        items = chapter.aggregates.map { |aggregate| aggregate_item(name, aggregate) }
         <<~HTML
           <h2>#{Escape.html(name)}#{%( <span class="badge">#{Escape.html(chapter.vision)}</span>) if chapter.vision}</h2>
           <ul class="verb-list">#{items.join}</ul>
         HTML
       end
+
+      # @param name [String] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate to link to
+      # @return [String] the list item linking to the aggregate, with its command and query counts
+      def self.aggregate_item(name, 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
     end
   end
 end

data/lib/hecks/forms/page.rb

@@ -1,4 +1,6 @@
 require_relative "html"
+require_relative "page_assets"
+require_relative "page_script"
 
 module Hecks
   module Forms
@@ -58,112 +60,6 @@ module Hecks
         end
         %(<nav class="breadcrumbs" aria-label="Breadcrumb">#{items.join(' <span class="sep">/</span> ')}</nav>)
       end
-
-      STYLE = <<~CSS.freeze
-        :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 works with JS disabled.
-      SCRIPT = <<~JS.freeze
-        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/page_assets.rb

@@ -0,0 +1,88 @@
+module Hecks
+  module Forms
+    module Page
+      STYLE = <<~CSS.freeze
+        :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
+    end
+  end
+end

data/lib/hecks/forms/page_script.rb

@@ -0,0 +1,28 @@
+module Hecks
+  module Forms
+    module Page
+      # Decorative only; every form works with JS disabled.
+      SCRIPT = <<~JS.freeze
+        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

@@ -61,18 +61,24 @@ module Hecks
         pairs.each_with_object({}) do |(path, value), result|
           segments = path.to_s.split(".").map(&:to_sym)
           leaf = segments.pop
-          node = segments.reduce(result) do |acc, segment|
-            existing = acc[segment]
-            raise nesting_collision(path) if existing && !existing.is_a?(Hash)
-
-            acc[segment] ||= {}
-          end
+          node = descend(result, segments, path)
           raise nesting_collision(path) if node[leaf].is_a?(Hash)
 
           node[leaf] = value
         end
       end
 
+      # @return [Hash] the group `segments` names under `result`, created as needed
+      # @raise [ArgumentError] if a plain value already sits at one of the segments
+      def self.descend(result, segments, path)
+        segments.reduce(result) do |acc, segment|
+          existing = acc[segment]
+          raise nesting_collision(path) if existing && !existing.is_a?(Hash)
+
+          acc[segment] ||= {}
+        end
+      end
+
       # Builds, without raising, the error `nest` raises for a path-prefix collision.
       #
       # @param path [String] the dotted path at which the collision was found
@@ -118,7 +124,7 @@ module Hecks
       # @raise [ArgumentError] if a number field's text is not numeric
       # @raise [TypeError] if a required number field is missing from `raw`
       def self.extract_leaf(field, raw)
-        return checkbox(raw[field.path]) if field.kind == :boolean
+        return checkbox?(raw[field.path]) if field.kind == :boolean
 
         text = raw[field.path]
         return SKIP if (text.nil? || text.empty?) && field.optional?
@@ -131,10 +137,13 @@ module Hecks
       # @param raw_value [String, nil] the submitted text; nil when the field was not posted
       # @return [Boolean] true for `"on"`, `"1"` or `"true"` in any letter case, false for
       #   anything else
-      def self.checkbox(raw_value)
+      def self.checkbox?(raw_value)
         %w[on 1 true].include?(raw_value.to_s.downcase)
       end
 
+      # The name callers know `checkbox?` by.
+      singleton_class.alias_method :checkbox, :checkbox?
+
       # Casts a leaf's submitted text to the Ruby type the runtime's numeric check requires,
       # which accepts an actual `Integer` or `Float` and never a numeric-looking String.
       #

data/lib/hecks/forms/query_form_renderer.rb

@@ -13,7 +13,11 @@ module Hecks
     # See docs/command-form-and-query-form-bluebook.md.
     module QueryFormRenderer
       # Renders one query's whole GET view as the page body.
-      def self.render(registry:, domain:, aggregate:, query:, action:, params: {}, results: nil, error: nil)
+      #
+      # @param view [Hash] `action:` (required), the form's URL path, and optionally `params:`
+      #   (the values asked for), `results:` (the records found) and `error:` (a refusal to show)
+      def self.render(registry:, domain:, aggregate:, query:, **view)
+        action = view.fetch(:action)
         fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
         reference_options = ReferenceOptions.collect(registry, domain, fields)
 
@@ -21,9 +25,9 @@ module Hecks
           #{header(domain, aggregate, query)}
           #{canonical_link(action, fields)}
           #{quick_links(action, fields)}
-          #{filter_form(action, fields, params, reference_options)}
-          #{error_banner(error)}
-          #{results_section(aggregate, results, domain)}
+          #{filter_form(action, fields, view.fetch(:params, {}), reference_options)}
+          #{error_banner(view[:error])}
+          #{results_section(aggregate, view[:results], domain)}
           #{inspect_panel(domain, aggregate, query, fields)}
         HTML
       end
@@ -44,7 +48,7 @@ module Hecks
 
       def self.canonical_link(action, fields)
         paths = Params.paths(fields)
-        template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join('&')}"
+        template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join("&")}"
         <<~HTML
           <p class="help">Every query is a plain GET — this exact URL is bookmarkable, linkable from a dashboard, curlable, whatever a feature needs:</p>
           <div class="link-row"><code id="canonical-link">#{Escape.html(template)}</code><button type="button" class="copy" data-copy="#canonical-link">copy</button></div>
@@ -77,7 +81,7 @@ module Hecks
       def self.error_banner(error)
         return "" unless error
 
-        %(<div class="error-banner" role="alert"><p><strong>#{Escape.html(error.class.name.split('::').last)}</strong> — ) \
+        %(<div class="error-banner" role="alert"><p><strong>#{Escape.html(error.class.name.split("::").last)}</strong> — ) \
           "#{Escape.html(error.message)}</p></div>"
       end
 
@@ -93,7 +97,7 @@ module Hecks
         <<~HTML
           <details class="inspect">
             <summary>Inspect — #{Escape.html(verb)}</summary>
-            <p>Parameters: #{paths.empty? ? '<em>none</em>' : paths.map { |p| "<code>#{Escape.html(p)}</code>" }.join(', ')}</p>
+            <p>Parameters: #{paths.empty? ? "<em>none</em>" : paths.map { |p| "<code>#{Escape.html(p)}</code>" }.join(", ")}</p>
             <pre>#{Escape.html(JSON.pretty_generate(query.to_h))}</pre>
           </details>
         HTML