198 lines
3.9 KiB
Markdown
198 lines
3.9 KiB
Markdown
1. [Home](/)
|
|
1. [Dial](/dial)
|
|
1. Api Notes
|
|
|
|
# API Design and Building Blocks
|
|
|
|
|
|
## DialPanel Component
|
|
|
|
|
|
The `DialPanel` component renders dial controls based on schemas. It accepts the following props:
|
|
|
|
|
|
### Props
|
|
|
|
|
|
| Prop | Type | Default | Description |
|
|
| `schemas` | `DialSchema[]` | Required | Array of dial schemas to render |
|
|
| `groups` | `DialGroupConfig[]` | `undefined` | Optional group configurations |
|
|
| `labelLayout` | `LabelPositionT` | `undefined` | Default label position layout for all inputs ("top", "left", "right", "inline", etc.) |
|
|
|
|
|
|
|
|
### Label Position Priority
|
|
|
|
|
|
The label position for inputs is determined by the following priority order:
|
|
|
|
|
|
|
|
1. **Component-specific**: Label position tags on individual properties (highest priority)
|
|
|
|
- `@dial-label-top`, `@dial-label-left`, `@dial-label-right`, `@dial-label-inline`
|
|
|
|
|
|
|
|
|
|
|
|
1. **Panel labelLayout**: `labelLayout` prop on DialPanel
|
|
|
|
1. **Component default**: Individual input component's default behavior (lowest priority)
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
|
|
```tsx
|
|
import { DialPanel, DialProvider } from '@vuer-ai/vuer-uikit';
|
|
|
|
// With default label layout for all inputs
|
|
<DialProvider schemas={schemas}>
|
|
<DialPanel
|
|
schemas={schemas}
|
|
labelLayout="top" // All inputs will have top-aligned labels by default
|
|
/>
|
|
</DialProvider>
|
|
|
|
// Without specifying (components use their own defaults)
|
|
<DialProvider schemas={schemas}>
|
|
<DialPanel schemas={schemas} />
|
|
</DialProvider>
|
|
|
|
```
|
|
|
|
|
|
Individual components can still override the panel's default label layout:
|
|
|
|
|
|
```tsx
|
|
interface Props {
|
|
/**
|
|
* @dial-label-left // This overrides the panel's labelLayout
|
|
*/
|
|
specialField: number;
|
|
}
|
|
|
|
```
|
|
|
|
|
|
## Building Blocks
|
|
|
|
|
|
We want to specify the property menu without duplicating the code. Here are the basic building blocks:
|
|
|
|
|
|
| Control Entry | Control Group |
|
|
| ```jsx
|
|
const controlEntry = {
|
|
dtype: 'number',
|
|
value: 10,
|
|
min: 0,
|
|
max: 100,
|
|
step: 1,
|
|
}
|
|
|
|
```
|
|
|
|
| ```jsx
|
|
const controlGroup = {
|
|
tag: 'group',
|
|
children: [
|
|
controlEntry,
|
|
],
|
|
layout: 'row',
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
Now, let's convert this into a react schema that we can create using react.createElement:
|
|
|
|
|
|
```jsx
|
|
<Dial.Provider>
|
|
<Dial.Row>
|
|
<DialInput label="Position" column type="number" key="prop-name" value={10} min={0} max={100} step={1}/>
|
|
<DialInput label="Rotation" column type="number" key="prop-name" value={10} min={0} max={100} step={1}/>
|
|
<DialInput label="Scale" column type="number" key="prop-name" value={10} min={0} max={100} step={1}/>
|
|
</Dial.Row>
|
|
</Dial.Provider>
|
|
|
|
```
|
|
|
|
|
|
this can be written via react createElement below:
|
|
|
|
|
|
```jsx
|
|
React.createElement(
|
|
Dial.Provider,
|
|
null,
|
|
React.createElement(
|
|
Dial.Row,
|
|
null,
|
|
React.createElement(DialInput, {
|
|
label: "Position",
|
|
column: true,
|
|
type: "number",
|
|
key: "prop-name",
|
|
value: 10,
|
|
min: 0,
|
|
max: 100,
|
|
step: 1
|
|
}),
|
|
React.createElement(DialInput, {
|
|
label: "Rotation",
|
|
column: true,
|
|
type: "number",
|
|
key: "prop-name",
|
|
value: 10,
|
|
min: 0,
|
|
max: 100,
|
|
step: 1
|
|
}),
|
|
React.createElement(DialInput, {
|
|
label: "Scale",
|
|
column: true,
|
|
type: "number",
|
|
key: "prop-name",
|
|
value: 10,
|
|
min: 0,
|
|
max: 100,
|
|
step: 1
|
|
})
|
|
)
|
|
)
|
|
|
|
```
|
|
|
|
|
|
We can do this via a nested json object using a convenient helper function:
|
|
|
|
|
|
```jsx
|
|
function build({tag, children, ...props}) {
|
|
return React.createElement(tag, props, children)
|
|
}
|
|
|
|
```
|
|
|
|
|
|
We can then rewrite the schema as:
|
|
|
|
|
|
```jsx
|
|
{ name: 'position', dtype: 'vector3', value: [0, 0, 0], min: 0, max: 100, options: [10, 20, 30, 40, 50],
|
|
tags: { grouping: 'transform', col: true } }
|
|
{ name: 'rotation', dtype: 'euler', value: [0, 0, 0], min: 0, max: 100, options: [10, 20, 30, 40, 50],
|
|
tags: { grouping: 'transform', col: true } }
|
|
{ name: 'scale', dtype: 'vector3', value: [1, 1, 1], min: 0, max: 100, options: [10, 20, 30, 40, 50],
|
|
tags: { grouping: 'transform', col: true } }
|
|
|
|
```
|