fix(bulma-ui): name Rate, Checkboxes, and Radios groups from their labels via aria-labelledby

[allxsmith]

Closes #494. Stacked on #496 (merge that first; GitHub will retarget this to main).

What

The convenience label prop on the three group inputs rendered an unassociated Field label. A group of controls can't take a single htmlFor, so the new useAutoLabelledBy hook (sibling of #492's useAutoLabelId) does it group-style: the rendered <label> gets an id — yours via labelProps.id, or a generated one — and the group container points at it with aria-labelledby.

• Checkboxes: wrapper gains role="group" + aria-labelledby.
• Radios: wrapper gains role="radiogroup" + aria-labelledby.
• Rate: container keeps its role="radiogroup"; the hardcoded aria-label="Rating" becomes a fallback, so a wired label actually names the group (aria-label would otherwise win). Unlabeled Rate keeps announcing "Rating" exactly as before.

The merged labelProps carry htmlFor: undefined, so group labels are never wired control-style (also forward-compat with the #495 PR next in this stack). A caller-supplied role or aria-labelledby still wins — {...rest} spreads after the literal attributes, the existing convention.

Behavior changes to review

• New role attributes on the Checkboxes/Radios wrapper divs (semantics only; no [role=] selectors exist in the SCSS, and all existing getByRole('radiogroup') queries are name-less).
• getByRole('group', { name }) / getByRole('radiogroup', { name }) now resolve from the label prop.

Tests

New describe('… group label association (#494)') blocks in all three suites: name resolution via role queries, label id === aria-labelledby, user labelProps.id respected, unlabeled → no aria-labelledby (Rate keeps its fallback), inside-Field no injection, and rest-override wins. All React 18/19-safe. pnpm all green.

Docs / skill

Accessibility sections updated on checkboxes.md, radios.md, rate.md (rate.md now documents the previously undocumented aria-label fallback); TSDoc drives the regenerated props tables; skills/bestax-form now describes group-style association, leaving only Field-composed usage as manual (that's #495, next in the stack).

Summary by CodeRabbit

• Accessibility

  • Added optional group labels and label properties to checkbox, radio, and rating controls.
  • Improved screen reader association using appropriate group roles and aria-labelledby, with support for generated or custom label IDs.
  • Preserved fallback labeling for unlabeled rating groups.

• Documentation

  • Updated form accessibility guidance and component documentation with labeling behavior and usage details.

• Tests

  • Added regression coverage for automatic, custom, missing, and nested group labels.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 260ca012-8f85-4ff0-b060-2c5975059baa

📥 Commits

Reviewing files that changed from the base of the PR and between 0f9267e and 3b3aaaf.

📒 Files selected for processing (11)

• bulma-ui/src/form/Checkboxes.tsx
• bulma-ui/src/form/Radios.tsx
• bulma-ui/src/form/Rate.tsx
• bulma-ui/src/form/__tests__/Checkboxes.test.tsx
• bulma-ui/src/form/__tests__/Radios.test.tsx
• bulma-ui/src/form/__tests__/Rate.test.tsx
• bulma-ui/src/form/useAutoLabelId.ts
• docs/docs/api/form/checkboxes.md
• docs/docs/api/form/radios.md
• docs/docs/api/form/rate.md
• skills/bestax-form/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (11)

• docs/docs/api/form/checkboxes.md
• bulma-ui/src/form/tests/Radios.test.tsx
• docs/docs/api/form/radios.md
• bulma-ui/src/form/useAutoLabelId.ts
• bulma-ui/src/form/tests/Rate.test.tsx
• bulma-ui/src/form/Rate.tsx
• bulma-ui/src/form/tests/Checkboxes.test.tsx
• bulma-ui/src/form/Checkboxes.tsx
• docs/docs/api/form/rate.md
• skills/bestax-form/SKILL.md
• bulma-ui/src/form/Radios.tsx

---

Walkthrough

Checkboxes, Radios, and Rate now support accessible group labels through role and aria-labelledby. A shared hook manages generated or explicit label IDs. Tests and documentation cover labeling, nesting, fallback, and precedence behavior.

Changes

Accessible form group labeling

Layer / File(s)	Summary
Label association hook bulma-ui/src/form/useAutoLabelId.ts, bulma-ui/src/form/fieldProps.ts	The shared hook resolves explicit or generated label IDs, returns aria-labelledby, and removes htmlFor from group labels.
Group component wiring bulma-ui/src/form/Checkboxes.tsx, bulma-ui/src/form/Radios.tsx, bulma-ui/src/form/Rate.tsx	The components expose label and labelProps, apply group roles and label associations, and pass normalized label props to Field.
Accessibility validation and guidance bulma-ui/src/form/__tests__/*.test.tsx, docs/docs/api/form/*.md, skills/bestax-form/SKILL.md	Tests cover generated and explicit IDs, unlabeled groups, nested fields, fallback labeling, horizontal radios, and precedence. Documentation describes automatic group labeling.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GroupComponent as Checkboxes/Radios/Rate
  participant LabelHook as useAutoLabelledBy
  participant Field
  participant GroupContainer as group container
  GroupComponent->>LabelHook: resolve label ID and field label props
  GroupComponent->>Field: pass normalized label props
  GroupComponent->>GroupContainer: set role and aria-labelledby

Loading

Possibly related PRs

• allxsmith/bestax#492: Extends the same label-association utilities for single-control inputs.
• allxsmith/bestax#496: Extends form component label handling.

Suggested labels: needs-human-review

Suggested reviewers: bestaxbot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main accessibility fix for Rate, Checkboxes, and Radios group labels.
Description check	✅ Passed	The description covers the changes, affected components, linked issue, behavior, tests, documentation, and stacking context.
Linked Issues check	✅ Passed	The changes satisfy issue #494 by adding group roles, label IDs, aria-labelledby, htmlFor removal, and Rate fallback behavior.
Out of Scope Changes check	✅ Passed	The implementation, tests, accessibility documentation, and skill guidance directly support the linked issue objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/494-group-aria-labelledby

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Deep review — 0 blocking · 2 advisory

#	Severity	Area	Finding	Location
1	🔵 Advisory	Accessibility	<Field label><Radios/Checkboxes/Rate/></Field> composition still leaves the group unnamed (Rate announces the hardcoded "Rating", not the visible label) — the deliberate #494→#495 hand-off, on the record.	Rate.tsx:521
2	🔵 Advisory	Coverage	Horizontal-layout label association (horizontal nests the label in FieldLabel) is not exercised by a test; it works by construction since the <label> still receives the id.	Field.tsx:224

Overall: The change is sound and lands cleanly. useAutoLabelledBy is a faithful group-style sibling of useAutoLabelId — same active = !!label && rendersLabel gate, same labelProps.id ?? generated resolution, same htmlFor: undefined merge — and the active gate keeps aria-labelledby and the Field's if (label) render gate in lockstep, so there is never a dangling id reference. I verified end-to-end: typecheck clean, all 1419 form tests green including the three new #494 blocks, and the role queries resolve the name from the label prop. The riskiest part is purely the accepted residual (row 1); the human should confirm they are comfortable shipping the Field-composed gap as documented and picking it up in #495.

Residual risk: the ways an unassociated-group-label (#494) can still occur:

• Field-composed usage — refuted as a known, deliberate deferral: the PR body, skills/bestax-form, and the component TSDoc all state the group only self-associates when it renders its own Field; #495 is next in the stack. Row 1 records it.
• Unlabeled group — <Radios>/<Checkboxes> with no label now render an unnamed role="radiogroup"/"group". Not a regression (naming was absent before too) and an unnamed group role is valid; the explicit role is a net semantic improvement over the prior role-less div.
• User override collision — checked: role/aria-labelledby literals sit before {...rest}, so a caller value wins (tested for Checkboxes; Rate spreads rest last over its explicit attrs). When label + a rest aria-label coexist on Rate the element carries both, but aria-labelledby wins in AT — harmless.

🏄 Clean set, dude — this one just points the group at its own label sign and paddles out. No gnarly wipeouts in the impl; the only ripple left is the Field-composed break they already promised to catch on the next wave (#495). Good to go.

[github-actions]

Preview Deployment

Preview URL: https://d0c28e6e.bestax.pages.dev

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bulma-ui/src/form/useAutoLabelId.ts`:
- Around line 77-80: Prevent active group labels from restoring single-control
labeling by spreading labelProps before the active overrides in useAutoLabelId,
ensuring htmlFor remains undefined and id is labelId. In
bulma-ui/src/form/__tests__/Checkboxes.test.tsx lines 212-276, add a regression
test supplying labelProps.htmlFor and assert the rendered label has no for
attribute.

In `@skills/bestax-form/SKILL.md`:
- Around line 128-131: Update the checklist near the group-input accessibility
guidance to remove manual htmlFor wiring requirements for the Checkboxes,
Radios, and Rate convenience components, which automatically associate their
label props. Retain manual wiring guidance only for controls composed from Field
plus base inputs, and preserve the existing distinction for maxTags.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a579906f-0c8b-43ec-841d-62cccd688d89

📥 Commits

Reviewing files that changed from the base of the PR and between 73cec33 and 0f9267e.

📒 Files selected for processing (12)

• bulma-ui/src/form/Checkboxes.tsx
• bulma-ui/src/form/Radios.tsx
• bulma-ui/src/form/Rate.tsx
• bulma-ui/src/form/__tests__/Checkboxes.test.tsx
• bulma-ui/src/form/__tests__/Radios.test.tsx
• bulma-ui/src/form/__tests__/Rate.test.tsx
• bulma-ui/src/form/fieldProps.ts
• bulma-ui/src/form/useAutoLabelId.ts
• docs/docs/api/form/checkboxes.md
• docs/docs/api/form/radios.md
• docs/docs/api/form/rate.md
• skills/bestax-form/SKILL.md

[Copilot]

Pull request overview

Adds accessible group labeling for Checkboxes, Radios, and Rate using aria-labelledby.

Changes:

• Adds group roles and automatic label IDs.
• Preserves Rate’s fallback accessible name.
• Updates tests, documentation, and form skill guidance.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
skills/bestax-form/SKILL.md	Documents group label association.
docs/docs/api/form/rate.md	Documents Rate accessibility behavior.
docs/docs/api/form/radios.md	Documents Radios group semantics.
docs/docs/api/form/checkboxes.md	Documents Checkboxes group semantics.
bulma-ui/src/form/useAutoLabelId.ts	Adds the group-labeling hook.
bulma-ui/src/form/Rate.tsx	Associates labels with the rating group.
bulma-ui/src/form/Radios.tsx	Adds radiogroup labeling.
bulma-ui/src/form/fieldProps.ts	Updates association guidance.
bulma-ui/src/form/Checkboxes.tsx	Adds checkbox-group labeling.
bulma-ui/src/form/__tests__/Rate.test.tsx	Tests Rate label association.
bulma-ui/src/form/__tests__/Radios.test.tsx	Tests Radios label association.
bulma-ui/src/form/__tests__/Checkboxes.test.tsx	Tests Checkboxes label association.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (2)

bulma-ui/src/form/Checkboxes.tsx:130

• {...rest} can only make a caller-supplied role win at runtime, but CheckboxesProps does not expose role (or div attributes), so TypeScript consumers cannot use the override promised by this change. Add a typed role?: React.AriaRole or extend the appropriate HTMLAttributes<HTMLDivElement> subset, then regenerate the props documentation.

      role="group"

bulma-ui/src/form/Radios.tsx:132

• {...rest} can only make a caller-supplied role win at runtime, but RadiosProps does not expose role (or div attributes), so TypeScript consumers cannot use the override promised by this change. Add a typed role?: React.AriaRole or extend the appropriate HTMLAttributes<HTMLDivElement> subset, then regenerate the props documentation.

      role="radiogroup"

[github-actions]

Preview Deployment

Preview URL: https://0db3a4b7.bestax.pages.dev

[bestax-release-bot]

🎉 This PR is included in version 5.8.4 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 5.9.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 4.0.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 2.0.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