npm package: @raj-rj/spatial-design
Description: A specialized React UI component library tailored for building 3D spatial design tools, editors, and administrative interfaces.
Author: Abhay Aggarwal
Latest version: 3.0.21

# Spatial Design System

A specialized React UI component library tailored for building 3D spatial design tools, editors, and administrative interfaces.

## Features

- **Spatial-First Design**: Components specifically built for coordinate manipulation, scene hierarchies, and 3D property management.
- **Dynamic Theming**: Full support for **Dark Mode** (default) and **Light Mode** using CSS variables.
- **Responsive System**: A unique object-based responsive syntax for styling and props.
- **Optimized for Editors**: Lightweight, tree-shakeable, and highly performant for complex real-time applications.

---

## Getting Started

### Installation

```bash
npm install @spatialos-admin/spatial-design
```

### Basic Setup

Import the global styles in your application's entry point (e.g., `main.tsx` or `App.tsx`):

```tsx
import '@spatialos-admin/spatial-design/styles';
```

### Theming

The library supports theme switching via the `data-theme` attribute on the `<html>` or `<body>` tag.

```tsx
// Toggle Light Mode
document.documentElement.setAttribute('data-theme', 'light');

// Default (Dark Mode)
document.documentElement.setAttribute('data-theme', 'dark');
```

---

## Core UI Components

### Button
Standard button component with support for loading states and icons.
- **Props**:
  - `variant`: `'primary' | 'secondary' | 'link' | 'tertiary'` (Default: `'primary'`)
  - `size`: `'base' | 'medium' | 'large'`
  - `isLoading`: Shows a loading spinner and disables interaction.
  - `isDisabled`: Disables interaction.
  - `isFullWidth`: Expands to fill parent container.
  - `danger`: Applies error styling.
  - `isAnimated`: Enables/disables press animations.

### TextInput
A versatile text input field designed for property editors.
- **Props**:
  - `type`: `'text' | 'number' | 'email' | 'password'`
  - `leadingUnit`: Displays units like `'percentage'`, `'degree'`, or custom strings (e.g., `'ms'`).
  - `isRightAligned`: Aligns text to the right.
  - `retainOldValueOnEmpty`: If true, maintains previous value if input is cleared.
  - `isFullWidth`: Fills container width.
  - `trailingContent`: Adds custom content (like an 'X' button) to the end of the input.

### Switch
A compact toggle control.
- **Props**:
  - `value`: Boolean state.
  - `onChange`: Callback returning the new state.

### Field
A wrapper for form controls to add consistent labels and tooltips.
- **Props**:
  - `title`: Label text.
  - `isTooltipShown`: Shows an info icon with a tooltip.
  - `tooltipValue`: Content of the tooltip.

### Select
A stylized dropdown selector.
- **Props**:
  - `items`: Array of `{ key, label, value, isDisabled }`.
  - `active`: The currently selected value.
  - `selectIcon`: Optional icon to display next to the selected value.
  - `dropdownPlacement`: Where the dropdown opens (Floating UI placements).

### Slider
A property-specific slider with infinite scrubbing support.
- **Props**:
  - `title`: Label for the slider.
  - `isInfinite`: Allows scrubbing beyond min/max bounds.
  - `isTooltipShown`: Shows value tooltip on scrub.
  - `step`: Increment value.
  - `onChangeEnd`: Callback triggered when scrubbing stops.

---

## Spatial & Editor Components

### TransformPanel
A specialized layout for X, Y, Z coordinate inputs (Scale, Position, Rotation).
- **Props**:
  - `title`: Heading for the panel.
  - `isRatioLocked`: Controls the ratio lock icon state.
  - `onLockRatioClick`: Callback when the ratio lock is toggled.

### StateField
A property field specifically for displaying and renaming "states" or "variants".
- **Props**:
  - `title`: Label.
  - `active`: Highlighted state.
  - `onRename`: Callback for inline renaming.

### Slot (GenericField)
A flexible container used to group multiple triggers or inputs into a single row.
- **Props**:
  - `icons`: Array of icons with click handlers.

### EnvironmentPicker
A specialized UI for selecting 3D environments or HDRIs.
- **Props**:
  - `backgroundImage`: Preview image URL.
  - `onClickCallback`: Triggered on selection.

### DirectoryTree
A complex hierarchical tree component used for scene graphs and layer management.
- **Props**:
  - `items`: Hierarchical data structure.
  - `onMove`: Callback for drag-and-drop operations.
  - `onItemRename`: Callback when a node is renamed.
  - `itemCustomizer`: Allows adding extra action icons to tree nodes.

