From 7a7c2b49202e8fa3c0b66f0beb5f7d84cbcbe1ea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 14 May 2026 20:29:27 -0500
Subject: [PATCH 01/18] feat: add ControlPresentation primitive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A presentational layout shell for input-like controls. Provides border
chrome, focus/hover/disabled/readonly/invalid styling, and two slots
(startSlot, endSlot) flanking an arbitrary focusable control passed as
children. Forwards a ref to the wrapper and forwards click events to the
inner control (toggleable via forwardClickToControl).

State-driven styling fires from :has() selectors that match three
signaling conventions — native HTML, ARIA, and data-attr — on the inner
control. The single source of truth is the a11y attributes the control
needs anyway. :invalid is deliberately omitted (fires pre-interaction).

Spacing is explicit conditional padding: 10px outer on each side by
default; left shrinks to 6px when startSlot is present (with 6px gap to
control); right shrinks to 4px when endSlot is present (with 6px gap).

ControlActionButton ships alongside as a compact 24x24 button variant
sized to fit the chrome alongside a 16px icon glyph.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../control-action-button.tsx                 |  48 +++
 .../control-presentation.module.css           | 136 +++++++++
 .../control-presentation.stories.tsx          | 286 ++++++++++++++++++
 .../control-presentation.tsx                  | 108 +++++++
 src/control-presentation/index.ts             |   2 +
 src/index.ts                                  |   1 +
 src/styles/design-tokens.css                  |   9 +-
 7 files changed, 589 insertions(+), 1 deletion(-)
 create mode 100644 src/control-presentation/control-action-button.tsx
 create mode 100644 src/control-presentation/control-presentation.module.css
 create mode 100644 src/control-presentation/control-presentation.stories.tsx
 create mode 100644 src/control-presentation/control-presentation.tsx
 create mode 100644 src/control-presentation/index.ts

diff --git a/src/control-presentation/control-action-button.tsx b/src/control-presentation/control-action-button.tsx
new file mode 100644
index 00000000..25c6b0b3
--- /dev/null
+++ b/src/control-presentation/control-action-button.tsx
@@ -0,0 +1,48 @@
+import * as React from 'react'
+
+import classNames from 'classnames'
+
+import { Button, IconButton } from '../button'
+
+import styles from './control-presentation.module.css'
+
+import type { ComponentProps } from 'react'
+
+export type ControlActionButtonProps =
+    | ({
+          children: React.ReactElement
+      } & Omit<ComponentProps<typeof Button>, 'variant' | 'size'>)
+    | ({
+          icon?: React.ReactElement
+      } & Omit<ComponentProps<typeof IconButton>, 'variant' | 'size'>)
+
+/**
+ * A compact action button intended for `ControlPresentation`'s `endSlot`. Wraps
+ * Reactist's `Button` / `IconButton` with a 24×24, 3px-radius variant sized to fit
+ * the field chrome alongside a 16px icon glyph.
+ */
+export const ControlActionButton = React.forwardRef<HTMLButtonElement, ControlActionButtonProps>(
+    function ControlActionButton({ exceptionallySetClassName, ...props }, ref) {
+        return 'children' in props ? (
+            <Button
+                ref={ref}
+                {...props}
+                variant="quaternary"
+                exceptionallySetClassName={classNames([
+                    styles.controlActionButton,
+                    exceptionallySetClassName,
+                ])}
+            />
+        ) : (
+            <IconButton
+                ref={ref}
+                {...props}
+                variant="quaternary"
+                exceptionallySetClassName={classNames([
+                    styles.controlActionButton,
+                    exceptionallySetClassName,
+                ])}
+            />
+        )
+    },
+)
diff --git a/src/control-presentation/control-presentation.module.css b/src/control-presentation/control-presentation.module.css
new file mode 100644
index 00000000..c57bcfbf
--- /dev/null
+++ b/src/control-presentation/control-presentation.module.css
@@ -0,0 +1,136 @@
+:root {
+    --reactist-field-height: 32px;
+}
+
+.container {
+    /* sizing */
+    height: var(--reactist-field-height);
+
+    /* default outer padding; shrunk on the side(s) where a slot is present (see below) */
+    padding-inline: 10px;
+
+    /* 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 (same three conventions as the disabled
+     * background-color rule above). */
+    &: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. Native :invalid is
+     * deliberately omitted — it fires before user interaction (e.g. on
+     * any required-but-empty field at first paint), which is rarely the
+     * desired UX. Consumers that want HTML5-validation-driven errors
+     * forward :invalid → aria-invalid in their own component. */
+    &:has([aria-invalid]:not([aria-invalid='false'])) {
+        border-color: var(--reactist-inputs-alert) !important;
+    }
+}
+
+/* Conditional outer padding. When a slot is present on a side, shrink
+ * the outer padding on that side. The slot itself carries its own
+ * margin (margin-inline-{end,start}: 6px) to space it from the
+ * control — see .startSlot / .endSlot rules below. */
+.container:has(.startSlot) {
+    padding-left: 6px;
+}
+
+.container:has(.endSlot) {
+    padding-right: 4px;
+}
+
+.control {
+    display: contents;
+
+    & > * {
+        /* layout */
+        flex: 1;
+        box-sizing: border-box;
+        margin: 0;
+        padding: 0;
+        width: 100%;
+
+        /* border */
+        border: none;
+        outline: none; /* focus state is handled by the wrapper border */
+
+        /* color */
+        background: transparent;
+        color: inherit;
+    }
+}
+
+.slot {
+    /* color */
+    color: var(--reactist-field-slot-content);
+}
+
+.startSlot {
+    /* 6px gap from startSlot to the control */
+    margin-inline-end: 6px;
+}
+
+.endSlot {
+    /* 6px gap from the control to endSlot */
+    margin-inline-start: 6px;
+}
+
+/*
+ * Compact 24×24 action button variant for use inside `endSlot`. The 3px
+ * border-radius and reduced min-width make it fit the field chrome alongside a
+ * 16px icon glyph.
+ */
+.controlActionButton.controlActionButton {
+    &.controlActionButton {
+        --reactist-btn-height: 24px;
+    }
+    border-radius: 3px;
+    min-width: var(--reactist-btn-height);
+}
diff --git a/src/control-presentation/control-presentation.stories.tsx b/src/control-presentation/control-presentation.stories.tsx
new file mode 100644
index 00000000..66ff2f9c
--- /dev/null
+++ b/src/control-presentation/control-presentation.stories.tsx
@@ -0,0 +1,286 @@
+import * as React from 'react'
+
+import { selectWithNone } from '../utils/storybook-helper'
+
+import { ControlActionButton } from './control-action-button'
+import { ControlPresentation } from './control-presentation'
+
+import type { ComponentProps } from 'react'
+
+export default {
+    title: 'Design system/ControlPresentation',
+    component: ControlPresentation,
+    parameters: {
+        badges: ['accessible'],
+    },
+}
+
+type PlaygroundArgs = {
+    startSlot: boolean
+    endSlot: boolean
+    readOnly: boolean
+    disabled: boolean
+    invalid: boolean
+    placeholder: string
+    defaultValue: string
+    maxWidth: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'full'
+}
+
+export function PlaygroundStory({
+    startSlot,
+    endSlot,
+    readOnly,
+    disabled,
+    invalid,
+    placeholder,
+    defaultValue,
+    maxWidth,
+}: PlaygroundArgs) {
+    return (
+        <section className="story playground">
+            <ControlPresentation
+                maxWidth={maxWidth}
+                startSlot={startSlot ? <InfoIcon /> : undefined}
+                endSlot={endSlot ? <ChevronDownIcon /> : undefined}
+            >
+                <input
+                    aria-label="Demo input"
+                    placeholder={placeholder}
+                    readOnly={readOnly}
+                    disabled={disabled}
+                    aria-invalid={invalid || undefined}
+                    defaultValue={defaultValue}
+                />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+PlaygroundStory.storyName = 'Playground'
+PlaygroundStory.args = {
+    startSlot: true,
+    endSlot: true,
+    readOnly: false,
+    disabled: false,
+    invalid: false,
+    placeholder: 'Select a value',
+    defaultValue: '',
+}
+PlaygroundStory.argTypes = {
+    maxWidth: selectWithNone(['xsmall', 'small', 'medium', 'large', 'xlarge', 'full'], 'small'),
+    startSlot: { control: { type: 'boolean' } },
+    endSlot: { control: { type: 'boolean' } },
+    readOnly: { control: { type: 'boolean' } },
+    disabled: { control: { type: 'boolean' } },
+    invalid: { control: { type: 'boolean' } },
+    placeholder: { control: { type: 'text' } },
+    defaultValue: { control: { type: 'text' } },
+}
+PlaygroundStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function PlaceholderStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ChevronDownIcon />}
+            >
+                <input aria-label="Placeholder" placeholder="Select a value" />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+PlaceholderStory.storyName = 'Placeholder'
+PlaceholderStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function WithValueStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ChevronDownIcon />}
+            >
+                <input aria-label="With value" defaultValue="Sample value" />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+WithValueStory.storyName = 'With value'
+WithValueStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function ReadOnlyStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ChevronDownIcon />}
+            >
+                <input aria-label="Read-only" defaultValue="Sample value" readOnly />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+ReadOnlyStory.storyName = 'Read-only'
+ReadOnlyStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function DisabledStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ChevronDownIcon />}
+            >
+                <input aria-label="Disabled" defaultValue="Sample value" disabled />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+DisabledStory.storyName = 'Disabled'
+DisabledStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function ErrorStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ChevronDownIcon />}
+            >
+                <input aria-label="Error" defaultValue="Invalid value" aria-invalid />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+ErrorStory.storyName = 'Error (aria-invalid)'
+ErrorStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function EndSlotAsUnitStory() {
+    return (
+        <section className="story">
+            <ControlPresentation maxWidth="small" startSlot={<InfoIcon />} endSlot="kg">
+                <input aria-label="Weight" type="number" defaultValue="72" />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+EndSlotAsUnitStory.storyName = 'endSlot as trailing unit'
+EndSlotAsUnitStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function EndSlotAsClearButtonStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ControlActionButton icon={<XIcon />} aria-label="Clear" />}
+            >
+                <input aria-label="Search" defaultValue="sample query" />
+            </ControlPresentation>
+        </section>
+    )
+}
+
+EndSlotAsClearButtonStory.storyName = 'endSlot with clear button'
+EndSlotAsClearButtonStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+export function WrappingSelectStory() {
+    return (
+        <section className="story">
+            <ControlPresentation
+                maxWidth="small"
+                startSlot={<InfoIcon />}
+                endSlot={<ChevronDownIcon />}
+            >
+                <select
+                    aria-label="Favourite fruit"
+                    defaultValue="banana"
+                    style={{ appearance: 'none' }}
+                >
+                    <option value="apple">Apple</option>
+                    <option value="banana">Banana</option>
+                    <option value="cherry">Cherry</option>
+                </select>
+            </ControlPresentation>
+        </section>
+    )
+}
+
+WrappingSelectStory.storyName = 'Wrapping a <select>'
+WrappingSelectStory.parameters = {
+    chromatic: { disableSnapshot: false },
+}
+
+function ChevronDownIcon(props: ComponentProps<'svg'>) {
+    return (
+        <svg
+            width="16"
+            height="16"
+            viewBox="0 0 16 16"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            {...props}
+        >
+            <path
+                d="M11.6464 5.64645C11.8417 5.45118 12.1583 5.45118 12.3536 5.64645C12.5488 5.84171 12.5488 6.15829 12.3536 6.35355L8.35355 10.3536C8.15829 10.5488 7.84171 10.5488 7.64645 10.3536L3.64645 6.35355C3.45118 6.15829 3.45118 5.84171 3.64645 5.64645C3.84171 5.45118 4.15829 5.45118 4.35355 5.64645L8 9.29289L11.6464 5.64645Z"
+                fill="currentColor"
+            />
+        </svg>
+    )
+}
+
+function InfoIcon(props: ComponentProps<'svg'>) {
+    return (
+        <svg
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            {...props}
+        >
+            <path
+                d="M12 3C16.9706 3 21 7.02944 21 12C21 16.9706 16.9706 21 12 21C7.02944 21 3 16.9706 3 12C3 7.02944 7.02944 3 12 3ZM12 4C7.58172 4 4 7.58172 4 12C4 16.4183 7.58172 20 12 20C16.4183 20 20 16.4183 20 12C20 7.58172 16.4183 4 12 4ZM12.6006 10.0107C12.8285 10.0573 13 10.2593 13 10.501V15.001H14C14.2761 15.001 14.5 15.2248 14.5 15.501C14.4995 15.7767 14.2758 16.001 14 16.001H11C10.7242 16.001 10.5005 15.7767 10.5 15.501C10.5 15.2248 10.7239 15.001 11 15.001H12V11.001H11C10.7242 11.001 10.5005 10.7767 10.5 10.501C10.5 10.2248 10.7239 10.001 11 10.001H12.5L12.6006 10.0107ZM12.3398 7.32031C12.8037 7.32031 13.1796 7.69631 13.1797 8.16016C13.1794 8.62385 12.8036 9 12.3398 9C11.8762 8.99992 11.5003 8.6238 11.5 8.16016C11.5001 7.69636 11.876 7.3204 12.3398 7.32031Z"
+                fill="currentColor"
+            />
+        </svg>
+    )
+}
+
+function XIcon(props: ComponentProps<'svg'>) {
+    return (
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="none" {...props}>
+            <path
+                d="M4 4l8 8m0-8l-8 8"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+            />
+        </svg>
+    )
+}
diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
new file mode 100644
index 00000000..7f6c3ec7
--- /dev/null
+++ b/src/control-presentation/control-presentation.tsx
@@ -0,0 +1,108 @@
+import * as React from 'react'
+import { type ComponentProps, forwardRef } from 'react'
+
+import { Box } from '../box'
+
+import styles from './control-presentation.module.css'
+
+import type { ObfuscatedClassName } from '../utils/common-types'
+
+type SlotContent = React.ReactElement | string | number
+
+export type ControlPresentationProps = {
+    /**
+     * A leading element rendered before the control — a decorative icon, a row
+     * of chips/tags, or any other content that should sit on the leading edge.
+     */
+    startSlot?: SlotContent
+
+    /**
+     * Trailing content rendered immediately after the control (e.g. a unit,
+     * counter, supplementary text, or an action button such as a clear button
+     * or dropdown-trigger chevron).
+     */
+    endSlot?: SlotContent
+
+    forwardClickToControl?: boolean
+    onClick?: React.MouseEventHandler<HTMLDivElement>
+
+    /**
+     * The control element (an `<input>`, an Ariakit Select trigger,
+     * `<select>`, etc.). Attributes belonging to the control — `type`,
+     * `value`, `onChange`, `readOnly`, `disabled`, `aria-invalid`, and so on —
+     * are set on this element directly. The wrapper chrome (read-only
+     * background, disabled state, error border) derives from those attributes.
+     */
+    children: React.ReactNode
+} & ObfuscatedClassName &
+    Omit<ComponentProps<typeof Box>, 'className'>
+
+/**
+ * A presentational primitive that renders the visual chrome of a
+ * text-field-style input (border, hover / focus / disabled / read-only / error
+ * states, plus an optional row of slots) around an arbitrary control element.
+ *
+ * Slot order (left to right):
+ * `startSlot` → control (children) → `endSlot`.
+ *
+ * Clicking anywhere on the wrapper focuses the control.
+ */
+export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentationProps>(
+    function ControlPresentation(
+        {
+            startSlot,
+            endSlot,
+            forwardClickToControl = true,
+            onClick,
+            exceptionallySetClassName,
+            children,
+            ...rest
+        },
+        ref,
+    ) {
+        const controlWrapperRef = React.useRef<HTMLDivElement>(null)
+
+        function handleWrapperClick(event: React.MouseEvent<HTMLDivElement>) {
+            onClick?.(event)
+            if (!forwardClickToControl) return
+
+            const control = controlWrapperRef.current?.firstElementChild as HTMLElement | null
+            control?.focus?.()
+        }
+
+        return (
+            <Box
+                ref={ref}
+                {...rest}
+                className={[styles.container, exceptionallySetClassName]}
+                display="flex"
+                alignItems="center"
+                overflow="hidden"
+                borderRadius="standard"
+                onClick={handleWrapperClick}
+            >
+                {startSlot ? (
+                    <Slot className={[styles.slot, styles.startSlot]}>{startSlot}</Slot>
+                ) : null}
+                <div ref={controlWrapperRef} className={styles.control}>
+                    {children}
+                </div>
+                {endSlot ? <Slot className={[styles.slot, styles.endSlot]}>{endSlot}</Slot> : null}
+            </Box>
+        )
+    },
+)
+
+function Slot(props: ComponentProps<typeof Box>) {
+    return (
+        <Box
+            role="presentation"
+            display="flex"
+            alignItems="center"
+            justifyContent="center"
+            height="full"
+            minWidth={0}
+            {...props}
+        />
+    )
+}
diff --git a/src/control-presentation/index.ts b/src/control-presentation/index.ts
new file mode 100644
index 00000000..5bd30a66
--- /dev/null
+++ b/src/control-presentation/index.ts
@@ -0,0 +1,2 @@
+export * from './control-action-button'
+export * from './control-presentation'
diff --git a/src/index.ts b/src/index.ts
index 84aef992..7be0452b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -29,6 +29,7 @@ export * from './text-link'
 
 // form fields
 export * from './checkbox-field'
