0
# React Types Shared
1

2
React Types Shared provides comprehensive TypeScript type definitions for the React Spectrum ecosystem. It serves as the foundational typing layer for accessible, adaptive UI components, offering interfaces for DOM interactions, input handling, styling systems, drag-and-drop functionality, collections, and internationalization support.
3

4
## Package Information
5

6
- **Package Name**: @react-types/shared
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-types/shared`
10
- **Peer Dependencies**: React ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
11

12
## Core Imports
13

14
```typescript
15
import {
16
  // DOM and ARIA
17
  DOMProps,
18
  AriaLabelingProps,
19
  FocusableDOMProps,
20
  TextInputDOMProps,
21
  LinkDOMProps,
22
  
23
  // Events
24
  PressEvent,
25
  HoverEvent,
26
  FocusEvent,
27
  
28
  // Collections and Selection
29
  Collection,
30
  Node,
31
  Selection,
32
  SingleSelection,
33
  MultipleSelection,
34
  
35
  // Drag and Drop
36
  DropEvent,
37
  DragItem,
38
  DropOperation,
39
  
40
  // Design Tokens
41
  DimensionValue,
42
  ColorValue,
43
  BorderSizeValue,
44
  BorderRadiusValue,
45
  
46
  // Styling
47
  StyleProps,
48
  Responsive,
49
  
50
  // Input Handling
51
  InputBase,
52
  ValueBase,
53
  Validation,
54
  
55
  // References
56
  DOMRef,
57
  FocusableRef,
58
  DOMRefValue,
59
  FocusableRefValue,
60
  
61
  // Labelable
62
  LabelableProps,
63
  SpectrumLabelableProps,
64
  
65
  // Basic Types
66
  Key,
67
  Direction,
68
  Orientation,
69
  ValidationState,
70
  PointerType
71
} from "@react-types/shared";
72
```
73

74
CommonJS:
75

76
```javascript
77
const {
78
  DOMProps,
79
  AriaLabelingProps,
80
  PressEvent,
81
  Selection,
82
  Key,
83
  StyleProps,
84
  Collection,
85
  DropEvent,
86
  DimensionValue,
87
  ColorValue,
88
  DOMRef,
89
  FocusableRef,
90
  LabelableProps,
91
  Direction,
92
  Orientation
93
} = require("@react-types/shared");
94
```
95

96
## Basic Usage
97

98
```typescript
99
import { DOMProps, AriaLabelingProps, PressEvent } from "@react-types/shared";
100

101
// Using DOM props with ARIA labeling
102
interface ButtonProps extends DOMProps, AriaLabelingProps {
103
  children: React.ReactNode;
104
  onPress?: (e: PressEvent) => void;
105
}
106

107
function Button({ id, "aria-label": ariaLabel, children, onPress }: ButtonProps) {
108
  return (
109
    <button
110
      id={id}
111
      aria-label={ariaLabel}
112
      onClick={(e) => onPress?.({ 
113
        type: 'press', 
114
        pointerType: 'mouse', 
115
        target: e.target as Element,
116
        continuePropagation: () => {},
117
        // ... other press event properties
118
      })}
119
    >
120
      {children}
121
    </button>
122
  );
123
}
124
```
125

126
## Architecture
127

128
React Types Shared is organized around several key type categories:
129

130
- **DOM Integration**: Comprehensive DOM attributes, events, and ARIA support for web accessibility
131
- **Input System**: Validation, value management, and input-specific type definitions
132
- **Event System**: Custom event types with propagation control and pointer type awareness
133
- **Collection Framework**: Generic interfaces for lists, grids, trees, and other data structures
134
- **Selection Model**: Single and multiple selection patterns with keyboard navigation
135
- **Drag & Drop**: Complete drag-and-drop type system with file and directory support
136
- **Styling System**: Responsive design tokens and layout props (flexbox, grid, positioning)
137
- **Accessibility**: ARIA attributes, focus management, and screen reader support
138
- **Internationalization**: RTL/LTR layout direction and locale-aware typing
139

140
## Core Types
141

142
```typescript { .api }
143
// Fundamental key type used throughout collections
144
type Key = string | number;
145

146
// Layout direction for internationalization
147
type Direction = "ltr" | "rtl";
148

149
// Component orientation
150
type Orientation = "horizontal" | "vertical";
151

152
// Validation states
153
type ValidationState = "valid" | "invalid";
154

155
// Selection modes for collections
156
type SelectionMode = "none" | "single" | "multiple";
157
type Selection = "all" | Set<Key>;
158

