feat: add ControlPresentation primitive

[pawelgrimm]

Short description

Adds ControlPresentation, a presentational layout primitive for input-like form controls.

It:

• draws the appropriate border based on state (idle / hover / focus / disabled / readonly / invalid) using html/aria props when appropriate (e.g. aria-readonly)
• wraps an arbitrary focusable control passed as children, forwards clicks to it
• exposes two slots (startSlot, endSlot) flanking the control
  • public API also includes ControlActionButton, a compact 24×24 button variant sized to fit inside the chrome alongside a 16px icon
• Spacing matches the design specs
  It is Intended to be responsible for the presentation of the control in TextField, the forthcoming SelectField, PasswordField, ComboboxField, and similar — anything that wants the visual chrome of a text field around an arbitrary control.

Out of scope

• A new Button / IconButton xsmall size to replace ControlActionButton's dimensions (separate Button-taxonomy spec, out of scope).
• TextField / SelectField / TextArea migration onto this primitive (follow-up PR).
• BorderedTextField (the outlined-with-label-inside sibling that will also compose OutlinedControlContainer) — follow-up PR.

PR Checklist

• Added tests for bugs / new features
• Updated docs (storybooks, readme)
• Reviewed and approved Chromatic visual regression tests in CI

[pawelgrimm]

@doistbot /review

[doistbot]

This PR introduces the ControlPresentation and ControlActionButton primitives, establishing a unified, state-responsive visual wrapper for input-like form controls. Centralizing the border chrome, conditional spacing, and native state reflection is a great step toward more composable and consistent form fields across the library. A few refinements have been noted around click-forwarding logic and event bubbling, tightening up TypeScript types and CSS scoping, expanding test coverage, and addressing styling duplication with existing field components.

_{Share Feedback • Review Logs}

[doistbot]

[P1] Clicks on interactive elements in slots (like a clear button) currently bubble up and synthetically focus/click the control. While a test expects focus to move to the control, this behavior also triggers control.click()/showPicker(). For example, clicking "Clear" on a composed <SelectField> would unintentionally pop open the dropdown.

Taking focus away from a clicked button also disrupts keyboard accessibility. Consider ignoring clicks that originate from interactive elements outside the control:

if (event.target instanceof Node && control.contains(event.target)) return

// Ignore clicks on slot buttons/links so they can behave natively
if (event.target instanceof Element && event.target.closest('button, a, input, select, textarea, [role="button"]')) return

[doistbot]

[P2] If control.click() is caught by a child element's handler that calls e.stopPropagation(), the event won't bubble back up to handleWrapperClick. isDispatchedReentryRef will remain true, causing the next wrapper click to be incorrectly ignored.

Since .click() dispatches synchronously, you can prevent this state leak using a try/finally block:

isDispatchedReentryRef.current = true
try {
    control.click()
} finally {
    isDispatchedReentryRef.current = false
}

(You can then safely remove isDispatchedReentryRef.current = false from the early return at line 71).

[doistbot]

[P2] These :has() state selectors are matching any descendant of the container, not just the wrapped control. That means slot content can flip the field chrome — e.g. a disabled ControlActionButton in endSlot will match [aria-disabled] here and make an otherwise editable input look disabled. Scope the state selectors to the control subtree so slots don't drive the wrapper state.

[doistbot]

[P2] The wrapper forwards activation unconditionally, even when the inner control advertises disabled state via aria-disabled/data-disabled (the same conventions the CSS treats as disabled). For custom triggers that don't prevent synthetic clicks themselves, clicking the chrome will still activate a disabled-looking control. Guard the forwarded click() with the same disabled-state checks before dispatching it.

[doistbot]

[P2] startSlot and endSlot are typed to accept numbers, but these truthiness checks drop valid 0 content. startSlot={0} / endSlot={0} currently render nothing. Use an explicit nullish check instead of a truthy check so numeric slot content is preserved.

[doistbot]

[P2] Extending full ComponentProps<typeof Box> leaks Box's polymorphic as prop into this API, but the component is hard-coded around a div wrapper and forwards an HTMLDivElement ref. as="label" / as="button" will type-check today while changing semantics and making the ref type wrong. Omit as (and ideally narrow the forwarded Box props to the few supported layout/DOM props) to keep the abstraction stable.

[doistbot]

[P2] This unconditionally dispatches a second click event for every wrapper-background click on any non-<select> control. For the main text-entry cases this component is meant to wrap (TextField, PasswordField, etc.), focus() already provides the needed behavior, so the extra .click() just adds another full event/bubble pass through React and any control-level onClick handlers. Please gate the synthetic click to controls that actually need activation (e.g. button-like/custom triggers or picker-like inputs) and skip it for plain text inputs/textarea.

[doistbot]

[P3] Project conventions specify querying elements by role. Since the nested controls have an aria-label, consider replacing getByTestId with screen.getByRole('textbox', { name: 'Subject' }) (and the equivalent getByRole for buttons) here and throughout the file.

[doistbot]

