Skip to content

fix(Tokenizer): a collapsed unfocusedLayer field keeps a tab stop on its placeholder - #12486

Draft
cixzhang wants to merge 3 commits into
mainfrom
l0/tokenizer-layer-tab-stop
Draft

cixzhang wants to merge 3 commits into
mainfrom
l0/tokenizer-layer-tab-stop

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

User impact

  • Who: keyboard and screen-reader users of a Tokenizer with tokenOverflowBehavior="unfocusedLayer".
  • Before (real Chromium): with the field collapsed, Tab reached only the visible tokens' Remove buttons and then left the field. The input lives in a closed layer, so it was never reached; a field with no tokens could not be reached at all. A disabled field had no tab stop at all, with or without disabledMessage (WCAG 2.1.1; spec:AST-085 FR1).
  • After: the collapsed field's placeholder is its one tab stop, before the tokens' own controls. Focusing it opens the field and moves focus to the input in the same step, as a click does. A disabled field keeps that stop: it is exposed as disabled, shows its disabledMessage, and opens nothing. No element is natively disabled.
  • Unchanged: the layout, the expanded layer, the tokens' Remove buttons and their stops, pointer behaviour, and the other overflow modes.

What changed

  • Tokenizer.tsx, layer mode: the placeholder is a role="group" named by the field label (not a control, because it holds the tokens' controls). It carries the field's description and status, has tabIndex 0 while collapsed and -1 while open, and aria-disabled when disabled. Its own focus opens the layer and moves focus to the input; focus on a token inside it stays put. The disabled-message tooltip anchors to the placeholder. The input in the layer is now focusable-disabled, like every other mode.
  • component:Tokenizer FR3 gains a consistency sentence naming the placeholder as the collapsed field's tab stop. The prop docs no longer say the layer-mode input is natively disabled.
  • A new story, "Overflow Layer States": an empty field, a disabled field, and a disabled field with a message.
  • [fix] changeset.

Evidence

  • Red first, real browser: TokenizerLayerFocus.a11y.browser.spec.ts "Tab reaches a collapsed field with tokens…" fails on main (focus lands on a Remove button) and passes here.

  • Chromium, this head: 4 of 4 cases pass, repeated 3 times (12 of 12).

    • Tab reaches the field with tokens and with none, and typing lands in the input.
    • Disabled, with and without a message: Tab reaches the placeholder, it is exposed as disabled, it shows the focus ring, Enter or typing opens nothing, and the message tooltip shows; no [disabled] element is in the page.
    • A mouse press on a disabled placeholder focuses it with no ring.
    • Shift+Tab out of an open field returns to the page order and closes it.
  • Disabled focus ring (spec:AST-085 FR6): at 3cec2d3 a disabled placeholder took Tab focus but drew no indicator. Here, Owners focused is pixel-identical to unfocused, and Approvers shows only its tooltip:

    Unfocused Owners after Tab (3cec2d3) Approvers after Tab (3cec2d3)
    unfocused Owners, no ring Approvers, tooltip only

    The placeholder now restores the field's focus ring on its own :focus-visible, through the shared inputDisabledFocusStyles (selfRing, beside ring and nestedRing). Tab shows the ring and a mouse press shows none. The browser case for the ring fails at 3cec2d3 and passes here; pointer focus shows no ring on both. After the fix (57ee36d; Chromium, evidence farm): Tab shows the ring on both disabled placeholders, a mouse press shows none, and the unfocused page is byte-identical to before. Because a disabled field draws at half opacity, the ring's border renders at 3.36:1 against the white page, a small margin over WCAG 1.4.11's 3:1, and 2.77:1 against the field's own edge.

    Owners after Tab (57ee36d) Approvers after Tab (57ee36d) Owners after a mouse press (57ee36d)
    Owners with the ring Approvers with ring and tooltip Owners, no ring
  • WebKit: the spec runs in CI's WebKit project. It could not run locally, because this container cannot install WebKit's system libraries.

  • Units: the new jsdom cases fail on main and pass here. Tokenizer and InputGroup pass (321). TypeScript (core and Storybook), ESLint, check:knowledge and check:changesets are clean.

  • Screen readers (evidence, not a gate; spec:AST-009 FR17): partial. VoiceOver on iOS Safari reads the Tokenizer's touch sheet cleanly ("Team Members, web dialog, Search Team Members…"). The test rig can't send hardware Tab or Shift+Tab inside the page (they leave for Safari's address field), so the Tab announcement, the handoff to the input, and the disabled field's description weren't observed. NVDA wasn't observed.

Writing rubric results

Record touched: component:Tokenizer FR3 (one consistency sentence), per the Specification session's ruling.

  • Present tense, system only: yes.
  • Checkable: each clause maps to a browser case.
  • Cross-references: none added.

Scope

Components: Tokenizer

  • No new public API.
  • Public text contains no internal context.

Owner: Astryx fix-loop lane 0. Land path: Specs stamp, screen-reader check, CodeBunny approval of the exact head, CI, then the merge queue.

Overlap checked: #12442, #11201, #8199 (they change the status icon, loading/changeAction and touch Delete; none touches the layer-mode placeholder, its tab stop or disabled focus)

…its placeholder

In layer mode the input lives in a closed popover, so Tab reached only the
visible tokens' Remove buttons, and a disabled field had no stop at all.
The placeholder is now the collapsed field's one tab stop, a group named by
the field label: its focus opens the layer and moves focus to the input.
Disabled, it keeps the stop with aria-disabled, anchors the disabledMessage
tooltip, and opens nothing; the input is no longer natively disabled.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 20, 2026 2:41am UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 17, 2026
@astracat-bot

astracat-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 20, 2026, 2:52 AM UTC

@cixzhang cixzhang added the lane:0 Astryx fix-loop lane 0 owns this label Nov 17, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 3cec2d3

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

…g under keyboard focus

The disabled placeholder kept its tab stop but drew no focus indicator,
because the shared disabled style drops the field ring. It now restores
the field ring on its own :focus-visible (inputDisabledFocusStyles.selfRing,
beside the shared ring and nestedRing), so Tab shows it and a mouse press
does not.
@github-actions github-actions Bot added the needs:design-review Affects visuals — Design should review label Nov 17, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 57ee36d

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has run to completion on this head before, and the run that restarted when the pull request left draft is still in progress, so merge waits on it.

A collapsed unfocusedLayer field now takes one Tab stop that opens it with focus in the input, and a disabled field keeps that stop, states that it is disabled and why, and shows the focus ring only under keyboard focus. Two earlier inline notes still apply and are optional: scope the browser spec's [disabled] count to the story root, and list the new browser spec in the record's FR1–FR3 verification row and verified_by.

Claims and files checked

Review mode: same-head; reason: none

Claims:

  • Release note: keyboard users can Tab to a collapsed layer-mode field. Verified: the placeholder is a tab stop (Tokenizer.tsx:2437); browser case "Tab reaches a collapsed field with tokens" passes.
  • Release note: the placeholder opens the field with focus in the input, even with no tokens. Verified: focus handler Tokenizer.tsx:1875-1882; browser case on the empty Reviewers field passes.
  • Release note: a disabled field keeps the stop, says it is disabled, shows its reason and opens nothing. Verified: aria-disabled and the early return (Tokenizer.tsx:2436, :1876), tooltip anchored on the placeholder (:1504); unit cases at Tokenizer.test.tsx:1045-1069 and the browser case pass.
  • Release note: no element is natively disabled. Verified: isFocusableDisabled={isDisabled} (Tokenizer.tsx:2076); the unit and browser cases find no [disabled] element.
  • Before: Tab reached only the visible tokens' Remove buttons, and an empty or disabled field had no stop. Verified on the base: the placeholder had no role or tab index, the layer input was natively disabled or inside the closed layer, and disabled tokens render no Remove button.
  • The placeholder is a group named by the field label, carrying its description and status, a tab stop while collapsed and not while open, disabled when the field is. Verified: Tokenizer.tsx:2423-2437, :1889-1897.
  • Focus on a token inside the placeholder stays on the token. Verified: the target guard at Tokenizer.tsx:1876.
  • The reason tooltip anchors to the placeholder, and the layer input is focusable-disabled as in every other mode. Verified: Tokenizer.tsx:1386-1408, :1500-1507, :2076.
  • Layout, the open layer, the tokens' Remove buttons, pointer behaviour and the other overflow modes are unchanged. Verified: the resting ring style equals the disabled style (inputDisabledFocus.ts:54-68), the other modes compute the same values as before, and the head's tab order keeps the Remove buttons after the placeholder.
  • The record's FR3 gains one sentence naming the placeholder as the tab stop. Verified in substance; the added text is two sentences.
  • The prop docs no longer say the layer-mode input is natively disabled. Verified: Tokenizer.tsx:280-285, Tokenizer.doc.mjs:95.
  • A new story shows an empty, a disabled and a disabled-with-reason field. Verified: Tokenizer.stories.tsx:333-367.
  • The release note is a patch fix. Verified.
  • The browser spec fails on main and passes here, four of four cases in Chromium. Verified at this head in CI; on main the placeholder has no tab stop, so the first case cannot pass.
  • The disabled placeholder shows the ring under Tab and not under a mouse press, through a shared self-focus variant. Verified: inputDisabledFocus.ts:54-68, Tokenizer.tsx:2453; both browser cases pass.
  • The ring's border measures 3.36:1 against the page and 2.77:1 against the field edge. Verified from a frame of this head.
  • The spec runs in CI's WebKit project. Verified: the WebKit project includes it and runs weekly, not on pull requests.
  • The new unit cases fail on main and pass here; unit suites, TypeScript, ESLint and the knowledge and changeset checks are clean. Verified at this head in CI; the new unit cases cannot pass on main.
  • Screen-reader observation is partial and not a merge requirement. Consistent with the record that sets the merge bar.
  • No new public API. Verified: zero API rows for every published package.
  • Public text holds no internal context. Verified.
  • The three named overlapping pull requests do not touch the layer-mode placeholder. Verified; one of them only re-indents the line this pull request rewrites.

Files:

  • .changeset/tokenizer-layer-tab-stop.md: clear.
  • apps/storybook/stories/Tokenizer.stories.tsx: clear.
  • docs/specs/components/Tokenizer/Tokenizer.spec.md: FR3 amendment approved at this head; non-blocking, the verification row and verified_by do not list the new browser spec.
  • packages/core/src/Field/inputDisabledFocus.ts: clear.
  • packages/core/src/Tokenizer/Tokenizer.doc.mjs: clear.
  • packages/core/src/Tokenizer/Tokenizer.test.tsx: clear.
  • packages/core/src/Tokenizer/Tokenizer.tsx: non-blocking, the handle's focus() does not reach the new stop.
  • packages/core/src/Tokenizer/__tests__/TokenizerLayerFocus.a11y.browser.spec.ts: non-blocking, the [disabled] count covers the whole document.

Automated review (maintainer link)

browserName,
}) => {
await mount(page, 'core-tokenizer--overflow-layer-states');
expect(await page.locator('[disabled]').count()).toBe(0);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This counts [disabled] across the whole document, so it also sees anything the harness renders. Against a development Storybook the page already carries one disabled stylesheet link in <head>, and the case fails there even though the component renders no disabled element. Scoping it to the story root, for example #storybook-root [disabled], keeps the assertion about the component in both harnesses (same for line 126).

| FR1 | Tokenizer MUST keep one native combobox input mounted across token addition, removal, clear, ordinary wrapping, and maximum-entry states. Reaching `maxEntries` may make the input zero-width, transparent, and out of flow, but MUST NOT replace its identity. | Current source and tests | Verified current behavior |
| FR2 | Tokenizer's suggestion menu MUST remain associated with the outer field/control surface. Existing `menuWidth` behavior remains an exact preferred pixel width plus the outer field's minimum width; it is not a maximum. | Current BaseTypeahead/Tokenizer source and docs | Verified current behavior; preserve |
| FR3 | `unfocusedInline` MAY replace direct token layout with OverflowList while blurred. `unfocusedLayer` MAY keep the real wrapper/input mounted in a context layer while an ordinary-flow placeholder represents the collapsed field. | Current source, tests, and stories | Verified current behavior |
| FR3 | `unfocusedInline` MAY replace direct token layout with OverflowList while blurred. `unfocusedLayer` MAY keep the real wrapper/input mounted in a context layer while an ordinary-flow placeholder represents the collapsed field. That placeholder is the collapsed field's one tab stop, before its tokens' own controls: a group named by the field label. Its focus opens the layer and moves focus to the input; disabled, it keeps the stop, exposes `aria-disabled`, anchors the `disabledMessage` tooltip, and opens nothing. | Current source, tests, and stories | Verified current behavior |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FR3 now states normative keyboard, naming and disabled behaviour, but the FR1-FR3 verification row still reads "Existing Tokenizer/BaseTypeahead unit tests plus source inspection" and verified_by does not list TokenizerLayerFocus.a11y.browser.spec.ts, although the record lists the component's other browser specs. Listing it keeps the claim and its proof together.

@cixzhang cixzhang added the ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) label Nov 18, 2026
@cixzhang
cixzhang marked this pull request as ready for review November 19, 2026 10:52
@cixzhang
cixzhang marked this pull request as draft November 19, 2026 19:22
@cixzhang
cixzhang marked this pull request as ready for review November 19, 2026 19:22
@cixzhang
cixzhang marked this pull request as draft November 19, 2026 20:02
@cixzhang
cixzhang marked this pull request as ready for review November 19, 2026 20:02
@cixzhang
cixzhang marked this pull request as draft November 20, 2026 02:28
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 093afdb

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet (the pull request is still a draft), so merge waits on it.

