Getting Started with Dial

This guide will help you get started with the Dial system in minutes. Dial automatically generates UI controls from your TypeScript interfaces using JSDoc annotations.

What is Dial?

Dial is a schema-driven menu system that:

• Parses JSDoc annotations in your TypeScript/React components
• Generates UI schemas that describe controls and their properties
• Creates interactive controls automatically from those schemas
• Supports complex types including vectors, tuples, and nested objects

Installation

# Install the CLI tool globally
pnpm install -g @vuer-ai/dial-cli

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

Quick Example

1. Annotate Your Component

Create a TypeScript component with Dial annotations:

// Box.tsx
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;
}

export const Box: React.FC<BoxProps> = ({ size, color, visible, opacity }) => {
  // Component implementation
  return <mesh visible={visible} />;
};

2. Generate the Schema

Run dial-cli to generate the UI schema:

dial-cli Box.tsx

# Output: metadata/schema.dial

3. Use the Generated Schema

The generated schema can be used with the Dial UI components:

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

function App() {
  // Get the Box component schema from the combined schema file
  const boxSchema = allSchemas.find(s => s.component === 'Box');
  
  return (
    <DialProvider schemas={[boxSchema]}>
      <DialPanel schemas={[boxSchema]} />
    </DialProvider>
  );
}

Core Concepts

Annotations

Dial uses JSDoc comments with special @dial tags:

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

Data Types

Common data types supported by Dial:

Grouping

Properties can be grouped for better organization:

interface Props {
  /** @dial transform */
  position: [number, number, number];
  
  /** @dial transform */  
  rotation: [number, number, number];
  
  /** @dial appearance */
  color: string;
  
  /** @dial appearance */
  metalness: number;
}

Next Steps

• Learn about Advanced Annotations for complex types
• Explore Type Inheritance for reusable interfaces
• See Complete Examples of real-world components
• Read the CLI Reference for all available options

Need Help?

• Check the Troubleshooting Guide
• View Testing Documentation for validation
• See API Notes for programmatic usage