375 lines
7.0 KiB
Markdown
375 lines
7.0 KiB
Markdown
1. [Home](/)
|
|
1. [Dial](/dial)
|
|
1. Tutorial
|
|
|
|
# Dial Tutorial: Using dial-cli
|
|
|
|
|
|
|
|
Dial CLI Tutorialdial-cli[v0.0.22](https://www.npmjs.com/package/@vuer-ai/dial-cli/v/0.0.22)
|
|
This tutorial will guide you through using the dial-cli tool to generate UI controls from TypeScript interfaces with Dial annotations.
|
|
|
|
|
|
## Using the dial-cli Tool
|
|
|
|
|
|
The `dial-cli` is now available as a standalone package for generating Dial schemas from TypeScript files, providing a cleaner installation experience without UI dependencies.
|
|
|
|
|
|
### Installation
|
|
|
|
|
|
```bash
|
|
# Install globally (recommended for CLI tools)
|
|
npm install -g @vuer-ai/dial-cli
|
|
# or
|
|
pnpm install -g @vuer-ai/dial-cli
|
|
|
|
# Check CLI is available
|
|
dial-cli --help
|
|
|
|
```
|
|
|
|
|
|
### Basic Usage
|
|
|
|
|
|
```bash
|
|
# Generate schemas from a TypeScript file
|
|
dial-cli <input-file> [input-file2...]
|
|
|
|
# Examples:
|
|
dial-cli ./src/components/Box.tsx
|
|
# Creates schema.dial in ./metadata directory
|
|
|
|
dial-cli ./src/components/Box.tsx -o ./schemas
|
|
# Outputs to specified directory
|
|
|
|
# Process multiple files
|
|
dial-cli Component1.tsx Component2.tsx
|
|
|
|
# Specify output directory
|
|
dial-cli -o ./metadata MyComponent.tsx
|
|
|
|
```
|
|
|
|
|
|
### What the CLI Does
|
|
|
|
|
|
The dial-cli tool will:
|
|
|
|
|
|
|
|
1. Parse your TypeScript file using the TypeScript compiler API
|
|
|
|
1. Extract all interfaces and types with Dial annotations
|
|
|
|
1. Process JSDoc comments following the `@dial` convention
|
|
|
|
1. Generate JSON schema files that can be directly used with DialPanel
|
|
|
|
|
|
|
|
### Output Files
|
|
|
|
|
|
The CLI generates files with a clean directory structure:
|
|
|
|
|
|
**Main Output:**
|
|
|
|
|
|
|
|
- `schema.dial` - Combined schemas for all components, ready for UI generation
|
|
|
|
|
|
|
|
**Debug Output (verbose mode only):**
|
|
|
|
|
|
|
|
- `debug/component-raw.json` - Raw output from react-docgen-typescript
|
|
|
|
- `debug/component-combined.json` - Enhanced metadata with dial schema information
|
|
|
|
- `debug/component-schemas.json` - Individual component schemas for debugging
|
|
|
|
|
|
|
|
### Local Script
|
|
|
|
|
|
This documentation includes a convenience script for generating metadata:
|
|
|
|
|
|
```bash
|
|
# From the dial directory
|
|
./generate-dial-metadata.sh
|
|
|
|
```
|
|
|
|
|
|
This will process the `BoxExample.tsx` file and output metadata to the `metadata/` directory.
|
|
|
|
|
|
## Using Generated Schemas
|
|
|
|
|
|
Once you've generated schemas using dial-cli, you can use them in your application.
|
|
The Dial system consists of three main components:
|
|
|
|
|
|
|
|
1. **DialProvider** - Manages state for all controls
|
|
|
|
1. **DialPanel** - Converts schemas to UI components
|
|
|
|
1. **Input Components** - Individual control types (number, vector, boolean, etc.)
|
|
|
|
|
|
|
|
### Component API
|
|
|
|
|
|
**DialPanel** accepts the following props:
|
|
|
|
|
|
```tsx
|
|
interface DialPanelProps {
|
|
schemas: DialSchema[]; // Array of control schemas
|
|
groups?: DialGroupConfig[]; // Optional group configurations
|
|
}
|
|
|
|
```
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
```tsx
|
|
// Basic usage with just schemas
|
|
<DialPanel schemas={schemas} />
|
|
|
|
// With group configuration for layout control
|
|
<DialPanel schemas={schemas} groups={groups} />
|
|
|
|
```
|
|
|
|
|
|
### TypeScript Interfaces
|
|
|
|
|
|
The Dial system uses the following main interfaces:
|
|
|
|
|
|
```tsx
|
|
// Schema for individual controls
|
|
interface DialSchema {
|
|
name: string;
|
|
dtype: string;
|
|
value?: DialValue;
|
|
min?: number;
|
|
max?: number;
|
|
step?: number;
|
|
options?: Array<string | number | { label: string; value: string | number }>;
|
|
// ... other properties
|
|
tags?: {
|
|
grouping?: string;
|
|
col?: boolean | number;
|
|
row?: number;
|
|
layout?: string;
|
|
labelPosition?: LabelPositionT;
|
|
noWrap?: boolean;
|
|
};
|
|
}
|
|
|
|
// Group configuration for styling and layout
|
|
interface DialGroupConfig {
|
|
name: string;
|
|
noWrap?: boolean;
|
|
[key: string]: unknown;
|
|
}
|
|
|
|
// Complete schema with groups (output from dial-cli)
|
|
interface DialSchemaGroup {
|
|
component: string;
|
|
schema: DialSchema[];
|
|
groups?: DialGroupConfig[];
|
|
}
|
|
|
|
// Valid value types
|
|
type DialValue = string | number | boolean | number[] | string[] | null | undefined;
|
|
|
|
```
|
|
|
|
|
|
```tsx
|
|
import { DialProvider, DialPanel } from './dial';
|
|
|
|
const schemas = [
|
|
{
|
|
name: 'position',
|
|
dtype: 'vector3',
|
|
value: [0, 0, 0],
|
|
min: -10,
|
|
max: 10,
|
|
tags: { grouping: 'transform', col: true }
|
|
},
|
|
// ... more schemas
|
|
];
|
|
|
|
function MyComponent() {
|
|
const handleValueChange = (name, value) => {
|
|
console.log(`${name} changed to`, value);
|
|
};
|
|
|
|
return (
|
|
<DialProvider
|
|
schemas={schemas}
|
|
onValueChange={handleValueChange}
|
|
>
|
|
<DialPanel schemas={schemas} />
|
|
</DialProvider>
|
|
);
|
|
}
|
|
|
|
```
|
|
|
|
|
|
### Complete Example with dial-cli
|
|
|
|
|
|
|
|
1. **Create a TypeScript file with Dial annotations:**
|
|
|
|
|
|
|
|
```tsx
|
|
// Box.tsx
|
|
interface BoxProps {
|
|
/**
|
|
* Transform properties displayed on single line
|
|
* @dial transform @dial-no-wrap
|
|
*/
|
|
|
|
/** @dial transform @dial-dtype vector3 */
|
|
position: [number, number, number];
|
|
|
|
/** @dial transform @dial-dtype euler */
|
|
rotation: [number, number, number];
|
|
|
|
/**
|
|
* Box dimensions
|
|
* @dial geometry
|
|
* @dial-dtype vector3
|
|
* @dial-min 0.1
|
|
* @dial-max 10
|
|
* @dial-step 0.1
|
|
*/
|
|
size: [number, number, number];
|
|
|
|
/**
|
|
* Box color
|
|
* @dial appearance
|
|
* @dial-dtype color
|
|
*/
|
|
color: string;
|
|
}
|
|
|
|
export const Box: React.FC<BoxProps> = ({ size, position, rotation, color }) => {
|
|
// Component implementation
|
|
};
|
|
|
|
```
|
|
|
|
|
|
|
|
1. **Generate the schema:**
|
|
|
|
|
|
|
|
```bash
|
|
dial-cli Box.tsx -o ./schemas
|
|
# Creates schemas/schema.dial with groups configuration
|
|
|
|
```
|
|
|
|
|
|
The generated schema includes group-level settings:
|
|
|
|
|
|
```json
|
|
{
|
|
"component": "Box",
|
|
"schema": [
|
|
{ "name": "position", "dtype": "vector3", "tags": { "grouping": "transform", "noWrap": true } },
|
|
{ "name": "rotation", "dtype": "euler", "tags": { "grouping": "transform", "noWrap": true } },
|
|
{ "name": "size", "dtype": "vector3", "tags": { "grouping": "geometry" } },
|
|
{ "name": "color", "dtype": "color", "tags": { "grouping": "appearance" } }
|
|
],
|
|
"groups": [
|
|
{ "name": "transform", "noWrap": true }
|
|
]
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
1. **Use the generated schema in your app:**
|
|
|
|
|
|
|
|
```tsx
|
|
import { DialProvider, DialPanel, DialSchemaGroup, DialValue } from '@vuer-ai/vuer-uikit';
|
|
import allSchemas from './schemas/schema.dial';
|
|
|
|
// Get the Box component schema from the combined schema file
|
|
const boxSchema = allSchemas.find(s => s.component === 'Box');
|
|
|
|
function App() {
|
|
const [boxProps, setBoxProps] = useState({
|
|
position: [0, 0, 0],
|
|
rotation: [0, 0, 0],
|
|
size: [1, 1, 1],
|
|
color: '#ff0000'
|
|
});
|
|
|
|
const handleValueChange = (name: string, value: DialValue) => {
|
|
setBoxProps(prev => ({ ...prev, [name]: value }));
|
|
};
|
|
|
|
return (
|
|
<DialProvider
|
|
schemas={[boxSchema]}
|
|
onValueChange={handleValueChange}
|
|
>
|
|
<div style={{ display: 'flex' }}>
|
|
{/* Your 3D scene */}
|
|
<Box {...boxProps} />
|
|
|
|
{/* Auto-generated controls with group configuration */}
|
|
<DialPanel schemas={[boxSchema]} />
|
|
</div>
|
|
</DialProvider>
|
|
);
|
|
}
|
|
|
|
```
|
|
|
|
|
|
## Next Steps
|
|
|
|
|
|
|
|
- Learn more about [Dial Annotation Syntax](/dial/overview) in the overview
|
|
|
|
- Explore all [Input Types](/dial/input-types) available in Dial
|
|
|
|
- See [Controlled Dials](/dial/controlled-dials) for advanced usage
|
|
|
|
- Check out the [API Notes](/dial/api-notes) for detailed reference
|
|
|
|
- Read the [CLI Details](/dial/cli-details) for advanced CLI options
|