Documentation
¶
Overview ¶
Package forms is the console's form library (spec form-library; design D1 to D14 of the forms-library change). Every form on the member and operator surfaces, and on an integration-owned page, is one declared value: a FormSpec with a name, a kind, a layout family, a method, a path, an ordered list of Field values, a commit label and a way out. One part renders the declaration, one Parse reads a request through it, and one registry indexes every declaration so tests can hold the whole console to the same rules.
The package sits below internal/server and below the integrations' web packages so both can import it without a cycle; it knows nothing about handlers, databases or the domain. Each form is declared in the package that serves it, in a *_forms.go file beside the handler, the way anatomy.go builds page headers per page, and registers itself with Register. The registry is the index, not the home.
The option set is small on purpose (Primer's side of the tradeoff): accessible and consistent forms by default, customisation limited so a caller cannot render a control without its label, its hint wiring or its error slot. A form that cannot be expressed here is a change to the library or a recorded exception, never a hand-built form; the one escape hatch is the data-* and hx-* attribute map, which cannot override an attribute the part owns.
Index ¶
- func CheckInvariants(spec FormSpec) []string
- func RegisterTrigger(t ActionTrigger)
- func Routes() map[string]string
- type ActionTrigger
- type Batch
- type Binding
- type CommitLinkView
- type ConfirmTrigger
- type Control
- type DeltaView
- type DisabledControlView
- type Errors
- type Family
- type Field
- type FieldView
- type Focus
- type FormSpec
- func (s FormSpec) Bind(b Binding) FormView
- func (s FormSpec) Field(name string) (Field, bool)
- func (s FormSpec) Parse(r *http.Request) (Values, *Errors)
- func (s FormSpec) ParseBatch(r *http.Request) Batch
- func (s FormSpec) ParseBatchWith(r *http.Request, options map[string][]Option) Batch
- func (s FormSpec) ParseSide(r *http.Request, side Side, options map[string][]Option) (Values, *Errors)
- func (s FormSpec) ParseWith(r *http.Request, options map[string][]Option) (Values, *Errors)
- type FormView
- func (v FormView) CommitClasses() string
- func (v FormView) CommitControl() *DisabledControlView
- func (v FormView) FormErrorNotice() notice.Notice
- func (v FormView) HasErrors() bool
- func (v FormView) RowAction(act, key, label, variant string) RowActionView
- func (v FormView) RowBox(instance string, fields ...string) RowBoxView
- func (v FormView) RowCommit(key string) RowActionView
- func (v FormView) RowConfirm(key string, t ConfirmTrigger) RowActionView
- func (v FormView) RowField(instance, field string, options ...string) FieldView
- func (v FormView) RowOpener(act, key, label, variant string, expanded bool) RowActionView
- type Fraction
- type HelpIcon
- type HiddenInput
- type Kind
- type Mode
- type Option
- type OptionView
- type Placement
- type RadioView
- type RowActionView
- type RowBinding
- type RowBoxView
- type ShowIf
- type Side
- type StagedDelta
- type Values
- func (v Values) Bool(name string) bool
- func (v Values) Int(name string) (int, bool)
- func (v Values) Present(name string) bool
- func (v Values) Raw(name string) string
- func (v *Values) Set(name, raw string)
- func (v *Values) SetBool(f Field, on bool)
- func (v Values) String(name string) string
- func (v Values) Time(name string) (time.Time, bool)
- func (v Values) UUID(name string) (uuid.UUID, bool)
- type WayOut
- type WayOutKind
- type WayOutView
- type Width
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckInvariants ¶
CheckInvariants returns every rule spec breaks, as sentences naming the form and the field. An empty result is a declaration the library can render and read.
func RegisterTrigger ¶
func RegisterTrigger(t ActionTrigger)
RegisterTrigger declares one out-of-form mutation trigger. Two triggers may share a route (the same mutation fired from two places); the first registration wins and the second is ignored, so a route is declared once however many controls fire it.
Types ¶
type ActionTrigger ¶
type ActionTrigger struct {
// Label is what the control reads, for the test's failure message and
// for a reader looking for the control on the page.
Label string
// Method and Path are the registered route.
Method string
Path string
// Modal reports whether the shared confirm modal guards the trigger.
Modal bool
// Note records anything a reader needs that the label does not say
// (the trigger is the sortable table itself, for instance).
Note string
}
ActionTrigger is a mutation the console fires from something that is not a form: a row's Revoke button, a panel's Sync control, a sortable table's reorder. These are the other half of the route-level template-versus-handler check (findings FA-6, FA-7, FA-9): the route test asserts every registered mutation route is either a form's path or one of these, so a handler cannot grow a route nothing renders and no declaration names.
func ActionTriggers ¶
func ActionTriggers() []ActionTrigger
ActionTriggers returns every declared out-of-form mutation trigger, ordered by route.
func (ActionTrigger) Key ¶
func (t ActionTrigger) Key() string
Key is the trigger's registry key, "METHOD /path".
type Batch ¶
type Batch struct {
// Act is what was pressed and Key the record it was pressed on, from
// the row action's own hx-vals. Both are the library's names, not
// declared fields: a declaration names controls, and these name the
// press.
Act string
Key string
// Open are the record keys whose editors were open, in the order the
// hidden inputs carried them.
Open []string
// Rows are those editors' values, keyed by record key, each read
// through the row fields' own rules.
Rows map[string]Values
// Staged is the batch as submitted, in index order, each delta's values
// read through the row and delta fields' rules. Line and Error are the
// render's, never the request's, so both are empty here.
Staged []StagedDelta
// Tray holds the tray's own fields.
Tray Values
// Errors are the refusals, keyed "rows.<instance>.<field>",
// "staged.<i>.<field>", the tray field's own name, and the form level.
Errors *Errors
}
Batch is one request through a batch form's declaration (design D1's "Rows family contract"; spec form-library "A batch form renders the caller's rows and one tray"). Every posting control of a Rows form sends the whole form, so one request carries what was pressed, every open editor's typed values, the whole staged batch and the tray's own fields; ParseBatch reads all four through the declaration and nothing else.
ParseBatch validates shape, not domain: the handler decides what Act means, re-reads the records the batch names, and refuses a delta whose record has moved under it (design D3).
func (Batch) Row ¶
func (b Batch) Row(instance string) RowBinding
Row returns one open editor as the render wants it: its values, and its refusals under the declaration's bare field names, so the handler hands back what it parsed without re-keying anything by hand.
type Binding ¶
type Binding struct {
// Mode is which of the three inputs this is.
Mode Mode
// Side is the side being rendered, which decides whether a one-sided
// field appears. Empty renders every declared field, which is right
// for a form that has only one side (a sub-record panel, a settings
// form, a search form).
Side Side
// Action is the concrete URL the form submits to, with any route
// placeholders already filled. Empty falls back to the declaration's
// Path (or EditPath on the edit side).
Action string
// Method overrides the declaration's method for this render. Empty
// falls back to the declaration's Method (or EditMethod on the edit
// side).
Method string
// Values are the record's or the submission's values.
Values Values
// Errors are the submission's refusals; nil in the other two modes.
Errors *Errors
// Options carry the option sets of the fields whose options are
// loaded per request. The same map is passed to ParseWith, so what
// the control offered and what the handler accepts are one list.
Options map[string][]Option
// Slots carry the first content of a field's declared slot region
// (the product name's duplicate warning at page load).
Slots map[string]template.HTML
// Cells carry a Table-family row's middle cells, keyed by field name,
// in FormSpec.Columns order. The page pre-renders them because what
// they hold is the page's (a source badge, a Not set badge, an
// effective value in a <code>), not the library's (design D21). A
// field with no entry renders empty cells; a family other than Table
// ignores them.
Cells map[string][]template.HTML
// control, in the same cell, keyed by field name; page-owned for the
// same reason Cells is (design D9, typed-config-keys): the integration
// settings page's Clear action and Pending restart badge describe the
// stored override, not the running value, so they render here rather
// than in one of Cells' columns. A field with no entry renders nothing
// extra; a family other than Table ignores it.
ControlFooters map[string]template.HTML
// Instance disambiguates a form rendered more than once on one page: a
// form repeated once per record on a listing (the org-type
// default-change form, once per type's card). It is suffixed onto
// every id the render computes, so a page with several instances
// carries no duplicate DOM id; data-form stays the declaration's own
// name, so the capture and coverage tooling still see one form.
// Wrapper ids stay stable within one instance across its three modes
// (design D11), which is what the contract is for. Empty for a form
// that renders once.
Instance string
// Target overrides the declaration's Target for this render, for a
// form whose swap target is per-instance (the org-type card's id
// carries the type). Empty falls back to the declaration's Target.
Target string
// WayOut overrides the declaration's WayOut for this render, for a
// way out that carries a per-render URL (a preview's Discard re-fetches
// the page it sits on). Nil falls back to the declaration's WayOut.
WayOut *WayOut
// Message is one block of prose rendered inside the section box, above
// the fields: a preview's explanation of what it is about to do, which
// belongs to the whole form rather than to one field (design D10's
// preview idiom), or the lead a stacked form in a panel opens with
// (Issue grant's, grant-resumption D21). Empty for a form with nothing
// to say beyond its fields.
Message template.HTML
// HXSelect and HXSelectOOB narrow a Search form's request to one
// embedded list panel (operator-list-scale's ListNav.Target/SyncSelect):
// HXSelect carves the panel's own markup out of the GET response,
// HXSelectOOB refreshes sibling panels from the same response. Both
// empty for a standalone list's search, which sets Boosted instead
// (form-conventions, "Every mutation form's no-JS behavior is a
// recorded decision").
HXSelect string
HXSelectOOB string
// Body is the caller's own fragment the Rows family renders in place of
// a section box: the table of records whose cells hold the
// declaration's controls (spec form-library "A batch form renders the
// caller's rows and one tray"). A body fragment usually needs the view
// it will sit inside, because its cells call FormView.RowField, so the
// common order is Bind, render the fragment with the view in scope, set
// FormView.Body, render the form part. Setting it here instead is the
// same thing for a body that needs nothing from the view. Refused on
// any other family.
Body template.HTML
// Staged is the batch the tray shows, in the order the tray lists it;
// the index is the delta's identity in the hidden fields the render
// writes and ParseBatch reads back. Refused outside the Rows family.
Staged []StagedDelta
// Rows are the open editors, keyed by the record key the caller passes
// to RowField as the instance. A record with no entry renders at rest,
// which is the caller's own markup and none of the library's business.
// Refused outside the Rows family.
Rows map[string]RowBinding
// Autofocus names the control that takes focus on a successful render
// (design D9; spec form-library "A binding names the control that takes
// focus"). A refusal ignores it and focuses the first invalid control
// instead, as every other family does.
Autofocus Focus
// CommitTarget is the hx-target of the Rows family's commit, which
// applies the batch and therefore usually re-renders more than the form
// region a row action re-renders. Empty falls back to the form's own
// target.
CommitTarget string
// CommitSwap is the hx-swap of that commit; "outerHTML" when empty, as
// it is for every other control of the form. A commit whose target is a
// container the page keeps (an operator body whose response is its
// contents rather than a wrapper) sets "innerHTML" here, because
// replacing the container itself would leave the next request with no
// target to swap into.
CommitSwap string
// Tray renders the tray with no staged delta, for a batch form whose
// tray says something at rest. Empty batch and no Tray renders no tray,
// no commit and no way out.
Tray bool
// Boosted renders a Search form with no explicit htmx attributes at
// all, relying entirely on the page's own hx-boost inheritance for
// both the scripted behaviour and the native no-JS fallback: the right
// choice for a standalone list's own search, whose target is the page
// itself and not a selector this declaration could name. An embedded
// list sets HXSelect/HXSelectOOB instead, never this.
Boosted bool
}
Binding is one render's input.
type CommitLinkView ¶
CommitLinkView is a commit that is a link out of the console (FormView.CommitLink).
type ConfirmTrigger ¶
type ConfirmTrigger struct {
// Label is the button's word ("Revoke").
Label string
// Title, Body and ConfirmLabel are the dialog's title, body and commit.
Title string
Body string
ConfirmLabel string
// URL is where the dialog posts, Target its hx-target.
URL string
Target string
// Fields are posted with the act as hidden fields.
Fields map[string]string
}
ConfirmTrigger is a destructive act a batch form's row offers (FormView.RowConfirm): a button that opens the shared confirm dialog (shell_confirm_modal.html, confirm-action-modal.js), which posts the act itself. The dialog commits it, not this form, so the act carries none of the form's fields.
type Control ¶
type Control string
Control is the closed set of controls the library renders and reads. A form that needs a control this set lacks needs a change to the library, with its rendering and its reading added together, not an improvised template (lessons L§12, L§26).
const ( Text Control = "text" Textarea Control = "textarea" Number Control = "number" Email Control = "email" URL Control = "url" Date Control = "date" DateTime Control = "datetime" Select Control = "select" Checkbox Control = "checkbox" Radio Control = "radio" // Hidden carries an identifier a sub-record form needs (a parent id). // A hidden field is parsed only because it is declared, and the // handler must still check it against the route: the route is the // authority, the field is a convenience (finding FA-10). Hidden Control = "hidden" // Static is a row that states a fact instead of offering a control: it // renders Field.Value as muted text where the control would be, emits // no name, and is never parsed. It exists for the Table family, whose // rows are the whole settings surface and must therefore hold the keys // an operator cannot set here at all (a secret key, set in the // environment): one table, one Save, no second table below it // (design D21). Static Control = "static" )
func (Control) Fraction ¶
Fraction is the control's natural rung: the lowest fraction that holds its widest ordinary value at a laptop width, where one twelfth of the content column is about 80px (design D2). Checkbox, Radio and Static are their own content, not a fraction of the row; Hidden takes no column at all, which is why both resolve to the zero value here and are handled by control alone wherever that distinction matters.
type DeltaView ¶
type DeltaView struct {
Index int
Verb string
Key string
Line template.HTML
Error string
ErrorID string
// Fields are the delta's own controls (Placement PlaceDelta), named
// "staged.<i>.<field>".
Fields []FieldView
// Undo drops this delta from the batch.
Undo RowActionView
}
DeltaView is one staged delta's tray line.
type DisabledControlView ¶
type DisabledControlView struct {
ID string
Label string
Classes string
Reason string
Visible bool
}
DisabledControlView is the shape the shared disabledControl part reads (internal/server.DisabledControl carries the same fields; internal/forms cannot import internal/server, which imports it, so this is the same shape declared on this side of the boundary). Set on FormView.CommitState to gate a preview's commit on a precondition the declaration cannot check itself (design D10; org-types "The commit waits for dispositions").
type Errors ¶
type Errors struct {
// contains filtered or unexported fields
}
Errors is one form's refusals: a message per field, plus the form-level message for a refusal that belongs to no field. The form-level slot is reached by the same call with an empty field name (lesson L§11).
func (*Errors) Any ¶
Any reports whether anything was refused. This is the handler's branch point: build the domain object only when it is false.
func (*Errors) Field ¶
Field records a refusal under one field. The last message wins: the convention is one concise message per field, not a list.
type Family ¶
type Family string
Family is the layout, of which there are five and no sixth (design D10, D20, D21; D1 of staged-rule-changes added the fifth). Kind says what a form is for; family says how it is laid out, and the pairing is fixed: the declaration names both so the registry table and the docs read the same way, but the choice is not the declaring file's to make (FamilyFor, and the invariants that hold every declaration to it).
- Stacked: one control per row, labels above, in a section box capped at a readable width; create pages, edit forms, previews, the confirm modal.
- Dense: one row of small controls with the commit at its end; sub-record panels only.
- Bar: one input group with a leading magnifier, the control, the outline commit and the way out; searches only. Round 3 forced a search into Stacked and every list page rendered a narrow input with its button wrapped onto the next line (maintainer, 2026-09-04).
- Table: one table row per field, the label and its hint in the first column, the page's own pre-rendered cells next, the control last; settings only. Round 3 forced settings into Stacked and both settings pages lost the effective value, the source and the status the table had carried.
- Rows: the caller's own table of records as the form's body, the declaration's controls rendered into the caller's cells through the field part, and one tray under the table at the body's width holding the staged batch and the commit; batch forms only. A Table's rows are fields, one per row; a Rows body's rows are records, each carrying several of the declaration's fields. A form that declares RowCommit has no tray: one row edits at a time and carries its own commit.
type Field ¶
type Field struct {
// Name is the submitted name. It is stable and never prefixed: the
// data-form id namespaces the DOM ids instead.
Name string
// Label is the visible label. Every control has one; in a dense row
// with no room it renders visually hidden, never absent (FA-51).
Label string
// HideLabel renders the label visually hidden, which the part honours
// in a dense row and in a bar only, the two families with no room for
// one. An aria-label never substitutes for a label.
HideLabel bool
// Control is the control this field renders and is read as.
Control Control
// Options are a select's or a radio group's entries. A form whose
// options are loaded per request declares RuntimeOptions instead and
// supplies them at render and at parse.
Options []Option
// RuntimeOptions declares that this select's or radio group's options
// come from the request (an entitlement-set picker, a product picker),
// so the invariants accept an empty Options and Parse is given the set
// through ParseWith.
RuntimeOptions bool
// Hint is one short line under the control. It survives an error
// (GOV.UK's side of the split; findings FA-48, FA-49). A field carries
// a Hint or a Notice, never both: one visible line under a control is
// the whole budget, and a second line reads as clutter (maintainer,
// 2026-09-03: "Can we remove all additional obvious text that doesn't
// need to be there?"). A dense row carries neither; its explanation
// goes behind the help icon.
Hint string
// HintOnChoice makes this select's Hint wait for a choice: the line
// renders only when an option the select offers has ShowsHint, hidden
// until such an option is chosen, and shown on a refused submission
// that chose one. The select names the hint it controls
// (data-hint-toggle), and hint-on-choice.js, which the operator shell
// loads, follows later choices. The field declares the Hint it shows
// and no Notice. An option that carries ShowsHint can carry its own
// Option.Hint, which the line shows in place of the declared Hint while
// that option is chosen; the declared Hint is then also the line's
// default (data-hint-default).
HintOnChoice bool
// Notice is the one-sidedness a person would otherwise be surprised
// by, as one line under the control: a create-only value that cannot
// be changed later, say. It is not the default for a one-sided field.
// Most differences are self-explanatory once the field is simply
// absent from the other side, and saying so out loud is the
// superfluous text the maintainer struck (2026-09-03).
Notice string
// Help is the click popover after the label.
Help HelpIcon
// Placeholder is a format example only, never a label, a state or an
// instruction (finding FA-35). The invariants refuse a sentence.
Placeholder string
// Optional marks the label with the "(optional)" suffix and lets an
// empty value through. On a select, requiredness is carried by the
// option set instead: an empty value is accepted exactly when an
// option with an empty value exists, so a select's Optional only
// governs the label's marker. On a radio group, by contrast, Optional
// governs the required attribute and Parse's requiredness check
// directly, like every other control except Select: a radio group has
// no "choose nothing" member the way a Select's enabled empty option
// does, so there is no equivalent convention available to carry the
// fact (fieldAttrs and the Select/Radio membership check in parse.go
// both give Radio its own case for this reason).
Optional bool
// MaxLen caps the value's length; it renders as maxlength and Parse
// refuses a longer value, so the browser's rule and the server's rule
// cannot differ.
MaxLen int
// Min and Max bound a number, a date or a date-time. They render as
// the min and max attributes and Parse applies them.
Min, Max string
// Step is a Number field's granularity ("0.01" for a currency amount),
// rendered as the step attribute. Parse does not apply it: a step
// mismatch is cosmetic (the constraint attribute is a convenience,
// never the control, design D2), and the amounts this library reads
// are already integer-cents or otherwise range-checked by the
// handler's own domain rule.
Step string
// Pattern is a regular expression the value must match, rendered as
// the pattern attribute and applied by Parse. PatternHint is the
// refusal's message, because a regular expression is not an error
// message.
Pattern string
PatternHint string
// Inputmode is the virtual keyboard hint (numeric, decimal, email).
Inputmode string
// Autocomplete is a real autofill token (name, email, url,
// organization) or "off" for keys, search boxes and one-time values.
// The part emits it from here and from nowhere else, and never writes
// it on the form tag (finding FA-52).
Autocomplete string
// Rows is a textarea's height in lines; 3 when unset.
Rows int
// Value is a checkbox's submitted value when it is ticked ("public",
// "true"). "true" when unset. A checkbox's absence always reads as
// false, and the invariants refuse a required checkbox. On a Static
// field it is instead the sentence the row states where its control
// would be, and nothing is submitted at all.
Value string
// Width steps the field's column one rung from its control's natural
// fraction (design D2); ignored when stacked. The zero value is the
// control's own rung.
Width Width
// Only names the side this field exists on. It carries no
// justification string: no surveyed framework does (Django's
// add_fieldsets and Filament's hiddenOn declare the side and nothing
// else), and a reason nothing renders and nothing reads is noise in
// the registry (maintainer, 2026-09-04). Why a field is one-sided is
// a Go comment beside the declaration, like any other comment; what a
// person needs to be told is a Notice.
Only Side
// Slot renders an empty container after the control, with the id
// "<wrapper id>-<Slot>", for a region a scoped htmx request swaps into
// (the product name's duplicate warning), or for a line the handler
// decides per render (the product's Entitlement set). The render
// supplies its first content through Binding.Slots.
Slot string
// ShowIf makes this field's rendering and parsing conditional on
// another field's bound value (the entitlement-set rule form's Limit
// and "Per unit" fields depend on the selected resource key's kind;
// design D2, entitlement-set-management "the kind-dependent shape
// SHALL be a declared field set"). The zero value
// always shows. The condition reads Values, not the database: a
// handler that derives visibility from data the library cannot see
// (a resource key's kind) writes that derived value into a Values
// entry itself, typically a Hidden field the render fills in, so the
// same submitted state governs the next render and the next parse
// (see ShowIf's doc for the trust model).
ShowIf ShowIf
// Placement is where a Rows form renders this field: with the record's
// row (the zero value, rendered by the caller's body), on a staged
// delta's tray line, or once in the tray before the commit. Ignored,
// and refused by the invariants, in every other family.
Placement Placement
// Attrs is the one escape hatch: data-* and hx-* keys only, and never
// a key the part owns. Anything else fails the invariants.
Attrs map[string]string
}
Field is one control's whole declaration: what it submits, what it says, how it is read, and where it exists. Nothing about a field lives in a template, and nothing a template would need is left undeclared.
func GrantNote ¶
func GrantNote() Field
GrantNote is the note written with a grant, by Issue grant and by Manage alike; the text is the grant's note, the column upstream is called description. The explanation rides the help icon after the label rather than a hint: Manage puts the control in the grant's own Reason cell, where a line under it would lengthen the row, and Issue grant, which was a dense row until it became stacked (grant-resumption D21), keeps the one field's one wording. Optional because grants.description is a nullable column (00001_init.sql) and pre-existing deliveries carry no description at all; an extension with no note and no expiry is a legitimate, complete submission, not a refused one (a lesson the DB-backed suite caught before this was corrected: TestManageGrant_SucceedsForSinglePoolOrg and TestGrantsListDeliveryStateAgreesWithGoDerivation both submit with the field absent and expect success).
func GrantValidUntil ¶
func GrantValidUntil() Field
GrantValidUntil is the optional end of a grant, on both grant forms. One label, because the two forms wrote one column under two names ("Valid until" and "Expires at") before this change.
func RecordDescription ¶
func RecordDescription() Field
RecordDescription is the optional prose under a catalog record's name. The same column on three records carried three markings before this change (finding FA-4); it carries one now.
func RecordName ¶
func RecordName() Field
RecordName is the name of a catalog record: a product, an entitlement set, a plan ladder. Required on every one of them, with no marker, because required is the default and only optional is marked.
func (Field) CheckboxValue ¶
CheckboxValue is the value a ticked checkbox submits.
func (Field) On ¶
On returns a copy of f declared for one side, so a shared field value can be included by reference and still exist on one side only (design D3, D8).
func (Field) RendersOn ¶
RendersOn reports whether the field renders in the given mode. A submission re-renders the side it was submitted from, which the binding carries.
type FieldView ¶
type FieldView struct {
Name string
Label string
Control Control
// InputType is the type attribute for the controls that are inputs.
InputType string
// LabelHidden renders the label visually hidden, for a dense row or a
// bar with no room for it. The label is never absent (finding FA-51).
LabelHidden bool
// LabelNarrowOnly renders the label d-lg-none: a Rows body's editing
// cells stack below lg, where the column headers that label them are
// off to the side, and hide their own labels again from lg up where the
// headers do the work (design D11). Set by the label-hidden option of
// FormView.RowField, and false everywhere else.
LabelNarrowOnly bool
// LabelAbove renders a checkbox's label above the box, as every other
// field's label sits, with its help icon after it and nothing beside
// the box (grant-resumption D19). Set for a checkbox in the Stacked and
// Dense families; a Rows cell keeps its label beside the box, and the
// Table family places the label in its own column.
LabelAbove bool
// Optional renders the "(optional)" suffix after the label. A bar and
// a table never do: their fields are optional by nature, so the marker
// states nothing (design D20, D21).
Optional bool
// WrapperID is the stable per-field id, "form-<spec>-<field>", so
// inline validation can be added later without rewriting the DOM
// (lessons L§18, L§19).
WrapperID string
// ControlID is what the label points at.
ControlID string
// ColClass is the dense row's grid column; empty in every other family.
// Small renders the -sm control a dense row and a table row use.
ColClass string
Small bool
Value string
// Checked is a checkbox's state; CheckboxValue is what it submits.
Checked bool
CheckboxValue string
Placeholder string
Rows int
Options []OptionView
Radios []RadioView
Help HelpIcon
Hint string
HintID string
// HintHidden renders the hint with the hidden attribute: a
// HintOnChoice field whose chosen option does not show it.
HintHidden bool
// HintDefault is the declared hint of a HintOnChoice field one of whose
// options carries its own hint, rendered as data-hint-default so
// hint-on-choice.js can restore it; empty otherwise.
HintDefault string
Error string
ErrorID string
// Cells are the Table family's middle cells for this row, in the
// declaration's Columns order, pre-rendered by the page
// (Binding.Cells). Empty in every other family.
Cells []template.HTML
// control, in the control's own cell, pre-rendered by the page
// (Binding.ControlFooters). Empty in every other family, and for a
// field with nothing to show there.
ControlFooter template.HTML
// Notice is the declared line under the control for a one-sidedness a
// person would be surprised by, and NoticeID is what the control's
// aria-describedby names it by. A one-sided field says nothing about
// its side unless it declares a Notice.
Notice string
NoticeID string
// SlotID and SlotHTML are the field's declared live region.
SlotID string
SlotHTML template.HTML
// Attrs carries every attribute derived from the declaration:
// required, maxlength, min, max, pattern, inputmode, autocomplete,
// aria-describedby, aria-invalid, autofocus, and the data-* and hx-*
// escape hatch. Built here so a template cannot write one by hand and
// the browser's constraints and the server's rules cannot differ.
Attrs template.HTMLAttr
}
FieldView is one rendered field: everything the formField part writes.
type Focus ¶
type Focus struct {
// Field is the declared field's name.
Field string
// Instance is the row key the field renders under, or "staged.<i>" for
// a delta's own control. Empty names a field the library renders once
// (a tray field).
Instance string
// Tray focuses the tray's message region instead of a control; the
// region renders tabindex="-1" so it can take focus at all.
Tray bool
// Act and Key name a posting control instead of a control that carries
// a value: the row's own Edit after a Cancel, say, so focus returns to
// the button the person pressed to open the editor rather than falling
// to the top of the swapped region.
Act string
Key string
}
Focus names the control a successful render gives focus to (design D9). The zero value focuses nothing, which is what every render did before this existed.
type FormSpec ¶
type FormSpec struct {
// Name is the data-form id and the registry key, unique across the
// console, e.g. "operator.product".
Name string
// Kind decides the outcome contract and the capture behaviour.
Kind Kind
// Family decides the layout.
Family Family
// Method and Path are the route the form submits to. For a form whose
// create and edit sides are different routes, Path is the create
// route and EditMethod and EditPath are the record's.
Method string
Path string
// EditMethod and EditPath are the record-bound side's route when it
// differs from Method and Path (a create form posts to the
// collection, an edit form puts to the record). Empty when the form
// has one route. Both are route patterns; the render is given the
// concrete URL.
EditMethod string
EditPath string
// Fields is the ordered field list; the order is the render order.
Fields []Field
// Commit is the commit button's label. CommitEdit is the record
// side's label when it differs ("Create product" against "Save
// changes"); empty means both sides commit under one label.
Commit string
CommitEdit string
// WayOut is how the form is left without submitting it, on the create
// side. The record side never carries one: an always-open edit form
// leaves nothing by cancelling, so the part renders none there
// whatever the declaration says (spec form-conventions "A form's way
// out follows its container"; finding FA-19).
WayOut WayOut
// Target is the swap target; "this" (the form's own outer element)
// when unset. Swap is the swap strategy; "outerHTML" when unset.
Target string
Swap string
// Wide drops the Bar family's width cap, so the bar spans its content
// column instead of stopping at 30rem: for a search that is its page's
// primary control and whose width should say so (the landing surface's
// lookup). Bar only.
Wide bool
// Columns are the Table family's middle columns, in order: the headings
// of the cells the page supplies per row through Binding.Cells (for
// integration settings, "Effective value" and "Source"). The badges
// those cells hold belong to the page, not to the library, which is why
// they arrive pre-rendered. Table only.
Columns []string
// LabelColumn and ControlColumn are the Table family's first and last
// column headings; "Field" and "Value" when unset. Table only.
LabelColumn string
ControlColumn string
// CommitAction is the path the Rows family's commit posts to, which is
// not the path its row actions post to: every row action, Undo and the
// way out re-render the form's own region from Path, while the commit
// applies the batch and re-renders whatever the page's commit renders
// (design D2). Batch forms only, and required on one. On a form that
// declares RowCommit it is the record's route pattern, which each open
// row's binding fills in for its own commit (RowBinding.Action).
CommitAction string
// RowCommit makes a batch form commit one record at a time instead of
// applying a staged batch (grant-resumption D15, the grants ledger's
// Manage): nothing is staged and there is no tray, at most one row
// edits at a time, and that row's own commit, which the body renders
// through FormView.RowCommit, posts the row's fields to the record's
// route and re-renders whatever the page's commit renders. The row
// actions still post to Path and re-render the form's region, so opening
// a row and cancelling it write nothing. Batch forms only.
RowCommit bool
// MessageAfter names the field the render's Message follows, for a
// preview whose message is the consequence of one control and reads
// wrong above it (the org-type card; maintainer, 2026-09-04: "The
// following text appears above the form element instead of below
// it"). Empty puts the message before the fields, which is right for a
// preview whose narrative introduces the choice. Preview only.
MessageAfter string
}
FormSpec is one form. It is declared once, rendered in three modes, and parsed through in the handler, so a field the handler reads and no template renders cannot exist.
func Register ¶
Register indexes one form. A duplicate name panics at boot, because two forms answering to one name would make every derived check ambiguous. Registration is idempotent for an identical re-registration, so a handler constructed twice in one process (a test set beside the real one) does not bring the process down.
func (FormSpec) Bind ¶
Bind renders this declaration against one binding. It is Render written as a method, so a caller that must hold the view before it can render the body it hands back (the Rows family: the body fragment calls RowField on the view) reads as one expression.
func (FormSpec) Parse ¶
Parse reads r through the declaration and returns the values and the refusals. It reads r.PostForm for a mutation and r.URL.Query() for a search form, never r.FormValue, so the query string cannot shadow a body field. Repeated names on a scalar field take the first value, as Go's own form parsing does; a multi-valued control does not exist.
func (FormSpec) ParseBatch ¶
ParseBatch reads a batch form's request through its declaration.
func (FormSpec) ParseBatchWith ¶
ParseBatchWith is ParseBatch with the option sets of the fields whose options are loaded per request, exactly as ParseWith is to Parse: a submitted value outside a field's options is a refusal. A batch form whose select offers a per-record option (a stored value the console offers back rather than writes) passes every value it ever renders here, because one request carries every row and every delta at once.
func (FormSpec) ParseSide ¶
func (s FormSpec) ParseSide(r *http.Request, side Side, options map[string][]Option) (Values, *Errors)
ParseSide is ParseWith restricted to the fields that render on one side, so a create submission cannot carry an edit-only field and an edit submission cannot carry a create-only one. The side the form rendered is the side it is read as; BothSides reads every declared field, which is right for a form with one side.
type FormView ¶
type FormView struct {
Name string
// ID is the outer element's id, "form-<name>".
ID string
Kind Kind
// Dense, Bar, Table and Rows report the layout family, so the part can
// pick its shape; all four false is Stacked (design D10, D20, D21, and
// D1 of staged-rule-changes).
Dense bool
Bar bool
Table bool
Rows bool
// Wide drops the bar's width cap (FormSpec.Wide). Bar only.
Wide bool
// Columns, LabelColumn and ControlColumn are the Table family's
// headings: the label column first, the declaration's Columns next,
// the control column last.
Columns []string
LabelColumn string
ControlColumn string
Fields []FieldView
Commit string
WayOut WayOutView
// FormError is the refusal that belongs to no field. Its slot renders
// on every form and is empty when unused, so a refusal without a
// field name always has somewhere to land (findings FA-22, FA-26).
FormError string
FormErrorID string
// Native reports a search form, which renders a real method and
// action and keeps a true no-JavaScript fallback (spec
// form-conventions "Every mutation form's no-JS behavior is a
// recorded decision").
Native bool
// Method and Action are the native attributes, set when Native.
Method string
Action string
// NoValidate emits the form's `novalidate` attribute, so the refusal a
// person sees is the server's, rendered under the control, and not
// the browser's transient bubble (maintainer, 2026-09-03: pressing
// Save on a cleared name produced no feedback at all).
NoValidate bool
// Box names the section box the part renders around the form (spec
// form-library, "The form part owns the container"): "card" for a
// create page or an edit form, "preview" for the preview idiom's box
// (design D10), which wears the preview tone, and empty for a dense sub-record row, whose panel
// is already its box, for a bar, which sits in a list's header, and
// for a settings table, which is its own shape. A stacked box is capped at the
// readable measure and hugs its fields, so the box ends where the
// fields end rather than running the width of the content column
// (maintainer, 2026-09-04: "Hugging definitely").
Box string
// HX carries the htmx attributes: the verb and its path, the target,
// the swap, and hx-disable on the commit so a double submit is
// impossible (finding FA-20).
HX template.HTMLAttr
// Target is the resolved hx-target (the declaration's, or Binding.
// Target), for a WayOutDiscard button to reuse as its own hx-target
// and hx-select: it re-fetches the page that owns this target and
// carves the same region back out.
Target string
// CommitState, when non-nil, replaces the ordinary submit button with
// the shared disabled-control idiom: a preview whose commit waits on a
// precondition the declaration cannot itself check (design D10;
// org-types "The commit waits for dispositions"). Nil renders the
// ordinary enabled commit. Its Classes are the render's, never the
// caller's: the part reads them through CommitControl, which overwrites
// whatever was set with the classes the enabled commit would carry, so
// a disabled commit and the way out beside it are the same height in
// every state (design D23).
CommitState *DisabledControlView
// CommitLink, when non-nil, replaces the ordinary submit button with a
// link that leaves the console, at the weight and size the submit would
// have: a preview whose next step is a page another service hosts (a
// payment the member approves on Stripe's invoice page). It opens in a
// new tab, so the console stays where the member left it. Nil renders
// the ordinary commit; CommitState, when also set, wins.
CommitLink *CommitLinkView
// CommitDescribedBy is the id of an element outside the form that
// states a fact about what committing does, such as who bills the
// charge. The part writes it as aria-describedby on the enabled submit
// button and on a CommitLink, never on a CommitState, whose disabled
// control is described by its own reason. Empty writes nothing.
CommitDescribedBy string
// CommitHidden renders no commit row at all, neither the commit nor
// the way out: a Preview form at rest has nothing to apply and nothing
// to discard, so it shows only its fields until a choice produces a
// message (design D23; maintainer, 2026-09-04: Discard with nothing to
// discard).
CommitHidden bool
// WayOutOnly renders the commit row with the way out alone and no
// commit, for a Preview form whose change cannot be applied: the act
// is certain to refuse it, or the preview could not read its outcome.
// It wins over CommitState and CommitLink; CommitHidden wins over it,
// because that suppresses the whole row.
WayOutOnly bool
// Message is prose rendered inside the section box (Binding.Message's
// doc), before the fields, or after the field MessageAfter names.
Message template.HTML
// MessageAfter is the field name the message follows
// (FormSpec.MessageAfter). Empty puts the message before the fields.
MessageAfter string
// MessageID is the message region's id. Every other kind renders the
// region only when Message is set; a Confirm form renders it always,
// empty at rest (app.css collapses an empty one), because
// confirm-action-modal.js writes each trigger's body text into it after
// the page has already loaded (design D4's Confirm kind; task 5.6).
MessageID string
// Danger reports a Confirm form's commit, which renders btn-danger by
// default rather than btn-primary (design D12: "A destructive commit
// renders btn-danger only inside the confirm modal"). The JS
// (confirm-action-modal.js) still reassigns the class per trigger on
// every open, as it does today; this is only the rendered default.
Danger bool
// The Rows family's own view (design D1's "Rows family contract"). Body
// is the caller's table, settable after Bind because the fragment that
// produces it calls RowField on this view; everything else the library
// builds.
Body template.HTML
// Hiddens are the open editors' keys and the staged batch, as hidden
// inputs the part writes and ParseBatch reads back.
Hiddens []HiddenInput
// Deltas are the tray's lines, one per staged delta.
Deltas []DeltaView
// Tray reports whether the tray renders at all: an empty batch with no
// Binding.Tray renders no tray, no commit and no way out, and a form
// that commits row by row never renders one.
Tray bool
// TrayFocus renders the tray's message region focusable and focused,
// for the render that follows a staging or an undo (design D9).
TrayFocus bool
// Apply and Discard are the tray's commit and way out, emitted through
// the same row-action part as every other posting control of the form.
Apply RowActionView
Discard RowActionView
// contains filtered or unexported fields
}
FormView is the whole rendered form: what the form part writes.
func (FormView) CommitClasses ¶
CommitClasses are the commit button's classes: filled by default, btn-danger inside the confirm modal, outline in a bar (a search is not a commit, so every bar's button is outline, the landing surface's "Look up" included; design D20), and btn-sm only in a dense row.
func (FormView) CommitControl ¶
func (v FormView) CommitControl() *DisabledControlView
CommitControl is the disabled commit the part renders in place of the submit button, with the classes the enabled commit would have carried (design D23): the caller declares the id, the label and the reason; the weight and the size are the family's, so Apply change and Discard are the same height whether the commit is live or waiting.
func (FormView) FormErrorNotice ¶
FormErrorNotice is the form-level refusal as a Problem notice, which the form part renders in the error slot; it is empty when the form has no form-level refusal.
func (FormView) HasErrors ¶
HasErrors reports whether this render carries any refusal: a field error or the form-level error. A page uses it to force a collapsed sub-record panel open, so a refused submission's errors are never hidden behind a closed panel (design D9).
func (FormView) RowAction ¶
func (v FormView) RowAction(act, key, label, variant string) RowActionView
RowAction returns one of a row's posting controls, for the caller's own cell to render through the row-action part. Every one of them posts the whole form to the declaration's path, carrying the act, the row's key, every open editor's values and the whole staged batch, and swaps the form's own region back (design D2). The variants are primary, secondary and danger; secondary and danger render outline, because solid secondary is not in the console's palette and a row's Remove stages a change rather than making one.
func (FormView) RowBox ¶
func (v FormView) RowBox(instance string, fields ...string) RowBoxView
RowBox returns the Rows family's add form for the part that renders it (the formRowBox part): a batch body uses it when its add row does not fit one desktop line, which a dense row may not exceed (form-conventions). The fields are the named row fields of the instance, in the order named, each with its label above its control (a checkbox's included) and at full size; the actions are Stage change, which posts the "stage" act, and Cancel, which posts "cancel", both at full size, as the Stacked family's commit is. The box is the part's, so the page writes no card of its own.
func (FormView) RowCommit ¶
func (v FormView) RowCommit(key string) RowActionView
RowCommit returns the commit of the row a form that commits row by row has open (FormSpec.RowCommit), for the caller's own cell to render through the row-action part: the declaration's commit label, posting the form, which holds that one row's fields and nothing else, to the row's own Action, and swapping what the binding's CommitTarget and CommitSwap name, as a tray's commit does. It carries the in-flight indicator and disables itself, the one control of the row a double press could apply twice.
func (FormView) RowConfirm ¶
func (v FormView) RowConfirm(key string, t ConfirmTrigger) RowActionView
RowConfirm returns a row's destructive act, for the caller's own cell to render through the row-action part: an outline-danger button labelled by the trigger, opening the shared confirm dialog with the trigger's words, route and hidden fields. The dialog posts the act, so the button posts nothing and carries none of the form's fields (a grant's Revoke in its editing row, grant-resumption D9).
func (FormView) RowField ¶
RowField returns one field of one record's row, for the caller's own cell to render through the field part: the declaration's label, its constraint attributes and its error wiring, under a name and a wrapper id that carry the row. The values and the refusals are that row's (Binding.Rows), so a refused staging renders every open editor's own text back.
Options. "label-hidden" renders the label d-lg-none: the column header labels the cell from lg up, and below lg, where the cells stack, the label is the only thing that does (design D11). "dense" is for a field the body lays out in a dense row of its own beside its table (design D8 of staged-rule-changes): the wrapper takes the dense family's grid column from the control's rung and the declared Width; its error renders under the control as everywhere, and the row aligns to the top so a refused column grows alone (design D16). "inline" and "inline-fill" are for a field the body lays out in a card of its own under the record's row (a grant's Manage, grant-resumption D9): the label shows at every width, a checkbox's above its box, and the wrapper is a flex item of app.css .app-inline-fields, one line from the large breakpoint up and one per line below it; "inline-fill" takes the line's free width. A body whose add row does not fit one desktop line lays it out through RowBox instead, which is not an option of this method.
func (FormView) RowOpener ¶
func (v FormView) RowOpener(act, key, label, variant string, expanded bool) RowActionView
RowOpener returns a row's posting control that owns a panel under the row (a grant's Manage card, grant-resumption D9): a RowAction that carries the shared opener glyph and reports aria-expanded, so the control states whether its panel is open. Closed, act is the act that opens the panel; expanded, the same control stays in its cell and posts the act that closes it, so opening the panel does not empty the cell and reflow the table's columns. The expanded control never takes autofocus: it shares its act and key with the panel's own way out, and only one of them may carry the attribute.
type Fraction ¶
type Fraction int
Fraction is a field's column in a dense row: one of five fractions of the twelve-column grid that divide it evenly, held as an ordered ladder from FractionSixth to FractionFull (design D1). The zero value, FractionNone, is not a rung on the ladder: it names a control with nothing to step from (a hidden field's no column; a checkbox's, a radio group's and a static value's own content).
func FieldFraction ¶
FieldFraction resolves a field's rung from its control's natural fraction and its declared Width, and reports whether the result stays on the ladder (design D2). ok is false when c has nothing to step from (hidden, checkbox, radio, static and textarea all stand on no rung for this purpose, a textarea's full row being the control's own rather than a step), when a narrower step would leave the ladder below a sixth, or when a wider step would reach a full row.
func (Fraction) ColClass ¶
ColClass is the dense row's grid class for this fraction (design D3, D5): below the extra-large breakpoint every field takes its own line, and the fractions apply from 1200px, where the content column beside the sidebar is wide enough for them. The zero value renders no class; a content column (checkbox, radio, static) is col-12 col-xl-auto instead, decided by control rather than by fraction.
type HelpIcon ¶
HelpIcon is the click-opened popover the shared helpIcon part renders after a field's label, as its sibling and never inside the label (findings FA-37, FA-50). Its field names match the part's pipeline, so a forms.HelpIcon is passed to {{ template "helpIcon" ... }} directly.
type HiddenInput ¶
HiddenInput is one name and value the Rows family writes out so a request carries the whole page state: the open editors' keys and the staged batch. The part writes them from here and composes no name of its own.
type Kind ¶
type Kind string
Kind decides a form's outcome contract (design D9) and what the capture utility does with it (design D16): create, edit, sub-record and settings forms are submitted empty for the refusal capture; search, preview and confirm forms are never submitted, because they navigate or mutate.
const ( KindCreate Kind = "create" KindEdit Kind = "edit" KindSubRecord Kind = "sub-record" KindSettings Kind = "settings" KindSearch Kind = "search" KindPreview Kind = "preview" KindConfirm Kind = "confirm" // KindBatch is a table of records edited in place: the declaration's // fields are one row's, the caller's table is the form's body, and a // staged batch of changes is applied by one commit in a tray under the // table (design D1, staged-rule-changes), or, on a form that declares // RowCommit, one open row is committed by its own Save (grant-resumption // D15). It is never submitted empty by the capture utility, because its // commit applies a batch, or a row, that an empty submission does not // have. KindBatch Kind = "batch" )
func (Kind) ServerValidated ¶
ServerValidated reports whether the form's refusal is the server's, and only the server's. The part emits `novalidate` on these, so pressing the commit with an empty required field reaches the handler and swaps back the 422 with the message under the control, rather than stopping at the browser's transient bubble, which cannot be captured, cannot be styled, disappears on the next keystroke, and says nothing the server's own message does not (GOV.UK Frontend does the same). The constraint attributes stay on the controls for assistive technology and for :invalid styling; they are a convenience, never the control.
A Search form keeps the browser's validation, because it navigates rather than refusing, and a Confirm form has nothing to validate.
func (Kind) Submittable ¶
Submittable reports whether the capture utility submits a form of this kind empty to photograph its refusal (design D16).
type Mode ¶
type Mode string
Mode is which of the three inputs a render carries.
const ( // ModeUnbound is a create page: defaults only, no values, no errors. ModeUnbound Mode = "unbound" // ModeRecord is an edit form bound to a record: the record's values // and no errors. An edit form never opens showing errors (L§6, L§7). ModeRecord Mode = "record" // ModeSubmission is a 422: the raw submitted strings and every error. ModeSubmission Mode = "submission" )
type Option ¶
type Option struct {
Value string
Label string
Disabled bool
// ShowsHint marks an option whose choice shows its select's hint
// (Field.HintOnChoice); it renders as data-shows-hint.
ShowsHint bool
// Hint is the line an option that carries ShowsHint shows in place of the
// select's declared Hint while it is chosen; it renders as data-hint and
// is read only with ShowsHint.
Hint string
}
Option is one entry of a select or a radio group.
func ChooseOption ¶
ChooseOption is the first option of a select whose value must be chosen: disabled, selected, empty-valued, so the form cannot submit a value the person never chose (spec form-conventions "A select that needs a choice opens with a placeholder option"). thing completes "Choose ...", so pass "an entitlement set" or "a product".
func NoneOption ¶
func NoneOption() Option
NoneOption is the first option of an optional select: an empty value the person may deliberately choose, which is how a select unsets a column.
type OptionView ¶
type OptionView struct {
Value string
Label string
Disabled bool
Selected bool
// ShowsHint renders data-shows-hint on the option.
ShowsHint bool
// Hint renders data-hint on the option: the line it shows in place of the
// declared hint. It is set only for an option that carries ShowsHint.
Hint string
}
OptionView is one rendered option.
type Placement ¶
type Placement string
Placement is where in a Rows form a field renders (design D1's "Rows family contract"). It is meaningless in every other family, and the invariants refuse anything but the zero value outside a batch form.
const ( // PlaceRow is the zero value: a field of one record's row, rendered by // the caller's own body through FormView.RowField. PlaceRow Placement = "" // PlaceDelta renders the field once per staged delta, on that delta's // tray line, with the delta's index as its instance: a decision whose // consequence is in view only once the change is staged (the rule // change's reduction policy). PlaceDelta Placement = "delta" // PlaceTray renders the field once in the tray, before the commit: the // batch's own field rather than any record's (the note). PlaceTray Placement = "tray" )
type RowActionView ¶
type RowActionView struct {
Act string
Key string
Label string
Variant string
// Classes are the button's classes, decided by the variant.
Classes string
// Indicator renders the in-flight spinner inside the button; a commit
// carries one, a row action does not.
Indicator bool
// Opener renders the shared opener glyph before the label and reports
// aria-expanded, for a control that owns a panel (FormView.RowOpener);
// Expanded is that attribute's value.
Opener bool
Expanded bool
// HX carries the control's behaviour: hx-post, hx-vals, hx-include,
// hx-target and hx-swap on a posting control, or the confirm dialog's
// data-* attributes on a destructive act, built here so no template
// composes a control by hand.
HX template.HTMLAttr
}
RowActionView is one control of a batch form: a row's Edit or Remove, a delta's Undo, the commit, the way out, a row's own commit on a form that commits row by row, and a row's destructive act. Every posting one of them posts the whole form, so each request carries every open editor's values and the whole staged batch (design D2); the destructive act opens the shared confirm dialog, which posts the act itself.
type RowBinding ¶
type RowBinding struct {
Values Values
Errors *Errors
// Options are this row's runtime option sets, keyed by field name, for a
// control whose choices depend on the record (the rule row's policy
// select offers a dormant stored value as its own option). A field with
// no entry here falls back to Binding.Options.
Options map[string][]Option
// Action is the concrete URL this row's own commit posts to, the
// declaration's CommitAction filled in for the record, on a form that
// commits row by row (FormSpec.RowCommit). Required there, and refused
// on a form that applies a staged batch, whose commit is the tray's.
Action string
}
RowBinding is one open editor: the values its controls carry and the refusals on them, keyed by the declaration's bare field names.
type RowBoxView ¶
type RowBoxView struct {
Fields []FieldView
Actions []RowActionView
}
RowBoxView is a batch body's add form as a Stacked section box: the named fields of one row, one control to a line, and the row's two actions.
type ShowIf ¶
type ShowIf struct {
// Field is the name of the field this condition reads.
Field string
// Equals is the set of that field's raw values for which this field
// is shown; empty Field means always shown.
Equals []string
}
ShowIf names another declared field and the raw values it must carry for this field to render and be parsed. It is the library's answer to "the field set depends on a value" (design D2): a small, general mechanism, not a rule form's private hack, so any future form with the same shape (a picker whose choice reveals different fields) can declare it too.
The condition is checked against Values, which Parse builds field by field in declaration order: a field referenced by another field's ShowIf must therefore be declared earlier in Fields. The referenced field need not itself be visible to the operator; a Hidden field the render sets from server-derived data (never from user choice) is the common case, and the trust model follows from that: whatever governs visibility is exactly what was rendered, so it is self-consistent across a refused resubmission, but it is never authoritative for a domain decision (the entitlement-set rule's actual type is still re-derived from the database, never read back from this field) because the value did round-trip through the client.
type Side ¶
type Side string
Side names the render side a field exists on. A field that exists on one side only declares that side and a reason, and the part renders the reason as one short line at the field on the side where it exists (design D8; spec form-conventions "Create and edit forms agree or disclose their difference").
type StagedDelta ¶
type StagedDelta struct {
// Verb is the caller's word for what this delta does ("add", "edit",
// "remove").
Verb string
// Key is the record key: a record's identifier, or the caller's own
// name for a record that does not exist yet.
Key string
// Values are the delta's field values, keyed by the declaration's bare
// field names. A field the tray renders as a control (PlaceDelta)
// renders from here; every other declared field present here rides as a
// hidden input, so the whole batch survives every request.
Values Values
// Line is the delta's narrative on its tray line, rendered by the
// caller: the library knows verbs and keys, not what a change means.
Line template.HTML
// Error is a refusal on this delta, rendered on its line with the rest
// of the batch intact (design D3: every request re-validates the batch).
Error string
// Options are this delta's runtime option sets, keyed by field name,
// for a control whose choices depend on the record (the rule change's
// policy select offers a dormant stored value as its own option).
// A field with no entry here falls back to Binding.Options.
Options map[string][]Option
}
StagedDelta is one staged change to one record: what the tray lists, what the hidden fields carry, and what ParseBatch reads back (design D1's "Rows family contract", D3). Verb and Key are opaque to the library: it writes them out, reads them back, and never interprets either.
type Values ¶
type Values struct {
// contains filtered or unexported fields
}
Values holds one form's values: the raw submitted string, whether the name was present at all, and the typed value where the field's rules passed. Go cannot tell an absent string from an empty one, so presence is recorded beside the value (lesson L§4).
func NewValues ¶
func NewValues() Values
NewValues returns an empty value set, for binding a record to a form.
func (Values) Bool ¶
Bool returns a checkbox's state. An absent checkbox is false, never an error (spec form-conventions "A checkbox is never required").
func (Values) Int ¶
Int returns the value as a whole number, and false when the field is absent, empty, or was refused.
func (Values) Present ¶
Present reports whether the name was submitted at all, which is not the same as carrying a value.
func (*Values) Set ¶
Set records a field's raw value, marking it present. Binding a record to a form goes through here, so the record-bound render and the submission-bound render read the same way.
func (*Values) SetBool ¶
SetBool records a checkbox's state. A ticked box carries the field's submitted value; an unticked one carries nothing, which is how the browser submits it. Either way, the typed bool is recorded too, so a bound checkbox answers Bool the same way a parsed one does (design D1).
type WayOut ¶
type WayOut struct {
Kind WayOutKind
Label string
// URL is the destination for WayOutLink, and the GET source for
// WayOutDiscard.
URL string
// PanelID is the collapse element the WayOutClosePanel button closes.
PanelID string
// HXTarget and HXSwap turn a WayOutLink into a scoped htmx GET instead
// of a plain navigation: the response at URL is swapped into HXTarget
// with HXSwap (default "innerHTML") rather than the browser navigating.
// For a form whose container is itself an htmx-swapped region, not a
// routable page (the workspace create panel's "Back" to the list), a plain <a href>
// would fall through to the page's own hx-boost and swap the wrong
// region. Both empty renders a plain <a href>, which is what a create
// page's Cancel to its own list needs.
HXTarget string
HXSwap string
// HXSelect, HXSelectOOB and HXPushURL complete a scoped request that
// replaces a panel of a routable page: the response is the whole page, so
// HXSelect names the part of it to swap in, HXSelectOOB the sibling parts
// to refresh from the same response, and HXPushURL puts URL in the address
// bar. Each renders only when set.
HXSelect string
HXSelectOOB string
HXPushURL bool
}
WayOut is a form's way out. It renders btn-outline-secondary after the commit; solid btn-secondary is not in the console's palette (design D12).
func ClosePanel ¶
ClosePanel leaves the form by collapsing the panel it sits in.
func Discard ¶
Discard leaves a preview form by re-fetching its resting state with a GET to url and swapping the same target the form posts to, carving that one region out of the GET's full-page response (design D10's preview idiom).
func DismissModal ¶
DismissModal leaves the form by closing the modal it sits in.
func PanelLinkOut ¶
PanelLinkOut leaves the form by a scoped htmx GET that replaces a panel of a routable page, the way a governed list's own search does: the page the URL returns is cut down to target (outerHTML), the panels named by selectOOB, when any, are refreshed from it, and the URL goes into the address bar. ScopedLinkOut is the way out for a partial route, which must not be pushed.
func ScopedLinkOut ¶
ScopedLinkOut leaves the form by a scoped htmx GET whose response swaps into target, for a way out that stays inside the htmx-swapped region the form itself occupies rather than navigating the page.
type WayOutKind ¶
type WayOutKind string
WayOutKind names how a form is left without submitting it.
const ( // WayOutNone is an always-open edit form: nothing is left by // cancelling, so no control is offered (finding FA-19). WayOutNone WayOutKind = "" // WayOutLink navigates away, typically a create page back to its list. WayOutLink WayOutKind = "link" // WayOutClosePanel collapses the sub-record panel the form sits in. WayOutClosePanel WayOutKind = "close-panel" // WayOutDismissModal closes the confirm modal the form sits in. WayOutDismissModal WayOutKind = "dismiss-modal" // WayOutDiscard re-fetches the form's own resting state with a GET to // URL and swaps it into the same target the form itself posts to, // carving that one region out of the GET's full-page response with the // same selector (design D10's preview idiom: a preview writes nothing, // so "Discard" has nothing to undo, only a pending choice to drop). Use // this over WayOutLink when the form renders more than once on its // page, so discarding one instance leaves its siblings alone. WayOutDiscard WayOutKind = "discard" )
type WayOutView ¶
type WayOutView struct {
Kind WayOutKind
Label string
URL string
PanelID string
HXTarget string
HXSwap string
// HXSelect, HXSelectOOB and HXPushURL are WayOut's.
HXSelect string
HXSelectOOB string
HXPushURL bool
}
WayOutView is the rendered way out.
func (WayOutView) Shown ¶
func (w WayOutView) Shown() bool
Shown reports whether the form offers a way out at all.
type Width ¶
type Width string
Width steps a field's column one rung from its control's natural fraction (design D2); ignored in every family but Dense. The zero value means the control's own rung, and no declaration writes any other constant for it: a declaration sets Width only where the field's values are shorter or longer than its control's usual ones.