feat: add FieldChromeContainer private primitive

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: pawelgrimm

src/control-presentation/field-chrome-container.module.css

@@ -0,0 +1,68 @@
+.container {
+    /* border */
+    border: 1px solid var(--reactist-inputs-idle);
+
+    /* color */
+    background: var(--reactist-field-background);
+    color: var(--reactist-field-content);
+
+    /* Read-only: matches native :read-only on form controls (scoped to
+     * <input> / <textarea> to avoid catching unrelated elements that
+     * default to :read-only), the ARIA convention (aria-readonly="true"),
+     * and the data-attr convention used by Ariakit/Radix-style components.
+     * The :not(='false') exclusion treats aria-readonly="false" /
+     * data-readonly="false" as "not read-only" per the ARIA spec. */
+    &:has(
+        input:read-only,
+        textarea:read-only,
+        [aria-readonly]:not([aria-readonly='false']),
+        [data-readonly]:not([data-readonly='false'])
+    ) {
+        background-color: var(--reactist-field-readonly-background);
+        color: var(--reactist-field-readonly-content);
+    }
+
+    /* Disabled: matches the native disabled attribute (form controls),
+     * the soft-disable ARIA convention (used by Reactist's own Button to
+     * keep elements focusable while announcing as disabled), and the
+     * data-attr convention used by Ariakit/Radix. */
+    &:has(
+        :disabled,
+        [aria-disabled]:not([aria-disabled='false']),
+        [data-disabled]:not([data-disabled='false'])
+    ) {
+        background-color: var(--reactist-field-disabled-background);
+        color: var(--reactist-field-disabled-content);
+    }
+
+    /* Interactive border (hover/focus) — suppressed when the control is
+     * in any disabled state. */
+    &:not(
+        :has(
+            :disabled,
+            [aria-disabled]:not([aria-disabled='false']),
+            [data-disabled]:not([data-disabled='false'])
+        )
+    ) {
+        &:hover {
+            border-color: var(--reactist-inputs-hover);
+        }
+
+        &:focus-within {
+            border-color: var(--reactist-inputs-focus);
+        }
+    }
+
+    /* Invalid: matches the ARIA convention only. */
+    &:has([aria-invalid]:not([aria-invalid='false'])) {
+        border-color: var(--reactist-inputs-alert) !important;
+    }
+}
+
+.borderRadiusSmall {
+    border-radius: var(--reactist-border-radius-small);
+}
+
+.borderRadiusLarge {
+    border-radius: var(--reactist-border-radius-large);
+}

src/control-presentation/field-chrome-container.test.tsx

@@ -0,0 +1,109 @@
+import * as React from 'react'
+
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { axe } from 'jest-axe'
+
+import { FieldChromeContainer } from './field-chrome-container'
+
+describe('FieldChromeContainer', () => {
+    it('renders children', () => {
+        render(
+            <FieldChromeContainer>
+                <input data-testid="control" aria-label="control" />
+            </FieldChromeContainer>,
+        )
+        expect(screen.getByTestId('control')).toBeInTheDocument()
+    })
+
+    it('forwards ref to the wrapper element', () => {
+        const ref = React.createRef<HTMLDivElement>()
+        const { container } = render(
+            <FieldChromeContainer ref={ref}>
+                <input aria-label="control" />
+            </FieldChromeContainer>,
+        )
+        expect(ref.current).toBe(container.firstElementChild)
+    })
+
+    it('merges exceptionallySetClassName onto the wrapper', () => {
+        const { container } = render(
+            <FieldChromeContainer exceptionallySetClassName="custom">
+                <input aria-label="control" />
+            </FieldChromeContainer>,
+        )
+        expect(container.firstElementChild).toHaveClass('custom')
+    })
+
+    describe('click-to-focus dispatch', () => {
+        it('focuses the inner control when the wrapper is clicked', () => {
+            const { container } = render(
+                <FieldChromeContainer>
+                    <input data-testid="control" aria-label="control" />
+                </FieldChromeContainer>,
+            )
+            const control = screen.getByTestId('control')
+            expect(control).not.toHaveFocus()
+
+            userEvent.click(container.firstElementChild as Element)
+            expect(control).toHaveFocus()
+        })
+
+        it('does not double-fire when the inner control is clicked directly', () => {
+            const onControlClick = jest.fn()
+            render(
+                <FieldChromeContainer>
+                    <button type="button" data-testid="control" onClick={onControlClick}>
+                        click
+                    </button>
+                </FieldChromeContainer>,
+            )
+            userEvent.click(screen.getByTestId('control'))
+            expect(onControlClick).toHaveBeenCalledTimes(1)
+        })
+
+        it('calls a consumer onClick passed via Box props when the wrapper is clicked', () => {
+            const onClick = jest.fn()
+            const { container } = render(
+                <FieldChromeContainer onClick={onClick}>
+                    <input aria-label="control" />
+                </FieldChromeContainer>,
+            )
+            userEvent.click(container.firstElementChild as Element)
+            expect(onClick).toHaveBeenCalledTimes(1)
+        })
+
+        it('uses showPicker for native <select>', () => {
+            const showPicker = jest.fn()
+            const { container } = render(
+                <FieldChromeContainer>
+                    <select aria-label="fruit" data-testid="control">
+                        <option value="a">A</option>
+                    </select>
+                </FieldChromeContainer>,
+            )
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            const select = screen.getByRole('combobox') as unknown as HTMLSelectElement
+            // jsdom does not implement showPicker; stub it.
+            Object.assign(select, { showPicker })
+
+            userEvent.click(container.firstElementChild as Element)
+            expect(showPicker).toHaveBeenCalledTimes(1)
+            expect(select).toHaveFocus()
+        })
+    })
+
+    describe('a11y', () => {
+        it('renders with no a11y violations', async () => {
+            const { container } = render(
+                <>
+                    <label htmlFor="plain">Plain</label>
+                    <FieldChromeContainer>
+                        <input id="plain" />
+                    </FieldChromeContainer>
+                </>,
+            )
+            expect(await axe(container)).toHaveNoViolations()
+        })
+    })
+})