A collapsed unfocusedLayer field now takes one Tab stop that opens it with focus in the input, and a disabled field keeps that stop, states that it is disabled and why, and shows the focus ring only under keyboard focus. Two earlier inline notes still apply and are optional: scope the browser spec's [disabled] count to the story root, and list the new browser spec in the record's FR1–FR3 verification row and verified_by.

Claims and files checked

Review mode: incremental; reason: none

Claims:

  • Release note: keyboard users can Tab to a collapsed layer-mode field. Verified: the placeholder is a tab stop (Tokenizer.tsx:2456); browser case "Tab reaches a collapsed field with tokens" passes at this head.
  • Release note: the placeholder opens the field with focus in the input, even with no tokens. Verified: focus handler Tokenizer.tsx:1880-1887; browser case on the empty Reviewers field passes.
  • Release note: a disabled field keeps the stop, says it is disabled, shows its reason and opens nothing. Verified: aria-disabled and the early return (Tokenizer.tsx:2455, :1881), tooltip anchored on the placeholder (:1496); unit cases at Tokenizer.test.tsx:1065-1089 and the browser case pass.
  • Release note: no element is natively disabled. Verified: isFocusableDisabled={isDisabled} (Tokenizer.tsx:2086); the unit and browser cases, and a probe of the new story, find no [disabled] element.
  • Before: Tab reached only the visible tokens' Remove buttons, and an empty or disabled field had no stop. Verified on the base: one Tab lands on "Remove Alice Johnson" with the field closed; the placeholder had no role or tab index, and the layer input was natively disabled or inside the closed layer.
  • The placeholder is a group named by the field label, carrying its description and status, a tab stop while collapsed and not while open, disabled when the field is. Verified: Tokenizer.tsx:2441-2456, :1894-1907.
  • Focus on a token inside the placeholder stays on the token. Verified: the target guard at Tokenizer.tsx:1881.
  • The reason tooltip anchors to the placeholder, and the layer input is focusable-disabled as in every other mode. Verified: Tokenizer.tsx:1369-1391, :1491-1500, :2086.
  • Layout, the open layer, the tokens' Remove buttons, pointer behaviour and the other overflow modes are unchanged. Verified: the resting frame is pixel-identical between base and head, the other modes compute the same values as before, and the Remove buttons stay stops after the placeholder.
  • The record's FR3 gains one sentence naming the placeholder as the tab stop. Verified in substance; the added text is two sentences.
  • The prop docs no longer say the layer-mode input is natively disabled. Verified: Tokenizer.tsx:289-290, Tokenizer.doc.mjs:95.
  • A new story shows an empty, a disabled and a disabled-with-reason field. Verified: Tokenizer.stories.tsx:333-367.
  • The release note is a patch fix. Verified.
  • The browser spec fails on main and passes here, four of four cases in Chromium. Verified: all four pass at this head, twice each; on main one Tab lands on a Remove button, so the first case cannot pass.
  • The disabled placeholder shows the ring under Tab and not under a mouse press, through a shared self-focus variant. Verified: inputDisabledFocus.ts:52-68, Tokenizer.tsx:2472; both browser cases pass.
  • The ring's border measures 3.36:1 against the page and 2.77:1 against the field edge. Verified from a frame of this head.
  • The spec runs in CI's WebKit project. Verified: the WebKit project includes it and runs weekly, not on pull requests.
  • The new unit cases fail on main and pass here; unit suites, TypeScript, ESLint and the knowledge and changeset checks are clean. Verified at this head: the new cases fail against main's code and pass here; the Tokenizer, InputGroup and Field suites pass; Core and Storybook typecheck; ESLint reports no error; the knowledge and changeset checks pass.
  • Screen-reader observation is partial and not a merge requirement. Consistent with the record that sets the merge bar.
  • No new public API. Verified: zero API rows for every published package.
  • Public text holds no internal context. Verified.
  • The three named overlapping pull requests do not touch the layer-mode placeholder. Verified; one is closed and one only re-indents the line this pull request rewrites.

Files:

  • .changeset/tokenizer-layer-tab-stop.md: clear.
  • apps/storybook/stories/Tokenizer.stories.tsx: clear.
  • docs/specs/components/Tokenizer/Tokenizer.spec.md: FR3 amendment approved at this head; non-blocking, the verification row and verified_by do not list the new browser spec.
  • packages/core/src/Field/inputDisabledFocus.ts: clear.
  • packages/core/src/Tokenizer/Tokenizer.doc.mjs: clear.
  • packages/core/src/Tokenizer/Tokenizer.test.tsx: clear.
  • packages/core/src/Tokenizer/Tokenizer.tsx: non-blocking, the handle's focus() does not reach the new stop (inherited).
  • packages/core/src/Tokenizer/__tests__/TokenizerLayerFocus.a11y.browser.spec.ts: non-blocking, the [disabled] count covers the whole document.

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — 093afdb8 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) CLA Signed This label is managed by the Meta Open Source bot. lane:0 Astryx fix-loop lane 0 owns this needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant