fix(bulma-ui): wire Taginput's suggestions as a combobox

[allxsmith]

What was wrong

With data, Taginput shows suggestions under its field. The arrow keys move a highlight through them and Enter adds the highlighted one, but none of that reached a screen reader. The input had no combobox role, nothing said a list was open, and nothing pointed at the highlighted suggestion. The role="listbox" had no id and no name, and its options had no ids, so nothing could have pointed at them anyway. A screen reader user typed, pressed Down Arrow, heard nothing, pressed Enter, and a tag appeared. Meanwhile the docs said the dropdown "follows ARIA listbox pattern".

What changes

With data, the input is a combobox. It gets the wiring Autocomplete got in #942, #998 and #1066, copied over and adapted to Taginput's markup:

• role="combobox", aria-autocomplete="list" and aria-haspopup="listbox".
• aria-expanded is true only while the list is on screen with suggestions in it. When nothing matches, Taginput renders no dropdown at all, so it's false.
• aria-controls points at the list only while the list is in the page, so it never dangles.
• aria-activedescendant points at the highlighted suggestion as the arrow keys or the mouse move it. It's dropped when nothing is highlighted: before the first arrow press, after Enter adds the highlighted suggestion and the list stays open, and when typing filters the list down past the highlight. It's dropped too while the highlight sits on a suggestion that's blank once trimmed, like an empty string in data, since that one can't become a tag.
• The input keeps its name: its own label, a surrounding Field's, or the aria-label="Add tag" fallback.

The list gets an id and a name. The existing .dropdown-content div already had role="listbox", so it stays the listbox and gains an id and a name. The name comes from the label that names the input, through aria-labelledby, using the same needsLabelId option of useAutoLabelId that names Autocomplete's list (#998). When no label names the input, or the one that does has no id to point at (a Field label wired by hand with no id in its labelProps), the list falls back to aria-label="Suggestions".

Each suggestion gets an id. The ids are ${listboxId}-${index}, from one useId per Taginput, so two Taginputs on a page never share one. aria-selected marks the option aria-activedescendant points at, which is the rule Autocomplete uses today, where that's always the highlighted one. Here it's the highlighted one too, except a blank suggestion, which is marked neither. Combobox can settle the library-wide rule later.

Without data, nothing changes. A Taginput with no data never shows a list, so a combobox role would announce a popup that can't open. It stays a plain text field with none of these attributes, and its label gets no id. "With data" means the prop is set, even to an empty array, so an app that loads suggestions as the user types keeps one role, not one that flips between textbox and combobox as results come and go. To tell the two apart, data lost its destructured [] default (the component reads dataProp ?? []), so the props table now shows no default for it.

What I left alone

• Behavior. Keyboard handling, tag creation and the look are unchanged, and so is Escape, which [Bug] bulma-ui: One Escape in a popup inside a Modal closes the Modal too #1077 is changing for popups and Modal.
• No empty content to move, and no status region. Taginput has no empty prop, and when nothing matches it renders no dropdown, so nothing non-option ever sat inside the list. Autocomplete's status region exists to announce its empty text, so it doesn't fall out of reusing the pattern here, and I didn't add one.
• No shared helper. Autocomplete's wiring is a handful of attributes and one computed id. Pulling it into a hook would mean touching Autocomplete for no gain right before Combobox replaces both, so it's copied and kept local.
• autoComplete="off". Autocomplete sets it and Taginput doesn't. Adding it would change how the browser's own suggestions behave, which isn't ARIA wiring, so it's left for Combobox.
• The list at maxTags. As on main, the list stays open after the last allowed tag unmounts the input. Closing it changes what renders, so it's left for [Bug] bulma-ui: Taginput's suggestion list stays open after the tag limit removes its input #1087.

Worth knowing

• A Taginput with data is now found by getByRole('combobox'), not getByRole('textbox'). That's the fix itself, but it breaks a consumer test that queries it the old way. This PR's own suites needed that change in 30 existing tests. A Taginput without data is still a textbox. It's worth a line in the release notes, the way fix(bulma-ui): announce Autocomplete's empty content, and keep its listbox to options #1068's markup note was.
• A labelled Taginput with data puts an id on its label, a generated one unless labelProps.id sets it, so the list has something to point at.

Tests