src/control-presentation/field-chrome-container.tsx

@@ -0,0 +1,103 @@
+import * as React from 'react'
+import { type ComponentProps, forwardRef } from 'react'
+
+import { Box } from '../box'
+
+import styles from './field-chrome-container.module.css'
+
+import type { ObfuscatedClassName } from '../utils/common-types'
+
+export type FieldChromeContainerProps = {
+    /**
+     * The control element to wrap. The wrapper chrome (border, hover/focus,
+     * disabled/read-only background tint, error border) derives from
+     * attributes on this descendant.
+     *
+     * Clicking the wrapper focuses the first focusable descendant and
+     * dispatches a `.click()` (or `.showPicker()` for native `<select>`).
+     */
+    children: React.ReactNode
+
+    /**
+     * The wrapper's border-radius.
+     * - `small` (default) — used by `ControlPresentation`'s inline chrome.
+     * - `large` — used by `BorderedTextField`'s outlined chrome.
+     */
+    borderRadius?: 'small' | 'large'
+} & ObfuscatedClassName &
+    Omit<ComponentProps<typeof Box>, 'className'>
+
+/**
+ * Private primitive shared by `ControlPresentation` and `BorderedTextField`.
+ *
+ * Provides the visual chrome (border with idle/hover/focus/error states,
+ * background tints for read-only/disabled descendants) and the
+ * click-to-focus dispatch behavior. Has no padding, sizing, or slot layout
+ * of its own — consumers add those on top.
+ *
+ * Contract: assumes a single focusable control descendant. Behavior is
+ * undefined if multiple focusable controls are inside.
+ */
+export const FieldChromeContainer = forwardRef<HTMLDivElement, FieldChromeContainerProps>(
+    function FieldChromeContainer(
+        { borderRadius = 'small', exceptionallySetClassName, children, ...rest },
+        ref,
+    ) {
+        const controlWrapperRef = React.useRef<HTMLDivElement>(null)
+        const isDispatchedReentryRef = React.useRef(false)
+
+        const { onClick, ...restWithoutClick } = rest as typeof rest & {
+            onClick?: React.MouseEventHandler<HTMLDivElement>
+        }
+
+        function handleWrapperClick(event: React.MouseEvent<HTMLDivElement>) {
+            if (isDispatchedReentryRef.current) {
+                isDispatchedReentryRef.current = false
+                return
+            }
+
+            onClick?.(event)
+
+            // Find the first focusable form control descendant. More robust
+            // than firstElementChild — works whether the control is the
+            // direct child (ControlPresentation) or nested inside a column
+            // layout (BorderedTextField).
+            const wrapper = controlWrapperRef.current
+            const control = wrapper?.querySelector<HTMLElement>('input, select, textarea')
+            if (!control) return
+
+            if (event.target instanceof Node && control.contains(event.target)) return
+
+            control.focus()
+            if (control instanceof HTMLSelectElement && typeof control.showPicker === 'function') {
+                try {
+                    control.showPicker()
+                } catch {
+                    // showPicker can throw (e.g. focus state issues) — fall back
+                    // silently; the focus above is the minimum useful behavior.
+                }
+                return
+            }
+
+            isDispatchedReentryRef.current = true
+            control.click()
+        }
+
+        return (
+            <Box
+                ref={ref}
+                {...restWithoutClick}
+                className={[
+                    styles.container,
+                    borderRadius === 'large' ? styles.borderRadiusLarge : styles.borderRadiusSmall,
+                    exceptionallySetClassName,
+                ]}
+                onClick={handleWrapperClick}
+            >
+                <div ref={controlWrapperRef} style={{ display: 'contents' }}>
+                    {children}
+                </div>
+            </Box>
+        )
+    },
+)