API Reference

Complete API documentation for the Dial system TypeScript types and component props. For annotation reference, see Annotations.

TypeScript Types

DialSchema

The main schema type that defines a dial control.

interface DialSchema {
  // Required fields
  name: string;                    // Property name
  dtype?: DialDataType;            // Data type

  // Display options
  label?: string;                  // Display label
  icon?: string;                   // Lucide icon name
  placeholder?: string;            // Input placeholder
  tooltip?: string;                // Hover tooltip

  // Numeric constraints
  min?: number;                    // Minimum value
  max?: number;                    // Maximum value
  step?: number;                   // Step increment
  value?: DialValue;               // Default value

  // Vector constraints (arrays)
  mins?: number[];                 // Min values per element
  maxs?: number[];                 // Max values per element
  steps?: number[];                // Step values per element
  dtypes?: string[];               // Data types per element
  placeholders?: string[];         // Placeholders per element
  tooltips?: string[];             // Tooltips per element

  // Select options
  options?: string[] | Record<string, any>[];

  // Grouping
  grouping?: string;               // Group name
  tags?: Record<string, any>;     // Additional metadata

  // Layout
  colSpan?: number;                // Grid column span
  rowSpan?: number;                // Grid row span
  labelPosition?: LabelPosition;   // Label position

  // Type definition (internal)
  typeDefinition?: ParsedNestedType;
}

DialDataType

Supported data types for dial controls.

type DialDataType =
  | 'boolean'      // Toggle switch
  | 'number'       // Numeric slider
  | 'int'          // Integer slider
  | 'number-int'   // Alternative integer
  | 'string'       // Text input
  | 'color'        // Color picker
  | 'select'       // Dropdown select
  | 'vector'       // Complex vector (any dimension)
  | 'vector3'      // 3D vector (simplified)
  | 'euler'        // Euler angles
  | 'interface'    // Nested interface
  | 'object';      // Nested object

DialValue

Possible values for dial controls.

type DialValue =
  | boolean
  | number
  | string
  | number[]
  | null
  | undefined;

GroupSchema

Configuration for property groups.

interface GroupSchema {
  name: string;                    // Group identifier
  layout?: 'grid' | 'flex';       // Layout type

  // Grid options
  gridCols?: number;                // Grid columns
  gridRows?: number;                // Grid rows
  gridFlow?: 'row' | 'column';    // Grid flow
  gridColTemplate?: string;        // CSS grid-template-columns
  gridRowTemplate?: string;        // CSS grid-template-rows

  // Flex options
  flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
  flexJustifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
}

LabelPosition

Label positioning options.

type LabelPosition =
  | 'left'
  | 'right'
  | 'top'
  | 'bottom'
  | 'center'
  | 'inline';

React Components

DialProvider

Context provider for dial controls.

interface DialProviderProps {
  schemas: DialSchema[];
  onValueChange?: (name: string, value: unknown) => void;
  initialValues?: Record<string, unknown>;
  values?: Record<string, unknown>;
  children: React.ReactNode;
}

const DialProvider: React.FC<DialProviderProps>;

Usage:

// Uncontrolled mode
<DialProvider
  schemas={schemas}
  onValueChange={handleChange}
  initialValues={{ position: [0, 0, 0] }}
>
  <DialPanel schemas={schemas} />
</DialProvider>

// Controlled mode
<DialProvider
  schemas={schemas}
  values={currentValues}
  onValueChange={handleChange}
>
  <DialPanel schemas={schemas} />
</DialProvider>

DialPanel

Renders the control panel UI.

interface DialPanelProps {
  schemas: DialSchema[];
  groups?: GroupSchema[];
  labelLayout?: 'left' | 'top' | 'inline';
}

const DialPanel: React.FC<DialPanelProps>;

Usage:

<DialPanel
  schemas={schemas}
  groups={groups}
  labelLayout="top"
/>

DialControl

Individual control component (used internally by DialPanel).

interface DialControlProps {
  schema: DialSchema;
  value?: DialValue;
  onChange?: (value: DialValue) => void;
  disabled?: boolean;
  className?: string;
  style?: React.CSSProperties;
}