+export * from './control-presentation'
 export * from './password-field'
 export * from './select-field'
 export * from './switch-field'
diff --git a/src/styles/design-tokens.css b/src/styles/design-tokens.css
index c2417ff8..a9470abb 100644
--- a/src/styles/design-tokens.css
+++ b/src/styles/design-tokens.css
@@ -145,7 +145,14 @@
     --reactist-alert-tone-critical-background: rgba(250, 250, 250);
 
     /* fields */
-    --reactist-field-readonly-background: rgb(246, 244, 244);
+    --reactist-field-background: var(--reactist-bg-default);
+    --reactist-field-content: var(--reactist-content-primary);
+    --reactist-field-readonly-background: rgb(248, 245, 242);
+    --reactist-field-readonly-content: var(--reactist-field-content);
+    --reactist-field-disabled-background: var(--reactist-field-readonly-background);
+    --reactist-field-disabled-content: rgb(153, 153, 153);
+
+    --reactist-field-slot-content: rgb(102, 102, 102);
 
     /* switches and checkboxes */
     --reactist-switch-background: var(--reactist-framework-fill-summit);

From 00bfaef5191340d4ccb3ae2a0a2ece282942b1e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 14 May 2026 20:29:39 -0500
Subject: [PATCH 02/18] test: add coverage for ControlPresentation

Cover the public API surface (slot rendering, click-forwarding, ref
forwarding, attribute passthrough, exceptionallySetClassName) plus each
state-styling signaling convention (native HTML, ARIA, data-attr) and
the slot-marker classes that drive the conditional outer padding.
jest-axe smoke test for accessibility.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../control-presentation.test.tsx             | 384 ++++++++++++++++++
 1 file changed, 384 insertions(+)
 create mode 100644 src/control-presentation/control-presentation.test.tsx

diff --git a/src/control-presentation/control-presentation.test.tsx b/src/control-presentation/control-presentation.test.tsx
new file mode 100644
index 00000000..57a75adc
--- /dev/null
+++ b/src/control-presentation/control-presentation.test.tsx
@@ -0,0 +1,384 @@
+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 { TestIcon } from '../utils/test-helpers'
+
+import { ControlPresentation } from './control-presentation'
+
+describe('ControlPresentation', () => {
+    it('renders the control passed as children', () => {
+        render(
+            <ControlPresentation>
+                <input aria-label="Subject" data-testid="subject" />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control.tagName).toBe('INPUT')
+    })
+
+    it('is polymorphic — any element can be the control', () => {
+        render(
+            <ControlPresentation>
+                <button type="button" aria-label="Subject" data-testid="subject">
+                    Choose
+                </button>
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control.tagName).toBe('BUTTON')
+        expect(control).toHaveTextContent('Choose')
+    })
+
+    it('does not alter attributes on the control', () => {
+        render(
+            <ControlPresentation>
+                <input
+                    aria-label="Subject"
+                    data-testid="subject"
+                    type="email"
+                    placeholder="you@example.com"
+                    data-custom="yes"
+                    readOnly
+                    disabled
+                />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control).toHaveAttribute('type', 'email')
+        expect(control).toHaveAttribute('placeholder', 'you@example.com')
+        expect(control).toHaveAttribute('data-custom', 'yes')
+        expect(control).toHaveAttribute('readonly')
+        expect(control).toBeDisabled()
+    })
+
+    it('marks slot wrappers with role="presentation"', () => {
+        const { container } = render(
+            <ControlPresentation startSlot={<TestIcon />} endSlot={<span>end</span>}>
+                <input aria-label="Subject" />
+            </ControlPresentation>,
+        )
+        // exactly 2: startSlot wrapper + endSlot wrapper
+        const presentation = container.querySelectorAll('[role="presentation"]')
+        expect(presentation).toHaveLength(2)
+    })
+
+    it('focuses the control when the wrapper is clicked', () => {
+        const { container } = render(
+            <ControlPresentation>
+                <input aria-label="Subject" data-testid="subject" />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control).not.toHaveFocus()
+
+        userEvent.click(container.firstElementChild as Element)
+        expect(control).toHaveFocus()
+    })
+
+    it('focuses the control when a non-interactive startSlot is clicked', () => {
+        render(
+            <ControlPresentation startSlot={<TestIcon />}>
+                <input aria-label="Subject" data-testid="subject" />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control).not.toHaveFocus()
+
+        userEvent.click(screen.getByTestId('test-icon'))
+        expect(control).toHaveFocus()
+    })
+
+    it('fires a startSlot button onClick and focuses the control', () => {
+        const onSlotClick = jest.fn()
+        render(
+            <ControlPresentation
+                startSlot={
+                    <button type="button" onClick={onSlotClick}>
+                        prefix
+                    </button>
+                }
+            >
+                <input aria-label="Subject" data-testid="subject" />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control).not.toHaveFocus()
+
+        userEvent.click(screen.getByRole('button', { name: 'prefix' }))
+        expect(onSlotClick).toHaveBeenCalledTimes(1)
+        expect(control).toHaveFocus()
+    })
+
+    it('fires an endSlot button onClick and focuses the control', () => {
+        const onSlotClick = jest.fn()
+        render(
+            <ControlPresentation
+                endSlot={
+                    <button type="button" onClick={onSlotClick}>
+                        clear
+                    </button>
+                }
+            >
+                <input aria-label="Subject" data-testid="subject" />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control).not.toHaveFocus()
+
+        userEvent.click(screen.getByRole('button', { name: 'clear' }))
+        expect(onSlotClick).toHaveBeenCalledTimes(1)
+        expect(control).toHaveFocus()
+    })
+
+    it('renders startSlot and endSlot together', () => {
+        render(
+            <ControlPresentation
+                startSlot={<TestIcon />}
+                endSlot={
+                    <button type="button" aria-label="open">
+                        ▾
+                    </button>
+                }
+            >
+                <input aria-label="Subject" />
+            </ControlPresentation>,
+        )
+        expect(screen.getByTestId('test-icon')).toBeInTheDocument()
+        expect(screen.getByRole('button', { name: 'open' })).toBeInTheDocument()
+    })
+
+    it('renders string and number content in slots', () => {
+        const { container } = render(
+            <ControlPresentation startSlot="$" endSlot={42}>
+                <input aria-label="Amount" />
+            </ControlPresentation>,
+        )
+        expect(container).toHaveTextContent('$')
+        expect(container).toHaveTextContent('42')
+    })
+
+    it('merges exceptionallySetClassName onto the wrapper', () => {
+        const { container } = render(
+            <ControlPresentation exceptionallySetClassName="custom-class">
+                <input aria-label="Subject" />
+            </ControlPresentation>,
+        )
+        expect(container.firstElementChild).toHaveClass('custom-class')
+    })
+
+    it('focuses a polymorphic (button) control on wrapper click', () => {
+        const { container } = render(
+            <ControlPresentation>
+                <button type="button" aria-label="Subject" data-testid="subject">
+                    Choose
+                </button>
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        expect(control).not.toHaveFocus()
+
+        userEvent.click(container.firstElementChild as Element)
+        expect(control).toHaveFocus()
+    })
+
+    it('allows typing into the control', () => {
+        render(
+            <ControlPresentation>
+                <input aria-label="Subject" data-testid="subject" />
+            </ControlPresentation>,
+        )
+        const control = screen.getByTestId('subject')
+        userEvent.type(control, 'hello')
+        expect(control).toHaveValue('hello')
+    })
+
+    describe('state styling', () => {
+        describe('read-only', () => {
+            it('preserves the native readOnly attribute on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" readOnly />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('readonly')
+            })
+
+            it('preserves aria-readonly="true" on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" aria-readonly="true" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('aria-readonly', 'true')
+            })
+
+            it('preserves aria-readonly="false" on the control (negative-case contract)', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" aria-readonly="false" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('aria-readonly', 'false')
+            })
+
+            it('preserves data-readonly="true" on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" data-readonly="true" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('data-readonly', 'true')
+            })
+        })
+
+        describe('disabled', () => {
+            it('preserves the native disabled attribute on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" disabled />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toBeDisabled()
+            })
+
+            it('preserves aria-disabled="true" on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" aria-disabled="true" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('aria-disabled', 'true')
+            })
+
+            it('preserves aria-disabled="false" on the control (negative-case contract)', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" aria-disabled="false" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('aria-disabled', 'false')
+            })
+
+            it('preserves data-disabled="true" on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" data-disabled="true" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('data-disabled', 'true')
+            })
+        })
+
+        describe('invalid', () => {
+            it('preserves aria-invalid="true" on the control', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" aria-invalid="true" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('aria-invalid', 'true')
+            })
+
+            it('preserves aria-invalid="false" on the control (negative-case contract)', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" aria-invalid="false" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).toHaveAttribute('aria-invalid', 'false')
+            })
+
+            it('does not add aria-invalid when not provided', () => {
+                render(
+                    <ControlPresentation>
+                        <input aria-label="x" data-testid="subject" />
+                    </ControlPresentation>,
+                )
+                expect(screen.getByTestId('subject')).not.toHaveAttribute('aria-invalid')
+            })
+        })
+    })
+
+    describe('slot markers', () => {
+        it('renders a startSlot wrapper carrying the startSlot marker class', () => {
+            const { container } = render(
+                <ControlPresentation startSlot={<TestIcon />}>
+                    <input aria-label="Subject" />
+                </ControlPresentation>,
+            )
+            expect(container.querySelector('[class*="startSlot"]')).not.toBeNull()
+        })
+
+        it('renders an endSlot wrapper carrying the endSlot marker class', () => {
+            const { container } = render(
+                <ControlPresentation endSlot={<TestIcon />}>
+                    <input aria-label="Subject" />
+                </ControlPresentation>,
+            )
+            expect(container.querySelector('[class*="endSlot"]')).not.toBeNull()
+        })
+
+        it('omits the startSlot wrapper when no startSlot is provided', () => {
+            const { container } = render(
+                <ControlPresentation>
+                    <input aria-label="Subject" />
+                </ControlPresentation>,
+            )
+            expect(container.querySelector('[class*="startSlot"]')).toBeNull()
+        })
+
+        it('omits the endSlot wrapper when no endSlot is provided', () => {
+            const { container } = render(
+                <ControlPresentation>
+                    <input aria-label="Subject" />
+                </ControlPresentation>,
+            )
+            expect(container.querySelector('[class*="endSlot"]')).toBeNull()
+        })
+
+        it('endSlot accepts multi-child composition', () => {
+            render(
+                <ControlPresentation
+                    endSlot={
+                        <>
+                            <span data-testid="a" />
+                            <span data-testid="b" />
+                        </>
+                    }
+                >
+                    <input aria-label="Subject" />
+                </ControlPresentation>,
+            )
+            expect(screen.getByTestId('a')).toBeInTheDocument()
+            expect(screen.getByTestId('b')).toBeInTheDocument()
+        })
+    })
+
+    describe('a11y', () => {
+        it('renders with no a11y violations', async () => {
+            const { container } = render(
+                <>
+                    <label htmlFor="plain">Plain</label>
+                    <ControlPresentation>
+                        <input id="plain" />
+                    </ControlPresentation>
+                    <label htmlFor="slotted">Slotted</label>
+                    <ControlPresentation
+                        startSlot={<TestIcon />}
+                        endSlot={
+                            <button type="button" aria-label="clear">
+                                x
+                            </button>
+                        }
+                    >
+                        <input id="slotted" />
+                    </ControlPresentation>
+                </>,
+            )
+            expect(await axe(container)).toHaveNoViolations()
+        })
+    })
+})

From 8d6553469eeb19a83b19f13e0f0b99e6fe84011a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 09:57:57 -0500
Subject: [PATCH 03/18] fix: Support focusing <select>

---
 .../control-presentation.tsx                  | 25 ++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index 7f6c3ec7..f6d88d66 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -67,7 +67,30 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
             if (!forwardClickToControl) return
 
             const control = controlWrapperRef.current?.firstElementChild as HTMLElement | null
-            control?.focus?.()
+            if (!control) return
+
+            // Don't re-fire when the click already came from inside the control —
+            // it handled itself, and re-dispatching would double-activate.
+            if (event.target instanceof Node && control.contains(event.target)) return
+
+            // .focus() handles inputs (cursor/keyboard focus). The activation
+            // hop differs by element type:
+            //  - Native <select>: synthetic .click() is blocked by browsers
+            //    for the native dropdown. .showPicker() is the correct API.
+            //  - Everything else (inputs, native <button>, Ariakit Select
+            //    triggers, anchors): .click() either activates the click
+            //    handler or is harmlessly redundant.
+            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
+            }
+            control.click()
         }
 
         return (

From 413e0a7c77069537b6f6cff0b0a884d0ef74ca1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 10:12:01 -0500
Subject: [PATCH 04/18] refactor: use flex gap instead of slot margins for slot
 spacing

Replace margin-inline-{end,start} on .startSlot / .endSlot with a single
gap: 6px declaration on the .container flex wrapper. The rendered
geometry is identical (flex gap only applies between rendered children,
so absent slots still produce no gap), but the spacing rule lives in one
place and can't drift between the two sides.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../control-presentation.module.css            | 18 +++++-------------
 1 file changed, 5 insertions(+), 13 deletions(-)

diff --git a/src/control-presentation/control-presentation.module.css b/src/control-presentation/control-presentation.module.css
index c57bcfbf..2f2eb39c 100644
--- a/src/control-presentation/control-presentation.module.css
+++ b/src/control-presentation/control-presentation.module.css
@@ -6,6 +6,9 @@
     /* sizing */
     height: var(--reactist-field-height);
 
+    /* slot-to-control gap (only takes effect between rendered children) */
+    gap: 6px;
+
     /* default outer padding; shrunk on the side(s) where a slot is present (see below) */
     padding-inline: 10px;
 
@@ -75,9 +78,8 @@
 }
 
 /* Conditional outer padding. When a slot is present on a side, shrink
- * the outer padding on that side. The slot itself carries its own
- * margin (margin-inline-{end,start}: 6px) to space it from the
- * control — see .startSlot / .endSlot rules below. */
+ * the outer padding on that side; the wrapper's flex `gap` then provides
+ * the visual spacing between the slot and the control. */
 .container:has(.startSlot) {
     padding-left: 6px;
 }
