npm package: @object-ui/designer
Description: The Tool. A drag-and-drop visual editor to generate Object UI schemas.
Latest version: 0.3.0

# @object-ui/designer

A professional drag-and-drop visual editor to generate Object UI schemas with advanced features including **component resizing** and **specialized designer modes**.

## 🎯 Specialized Designer Modes

The designer now supports three specialized modes optimized for different use cases:

- **Form Designer** (`mode="form"`): Optimized for building forms with field validation and layouts
- **Layout Designer** (`mode="layout"`): Optimized for designing page structures and layouts
- **General Designer** (`mode="general"` or default): Full-featured designer with all components

See [SPECIALIZED_DESIGNERS.md](./SPECIALIZED_DESIGNERS.md) for detailed information about each mode.

### Quick Mode Comparison

| Mode | Best For | Component Count | Complexity |
|------|----------|----------------|------------|
| Form | Contact forms, data entry | ~15 | Low |
| Layout | Page structures, dashboards | ~15 | Medium |
| General | Everything | 30+ | High |

## Features

### Core Functionality
- **Visual Schema Editor**: Edit Object UI schemas visually with a live preview
- **Drag-and-Drop**: Drag components from the palette to the canvas and reorder them within the canvas
- **Component Resizing**: 🆕 Resize container components with 8-directional handles (width, height, or both)
- **Smart Insertion**: Intelligent drop position detection for precise component placement
- **Component Search**: Quickly find components with the built-in search functionality
- **JSON Import/Export**: Import and export schemas as JSON files or clipboard
- **Undo/Redo**: Full history management with keyboard shortcuts (works with resize!)
- **Copy/Cut/Paste**: 🆕 Duplicate and move components easily with Ctrl+C/X/V
- **Duplicate**: 🆕 Quickly duplicate components with Ctrl+D
- **Component Tree**: 🆕 Hierarchical tree view with expand/collapse all functionality
- **Move Up/Down**: 🆕 Reorder components within their parent container

### Visual Design
- **Premium Gradient Effects**: 🆕 Smooth gradient borders and backgrounds for enhanced visual feedback
- **Enhanced Selection**: Clear visual feedback with animated component type labels
- **Animated Drop Zones**: 🆕 Pulsing gradient borders guide drag operations
- **Hover Indicators**: Helpful indicators with smooth scale animations
- **Resizable Badges**: 🆕 Visual indicators show which components can be resized
- **Empty State Guidance**: Helpful instructions when starting a new design
- **Responsive Preview**: Switch between Desktop (1024px), Tablet (768px), and Mobile (375px) views
- **Enhanced Zoom Controls**: 🆕 Premium controls with gradient hover effects

### User Experience
- **Keyboard Shortcuts**: 
  - `Ctrl+Z` / `Cmd+Z`: Undo (including resize operations)
  - `Ctrl+Y` / `Cmd+Y` / `Cmd+Shift+Z`: Redo (including resize operations)
  - `Ctrl+C` / `Cmd+C`: Copy component
  - `Ctrl+X` / `Cmd+X`: Cut component 🆕
  - `Ctrl+V` / `Cmd+V`: Paste component
  - `Ctrl+D` / `Cmd+D`: Duplicate component 🆕
  - `Ctrl+↑` / `Cmd+↑`: Move component up in tree 🆕
  - `Ctrl+↓` / `Cmd+↓`: Move component down in tree 🆕
  - `Delete` / `Backspace`: Delete component
  - `Click`: Select component (shows resize handles if resizable)
- **Keyboard Shortcuts Help**: 🆕 Click the keyboard icon in toolbar to view all shortcuts
- **Context Menu**: 🆕 Right-click components for quick actions (Copy, Cut, Paste, Duplicate, Move Up/Down, Delete)
- **Resize Handles**: 🆕 8-directional handles appear on selected container components
- **Visual Constraints**: 🆕 Min/max width and height constraints prevent invalid sizing
- **Tooltips**: Contextual help throughout the interface
- **Property Editor**: Configure component properties with a dynamic form
- **Categorized Components**: Organized by Layout, Form, Data Display, Feedback, Overlay, and Navigation

## Resizable Components