const DialControl: React.FC<DialControlProps>;

DialBadge

Badge component to display Dial version or status.

interface DialBadgeProps {
  variant?: 'default' | 'success' | 'warning' | 'error';
  className?: string;
}

const DialBadge: React.FC<DialBadgeProps>;

Hooks

useDialSchema

Access dial context within provider.

interface DialContextValue {
  values: Record<string, unknown>;
  schemas: DialSchema[];
  getValue: (name: string) => DialValue;
  setValue: (name: string, value: DialValue) => void;
  onValueChange?: (name: string, value: DialValue) => void;
}

function useDialSchema(): DialContextValue;

Usage:

function CustomControl() {
  const { values, setValue, getValue } = useDialSchema();

  return (
    <div>
      <p>Current value: {JSON.stringify(getValue('visible'))}</p>
      <button onClick={() => setValue('visible', !values.visible)}>
        Toggle Visibility
      </button>
    </div>
  );
}

CLI API

Command Line Interface

dial-cli [options] <files...>

Options

interface CLIOptions {
  output?: string;       // -o, --output <dir>
  ignore?: string;       // -i, --ignore <patterns>
  verbose?: boolean;     // --verbose, --debug
  quiet?: boolean;       // --quiet
  remove?: boolean;      // -r, --remove
  version?: boolean;     // -v, --version
  help?: boolean;        // -h, --help
}

Programmatic Usage

import { processFile } from '@vuer-ai/dial-cli/dist/generators/file-processor';
import { writeSchemaFile } from '@vuer-ai/dial-cli/dist/utils/file-manager';

async function generateSchema(filePath: string) {
  const schemas = await processFile(filePath, {
    verbose: false,
    ignorePatterns: ['className', 'style']
  });

  await writeSchemaFile('./metadata', schemas);
}

Events

Value Change Event

type ValueChangeHandler = (
  name: string,
  value: DialValue,
  previousValue?: DialValue
) => void;

Usage:

const handleValueChange: ValueChangeHandler = (name, value, prev) => {
  console.log(`${name} changed from ${prev} to ${value}`);

  // Validate
  if (name === 'opacity' && value > 1) {
    console.error('Invalid opacity');
    return;
  }

  // Update state
  setState(prev => ({ ...prev, [name]: value }));
};

Utility Functions

parseDialTags

Parse dial annotations from JSDoc comments.

function parseDialTags(comment: string): ParsedTagsResult;

interface ParsedTagsResult {
  grouping?: string;
  tags: Record<string, any>;
  groupTags: Record<string, any>;
}

inferDtype

Infer data type from TypeScript type name.

function inferDtype(
  typeName: string,
  typeStructure?: ParsedNestedType
): DialDataType | undefined;

validateSchema

Validate dial schema structure.

function validateSchema(schema: DialSchema): {
  valid: boolean;
  errors: string[];
};

Error Handling

Common Errors

// Schema validation error
class DialSchemaError extends Error {
  constructor(message: string, schema?: DialSchema);
}

// CLI processing error
class DialCLIError extends Error {
  constructor(message: string, file?: string);
}

// Runtime value error
class DialValueError extends Error {
  constructor(message: string, name: string, value: any);
}

Error Recovery

function SafeDialPanel({ schemas, onError }) {
  try {
    return <DialPanel schemas={schemas} />;
  } catch (error) {
    onError(error);
    return <div>Error loading controls</div>;
  }
}

Browser Support

Performance Considerations

Schema Caching

const schemaCache = new Map<string, DialSchema[]>();

async function getCachedSchema(file: string) {
  if (!schemaCache.has(file)) {
    const schema = await generateSchema(file);
    schemaCache.set(file, schema);
  }
  return schemaCache.get(file);
}

Debounced Updates

import { debounce } from 'lodash';

const debouncedUpdate = debounce((name, value) => {
  updateServer(name, value);
}, 300);

const handleChange = (name: string, value: DialValue) => {
  updateLocal(name, value);      // Immediate
  debouncedUpdate(name, value);  // Debounced
};

Next Steps