or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

collections.mddesign-tokens.mddom-aria.mddrag-drop.mdevents.mdindex.mdinput-handling.mdlabelable.mdrefs.mdselection.mdstyling.md
tile.json

tessl/npm-react-types--shared

Shared TypeScript type definitions for React Spectrum components and hooks, providing common interfaces for DOM interactions, styling, accessibility, internationalization, and component behavior across the React Spectrum ecosystem

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@react-types/shared@3.32.x

To install, run

npx @tessl/cli install tessl/npm-react-types--shared@3.32.0

index.mddocs/

React Types Shared

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.

Package Information

  • Package Name: @react-types/shared
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @react-types/shared
  • Peer Dependencies: React ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1

Core Imports

import {
  // DOM and ARIA
  DOMProps,
  AriaLabelingProps,
  FocusableDOMProps,
  TextInputDOMProps,
  LinkDOMProps,
  
  // Events
  PressEvent,
  HoverEvent,
  FocusEvent,
  
  // Collections and Selection
  Collection,
  Node,
  Selection,
  SingleSelection,
  MultipleSelection,
  
  // Drag and Drop
  DropEvent,
  DragItem,
  DropOperation,
  
  // Design Tokens
  DimensionValue,
  ColorValue,
  BorderSizeValue,
  BorderRadiusValue,
  
  // Styling
  StyleProps,
  Responsive,
  
  // Input Handling
  InputBase,
  ValueBase,
  Validation,
  
  // References
  DOMRef,
  FocusableRef,
  DOMRefValue,
  FocusableRefValue,
  
  // Labelable
  LabelableProps,
  SpectrumLabelableProps,
  
  // Basic Types
  Key,
  Direction,
  Orientation,
  ValidationState,
  PointerType
} from "@react-types/shared";

CommonJS:

const {
  DOMProps,
  AriaLabelingProps,
  PressEvent,
  Selection,
  Key,
  StyleProps,
  Collection,
  DropEvent,
  DimensionValue,
  ColorValue,
  DOMRef,
  FocusableRef,
  LabelableProps,
  Direction,
  Orientation
} = require("@react-types/shared");

Basic Usage

import { DOMProps, AriaLabelingProps, PressEvent } from "@react-types/shared";

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

function Button({ id, "aria-label": ariaLabel, children, onPress }: ButtonProps) {
  return (
    <button
      id={id}
      aria-label={ariaLabel}
      onClick={(e) => onPress?.({ 
        type: 'press', 
        pointerType: 'mouse', 
        target: e.target as Element,
        continuePropagation: () => {},
        // ... other press event properties
      })}
    >
      {children}
    </button>
  );
}

Architecture

React Types Shared is organized around several key type categories:

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

Core Types

// Fundamental key type used throughout collections
type Key = string | number;

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

// Component orientation
type Orientation = "horizontal" | "vertical";

// Validation states
type ValidationState = "valid" | "invalid";

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

// Pointer interaction types
type PointerType = "mouse" | "pen" | "touch" | "keyboard" | "virtual";

Capabilities

DOM and ARIA Integration

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

interface DOMProps {
  id?: string;
}

interface AriaLabelingProps {
  "aria-label"?: string;
  "aria-labelledby"?: string;
  "aria-describedby"?: string;
  "aria-details"?: string;
}

interface FocusableDOMProps extends DOMProps {
  excludeFromTabOrder?: boolean;
}

DOM and ARIA

Input Handling and Validation

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

interface InputBase {
  isDisabled?: boolean;
  isReadOnly?: boolean;
}

interface ValueBase<T, C = T> {
  value?: T;
  defaultValue?: T;
  onChange?: (value: C) => void;
}

interface Validation<T = unknown> {
  isRequired?: boolean;
  isInvalid?: boolean;
  validationBehavior?: "aria" | "native";
  validate?: (value: T) => ValidationError | true | null | undefined;
}

Input Handling

Event System

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

interface PressEvent {
  type: "pressstart" | "pressend" | "pressup" | "press";
  pointerType: PointerType;
  target: Element;
  shiftKey: boolean;
  ctrlKey: boolean;
  metaKey: boolean;
  altKey: boolean;
  continuePropagation(): void;
}

interface HoverEvent {
  type: "hoverstart" | "hoverend";
  pointerType: "mouse" | "pen";
  target: HTMLElement;
}