@@ -112,16 +114,6 @@
     color: var(--reactist-field-slot-content);
 }
 
-.startSlot {
-    /* 6px gap from startSlot to the control */
-    margin-inline-end: 6px;
-}
-
-.endSlot {
-    /* 6px gap from the control to endSlot */
-    margin-inline-start: 6px;
-}
-
 /*
  * Compact 24×24 action button variant for use inside `endSlot`. The 3px
  * border-radius and reduced min-width make it fit the field chrome alongside a

From 4b77d56c136af92a542a9e1daabf7b5fc2d429e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 10:26:21 -0500
Subject: [PATCH 05/18] fix: prevent onClick from firing twice on wrapper
 background click

When the wrapper background is clicked, handleWrapperClick synthesizes
control.click() to activate the inner control. That synthetic click
bubbles back up to the wrapper and re-enters the same handler, which
called onClick a second time. Track the dispatched re-entry via a ref
and short-circuit it so consumer onClick fires exactly once per user
gesture.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/control-presentation/control-presentation.tsx | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index f6d88d66..61fdcbbe 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -61,15 +61,24 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
         ref,
     ) {
         const controlWrapperRef = React.useRef<HTMLDivElement>(null)
+        // The synthetic .click() we dispatch below bubbles back up to this
+        // handler. Track that we're inside that re-entry so we can skip
+        // re-invoking onClick + activation for it.
+        const isDispatchedReentryRef = React.useRef(false)
 
         function handleWrapperClick(event: React.MouseEvent<HTMLDivElement>) {
+            if (isDispatchedReentryRef.current) {
+                isDispatchedReentryRef.current = false
+                return
+            }
+
             onClick?.(event)
             if (!forwardClickToControl) return
 
             const control = controlWrapperRef.current?.firstElementChild as HTMLElement | null
             if (!control) return
 
-            // Don't re-fire when the click already came from inside the control —
+            // Don't re-fire when the user clicked directly on the control —
             // it handled itself, and re-dispatching would double-activate.
             if (event.target instanceof Node && control.contains(event.target)) return
 
@@ -90,6 +99,8 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
                 }
                 return
             }
+
+            isDispatchedReentryRef.current = true
             control.click()
         }
 

From f1fa78fbe7b79ecf07ad2fa45fd4ceedf6db170d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 10:26:44 -0500
Subject: [PATCH 06/18] refactor: prune ControlPresentation test suite to
 behavioral coverage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

30 → 12 tests. The pruned tests were either (a) asserting React's own
attribute-passthrough behavior (the entire state-styling describe block —
JSDOM doesn't evaluate the :has() CSS that gives those attributes
visual meaning), (b) locking in implementation details (role attributes,
CSS-module class names on slot wrappers), or (c) duplicating other
tests' coverage.

Visual concerns (conditional padding, :has()-driven state styling) stay
verified by Storybook/Chromatic — Jest is the wrong tool for CSS
behavior.

Added three small prop-guardrail tests so every documented prop has at
least one direct test: forwardClickToControl, onClick, ref forwarding.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../control-presentation.test.tsx             | 264 +++---------------
 1 file changed, 34 insertions(+), 230 deletions(-)

diff --git a/src/control-presentation/control-presentation.test.tsx b/src/control-presentation/control-presentation.test.tsx
index 57a75adc..1668a212 100644
--- a/src/control-presentation/control-presentation.test.tsx
+++ b/src/control-presentation/control-presentation.test.tsx
@@ -54,17 +54,6 @@ describe('ControlPresentation', () => {
         expect(control).toBeDisabled()
     })
 
-    it('marks slot wrappers with role="presentation"', () => {
-        const { container } = render(
-            <ControlPresentation startSlot={<TestIcon />} endSlot={<span>end</span>}>
-                <input aria-label="Subject" />
-            </ControlPresentation>,
-        )
-        // exactly 2: startSlot wrapper + endSlot wrapper
-        const presentation = container.querySelectorAll('[role="presentation"]')
-        expect(presentation).toHaveLength(2)
-    })
-
     it('focuses the control when the wrapper is clicked', () => {
         const { container } = render(
             <ControlPresentation>
@@ -91,13 +80,13 @@ describe('ControlPresentation', () => {
         expect(control).toHaveFocus()
     })
 
-    it('fires a startSlot button onClick and focuses the control', () => {
+    it('fires a slot button onClick and focuses the control', () => {
         const onSlotClick = jest.fn()
         render(
             <ControlPresentation
-                startSlot={
+                endSlot={
                     <button type="button" onClick={onSlotClick}>
-                        prefix
+                        clear
                     </button>
                 }
             >
@@ -107,254 +96,69 @@ describe('ControlPresentation', () => {
         const control = screen.getByTestId('subject')
         expect(control).not.toHaveFocus()
 
-        userEvent.click(screen.getByRole('button', { name: 'prefix' }))
+        userEvent.click(screen.getByRole('button', { name: 'clear' }))
         expect(onSlotClick).toHaveBeenCalledTimes(1)
         expect(control).toHaveFocus()
     })
 
-    it('fires an endSlot button onClick and focuses the control', () => {
-        const onSlotClick = jest.fn()
-        render(
-            <ControlPresentation
-                endSlot={
-                    <button type="button" onClick={onSlotClick}>
-                        clear
-                    </button>
-                }
-            >
-                <input aria-label="Subject" data-testid="subject" />
+    it('merges exceptionallySetClassName onto the wrapper', () => {
+        const { container } = render(
+            <ControlPresentation exceptionallySetClassName="custom-class">
+                <input aria-label="Subject" />
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
-        expect(control).not.toHaveFocus()
-
-        userEvent.click(screen.getByRole('button', { name: 'clear' }))
-        expect(onSlotClick).toHaveBeenCalledTimes(1)
-        expect(control).toHaveFocus()
+        expect(container.firstElementChild).toHaveClass('custom-class')
     })
 
-    it('renders startSlot and endSlot together', () => {
+    it('endSlot accepts multi-child composition', () => {
         render(
             <ControlPresentation
-                startSlot={<TestIcon />}
                 endSlot={
-                    <button type="button" aria-label="open">
-                        ▾
-                    </button>
+                    <>
+                        <span data-testid="a" />
+                        <span data-testid="b" />
+                    </>
                 }
             >
                 <input aria-label="Subject" />
             </ControlPresentation>,
         )
-        expect(screen.getByTestId('test-icon')).toBeInTheDocument()
-        expect(screen.getByRole('button', { name: 'open' })).toBeInTheDocument()
+        expect(screen.getByTestId('a')).toBeInTheDocument()
+        expect(screen.getByTestId('b')).toBeInTheDocument()
     })
 
-    it('renders string and number content in slots', () => {
+    it('does not forward the click to the control when forwardClickToControl is false', () => {
         const { container } = render(
-            <ControlPresentation startSlot="$" endSlot={42}>
-                <input aria-label="Amount" />
+            <ControlPresentation forwardClickToControl={false}>
+                <input aria-label="Subject" data-testid="subject" />
             </ControlPresentation>,
         )
-        expect(container).toHaveTextContent('$')
-        expect(container).toHaveTextContent('42')
-    })
+        const control = screen.getByTestId('subject')
+        expect(control).not.toHaveFocus()
 
-    it('merges exceptionallySetClassName onto the wrapper', () => {
-        const { container } = render(
-            <ControlPresentation exceptionallySetClassName="custom-class">
-                <input aria-label="Subject" />
-            </ControlPresentation>,
-        )
-        expect(container.firstElementChild).toHaveClass('custom-class')
+        userEvent.click(container.firstElementChild as Element)
+        expect(control).not.toHaveFocus()
     })
 
-    it('focuses a polymorphic (button) control on wrapper click', () => {
+    it('calls the consumer onClick when the wrapper is clicked', () => {
+        const onClick = jest.fn()
         const { container } = render(
-            <ControlPresentation>
-                <button type="button" aria-label="Subject" data-testid="subject">
-                    Choose
-                </button>
+            <ControlPresentation onClick={onClick}>
+                <input aria-label="Subject" />
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
-        expect(control).not.toHaveFocus()
-
         userEvent.click(container.firstElementChild as Element)
-        expect(control).toHaveFocus()
+        expect(onClick).toHaveBeenCalledTimes(1)
     })
 
-    it('allows typing into the control', () => {
-        render(
-            <ControlPresentation>
-                <input aria-label="Subject" data-testid="subject" />
+    it('forwards ref to the wrapper element', () => {
+        const ref = React.createRef<HTMLDivElement>()
+        const { container } = render(
+            <ControlPresentation ref={ref}>
+                <input aria-label="Subject" />
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
-        userEvent.type(control, 'hello')
-        expect(control).toHaveValue('hello')
-    })
-
-    describe('state styling', () => {
-        describe('read-only', () => {
-            it('preserves the native readOnly attribute on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" readOnly />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('readonly')
-            })
-
-            it('preserves aria-readonly="true" on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" aria-readonly="true" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('aria-readonly', 'true')
-            })
-
-            it('preserves aria-readonly="false" on the control (negative-case contract)', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" aria-readonly="false" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('aria-readonly', 'false')
-            })
-
-            it('preserves data-readonly="true" on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" data-readonly="true" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('data-readonly', 'true')
-            })
-        })
-
-        describe('disabled', () => {
-            it('preserves the native disabled attribute on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" disabled />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toBeDisabled()
-            })
-
-            it('preserves aria-disabled="true" on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" aria-disabled="true" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('aria-disabled', 'true')
-            })
-
-            it('preserves aria-disabled="false" on the control (negative-case contract)', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" aria-disabled="false" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('aria-disabled', 'false')
-            })
-
-            it('preserves data-disabled="true" on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" data-disabled="true" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('data-disabled', 'true')
-            })
-        })
-
-        describe('invalid', () => {
-            it('preserves aria-invalid="true" on the control', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" aria-invalid="true" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('aria-invalid', 'true')
-            })
-
-            it('preserves aria-invalid="false" on the control (negative-case contract)', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" aria-invalid="false" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).toHaveAttribute('aria-invalid', 'false')
-            })
-
-            it('does not add aria-invalid when not provided', () => {
-                render(
-                    <ControlPresentation>
-                        <input aria-label="x" data-testid="subject" />
-                    </ControlPresentation>,
-                )
-                expect(screen.getByTestId('subject')).not.toHaveAttribute('aria-invalid')
-            })
-        })
-    })
-
-    describe('slot markers', () => {
-        it('renders a startSlot wrapper carrying the startSlot marker class', () => {
-            const { container } = render(
-                <ControlPresentation startSlot={<TestIcon />}>
-                    <input aria-label="Subject" />
-                </ControlPresentation>,
-            )
-            expect(container.querySelector('[class*="startSlot"]')).not.toBeNull()
-        })
-
-        it('renders an endSlot wrapper carrying the endSlot marker class', () => {
-            const { container } = render(
-                <ControlPresentation endSlot={<TestIcon />}>
-                    <input aria-label="Subject" />
-                </ControlPresentation>,
-            )
-            expect(container.querySelector('[class*="endSlot"]')).not.toBeNull()
-        })
-
-        it('omits the startSlot wrapper when no startSlot is provided', () => {
-            const { container } = render(
-                <ControlPresentation>
-                    <input aria-label="Subject" />
-                </ControlPresentation>,
-            )
-            expect(container.querySelector('[class*="startSlot"]')).toBeNull()
-        })
-
-        it('omits the endSlot wrapper when no endSlot is provided', () => {
-            const { container } = render(
-                <ControlPresentation>
-                    <input aria-label="Subject" />
-                </ControlPresentation>,
-            )
-            expect(container.querySelector('[class*="endSlot"]')).toBeNull()
-        })
-
-        it('endSlot accepts multi-child composition', () => {
-            render(
-                <ControlPresentation
-                    endSlot={
-                        <>
-                            <span data-testid="a" />
-                            <span data-testid="b" />
-                        </>
-                    }
-                >
-                    <input aria-label="Subject" />
-                </ControlPresentation>,
-            )
-            expect(screen.getByTestId('a')).toBeInTheDocument()
-            expect(screen.getByTestId('b')).toBeInTheDocument()
-        })
+        expect(ref.current).toBe(container.firstElementChild)
     })
 
     describe('a11y', () => {

From d1be6d29a8ce954a88b3e46fae41428d1753e1c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 11:01:27 -0500
Subject: [PATCH 07/18] refactor: drop onClick and forwardClickToControl from
 ControlPresentation props
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Click handlers belong on the inner control, not on the wrapper. The
wrapper's click-to-focus behavior is internal — there's no real need
for consumers to disable it (forwardClickToControl) or hook into it
(onClick) for the wrap pattern.

The implementation still extracts onClick out of rest (via a type cast)
to compose with the focus-forwarding handler — this path exists only for
render-prop use, where Ariakit (or similar) forwards its own onClick to
the wrapper-as-trigger. Consumers of ControlPresentation directly won't
see onClick in autocomplete; TypeScript rejects passing it at call
sites.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../control-presentation.test.tsx             | 15 +---------
 .../control-presentation.tsx                  | 29 +++++++++----------
 2 files changed, 15 insertions(+), 29 deletions(-)

diff --git a/src/control-presentation/control-presentation.test.tsx b/src/control-presentation/control-presentation.test.tsx
index 1668a212..19b24561 100644
--- a/src/control-presentation/control-presentation.test.tsx
+++ b/src/control-presentation/control-presentation.test.tsx
@@ -127,20 +127,7 @@ describe('ControlPresentation', () => {
         expect(screen.getByTestId('b')).toBeInTheDocument()
     })
 
-    it('does not forward the click to the control when forwardClickToControl is false', () => {
-        const { container } = render(
-            <ControlPresentation forwardClickToControl={false}>
-                <input aria-label="Subject" data-testid="subject" />
-            </ControlPresentation>,
-        )
-        const control = screen.getByTestId('subject')
-        expect(control).not.toHaveFocus()
-
-        userEvent.click(container.firstElementChild as Element)
-        expect(control).not.toHaveFocus()
-    })
-
-    it('calls the consumer onClick when the wrapper is clicked', () => {
+    it('calls a consumer onClick passed via Box props when the wrapper is clicked', () => {
         const onClick = jest.fn()
         const { container } = render(
             <ControlPresentation onClick={onClick}>
diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index 61fdcbbe..879f5f04 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -23,15 +23,14 @@ export type ControlPresentationProps = {
      */
     endSlot?: SlotContent
 