[P2] This test verifies that the inner control receives focus, but it leaves the synthetic .click() and the native <select> .showPicker() fallbacks untested. Consider adding tests to ensure these core activation mechanics trigger correctly when the wrapper is clicked.

[doistbot]

[P2] This new exported primitive ships without any dedicated test coverage. Please add tests for both branches of the union (children -> Button, icon -> IconButton) so regressions in the prop discrimination and the injected compact styling don't slip through unnoticed.

[doistbot]

Thanks pawelgrimm for your contribution 😇. This introduces a solid foundation for unifying form control presentation and standardizing input layouts.

Few things worth tightening:

• Refine the wrapper's DOM queries and event routing so interactive slot elements don't steal focus, trigger unintended synthetic clicks, or accidentally apply disabled styling to the entire container via broad :has() selectors.
• Loosen ControlActionButton types to fully support the underlying button APIs, and update slot rendering checks to preserve valid numeric content like 0.
• Gate the wrapper's synthetic .click() dispatch to only activate picker-style controls, avoiding redundant event bubbling for plain text entries.
• Expand test coverage for ControlActionButton branches, synthetic click forwarding, and edge cases like interactive or numeric slot content.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (2)

• [P3] src/control-presentation/control-presentation.test.tsx:18: Project conventions specify querying elements by role. Since the inner control has an aria-label, consider replacing getByTestId('subject') with screen.getByRole('textbox', { name: 'Subject' }) here and throughout the file to align with established accessibility testing patterns.
• [P3] src/control-presentation/control-action-button.tsx:11: ControlActionButton is a new public export, but its branch-specific props are undocumented. The repo’s component conventions call for JSDoc on each public prop so consumers get proper hover/docs coverage. Please add prop comments for the children and icon branches here (or refactor this union into documented interfaces).

_{Share Feedback • Review Logs}

[doistbot]

This query searches the entire wrapper subtree, including slots. If startSlot contains a focusable element (like a country-code <select>), this will incorrectly target the slot element instead of the primary control. Furthermore, restricting the query to 'input, select, textarea' prevents click forwarding from working on custom controls (like a <button role="combobox">). Consider having consumers pass a controlRef, or querying a specific marker (e.g., [data-primary-control]) so the main control is identified unambiguously and supports arbitrary focusable elements.

[doistbot]

Clicks on interactive elements in the slots (like a "Clear" button) will bubble to the wrapper, bypassing this check because they are outside the targeted control. This causes the wrapper to synthetically focus and click the primary control, stealing focus from the slot button and potentially triggering unwanted actions. Ignore clicks that originate from interactive slot elements (e.g., if (event.target instanceof Element && event.target.closest('button, a, [role="button"]')) return).

[doistbot]

These :has() state selectors match any descendant of the container. Because OutlinedControlContainer wraps both the slots and the main control, a disabled element in a slot (e.g., a disabled "Clear" button in endSlot) will incorrectly trigger this rule and apply disabled styling to the entire field wrapper. Consider scoping these selectors to target the main control specifically (e.g., using a specific wrapper class), or passing state props directly.

[doistbot]

startSlot and endSlot are typed to accept numbers via SlotContent, but these truthiness checks drop valid 0 content, rendering nothing instead of the number 0. Use an explicit nullish check (e.g., startSlot != null) so numeric slot content is preserved.

[doistbot]

This wrapper narrows the underlying button APIs more than intended. Button accepts any ReactNode label and IconButton accepts ReactElement | string for icon, but this union requires ReactElement in both branches. Callers like <ControlActionButton>Clear</ControlActionButton> or icon="×" now fail type-check even though the wrapped components support them. Reuse the underlying children/icon prop types instead of redefining them here.

[doistbot]

This adds a second click dispatch for every wrapper click on non-<select> controls. For the main text-entry cases this primitive is meant to wrap (input[type=text|email|password|search|number|... ], textarea), focus() already gives the needed behavior, so the extra .click() just runs another full event/bubble cycle through React and any control onClick handlers. Please gate the synthetic click to controls that actually need activation (for example picker-like inputs) and skip it for plain text-entry controls.

[doistbot]

ControlActionButton remains exported without any dedicated test coverage. Please add tests to verify both branches of its union API (rendering Button when passed children, and IconButton when passed icon) so the prop discrimination works correctly.

[doistbot]

This test confirms that the wrapper forwards focus, but the suite still lacks a test for the synthetic .click() forwarding. (For instance, the stop-propagation test on line 115 would still pass if control.click() were deleted from the implementation). Please add a test that asserts an onClick handler on the inner control is called when the wrapper is clicked.

[doistbot]

This only covers a decorative slot. The main new surface here is interactive slot content (ControlActionButton, clear buttons, chevrons), and a regression there will forward the wrapper activation into the inner control — for example, clicking a slotted button on a wrapped <select> can open the picker. Please add a behavior test with a slotted button asserting the button handles the click and the wrapped control does not get activated.

[doistbot]

The slot rendering tests never exercise the number branch of SlotContent. 0 is the edge case most likely to break here, and this API explicitly supports numeric slot content for things like counters/units. Add a case for startSlot={0} or endSlot={0} so valid numeric content can't be silently dropped.