Property Panels
Property panels in @open-pencil/vue are intentionally composable-first.
If a panel mostly needs selection-derived values and update actions, prefer composables. If a panel needs reusable array/list structure, use a headless primitive like PropertyListRoot.
Common control composables
For standard property sections, start with:
usePosition()useLayout()useAppearance()useTypography()useExport()
For list-style panels, use:
useFillControls()useStrokeControls()useEffectsControls()
Binding-aware fields
Compose BindableValueRoot around fields that can reference variables or external design tokens. The primitive is presentation-agnostic, but binding-aware interfaces should keep focus non-destructive:
- Show variable identity while the field is idle; expose the resolved value in supporting UI such as a tooltip.
- Focusing or opening the picker must not detach a binding.
- Apply
detach-on-edit,readonly-when-bound, oredit-variableonly when the user actually changes the value. - Put explicit detach actions in the picker rather than on a destructive one-click field icon.
- Keep binding replacement, detach-on-edit, and multi-target changes in one provider batch.
OpenPencil's app skin uses a violet variable-name pill at rest and reveals the resolved numeric value when NumberField enters editing mode. Custom editor shells can present the same headless state differently.
Example: position panel
vue
<script setup lang="ts">
import { MIXED } from '@open-pencil/vue/controls/node-props'
import { usePosition } from '@open-pencil/vue/controls/position'
const { panelProp, updateProp, commitProp } = usePosition()
const x = panelProp('x')
const y = panelProp('y')
const width = panelProp('width')
const height = panelProp('height')
// A multi-selection whose layers show different values shows an empty field.
const shown = (value: number | typeof MIXED) => (value === MIXED ? '' : value)
// Applied on change, so the rounded value replaces the text only once typing is done.
function set(key: 'x' | 'y' | 'width' | 'height', event: Event) {
const value = Number((event.target as HTMLInputElement).value)
updateProp(key, value)
commitProp(key, value, value)
}
</script>
<template>
<div class="grid grid-cols-2 gap-2">
<input :value="shown(x)" @change="set('x', $event)" />
<input :value="shown(y)" @change="set('y', $event)" />
<input :value="shown(width)" @change="set('width', $event)" />
<input :value="shown(height)" @change="set('height', $event)" />
</div>
</template>Example: fills panel
vue
<script setup lang="ts">
import { PropertyListRoot } from '@open-pencil/vue/primitives/PropertyList'
import { useEditorPropertyList } from '@open-pencil/vue/controls/property-list'
import { useFillControls } from '@open-pencil/vue/controls/fill'
const fillControls = useFillControls()
const fills = useEditorPropertyList('fills')
</script>
<template>
<PropertyListRoot
prop-key="fills"
:items="fills.items.value"
:mixed="fills.isMixed.value"
@add="fills.actions.add"
@remove="fills.actions.remove"
v-slot="{ items, actions }"
>
<div v-for="(fill, index) in items" :key="index">
{{ fill.type }}
<button @click="actions.remove(index)">Remove</button>
</div>
<button @click="actions.add(fillControls.defaultFill)">Add fill</button>
</PropertyListRoot>
</template>Rule of thumb
- use composables for direct control logic
- use structural primitives when repeated list/tree/slot coordination is the hard part