159
// Pointer interaction types
160
type PointerType = "mouse" | "pen" | "touch" | "keyboard" | "virtual";
161
```
162

163
## Capabilities
164

165
### DOM and ARIA Integration
166

167
Essential DOM properties and ARIA attributes for building accessible web components. Includes comprehensive event handling and element attribute management.
168

169
```typescript { .api }
170
interface DOMProps {
171
  id?: string;
172
}
173

174
interface AriaLabelingProps {
175
  "aria-label"?: string;
176
  "aria-labelledby"?: string;
177
  "aria-describedby"?: string;
178
  "aria-details"?: string;
179
}
180

181
interface FocusableDOMProps extends DOMProps {
182
  excludeFromTabOrder?: boolean;
183
}
184
```
185

186
[DOM and ARIA](./dom-aria.md)
187

188
### Input Handling and Validation
189

190
Comprehensive input management including validation, value handling, form integration, and text input specific functionality.
191

192
```typescript { .api }
193
interface InputBase {
194
  isDisabled?: boolean;
195
  isReadOnly?: boolean;
196
}
197

198
interface ValueBase<T, C = T> {
199
  value?: T;
200
  defaultValue?: T;
201
  onChange?: (value: C) => void;
202
}
203

204
interface Validation<T = unknown> {
205
  isRequired?: boolean;
206
  isInvalid?: boolean;
207
  validationBehavior?: "aria" | "native";
208
  validate?: (value: T) => ValidationError | true | null | undefined;
209
}
210
```
211

212
[Input Handling](./input-handling.md)
213

214
### Event System
215

216
Custom event system with propagation control, pointer type awareness, and comprehensive interaction support including press, hover, focus, and move events.
217

218
```typescript { .api }
219
interface PressEvent {
220
  type: "pressstart" | "pressend" | "pressup" | "press";
221
  pointerType: PointerType;
222
  target: Element;
223
  shiftKey: boolean;
224
  ctrlKey: boolean;
225
  metaKey: boolean;
226
  altKey: boolean;
227
  continuePropagation(): void;
228
}
229

230
interface HoverEvent {
231
  type: "hoverstart" | "hoverend";
232
  pointerType: "mouse" | "pen";
233
  target: HTMLElement;
234
}
235
```
236

237
[Event System](./events.md)
238

239
### Collections and Data Structures
240

241
Generic collection interfaces supporting lists, grids, trees, and other data structures with keyboard navigation, sorting, expansion, and loading states.
242

243
```typescript { .api }
244
interface Collection<T> extends Iterable<T> {
245
  readonly size: number;
246
  getKeys(): Iterable<Key>;
247
  getItem(key: Key): T | null;
248
  at(idx: number): T | null;
249
  getKeyBefore(key: Key): Key | null;
250
  getKeyAfter(key: Key): Key | null;
251
  getFirstKey(): Key | null;
252
  getLastKey(): Key | null;
253
}
254

255
interface Node<T> {
256
  type: string;
257
  key: Key;
258
  value: T | null;
259
  level: number;
260
  hasChildNodes: boolean;
261
  rendered: ReactNode;
262
  textValue: string;
263
}
264
```
265

266
[Collections](./collections.md)
267

268
### Selection Management
269

270
Single and multiple selection patterns with keyboard navigation, disabled items, and selection behavior configuration.
271

272
```typescript { .api }
273
interface SingleSelection {
274
  disallowEmptySelection?: boolean;
275
  selectedKey?: Key | null;
276
  defaultSelectedKey?: Key;
277
  onSelectionChange?: (key: Key | null) => void;
278
}
279

280
interface MultipleSelection {
281
  selectionMode?: SelectionMode;
282
  disallowEmptySelection?: boolean;
283
  selectedKeys?: "all" | Iterable<Key>;
284
  defaultSelectedKeys?: "all" | Iterable<Key>;
285
  onSelectionChange?: (keys: Selection) => void;
286
  disabledKeys?: Iterable<Key>;
287
}
288
```
289

290
[Selection](./selection.md)
291

292
### Drag and Drop
293

294
Complete drag-and-drop system supporting files, directories, text, and custom data types with collection-aware drop targets and reordering.
295

296
```typescript { .api }
297
interface DropEvent extends DragDropEvent {
298
  type: "drop";
299
  dropOperation: DropOperation;
300
  items: DropItem[];
301
}
302

303
interface DragItem {
304
  [type: string]: string;
305
}
306

307
type DropOperation = "copy" | "link" | "move" | "cancel";
308
type DropItem = TextDropItem | FileDropItem | DirectoryDropItem;
309
```
310

311
[Drag and Drop](./drag-drop.md)
312

313
### Styling and Layout
314

315
Responsive design system with design tokens for dimensions, colors, spacing, and comprehensive layout props supporting flexbox, grid, and positioning.
316

317
```typescript { .api }
318
interface StyleProps {
319
  margin?: Responsive<DimensionValue>;
320
  padding?: Responsive<DimensionValue>;
321
  width?: Responsive<DimensionValue>;
322
  height?: Responsive<DimensionValue>;
323
  position?: Responsive<"static" | "relative" | "absolute" | "fixed" | "sticky">;
324
  isHidden?: Responsive<boolean>;
325
}
326

