Show the grant form's supersession hint only once a marked product is chosen

Task 5.10 of #269's change. The Issue grant form showed a yellow alert
under its lead whenever its Product select offered a product marked
with the warning sign, before anything was chosen, so it read as a
standing warning. The sentence now reads "This grant would supersede a
tier a subscription pays for; its billing pauses until the grant ends."
and is the Product field's one hint line, hidden until the operator
chooses a marked product and hidden again when an unmarked one is
chosen. A refused submission that chose a marked product renders it
shown. The form's message is the lead alone.

The forms library gains the mechanism, for any Stacked form: a select
declares HintOnChoice with its Hint, options carry ShowsHint, and the
field part renders the hint only when an offered option shows it,
hidden unless the chosen one does, and named by the select's
aria-describedby only while it shows. One external script,
hint-on-choice.js, loaded with defer by the operator shell, follows
later choices and htmx swaps through data-hint-toggle and
data-shows-hint. The invariants refuse HintOnChoice off a Stacked
select, without a Hint or with a Notice, and the escape hatch refuses
data-hint-toggle.

The change's text gains a form-library requirement ("A select's hint
can wait for the option that shows it") and modifies form-conventions'
"Every control has a label, and its hint and error are described" so a
hint is described while it shows. docs/design-system.md describes the
mechanism in section 8 and adds the script to the
progressive-enhancement table.

Tests: TestOrgEnrollmentIssueGrantSupersedeHint (at rest, no marked
product, a refused submission with a marked, an unmarked and no
product, the message the lead alone), TestOperatorShellLoadsTheHintToggle,
TestRenderHintOnChoiceFollowsTheChosenOption,
TestInvariantsHintOnChoiceBelongsToAStackedSelectWithItsHint, the
escape hatch's and the invariant messages' rows, and
TestGrantSupersedeHintWalkthrough, which chooses a marked and then an
unmarked product on the demo's Carlos Member organization and checks
the hint and aria-describedby both ways. Three organization goldens
change only in the message and the Product field.

Review: round 1, three majors (the hint supplied per render, bypassing
the registry's hint checks; no spec for the library's new contract,
with form-conventions saying the opposite; the script's break
unreachable while the app serves its embedded copy) and five minors,
all fixed; round 2, no major.

Breaks: 12 of 12 caught. 8 in code; the script's 4 run as a second
list whose preparation rebuilds and restarts the app on the broken
tree. Full suite on reset databases: 4843 pass, 14 skip.

