Authoring Model: props

index

2

status

Draft

Props are the heart of how Workbench examples become interactive. A prop is any named value that can influence the state or appearance of the demo — and optionally be configured, animated, or derived from other values.

Each Workbench defines a single props object that includes all values used by the demo. These may be:

• Configurable props – directly editable by the learner via control panel UI.
• Derived props – calculated based on one or more other props.
• Static props – used internally but not shown in the UI and not calculated from others.

Each prop has a structure like this:

hue: {
  type: "number",
  value: 45,
  unit: "deg",
  min: 0,
  max: 360,
  configurable: true,
  playable: true,
  duration: 2000,
  label: "Hue",
  help: "Adjusts the color hue.",
  showValue: true,
  showUnit: true,
  unitDisplay: "degrees", // optional override
  secondary: false, // optional, default false
  // options: [...] // for string enums
}

Key fields

• value – initial value for the prop. For derived props, this is optional and used as a fallback.
• unit – optional string representing the unit for number values (e.g. “px”, “deg”, “%”). Units never change at runtime.
• type – "number", "string", or "boolean". Determines the default control widget.
• label – optional display label in the control panel (defaults to prop name).
• help – optional description or help text string.
• showValue, showUnit – let you hide the number and/or unit display, for cleaner UI.
• options – optional array of string values (used for string enums).
• secondary – marks the control as secondary (shown in a lower priority panel).
• unitDisplay – overrides how the unit is shown (e.g., “deg” → “°”).

Derived props

A derived prop includes a derive function and an inputs array:

baseColor: {
  derive: ({ hue, saturation }) => hslToHex(hue.value, saturation.value, 0.5),
  inputs: ["hue", "saturation"]
}

Derived props are recalculated automatically when their dependencies change. If an error occurs, Workbench will fall back to a fallback value if provided, or use the value field as a last resort.

Playable props

Only numeric props can be marked as playable — meaning they animate back and forth between min and max.

curvature: {
  type: "number",
  value: 50,
  min: 0,
  max: 100,
  configurable: true,
  playable: true,
  duration: 1500,
}

Playable props animate linearly. Animation direction is tracked per prop and resumes from where it left off. Only one play button appears per Workbench, and interaction with any playable control pauses playback.

Author expectations

• Authors must explicitly mark props as configurable: true for them to appear in the UI.
• Derived props shown in the controls (rare) will be disabled, but still update to reflect the current value.
• Authors can assign meaningful labels, units, and help text to improve learner experience.
• Units for number props are fixed but can be renamed for display (e.g. “deg” → “degrees” or “°”).
• Value/unit display can be suppressed with showValue: false, showUnit: false.