2.2 KiB
Dial: A Schema-Driven Menu System
Overview
Dial represents a system that generates user interface controls automatically from TypeScript interfaces using JSDoc annotations. This approach eliminates manual UI creation by defining control properties directly in code comments.
Core Annotation Syntax
The system uses JSDoc comments to specify UI behavior:
Grouping Controls:
@dial <grouping>organizes related properties@dial <grouping> @dial-no-wrapapplies group-level settings
Property Configuration:
@dial-<property> <value>sets control attributes using hyphen notation@dial-col-<n>arranges elements in n-column layouts@dial-dtype <type>specifies data types (vector3, euler, boolean, int, etc.)@dial-min <number>and@dial-max <number>establish value bounds@dial-step <number>defines increment sizes@dial-options [...]provides preset values@dial-icon <name>assigns Lucide icon names@dial-label <text>customizes property display names@dial-ignoreexcludes properties from schema generation
Example Implementation
A TypeScript interface can be annotated to define a 3D box geometry with transformation controls:
interface ExampleBoxProps {
args: ExampleBoxArgs;
position: number[] | null;
rotation: number[] | null;
scale: number[] | null;
hide: boolean;
alphaTest: boolean;
depthTest: boolean;
renderOrder: number;
_internalState?: any;
}
Annotations specify constraints, groupings, and visual representation for each property.
Key Features
Schema-Driven Architecture: UI controls generate automatically from annotated TypeScript code, eliminating manual interface creation.
Grouped Layout System: Properties organize automatically into sections based on their grouping annotations.
Integrated State Management: Built-in state tracking with value change callbacks enables seamless application integration.
Next Steps
- Tutorial: Step-by-step guide for using dial-cli
- Input Types: Complete reference of supported input types
- Controlled Dials: Advanced usage patterns
- API Notes: Detailed API reference
- CLI Details: Advanced command-line options