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: two callsites of the deprecated <Input> rely on a className landing on the input element (an Adaptive Cards host config that targets the input by class, and a borderless popover input that needs the styling hook). Without this affordance the migrations either need per-callsite CSS rewrites or ad-hoc workarounds.

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.

Scope notes

• SelectField intentionally excluded. Per the ADR caveat from @pawelgrimm, the one current SelectField callsite that would need this (FormSelect → Adaptive Cards in comms-web) is being handled by a separate cleanup that may drop the integration entirely. 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).

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.