Event System

Collections and Data Structures

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

interface Collection<T> extends Iterable<T> {
  readonly size: number;
  getKeys(): Iterable<Key>;
  getItem(key: Key): T | null;
  at(idx: number): T | null;
  getKeyBefore(key: Key): Key | null;
  getKeyAfter(key: Key): Key | null;
  getFirstKey(): Key | null;
  getLastKey(): Key | null;
}

interface Node<T> {
  type: string;
  key: Key;
  value: T | null;
  level: number;
  hasChildNodes: boolean;
  rendered: ReactNode;
  textValue: string;
}

Collections

Selection Management

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

interface SingleSelection {
  disallowEmptySelection?: boolean;
  selectedKey?: Key | null;
  defaultSelectedKey?: Key;
  onSelectionChange?: (key: Key | null) => void;
}

interface MultipleSelection {
  selectionMode?: SelectionMode;
  disallowEmptySelection?: boolean;
  selectedKeys?: "all" | Iterable<Key>;
  defaultSelectedKeys?: "all" | Iterable<Key>;
  onSelectionChange?: (keys: Selection) => void;
  disabledKeys?: Iterable<Key>;
}

Selection

Drag and Drop

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

interface DropEvent extends DragDropEvent {
  type: "drop";
  dropOperation: DropOperation;
  items: DropItem[];
}

interface DragItem {
  [type: string]: string;
}

type DropOperation = "copy" | "link" | "move" | "cancel";
type DropItem = TextDropItem | FileDropItem | DirectoryDropItem;

Drag and Drop

Styling and Layout

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

interface StyleProps {
  margin?: Responsive<DimensionValue>;
  padding?: Responsive<DimensionValue>;
  width?: Responsive<DimensionValue>;
  height?: Responsive<DimensionValue>;
  position?: Responsive<"static" | "relative" | "absolute" | "fixed" | "sticky">;
  isHidden?: Responsive<boolean>;
}

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

type Responsive<T> = T | ResponsiveProp<T>;

Styling and Layout

Design Tokens

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

type DimensionValue =
  | "size-0" | "size-10" | "size-25" | "size-50" | "size-100"
  | "size-200" | "size-300" | "size-400" | "size-500" | "size-600"
  // ... many more size tokens
  | "static-size-0" | "static-size-10" | "static-size-25"
  // ... static size tokens  
  | "single-line-height" | "single-line-width"
  | (string & {}) | number;

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

type BorderSizeValue = "thin" | "thick" | "thicker" | "thickest" | "none";
type BorderRadiusValue = "xsmall" | "small" | "regular" | "medium" | "large";

Design Tokens

DOM References

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

interface DOMRefValue<T extends HTMLElement = HTMLElement> {
  UNSAFE_getDOMNode(): T | null;
}

interface FocusableRefValue<T extends HTMLElement = HTMLElement, D extends HTMLElement = T> 
  extends DOMRefValue<D> {
  focus(): void;
}

type DOMRef<T extends HTMLElement = HTMLElement> = Ref<DOMRefValue<T>>;
type FocusableRef<T extends HTMLElement = HTMLElement> = Ref<FocusableRefValue<T>>;

DOM References

Labelable Components

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

type LabelPosition = "top" | "side";
type Alignment = "start" | "end";
type NecessityIndicator = "icon" | "label";

interface LabelableProps {
  label?: ReactNode;
}

interface SpectrumLabelableProps extends LabelableProps {
  labelPosition?: LabelPosition;
  labelAlign?: Alignment;
  necessityIndicator?: NecessityIndicator;
  isRequired?: boolean;
  contextualHelp?: ReactNode;
}

Labelable Components

Type Definitions

// Router configuration for type-safe URLs
interface RouterConfig {}
type Href = RouterConfig extends {href: infer H} ? H : string;
type RouterOptions = RouterConfig extends {routerOptions: infer O} ? O : never;

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

// Range value for inputs like sliders
interface RangeValue<T> {
  start: T;
  end: T;
}

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

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

// Basic foundational types
type Key = string | number;
type Direction = "ltr" | "rtl";
type Orientation = "horizontal" | "vertical";

// Removable item interface
interface Removable<T, R> {
  isRemovable?: boolean;
  onRemove?: (value: T, event?: SyntheticEvent) => R;
}

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