-    forwardClickToControl?: boolean
-    onClick?: React.MouseEventHandler<HTMLDivElement>
-
     /**
      * The control element (an `<input>`, an Ariakit Select trigger,
      * `<select>`, etc.). Attributes belonging to the control — `type`,
      * `value`, `onChange`, `readOnly`, `disabled`, `aria-invalid`, and so on —
      * are set on this element directly. The wrapper chrome (read-only
      * background, disabled state, error border) derives from those attributes.
+     *
+     * Click handlers belong on the control itself, not on this wrapper.
      */
     children: React.ReactNode
 } & ObfuscatedClassName &
@@ -49,23 +48,24 @@ export type ControlPresentationProps = {
  */
 export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentationProps>(
     function ControlPresentation(
-        {
-            startSlot,
-            endSlot,
-            forwardClickToControl = true,
-            onClick,
-            exceptionallySetClassName,
-            children,
-            ...rest
-        },
+        { startSlot, endSlot, exceptionallySetClassName, children, ...rest },
         ref,
     ) {
         const controlWrapperRef = React.useRef<HTMLDivElement>(null)
         // The synthetic .click() we dispatch below bubbles back up to this
         // handler. Track that we're inside that re-entry so we can skip
-        // re-invoking onClick + activation for it.
+        // re-invoking the consumer onClick + activation for it.
         const isDispatchedReentryRef = React.useRef(false)
 
+        // `onClick` isn't part of `ControlPresentationProps` — consumers
+        // should put click handlers on the inner control. This extraction
+        // exists only to compose with onClick that arrives via render-prop
+        // wrapping (e.g. Ariakit's Select trigger uses `render={<ControlPresentation/>}`
+        // and forwards its own onClick), where the wrapper IS the trigger.
+        const { onClick, ...restWithoutClick } = rest as typeof rest & {
+            onClick?: React.MouseEventHandler<HTMLDivElement>
+        }
+
         function handleWrapperClick(event: React.MouseEvent<HTMLDivElement>) {
             if (isDispatchedReentryRef.current) {
                 isDispatchedReentryRef.current = false
@@ -73,7 +73,6 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
             }
 
             onClick?.(event)
-            if (!forwardClickToControl) return
 
             const control = controlWrapperRef.current?.firstElementChild as HTMLElement | null
             if (!control) return
@@ -107,7 +106,7 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
         return (
             <Box
                 ref={ref}
-                {...rest}
+                {...restWithoutClick}
                 className={[styles.container, exceptionallySetClassName]}
                 display="flex"
                 alignItems="center"

From fa7ed1aeed5f95f9f4e8e6c9ed3d77588171fcb9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 13:50:51 -0500
Subject: [PATCH 08/18] feat: add FieldChromeContainer private primitive

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../field-chrome-container.module.css         |  68 +++++++++++
 .../field-chrome-container.test.tsx           | 109 ++++++++++++++++++
 .../field-chrome-container.tsx                | 103 +++++++++++++++++
 3 files changed, 280 insertions(+)
 create mode 100644 src/control-presentation/field-chrome-container.module.css
 create mode 100644 src/control-presentation/field-chrome-container.test.tsx
 create mode 100644 src/control-presentation/field-chrome-container.tsx

diff --git a/src/control-presentation/field-chrome-container.module.css b/src/control-presentation/field-chrome-container.module.css
new file mode 100644
index 00000000..1db29982
--- /dev/null
+++ b/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);
+}
diff --git a/src/control-presentation/field-chrome-container.test.tsx b/src/control-presentation/field-chrome-container.test.tsx
new file mode 100644
index 00000000..cb6f9402
--- /dev/null
+++ b/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()
+        })
+    })
+})
diff --git a/src/control-presentation/field-chrome-container.tsx b/src/control-presentation/field-chrome-container.tsx
new file mode 100644
index 00000000..cb2fcc49
--- /dev/null
+++ b/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>
+        )
+    },
+)

From adcb1e249aaf9957430640d8e74e3d50c1877a24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 14:01:32 -0500
Subject: [PATCH 09/18] test: add FieldChromeContainer border-radius and class
 assertions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../field-chrome-container.test.tsx           | 41 +++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/control-presentation/field-chrome-container.test.tsx b/src/control-presentation/field-chrome-container.test.tsx
