hecks 1.3.0 → 1.4.0

data/lib/hecks/forms/field_renderer.rb

@@ -11,11 +11,24 @@ module Hecks
     # 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
+      # Renders one field, and recursively a group's children, as form markup with any held
+      # value filled back in.
+      #
+      # `values` is the 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).
+      #
+      # @param field [Forms::Field] the field to render
+      # @param values [Hash{String, Symbol => Object}] held values, either flat and keyed by
+      #   dotted path or nested by path segment; see `dig`
+      # @param errors [Hash{String => String}, nil] message per dotted field path; nil for none
+      # @param reference_options [Hash{String => Array<Array>, nil}] `[id, label]` pairs per
+      #   `:reference` field path, as `ReferenceOptions.collect` builds them; a nil or empty
+      #   entry renders a plain text input
+      # @return [String] HTML for the field: a `<fieldset>` for `:group` and `:money`, a
+      #   `<div class="field">` otherwise
       def self.render(field, values: {}, errors: nil, reference_options: {})
         case field.kind
         when :group  then group(field, values, errors, reference_options, tag: "fieldset")
@@ -25,6 +38,17 @@ module Hecks
         end
       end
 
+      # Renders a field's children inside one enclosing element, with the field's label as
+      # its `<legend>`.
+      #
+      # @param field [Forms::Field] a `:group` or `:money` field carrying `children`
+      # @param values [Hash{String, Symbol => Object}] held values; see `dig`
+      # @param errors [Hash{String => String}, nil] message per dotted field path
+      # @param reference_options [Hash{String => Array<Array>, nil}] `[id, label]` pairs per
+      #   `:reference` field path
+      # @param tag [String] name of the enclosing element, such as `"fieldset"`
+      # @param css [String, nil] class attribute for the enclosing element; nil for none
+      # @return [String] HTML for the enclosing element and every child
       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
@@ -35,6 +59,14 @@ module Hecks
         HTML
       end
 
+      # Renders a `:list` field as one textarea taking an element per line, which is the shape
+      # `Params.extract_list` reads back.
+      #
+      # @param field [Forms::Field] a `:list` field whose first child describes one element
+      # @param values [Hash{String, Symbol => Object}] held values; the list's entry may be an
+      #   Array, a newline-joined String, or absent
+      # @param _errors [Hash{String => String}, nil] ignored; a list shows no per-field message
+      # @return [String] HTML for the labelled textarea and its help line
       def self.list(field, values, _errors)
         item = field.children.first
         current = Array(dig(values, field.path)).join("\n")
@@ -48,6 +80,15 @@ module Hecks
         HTML
       end
 
+      # Renders a single-value field with the control its `kind` calls for, wrapped with its
+      # label, help text and error.
+      #
+      # @param field [Forms::Field] a leaf field
+      # @param values [Hash{String, Symbol => Object}] held values; see `dig`
+      # @param errors [Hash{String => String}, nil] message per dotted field path
+      # @param reference_options [Hash{String => Array<Array>, nil}] `[id, label]` pairs per
+      #   `:reference` field path
+      # @return [String] HTML for the `<div class="field">` block
       def self.leaf(field, values, errors, reference_options)
         value = dig(values, field.path)
         error = errors && errors[field.path]
@@ -62,6 +103,14 @@ module Hecks
         wrap(field, body, error)
       end
 
+      # Wraps a rendered control with its label, help text and error message; a `:boolean`
+      # gets no label here because `checkbox` renders its own beside the box.
+      #
+      # @param field [Forms::Field] the field the control belongs to
+      # @param body [String] HTML of the control itself
+      # @param error [String, nil] message shown as an alert; nil for none
+      # @return [String] HTML for the `<div class="field">` block, classed `has-error` when
+      #   `error` is given
       def self.wrap(field, body, error)
         <<~HTML
           <div class="field#{' has-error' if error}">
@@ -73,6 +122,13 @@ module Hecks
         HTML
       end
 
+      # Renders an `<input>` of the field's `html_type`, falling back to the field's default
+      # for a missing value; a whole-cents number also gets a live preview span.
+      #
+      # @param field [Forms::Field] a leaf field
+      # @param value [Object, nil] the held value, rendered with `to_s`; nil shows the default
+      # @return [String] HTML for the input, followed by the preview `<span>` when the field
+      #   is a `:number` whose help text mentions cents
       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,
