docs(FormField): document and exemplify the `#label` slot

[IgorShevchik]

Summary

B24FormField already exposes a #label slot, but it is undocumented and has no usage example. Developers reading the docs only see the label prop (a plain string) and have no signal that a richer, custom label is possible without overriding internals.

Current state (the slot exists)

src/runtime/components/FormField.vue declares and renders the slot:

// FormField.vue (slots interface)
export interface FormFieldSlots {
  label?(props: { label: string | undefined }): VNode[]
  // ...
}

<!-- FormField.vue (template) -->
<Label :for="id" data-slot="label" :class="b24ui.label({ class: props.b24ui?.label })">
  <slot name="label" :label="props.label">
    {{ props.label }}
  </slot>
</Label>

So the capability is shipped and working — this is not a feature request to add the slot.

The gap

docs/content/docs/2.components/form-field.md documents only the label prop (the "Label" section). There is:

• no mention of the #label slot,
• no example showing a rich label (e.g. label text + a trailing help/info icon or tooltip, a badge, or an inline link).

This is the real-world need behind "rich labels" that comes up in record-edit / CRM forms (e.g. a field label with a help tooltip next to it).

Proposed changes

• Add a "Label slot" subsection to form-field.md with a ::component-code example, e.g. a label composed of text + a small help icon/tooltip via the #label slot.
• Note in the forms skill guideline that #label is available for custom labels (one line + snippet).
• Optionally cross-link from the label prop section to the slot section.

Out of scope / for discussion

A separate, distinct gap (not this issue): there is no built-in "titled, bordered field-group / fieldset" primitive for grouping several FormFields under one labeled box (the "Client" sub-section pattern). If we want that, it should be its own issue/PR for a B24FieldGroup-style fieldset variant — please confirm interest before scoping.

Context: surfaced while reviewing the record-edit form example (branch claude/bitrix24-ui-layout-U2iTb).

[IgorShevchik]

Shipped in #461 — the #label slot is on the page now, with a runnable example. 🏷️

You called it exactly right: capability shipped, discoverability missing. Verified before touching anything — the slot renders (FormField.vue:122-126), passes label through, and has had a snapshot case all along. The docs just never said so outside a generated API table, and nobody reads one of those to find out something is possible.

<B24FormField label="Email" name="email">
  <template #label="{ label }">
    {{ label }}
    <B24Badge label="Work" size="xs" aria-hidden="true" />
  </template>

  <B24Input placeholder="Enter your email" />
</B24FormField>

Two things the review caught that are worth knowing if you use this:

aria-hidden on that badge is not decoration. Anything inside #label joins the control's accessible name, so without it a screen reader announces "Email Work". Same reason the docs no longer suggest putting a link in there — a <label> toggles its control when activated, so a link inside fires both.

#error and #help are not drop-in equivalents of their props, unlike #hint and #description. The error block renders whenever an #error slot exists — error or not — and help is the v-else-if on that same branch, so supplying #error hides help for good. That's now a caution box on the page rather than something you find out in production.

Also added two tests, since the docs now promise things nothing asserted: that the for/id association survives a custom slot, and that { label } actually arrives. Removing just the for binding fails 31 tests now — before, it passed the snapshot.

The other half of this issue is not forgotten. The fieldset/<legend> primitive for grouping fields under one heading — the "Client" sub-section pattern, which you explicitly asked to confirm interest on before scoping — is carried forward as #463 with the naming collision (B24FieldGroup already means something else) and the <fieldset> accessibility implications written down. It needs a yes/no from you, not a PR.

And #462 tracks giving the remaining four slots the same treatment, now that the scaffolding exists.

Thanks for filing it with the source lines already located — and for flagging your own uncertainty on it, which is what made checking first the obvious move. 🙏

---

Generated by Claude Code