130 lines
2.7 KiB
Markdown
130 lines
2.7 KiB
Markdown
# 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;
|
|
}
|
|
```
|