@raj-rj/spatial-design

v3.0.21

Published

16 days ago

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

0High
0Medium
0Low

raj-rj

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

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):

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

Theming

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

// 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.

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.