The following layout components support resizing:
- **Card**: Container with title/description
- **Container**: Responsive wrapper with max-width
- **Grid**: Grid layout component

See [DRAG_AND_RESIZE_GUIDE.md](./DRAG_AND_RESIZE_GUIDE.md) for detailed documentation on drag-and-drop and resize functionality.

## Installation

```bash
npm install @object-ui/designer @object-ui/react @object-ui/components
# or
yarn add @object-ui/designer @object-ui/react @object-ui/components
# or
pnpm add @object-ui/designer @object-ui/react @object-ui/components
```

## Usage

### Basic Example (General Designer)

```tsx
import { Designer } from '@object-ui/designer';
import { useState } from 'react';
import type { SchemaNode } from '@object-ui/core';

function App() {
  const [schema, setSchema] = useState<SchemaNode>({
    type: 'div',
    className: 'p-8',
    body: []
  });
  
  return (
    <Designer 
      initialSchema={schema} 
      onSchemaChange={setSchema}
    />
  );
}
```

### Using Specialized Designer Modes

```tsx
import { Designer } from '@object-ui/designer';

// Form Designer - for building forms
function FormBuilderApp() {
  return <Designer mode="form" />;
}

// Layout Designer - for page layouts
function LayoutBuilderApp() {
  return <Designer mode="layout" />;
}

// General Designer - for everything (default)
function GeneralBuilderApp() {
  return <Designer mode="general" />;
}
```

Or use dedicated components:

```tsx
import { FormDesigner, LayoutDesigner, GeneralDesigner } from '@object-ui/designer';

function App() {
  return <FormDesigner />;  // or <LayoutDesigner /> or <GeneralDesigner />
}
```

### With Initial Schema

```tsx
const initialSchema: SchemaNode = {
  type: 'div',
  className: 'p-8 max-w-4xl mx-auto',
  body: [
    {
      type: 'card',
      title: 'Welcome',
      body: [
        {
          type: 'text',
          content: 'This is a starter template'
        }
      ]
    }
  ]
};

function App() {
  return <Designer initialSchema={initialSchema} />;
}
```

### Custom Layout

You can use individual designer components to create a custom layout:

```tsx
import { 
  DesignerProvider, 
  Canvas, 
  ComponentPalette, 
  PropertyPanel,
  Toolbar 
} from '@object-ui/designer';

function CustomDesigner() {
  return (
    <DesignerProvider>
      <div className="flex flex-col h-screen">
        <Toolbar />
        <div className="flex-1 flex">
          <ComponentPalette className="w-64" />
          <Canvas className="flex-1" />
          <PropertyPanel className="w-80" />
        </div>
      </div>
    </DesignerProvider>
  );
}
```

## Keyboard Shortcuts

The designer supports the following keyboard shortcuts for efficient workflow:

| Shortcut | Action | Description |
|----------|--------|-------------|
| `Ctrl+Z` / `Cmd+Z` | Undo | Undo the last change |
| `Ctrl+Y` / `Cmd+Y` | Redo | Redo the last undone change |
| `Cmd+Shift+Z` | Redo (Mac) | Alternative redo on macOS |
| `Ctrl+C` / `Cmd+C` | Copy | Copy the selected component |
| `Ctrl+X` / `Cmd+X` | Cut | Cut the selected component 🆕 |
| `Ctrl+V` / `Cmd+V` | Paste | Paste the copied component |
| `Ctrl+D` / `Cmd+D` | Duplicate | Duplicate the selected component 🆕 |
| `Ctrl+↑` / `Cmd+↑` | Move Up | Move component up in parent container 🆕 |
| `Ctrl+↓` / `Cmd+↓` | Move Down | Move component down in parent container 🆕 |
| `Delete` / `Backspace` | Delete | Delete the selected component |

**Note**: Copy, cut, paste, duplicate, and delete shortcuts only work when not editing text in input fields.

**Tip**: Click the keyboard icon (⌨️) in the toolbar to view the interactive keyboard shortcuts reference anytime!

## Components

### `<Designer />`

The main designer component that includes all panels and functionality.