@@ -84,10 +140,23 @@ module Hecks
         %(#{tag} <span id="#{dom_id(field.path)}-preview" class="mono help" aria-live="polite"></span>)
       end
 
+      # Renders a `<textarea>` holding the value as escaped text; unlike `input`, the field's
+      # default is not filled in.
+      #
+      # @param field [Forms::Field] a `:textarea` field
+      # @param value [Object, nil] the held value, rendered with `to_s`; nil renders empty
+      # @return [String] HTML for the textarea
       def self.textarea(field, value)
         %(<textarea id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{Escape.html(value)}</textarea>)
       end
 
+      # Renders a checkbox preceded by a hidden `"0"` input of the same name, so an unticked
+      # box still submits a value, with the field's label beside it.
+      #
+      # @param field [Forms::Field] a `:boolean` field
+      # @param value [Boolean, String, nil] the held value; `true`, `"true"`, `"on"` and `"1"`
+      #   tick the box, and nil falls back to a default of exactly `true`
+      # @return [String] HTML for the checkbox row
       def self.checkbox(field, value)
         checked = value.nil? ? field.default == true : [true, "true", "on", "1"].include?(value)
         <<~HTML
@@ -99,6 +168,13 @@ module Hecks
         HTML
       end
 
+      # Renders one radio button per option, pre-checking the one equal to the held value or,
+      # failing that, to the field's default.
+      #
+      # @param field [Forms::Field] a `:radio` field whose `options` are `[value, label]` pairs
+      # @param value [Object, nil] the held value, compared with `to_s`; nil falls back to the
+      #   default
+      # @return [String] HTML for the `<div role="radiogroup">` block
       def self.radio_group(field, value)
         selected = value || field.default
         options = field.options.map do |option_value, option_label|
@@ -111,6 +187,13 @@ module Hecks
         %(<div class="radio-group" role="radiogroup">#{options.join}</div>)
       end
 
+      # Renders a `<select>` over the field's fixed options, with a blank "—" entry first when
+      # the field is optional.
+      #
+      # @param field [Forms::Field] a `:select` field whose `options` are `[value, label]` pairs
+      # @param value [Object, nil] the held value, compared with `to_s`; nil falls back to the
+      #   default
+      # @return [String] HTML for the select
       def self.select(field, value)
         selected = value || field.default
         options = field.options.map do |option_value, option_label|
@@ -121,6 +204,16 @@ module Hecks
         %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{options.join}</select>)
       end
 
+      # Renders a `<select>` of existing records for a `:reference` field, degrading to a plain
+      # text id input when no records are on offer.
+      #
+      # @param field [Forms::Field] a `:reference` field; its `html_type` is set to `"text"`
+      #   in place when the text fallback is taken
+      # @param value [Object, nil] the held id, compared with `to_s`; nil preselects the
+      #   disabled "choose one…" entry of a required field
+      # @param options [Array<Array>, nil] `[id, label]` pairs to offer; nil or empty takes the
+      #   text fallback
+      # @return [String] HTML for the select, or for the fallback `<input>`
       def self.reference_select(field, value, options)
         return input(field.tap { |f| f.html_type = "text" }, value) unless options && !options.empty?
 
@@ -135,30 +228,73 @@ module Hecks
         %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{rendered.join}</select>)
       end
 
+      # Renders the asterisk that marks a required field's label or legend.
+      #
+      # @param field [Forms::Field] the field being labelled
+      # @return [String] HTML for the mark, or `""` when the field is optional
       def self.required_mark(field) = field.required? ? %(<span class="required-mark" title="required">*</span>) : ""
+
+      # Derives the element id of a field's control from its dotted path, such as
+      # `"f-amount-cents"` for `"amount.cents"`.
+      #
+      # @param path [String, Symbol] the field's dotted path
+      # @return [String] the id, `"f-"` followed by the path with dots turned to hyphens
       def self.dom_id(path) = "f-#{path.to_s.tr('.', '-')}"
+
+      # Picks the `pattern` attribute an input carries, withholding it from a `:reference`
+      # field, whose input takes a record id rather than the attribute's own value.
+      #
+      # @param field [Forms::Field] a leaf field
+      # @return [String, nil] the regex source the attribute declares as `pattern:`; nil for a
+      #   `:reference` field or when none is declared
       def self.leaf_pattern(field) = field.kind == :reference ? nil : field.pattern
+
+      # Names the preview span a whole-cents input's `data-money-cents` attribute points at.
+      #
+      # @param field [Forms::Field] the cents field
+      # @return [String] a CSS id selector, such as `"#f-amount-cents-preview"`
       def self.money_preview_target(field) = "##{dom_id(field.path)}-preview"
 
