Initial commit

2025-11-30 09:05:04 +08:00
commit 7afdd6601b
69 changed files with 9552 additions and 0 deletions
--- a/docs/dial/getting-started.md
+++ b/docs/dial/getting-started.md
@@ -0,0 +1,129 @@
+# Getting Started with Dial
+
+## Overview
+
+Dial is a schema-driven system that "parses JSDoc annotations in your TypeScript/React components" and then "generates UI schemas that describe controls and their properties."
+
+The system automates interactive control creation from TypeScript interfaces, supporting complex types like vectors, tuples, and nested objects.
+
+## Installation
+
+Install the CLI tool using your package manager:
+
+```bash
+# Global installation
+pnpm install -g @vuer-ai/dial-cli
+
+# Or as a dev dependency
+pnpm add -D @vuer-ai/dial-cli
+```
+
+## Basic Workflow
+
+### Step 1: Annotate Your Component
+
+Add JSDoc comments with `@dial` tags to your TypeScript component properties:
+
+```typescript
+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;
+}
+```
+
+### Step 2: Generate the Schema
+
+```bash
+dial-cli Box.tsx
+# Outputs: metadata/schema.dial
+```
+
+### Step 3: Use the Generated Schema
+
+```typescript
+import { DialProvider, DialPanel } from '@vuer-ai/vuer-uikit';
+import allSchemas from './metadata/schema.dial';
+
+function App() {
+  const boxSchema = allSchemas.find(s => s.component === 'Box');
+
+  return (
+    <DialProvider schemas={[boxSchema]}>
+      <DialPanel schemas={[boxSchema]} />
+    </DialProvider>
+  );
+}
+```
+
+## Core Annotation Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `@dial <group>` | Groups related properties together |
+| `@dial-dtype <type>` | Specifies control data type |
+| `@dial-min/max/step` | Sets numeric constraints |
+| `@dial-icon <name>` | Adds Lucide icon to control |
+| `@dial-ignore` | Excludes property from schema |
+
+## Supported Data Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `number` | Basic numeric input | `42` |
+| `boolean` | Toggle switch | `true/false` |
+| `string` | Text input | `"hello"` |
+| `color` | Color picker | `"#ff0000"` |
+| `vector3` | 3D vector | `[1, 2, 3]` |
+| `euler` | Rotation angles | `[0, 90, 180]` |
+| `select` | Dropdown menu | `"option1"` |
+
+## Property Grouping
+
+Organize properties by adding the same group name across multiple fields:
+
+```typescript
+interface Props {
+  /** @dial transform */
+  position: [number, number, number];
+
+  /** @dial transform */
+  rotation: [number, number, number];
+
+  /** @dial appearance */
+  color: string;
+
+  /** @dial appearance */
+  metalness: number;
+}
+```