### Triggers
Pre-styled buttons that trigger specific editor sub-panels.
- Available Triggers: `EnvironmentPickerTrigger`, `EffectTrigger`, `MaterialTrigger`, `BehaviourTrigger`, `BlockTrigger`, `OperationTrigger`.

---

## Layout & Responsive Design

This library uses a `Responsive<T>` type for many props, allowing you to define values per breakpoint.

**Breakpoint Keys**: `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`, `xxxl`

### Flex
A responsive Flexbox container.
- **Props**:
  - `vertical`: Switches to `flex-direction: column`.
  - `gap`: `Responsive<number | string>`.
  - `align`, `justify`, `wrap`: Standard flex properties.

### Grid
A responsive Grid container with auto-calculating columns.
- **Props**:
  - `gap`: `Responsive<number | string>`.

### Divider
A simple horizontal or vertical separator.

---

## Data Display & Feedback

### Typography
Consistent text styling for headings and labels.
- `Typography.Title`: Supports `level` (`h1` to `h5`) and `strong`.
- `Typography.Text`: Supports `variant` (`primary`, `secondary`, `danger`), `ellipsis`, and `isEditable` (double-click to edit).

### Card
A container for grouping related content, often used for collapsible sections.
- **Props**:
  - `title`: Header text.
  - `collapsible`: Enables collapse/expand behavior.
  - `collapsed`: Controlled collapse state.

### Link
Styled anchor component for navigation.
- **Props**:
  - `variant`: `'inline' | 'default'`.
  - `href`: Destination URL.

### Avatar
Displays user profile pictures or initials.
- **Props**:
  - `uname`: Full name for initial extraction.
  - `state`: `'default' | 'intermediate'` (dashed border).

### Notification
Context-based alert system.
- **Hook**: `useNotifications()`
- **Methods**: `notifySuccess`, `notifyError`, `notifyInfo`.
- **Options**: Supports custom action buttons (primary/secondary).

---

## Icons

### Standard Icons
A vast library of functional UI icons:
- `ChevronDownIcon`, `PlusIcon`, `CrossIcon`, `SettingsIcon`, `LinkIcon`, `EyeVisibleIcon`, etc.

### Object Icons
Specific icons for 3D objects:
- `ObjectCubeIcon`, `ObjectSphereIcon`, `ObjectCameraIcon`, `ObjectPointIcon`, `ObjectDirectionalIcon`, etc.

### Tabs
Organize content into switchable panes.
- **Components**: `Tabs`, `TabPane`.
- **Props (Tabs)**:
  - `active`: Key of the currently active tab.
  - `onTabChange`: Callback when a tab is clicked.
- **Props (TabPane)**:
  - `tabKey`: Unique identifier for the pane.
  - `heading`: Label shown in the tab bar.

---

## Overlays & Navigation

### Dropdown
A flexible overlay component using Floating UI.
- **Components**: `Dropdown`, `DropdownTrigger`, `DropdownContent`, `DropdownHeader`.
- **Props**:
  - `placement`: Floating UI placement (e.g., `'top-start'`, `'bottom'`).
  - `offsetFromParent`: Pixel distance from the trigger.

### ContextMenu
A right-click menu system.
- **Props**:
  - `items`: Array of menu item configurations.

### Menu
Sidebar or navigation menu structures.
- **Components**: `Menu`, `MenuItem`.
- **Props (MenuItem)**:
  - `title`: Label.
  - `group`: Optional grouping label.
  - `Icon`: Leading icon.

---

## Utility Components

### ColorPicker
A specialized color selection tool.
- **Props**:
  - `value`: Current hex color.
  - `onChangeComplete`: Callback when selection is finalized.

### OTPInput
A multi-segment input for one-time passwords or codes.
- **Props**:
  - `otpLength`: Number of segments.
  - `onChange`: Callback returning the full string.

### ProgressBar
A simple horizontal progress indicator.
- **Props**:
  - `current`: Current value.
  - `total`: Maximum value.

---

## Architecture & Setup for AI Agents

- **Source Code**: Rooted in `src/`. Components are in `src/components/`, each with a dedicated `.tsx` and `.scss` file.
- **Styling**: Uses CSS Modules/Global SCSS. Variables are managed via `src/styles/_variables.scss`.
- **Build Output**: Targeted at `dist/` with ESM format and preserved modules for tree-shaking.
- **Types**: Public interfaces are centralized in `src/types/index.ts`.