61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# 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-wrap` applies 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-ignore` excludes properties from schema generation
|
|
|
|
## Example Implementation
|
|
|
|
A TypeScript interface can be annotated to define a 3D box geometry with transformation controls:
|
|
|
|
```typescript
|
|
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
|