feat(text-field): accept exceptionallySetClassName on the input element

[lmjabreu]

Closes: no issue (decided via the exceptionallySetClassName ADR, motivated by the Reactist colour audit).

Short description

TextField now accepts exceptionallySetClassName and forwards it as className on the underlying <input> element. This mirrors the existing Reactist convention used by Box, Tooltip, Loading, Hidden, Heading, Inline, Stack, etc.

The need was surfaced by the DS-P005 migration. One comms-web TextField-bound callsite depends on a className landing on the input element: the composer's borderless link-toolbar popover (link-toolbar-popover.tsx), which styles its input directly (.linkToolbarContainer .linkInput) for a borderless, no-padding presentation inside a custom container. Dropping that className hands the visuals back to TextField and breaks the popover's design. The migration plan's alternative is a per-surface CSS refactor that re-targets the input descendant.

Scope notes

• The Adaptive Cards case is SelectField, not this PR. The other frequently-cited callsite (an Adaptive Cards host config that grabs the field element by class) is a <select> in FormSelect, handled by @pawelgrimm's separate cleanup. It is a SelectField concern, not a <TextField>/<input> one, so it does not justify this change. Earlier wording in this body conflated the two; corrected.
• SelectField intentionally excluded. Per the ADR caveat, the one current SelectField callsite that would need this (FormSelect → Adaptive Cards) is moving with a separate cleanup that may drop the integration. No need to pre-emptively expand the API.
• BaseField needs no change. It is an abstraction over the children render-prop pattern and does not directly render the inner field element. Forwarding happens in the concrete field component (TextField).

The escape-hatch framing in ObfuscatedClassName's JSDoc still applies: adding the prop is not a green light for callers to style the design system freely; it is a deliberate, named exit ramp for cases the component cannot yet meet on its own.

PR Checklist

• Added tests for bugs / new features (one new test asserting the className lands on the input element)
• Updated docs (storybooks, readme). Happy to add a story showing the escape hatch if reviewers want; left out for now since the prop is intentionally discouraged.
• Reviewed and approved Chromatic visual regression tests in CI. Pending CI run; no visual diffs expected (the prop is opt-in and unused in stories).

Related work

• ADR: exceptionallySetClassName is the convention for Reactist field components
• Audit: Reactist colour audit (2026-05-08)
• Twist discussion: t/7796256
• Parent migration plan: DS-P005 deprecated Reactist migration

[doistbot]

This PR thoughtfully introduces the exceptionallySetClassName prop to TextField, providing a deliberate escape hatch for styling the underlying input element and unblocking ongoing migration efforts. While the implementation aligns well with the design system's styling conventions, a couple of adjustments are needed to ensure the TypeScript documentation accurately reflects that the class targets the nested input rather than the container. Additionally, the testing approach should be refined to query the input by role rather than relying on a test ID to guarantee the assertion targets the exact element.

_{Share Feedback • Review Logs}

[doistbot]

[P2] Extending ObfuscatedClassName here makes the public prop docs say this class is applied to the component's main container, but this component now forwards it to the nested input instead. That leaves the TypeScript/IDE contract wrong for both TextField and PasswordField. Define exceptionallySetClassName locally on TextFieldProps with JSDoc that says it targets the underlying input, rather than inheriting the shared root-element type.

[doistbot]

[P2] Using data-testid may target the field's wrapper instead of the underlying <input> element, which undermines the test's intent to verify exactly where the class lands. To guarantee you are asserting on the input element itself (and to follow the project's testing conventions), query by role instead.

expect(screen.getByRole('textbox', { name: 'Whatʼs your name?' })).toHaveClass('custom-input-class')

You can then safely remove the data-testid prop from the TextField on line 245.

[pawelgrimm]

@lmjabreu Are you sure we need to do this? Is there a good reason for this "borderless popover input" to deviate from the standard styling? I'm not sure what you're referencing TBH.

[lmjabreu]

You're right, sorry. The only use case is the link toolbar popover in comms-web, and this doesn't actually solve it. Closing, no use case for it.