In Taginput.test.tsx, a new Taginput suggestions as a combobox (#1082) block:

• without data: a plain text field with no combobox attributes, and its label gets no id
• with data: a collapsed combobox named "Add tag", with aria-autocomplete="list", aria-haspopup="listbox", aria-expanded="false" and no aria-controls or aria-activedescendant
• with data={[]}: still a combobox, and it stays collapsed since no list opens
• typing or openOnFocus opens the list: aria-expanded="true" and aria-controls pointing at the listbox's id
• no suggestion matching, and a click outside closing the list, both leave it collapsed and pointing at nothing, with no id reference left dangling
• aria-activedescendant follows the highlight through Down, Down, Up and a mouse hover, with aria-selected="true" on that option only, and the option ids hold still while it moves
• keepFirst points it at the first option
• it's cleared after Enter adds the highlighted suggestion with the list still open, and when filtering leaves the highlight past the end of the list
• an empty or whitespace-only suggestion takes the highlight on screen but isn't pointed at or marked selected, Enter adds nothing there, and the next suggestion is pointed at as usual
• the listbox holds only role="option" children, each with an id
• two Taginputs get different listbox ids and no shared option id, and each one's aria-activedescendant stays its own
• the list is named by its own label, a surrounding Field's label, and a horizontal Field's label wired by hand into an inner Field, through a generated id or a labelProps.id of your own
• the list falls back to "Suggestions" with no label, under a label wired to another control, and under a Field label wired by hand with no id

The existing tests that render a Taginput with data now find its input as a combobox, 28 in Taginput.test.tsx and two in shadow-root.test.tsx. Nothing else in them changed.

Coverage for Taginput.tsx: lines, statements and functions stay at 100%, and the only branches missed are the same two as on main, the object-tag paths in addTag, which only strings reach.

Fail on the old behavior

With main's Taginput.tsx put back over this branch's tests, every new test fails except the two for a Taginput without data, which is the behavior that shouldn't change. The existing tests that now query a combobox fail too.

Most of the new ones fail at the role query, so I ran them again with main's file plus nothing but role="combobox" on the input. They all still fail, on the missing aria-* attributes, ids and list name, so they're testing the wiring and not just the role.

Visual check

The markup around the list doesn't change: the same elements, classes and nesting. What changes is attributes: the combobox ones on the input, an id and a name on the listbox div that was already there, ids on the options, and an id on the label. Neither Bulma's CSS nor bestax's SCSS selects on role, aria-* or id for anything in a Taginput, so I didn't take screenshots.

Docs and generated output

• The Accessibility section on the Taginput page now says what's wired, replacing the "follows ARIA listbox pattern" line.
• The TSDoc on data says it makes the input a combobox, and the TSDoc on label and labelProps says how the list gets its name.
• Field's TSDoc and its page, the label hooks' notes and the form skill name Taginput beside Autocomplete where a label's id names a suggestion list, so a label wired by hand gets an id for a Taginput too.
• The props tables and the MCP index are regenerated in the chore: regenerate commits. No listing in the distribution guide is affected.

Fixes #1082

[allxsmith]

deep-review: fresh

This fixes #1082. Taginput's suggestion list is now wired as a combobox, copying Autocomplete's pattern. The input gets role="combobox", aria-autocomplete="list", aria-expanded (true only while suggestions show), aria-controls (only while the list exists) and aria-activedescendant. The list is named through its label, or "Suggestions" when it has none. Each option gets a stable id.

The wiring applies only when data is set, even to []. A Taginput with no data can't open a list, so it stays a textbox. That's why data lost its = [] default. Keyboard handling, Escape, tag creation and the look are unchanged.

Review it in full. Above all, check:

• that every id reference stays valid as the list opens and closes;
• the list's accessible name in each label setup (own label, Field label, hand-wired label, none);
• the data-set rule and its effect on consumers who query by role;
• that the docs page's accessibility claim now matches the markup.

Post every finding, advisory included, as its own thread.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 3 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: allxsmith/bestax/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 15d35dbf-52bf-4f97-9fdf-6dd4daeb0708

📥 Commits

Reviewing files that changed from the base of the PR and between 730db1e and 490ff1a.

📒 Files selected for processing: 14

• bestax-mcp/data/components/Field.json
• bestax-mcp/data/components/Taginput.json
• bestax-mcp/data/skills.json
• bulma-ui/src/__tests__/shadow-root.test.tsx
• bulma-ui/src/form/Field.tsx
• bulma-ui/src/form/FormContext.tsx
• bulma-ui/src/form/Taginput.tsx
• bulma-ui/src/form/__tests__/Taginput.test.tsx
• bulma-ui/src/form/useAutoLabelId.ts
• docs/docs/api/form/field.md
• docs/docs/api/form/taginput.md
• skills/bestax-form/SKILL.md
• skills/bestax-form/references/api.md
• skills/bestax-form/references/patterns.md

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[github-actions]

Preview Deployment

Preview URL: https://823f5541.bestax.pages.dev

[claude]

Deep review — 0 blocking · 3 advisory

#	Severity	Area	Finding	Location
1	🔵 Advisory	Accessibility	Field's and useAutoLabelId's TSDoc still name only Autocomplete as naming a suggestion list from the Field label; field.md and the MCP index are generated from it	bulma-ui/src/form/Taginput.tsx:307 (subject: Field.tsx:35,39, useAutoLabelId.ts:28)
2	🔵 Advisory	Accessibility	At maxTags the input unmounts while the listbox stays on screen — orphan named listbox, aria-selected options that do nothing, focus dropped to <body> (pre-existing)	bulma-ui/src/form/Taginput.tsx:733
3	🔵 Advisory	Accessibility	activeOptionId/aria-selected guard on index-in-range while Enter guards on truthiness, so an empty-string suggestion announces as selected but cannot be chosen	bulma-ui/src/form/Taginput.tsx:644

Overall: The change is sound and lands the fix the issue asked for. I traced every IDREF through useAutoLabelId by hand — own label, outer Field (plain, grouped, hasAddons), hand-wired labelProps.htmlFor with and without an id, maxTags, and the open-to-closed transition — and found no path that leaves aria-controls, aria-activedescendant or aria-labelledby pointing at nothing: aria-controls and aria-activedescendant are gated on the same listOpen that renders the list in the same commit, and at maxTags labelled goes false so the list falls back to aria-label="Suggestions" rather than dangling. The wiring mirrors Autocomplete.tsx:498-640 closely, which is the right call for a component Combobox will replace. Tests (156 across Taginput.test.tsx and shadow-root.test.tsx) pass, tsc --noEmit is clean, prettier is clean, and Taginput.tsx holds 100% statements/lines/functions with 98.93% branches — the only misses are the pre-existing object-tag paths at lines 353-355, matching the PR body's claim. The data-set rule checks out: data = dataProp ?? [] keeps caller identity when set, and only data.length reaches the useCallback dep arrays, so the fresh [] on the undefined path memoizes nothing away. The riskiest part is the consumer-facing role flip — a data-bearing Taginput is no longer getByRole('textbox') — but that is the fix itself, it matches the fix(bulma-ui) precedent set by the Autocomplete work in #942/#998/#1066, and the first line of the squash message states it. Look at finding 3 first; it is the only one with a code change behind it.

Residual risk:

• Dangling IDREFs as the list opens and closes — refuted. listOpen gates the listbox element, aria-controls and aria-activedescendant in one render, so they commit together; the new danglingIdRefs helper checks all four attributes (aria-labelledby, aria-controls, aria-activedescendant, for) across no-match, click-outside and all three label setups. I separately traced the two cases the tests do not cover — maxTags reached with the list open, and a grouped/hasAddons Field — and both resolve to listLabelId === undefined, i.e. the "Suggestions" fallback, not a dangling reference.
• Stale highlightedIndex after the match set shrinks — refuted. activeOptionId's upper bound and handleKeyDown's filteredData[highlightedIndex] drop out together for an out-of-range index, and the suite covers it ("drops aria-activedescendant when filtering leaves the highlight behind"). The one place the two guards diverge is an empty-string suggestion, posted as finding 3.
• Collision between two Taginputs' generated ids — refuted. listboxId comes from a useId() distinct from useAutoLabelId's, and the test "gives each Taginput its own listbox and option ids" asserts set-uniqueness across frameworks.length * 2 option ids plus per-instance aria-controls/aria-activedescendant.
• Other surfaces still claiming the old semantics — refuted. A grep for "ARIA listbox" across docs/, skills/, bestax-mcp/data/ and bulma-ui/src returns nothing after the change; the only remaining stale prose is the Field/useAutoLabelId TSDoc in finding 1. No skills/ page documents Taginput's accessibility, and the eslint-plugin metadata carries deprecations only, so dropping data's destructured default does not stale it.
• Open, by design: nothing announces the arrival or count of matches, and going from matches to no matches collapses the list silently — aria-expanded flipping is the only signal. The PR declines a status region with a reason (Autocomplete's exists to speak its empty text, which Taginput has no equivalent of), so Taginput sits at parity with an Autocomplete that has no empty. Recorded rather than raised.
• Open, not reachable from this diff: autoComplete="off" is on Autocomplete's input and not Taginput's, so a browser autofill popup can still overlay the suggestion list. Unchanged by this PR and deliberately deferred to Combobox.

🏄 Clean little a11y set, brah — paddled right into Autocomplete's wake and caught the same wave, no wipeouts on the id refs. Three mellow advisories floating out back, nothing that'll hold up the lineup. Good to go.

[allxsmith]

deep-review: verify

Every open thread has a reply: fixed, with the commit, or refuted with a reason. This settles them on 490ff1a.

[github-actions]

Preview Deployment

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

[claude]

Deep review (verify) — 3 resolved · 0 open

#	Severity	Area	Thread	Outcome
1	🔵 Advisory	Accessibility	Field docs named Autocomplete alone as naming a suggestion list	Fixed — resolved
2	🔵 Advisory	Accessibility	At maxTags the listbox outlives its combobox	Accepted (deliberate, tracked in #1087) — resolved
3	🔵 Advisory	Accessibility	aria-activedescendant looser than the Enter guard	Fixed — resolved

What I checked

1 — Field docs. Field.tsx:35 now names "An Autocomplete or a Taginput" as naming the open suggestion list after the label, Field.tsx:39 names both in the aria-labelledby sentence and again in the labelProps.id sentence that the third labelSources case of this PR depends on, and useAutoLabelId.ts:30 names both suggestion lists with #998 and #1082. The change went further than the finding asked: FieldLabel TSDoc, FormContext.tsx:276, the two hand-written Field page lines, and the form skill SKILL.md, references/api.md and references/patterns.md. I ran pnpm run gen:mcp:check and pnpm run gen:catalog:check — both clean — so docs/docs/api/form/field.md (7 Taginput mentions) and bestax-mcp/data/components/Field.json carry it.

2 — orphaned listbox. The reason holds. The behaviour predates the PR, the fix changes what every user sees (the list would close as the last allowed tag goes in), it flips Taginput.test.tsx:216, and it forces a decision about the now-unreachable maxTags check inside addTag. #1087 is open and carries the repro, the one-line gate and that follow-on question, so this is a tracked deliberate deferral rather than a bare out-of-scope.

3 — activedescendant guard. activeOptionId at Taginput.tsx:648-651 is now gated on listOpen plus an optional-chained .trim() of the highlighted entry of filteredData. The optional chaining covers a highlighted index of -1 and any out-of-range index, so dropping the explicit upper-bound comparison loses nothing, and data is typed as an array of strings, which makes the .trim() always safe. The aria-selected on each option at :754 is now derived from the same activeOptionId, so the announced option and the pointed-at option can no longer diverge. The new it.each over an empty-string entry and a whitespace-only entry asserts the blank row keeps is-active, reports aria-selected="false", draws no aria-activedescendant, swallows Enter, and that the next ArrowDown points at Vue. Full Taginput.test.tsx plus Field.test.tsx run: 371 passed.

Overall: This pass settled the three threads the earlier deep review left open and reviewed no commits — two verified fixed against the current code, one accepted as a reasoned deferral with a tracking issue. Nothing of mine is left open; a reader who wants 1a7e6daf, 8f02a403 and 490ff1ae themselves reviewed should ask for a fresh pass.

Residual risk: not assessed — a verify pass settles threads and does not hunt for new failure modes.

🏄 Three threads paddled in clean, dude — two patched tighter than asked and one parked in its own issue with a proper note. Board is waxed, no open sets on the horizon.

[github-actions]

📸 Story screenshots at handoff — 490ff1a

12 stories (light + dark) from this PR's changed files under bulma-ui/src/ (workflow run · artifact story-screenshots-pr-1084, 30-day retention).

form-field--default · Form/Field · Default

Light	Dark

form-field--with-help-text · Form/Field · With Help Text

Light	Dark

form-field--labels-custom-controls · Form/Field · Labels Custom Controls

Light	Dark

form-field--labels-composed-pickers · Form/Field · Labels Composed Pickers

Light	Dark

form-field--validation-states · Form/Field · Validation States

Light	Dark

form-field--label-sizes · Form/Field · Label Sizes

Light	Dark

form-taginput--default · Form/Taginput · Default

Light	Dark

form-taginput--with-icon · Form/Taginput · With Icon

Light	Dark

form-taginput--with-autocomplete · Form/Taginput · With Autocomplete

Light	Dark

form-taginput--restrict-to-list · Form/Taginput · Restrict To List

Light	Dark

form-taginput--default-tags · Form/Taginput · Default Tags

Light	Dark

form-taginput--limits · Form/Taginput · Limits

Light	Dark

> ✂ 36 more matched stories skipped by the cap: `form-field--horizontal`, `form-field--horizontal-explicit-body`, `form-field--horizontal-narrow`, `form-field--grouped`, `form-field--grouped-centered`, `form-field--grouped-right`, `form-field--grouped-expanded`, `form-field--grouped-multiline`, `form-field--addons`, `form-field--addons-with-select`, … — full set in the artifact.

[bestax-release-bot]

🎉 This PR is included in version 5.34.1 🎉

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.25.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 1.15.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 4.2.17 🎉

The release is available on:

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

Your semantic-release bot 📦🚀