docs(FormField): document the four remaining slots, and what #error actually does

[IgorShevchik]

Linked issue

Resolves #462 · uncovered #497

Type of change

• Documentation (updates to the documentation or readme)
• Bug fix (a non-breaking change that fixes an issue)
• Enhancement (improving an existing functionality)
• New feature (a non-breaking change that adds functionality)
• Chore (updates to the build process or auxiliary tools and libraries)
• Revert (undoing a merged change — retitle this PR revert(Scope): ...)
• Breaking change (fix or feature that would cause existing functionality to change)

src/ is untouched. Nothing is fixed here — a real defect is documented and pinned, and filed as #497.

Description

#461 documented #label. The other four slots had no examples, so the only signal they exist was the generated API table — which nobody reads to discover a capability.

Writing the examples turned up two behaviours, and the review round turned up that I had only half-understood the second one.

A hint needs a label

It renders inside the label row, and the component only draws that row when label or #label is present. So hint on a label-less field renders nothing, silently. That is also why with hint and with hint slot were byte-identical to with b24ui in the snapshots — two more of the vacuous cases #454 was about, sitting in its baseline. Both now pass a label; the baseline shrinks from 293 groups to 291.

The blocks and the announcement disagree

FormField decides what to render from props.x || !!slots.x, and what to announce from the props alone:

// useFormField.ts:127
const descriptiveAttrs = ['error', 'hint', 'description', 'help']
  .filter(type => formField?.value?.[type])   // ← props, via provide(). No slots.

Measured, across all five blocks:

what is passed	block on screen	named in aria-describedby
description prop	yes	yes
#description slot, no prop	yes	no
#hint slot, no prop	yes	no
#help slot, no prop	yes	no
hint prop, no label	no	yes

The first version of this PR taught the broken shape. Every example used the slot without the prop, which is exactly the row where the announcement disappears — and three statements on the page were false as written: that the hint is announced through aria-describedby, that the description association "is unchanged", and that #help has no trap of its own. All three are gone.

The page now leads with the rule that fixes all five — set the prop, use the slot for markup — which is the shape #label has had since #461.

#error keeps its own section, because its v-if is satisfied by the slot's mere existence:

v-if="props.error !== false && ((typeof error === 'string' && error) || !!slots.error)"
v-else-if="props.help || !!slots.help"

An #error slot with no error value: a red error block on screen, help gone, aria-invalid="false", and aria-describedby naming a …-help that is no longer in the document. The recommended pattern — bind error to the message or to false — is spelled out with its three states, and the section admits that even its "good" row still names …-help while the block is not rendered.

Checked against upstream first

Per PORTING.md §7, before writing a word: git -C <mirror> show <cursor>:src/runtime/components/FormField.vue. The component and the composable are line-for-line identical to nuxt/ui. So this is upstream's design, fixing it here is a deliberate divergence that a later port would silently revert, and that decision belongs in its own change rather than in a documentation PR. Filed as #497 with the measurements and three repair options.

Tests

The issue asked for these, and it was right — the existing snapshot cases assert neither the association nor the scoped payload. Review found my first attempt was itself vacuous for the case that mattered.

• the association surviving the #hint / #description slots with the prop set — the recommended shape;
• three slot-only cases pinning the missing association — the shape the docs used to teach, which the prop-and-slot test could not see;
• the dangling …-hint when hint is set without a label;
• all three states of the #error branch, including the dangling reference;
• the scoped payload arriving in each slot;
• binds hints with aria-describedby — pre-existing — gains a label and an assertion that the id resolves. It checked one end of an association, which is how the dangling reference stayed hidden.

Each characterization test points at #497, so when the defect is fixed they fail and mark the documentation that has to change with them.

Also

documentation.md gains the command that checks a page renders, corrected after review to name pnpm dev:prepare and to say that CI runs docs:full:generate (pnpm build && pnpm docs:generate) — the environment is not the only difference. MDC fails at render time, and without the NUXT_PUBLIC_* variables the build dies with ERROR completable is not defined, a @nuxtjs/mcp-toolkit symbol with nothing to do with your page. Confirmed identical on a clean main before writing that down.

skills/b24-ui-nuxt/references/guidelines/forms.md is mirrored and restructured: the #label example had been orphaned under the new prose, v-else said where the component says v-else-if, and description described as "below the input" when it renders above.

Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

Gate: lint 0 · typecheck 0 · test 314/314 · test:module 3/3 · test:workflows 49/0 · skill:check clean · baseline regenerates to 291/870 with no drift · docs:generate 1264 routes, form-field among them.