make screens: Carlos Member's organization, open and refused, at both
widths, loses the alert. Hand captures of the form at rest, with a
marked product chosen and with an unmarked one chosen after it sit
beside the change's screens.
This commit is contained in:
2026-10-28 14:18:11 -05:00
parent 56d801e36a
commit f7363e98af
23 changed files with 478 additions and 68 deletions
+11 -1
View File
@@ -635,6 +635,7 @@ htmx 4 swaps every response except 204/304. The contract:
| Operator list controls (search, facets, paging) | Work: native GET `action`/`method` present | True progressive enhancement, kept. |
| Operator lookup (`operator.lookup.search`, the `Search` kind, §8) | Work: native `method="get"` `action` | True progressive enhancement, kept: a lookup writes nothing, so it never needed the mutation path (`form-conventions`). |
| Timezone offset attachment (`grant-valid-until-tz.js`) | Server falls back to its own zone | Optional enhancement, kept. |
| Hint toggled by a select's choice (`hint-on-choice.js`) | Server renders the hint hidden or shown for the chosen option | Optional enhancement: without it the hint stays as rendered. |
| Stripe checkout | `HX-Redirect` handoff requires htmx (see `billing.go`) | Require htmx, recorded in code. |
A new form names its category; a different answer needs a recorded decision
@@ -916,7 +917,8 @@ always, never inside the `<label>` element: a button inside a label
toggles the labelled control on every click that opens the popover,
which is not what a help click should do.
A field's hint carries an id its control's `aria-describedby` names; its
A field's hint carries an id its control's `aria-describedby` names while
it shows; its
error, when the submission is refused, carries its own id, also named,
with `aria-invalid="true"` on the control; the hint stays visible beside
the error, because GOV.UK's own side of this split is: don't take away
@@ -939,6 +941,14 @@ checks, the 100-character cap among them, read only a declared hint and
do not see that line; the `filler-copy` lint still reads the Go literals
that build it.
A hint can wait for a choice. A select that declares `HintOnChoice`
renders its declared `Hint` only when an option it offers carries
`ShowsHint`. The hint stays hidden, and out of `aria-describedby`,
until such an option is chosen, and a refused submission that chose one
renders it shown. `hint-on-choice.js` follows later choices through the
select's `data-hint-toggle` and the options' `data-shows-hint`. Issue
grant's supersession hint is built this way.
`autocomplete` is declared per field: a real token (`name`, `email`,
`url`, `organization`) where one applies, `off` for keys, search boxes
and one-time values; the form tag itself carries none, and a template
+49
View File
@@ -0,0 +1,49 @@
// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial
// SPDX-FileCopyrightText: 2025-2026 Christian Galo
// hint-on-choice.js
//
// Shows a select's hint line only while the chosen option marks it. The
// select names the hint it controls in data-hint-toggle (the hint element's
// id), and each option that shows the hint carries data-shows-hint. The
// server renders the line already hidden or shown for the chosen option, so
// this script only follows later choices and restores the state after the
// browser restores a form's values. The hint joins the select's
// aria-describedby while it is shown.
(function () {
"use strict";
function sync(select) {
var id = select.getAttribute("data-hint-toggle");
var hint = id && document.getElementById(id);
if (!hint) return;
var chosen = select.options[select.selectedIndex];
var shown = !!chosen && chosen.hasAttribute("data-shows-hint");
hint.hidden = !shown;
var ids = (select.getAttribute("aria-describedby") || "").split(/\s+/).filter(function (x) {
return x && x !== id;
});
if (shown) ids.unshift(id);
if (ids.length) {
select.setAttribute("aria-describedby", ids.join(" "));
} else {
select.removeAttribute("aria-describedby");
}
}
function syncAll(root) {
if (root && root.matches && root.matches("select[data-hint-toggle]")) sync(root);
var selects = (root || document).querySelectorAll("select[data-hint-toggle]");
for (var i = 0; i < selects.length; i++) sync(selects[i]);
}
document.addEventListener("change", function (evt) {
var t = evt.target;
if (t && t.matches && t.matches("select[data-hint-toggle]")) sync(t);
});
if (window.htmx && typeof window.htmx.onLoad === "function") {
window.htmx.onLoad(syncAll);
}
syncAll(document);
})();
+1
View File
@@ -28,6 +28,7 @@
<script defer src="/static/error-handler.js"></script>
<script defer src="/static/success-toast.js"></script>
<script defer src="/static/grant-valid-until-tz.js"></script>
<script defer src="/static/hint-on-choice.js"></script>
<script defer src="/static/confirm-action-modal.js"></script>
<script defer src="/static/sortable.min.js"></script>
<script defer src="/static/sortable-reorder.js"></script>
@@ -48,7 +48,8 @@
The .Attrs blob is every attribute the declaration decides: required,
maxlength, min, max, pattern, inputmode, autocomplete, the
described-by wiring, autofocus on the first errored control, and the
described-by wiring, the hint a select toggles (data-hint-toggle),
autofocus on the first errored control, and the
data-* and hx-* escape hatch. It is built in Go (forms.fieldAttrs) so
the browser's constraints and the server's rules cannot differ and no
template can write one by hand.
@@ -83,7 +84,7 @@
the rare field whose one-sidedness would surprise a person, its
notice. A one-sided field's declared reason is not copy and never
renders (maintainer, 2026-09-03). */}}
{{ if .Hint }}<div id="{{ .HintID }}" class="form-text">{{ .Hint }}</div>{{ end }}
{{ if .Hint }}<div id="{{ .HintID }}" class="form-text"{{ if .HintHidden }} hidden{{ end }}>{{ .Hint }}</div>{{ end }}
{{ if .Notice }}<div id="{{ .NoticeID }}" class="form-text">{{ .Notice }}</div>{{ end }}
{{ if .Error }}<div id="{{ .ErrorID }}" class="invalid-feedback d-block">{{ .Error }}</div>{{ end }}
</div>
@@ -109,7 +110,7 @@
<input class="form-check-input{{ if .Error }} is-invalid{{ end }}" type="checkbox" id="{{ .ControlID }}" name="{{ .Name }}" value="{{ .CheckboxValue }}"{{ if .Checked }} checked{{ end }} {{ .Attrs }}>
{{- else if eq .Control "select" -}}
<select class="form-select{{ if .Small }} form-select-sm{{ end }}{{ if .Error }} is-invalid{{ end }}" id="{{ .ControlID }}" name="{{ .Name }}" {{ .Attrs }}>
{{ range .Options }}<option value="{{ .Value }}"{{ if .Disabled }} disabled{{ end }}{{ if .Selected }} selected{{ end }}>{{ .Label }}</option>
{{ range .Options }}<option value="{{ .Value }}"{{ if .Disabled }} disabled{{ end }}{{ if .Selected }} selected{{ end }}{{ if .ShowsHint }} data-shows-hint{{ end }}>{{ .Label }}</option>
{{ end }}
</select>
{{- else if eq .Control "textarea" -}}
+11
View File
@@ -475,6 +475,9 @@ 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
}
// ChooseOption is the first option of a select whose value must be chosen:
@@ -540,6 +543,14 @@ type Field struct {
// 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.
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.
@@ -142,8 +142,10 @@ var invariantCases = []invariantCase{
{"hint restates label", func(s *FormSpec) { firstField(s).Hint = "Enter the name" }, msgBase, false},
{"hint in a dense row", func(s *FormSpec) { firstField(s).Hint = "Shown on invoices." }, msgDense, false},
{"notice in a dense row", func(s *FormSpec) { firstField(s).Notice = "Changes apply tomorrow." }, msgDense, false},
{"hint on choice off a stacked select", func(s *FormSpec) { firstField(s).HintOnChoice = true }, msgBase, false},
{"placeholder sentence", func(s *FormSpec) { firstField(s).Placeholder = "Enter the name." }, msgBase, false},
{"escape hatch outside data and hx", func(s *FormSpec) { firstField(s).Attrs = map[string]string{"class": "x"} }, msgBase, false},
{"escape hatch writes the hint toggle", func(s *FormSpec) { firstField(s).Attrs = map[string]string{"data-hint-toggle": "x"} }, msgBase, false},
{"em dash in label", func(s *FormSpec) { firstField(s).Label = "Name — legal" }, msgBase, false},
{"em dash in hint", func(s *FormSpec) { firstField(s).Hint = "Shown — on invoices." }, msgBase, false},
{"em dash in placeholder", func(s *FormSpec) { firstField(s).Placeholder = "e.g. a — b" }, msgBase, false},
+8 -2
View File
@@ -266,6 +266,9 @@ func checkFieldCopy(family Family, f Field, add addFunc) {
if f.Pattern != "" && f.PatternHint == "" {
add("the field %q declares a pattern with no hint; a regular expression is not an error message", f.Name)
}
if f.HintOnChoice && (f.Control != Select || f.Hint == "" || f.Notice != "" || family != Stacked) {
add("the field %q declares HintOnChoice; it belongs to a select in a stacked form that declares the Hint it shows and no Notice", f.Name)
}
if f.Hint != "" && f.Notice != "" {
add("the field %q declares a hint and a notice; one visible line under a control is the budget, so put the explanation in one of them or in Help", f.Name)
}
@@ -304,14 +307,17 @@ func checkFieldCopy(family Family, f Field, add addFunc) {
// checkEscapeHatch checks the keys of a field's escape hatch. It admits
// data-* and hx-* keys only: no attribute the field part writes itself
// has either prefix, so a caller cannot use it to render a control without
// its label wiring or with a constraint the server does not apply (lesson
// has either prefix, apart from data-hint-toggle, which it refuses too,
// so a caller cannot use it to render a control without its label wiring or with a constraint the server does not apply (lesson
// L§12, GOV.UK's Nunjucks API rules).
func checkEscapeHatch(f Field, add addFunc) {
for _, key := range slices.Sorted(maps.Keys(f.Attrs)) {
if !strings.HasPrefix(key, "data-") && !strings.HasPrefix(key, "hx-") {
add("the field %q escape hatch carries %q; the escape hatch admits data-* and hx-* keys only", f.Name, key)
}
if key == "data-hint-toggle" {
add("the field %q escape hatch carries %q, which the field part writes for HintOnChoice", f.Name, key)
}
}
}
+33
View File
@@ -147,6 +147,9 @@ func TestInvariantsEscapeHatchKeys(t *testing.T) {
wants(t, spec, "escape hatch")
}
spec := base()
spec.Fields[0].Attrs = map[string]string{"data-hint-toggle": "x"}
wants(t, spec, "writes for HintOnChoice")
spec = base()
spec.Fields[0].Attrs = map[string]string{"data-thing": "x", "hx-get": "/x"}
if problems := CheckInvariants(spec); len(problems) != 0 {
t.Errorf("data-* and hx-* keys are the escape hatch, got %v", problems)
@@ -441,3 +444,33 @@ func TestInvariantsRowCommitBelongsToABatchFormWithoutATray(t *testing.T) {
wants(t, placed, "commits row by row; such a form stages nothing and has no tray")
}
}
// HintOnChoice belongs to a select in a stacked form that declares the Hint
// it shows and no Notice.
func TestInvariantsHintOnChoiceBelongsToAStackedSelectWithItsHint(t *testing.T) {
sel := func() Field {
return Field{Name: "kind", Label: "Kind", Control: Select, RuntimeOptions: true, HintOnChoice: true, Hint: "B is special."}
}
spec := base()
spec.Fields[0].HintOnChoice = true
wants(t, spec, "declares HintOnChoice")
spec = base()
spec.Fields[0] = sel()
spec.Fields[0].Hint = ""
wants(t, spec, "declares HintOnChoice")
spec = base()
spec.Fields[0] = sel()
spec.Fields[0].Notice = "Fixed later."
wants(t, spec, "declares HintOnChoice")
spec = denseBase()
spec.Fields[0] = sel()
wants(t, spec, "declares HintOnChoice")
spec = base()
spec.Fields[0] = sel()
for _, p := range CheckInvariants(spec) {
if strings.Contains(p, "HintOnChoice") {
t.Errorf("a stacked select declaring its hint is refused: %v", CheckInvariants(spec))
break
}
}
}
+42 -7
View File
@@ -337,6 +337,8 @@ type OptionView struct {
Label string
Disabled bool
Selected bool
// ShowsHint renders data-shows-hint on the option.
ShowsHint bool
}
// RadioView is one rendered radio in a group.
@@ -395,8 +397,11 @@ type FieldView struct {
Help HelpIcon
Hint string
HintID string
Error string
ErrorID string
// HintHidden renders the hint with the hidden attribute: a
// HintOnChoice field whose chosen option does not show it.
HintHidden bool
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.
@@ -980,6 +985,19 @@ func renderFieldAs(formID, suffix, name string, family Family, f Field, b Bindin
fv.Radios = radioOptions(opts, wrapper, fv.Value)
}
if f.HintOnChoice {
fv.Hint = choiceHint(f.Hint, fv.Options)
fv.HintHidden = true
for _, o := range fv.Options {
if o.Selected && o.ShowsHint {
fv.HintHidden = false
}
}
} else {
for i := range fv.Options {
fv.Options[i].ShowsHint = false
}
}
describedBy := describeField(&fv, wrapper, f, b)
fv.Attrs = template.HTMLAttr(strings.Join(fieldAttrs(f, fv, opts, describedBy), " "))
return fv
@@ -1071,7 +1089,7 @@ func selectOptions(opts []Option, value string, present bool) []OptionView {
for _, o := range opts {
selected := present && o.Value == value
chosen = chosen || selected
out = append(out, OptionView{Value: o.Value, Label: o.Label, Disabled: o.Disabled, Selected: selected})
out = append(out, OptionView{Value: o.Value, Label: o.Label, Disabled: o.Disabled, Selected: selected, ShowsHint: o.ShowsHint})
}
if !chosen && len(out) > 0 && !present {
out[0].Selected = true
@@ -1088,15 +1106,29 @@ func radioOptions(opts []Option, wrapper, value string) []RadioView {
return out
}
// choiceHint is a HintOnChoice field's hint when an option the select
// offers shows it, and "" when none does, so the field renders no line.
func choiceHint(hint string, opts []OptionView) string {
for _, o := range opts {
if o.ShowsHint {
return hint
}
}
return ""
}
// describeField sets the ids of the lines under a control and returns them
// in described-by order: the hint keeps its id and stays visible beside the
// error, and the error carries its own id, so a screen reader hears why a
// in described-by order: a hint that shows keeps its id and stays visible
// beside the error (a hint that waits for a choice is named only while it
// shows), and the error carries its own id, so a screen reader hears why a
// control was refused and not only that it was (findings FA-48, FA-49).
func describeField(fv *FieldView, wrapper string, f Field, b Binding) []string {
var describedBy []string
if f.Hint != "" {
if fv.Hint != "" {
fv.HintID = wrapper + "-hint"
describedBy = append(describedBy, fv.HintID)
if !fv.HintHidden {
describedBy = append(describedBy, fv.HintID)
}
}
if fv.Notice != "" {
fv.NoticeID = wrapper + "-notice"
@@ -1170,6 +1202,9 @@ func fieldAttrs(f Field, fv FieldView, opts []Option, describedBy []string) []st
if f.Autocomplete != "" && f.Control != Checkbox && f.Control != Hidden && f.Control != Static {
add("autocomplete", f.Autocomplete)
}
if f.HintOnChoice && fv.HintID != "" {
add("data-hint-toggle", fv.HintID)
}
if len(describedBy) > 0 {
add("aria-describedby", strings.Join(describedBy, " "))
}
+28
View File
@@ -1200,3 +1200,31 @@ func TestRenderRowFieldInlineOptions(t *testing.T) {
t.Error("a cell's checkbox moved its label above the box")
}
}
// A HintOnChoice select renders its declared hint hidden unless the chosen
// option shows it, names the hint it controls, and renders no hint when no
// option it offers shows it.
func TestRenderHintOnChoiceFollowsTheChosenOption(t *testing.T) {
spec := base()
spec.Fields[0] = Field{Name: "kind", Label: "Kind", Control: Select, RuntimeOptions: true, HintOnChoice: true, Hint: "B is special."}
opts := map[string][]Option{"kind": {ChooseOption("a kind"), {Value: "a", Label: "A"}, {Value: "b", Label: "B", ShowsHint: true}}}
chosen := func(v string) FieldView {
values := NewValues()
values.Set("kind", v)
return Render(spec, Binding{Mode: ModeSubmission, Values: values, Options: opts}).Fields[0]
}
if f := Render(spec, Binding{Mode: ModeUnbound, Options: opts}).Fields[0]; !f.HintHidden || f.Hint != "B is special." || !strings.Contains(string(f.Attrs), `data-hint-toggle="`+f.HintID+`"`) || strings.Contains(string(f.Attrs), "aria-describedby") {
t.Errorf("at rest, the hint = %q hidden %v attrs %q, want the text, hidden, named by the select and not described", f.Hint, f.HintHidden, f.Attrs)
}
if f := chosen("b"); f.HintHidden || !strings.Contains(string(f.Attrs), `aria-describedby="`+f.HintID+`"`) || !f.Options[2].ShowsHint {
t.Errorf("after choosing the option that shows it, hidden %v attrs %q, want shown and described", f.HintHidden, f.Attrs)
}
if f := chosen("a"); !f.HintHidden {
t.Error("after choosing an option that does not show it, the hint is shown")
}
plain := map[string][]Option{"kind": {ChooseOption("a kind"), {Value: "a", Label: "A"}, {Value: "b", Label: "B"}}}
if f := Render(spec, Binding{Mode: ModeUnbound, Options: plain}).Fields[0]; f.Hint != "" || f.HintID != "" || strings.Contains(string(f.Attrs), "data-hint-toggle") {
t.Errorf("with no option that shows it the field renders hint %q attrs %q", f.Hint, f.Attrs)
}
}
+5 -1
View File
@@ -104,10 +104,14 @@ hint in a dense row:
the field "name" carries a hint in a dense row; put the explanation in Help, which the icon after the label opens
notice in a dense row:
the field "name" carries a notice in a dense row; put it in Help, which the icon after the label opens
hint on choice off a stacked select:
the field "name" declares HintOnChoice; it belongs to a select in a stacked form that declares the Hint it shows and no Notice
placeholder sentence:
the field "name" placeholder reads as a sentence; a placeholder is a format example, and anything else is a hint
escape hatch outside data and hx:
the field "name" escape hatch carries "class"; the escape hatch admits data-* and hx-* keys only
escape hatch writes the hint toggle:
the field "name" escape hatch carries "data-hint-toggle", which the field part writes for HintOnChoice
em dash in label:
the field "name" label uses an em dash; write it as a semicolon, colon, or comma
em dash in hint:
@@ -153,4 +157,4 @@ one problem in each rule group, in the order the groups run:
the form declares the field "name" twice
the form's commit label uses an em dash; write it as a semicolon, colon, or comma
distinct messages: 59
distinct messages: 61
+14 -20
View File
@@ -127,15 +127,15 @@ var issueGrantForm = forms.Register(forms.FormSpec{
// (grant-resumption D21).
const issueGrantLead = "A tier product moves the pool to that tier, up or down."
// issueGrantSupersedeWarning follows the lead when a product the select
// offers is marked with the supersession marker. The sentence states what the
// grant does to the subscription and names no view, because the operator's
// billing views only read (displaced-subscription-waits D4). The sentence is
// grant-pauses-subscription-billing Copy row W. The grant pauses the subscription's
// issueGrantSupersedeWarning is the Product field's hint line, shown while the
// chosen product carries the supersession marker (grant-pauses-subscription-billing
// Copy row W). The sentence states what the grant does to the subscription and
// names no view, because the operator's billing views only read
// (displaced-subscription-waits D4). The grant pauses the subscription's
// billing because the console pauses collection at Stripe while a grant holds
// every ladder the subscription pays for, so the subscription is not charged
// for a period the grant covers.
const issueGrantSupersedeWarning = "Products marked ⚠ would supersede a tier a subscription pays for; its billing pauses until the grant ends."
const issueGrantSupersedeWarning = "This grant would supersede a tier a subscription pays for; its billing pauses until the grant ends."
// manageGrantForm is the declaration for Manage (grant-resumption D15):
// everything about a grant that can change after issue, with the fields the
@@ -206,13 +206,14 @@ func issuanceProductOptions(products []IssuanceProductOption) []forms.Option {
if p.SupersedesSubscription {
label += " ⚠"
}
opts = append(opts, forms.Option{Value: p.ProductID, Label: label})
opts = append(opts, forms.Option{Value: p.ProductID, Label: label, ShowsHint: p.SupersedesSubscription})
}
return opts
}
// issueGrantProductField is the grant's product picker plus the rule-less
// warning's live region (design.md M1; plan-enrollment-administration "Issue
// warning's live region, with Copy W as its hint, which waits for a product
// marked ⚠ (HintOnChoice) (design.md M1; plan-enrollment-administration "Issue
// grant names a product that provides nothing"), on the duplicate-name
// warning's precedent. The picker stays unfiltered and unpartitioned and the
// commit stays enabled: a set with no active rule is a state an operator may
@@ -223,6 +224,8 @@ func issueGrantProductField() forms.Field {
Label: "Product",
Control: forms.Select,
RuntimeOptions: true,
HintOnChoice: true,
Hint: issueGrantSupersedeWarning,
Slot: "warning",
Attrs: map[string]string{
"hx-get": "/partials/operator/products/rule-check",
@@ -243,8 +246,8 @@ func issueGrantFormOptions(products []IssuanceProductOption) map[string][]forms.
// issueGrantFormView renders the Issue grant panel: mode is ModeRecord at
// rest (bound to empty values, so a fresh open shows nothing chosen and no
// error) and ModeSubmission on a refused submission, with every submitted
// value carried back (design D9). Its message is the lead, followed by the
// supersession warning when a product the select offers carries the marker.
// value carried back (design D9). Its message is the lead alone; the
// supersession warning is the Product field's hint.
func issueGrantFormView(orgID string, products []IssuanceProductOption, mode forms.Mode, values forms.Values, errs *forms.Errors, warning template.HTML) forms.FormView {
action, err := web.RouteURL(issueGrantForm.Path, orgID)
if err != nil {
@@ -254,15 +257,6 @@ func issueGrantFormView(orgID string, products []IssuanceProductOption, mode for
if warning != "" {
slots = map[string]template.HTML{"product_id": warning}
}
// Both sentences are this file's constants, never a person's input, so
// they enter the message as markup without escaping.
message := template.HTML(issueGrantLead)
for _, p := range products {
if p.SupersedesSubscription {
message += `<div class="alert alert-warning py-1 px-2 small mt-2 mb-0" role="alert">` + template.HTML(issueGrantSupersedeWarning) + `</div>`
break
}
}
return forms.Render(issueGrantForm, forms.Binding{
Mode: mode,
Action: action,
@@ -270,7 +264,7 @@ func issueGrantFormView(orgID string, products []IssuanceProductOption, mode for
Errors: errs,
Options: issueGrantFormOptions(products),
Slots: slots,
Message: message,
Message: template.HTML(issueGrantLead),
})
}
@@ -21,6 +21,7 @@ import (
"git.coopcloud.tech/wiki-cafe/member-console/internal/billing"
"git.coopcloud.tech/wiki-cafe/member-console/internal/entitlements"
"git.coopcloud.tech/wiki-cafe/member-console/internal/forms"
"git.coopcloud.tech/wiki-cafe/member-console/internal/testkit/htmltest"
"git.coopcloud.tech/wiki-cafe/member-console/internal/web"
"github.com/google/uuid"
)
@@ -502,15 +503,106 @@ func TestOrgEnrollmentIssueGrantPanel_TerseCopy(t *testing.T) {
}
// supersedeWarningCopy is Copy row W of grant-pauses-subscription-billing, the
// whole sentence the Issue grant form's warning reads.
const supersedeWarningCopy = "Products marked ⚠ would supersede a tier a subscription pays for; its billing pauses until the grant ends."
// whole sentence the Issue grant form's warning reads: the Product field's
// hint line.
const supersedeWarningCopy = "This grant would supersede a tier a subscription pays for; its billing pauses until the grant ends."
// supersedeHintID is the Product field's hint element, which the select
// names in data-hint-toggle.
const supersedeHintID = "form-operator.enrollment.grant.issue-product_id-hint"
// issueGrantPanelHTML is the Issue grant form's markup in a rendered page.
func issueGrantPanelHTML(t *testing.T, out string) string {
t.Helper()
i := strings.Index(out, `id="issueGrantPanel"`)
if i < 0 {
t.Fatalf("no Issue grant panel:\n%s", out)
}
panel := out[i:]
return panel[:strings.Index(panel, "</form>")]
}
// TestOrgEnrollmentIssueGrantSupersedeHint covers the supersession warning
// as the Product field's hint (grant-pauses-subscription-billing Copy row
// W): present and hidden at rest when a marked product is offered, absent
// when none is, shown in a refused submission that chose a marked product,
// hidden in one that chose an unmarked product, and never in the message.
func TestOrgEnrollmentIssueGrantSupersedeHint(t *testing.T) {
marked := onePoolFixture()
marked.IssuanceProducts = []IssuanceProductOption{
{ProductID: "prod-plain", Name: "Plain"},
{ProductID: "prod-pro", Name: "Pro", SupersedesSubscription: true},
}
render := func(d OrgEnrollmentData, mode forms.Mode, values forms.Values) string {
d.IssueGrantForm = issueGrantFormView(d.OrgID, d.IssuanceProducts, mode, values, nil, "")
return issueGrantPanelHTML(t, renderOrgEnrollment(t, d))
}
chose := func(id string) forms.Values {
v := forms.NewValues()
v.Set("product_id", id)
return v
}
// hint is the Product hint's nodes in the panel; hintMiss names how they
// differ from one hint reading Copy W, hidden or shown as wanted, and is
// "" when they do not.
hint := func(doc *htmltest.Node) []*htmltest.Node {
return doc.All(`[id="` + supersedeHintID + `"]`)
}
hintMiss := func(doc *htmltest.Node, wantHidden bool) string {
nodes := hint(doc)
if len(nodes) != 1 {
return fmt.Sprintf("renders %d times, want once", len(nodes))
}
if _, hidden := nodes[0].Attr("hidden"); hidden != wantHidden {
if wantHidden {
return "is not rendered hidden"
}
return "is not shown"
}
if got := strings.TrimSpace(nodes[0].Text()); got != supersedeWarningCopy {
return fmt.Sprintf("reads %q", got)
}
return ""
}
atHTML := render(marked, forms.ModeRecord, forms.NewValues())
at := htmltest.Parse(t, atHTML)
if miss := hintMiss(at, true); miss != "" {
t.Errorf("at rest, the Product hint %s:\n%s", miss, atHTML)
}
if sel := at.All(`select[name=product_id]`); len(sel) != 1 {
t.Errorf("at rest, the Product select lacks its one control, found %d:\n%s", len(sel), atHTML)
} else if toggle, _ := sel[0].Attr("data-hint-toggle"); toggle != supersedeHintID {
t.Errorf("at rest, the Product select lacks data-hint-toggle %q, has %q:\n%s", supersedeHintID, toggle, atHTML)
}
if at.Count(`option[value=prod-pro][data-shows-hint]`) != 1 || at.Count(`option[value=prod-plain][data-shows-hint]`) != 0 {
t.Errorf("at rest, the Product select lacks data-shows-hint on exactly the marked option:\n%s", atHTML)
}
if msg := at.All(`.app-form-message`); len(msg) != 1 || strings.TrimSpace(msg[0].Text()) != "A tier product moves the pool to that tier, up or down." || at.Count(`.app-form-message [role=alert]`) != 0 {
t.Errorf("at rest, the message is not the lead alone:\n%s", atHTML)
}
markedHTML := render(marked, forms.ModeSubmission, chose("prod-pro"))
if miss := hintMiss(htmltest.Parse(t, markedHTML), false); miss != "" {
t.Errorf("in a refused submission that chose a marked product, the Product hint %s:\n%s", miss, markedHTML)
}
plainHTML := render(marked, forms.ModeSubmission, chose("prod-plain"))
if miss := hintMiss(htmltest.Parse(t, plainHTML), true); miss != "" {
t.Errorf("in a refused submission that chose an unmarked product, the Product hint %s:\n%s", miss, plainHTML)
}
none := onePoolFixture()
noneHTML := render(none, forms.ModeRecord, forms.NewValues())
if doc := htmltest.Parse(t, noneHTML); len(hint(doc)) != 0 || doc.Count(`[data-hint-toggle]`) != 0 || strings.Contains(noneHTML, supersedeWarningCopy) {
t.Errorf("with no marked product offered, the Product field carries a hint:\n%s", noneHTML)
}
}
// TestOrgEnrollmentIssueGrantPanel_Stacked covers grant-resumption D21:
// Issue grant is a stacked form in its panel, the form part's own box at the
// readable measure, one field per row with its label above, the lead above
// the fields, and "Issue grant" with "Cancel" under the last field. The
// supersession warning joins the lead only when a product carries the
// marker.
// supersession warning is the Product field's hint, covered by
// TestOrgEnrollmentIssueGrantSupersedeHint.
func TestOrgEnrollmentIssueGrantPanel_Stacked(t *testing.T) {
out := renderOrgEnrollment(t, onePoolFixture())
i := strings.Index(out, `id="issueGrantPanel"`)
@@ -548,15 +640,6 @@ func TestOrgEnrollmentIssueGrantPanel_Stacked(t *testing.T) {
}
last = at
}
data := onePoolFixture()
data.IssuanceProducts = append(data.IssuanceProducts, IssuanceProductOption{ProductID: "prod-pro", Name: "Pro", SupersedesSubscription: true})
data.IssueGrantForm = issueGrantFormView(data.OrgID, data.IssuanceProducts, forms.ModeRecord, forms.NewValues(), nil, "")
warned := renderOrgEnrollment(t, data)
wantWarning := `A tier product moves the pool to that tier, up or down.<div class="alert alert-warning py-1 px-2 small mt-2 mb-0" role="alert">` + supersedeWarningCopy + `</div>`
if !strings.Contains(warned, wantWarning) {
t.Errorf("the stacked Issue grant panel lacks %q:\n%s", wantWarning, warned)
}
}
// TestOrgEnrollmentManageRow_Fields covers grant-resumption D15 and findings
@@ -705,8 +788,8 @@ func TestOrgEnrollmentProductsSection(t *testing.T) {
if !strings.Contains(out, "Standard Plan ⚠") {
t.Error("expected the ⚠ marker on superseding product options")
}
if !strings.Contains(out, ">"+supersedeWarningCopy+"<") {
t.Errorf("the products section lacks the supersession warning %q when a ⚠ option is present", supersedeWarningCopy)
if !strings.Contains(out, ` hidden>`+supersedeWarningCopy+`</div>`) {
t.Errorf("the products section lacks the supersession hint %q, hidden at rest, when a ⚠ option is present", supersedeWarningCopy)
}
})
}
@@ -205,6 +205,16 @@ func TestOperatorShellTopBarAndDrawer(t *testing.T) {
}
}
// TestOperatorShellLoadsTheHintToggle pins that the operator pages load the
// script that shows a select's hint while a marked option is chosen
// (Issue grant's supersession warning).
func TestOperatorShellLoadsTheHintToggle(t *testing.T) {
page := operatorPage(t, signedInOperator("organizations"))
if page.Count(`script[defer][src="/static/hint-on-choice.js"]`) != 1 {
t.Error("the operator shell does not load hint-on-choice.js with defer")
}
}
// TestOperatorShellRailAccountBlock mirrors TestShellRailAccountBlock
// (member_nav_test.go) on the operator surface: below lg the drawer is the
// shell's one menu, so it carries the account items after the eight
@@ -185,7 +185,7 @@
<form id="form-operator.enrollment.grant.issue" data-form="operator.enrollment.grant.issue" data-form-kind="create" class="app-form" novalidate hx-post="/partials/operator/organizations/<org:rich>/grant/create" hx-target="#operator-body" hx-swap="innerHTML" hx-disable="find button[type=submit]" hx-indicator="find .htmx-indicator">
<div id="form-operator.enrollment.grant.issue-error" class="app-form-error" role="alert"></div>
<div class="app-form-message mb-2">A tier product moves the pool to that tier, up or down.<div class="alert alert-warning py-1 px-2 small mt-2 mb-0" role="alert">Products marked ⚠ would supersede a tier a subscription pays for; its billing pauses until the grant ends.</div></div>
<div class="app-form-message mb-2">A tier product moves the pool to that tier, up or down.</div>
@@ -195,18 +195,18 @@
<label class="form-label" for="form-operator.enrollment.grant.issue-product_id-control">Product</label>
<select class="form-select" id="form-operator.enrollment.grant.issue-product_id-control" name="product_id" required aria-describedby="form-operator.enrollment.grant.issue-product_id-warning" hx-get="/partials/operator/products/rule-check" hx-swap="innerHTML" hx-target="#form-operator\.enrollment\.grant\.issue-product_id-warning" hx-trigger="change">
<select class="form-select" id="form-operator.enrollment.grant.issue-product_id-control" name="product_id" required data-hint-toggle="form-operator.enrollment.grant.issue-product_id-hint" aria-describedby="form-operator.enrollment.grant.issue-product_id-warning" hx-get="/partials/operator/products/rule-check" hx-swap="innerHTML" hx-target="#form-operator\.enrollment\.grant\.issue-product_id-warning" hx-trigger="change">
<option value="" disabled selected>Choose a product</option>
<option value="<product:Basic>">Basic</option>
<option value="<product:Forum>">Forum</option>
<option value="<product:Forum2>">Forum2</option>
<option value="<product:Large>">Large ⚠</option>
<option value="<product:Large>" data-shows-hint>Large ⚠</option>
<option value="<product:Lite>">Lite</option>
<option value="<product:Lite2>">Lite2</option>
<option value="<product:Mid>">Mid</option>
<option value="<product:Plus>">Plus</option>
<option value="<product:Pro>">Pro</option>
<option value="<product:Small>">Small ⚠</option>
<option value="<product:Small>" data-shows-hint>Small ⚠</option>
<option value="<product:Small2>">Small2</option>
<option value="<product:Starter>">Starter</option>
<option value="<product:Starter2>">Starter2</option>
@@ -216,7 +216,7 @@
<div id="form-operator.enrollment.grant.issue-product_id-warning"></div>
<div id="form-operator.enrollment.grant.issue-product_id-hint" class="form-text" hidden>This grant would supersede a tier a subscription pays for; its billing pauses until the grant ends.</div>
</div><div id="form-operator.enrollment.grant.issue-quantity" class="mb-3 app-form-field">
+5 -5
View File
@@ -185,7 +185,7 @@
<form id="form-operator.enrollment.grant.issue" data-form="operator.enrollment.grant.issue" data-form-kind="create" class="app-form" novalidate hx-post="/partials/operator/organizations/<org:rich>/grant/create" hx-target="#operator-body" hx-swap="innerHTML" hx-disable="find button[type=submit]" hx-indicator="find .htmx-indicator">
<div id="form-operator.enrollment.grant.issue-error" class="app-form-error" role="alert"></div>
<div class="app-form-message mb-2">A tier product moves the pool to that tier, up or down.<div class="alert alert-warning py-1 px-2 small mt-2 mb-0" role="alert">Products marked ⚠ would supersede a tier a subscription pays for; its billing pauses until the grant ends.</div></div>
<div class="app-form-message mb-2">A tier product moves the pool to that tier, up or down.</div>
@@ -195,18 +195,18 @@
<label class="form-label" for="form-operator.enrollment.grant.issue-product_id-control">Product</label>
<select class="form-select" id="form-operator.enrollment.grant.issue-product_id-control" name="product_id" required aria-describedby="form-operator.enrollment.grant.issue-product_id-warning" hx-get="/partials/operator/products/rule-check" hx-swap="innerHTML" hx-target="#form-operator\.enrollment\.grant\.issue-product_id-warning" hx-trigger="change">
<select class="form-select" id="form-operator.enrollment.grant.issue-product_id-control" name="product_id" required data-hint-toggle="form-operator.enrollment.grant.issue-product_id-hint" aria-describedby="form-operator.enrollment.grant.issue-product_id-warning" hx-get="/partials/operator/products/rule-check" hx-swap="innerHTML" hx-target="#form-operator\.enrollment\.grant\.issue-product_id-warning" hx-trigger="change">
<option value="" disabled selected>Choose a product</option>
<option value="<product:Basic>">Basic</option>
<option value="<product:Forum>">Forum</option>
<option value="<product:Forum2>">Forum2</option>
<option value="<product:Large>">Large ⚠</option>
<option value="<product:Large>" data-shows-hint>Large ⚠</option>
<option value="<product:Lite>">Lite</option>
<option value="<product:Lite2>">Lite2</option>
<option value="<product:Mid>">Mid</option>
<option value="<product:Plus>">Plus</option>
<option value="<product:Pro>">Pro</option>
<option value="<product:Small>">Small ⚠</option>
<option value="<product:Small>" data-shows-hint>Small ⚠</option>
<option value="<product:Small2>">Small2</option>
<option value="<product:Starter>">Starter</option>
<option value="<product:Starter2>">Starter2</option>
@@ -216,7 +216,7 @@
<div id="form-operator.enrollment.grant.issue-product_id-warning"></div>
<div id="form-operator.enrollment.grant.issue-product_id-hint" class="form-text" hidden>This grant would supersede a tier a subscription pays for; its billing pauses until the grant ends.</div>
</div><div id="form-operator.enrollment.grant.issue-quantity" class="mb-3 app-form-field">
@@ -140,7 +140,7 @@
<form id="form-operator.enrollment.grant.issue" data-form="operator.enrollment.grant.issue" data-form-kind="create" class="app-form" novalidate hx-post="/partials/operator/organizations/<org:suspended-subscription>/grant/create" hx-target="#operator-body" hx-swap="innerHTML" hx-disable="find button[type=submit]" hx-indicator="find .htmx-indicator">
<div id="form-operator.enrollment.grant.issue-error" class="app-form-error" role="alert"></div>
<div class="app-form-message mb-2">A tier product moves the pool to that tier, up or down.<div class="alert alert-warning py-1 px-2 small mt-2 mb-0" role="alert">Products marked ⚠ would supersede a tier a subscription pays for; its billing pauses until the grant ends.</div></div>
<div class="app-form-message mb-2">A tier product moves the pool to that tier, up or down.</div>
@@ -150,7 +150,7 @@
<label class="form-label" for="form-operator.enrollment.grant.issue-product_id-control">Product</label>
<select class="form-select" id="form-operator.enrollment.grant.issue-product_id-control" name="product_id" required aria-describedby="form-operator.enrollment.grant.issue-product_id-warning" hx-get="/partials/operator/products/rule-check" hx-swap="innerHTML" hx-target="#form-operator\.enrollment\.grant\.issue-product_id-warning" hx-trigger="change">
<select class="form-select" id="form-operator.enrollment.grant.issue-product_id-control" name="product_id" required data-hint-toggle="form-operator.enrollment.grant.issue-product_id-hint" aria-describedby="form-operator.enrollment.grant.issue-product_id-warning" hx-get="/partials/operator/products/rule-check" hx-swap="innerHTML" hx-target="#form-operator\.enrollment\.grant\.issue-product_id-warning" hx-trigger="change">
<option value="" disabled selected>Choose a product</option>
<option value="<product:Basic>">Basic</option>
<option value="<product:Forum>">Forum</option>
@@ -162,7 +162,7 @@
<option value="<product:Plus>">Plus</option>
<option value="<product:Pro>">Pro</option>
<option value="<product:Small>">Small</option>
<option value="<product:Small2>">Small2 ⚠</option>
<option value="<product:Small2>" data-shows-hint>Small2 ⚠</option>
<option value="<product:Starter>">Starter</option>
<option value="<product:Starter2>">Starter2</option>
<option value="<product:Top>">Top</option>
@@ -171,7 +171,7 @@
<div id="form-operator.enrollment.grant.issue-product_id-warning"></div>
<div id="form-operator.enrollment.grant.issue-product_id-hint" class="form-text" hidden>This grant would supersede a tier a subscription pays for; its billing pauses until the grant ends.</div>
</div><div id="form-operator.enrollment.grant.issue-quantity" class="mb-3 app-form-field">
@@ -548,7 +548,7 @@ Each claim is pinned by a deliberate break (`docs/testing.md`, "Prove a test wit
| 2 | `TestReconcile_MirrorsTheCollectionPause`, `TestSubscriptionCollectionPauseMigrationUpDownUp`, `TestConsoleReaderColumns`, `TestOverviewMonthlyRecurringLeavesOutAPausedSubscription` | The mirror, the migration, the reader role, O4 |
| 3 | `TestCollectionPauseWanted`, `TestDecideCollection`, `TestReconcile_AGrantOverTheSubscriptionRequestsThePause`, `TestApplyCollection_*` (eight), `TestOutbox_ReconcileSubscriptionAction`, trace goldens | D1, D2, D6 |
| 4 | `TestActsRequestSubscriptionReconciles` (one row per act), `TestConferGrantTxRequestsNothing`, `TestReconcileEndedRequestsTheOtherSubscriptions`, `TestSurplusEndRequestsTheOtherSubscriptions`, `TestIssueGrantHandlerRequestsAReconcile`, the demo seed's assertion | D4 |
| 5 | `TestDisplacementTitle` (rewritten, with the several-grants rows), `TestSubscriptionTitlesFor`, `TestDisplacedOnPage`, `TestSubscriptionsListMarksAPausedSubscription`, `TestOrgEnrollmentGolden` (`grant-over-subscription-paused`), `TestOrgEnrollmentIssueGrantPanel_Stacked`, `TestOrgEnrollmentProductsSection` | D16 |
| 5 | `TestDisplacementTitle` (rewritten, with the several-grants rows), `TestSubscriptionTitlesFor`, `TestDisplacedOnPage`, `TestSubscriptionsListMarksAPausedSubscription`, `TestOrgEnrollmentGolden` (`grant-over-subscription-paused`), `TestOrgEnrollmentProductsSection`; for 5.10, `TestOrgEnrollmentIssueGrantSupersedeHint`, `TestOperatorShellLoadsTheHintToggle`, `TestRenderHintOnChoiceFollowsTheChosenOption`, `TestInvariantsHintOnChoiceBelongsToAStackedSelectWithItsHint`, `TestGrantSupersedeHintWalkthrough` | D16, Copy W |
| 6 | `TestCollectionDrift`, `TestSweepCollectionDrift_*` (six), `TestSweepScheduledChangesWorkflowRunsTheCollectionSweepAfterAFailure` | D5 |
| 7 | `TestDeliverDisplaced_*` (including the ending holder's displaced subscription first), `TestHumanizeTransitionReason` rows, trace goldens | D7 |
| 8 | `TestDisplacedProducts` rows, `TestSubscriptionDisplacements_TheHolderRank`, `TestDisplacementHolderRankMigrationUpDownUp`, `TestReconcile_ATierAtOrAboveTheGrantTakesTheLadder`, `TestReconcile_AGrantBelowTheSubscriptionsTierKeepsTheLadder` | D8 |
@@ -58,6 +58,8 @@ None.
- `operator-billing-views`: modified "The subscriptions list marks a subscription that delivers nothing while another plan holds its ladder" (the paused title).
- `grant-resumption`: modified "Only the end of a replacing plan resumes a grant" (the ending act's delivery of a subscription is not a resumption and runs after it; a switch or a resume that takes the ladder replaces the grant) and "A grant waits on the nearest plan above it that has not ended" (its scenario's subscription is live while the operator's grant supersedes its position).
- `operator-panel-navigation`: added "The Monthly recurring headline leaves out a subscription whose collection is paused".
- `form-library`: added "A select's hint can wait for the option that shows it" (the mechanism behind Issue grant's supersession hint).
- `form-conventions`: modified "Every control has a label, and its hint and error are described" (a hint hidden until a choice shows it is described only while it shows).
## Impact
@@ -68,7 +70,8 @@ None.
- **Behaviour a deployment sees:** a grant over a paid tier stops the subscription's charges within seconds and resumes them when the grant ends, with the tier delivered in the same act; the member sees the paused plan, can cancel it, move it to the granted tier or above, or, under a lower grant, resume it; no second subscription on a ladder can be bought.
- **Deploy:** re-run `scripts/db-reader-role.sql` after the migrations so the reader role reads the three new columns (`docs/database-management.md`, "Running the script"). Nothing to backfill: the drift sweep pauses every subscription already displaced by a grant within an hour of the deploy (D19), and a read-only count before the push goes to the maintainer (task 13.3).
- **Tests:** unit tests of the rules, reconcile tests through the Stripe mock, database tests of each act's request and of the delivery step, the trace goldens, handler tests of the Products page, Checkout, the switch, Resume plan and Pay invoice, database tests of the resume act and its refusals, the organization page and subscriptions list titles, the migrations' up-down-up, and the Stripe sandbox walk at landing.
- **Docs:** `docs/stripe.md`, `docs/models/payments-billing.md`, `docs/models/plan-ladders-transitions.md`, `docs/plan-management.md`, `docs/database-locks.md`, `test/AGENTS.md`, `test/seed/member-console-demo/README.md`.
- **Forms library:** `internal/forms` gains a select's hint that waits for the option that shows it (`HintOnChoice`, `ShowsHint`), rendered by the field part and followed by one external script, `internal/embeds/static/hint-on-choice.js`, loaded by the operator shell.
- **Docs:** `docs/design-system.md` (§8 and the progressive-enhancement table), `docs/stripe.md`, `docs/models/payments-billing.md`, `docs/models/plan-ladders-transitions.md`, `docs/plan-management.md`, `docs/database-locks.md`, `test/AGENTS.md`, `test/seed/member-console-demo/README.md`.
## Related issues
@@ -0,0 +1,26 @@
## MODIFIED Requirements
### Requirement: Every control has a label, and its hint and error are described
Every form control SHALL have a `<label for>`; in a dense row with no room the label is visually hidden, never absent, and an `aria-label` SHALL NOT substitute for it. A label sits above its control, a checkbox's included: in the Stacked and Dense families a checkbox's label sits above the box, as every other field's label does, and nothing is written beside the box (grant-resumption design D19, 2026-09-29). This retires the placement beside the box, after it, that the boolean rule of 2026-09-03 set: a sentence to the right of a box in a dense row read as belonging to the field beside it, and one form placing its checkbox's label differently would leave the console with two checkbox patterns. The label still names the state the box turns on ("Listed", "Active", "Resumes"), which is the design system's boolean rule. The Table family carries every label, a checkbox's included, in its label column, and a control the Rows family renders in a table cell keeps its visually hidden label; neither changes. A Rows control in a card a row grows (a grant's Manage) shows its label above the control at every width, a checkbox's included. A field's hint SHALL carry an id referenced by the control's `aria-describedby` while the hint shows, and a hint that waits for a choice is hidden and not referenced until the chosen option shows it (`form-library`, "A select's hint can wait for the option that shows it"); a field's error SHALL carry an id also referenced, with `aria-invalid="true"` on the control while the error shows; a hint that shows SHALL remain when the error shows. The help icon SHALL render after the label as its sibling, never inside the `<label>`.
#### Scenario: A screen reader hears the hint and the error
- **WHEN** a control whose hint shows is refused
- **THEN** the control's `aria-describedby` names both the hint and the error, `aria-invalid` is true, and the hint is still visible
#### Scenario: No button inside a label
- **WHEN** a field with help renders
- **THEN** the help icon's button is a sibling of the label, not its child
#### Scenario: A checkbox's label sits above its box
- **WHEN** an operator opens a product's record page and the Issue grant panel
- **THEN** "Listed", "Active" and "Resumes" each render above their checkbox, as every other field's label does, with the help icon after the label and nothing written beside or under the box
- **AND** each label's `for` names its checkbox
#### Scenario: A checkbox in Manage's card keeps its label above the box
- **WHEN** an operator presses Manage on a grant's row
- **THEN** the Resumes checkbox in the card carries a visible `<label for>` naming it above the box, with its help icon after the label, and nothing is written beside the box, the label as close to the box as any label sits to its control
@@ -0,0 +1,26 @@
## ADDED Requirements
### Requirement: A select's hint can wait for the option that shows it
A select field of a Stacked-family form MAY declare `HintOnChoice` with its `Hint`, and each option the select offers MAY carry `ShowsHint`. The field part SHALL render the hint only when an option the select offers carries `ShowsHint`, and SHALL render it with the `hidden` attribute unless the selected option carries `ShowsHint`, in every mode: at rest, a select that opens on its placeholder renders the hint hidden, and a refused submission renders the hint shown when the submitted option carries `ShowsHint` and hidden otherwise. The control's `aria-describedby` SHALL name the hint only while it shows. The select SHALL name the hint's id in `data-hint-toggle`, and each option that shows it SHALL carry `data-shows-hint`. One external script, loaded with `defer` by the shell of every surface that renders such a field, SHALL show and hide the hint and add and remove its id in the select's `aria-describedby` when the choice changes, on load and after every htmx swap; without the script the hint SHALL stay as the server rendered it. The hint is the field's one declared line under its control and is checked as every declared hint is: the invariants SHALL refuse `HintOnChoice` on a control other than a select, in a family other than Stacked, without a `Hint`, or with a `Notice`.
#### Scenario: The hint waits for a choice
- **WHEN** a person opens a form whose `HintOnChoice` select offers an option that carries `ShowsHint`, and no option is chosen
- **THEN** the hint renders with `hidden`, the select names it in `data-hint-toggle`, and the select's `aria-describedby` does not name it
#### Scenario: Choosing the option shows the hint
- **WHEN** the person chooses an option that carries `ShowsHint`
- **THEN** the hint shows and the select's `aria-describedby` names it
- **AND** choosing an option that does not carry it hides the hint and removes its id from `aria-describedby`
#### Scenario: A refused submission keeps the hint of its choice
- **WHEN** a submission whose chosen option carries `ShowsHint` is refused
- **THEN** the 422 body renders the hint shown and named by the select's `aria-describedby`
#### Scenario: No option shows it, so no line renders
- **WHEN** the select offers no option that carries `ShowsHint`
- **THEN** the field renders no hint line and no `data-hint-toggle`
@@ -128,9 +128,9 @@ Sections 1 to 12 are one commit each, and their items are that commit's parts; s
- the list's paused title not rendered: caught by `TestSubscriptionsListMarksAPausedSubscription`, `want_new` `subscriptions list title =`.
- [x] 5.9 `make screens`: no change. No capture shows the warning: the captured organization's one subscription, Carlos's, holds no tier, so no product the Issue grant select offers carries the marker; the goldens of 5.5 pin the warning's text. The paused title is an attribute no capture shows; the golden pins it.
- [ ] 5.10 The supersession warning follows the choice (design Copy W; the spec's "Advisory warning when a grant would supersede a subscription-sourced position"). `issueGrantFormView` no longer adds the warning to the form's message; the lead stays. The Product field renders Copy W as its one hint line, hidden at rest and shown while the chosen option is one marked ⚠ (`IssuanceProductOption.SupersedesSubscription`), in the field's hint style, never an alert. A refused submission whose chosen product is marked renders it shown. The toggle is a general-purpose behaviour keyed by data attributes (a select names the hint it controls, and each marked option carries the attribute), in an external script under `internal/embeds/static/` loaded with `defer` (the CSP refuses inline scripts), so another form can reuse it; read `internal/forms` for how a field's hint and slots render and extend it there rather than writing markup in the handler. `issueGrantSupersedeWarning` keeps its name and reads Copy W.
- Tests: the render tests that compare the warning (`TestOrgEnrollmentIssueGrantPanel_Stacked`, `TestOrgEnrollmentProductsSection`, `rule_less_warning_test.go`) assert the hint is present and hidden at rest when a marked product is offered, absent when none is, shown in a refused submission that chose a marked product, and that the message holds the lead alone. A browser test (the walkthrough package's pattern, `test/e2e/operator-walkthroughs`) chooses a marked product and sees the hint, then an unmarked one and sees it hidden. The goldens `rich.html`, `rich-history-search.html` and `suspended-subscription.html`, rewritten with `-update` and read, change only in the message and the field's hint. Failure texts name the state (`at rest`, `after choosing a marked product`, `after choosing an unmarked product`, `in a refused submission`).
- Breaks: the hint rendered shown at rest; the hint rendered absent; the warning kept in the message; the script not loaded; the toggle inverted.
- [x] 5.10 The supersession warning follows the choice (design Copy W; the spec's "Advisory warning when a grant would supersede a subscription-sourced position"). `issueGrantFormView` no longer adds the warning to the form's message; the lead stays. The Product field renders Copy W as its one hint line, hidden at rest and shown while the chosen option is one marked ⚠ (`IssuanceProductOption.SupersedesSubscription`), in the field's hint style, never an alert. A refused submission whose chosen product is marked renders it shown. The toggle is a general-purpose behaviour keyed by data attributes (a select names the hint it controls, and each marked option carries the attribute), in an external script under `internal/embeds/static/` loaded with `defer` (the CSP refuses inline scripts), so another form can reuse it; read `internal/forms` for how a field's hint and slots render and extend it there rather than writing markup in the handler. `issueGrantSupersedeWarning` keeps its name and reads Copy W.
- Tests: `TestOrgEnrollmentIssueGrantSupersedeHint` (new), with `TestOrgEnrollmentProductsSection` for the hidden hint at rest, asserts the hint is present and hidden at rest when a marked product is offered, absent when none is, shown in a refused submission that chose a marked product, and that the message holds the lead alone. `TestOperatorShellLoadsTheHintToggle` pins the script's tag in the operator shell; the forms library's `TestRenderHintOnChoiceFollowsTheChosenOption` and `TestInvariantsHintOnChoiceBelongsToAStackedSelectWithItsHint` pin the field part and the invariant, and `TestInvariantsEscapeHatchKeys` refuses `data-hint-toggle` through the escape hatch. `TestGrantSupersedeHintWalkthrough` (`test/e2e/operator-walkthroughs`) chooses a marked product and sees the hint, named by the select's `aria-describedby`, then an unmarked one and sees it hidden and no longer named. The goldens `rich.html`, `rich-history-search.html` and `suspended-subscription.html`, rewritten with `-update` and read, change only in the message and the field's hint. Failure texts name the state (`at rest`, `after choosing a marked product`, `after choosing an unmarked product`, `in a refused submission`).
- Breaks: the hint rendered shown at rest; the hint rendered absent; the warning kept in the message; the script not loaded; the render-side toggle inverted; a marked option without its attribute; a stacked select's missing hint accepted; a hidden hint described. The script's toggle inverted and the script never describing the hint run as a second list whose preparation rebuilds and restarts the app on the broken tree, because the app embeds its static files.
- `make screens`: `operator-organization-detail-open` and `-invalid` change, at both widths: since section 7, Carlos Member's canceling subscription holds the Demo Ladder, so his form offers marked products and the accepted baseline shows the alert; hand captures at 1280 desktop width and 390 mobile width (emulated, `innerWidth` checked) of the open form with a marked product chosen, beside the change's screens.
## 6. An hourly sweep asks again for a subscription whose pause disagrees with the rule
@@ -0,0 +1,88 @@
// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial
// SPDX-FileCopyrightText: 2025-2026 Christian Galo
// walkthrough: grant-supersede-hint
// covers: GET /operator/organizations/{orgID}
//
// Issue grant's Product field carries the supersession warning as its one
// hint line (grant-pauses-subscription-billing Copy row W): hidden while no
// product is chosen, shown once the operator chooses a product marked ⚠,
// hidden again on an unmarked one. Nothing is submitted.
//
// The walkthrough needs an organization whose Issue grant form offers a
// product marked ⚠, which is an organization with a subscription on a
// ladder; it skips with that precondition named when none exists.
package operatorwalkthroughs_test
import (
"slices"
"strings"
"testing"
"git.coopcloud.tech/wiki-cafe/member-console/test/e2e/browsertest"
)
const markedProductOption = `form[data-form="operator.enrollment.grant.issue"] select[name="product_id"] option[data-shows-hint]`
func TestGrantSupersedeHintWalkthrough(t *testing.T) {
defer browsertest.Recover(t)
page, base := browsertest.OpenOperator(t, "/operator/organizations")
_, marked := gotoOrgCompositeWith(t, page, base, markedProductOption,
"no org's Issue grant form offers a product marked as superseding a subscription; run test/seed-demo.sh for a fresh subject")
// The toggle is a deferred script: a choice made before it runs meets no listener.
browsertest.WaitLoaded(t, page)
sel := marked.MustParent()
hintID := sel.MustAttribute("data-hint-toggle")
if hintID == nil || *hintID == "" {
t.Fatal("the Product select names no hint in data-hint-toggle")
}
hint := page.MustElement(`[id="` + *hintID + `"]`)
const copyW = "This grant would supersede a tier a subscription pays for; its billing pauses until the grant ends."
if got := strings.TrimSpace(hint.MustText()); got != copyW {
t.Errorf("the Product hint reads %q, want %q", got, copyW)
}
shown := func() bool { return !hint.MustProperty("hidden").Bool() }
described := func() bool {
d := sel.MustAttribute("aria-describedby")
return d != nil && slices.Contains(strings.Fields(*d), *hintID)
}
choose := func(value string) {
sel.MustEval(`(v) => { this.value = v; this.dispatchEvent(new Event("change", {bubbles: true})); }`, value)
}
t.Logf("at rest: the hint is hidden")
if shown() {
t.Error("at rest, the Product hint is shown")
}
if described() {
t.Error("at rest, the Product select's aria-describedby names the hint")
}
markedValue := *marked.MustAttribute("value")
t.Logf("after choosing a marked product: the hint is shown")
choose(markedValue)
if !shown() {
t.Error("after choosing a marked product, the Product hint is hidden")
}
if !described() {
t.Error("after choosing a marked product, the Product select's aria-describedby does not name the hint")
}
var unmarked string
for _, o := range sel.MustElements(`option`) {
if v := *o.MustAttribute("value"); v != "" && o.MustAttribute("data-shows-hint") == nil {
unmarked = v
break
}
}
if unmarked == "" {
t.Skip("the Product select offers no unmarked product to choose after the marked one")
}
t.Logf("after choosing an unmarked product: the hint is hidden")
choose(unmarked)
if shown() {
t.Error("after choosing an unmarked product, the Product hint is shown")
}
if described() {
t.Error("after choosing an unmarked product, the Product select's aria-describedby names the hint")
}
}