+      # Renders the `required` and `aria-describedby` attributes of a control as an
+      # attribute string, for the controls assembled by hand rather than through `Tag.void`.
+      #
+      # @param field [Forms::Field] the field the control belongs to
+      # @return [String] the rendered attributes, or `""` when the field is optional and has
+      #   no help text
       def self.aria(field)
         Tag.attrs(required: field.required?, aria_describedby: field.help ? "#{dom_id(field.path)}-help" : nil)
       end
 
+      # Builds the `required` and `aria-describedby` attributes of a control as a Hash, to
+      # splat into `Tag.void`.
+      #
+      # @param field [Forms::Field] the field the control belongs to
+      # @return [Hash{Symbol => Boolean, String, nil}] `:required` and `:aria_describedby`;
+      #   the latter is the help span's element id, or nil when the field has no help text
       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
+      # Reads the value held for a dotted field path out of either spelling a form's values
+      # arrive in, flat or nested, without losing a stored `false`.
+      #
+      # `values` is a nested hash; `path` a dotted string using the same
+      # segment spelling the hash keys are built from (`Params.nest` 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.
+      #
+      # @param values [Hash{String, Symbol => Object}, Object] held values; anything that is
+      #   not a Hash, nil included, reads as nil
+      # @param path [String, Symbol] the field's dotted path, such as `"amount.cents"`
+      # @return [Object, nil] the held value exactly as stored (a raw form String, or a typed
+      #   value from a record's state); nil when no key on the path answers
       def self.dig(values, path)
         return nil unless values.is_a?(Hash)
 
-        # A sticky re-render after a refused submission hands back the RAW
+        # 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
+        # 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.
         # `key?` decides which spelling answers, at every step below —

data/lib/hecks/forms/field_shape.rb

@@ -1,37 +1,57 @@
+require_relative "../vocabulary"
 require_relative "../bluebook/attribute"
 require_relative "../naming"
 require_relative "value_object_shape"
 
 module Hecks
   module Forms
-    # One resolved field, ready for a renderer to turn into markup. A LEAF
+    # 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 —
+    # `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
+    # (`email: {address: "..."}`), so `Params.extract` (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
+      # Tells whether this field holds a value itself rather than carrying `children`.
+      #
+      # @return [Boolean] false for a `:group` or `:list`, true for every other kind,
+      #   `:money` included
       def leaf? = kind != :group && kind != :list
+
+      # Tells whether a submission may leave this field blank.
+      #
+      # @return [Boolean, nil] the `optional` member as given; nil when the field was built
+      #   without one, which reads as required
       def optional? = optional
+
+      # Tells whether a submission must fill this field in.
+      #
+      # @return [Boolean] true unless `optional` was set truthy
       def required? = !optional
     end
 
     # Turns a wire-spelled field or path segment into the plain-English text
     # `FieldShape` embeds as a `Field`'s label or a group's legend.
     module Humanize
+      # Humanizes the last segment of a field name or dotted path into sentence-case words.
+      #
       # "given" -> "Given", "daily_limit" -> "Daily limit", "end_to_end" ->
       # "End to end" — the label a plain reader wants, not the wire spelling.
+      #
+      # @param text [String, Symbol, nil] a field name or dotted path, such as
+      #   `"amount.cents"`; only the part after the last `"."` is used
+      # @return [String] the humanized words, or `""` when `text` is nil or empty
       def self.label(text)
-        # Split on "." FIRST, alone, to take only the last path segment —
+        # 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
@@ -39,14 +59,19 @@ module Hecks
         segment = text.to_s.split(".").last.to_s
         return segment if segment.empty?
 
-        # The word split itself is `Naming.words`' now — the one
-        # humanizer, shared with the glossary projection.
+        # The word split itself is `Naming.words` — the one humanizer,
+        # shared with the glossary projection.
         Naming.words(segment)
       end
 
+      # Humanizes every segment of a dotted path and joins them with " → ".
+      #
       # 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.
+      #
+      # @param path [String, Symbol, nil] a dotted field path, such as `"amount.cents"`
+      # @return [String] the humanized trail, or `""` when `path` is nil or empty
       def self.breadcrumb(path)
         path.to_s.split(".").map { |part| label(part) }.join(" → ")
       end
@@ -61,12 +86,23 @@ module Hecks
     module FieldShape
       PRIMITIVES = Bluebook::Attribute::PRIMITIVES
 