327
type DimensionValue = 
328
  | "size-0" | "size-10" | "size-25" | "size-50" // ... many more
329
  | (string & {})
330
  | number;
331

332
type Responsive<T> = T | ResponsiveProp<T>;
333
```
334

335
[Styling and Layout](./styling.md)
336

337
### Design Tokens
338

339
Standardized design tokens (DNA) from the Adobe Spectrum design system, providing consistent values for dimensions, colors, borders, and other visual properties.
340

341
```typescript { .api }
342
type DimensionValue =
343
  | "size-0" | "size-10" | "size-25" | "size-50" | "size-100"
344
  | "size-200" | "size-300" | "size-400" | "size-500" | "size-600"
345
  // ... many more size tokens
346
  | "static-size-0" | "static-size-10" | "static-size-25"
347
  // ... static size tokens  
348
  | "single-line-height" | "single-line-width"
349
  | (string & {}) | number;
350

351
type ColorValue = 
352
  | "gray-50" | "gray-100" | "gray-200" // ... grayscale
353
  | "red-400" | "red-500" | "red-600" | "red-700" // ... brand colors
354
  | "static-black" | "static-white" // ... static colors
355
  | SemanticColorValue;
356

357
type BorderSizeValue = "thin" | "thick" | "thicker" | "thickest" | "none";
358
type BorderRadiusValue = "xsmall" | "small" | "regular" | "medium" | "large";
359
```
360

361
[Design Tokens](./design-tokens.md)
362

363
### DOM References
364

365
DOM reference types and utilities for safe DOM node access and focus management with enhanced forwardRef support.
366

367
```typescript { .api }
368
interface DOMRefValue<T extends HTMLElement = HTMLElement> {
369
  UNSAFE_getDOMNode(): T | null;
370
}
371

372
interface FocusableRefValue<T extends HTMLElement = HTMLElement, D extends HTMLElement = T> 
373
  extends DOMRefValue<D> {
374
  focus(): void;
375
}
376

377
type DOMRef<T extends HTMLElement = HTMLElement> = Ref<DOMRefValue<T>>;
378
type FocusableRef<T extends HTMLElement = HTMLElement> = Ref<FocusableRefValue<T>>;
379
```
380

381
[DOM References](./refs.md)
382

383
### Labelable Components
384

385
Label positioning, alignment, and form-related properties for consistent labeling patterns across components.
386

387
```typescript { .api }
388
type LabelPosition = "top" | "side";
389
type Alignment = "start" | "end";
390
type NecessityIndicator = "icon" | "label";
391

392
interface LabelableProps {
393
  label?: ReactNode;
394
}
395

396
interface SpectrumLabelableProps extends LabelableProps {
397
  labelPosition?: LabelPosition;
398
  labelAlign?: Alignment;
399
  necessityIndicator?: NecessityIndicator;
400
  isRequired?: boolean;
401
  contextualHelp?: ReactNode;
402
}
403
```
404

405
[Labelable Components](./labelable.md)
406

407
## Type Definitions
408

409
```typescript { .api }
410
// Router configuration for type-safe URLs
411
interface RouterConfig {}
412
type Href = RouterConfig extends {href: infer H} ? H : string;
413
type RouterOptions = RouterConfig extends {routerOptions: infer O} ? O : never;
414

415
// Validation types
416
type ValidationError = string | string[];
417
type ValidationErrors = Record<string, ValidationError>;
418
type ValidationFunction<T> = (value: T) => ValidationError | true | null | undefined;
419

420
// Range value for inputs like sliders
421
interface RangeValue<T> {
422
  start: T;
423
  end: T;
424
}
425

426
// Color version for design system
427
type ColorVersion = 5 | 6;
428

429
// Focus strategy for keyboard navigation
430
type FocusStrategy = "first" | "last";
431

432
// Basic foundational types
433
type Key = string | number;
434
type Direction = "ltr" | "rtl";
435
type Orientation = "horizontal" | "vertical";
436

437
// Removable item interface
438
interface Removable<T, R> {
439
  isRemovable?: boolean;
440
  onRemove?: (value: T, event?: SyntheticEvent) => R;
441
}
442

443
// Label positioning and alignment (moved to Labelable Components section)
444
type LabelPosition = "top" | "side";
445
type Alignment = "start" | "end";
446
type NecessityIndicator = "icon" | "label";
447
```