hecks 2.7.0 → 2.9.0

data/lib/hecks/forms/command_form_renderer.rb

@@ -7,18 +7,14 @@ require_relative "params"
 
 module Hecks
   module Forms
-    # Command -> the page body for its HTML form — the working half of
-    # what `command_form.bluebook` names (see docs/command-form-and-query-
-    # form-bluebook.md). Every command in every loaded, exposed bluebook
-    # renders through here — nothing here is per-command code; see that
-    # doc for the 1:1 rule this deliberately holds to for now.
+    # Renders a command as the page body of its HTML form; no per-command code
+    # (see docs/command-form-and-query-form-bluebook.md).
     module CommandFormRenderer
       # Lists every field a command's form shows: the `to` identity picker first (unless the
       # command creates its aggregate), then one field per command attribute.
       #
-      # The same field list a POST handler needs to cast raw params against
-      # (params.rb's `Params.extract`) — one derivation, so a page never
-      # renders an input the submit handler doesn't also expect.
+      # The same list `Params.extract` casts a POST against, so a page never renders
+      # an input the submit handler does not expect.
       #
       # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
       # @param command [Bluebook::Command] the command the form submits
@@ -33,25 +29,14 @@ module Hecks
       # Renders the page body for one command: header, refusal banner, the form itself, and
       # the inspect panel.
       #
-      # `registry` serves only to populate a `:reference` field's
-      # `<select>` with real records (including the identity picker itself,
-      # for a non-creating command — see `identity_field` below). `values`/
-      # `error` carry a sticky re-render after a refused submission; leave
-      # both nil for a fresh form. `prefill` carries values a caller
-      # arrived with (typically `?to=...` off a record's own detail page) —
-      # kept separate from `values` because a prefill is not an error retry
-      # and should not be treated as one by a future reader of this code.
+      # `registry` populates `:reference` selects. `values` and `error` re-render after a
+      # refusal; `prefill` carries values the caller arrived with (`?to=...`), not a retry.
       #
       # @param registry [Runtime::Registry] the booted registry, read for reference options
-      # @param domain [String] name of the domain (chapter) the aggregate belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
-      # @param command [Bluebook::Command] the command the form submits
       # @param action [String] URL path the form posts to
-      # @param values [Hash{String => Object}, nil] the raw submission to re-show after a
-      #   refusal, keyed by dotted field path; nil falls back to `prefill`
+      # @param values [Hash{String => Object}, nil] raw submission to re-show; nil uses `prefill`
       # @param error [Exception, nil] the refusal to show in the banner; nil for a fresh form
-      # @param prefill [Hash{String => String}] values the caller arrived with, keyed by
-      #   dotted field path; ignored when `values` is given
+      # @param prefill [Hash{String => String}] values the caller arrived with, by dotted path
       # @return [String] the HTML page body, without the surrounding page chrome
       def self.render(registry:, domain:, aggregate:, command:, action:, values: nil, error: nil, prefill: {})
         all_fields = fields_for(aggregate, command)
@@ -130,12 +115,8 @@ module Hecks
       # Maps a refusal to per-field messages; always empty, so every refusal is shown in
       # the banner rather than beside a field.
       #
-      # No structured field attribution exists on a domain refusal today
-      # (it is a typed exception with a rendered message — see
-      # docs/command-form-and-query-form-bluebook.md's note on
-      # `RefusalWording`), so this returns empty rather than guessing which
-      # field a message meant; the banner above carries the real text
-      # instead of a misattributed hint.
+      # A domain refusal carries no field attribution, so the banner shows the message
+      # instead of guessing a field.
       #
       # @param _error [Exception, nil] the refusal raised by the submission; ignored
       # @return [Hash] always empty; keys would be dotted field paths

data/lib/hecks/forms/field_renderer.rb

@@ -4,31 +4,13 @@ require_relative "../naming"
 
 module Hecks
   module Forms
-    # A Field (field_shape.rb) -> the `<div class="field">...</div>` or
-    # `<fieldset>...</fieldset>` markup for it. One renderer, called
-    # recursively for a group's children, shared by CommandFormRenderer
-    # (POST) and QueryFormRenderer (GET) — the same attribute shape asks
-    # for the same input either way; only the surrounding `<form>`'s
-    # method differs.
+    # Renders a Field (field_shape.rb) as form markup, recursing into a group's children.
+    # Shared by CommandFormRenderer (POST) and QueryFormRenderer (GET).
     module FieldRenderer
-      # Renders one field, and recursively a group's children, as form markup with any held
-      # value filled back in.
+      # Renders one field, filling any held value 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
+      # `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: {})
         case field.kind
         when :group  then group(field, values, errors, reference_options, tag: "fieldset")
@@ -38,17 +20,6 @@ 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
@@ -59,14 +30,7 @@ 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
+      # 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")
@@ -80,15 +44,6 @@ 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]
@@ -103,14 +58,7 @@ 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
+      # 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}">
@@ -122,13 +70,6 @@ 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,
@@ -140,23 +81,11 @@ 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
+      # 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
@@ -168,13 +97,6 @@ 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|
@@ -187,13 +109,6 @@ 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|
@@ -204,16 +119,7 @@ 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>`
+      # 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?
 
@@ -228,78 +134,33 @@ 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
+      # "amount.cents" -> "f-amount-cents".
       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
+      # 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
 
-      # 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
+      # String form, for controls assembled by hand rather than through `Tag.void`.
       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
+      # Hash form of `aria`, to splat into `Tag.void`.
       def self.aria_attrs(field)
         { required: field.required?, aria_describedby: field.help ? "#{dom_id(field.path)}-help" : nil }
       end
 
-      # 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
+      # Reads the value held for a dotted path from either a flat or a nested values hash.
       def self.dig(values, path)
         return nil unless values.is_a?(Hash)
 
-        # A sticky re-render after a refused submission hands back the raw
-        # flat params (`{"amount.cents"=>"1050"}` — the same shape the form
-        # posted, string values and all, dotted key intact) ; a prefill from
-        # an existing record's own state hands back a nested hash instead
-        # (`{amount: {cents: 1050}}`). Flat wins when both would answer,
-        # since only the raw form is ever what the caller actually typed.
-        # `key?` decides which spelling answers, at every step below —
-        # never `||`, which would treat a genuinely-held `false` the
-        # same as an absent key and fall through to `nil`.
+        # A sticky re-render hands back raw flat params ({"amount.cents"=>"1050"}); a prefill
+        # from a record's state is nested ({amount: {cents: 1050}}). Flat wins when both answer.
+        # Test with `key?`, never `||`, so a held `false` is not mistaken for an absent key.
         str = path.to_s
         return values[str] if values.key?(str)