-      # `aggregate:` is the Aggregate that OWNS this attribute (a
+      # Resolves one declared attribute into the field a form renders for it, choosing the
+      # input kind from the attribute's type, pattern, `admits:` set and value-object shape.
+      #
+      # `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.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to build a field for
+      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
+      # @param path [String] dotted field path the attribute is reached at
+      # @return [Forms::Field] the resolved field; a single-attribute value object resolves
+      #   to its inner leaf, so the returned path may be longer than `path`
+      # @raise [Bluebook::DSL::Malformed] if a `reference_to` attribute cannot say which
+      #   aggregate declares it
       def self.resolve(attribute, aggregate:, path: attribute.name.to_s)
         return list_field(attribute, aggregate, path) if attribute.list?
 
@@ -80,6 +116,15 @@ module Hecks
         primitive_field(attribute, common)
       end
 
+      # Builds the `:list` field for a `list_of` attribute, carrying as its one child the field
+      # a single element would resolve to.
+      #
+      # @param attribute [Bluebook::Attribute] the list attribute
+      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
+      # @param path [String] dotted field path the list is reached at
+      # @return [Forms::Field] a `:list` field whose `children` holds exactly one element field
+      # @raise [Bluebook::DSL::Malformed] if the element is a `reference_to` that cannot say
+      #   which aggregate declares it
       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
@@ -92,6 +137,17 @@ module Hecks
                   children: [resolve(scalar, aggregate: aggregate, path: path)])
       end
 
+      # Builds the `:reference` field for a `reference_to` attribute, remembering the target
+      # aggregate so a renderer can offer its records.
+      #
+      # @param attribute [Bluebook::Attribute] an attribute whose type is a
+      #   `Bluebook::Reference`
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @return [Forms::Field] a `:reference` field; its `target_aggregate` is nil when the
+      #   target belongs to a domain that is not loaded
+      # @raise [Bluebook::DSL::Malformed] if the reference cannot say which aggregate
+      #   declares it
       def self.reference_field(attribute, common)
         target = attribute.type.resolve
         Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target,
@@ -102,27 +158,40 @@ module Hecks
                                   end)
       end
 
-      # `admits:` names a closed set declared ELSEWHERE (`"Account::
+      # Builds the radio or select field for an attribute whose `admits:` names a closed set,
+      # offering exactly that set's members.
+      #
+      # `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.
+      #
+      # @param attribute [Bluebook::Attribute] an attribute declaring `admits:`
+      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute; its
+      #   chapter is searched for the named set
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @return [Forms::Field] a `:radio` or `:select` field, its path extended by one hop
+      #   when the attribute's own type is a single-attribute value object; a plain
+      #   primitive field when the named set is not declared
       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
+        # undeclared — refuse-at-dispatch stays the backstop
+        return primitive_field(attribute, common) unless set
 
         options = select_or_radio(common, closed_set_options(set))
-        # The attribute's OWN type still has to be built the shape coercion
+        # 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
+        # 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
+        # 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)
@@ -132,10 +201,28 @@ module Hecks
         options
       end
 
+      # Finds the value object an attribute's type names, looking on the owning aggregate
+      # first and then on every other aggregate of the same chapter.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute whose type names a value object
+      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
+      # @return [Bluebook::ValueObject, nil] the declared shape, or nil when no aggregate in
+      #   the chapter declares a value object of that name
       def self.own_value_object(attribute, aggregate)
         aggregate.value_object(attribute.type) || cross_aggregate_value_object(aggregate, attribute.type)
       end
 
+      # Builds the field for an attribute typed as a value object: a closed-set choice, a
+      # money pair, the unwrapped inner leaf of a single-attribute shape, or a group.
+      #
+      # @param attribute [Bluebook::Attribute] an attribute whose type is not a primitive
+      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @return [Forms::Field] the resolved field; a plain primitive field when the named
+      #   value object is not declared anywhere in the chapter
+      # @raise [Bluebook::DSL::Malformed] if a nested `reference_to` attribute cannot say
+      #   which aggregate declares it
       def self.value_object_field(attribute, aggregate, common)
         shape = own_value_object(attribute, aggregate)
         return primitive_field(attribute, common) unless shape
@@ -144,9 +231,9 @@ module Hecks
         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
+        # 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,
+        # 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.
@@ -158,6 +245,14 @@ module Hecks
         group_field(shape, aggregate, common)
       end
 