**Props:**
- `initialSchema?: SchemaNode` - Initial schema to load
- `onSchemaChange?: (schema: SchemaNode) => void` - Callback when schema changes

### `<DesignerProvider />`

Context provider for designer state.

**Props:**
- `initialSchema?: SchemaNode` - Initial schema
- `onSchemaChange?: (schema: SchemaNode) => void` - Change callback
- `children: ReactNode` - Child components

### `<Canvas />`

The visual editor canvas that renders the schema.

**Props:**
- `className?: string` - Additional CSS classes

### `<ComponentPalette />`

Sidebar showing available components to add.

**Props:**
- `className?: string` - Additional CSS classes

### `<PropertyPanel />`

Right sidebar for editing selected component properties.

**Props:**
- `className?: string` - Additional CSS classes

### `<Toolbar />`

Top toolbar with import/export and other actions.

**Props:**
- `className?: string` - Additional CSS classes

## Hooks

### `useDesigner()`

Access the designer context in custom components.

```tsx
import { useDesigner } from '@object-ui/designer';

function CustomComponent() {
  const { 
    schema, 
    setSchema,
    selectedNodeId,
    setSelectedNodeId,
    updateNode,
    addNode,
    deleteNode
  } = useDesigner();
  
  // Use designer state and methods
}
```

## API

### Context API

```typescript
interface DesignerContextValue {
  schema: SchemaNode;
  setSchema: (schema: SchemaNode) => void;
  selectedNodeId: string | null;
  setSelectedNodeId: (id: string | null) => void;
  hoveredNodeId: string | null;
  setHoveredNodeId: (id: string | null) => void;
  updateNode: (id: string, updates: Partial<SchemaNode>) => void;
  addNode: (parentId: string | null, node: SchemaNode, index?: number) => void;
  deleteNode: (id: string) => void;
  moveNode: (nodeId: string, targetParentId: string | null, targetIndex: number) => void;
}
```

## Styling

The designer uses Tailwind CSS. Make sure to include the designer components in your Tailwind configuration:

```javascript
// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@object-ui/designer/**/*.{js,ts,jsx,tsx}',
    './node_modules/@object-ui/components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}
```

## Features Roadmap

### Completed ✅
- [x] Drag and drop components from palette
- [x] Drag to reorder components in canvas
- [x] Smart insertion based on drop position
- [x] **Component resizing with 8-directional handles** 🆕
- [x] **Premium gradient visual effects** 🆕
- [x] **Animated selection and hover states** 🆕
- [x] **Resizable component indicators** 🆕
- [x] Undo/redo functionality with history (works with resize)
- [x] Copy/paste components
- [x] **Cut functionality (Ctrl+X/Cmd+X)** 🆕
- [x] **Duplicate functionality (Ctrl+D/Cmd+D)** 🆕
- [x] **Component tree with expand/collapse all** 🆕
- [x] **Context menu with move up/down** 🆕
- [x] **Keyboard navigation (Ctrl+↑/↓ for reordering)** 🆕
- [x] **Keyboard shortcuts help dialog** 🆕
- [x] Keyboard shortcuts (Ctrl+Z/Y, Ctrl+C/X/V/D, Delete)
- [x] Component search in palette
- [x] JSON import/export with file and clipboard support
- [x] Responsive viewport modes (Desktop/Tablet/Mobile)
- [x] Enhanced visual feedback and tooltips
- [x] Zoom controls for canvas with gradient effects

### Planned 🚀
- [ ] Snap-to-grid for precise positioning and resizing
- [ ] Aspect ratio locking (Shift+Drag during resize)
- [ ] Keyboard resize controls (Shift+Arrow keys)
- [ ] Resize preview overlay showing dimensions
- [ ] Schema validation with error indicators
- [ ] Component visibility toggle (hide/show components)
- [ ] Copy/duplicate entire schema branches
- [ ] Multi-select components with Shift+Click
- [ ] Component grouping and ungrouping
- [ ] Custom component templates library
- [ ] Export to React/TypeScript code
- [ ] Collaborative editing features
- [ ] Version history and restore points
- [ ] Accessibility checker

## Examples

See the [examples/designer-demo](../../examples/designer-demo) directory for a complete working example.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT