Basic controls

The Common subpath provides native basic controls for ordinary React state and browser forms. They expose real element refs, standard native attributes, semantic value callbacks, stable parts, and canonical state attributes without an Arc command binding.

import {
    Button,
    Checkbox,
    IconButton,
    Radio,
    Surface,
    Switch,
    TextArea,
    TextInput,
} from '@cratis/components/Common';

<Surface as='section' aria-label='Preferences'>
    <TextInput
        name='displayName'
        aria-label='Display name'
        defaultValue='Sample User'
        onChange={(value) => console.log(value)}
    />
    <TextArea name='notes' aria-label='Notes' />
    <Checkbox name='updates' value='email' label='Email updates' />
    <Radio name='frequency' value='daily' label='Daily' />
    <Switch name='notifications' value='enabled' label='Enable notifications' />
    <IconButton icon={<span aria-hidden='true'>+</span>} aria-label='Add preference' />
    <Button label='Save preferences' type='submit' />
</Surface>

API reference

Component	Native element and ref	Semantic value	Stable parts	Canonical states
Button	button / HTMLButtonElement	Native click and form action	root, spinner, icon, label	disabled, loading, variant, tone, shape, size on root
IconButton	button / HTMLButtonElement	Uses Button click semantics	root, spinner, icon, label	disabled, loading on root
TextInput	input / HTMLInputElement	string	root	disabled, invalid, readonly
TextArea	textarea / HTMLTextAreaElement	string	root	disabled, invalid, readonly
Checkbox	input[type=checkbox] / HTMLInputElement	boolean	root, input, box, indicator, label	selected, disabled, invalid, readonly
Radio	one input[type=radio] / HTMLInputElement	boolean when checked	root, input, box, indicator, label	selected, disabled, invalid, readonly
Switch	input[type=checkbox][role=switch] / HTMLInputElement	boolean	root, input, control, handle, label	selected, disabled, invalid, readonly
Surface	div, section, or article / HTMLElement	none	root	none

IconButton requires aria-label and delegates to Button; it does not add another button or interaction layer. It accepts the same semantic variant, tone, shape, size, loading, and disabled props as Button.

TextInput accepts the native text-like types text, email, password, search, tel, and url. TextInput and TextArea preserve native controlled (value) and uncontrolled (defaultValue) behavior.

Radio represents exactly one native option. Give related options the same name; the browser owns grouping. Components does not add radio-group state or keyboard orchestration.

Change metadata

Each value control uses ChangeHandler<T>:

onChange?: (value: T, meta?: ChangeMeta) => void;

A user change supplies { source: 'user', nativeEvent }, where nativeEvent is the real browser Event. The optional second argument keeps a one-argument callback, including a React state setter, directly assignable.

Native forms and read-only choices

The controls preserve name, value, form, checked, defaultChecked, value, and defaultValue on the real native element. Uncontrolled controls therefore submit and reset through browser form behavior.

HTML does not define native read-only behavior for checkboxes and radios. Checkbox, Radio, and Switch keep a read-only selected control enabled so its name and value still submit, expose the canonical data-readonly state, and prevent user toggling. Checkbox and Switch additionally expose supported aria-readonly semantics; native radio does not allow that ARIA attribute. Use disabled instead when the control must be excluded from submission.

For progress UI, use ProgressBar and its existing ProgressBarProps contract from @cratis/components/Display; Common does not define a second progress component.