# Getting Started with Dial

## Overview

Dial is a schema-driven system that "parses JSDoc annotations in your TypeScript/React components" and then "generates UI schemas that describe controls and their properties."

The system automates interactive control creation from TypeScript interfaces, supporting complex types like vectors, tuples, and nested objects.

## Installation

Install the CLI tool using your package manager:

```bash
# Global installation
pnpm install -g @vuer-ai/dial-cli

# Or as a dev dependency
pnpm add -D @vuer-ai/dial-cli
```

## Basic Workflow

### Step 1: Annotate Your Component

Add JSDoc comments with `@dial` tags to your TypeScript component properties:

```typescript
interface BoxProps {
  /**
   * Box dimensions
   * @dial geometry
   * @dial-dtype vector3
   * @dial-min 0.1
   * @dial-max 10
   * @dial-step 0.1
   */
  size: [number, number, number];

  /**
   * Material color
   * @dial appearance
   * @dial-dtype color
   */
  color: string;

  /**
   * Visibility toggle
   * @dial visibility
   * @dial-dtype boolean
   */
  visible: boolean;

  /**
   * Opacity level
   * @dial appearance
   * @dial-dtype number
   * @dial-min 0
   * @dial-max 1
   * @dial-step 0.01
   */
  opacity: number;
}
```

### Step 2: Generate the Schema

```bash
dial-cli Box.tsx
# Outputs: metadata/schema.dial
```

### Step 3: Use the Generated Schema

```typescript
import { DialProvider, DialPanel } from '@vuer-ai/vuer-uikit';
import allSchemas from './metadata/schema.dial';

function App() {
  const boxSchema = allSchemas.find(s => s.component === 'Box');

  return (
    <DialProvider schemas={[boxSchema]}>
      <DialPanel schemas={[boxSchema]} />
    </DialProvider>
  );
}
```

## Core Annotation Tags

| Tag | Purpose |
|-----|---------|
| `@dial <group>` | Groups related properties together |
| `@dial-dtype <type>` | Specifies control data type |
| `@dial-min/max/step` | Sets numeric constraints |
| `@dial-icon <name>` | Adds Lucide icon to control |
| `@dial-ignore` | Excludes property from schema |

## Supported Data Types

| Type | Purpose | Example |
|------|---------|---------|
| `number` | Basic numeric input | `42` |
| `boolean` | Toggle switch | `true/false` |
| `string` | Text input | `"hello"` |
| `color` | Color picker | `"#ff0000"` |
| `vector3` | 3D vector | `[1, 2, 3]` |
| `euler` | Rotation angles | `[0, 90, 180]` |
| `select` | Dropdown menu | `"option1"` |

## Property Grouping

Organize properties by adding the same group name across multiple fields:

```typescript
interface Props {
  /** @dial transform */
  position: [number, number, number];

  /** @dial transform */
  rotation: [number, number, number];

  /** @dial appearance */
  color: string;

  /** @dial appearance */
  metalness: number;
}
```