index cb6f9402..ae5fd2ac 100644
--- a/src/control-presentation/field-chrome-container.test.tsx
+++ b/src/control-presentation/field-chrome-container.test.tsx
@@ -7,6 +7,12 @@ import { axe } from 'jest-axe'
 import { FieldChromeContainer } from './field-chrome-container'
 
 describe('FieldChromeContainer', () => {
+    // Note: CSS `:has()`-driven state styling (readonly/disabled tinting, error
+    // border via aria-invalid, hover/focus border colors) is verified by visual
+    // regression / Chromatic, not Jest. jsdom does not implement `:has()` for
+    // computed styles, so asserting these rules in Jest would require parsing
+    // the CSS module and computing match — out of scope.
+
     it('renders children', () => {
         render(
             <FieldChromeContainer>
@@ -35,6 +41,41 @@ describe('FieldChromeContainer', () => {
         expect(container.firstElementChild).toHaveClass('custom')
     })
 
+    describe('chrome class wiring', () => {
+        it('applies the base container class to the wrapper', () => {
+            const { container } = render(
+                <FieldChromeContainer>
+                    <input aria-label="control" />
+                </FieldChromeContainer>,
+            )
+            // The class is hashed by CSS Modules in production but the import yields
+            // an object whose `.container` value is the actual className used.
+            // We assert presence of the class indirectly via toHaveClass with the
+            // module's resolved class name.
+            expect(container.firstElementChild?.className).toMatch(/container/)
+        })
+
+        it('applies the small border-radius class by default', () => {
+            const { container } = render(
+                <FieldChromeContainer>
+                    <input aria-label="control" />
+                </FieldChromeContainer>,
+            )
+            expect(container.firstElementChild?.className).toMatch(/borderRadiusSmall/)
+            expect(container.firstElementChild?.className).not.toMatch(/borderRadiusLarge/)
+        })
+
+        it('applies the large border-radius class when borderRadius="large"', () => {
+            const { container } = render(
+                <FieldChromeContainer borderRadius="large">
+                    <input aria-label="control" />
+                </FieldChromeContainer>,
+            )
+            expect(container.firstElementChild?.className).toMatch(/borderRadiusLarge/)
+            expect(container.firstElementChild?.className).not.toMatch(/borderRadiusSmall/)
+        })
+    })
+
     describe('click-to-focus dispatch', () => {
         it('focuses the inner control when the wrapper is clicked', () => {
             const { container } = render(

From 4a7281c19b0c9411ac6fff2aca15b6c5fe0c3731 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 14:05:51 -0500
Subject: [PATCH 10/18] refactor: compose ControlPresentation on top of
 FieldChromeContainer

---
 .../control-presentation.module.css           | 66 +-------------
 .../control-presentation.test.tsx             | 55 ------------
 .../control-presentation.tsx                  | 89 ++++---------------
 3 files changed, 20 insertions(+), 190 deletions(-)

diff --git a/src/control-presentation/control-presentation.module.css b/src/control-presentation/control-presentation.module.css
index 2f2eb39c..9b64393a 100644
--- a/src/control-presentation/control-presentation.module.css
+++ b/src/control-presentation/control-presentation.module.css
@@ -9,72 +9,8 @@
     /* slot-to-control gap (only takes effect between rendered children) */
     gap: 6px;
 
-    /* default outer padding; shrunk on the side(s) where a slot is present (see below) */
+    /* default outer padding; shrunk on the side(s) where a slot is present */
     padding-inline: 10px;
-
-    /* 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 (same three conventions as the disabled
-     * background-color rule above). */
-    &: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. Native :invalid is
-     * deliberately omitted — it fires before user interaction (e.g. on
-     * any required-but-empty field at first paint), which is rarely the
-     * desired UX. Consumers that want HTML5-validation-driven errors
-     * forward :invalid → aria-invalid in their own component. */
-    &:has([aria-invalid]:not([aria-invalid='false'])) {
-        border-color: var(--reactist-inputs-alert) !important;
-    }
 }
 
 /* Conditional outer padding. When a slot is present on a side, shrink
diff --git a/src/control-presentation/control-presentation.test.tsx b/src/control-presentation/control-presentation.test.tsx
index 19b24561..16cf654f 100644
--- a/src/control-presentation/control-presentation.test.tsx
+++ b/src/control-presentation/control-presentation.test.tsx
@@ -54,19 +54,6 @@ describe('ControlPresentation', () => {
         expect(control).toBeDisabled()
     })
 
-    it('focuses the control when the wrapper is clicked', () => {
-        const { container } = render(
-            <ControlPresentation>
-                <input aria-label="Subject" data-testid="subject" />
-            </ControlPresentation>,
-        )
-        const control = screen.getByTestId('subject')
-        expect(control).not.toHaveFocus()
-
-        userEvent.click(container.firstElementChild as Element)
-        expect(control).toHaveFocus()
-    })
-
     it('focuses the control when a non-interactive startSlot is clicked', () => {
         render(
             <ControlPresentation startSlot={<TestIcon />}>
@@ -80,27 +67,6 @@ describe('ControlPresentation', () => {
         expect(control).toHaveFocus()
     })
 
-    it('fires a slot button onClick and focuses the control', () => {
-        const onSlotClick = jest.fn()
-        render(
-            <ControlPresentation
-                endSlot={
-                    <button type="button" onClick={onSlotClick}>
-                        clear
-                    </button>
-                }
-            >
-                <input aria-label="Subject" data-testid="subject" />
-            </ControlPresentation>,
-        )
-        const control = screen.getByTestId('subject')
-        expect(control).not.toHaveFocus()
-
-        userEvent.click(screen.getByRole('button', { name: 'clear' }))
-        expect(onSlotClick).toHaveBeenCalledTimes(1)
-        expect(control).toHaveFocus()
-    })
-
     it('merges exceptionallySetClassName onto the wrapper', () => {
         const { container } = render(
             <ControlPresentation exceptionallySetClassName="custom-class">
@@ -127,27 +93,6 @@ describe('ControlPresentation', () => {
         expect(screen.getByTestId('b')).toBeInTheDocument()
     })
 
-    it('calls a consumer onClick passed via Box props when the wrapper is clicked', () => {
-        const onClick = jest.fn()
-        const { container } = render(
-            <ControlPresentation onClick={onClick}>
-                <input aria-label="Subject" />
-            </ControlPresentation>,
-        )
-        userEvent.click(container.firstElementChild as Element)
-        expect(onClick).toHaveBeenCalledTimes(1)
-    })
-
-    it('forwards ref to the wrapper element', () => {
-        const ref = React.createRef<HTMLDivElement>()
-        const { container } = render(
-            <ControlPresentation ref={ref}>
-                <input aria-label="Subject" />
-            </ControlPresentation>,
-        )
-        expect(ref.current).toBe(container.firstElementChild)
-    })
-
     describe('a11y', () => {
         it('renders with no a11y violations', async () => {
             const { container } = render(
diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index 879f5f04..d7151bb5 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -1,8 +1,12 @@
 import * as React from 'react'
 import { type ComponentProps, forwardRef } from 'react'
 
+import classNames from 'classnames'
+
 import { Box } from '../box'
 
+import { FieldChromeContainer } from './field-chrome-container'
+
 import styles from './control-presentation.module.css'
 
 import type { ObfuscatedClassName } from '../utils/common-types'
@@ -27,101 +31,46 @@ export type ControlPresentationProps = {
      * The control element (an `<input>`, an Ariakit Select trigger,
      * `<select>`, etc.). Attributes belonging to the control — `type`,
      * `value`, `onChange`, `readOnly`, `disabled`, `aria-invalid`, and so on —
-     * are set on this element directly. The wrapper chrome (read-only
-     * background, disabled state, error border) derives from those attributes.
+     * are set on this element directly. The wrapper chrome derives from those
+     * attributes.
      *
      * Click handlers belong on the control itself, not on this wrapper.
+     * Clicking the wrapper focuses the control.
      */
     children: React.ReactNode
 } & ObfuscatedClassName &
-    Omit<ComponentProps<typeof Box>, 'className'>
+    Omit<ComponentProps<typeof FieldChromeContainer>, 'borderRadius'>
 
 /**
- * A presentational primitive that renders the visual chrome of a
- * text-field-style input (border, hover / focus / disabled / read-only / error
- * states, plus an optional row of slots) around an arbitrary control element.
+ * The visual chrome of an inline, single-row, text-field-style input: a
+ * 32px-tall row with optional start/end slots around a control element.
  *
- * Slot order (left to right):
- * `startSlot` → control (children) → `endSlot`.
+ * Slot order (left to right): `startSlot` → control (children) → `endSlot`.
  *
- * Clicking anywhere on the wrapper focuses the control.
+ * Click handlers belong on the control itself, not on this wrapper.
+ * Clicking the wrapper focuses the control.
  */
 export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentationProps>(
     function ControlPresentation(
         { startSlot, endSlot, exceptionallySetClassName, children, ...rest },
         ref,
     ) {
-        const controlWrapperRef = React.useRef<HTMLDivElement>(null)
-        // The synthetic .click() we dispatch below bubbles back up to this
-        // handler. Track that we're inside that re-entry so we can skip
-        // re-invoking the consumer onClick + activation for it.
-        const isDispatchedReentryRef = React.useRef(false)
-
-        // `onClick` isn't part of `ControlPresentationProps` — consumers
-        // should put click handlers on the inner control. This extraction
-        // exists only to compose with onClick that arrives via render-prop
-        // wrapping (e.g. Ariakit's Select trigger uses `render={<ControlPresentation/>}`
-        // and forwards its own onClick), where the wrapper IS the trigger.
-        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)
-
-            const control = controlWrapperRef.current?.firstElementChild as HTMLElement | null
-            if (!control) return
-
-            // Don't re-fire when the user clicked directly on the control —
-            // it handled itself, and re-dispatching would double-activate.
-            if (event.target instanceof Node && control.contains(event.target)) return
-
-            // .focus() handles inputs (cursor/keyboard focus). The activation
-            // hop differs by element type:
-            //  - Native <select>: synthetic .click() is blocked by browsers
-            //    for the native dropdown. .showPicker() is the correct API.
-            //  - Everything else (inputs, native <button>, Ariakit Select
-            //    triggers, anchors): .click() either activates the click
-            //    handler or is harmlessly redundant.
-            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
+            <FieldChromeContainer
                 ref={ref}
-                {...restWithoutClick}
-                className={[styles.container, exceptionallySetClassName]}
+                {...rest}
+                borderRadius="small"
+                exceptionallySetClassName={classNames(styles.container, exceptionallySetClassName)}
                 display="flex"
                 alignItems="center"
                 overflow="hidden"
-                borderRadius="standard"
-                onClick={handleWrapperClick}
             >
                 {startSlot ? (
                     <Slot className={[styles.slot, styles.startSlot]}>{startSlot}</Slot>
                 ) : null}
-                <div ref={controlWrapperRef} className={styles.control}>
-                    {children}
-                </div>
+                <div className={styles.control}>{children}</div>
                 {endSlot ? <Slot className={[styles.slot, styles.endSlot]}>{endSlot}</Slot> : null}
-            </Box>
+            </FieldChromeContainer>
         )
     },
 )

From 3ebe67a8342512553c06394703c0f6554f90d296 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 14:44:01 -0500
Subject: [PATCH 11/18] refactor: narrow FieldChromeContainer's public surface

Replace `Omit<ComponentProps<typeof Box>, 'className'>` on FCC with
explicit `onClick` + `ObfuscatedClassName`. Move `display:flex`,
`align-items:center`, `overflow:hidden` into FCC's CSS. CP keeps its
loose public type (Box props) but only forwards `onClick` to FCC;
other Box props (maxWidth, etc.) are silently dropped pending a
follow-up CP API tightening.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../control-presentation.tsx                  | 10 +++---
 .../field-chrome-container.module.css         |  4 +++
 .../field-chrome-container.tsx                | 34 +++++++++++--------
 3 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index d7151bb5..ab8bec69 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -39,7 +39,7 @@ export type ControlPresentationProps = {
      */
     children: React.ReactNode
 } & ObfuscatedClassName &
-    Omit<ComponentProps<typeof FieldChromeContainer>, 'borderRadius'>
+    Omit<ComponentProps<typeof Box>, 'className'>
 
 /**
  * The visual chrome of an inline, single-row, text-field-style input: a
@@ -55,15 +55,15 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
         { startSlot, endSlot, exceptionallySetClassName, children, ...rest },
         ref,
     ) {
+        // Only `onClick` is meaningful to forward to FCC; other Box props are
+        // silently dropped pending CP API tightening in a follow-up.
+        const { onClick } = rest as { onClick?: React.MouseEventHandler<HTMLDivElement> }
         return (
             <FieldChromeContainer
                 ref={ref}
-                {...rest}
                 borderRadius="small"
+                onClick={onClick}
                 exceptionallySetClassName={classNames(styles.container, exceptionallySetClassName)}
-                display="flex"
-                alignItems="center"
-                overflow="hidden"
             >
                 {startSlot ? (
                     <Slot className={[styles.slot, styles.startSlot]}>{startSlot}</Slot>
diff --git a/src/control-presentation/field-chrome-container.module.css b/src/control-presentation/field-chrome-container.module.css
index 1db29982..725792e2 100644
--- a/src/control-presentation/field-chrome-container.module.css
+++ b/src/control-presentation/field-chrome-container.module.css
@@ -1,4 +1,8 @@
 .container {
+    display: flex;
+    align-items: center;
+    overflow: hidden;
+
     /* border */
     border: 1px solid var(--reactist-inputs-idle);
 
diff --git a/src/control-presentation/field-chrome-container.tsx b/src/control-presentation/field-chrome-container.tsx
index cb2fcc49..57511c1f 100644
--- a/src/control-presentation/field-chrome-container.tsx
+++ b/src/control-presentation/field-chrome-container.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { type ComponentProps, forwardRef } from 'react'
+import { forwardRef } from 'react'
 
 import { Box } from '../box'
 
@@ -9,12 +9,15 @@ 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.
+     * The control element (or a layout containing one) to wrap. The wrapper
+     * chrome (border, hover/focus, disabled/read-only background tint, error
+     * border) derives from attributes on the focusable descendant. Clicking
+     * the wrapper focuses the first focusable input/select/textarea
+     * descendant and dispatches a `.click()` (or `.showPicker()` for native
+     * `<select>`).
      *
-     * Clicking the wrapper focuses the first focusable descendant and
-     * dispatches a `.click()` (or `.showPicker()` for native `<select>`).
+     * Contract: assumes a single focusable control descendant. Behavior is
+     * undefined if multiple focusable controls are inside.
      */
     children: React.ReactNode
 
@@ -24,8 +27,16 @@ export type FieldChromeContainerProps = {
      * - `large` — used by `BorderedTextField`'s outlined chrome.
      */
     borderRadius?: 'small' | 'large'
-} & ObfuscatedClassName &
-    Omit<ComponentProps<typeof Box>, 'className'>
+
+    /**
+     * Optional click handler. Fires before the click-to-focus dispatch.
+     * Intended for composition with library wrappers (e.g. Ariakit's
+     * render-prop pattern) that forward an upstream onClick to the chrome
+     * element. Component-level click handling normally lives on the inner
+     * control.
+     */
+    onClick?: React.MouseEventHandler<HTMLDivElement>
+} & ObfuscatedClassName
 
 /**
  * Private primitive shared by `ControlPresentation` and `BorderedTextField`.
@@ -40,16 +51,12 @@ export type FieldChromeContainerProps = {
  */
 export const FieldChromeContainer = forwardRef<HTMLDivElement, FieldChromeContainerProps>(
     function FieldChromeContainer(
-        { borderRadius = 'small', exceptionallySetClassName, children, ...rest },
+        { borderRadius = 'small', exceptionallySetClassName, onClick, children },
         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
@@ -86,7 +93,6 @@ export const FieldChromeContainer = forwardRef<HTMLDivElement, FieldChromeContai
         return (
             <Box
                 ref={ref}
-                {...restWithoutClick}
                 className={[
                     styles.container,
                     borderRadius === 'large' ? styles.borderRadiusLarge : styles.borderRadiusSmall,

From 0c9693917abefdd145fa8c504c171e465f6ca431 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Fri, 15 May 2026 14:50:19 -0500
Subject: [PATCH 12/18] refactor: rename FieldChromeContainer to
 OutlinedControlContainer; tighten ControlPresentation type

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../control-presentation.stories.tsx          | 141 +++++++++---------
 .../control-presentation.tsx                  |  28 +---
 ... => outlined-control-container.module.css} |   0
 ...sx => outlined-control-container.test.tsx} |  48 +++---
 ...ner.tsx => outlined-control-container.tsx} |   8 +-
 5 files changed, 100 insertions(+), 125 deletions(-)
 rename src/control-presentation/{field-chrome-container.module.css => outlined-control-container.module.css} (100%)
 rename src/control-presentation/{field-chrome-container.test.tsx => outlined-control-container.test.tsx} (81%)
 rename src/control-presentation/{field-chrome-container.tsx => outlined-control-container.tsx} (94%)

diff --git a/src/control-presentation/control-presentation.stories.tsx b/src/control-presentation/control-presentation.stories.tsx
index 66ff2f9c..0d9d8999 100644
--- a/src/control-presentation/control-presentation.stories.tsx
+++ b/src/control-presentation/control-presentation.stories.tsx
@@ -1,5 +1,6 @@
 import * as React from 'react'
 
+import { Box } from '../box'
 import { selectWithNone } from '../utils/storybook-helper'
 
 import { ControlActionButton } from './control-action-button'
@@ -38,20 +39,21 @@ export function PlaygroundStory({
 }: PlaygroundArgs) {
     return (
         <section className="story playground">
-            <ControlPresentation
-                maxWidth={maxWidth}
-                startSlot={startSlot ? <InfoIcon /> : undefined}
-                endSlot={endSlot ? <ChevronDownIcon /> : undefined}
-            >
-                <input
-                    aria-label="Demo input"
-                    placeholder={placeholder}
-                    readOnly={readOnly}
-                    disabled={disabled}
-                    aria-invalid={invalid || undefined}
-                    defaultValue={defaultValue}
-                />
-            </ControlPresentation>
+            <Box maxWidth={maxWidth}>
+                <ControlPresentation
+                    startSlot={startSlot ? <InfoIcon /> : undefined}
+                    endSlot={endSlot ? <ChevronDownIcon /> : undefined}
+                >
+                    <input
+                        aria-label="Demo input"
+                        placeholder={placeholder}
+                        readOnly={readOnly}
+                        disabled={disabled}
+                        aria-invalid={invalid || undefined}
+                        defaultValue={defaultValue}
+                    />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -83,13 +85,11 @@ PlaygroundStory.parameters = {
 export function PlaceholderStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ChevronDownIcon />}
-            >
-                <input aria-label="Placeholder" placeholder="Select a value" />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
+                    <input aria-label="Placeholder" placeholder="Select a value" />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -102,13 +102,11 @@ PlaceholderStory.parameters = {
 export function WithValueStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ChevronDownIcon />}
-            >
-                <input aria-label="With value" defaultValue="Sample value" />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
+                    <input aria-label="With value" defaultValue="Sample value" />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -121,13 +119,11 @@ WithValueStory.parameters = {
 export function ReadOnlyStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ChevronDownIcon />}
-            >
-                <input aria-label="Read-only" defaultValue="Sample value" readOnly />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
+                    <input aria-label="Read-only" defaultValue="Sample value" readOnly />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -140,13 +136,11 @@ ReadOnlyStory.parameters = {
 export function DisabledStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ChevronDownIcon />}
-            >
-                <input aria-label="Disabled" defaultValue="Sample value" disabled />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
+                    <input aria-label="Disabled" defaultValue="Sample value" disabled />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -159,13 +153,11 @@ DisabledStory.parameters = {
 export function ErrorStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ChevronDownIcon />}
-            >
-                <input aria-label="Error" defaultValue="Invalid value" aria-invalid />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
+                    <input aria-label="Error" defaultValue="Invalid value" aria-invalid />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -178,9 +170,11 @@ ErrorStory.parameters = {
 export function EndSlotAsUnitStory() {
     return (
         <section className="story">
-            <ControlPresentation maxWidth="small" startSlot={<InfoIcon />} endSlot="kg">
-                <input aria-label="Weight" type="number" defaultValue="72" />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot="kg">
+                    <input aria-label="Weight" type="number" defaultValue="72" />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -193,13 +187,14 @@ EndSlotAsUnitStory.parameters = {
 export function EndSlotAsClearButtonStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ControlActionButton icon={<XIcon />} aria-label="Clear" />}
-            >
-                <input aria-label="Search" defaultValue="sample query" />
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation
+                    startSlot={<InfoIcon />}
+                    endSlot={<ControlActionButton icon={<XIcon />} aria-label="Clear" />}
+                >
+                    <input aria-label="Search" defaultValue="sample query" />
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
@@ -212,21 +207,19 @@ EndSlotAsClearButtonStory.parameters = {
 export function WrappingSelectStory() {
     return (
         <section className="story">
-            <ControlPresentation
-                maxWidth="small"
-                startSlot={<InfoIcon />}
-                endSlot={<ChevronDownIcon />}
-            >
-                <select
-                    aria-label="Favourite fruit"
-                    defaultValue="banana"
-                    style={{ appearance: 'none' }}
-                >
-                    <option value="apple">Apple</option>
-                    <option value="banana">Banana</option>
-                    <option value="cherry">Cherry</option>
-                </select>
-            </ControlPresentation>
+            <Box maxWidth="small">
+                <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
+                    <select
+                        aria-label="Favourite fruit"
+                        defaultValue="banana"
+                        style={{ appearance: 'none' }}
+                    >
+                        <option value="apple">Apple</option>
+                        <option value="banana">Banana</option>
+                        <option value="cherry">Cherry</option>
+                    </select>
+                </ControlPresentation>
+            </Box>
         </section>
     )
 }
diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index ab8bec69..b55ab497 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -5,12 +5,10 @@ import classNames from 'classnames'
 
 import { Box } from '../box'
 
-import { FieldChromeContainer } from './field-chrome-container'
+import { OutlinedControlContainer } from './outlined-control-container'
 
 import styles from './control-presentation.module.css'
 
-import type { ObfuscatedClassName } from '../utils/common-types'
-
 type SlotContent = React.ReactElement | string | number
 
 export type ControlPresentationProps = {
@@ -26,20 +24,7 @@ export type ControlPresentationProps = {
      * or dropdown-trigger chevron).
      */
     endSlot?: SlotContent
-
-    /**
-     * The control element (an `<input>`, an Ariakit Select trigger,
-     * `<select>`, etc.). Attributes belonging to the control — `type`,
-     * `value`, `onChange`, `readOnly`, `disabled`, `aria-invalid`, and so on —
-     * are set on this element directly. The wrapper chrome derives from those
-     * attributes.
-     *
-     * Click handlers belong on the control itself, not on this wrapper.
-     * Clicking the wrapper focuses the control.
-     */
-    children: React.ReactNode
-} & ObfuscatedClassName &
-    Omit<ComponentProps<typeof Box>, 'className'>
+} & Omit<ComponentProps<typeof OutlinedControlContainer>, 'borderRadius'>
 
 /**
  * The visual chrome of an inline, single-row, text-field-style input: a
@@ -52,14 +37,11 @@ export type ControlPresentationProps = {
  */
 export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentationProps>(
     function ControlPresentation(
-        { startSlot, endSlot, exceptionallySetClassName, children, ...rest },
+        { startSlot, endSlot, exceptionallySetClassName, onClick, children },
         ref,
     ) {
-        // Only `onClick` is meaningful to forward to FCC; other Box props are
-        // silently dropped pending CP API tightening in a follow-up.
-        const { onClick } = rest as { onClick?: React.MouseEventHandler<HTMLDivElement> }
         return (
-            <FieldChromeContainer
+            <OutlinedControlContainer
                 ref={ref}
                 borderRadius="small"
                 onClick={onClick}
@@ -70,7 +52,7 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
                 ) : null}
                 <div className={styles.control}>{children}</div>
                 {endSlot ? <Slot className={[styles.slot, styles.endSlot]}>{endSlot}</Slot> : null}
-            </FieldChromeContainer>
+            </OutlinedControlContainer>
         )
     },
 )
diff --git a/src/control-presentation/field-chrome-container.module.css b/src/control-presentation/outlined-control-container.module.css
similarity index 100%
rename from src/control-presentation/field-chrome-container.module.css
rename to src/control-presentation/outlined-control-container.module.css
diff --git a/src/control-presentation/field-chrome-container.test.tsx b/src/control-presentation/outlined-control-container.test.tsx
similarity index 81%
rename from src/control-presentation/field-chrome-container.test.tsx
rename to src/control-presentation/outlined-control-container.test.tsx
index ae5fd2ac..38684cea 100644
--- a/src/control-presentation/field-chrome-container.test.tsx
+++ b/src/control-presentation/outlined-control-container.test.tsx
@@ -4,9 +4,9 @@ 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'
+import { OutlinedControlContainer } from './outlined-control-container'
 
-describe('FieldChromeContainer', () => {
+describe('OutlinedControlContainer', () => {
     // Note: CSS `:has()`-driven state styling (readonly/disabled tinting, error
     // border via aria-invalid, hover/focus border colors) is verified by visual
     // regression / Chromatic, not Jest. jsdom does not implement `:has()` for
@@ -15,9 +15,9 @@ describe('FieldChromeContainer', () => {
 
     it('renders children', () => {
         render(
-            <FieldChromeContainer>
+            <OutlinedControlContainer>
                 <input data-testid="control" aria-label="control" />
-            </FieldChromeContainer>,
+            </OutlinedControlContainer>,
         )
         expect(screen.getByTestId('control')).toBeInTheDocument()
     })
@@ -25,18 +25,18 @@ describe('FieldChromeContainer', () => {
     it('forwards ref to the wrapper element', () => {
         const ref = React.createRef<HTMLDivElement>()
         const { container } = render(
-            <FieldChromeContainer ref={ref}>
+            <OutlinedControlContainer ref={ref}>
                 <input aria-label="control" />
-            </FieldChromeContainer>,
+            </OutlinedControlContainer>,
         )
         expect(ref.current).toBe(container.firstElementChild)
     })
 
     it('merges exceptionallySetClassName onto the wrapper', () => {
         const { container } = render(
-            <FieldChromeContainer exceptionallySetClassName="custom">
+            <OutlinedControlContainer exceptionallySetClassName="custom">
                 <input aria-label="control" />
-            </FieldChromeContainer>,
+            </OutlinedControlContainer>,
         )
         expect(container.firstElementChild).toHaveClass('custom')
     })
@@ -44,9 +44,9 @@ describe('FieldChromeContainer', () => {
     describe('chrome class wiring', () => {
         it('applies the base container class to the wrapper', () => {
             const { container } = render(
-                <FieldChromeContainer>
+                <OutlinedControlContainer>
                     <input aria-label="control" />
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             // The class is hashed by CSS Modules in production but the import yields
             // an object whose `.container` value is the actual className used.
@@ -57,9 +57,9 @@ describe('FieldChromeContainer', () => {
 
         it('applies the small border-radius class by default', () => {
             const { container } = render(
-                <FieldChromeContainer>
+                <OutlinedControlContainer>
                     <input aria-label="control" />
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             expect(container.firstElementChild?.className).toMatch(/borderRadiusSmall/)
             expect(container.firstElementChild?.className).not.toMatch(/borderRadiusLarge/)
@@ -67,9 +67,9 @@ describe('FieldChromeContainer', () => {
 
         it('applies the large border-radius class when borderRadius="large"', () => {
             const { container } = render(
-                <FieldChromeContainer borderRadius="large">
+                <OutlinedControlContainer borderRadius="large">
                     <input aria-label="control" />
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             expect(container.firstElementChild?.className).toMatch(/borderRadiusLarge/)
             expect(container.firstElementChild?.className).not.toMatch(/borderRadiusSmall/)
@@ -79,9 +79,9 @@ describe('FieldChromeContainer', () => {
     describe('click-to-focus dispatch', () => {
         it('focuses the inner control when the wrapper is clicked', () => {
             const { container } = render(
-                <FieldChromeContainer>
+                <OutlinedControlContainer>
                     <input data-testid="control" aria-label="control" />
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             const control = screen.getByTestId('control')
             expect(control).not.toHaveFocus()
@@ -93,11 +93,11 @@ describe('FieldChromeContainer', () => {
         it('does not double-fire when the inner control is clicked directly', () => {
             const onControlClick = jest.fn()
             render(
-                <FieldChromeContainer>
+                <OutlinedControlContainer>
                     <button type="button" data-testid="control" onClick={onControlClick}>
                         click
                     </button>
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             userEvent.click(screen.getByTestId('control'))
             expect(onControlClick).toHaveBeenCalledTimes(1)
@@ -106,9 +106,9 @@ describe('FieldChromeContainer', () => {
         it('calls a consumer onClick passed via Box props when the wrapper is clicked', () => {
             const onClick = jest.fn()
             const { container } = render(
-                <FieldChromeContainer onClick={onClick}>
+                <OutlinedControlContainer onClick={onClick}>
                     <input aria-label="control" />
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             userEvent.click(container.firstElementChild as Element)
             expect(onClick).toHaveBeenCalledTimes(1)
@@ -117,11 +117,11 @@ describe('FieldChromeContainer', () => {
         it('uses showPicker for native <select>', () => {
             const showPicker = jest.fn()
             const { container } = render(
-                <FieldChromeContainer>
+                <OutlinedControlContainer>
                     <select aria-label="fruit" data-testid="control">
                         <option value="a">A</option>
                     </select>
-                </FieldChromeContainer>,
+                </OutlinedControlContainer>,
             )
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
             const select = screen.getByRole('combobox') as unknown as HTMLSelectElement
@@ -139,9 +139,9 @@ describe('FieldChromeContainer', () => {
             const { container } = render(
                 <>
                     <label htmlFor="plain">Plain</label>
-                    <FieldChromeContainer>
+                    <OutlinedControlContainer>
                         <input id="plain" />
-                    </FieldChromeContainer>
+                    </OutlinedControlContainer>
                 </>,
             )
             expect(await axe(container)).toHaveNoViolations()
diff --git a/src/control-presentation/field-chrome-container.tsx b/src/control-presentation/outlined-control-container.tsx
similarity index 94%
rename from src/control-presentation/field-chrome-container.tsx
rename to src/control-presentation/outlined-control-container.tsx
index 57511c1f..5683e81a 100644
--- a/src/control-presentation/field-chrome-container.tsx
+++ b/src/control-presentation/outlined-control-container.tsx
@@ -3,11 +3,11 @@ import { forwardRef } from 'react'
 
 import { Box } from '../box'
 
-import styles from './field-chrome-container.module.css'
+import styles from './outlined-control-container.module.css'
 
 import type { ObfuscatedClassName } from '../utils/common-types'
 
-export type FieldChromeContainerProps = {
+export type OutlinedControlContainerProps = {
     /**
      * The control element (or a layout containing one) to wrap. The wrapper
      * chrome (border, hover/focus, disabled/read-only background tint, error
@@ -49,8 +49,8 @@ export type FieldChromeContainerProps = {
  * Contract: assumes a single focusable control descendant. Behavior is
  * undefined if multiple focusable controls are inside.
  */
-export const FieldChromeContainer = forwardRef<HTMLDivElement, FieldChromeContainerProps>(
-    function FieldChromeContainer(
+export const OutlinedControlContainer = forwardRef<HTMLDivElement, OutlinedControlContainerProps>(
+    function OutlinedControlContainer(
         { borderRadius = 'small', exceptionallySetClassName, onClick, children },
         ref,
     ) {

From de7ca2107f18a4ac0194d1b81ee72f2dd1960f25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 28 May 2026 13:10:16 -0500
Subject: [PATCH 13/18] chore: update ControlPresentation stories for Storybook
 10

---
 .../control-presentation.stories.tsx          | 179 +++++++++---------
 .../control-presentation.test.tsx             |   4 +-
 .../outlined-control-container.test.tsx       |  16 +-
 3 files changed, 100 insertions(+), 99 deletions(-)

diff --git a/src/control-presentation/control-presentation.stories.tsx b/src/control-presentation/control-presentation.stories.tsx
index 0d9d8999..86fe0d98 100644
--- a/src/control-presentation/control-presentation.stories.tsx
+++ b/src/control-presentation/control-presentation.stories.tsx
@@ -6,15 +6,20 @@ import { selectWithNone } from '../utils/storybook-helper'
 import { ControlActionButton } from './control-action-button'
 import { ControlPresentation } from './control-presentation'
 
+import type { Meta, StoryObj } from '@storybook/react-vite'
 import type { ComponentProps } from 'react'
 
-export default {
+const meta = {
     title: 'Design system/ControlPresentation',
     component: ControlPresentation,
     parameters: {
         badges: ['accessible'],
     },
-}
+} satisfies Meta<typeof ControlPresentation>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
 
 type PlaygroundArgs = {
     startSlot: boolean
@@ -27,7 +32,7 @@ type PlaygroundArgs = {
     maxWidth: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'full'
 }
 
-export function PlaygroundStory({
+function PlaygroundTemplate({
     startSlot,
     endSlot,
     readOnly,
@@ -58,32 +63,37 @@ export function PlaygroundStory({
     )
 }
 
-PlaygroundStory.storyName = 'Playground'
-PlaygroundStory.args = {
-    startSlot: true,
-    endSlot: true,
-    readOnly: false,
-    disabled: false,
-    invalid: false,
-    placeholder: 'Select a value',
-    defaultValue: '',
-}
-PlaygroundStory.argTypes = {
-    maxWidth: selectWithNone(['xsmall', 'small', 'medium', 'large', 'xlarge', 'full'], 'small'),
-    startSlot: { control: { type: 'boolean' } },
-    endSlot: { control: { type: 'boolean' } },
-    readOnly: { control: { type: 'boolean' } },
-    disabled: { control: { type: 'boolean' } },
-    invalid: { control: { type: 'boolean' } },
-    placeholder: { control: { type: 'text' } },
-    defaultValue: { control: { type: 'text' } },
-}
-PlaygroundStory.parameters = {
-    chromatic: { disableSnapshot: false },
+export const Playground: StoryObj<PlaygroundArgs> = {
+    name: 'Playground',
+    render: PlaygroundTemplate,
+    args: {
+        startSlot: true,
+        endSlot: true,
+        readOnly: false,
+        disabled: false,
+        invalid: false,
+        placeholder: 'Select a value',
+        defaultValue: '',
+        maxWidth: 'small',
+    },
+    argTypes: {
+        maxWidth: selectWithNone(['xsmall', 'small', 'medium', 'large', 'xlarge', 'full'], 'small'),
+        startSlot: { control: { type: 'boolean' } },
+        endSlot: { control: { type: 'boolean' } },
+        readOnly: { control: { type: 'boolean' } },
+        disabled: { control: { type: 'boolean' } },
+        invalid: { control: { type: 'boolean' } },
+        placeholder: { control: { type: 'text' } },
+        defaultValue: { control: { type: 'text' } },
+    },
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function PlaceholderStory() {
-    return (
+export const Placeholder: Story = {
+    name: 'Placeholder',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
@@ -91,16 +101,15 @@ export function PlaceholderStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-PlaceholderStory.storyName = 'Placeholder'
-PlaceholderStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function WithValueStory() {
-    return (
+export const WithValue: Story = {
+    name: 'With value',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
@@ -108,16 +117,15 @@ export function WithValueStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-WithValueStory.storyName = 'With value'
-WithValueStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function ReadOnlyStory() {
-    return (
+export const ReadOnly: Story = {
+    name: 'Read-only',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
@@ -125,16 +133,15 @@ export function ReadOnlyStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-ReadOnlyStory.storyName = 'Read-only'
-ReadOnlyStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function DisabledStory() {
-    return (
+export const Disabled: Story = {
+    name: 'Disabled',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
@@ -142,16 +149,15 @@ export function DisabledStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-DisabledStory.storyName = 'Disabled'
-DisabledStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function ErrorStory() {
-    return (
+export const Error: Story = {
+    name: 'Error (aria-invalid)',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
@@ -159,16 +165,15 @@ export function ErrorStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-ErrorStory.storyName = 'Error (aria-invalid)'
-ErrorStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function EndSlotAsUnitStory() {
-    return (
+export const EndSlotAsUnit: Story = {
+    name: 'endSlot as trailing unit',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot="kg">
@@ -176,16 +181,15 @@ export function EndSlotAsUnitStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-EndSlotAsUnitStory.storyName = 'endSlot as trailing unit'
-EndSlotAsUnitStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function EndSlotAsClearButtonStory() {
-    return (
+export const EndSlotAsClearButton: Story = {
+    name: 'endSlot with clear button',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation
@@ -196,16 +200,15 @@ export function EndSlotAsClearButtonStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-EndSlotAsClearButtonStory.storyName = 'endSlot with clear button'
-EndSlotAsClearButtonStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
-export function WrappingSelectStory() {
-    return (
+export const WrappingSelect: Story = {
+    name: 'Wrapping a <select>',
+    render: () => (
         <section className="story">
             <Box maxWidth="small">
                 <ControlPresentation startSlot={<InfoIcon />} endSlot={<ChevronDownIcon />}>
@@ -221,12 +224,10 @@ export function WrappingSelectStory() {
                 </ControlPresentation>
             </Box>
         </section>
-    )
-}
-
-WrappingSelectStory.storyName = 'Wrapping a <select>'
-WrappingSelectStory.parameters = {
-    chromatic: { disableSnapshot: false },
+    ),
+    parameters: {
+        chromatic: { disableSnapshot: false },
+    },
 }
 
 function ChevronDownIcon(props: ComponentProps<'svg'>) {
diff --git a/src/control-presentation/control-presentation.test.tsx b/src/control-presentation/control-presentation.test.tsx
index 16cf654f..6a42b05d 100644
--- a/src/control-presentation/control-presentation.test.tsx
+++ b/src/control-presentation/control-presentation.test.tsx
@@ -54,7 +54,7 @@ describe('ControlPresentation', () => {
         expect(control).toBeDisabled()
     })
 
-    it('focuses the control when a non-interactive startSlot is clicked', () => {
+    it('focuses the control when a non-interactive startSlot is clicked', async () => {
         render(
             <ControlPresentation startSlot={<TestIcon />}>
                 <input aria-label="Subject" data-testid="subject" />
@@ -63,7 +63,7 @@ describe('ControlPresentation', () => {
         const control = screen.getByTestId('subject')
         expect(control).not.toHaveFocus()
 
-        userEvent.click(screen.getByTestId('test-icon'))
+        await userEvent.click(screen.getByTestId('test-icon'))
         expect(control).toHaveFocus()
     })
 
diff --git a/src/control-presentation/outlined-control-container.test.tsx b/src/control-presentation/outlined-control-container.test.tsx
index 38684cea..638767cf 100644
--- a/src/control-presentation/outlined-control-container.test.tsx
+++ b/src/control-presentation/outlined-control-container.test.tsx
@@ -77,7 +77,7 @@ describe('OutlinedControlContainer', () => {
     })
 
     describe('click-to-focus dispatch', () => {
-        it('focuses the inner control when the wrapper is clicked', () => {
+        it('focuses the inner control when the wrapper is clicked', async () => {
             const { container } = render(
                 <OutlinedControlContainer>
                     <input data-testid="control" aria-label="control" />
@@ -86,11 +86,11 @@ describe('OutlinedControlContainer', () => {
             const control = screen.getByTestId('control')
             expect(control).not.toHaveFocus()
 
-            userEvent.click(container.firstElementChild as Element)
+            await userEvent.click(container.firstElementChild as Element)
             expect(control).toHaveFocus()
         })
 
-        it('does not double-fire when the inner control is clicked directly', () => {
+        it('does not double-fire when the inner control is clicked directly', async () => {
             const onControlClick = jest.fn()
             render(
                 <OutlinedControlContainer>
@@ -99,22 +99,22 @@ describe('OutlinedControlContainer', () => {
                     </button>
                 </OutlinedControlContainer>,
             )
-            userEvent.click(screen.getByTestId('control'))
+            await userEvent.click(screen.getByTestId('control'))
             expect(onControlClick).toHaveBeenCalledTimes(1)
         })
 
-        it('calls a consumer onClick passed via Box props when the wrapper is clicked', () => {
+        it('calls a consumer onClick passed via Box props when the wrapper is clicked', async () => {
             const onClick = jest.fn()
             const { container } = render(
                 <OutlinedControlContainer onClick={onClick}>
                     <input aria-label="control" />
                 </OutlinedControlContainer>,
             )
-            userEvent.click(container.firstElementChild as Element)
+            await userEvent.click(container.firstElementChild as Element)
             expect(onClick).toHaveBeenCalledTimes(1)
         })
 
-        it('uses showPicker for native <select>', () => {
+        it('uses showPicker for native <select>', async () => {
             const showPicker = jest.fn()
             const { container } = render(
                 <OutlinedControlContainer>
@@ -128,7 +128,7 @@ describe('OutlinedControlContainer', () => {
             // jsdom does not implement showPicker; stub it.
             Object.assign(select, { showPicker })
 
-            userEvent.click(container.firstElementChild as Element)
+            await userEvent.click(container.firstElementChild as Element)
             expect(showPicker).toHaveBeenCalledTimes(1)
             expect(select).toHaveFocus()
         })

From 0e3714ede3661f430275931d3675caeb7fc76319 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 28 May 2026 14:13:51 -0500
Subject: [PATCH 14/18] fix: prevent reentry guard from latching when
 dispatched click does not bubble

The guard was cleared only on the next handler invocation. If a consumer's
onClick stops propagation on the inner control, control.click() never bubbles
back to the wrapper, the guard stays true, and the next real wrapper click is
silently swallowed.

Always clear immediately after control.click() returns.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../outlined-control-container.test.tsx       | 21 +++++++++++++++++++
 .../outlined-control-container.tsx            |  9 ++++----
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/control-presentation/outlined-control-container.test.tsx b/src/control-presentation/outlined-control-container.test.tsx
index 638767cf..ea463f69 100644
--- a/src/control-presentation/outlined-control-container.test.tsx
+++ b/src/control-presentation/outlined-control-container.test.tsx
@@ -114,6 +114,27 @@ describe('OutlinedControlContainer', () => {
             expect(onClick).toHaveBeenCalledTimes(1)
         })
 
+        it('does not latch the dispatch guard if the dispatched click does not bubble', async () => {
+            const { container } = render(
+                <OutlinedControlContainer>
+                    <input
+                        aria-label="control"
+                        data-testid="control"
+                        onClick={(e) => e.stopPropagation()}
+                    />
+                </OutlinedControlContainer>,
+            )
+            const wrapper = container.firstElementChild as Element
+            const control = screen.getByTestId('control')
+
+            await userEvent.click(wrapper)
+            expect(control).toHaveFocus()
+
+            control.blur()
+            await userEvent.click(wrapper)
+            expect(control).toHaveFocus()
+        })
+
         it('uses showPicker for native <select>', async () => {
             const showPicker = jest.fn()
             const { container } = render(
diff --git a/src/control-presentation/outlined-control-container.tsx b/src/control-presentation/outlined-control-container.tsx
index 5683e81a..50fd8dd0 100644
--- a/src/control-presentation/outlined-control-container.tsx
+++ b/src/control-presentation/outlined-control-container.tsx
@@ -58,10 +58,7 @@ export const OutlinedControlContainer = forwardRef<HTMLDivElement, OutlinedContr
         const isDispatchedReentryRef = React.useRef(false)
 
         function handleWrapperClick(event: React.MouseEvent<HTMLDivElement>) {
-            if (isDispatchedReentryRef.current) {
-                isDispatchedReentryRef.current = false
-                return
-            }
+            if (isDispatchedReentryRef.current) return
 
             onClick?.(event)
 
@@ -86,8 +83,12 @@ export const OutlinedControlContainer = forwardRef<HTMLDivElement, OutlinedContr
                 return
             }
 
+            // Guard against the synchronous re-entry from control.click() bubbling
+            // back to this handler. Always clear after the dispatch returns so the
+            // guard cannot latch if a consumer's onClick stops propagation.
             isDispatchedReentryRef.current = true
             control.click()
+            isDispatchedReentryRef.current = false
         }
 
         return (

From 915a823cca67f1360e98c88f807eb298f71d2710 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 28 May 2026 14:14:21 -0500
Subject: [PATCH 15/18] refactor: flatten CSS in control-presentation modules

Per project convention (no CSS nesting; followed by all other component
module.css files). Preserve the tripled .controlActionButton specificity hack
with a comment explaining why it overrides Button's .baseButton.size-* rules.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../control-presentation.module.css           | 40 +++++----
 .../outlined-control-container.module.css     | 88 ++++++++++---------
 2 files changed, 67 insertions(+), 61 deletions(-)

diff --git a/src/control-presentation/control-presentation.module.css b/src/control-presentation/control-presentation.module.css
index 9b64393a..d4a61ab2 100644
--- a/src/control-presentation/control-presentation.module.css
+++ b/src/control-presentation/control-presentation.module.css
@@ -26,23 +26,25 @@
 
 .control {
     display: contents;
+}
 
-    & > * {
-        /* layout */
-        flex: 1;
-        box-sizing: border-box;
-        margin: 0;
-        padding: 0;
-        width: 100%;
+/* The wrapped control inherits chrome styling so that native elements
+ * (input/select/textarea) render flush with the surrounding wrapper. */
+.control > * {
+    /* layout */
+    flex: 1;
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    width: 100%;
 
-        /* border */
-        border: none;
-        outline: none; /* focus state is handled by the wrapper border */
+    /* border */
+    border: none;
+    outline: none; /* focus state is handled by the wrapper border */
 
-        /* color */
-        background: transparent;
-        color: inherit;
-    }
+    /* color */
+    background: transparent;
+    color: inherit;
 }
 
 .slot {
@@ -53,12 +55,12 @@
 /*
  * Compact 24×24 action button variant for use inside `endSlot`. The 3px
  * border-radius and reduced min-width make it fit the field chrome alongside a
- * 16px icon glyph.
+ * 16px icon glyph. The tripled class boosts specificity above Button's
+ * size-class rules (e.g. `.baseButton.size-normal`) so the height override
+ * wins regardless of stylesheet load order.
  */
-.controlActionButton.controlActionButton {
-    &.controlActionButton {
-        --reactist-btn-height: 24px;
-    }
+.controlActionButton.controlActionButton.controlActionButton {
+    --reactist-btn-height: 24px;
     border-radius: 3px;
     min-width: var(--reactist-btn-height);
 }
diff --git a/src/control-presentation/outlined-control-container.module.css b/src/control-presentation/outlined-control-container.module.css
index 725792e2..a41597c9 100644
--- a/src/control-presentation/outlined-control-container.module.css
+++ b/src/control-presentation/outlined-control-container.module.css
@@ -9,58 +9,62 @@
     /* 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);
-    }
+/* 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. */
+.container: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);
-    }
+/* 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. */
+.container: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(
+/* Interactive border (hover/focus) — suppressed when the control is
+ * in any disabled state. */
+.container:not(
         :has(
             :disabled,
             [aria-disabled]:not([aria-disabled='false']),
             [data-disabled]:not([data-disabled='false'])
         )
-    ) {
-        &:hover {
-            border-color: var(--reactist-inputs-hover);
-        }
+    ):hover {
+    border-color: var(--reactist-inputs-hover);
+}
 
-        &:focus-within {
-            border-color: var(--reactist-inputs-focus);
-        }
-    }
+.container:not(
+        :has(
+            :disabled,
+            [aria-disabled]:not([aria-disabled='false']),
+            [data-disabled]:not([data-disabled='false'])
+        )
+    ):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;
-    }
+/* Invalid: matches the ARIA convention only. */
+.container:has([aria-invalid]:not([aria-invalid='false'])) {
+    border-color: var(--reactist-inputs-alert) !important;
 }
 
 .borderRadiusSmall {

From 3020859d62bf8f7f5b21e4bd91d67bbb990ceab9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 28 May 2026 14:14:29 -0500
Subject: [PATCH 16/18] test: use styles.X for class assertions instead of
 regex matches

Less brittle: refers to the CSS module's resolved className directly rather
than coupling to internal naming. jest-dom's toHaveClass also gives better
failure messages than .className.toMatch().

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../outlined-control-container.test.tsx          | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/control-presentation/outlined-control-container.test.tsx b/src/control-presentation/outlined-control-container.test.tsx
index ea463f69..1dab11dc 100644
--- a/src/control-presentation/outlined-control-container.test.tsx
+++ b/src/control-presentation/outlined-control-container.test.tsx
@@ -6,6 +6,8 @@ import { axe } from 'jest-axe'
 
 import { OutlinedControlContainer } from './outlined-control-container'
 
+import styles from './outlined-control-container.module.css'
+
 describe('OutlinedControlContainer', () => {
     // Note: CSS `:has()`-driven state styling (readonly/disabled tinting, error
     // border via aria-invalid, hover/focus border colors) is verified by visual
@@ -48,11 +50,7 @@ describe('OutlinedControlContainer', () => {
                     <input aria-label="control" />
                 </OutlinedControlContainer>,
             )
-            // The class is hashed by CSS Modules in production but the import yields
-            // an object whose `.container` value is the actual className used.
-            // We assert presence of the class indirectly via toHaveClass with the
-            // module's resolved class name.
-            expect(container.firstElementChild?.className).toMatch(/container/)
+            expect(container.firstElementChild).toHaveClass(styles.container!)
         })
 
         it('applies the small border-radius class by default', () => {
@@ -61,8 +59,8 @@ describe('OutlinedControlContainer', () => {
                     <input aria-label="control" />
                 </OutlinedControlContainer>,
             )
-            expect(container.firstElementChild?.className).toMatch(/borderRadiusSmall/)
-            expect(container.firstElementChild?.className).not.toMatch(/borderRadiusLarge/)
+            expect(container.firstElementChild).toHaveClass(styles.borderRadiusSmall!)
+            expect(container.firstElementChild).not.toHaveClass(styles.borderRadiusLarge!)
         })
 
         it('applies the large border-radius class when borderRadius="large"', () => {
@@ -71,8 +69,8 @@ describe('OutlinedControlContainer', () => {
                     <input aria-label="control" />
                 </OutlinedControlContainer>,
             )
-            expect(container.firstElementChild?.className).toMatch(/borderRadiusLarge/)
-            expect(container.firstElementChild?.className).not.toMatch(/borderRadiusSmall/)
+            expect(container.firstElementChild).toHaveClass(styles.borderRadiusLarge!)
+            expect(container.firstElementChild).not.toHaveClass(styles.borderRadiusSmall!)
         })
     })
 

From cfad4acf9fce34e7ae8d80cb3c90956a84cd6b84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 28 May 2026 16:57:41 -0500
Subject: [PATCH 17/18] fix: widen control action button props

---
 .../control-action-button.test.tsx            | 23 +++++++++++
 .../control-action-button.tsx                 | 41 ++++++++-----------
 2 files changed, 41 insertions(+), 23 deletions(-)
 create mode 100644 src/control-presentation/control-action-button.test.tsx

diff --git a/src/control-presentation/control-action-button.test.tsx b/src/control-presentation/control-action-button.test.tsx
new file mode 100644
index 00000000..0c76aab6
--- /dev/null
+++ b/src/control-presentation/control-action-button.test.tsx
@@ -0,0 +1,23 @@
+import * as React from 'react'
+
+import { render, screen } from '@testing-library/react'
+
+import { ControlActionButton } from './control-action-button'
+
+import styles from './control-presentation.module.css'
+
+describe('ControlActionButton', () => {
+    it('renders the text-label Button branch with compact field styling', () => {
+        render(<ControlActionButton>Clear</ControlActionButton>)
+
+        const button = screen.getByRole('button', { name: 'Clear' })
+        expect(button).toHaveClass(styles.controlActionButton!)
+    })
+
+    it('renders the icon-only IconButton branch with compact field styling', () => {
+        render(<ControlActionButton icon="x" aria-label="Clear" />)
+
+        const button = screen.getByRole('button', { name: 'Clear' })
+        expect(button).toHaveClass(styles.controlActionButton!)
+    })
+})
diff --git a/src/control-presentation/control-action-button.tsx b/src/control-presentation/control-action-button.tsx
index 25c6b0b3..0ba71b94 100644
--- a/src/control-presentation/control-action-button.tsx
+++ b/src/control-presentation/control-action-button.tsx
@@ -6,15 +6,17 @@ import { Button, IconButton } from '../button'
 
 import styles from './control-presentation.module.css'
 
-import type { ComponentProps } from 'react'
+import type { ButtonProps, IconButtonProps } from '../button'
 
 export type ControlActionButtonProps =
     | ({
-          children: React.ReactElement
-      } & Omit<ComponentProps<typeof Button>, 'variant' | 'size'>)
+          children: NonNullable<ButtonProps['children']>
+          icon?: never
+      } & Omit<ButtonProps, 'children' | 'variant' | 'size'>)
     | ({
-          icon?: React.ReactElement
-      } & Omit<ComponentProps<typeof IconButton>, 'variant' | 'size'>)
+          icon: IconButtonProps['icon']
+          children?: never
+      } & Omit<IconButtonProps, 'children' | 'icon' | 'variant' | 'size'>)
 
 /**
  * A compact action button intended for `ControlPresentation`'s `endSlot`. Wraps
@@ -23,26 +25,19 @@ export type ControlActionButtonProps =
  */
 export const ControlActionButton = React.forwardRef<HTMLButtonElement, ControlActionButtonProps>(
     function ControlActionButton({ exceptionallySetClassName, ...props }, ref) {
+        const sharedProps = {
+            ref,
+            variant: 'quaternary' as const,
+            exceptionallySetClassName: classNames([
+                styles.controlActionButton,
+                exceptionallySetClassName,
+            ]),
+        }
+
         return 'children' in props ? (
-            <Button
-                ref={ref}
-                {...props}
-                variant="quaternary"
-                exceptionallySetClassName={classNames([
-                    styles.controlActionButton,
-                    exceptionallySetClassName,
-                ])}
-            />
+            <Button {...props} {...sharedProps} />
         ) : (
-            <IconButton
-                ref={ref}
-                {...props}
-                variant="quaternary"
-                exceptionallySetClassName={classNames([
-                    styles.controlActionButton,
-                    exceptionallySetClassName,
-                ])}
-            />
+            <IconButton {...props} {...sharedProps} />
         )
     },
 )

From 14f7734a42a45ba95c060ce98d0653fc34fbdfb7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Grimm?= <pawel@doist.com>
Date: Thu, 28 May 2026 16:57:49 -0500
Subject: [PATCH 18/18] fix: harden control presentation activation

---
 .../control-presentation.test.tsx             | 48 ++++++++--
 .../control-presentation.tsx                  | 17 +++-
 .../outlined-control-container.module.css     | 50 +++++++---
 .../outlined-control-container.test.tsx       | 81 +++++++++++++++-
 .../outlined-control-container.tsx            | 95 +++++++++++++++++--
 5 files changed, 257 insertions(+), 34 deletions(-)

diff --git a/src/control-presentation/control-presentation.test.tsx b/src/control-presentation/control-presentation.test.tsx
index 6a42b05d..246b4456 100644
--- a/src/control-presentation/control-presentation.test.tsx
+++ b/src/control-presentation/control-presentation.test.tsx
@@ -12,22 +12,22 @@ describe('ControlPresentation', () => {
     it('renders the control passed as children', () => {
         render(
             <ControlPresentation>
-                <input aria-label="Subject" data-testid="subject" />
+                <input aria-label="Subject" />
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
+        const control = screen.getByRole('textbox', { name: 'Subject' })
         expect(control.tagName).toBe('INPUT')
     })
 
-    it('is polymorphic — any element can be the control', () => {
+    it('is polymorphic - any element can be the control', () => {
         render(
             <ControlPresentation>
-                <button type="button" aria-label="Subject" data-testid="subject">
+                <button type="button" aria-label="Subject">
                     Choose
                 </button>
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
+        const control = screen.getByRole('button', { name: 'Subject' })
         expect(control.tagName).toBe('BUTTON')
         expect(control).toHaveTextContent('Choose')
     })
@@ -46,7 +46,7 @@ describe('ControlPresentation', () => {
                 />
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
+        const control = screen.getByRole('textbox', { name: 'Subject' })
         expect(control).toHaveAttribute('type', 'email')
         expect(control).toHaveAttribute('placeholder', 'you@example.com')
         expect(control).toHaveAttribute('data-custom', 'yes')
@@ -57,16 +57,39 @@ describe('ControlPresentation', () => {
     it('focuses the control when a non-interactive startSlot is clicked', async () => {
         render(
             <ControlPresentation startSlot={<TestIcon />}>
-                <input aria-label="Subject" data-testid="subject" />
+                <input aria-label="Subject" />
             </ControlPresentation>,
         )
-        const control = screen.getByTestId('subject')
+        const control = screen.getByRole('textbox', { name: 'Subject' })
         expect(control).not.toHaveFocus()
 
         await userEvent.click(screen.getByTestId('test-icon'))
         expect(control).toHaveFocus()
     })
 
+    it('does not forward interactive slot clicks to the control', async () => {
+        const onControlClick = jest.fn()
+        const onSlotClick = jest.fn()
+        render(
+            <ControlPresentation
+                endSlot={
+                    <button type="button" onClick={onSlotClick}>
+                        Clear
+                    </button>
+                }
+            >
+                <input aria-label="Subject" onClick={onControlClick} />
+            </ControlPresentation>,
+        )
+
+        const slotButton = screen.getByRole('button', { name: 'Clear' })
+        await userEvent.click(slotButton)
+
+        expect(onSlotClick).toHaveBeenCalledTimes(1)
+        expect(onControlClick).not.toHaveBeenCalled()
+        expect(slotButton).toHaveFocus()
+    })
+
     it('merges exceptionallySetClassName onto the wrapper', () => {
         const { container } = render(
             <ControlPresentation exceptionallySetClassName="custom-class">
@@ -93,6 +116,15 @@ describe('ControlPresentation', () => {
         expect(screen.getByTestId('b')).toBeInTheDocument()
     })
 
+    it('renders numeric zero slot content', () => {
+        render(
+            <ControlPresentation startSlot={0} endSlot={0}>
+                <input aria-label="Subject" />
+            </ControlPresentation>,
+        )
+        expect(screen.getAllByText('0')).toHaveLength(2)
+    })
+
     describe('a11y', () => {
         it('renders with no a11y violations', async () => {
             const { container } = render(
diff --git a/src/control-presentation/control-presentation.tsx b/src/control-presentation/control-presentation.tsx
index b55ab497..b7524666 100644
--- a/src/control-presentation/control-presentation.tsx
+++ b/src/control-presentation/control-presentation.tsx
@@ -24,7 +24,12 @@ export type ControlPresentationProps = {
      * or dropdown-trigger chevron).
      */
     endSlot?: SlotContent
-} & Omit<ComponentProps<typeof OutlinedControlContainer>, 'borderRadius'>
+
+    /**
+     * The single control element to wrap.
+     */
+    children: React.ReactElement
+} & Omit<ComponentProps<typeof OutlinedControlContainer>, 'borderRadius' | 'children'>
 
 /**
  * The visual chrome of an inline, single-row, text-field-style input: a
@@ -47,11 +52,15 @@ export const ControlPresentation = forwardRef<HTMLDivElement, ControlPresentatio
                 onClick={onClick}
                 exceptionallySetClassName={classNames(styles.container, exceptionallySetClassName)}
             >
-                {startSlot ? (
+                {startSlot != null ? (
                     <Slot className={[styles.slot, styles.startSlot]}>{startSlot}</Slot>
                 ) : null}
-                <div className={styles.control}>{children}</div>
-                {endSlot ? <Slot className={[styles.slot, styles.endSlot]}>{endSlot}</Slot> : null}
+                <div className={styles.control} data-reactist-control>
+                    {children}
+                </div>
+                {endSlot != null ? (
+                    <Slot className={[styles.slot, styles.endSlot]}>{endSlot}</Slot>
+                ) : null}
             </OutlinedControlContainer>
         )
     },
diff --git a/src/control-presentation/outlined-control-container.module.css b/src/control-presentation/outlined-control-container.module.css
index a41597c9..d4aa0a07 100644
--- a/src/control-presentation/outlined-control-container.module.css
+++ b/src/control-presentation/outlined-control-container.module.css
@@ -18,11 +18,17 @@
  * The :not(='false') exclusion treats aria-readonly="false" /
  * data-readonly="false" as "not read-only" per the ARIA spec. */
 .container:has(
-    input:read-only,
-    textarea:read-only,
-    [aria-readonly]:not([aria-readonly='false']),
-    [data-readonly]:not([data-readonly='false'])
-) {
+    [data-reactist-control] input:read-only,
+    [data-reactist-control] textarea:read-only,
+    [data-reactist-control] [aria-readonly]:not([aria-readonly='false']),
+    [data-reactist-control] [data-readonly]:not([data-readonly='false'])
+),
+.container:not(:has([data-reactist-control])):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);
 }
@@ -32,17 +38,29 @@
  * keep elements focusable while announcing as disabled), and the
  * data-attr convention used by Ariakit/Radix. */
 .container:has(
-    :disabled,
-    [aria-disabled]:not([aria-disabled='false']),
-    [data-disabled]:not([data-disabled='false'])
-) {
+    [data-reactist-control] :disabled,
+    [data-reactist-control] [aria-disabled]:not([aria-disabled='false']),
+    [data-reactist-control] [data-disabled]:not([data-disabled='false'])
+),
+.container:not(:has([data-reactist-control])):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. */
-.container:not(
+.container:has([data-reactist-control]):not(
+        :has(
+            [data-reactist-control] :disabled,
+            [data-reactist-control] [aria-disabled]:not([aria-disabled='false']),
+            [data-reactist-control] [data-disabled]:not([data-disabled='false'])
+        )
+    ):hover,
+.container:not(:has([data-reactist-control])):not(
         :has(
             :disabled,
             [aria-disabled]:not([aria-disabled='false']),
@@ -52,7 +70,14 @@
     border-color: var(--reactist-inputs-hover);
 }
 
-.container:not(
+.container:has([data-reactist-control]):not(
+        :has(
+            [data-reactist-control] :disabled,
+            [data-reactist-control] [aria-disabled]:not([aria-disabled='false']),
+            [data-reactist-control] [data-disabled]:not([data-disabled='false'])
+        )
+    ):focus-within,
+.container:not(:has([data-reactist-control])):not(
         :has(
             :disabled,
             [aria-disabled]:not([aria-disabled='false']),
@@ -63,7 +88,8 @@
 }
 
 /* Invalid: matches the ARIA convention only. */
-.container:has([aria-invalid]:not([aria-invalid='false'])) {
+.container:has([data-reactist-control] [aria-invalid]:not([aria-invalid='false'])),
+.container:not(:has([data-reactist-control])):has([aria-invalid]:not([aria-invalid='false'])) {
     border-color: var(--reactist-inputs-alert) !important;
 }
 
diff --git a/src/control-presentation/outlined-control-container.test.tsx b/src/control-presentation/outlined-control-container.test.tsx
index 1dab11dc..95a90766 100644
--- a/src/control-presentation/outlined-control-container.test.tsx
+++ b/src/control-presentation/outlined-control-container.test.tsx
@@ -78,16 +78,46 @@ describe('OutlinedControlContainer', () => {
         it('focuses the inner control when the wrapper is clicked', async () => {
             const { container } = render(
                 <OutlinedControlContainer>
-                    <input data-testid="control" aria-label="control" />
+                    <input aria-label="control" />
                 </OutlinedControlContainer>,
             )
-            const control = screen.getByTestId('control')
+            const control = screen.getByRole('textbox', { name: 'control' })
             expect(control).not.toHaveFocus()
 
             await userEvent.click(container.firstElementChild as Element)
             expect(control).toHaveFocus()
         })
 
+        it('does not dispatch a synthetic click for text inputs', async () => {
+            const onControlClick = jest.fn()
+            const { container } = render(
+                <OutlinedControlContainer>
+                    <input aria-label="control" onClick={onControlClick} />
+                </OutlinedControlContainer>,
+            )
+            const control = screen.getByRole('textbox', { name: 'control' })
+
+            await userEvent.click(container.firstElementChild as Element)
+
+            expect(control).toHaveFocus()
+            expect(onControlClick).not.toHaveBeenCalled()
+        })
+
+        it('does not dispatch a synthetic click for textareas', async () => {
+            const onControlClick = jest.fn()
+            const { container } = render(
+                <OutlinedControlContainer>
+                    <textarea aria-label="control" onClick={onControlClick} />
+                </OutlinedControlContainer>,
+            )
+            const control = screen.getByRole('textbox', { name: 'control' })
+
+            await userEvent.click(container.firstElementChild as Element)
+
+            expect(control).toHaveFocus()
+            expect(onControlClick).not.toHaveBeenCalled()
+        })
+
         it('does not double-fire when the inner control is clicked directly', async () => {
             const onControlClick = jest.fn()
             render(
@@ -101,6 +131,23 @@ describe('OutlinedControlContainer', () => {
             expect(onControlClick).toHaveBeenCalledTimes(1)
         })
 
+        it('activates button-like controls when the wrapper is clicked', async () => {
+            const onControlClick = jest.fn()
+            const { container } = render(
+                <OutlinedControlContainer>
+                    <button type="button" onClick={onControlClick}>
+                        Choose
+                    </button>
+                </OutlinedControlContainer>,
+            )
+            const control = screen.getByRole('button', { name: 'Choose' })
+
+            await userEvent.click(container.firstElementChild as Element)
+
+            expect(control).toHaveFocus()
+            expect(onControlClick).toHaveBeenCalledTimes(1)
+        })
+
         it('calls a consumer onClick passed via Box props when the wrapper is clicked', async () => {
             const onClick = jest.fn()
             const { container } = render(
@@ -133,6 +180,36 @@ describe('OutlinedControlContainer', () => {
             expect(control).toHaveFocus()
         })
 
+        it('does not activate aria-disabled controls from wrapper clicks', async () => {
+            const onControlClick = jest.fn()
+            const { container } = render(
+                <OutlinedControlContainer>
+                    <button type="button" aria-disabled onClick={onControlClick}>
+                        Choose
+                    </button>
+                </OutlinedControlContainer>,
+            )
+
+            await userEvent.click(container.firstElementChild as Element)
+
+            expect(onControlClick).not.toHaveBeenCalled()
+        })
+
+        it('does not activate data-disabled controls from wrapper clicks', async () => {
+            const onControlClick = jest.fn()
+            const { container } = render(
+                <OutlinedControlContainer>
+                    <button type="button" data-disabled onClick={onControlClick}>
+                        Choose
+                    </button>
+                </OutlinedControlContainer>,
+            )
+
+            await userEvent.click(container.firstElementChild as Element)
+
+            expect(onControlClick).not.toHaveBeenCalled()
+        })
+
         it('uses showPicker for native <select>', async () => {
             const showPicker = jest.fn()
             const { container } = render(
diff --git a/src/control-presentation/outlined-control-container.tsx b/src/control-presentation/outlined-control-container.tsx
index 50fd8dd0..2e464952 100644
--- a/src/control-presentation/outlined-control-container.tsx
+++ b/src/control-presentation/outlined-control-container.tsx
@@ -7,14 +7,42 @@ import styles from './outlined-control-container.module.css'
 
 import type { ObfuscatedClassName } from '../utils/common-types'
 
+const CONTROL_SCOPE_SELECTOR = '[data-reactist-control]'
+const FOCUSABLE_CONTROL_SELECTOR = [
+    'input',
+    'select',
+    'textarea',
+    'button',
+    'a[href]',
+    '[role="button"]',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',')
+const INTERACTIVE_SELECTOR = [
+    'button',
+    'a[href]',
+    'input',
+    'select',
+    'textarea',
+    '[role="button"]',
+].join(',')
+const TEXT_ENTRY_INPUT_TYPES = new Set([
+    'email',
+    'number',
+    'password',
+    'search',
+    'tel',
+    'text',
+    'url',
+])
+
 export type OutlinedControlContainerProps = {
     /**
      * The control element (or a layout containing one) to wrap. The wrapper
      * chrome (border, hover/focus, disabled/read-only background tint, error
      * border) derives from attributes on the focusable descendant. Clicking
-     * the wrapper focuses the first focusable input/select/textarea
-     * descendant and dispatches a `.click()` (or `.showPicker()` for native
-     * `<select>`).
+     * the wrapper focuses the first focusable control descendant. It activates
+     * button-like controls with `.click()` and native `<select>` elements with
+     * `.showPicker()`.
      *
      * Contract: assumes a single focusable control descendant. Behavior is
      * undefined if multiple focusable controls are inside.
@@ -60,19 +88,26 @@ export const OutlinedControlContainer = forwardRef<HTMLDivElement, OutlinedContr
         function handleWrapperClick(event: React.MouseEvent<HTMLDivElement>) {
             if (isDispatchedReentryRef.current) 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
+            const control = findWrappedControl(wrapper)
+            if (!control) {
+                onClick?.(event)
+                return
+            }
+
+            if (isInteractiveElementOutsideControl(event.target, control)) return
+
+            onClick?.(event)
 
             if (event.target instanceof Node && control.contains(event.target)) return
 
             control.focus()
+            if (isDisabledControl(control) || isTextEntryControl(control)) return
+
             if (control instanceof HTMLSelectElement && typeof control.showPicker === 'function') {
                 try {
                     control.showPicker()
@@ -87,8 +122,17 @@ export const OutlinedControlContainer = forwardRef<HTMLDivElement, OutlinedContr
             // back to this handler. Always clear after the dispatch returns so the
             // guard cannot latch if a consumer's onClick stops propagation.
             isDispatchedReentryRef.current = true
-            control.click()
+            let didThrow = false
+            let thrownError: unknown
+            try {
+                control.click()
+            } catch (error) {
+                didThrow = true
+                thrownError = error
+            }
             isDispatchedReentryRef.current = false
+
+            if (didThrow) throw thrownError
         }
 
         return (
@@ -108,3 +152,38 @@ export const OutlinedControlContainer = forwardRef<HTMLDivElement, OutlinedContr
         )
     },
 )
+
+function findWrappedControl(wrapper: HTMLElement | null) {
+    if (!wrapper) return null
+
+    const controlScope = wrapper.querySelector<HTMLElement>(CONTROL_SCOPE_SELECTOR)
+    const searchRoot = controlScope ?? wrapper
+    if (searchRoot.matches(FOCUSABLE_CONTROL_SELECTOR)) return searchRoot
+
+    return searchRoot.querySelector<HTMLElement>(FOCUSABLE_CONTROL_SELECTOR)
+}
+
+function isInteractiveElementOutsideControl(target: EventTarget, control: HTMLElement) {
+    if (!(target instanceof Element) || control.contains(target)) return false
+    return target.closest(INTERACTIVE_SELECTOR) != null
+}
+
+function isDisabledControl(control: HTMLElement) {
+    return (
+        control.hasAttribute('disabled') ||
+        isTruthyStateAttribute(control, 'aria-disabled') ||
+        isTruthyStateAttribute(control, 'data-disabled')
+    )
+}
+
+function isTruthyStateAttribute(control: HTMLElement, attribute: string) {
+    const value = control.getAttribute(attribute)
+    return value != null && value !== 'false'
+}
+
+function isTextEntryControl(control: HTMLElement) {
+    if (control instanceof HTMLTextAreaElement) return true
+    if (!(control instanceof HTMLInputElement)) return false
+
+    return TEXT_ENTRY_INPUT_TYPES.has(control.type)
+}