+      # Searches every aggregate of the owning chapter for a value object by name, so a shape
+      # declared on a sibling aggregate still resolves.
+      #
+      # @param aggregate [Bluebook::Aggregate] any aggregate of the chapter to search
+      # @param type_name [String] name of the value object, as `Bluebook::Attribute#type`
+      #   spells it
+      # @return [Bluebook::ValueObject, nil] the first match in aggregate declaration order, or
+      #   nil when none declares it or the aggregate has no owning chapter
       def self.cross_aggregate_value_object(aggregate, type_name)
         aggregate.hecks_owner&.aggregates&.each do |sibling|
           found = sibling.value_object(type_name)
@@ -166,11 +261,31 @@ module Hecks
         nil
       end
 
+      # Builds the `:group` field for a multi-attribute value object, resolving each of its
+      # attributes one path hop below the group.
+      #
+      # @param shape [Bluebook::ValueObject] the value object whose attributes become children
+      # @param aggregate [Bluebook::Aggregate] the aggregate the nested attributes resolve
+      #   against
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares; only
+      #   `:path`, `:label` and `:optional` are read
+      # @return [Forms::Field] a `:group` field with one child per attribute of `shape`
+      # @raise [Bluebook::DSL::Malformed] if a nested `reference_to` attribute cannot say
+      #   which aggregate declares it
       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
 
+      # Builds the `:money` field for a `cents`/`currency` value object: a required-or-not
+      # whole-cents number input beside an always-optional currency code.
+      #
+      # @param shape [Bluebook::ValueObject] the money-shaped value object, read for the
+      #   declared defaults of `cents` and `currency`
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares; only
+      #   `:path`, `:label` and `:optional` are read
+      # @return [Forms::Field] a `:money` field whose children are the `cents` and `currency`
+      #   leaves, the currency defaulting to `"USD"` when the shape declares none
       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],
@@ -182,27 +297,57 @@ module Hecks
                   children: [cents, currency])
       end
 
+      # Lists a closed set's members by their discriminant — the value object's first
+      # attribute — as the strings a form offers.
+      #
+      # @param value_object [Bluebook::ValueObject] a closed-set (`one_of`) value object
+      # @return [Array<String>] one discriminant value per declared member, in declaration
+      #   order; `[]` when the shape declares no members
       def self.closed_set_options(value_object)
         discriminant = value_object.attributes.first.name
         value_object.members.map { |member| member[discriminant].to_s }
       end
 
+      # Builds the radio or select field for an attribute typed as a closed set, its path
+      # extended by the set's discriminant attribute.
+      #
       # A `one_of` shape (`AccountKind{name}`, `LedgerDirection{value}`) is
-      # ALWAYS single-attribute in this language — the discriminant IS the
+      # 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).
+      #
+      # @param shape [Bluebook::ValueObject] the closed-set value object
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @return [Forms::Field] a `:radio` or `:select` field offering the set's members
       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
 
+      # Builds a choice field over fixed options, as radio buttons for four or fewer and a
+      # `<select>` beyond that.
+      #
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @param options [Array<String>] the values offered; each is its own label
+      # @return [Forms::Field] a `:radio` or `:select` field whose `options` are
+      #   `[value, label]` pairs
       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
 
+      # Builds the leaf field for a primitive-typed attribute: a number input for `Integer`
+      # and `Float`, a checkbox for a boolean, and a text-family input for anything else.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute whose type picks the input
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @return [Forms::Field] a `:number`, `:boolean`, `:text` or `:textarea` leaf; an
+      #   `Integer` carries `step` `"1"`, a `Float` `"any"`
       def self.primitive_field(attribute, common)
         case attribute.type.to_s
         when "Integer" then Field.new(**common, kind: :number, html_type: "number", step: "1")
@@ -214,11 +359,27 @@ module Hecks
         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
+      # Vocabulary::FieldHint (language/bluebook/vocabulary.bluebook), read
+      # off the generated table: `pattern` is the regex source, matched
+      # case-insensitively. bin/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")
 
+      # Builds a text-family leaf, picking `email`, `url`, `tel` or plain `text` from the
+      # attribute's pattern and the `FieldHint` name patterns, and a textarea for a
+      # long-text name.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute whose name and pattern are read
+      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
+      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
+      # @return [Forms::Field] a `:text` leaf, or `:textarea` when the input type is plain
+      #   `"text"` and the name matches `TEXTAREA_HINT`
       def self.text_field(attribute, common)
         name = attribute.name.to_s
         pattern = attribute.pattern.to_s