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:

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

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

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

Step 3: Use the Generated Schema

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:

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

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

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

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

2.7 KiB Raw Blame History