@things-factory/figure-ui 10.1.162 → 10.1.164

package/client/modeller/data-interface.ts

@@ -1,127 +1,382 @@
 /*
- * The figure's public data properties and what each moves (ADR-0051 §2.2): what the data tab offers and shows. Every
- * rule is figure-model's -- which transform a property may take, whether a connection holds, what a sample moves; this
- * only lists what there is to choose and drafts a first connection the kernel then checks. Kept apart from the element so
- * it is tested without a browser.
+ * The figure's data and what it moves (ADR-0051 §8, data binding design appendix A): what the data tab offers and
+ * shows. Every rule is figure-model's -- which accessor holds, which rule's results a behavior takes -- and the reading
+ * of data is things-scene's; this only lists what there is to choose, drafts a binding the kernel then checks, and edits
+ * the schema as a tree. Kept apart from the element so it is tested without a browser.
  */
-import { compileFigureDataInterface, evaluateFigureDataInterface, validateFigureDataValues, FIGURE_PART_ID } from '@hatiolab/figure-model'
-import type { FigureAsset, FigureDataConnection, FigureDataProperty, FigureDataResult, FigureDataTarget, FigureDataValue, FigureDataValueIssue } from '@hatiolab/figure-model'
+import { FIGURE_PART_ID, FIGURE_MOTION_SPEED_MAX, FigureContractError, figureDataRows, parseFigureAccessor } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureDataBehavior, FigureDataBinding, FigureDataField, FigureDataNode, FigureDataRow, FigureDataValue, FigureDataValueIssue, FigureProposalStep, FigureStatusPort } from '@hatiolab/figure-model'
+import { FigureInputs, type FigureDataResult } from '@hatiolab/things-scene'
 
-/** Something a connection can write, with what the screen shows of it. */
-export interface DataTargetChoice {
-  /** One string per target, for a select's value. */
+/** Something a binding can move, with what the screen shows of it. */
+export interface BehaviorChoice {
+  /** One string per behavior, for a select's value. */
   key: string
-  target: FigureDataTarget
-  /** The control's label, the colour token, or the group's label. */
+  behavior: FigureDataBehavior
+  /** The screen's word for the kind: a control, a colour, a group's clip, … */
+  kind: FigureDataBehavior['kind']
+  /** The control's label, the colour token, the group's label, the port's label, the axis. */
   name: string
   unit?: string
   min?: number
   max?: number
 }
 
-export const targetKeyOf = (t: FigureDataTarget): string =>
-  t.kind === 'state' ? `state:${t.input}` : t.kind === 'palette' ? `palette:${t.token}` : `${t.kind}:${t.group}`
+export const behaviorKeyOf = (b: FigureDataBehavior): string =>
+  b.kind === 'state'
+    ? `state:${b.input}`
+    : b.kind === 'palette'
+      ? `palette:${b.token}`
+      : b.kind === 'status'
+        ? `status:${b.port}`
+        : b.kind === 'pose'
+          ? `pose:${b.axis}`
+          : b.kind === 'items'
+            ? `items:${b.slot ?? ''}`
+            : `${b.kind}:${b.group}`
 
 /**
- * What a property of this kind can be connected to: a number moves a control or a group's speed; an enum or a boolean
- * moves a control, a colour or which clip of a group plays (through a case per value). A control is offered observed: a
- * value read from the machine applies as it comes.
+ * Everything the figure can do that data may drive: each control, each colour, each motion group's clip, speed and
+ * pause, each status port, its position and heading, and -- when it has places -- the items in them.
  */
-export function dataTargetsOf(asset: FigureAsset, kind: FigureDataProperty['kind']): DataTargetChoice[] {
-  const out: DataTargetChoice[] = []
+export function behaviorsOf(asset: FigureAsset): BehaviorChoice[] {
+  const out: BehaviorChoice[] = []
+  const add = (behavior: FigureDataBehavior, name: string, more: Partial<BehaviorChoice> = {}) => out.push({ key: behaviorKeyOf(behavior), behavior, kind: behavior.kind, name, ...more })
   for (const input of asset.document.model.inputs) {
     if (input.role !== 'state') continue
-    const target: FigureDataTarget = { kind: 'state', input: input.id, sourceMode: 'observed' }
-    out.push({ key: targetKeyOf(target), target, name: asset.stateInputs?.[input.id]?.label ?? input.id, unit: input.unit, min: input.min, max: input.max })
+    add({ kind: 'state', input: input.id, sourceMode: 'observed' }, asset.stateInputs?.[input.id]?.label ?? input.id, { unit: input.unit, min: input.min, max: input.max })
   }
-  if (kind !== 'number')
-    for (const token of Object.keys(asset.palette)) {
-      const target: FigureDataTarget = { kind: 'palette', token }
-      out.push({ key: targetKeyOf(target), target, name: token })
-    }
+  for (const token of Object.keys(asset.palette)) add({ kind: 'palette', token }, token)
   for (const group of asset.motionGroups ?? []) {
-    const target: FigureDataTarget = kind === 'number' ? { kind: 'motion-speed', group: group.id } : { kind: 'motion-clip', group: group.id }
-    out.push({ key: targetKeyOf(target), target, name: group.label })
+    add({ kind: 'motion-clip', group: group.id }, group.label)
+    add({ kind: 'motion-speed', group: group.id }, group.label, { min: 0, max: FIGURE_MOTION_SPEED_MAX })
+    add({ kind: 'motion-paused', group: group.id }, group.label)
   }
+  for (const port of asset.dataInterface?.ports ?? []) add({ kind: 'status', port: port.id }, port.label)
+  for (const axis of ['x', 'z', 'y', 'heading'] as const) add({ kind: 'pose', axis, seconds: 1 }, axis, { unit: axis === 'heading' ? 'deg' : 'mm' })
+  if (asset.document.capabilities.slotLayout || asset.document.capabilities.names?.includes('Holdable')) add({ kind: 'items' }, asset.document.capabilities.slotLayout?.label ?? 'items')
   return out
 }
 
-/** The values a lookup has a case for: an enum's values, or both booleans. Nothing for a number. */
-export const domainOf = (property: FigureDataProperty): FigureDataValue[] =>
-  property.kind === 'enum' ? [...property.values] : property.kind === 'boolean' ? [false, true] : []
+const isValue = (n: FigureDataNode): n is Extract<FigureDataNode, { kind: 'number' | 'boolean' | 'text' }> => n.kind === 'number' || n.kind === 'boolean' || n.kind === 'text'
+
+/** Whether a field of this kind can drive the behavior, by some rule -- the choices offered for it. */
+export function fitsField(node: FigureDataNode, choice: BehaviorChoice): boolean {
+  if (choice.kind === 'items') return node.kind === 'list' || node.kind === 'text' || node.kind === 'number'
+  if (!isValue(node)) return false
+  if (choice.kind === 'pose') return node.kind === 'number'
+  if (choice.kind === 'motion-speed') return node.kind === 'number' || node.kind === 'boolean'
+  if (choice.kind === 'motion-paused') return node.kind === 'boolean' || (node.kind === 'text' && !!node.values)
+  if (choice.kind === 'status') return node.kind !== 'boolean'
+  return true
+}
 
 /** An id not taken among `taken`: `base`, then `base-2`, `base-3`, … made into the kernel's id shape. */
-export function freeDataIdOf(taken: Iterable<string>, base: string): string {
+export function freeIdOf(taken: Iterable<string>, base: string): string {
   const used = new Set(taken)
-  const cleaned = base.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^[^a-zA-Z]+/, '').replace(/-+$/, '') || 'data'
-  const id = FIGURE_PART_ID.test(cleaned) ? cleaned : 'data'
+  const cleaned = base.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^[^a-zA-Z]+/, '').replace(/-+$/, '') || 'binding'
+  const id = FIGURE_PART_ID.test(cleaned) ? cleaned : 'binding'
   if (!used.has(id)) return id
   let n = 2
   while (used.has(`${id}-${n}`)) n++
   return `${id}-${n}`
 }
 
+/** How many mm, or degrees, one of a unit is: only lengths and angles are converted. */
+const TO_MM: Record<string, number> = { mm: 1, cm: 10, m: 1000 }
+const TO_DEG: Record<string, number> = { deg: 1, rad: 180 / Math.PI }
+
+/** The values a closed field takes: a closed text's values, both booleans. Empty when open. */
+export const domainOf = (node: FigureDataNode): FigureDataValue[] => (node.kind === 'boolean' ? [false, true] : node.kind === 'text' && node.values ? [...node.values] : [])
+
 /**
- * A first connection of a property to a target, for the author to adjust: a number as it is in the control's own unit,
- * or scaled from another; an enum or a boolean case by case, each case at what the target shows now -- the control's
- * rest value, the colour, the group's first clip. The kernel says whether it holds.
+ * A first binding of a field to a behavior, for the author to adjust: the value as it is when it already fits, a scale
+ * when only its unit or range differs, one result per value (a map) for a closed field, a default for an open one.
+ * Each result starts at what the behavior shows now -- the control's rest value, the colour, the group's default clip --
+ * or, for a clip, the clip of the value's own name. The kernel says whether it holds.
  */
-export function connectionDraftOf(asset: FigureAsset, property: FigureDataProperty, choice: DataTargetChoice): FigureDataConnection {
-  const taken = (asset.dataInterface?.connections ?? []).map(c => c.id)
-  const id = freeDataIdOf(taken, `${property.id}-${choice.target.kind === 'state' ? choice.target.input : choice.target.kind === 'palette' ? 'colour' : choice.target.group}`)
-  const target = choice.target
-  if (property.kind === 'number') {
-    const same = target.kind === 'motion-speed' || (target.kind === 'state' && choice.unit === property.unit)
-    return { id, property: property.id, transform: same ? { kind: 'identity' } : { kind: 'affine', scale: 1, offset: 0 }, target }
+export function bindingDraftOf(asset: FigureAsset, accessor: string, node: FigureDataNode, choice: BehaviorChoice): FigureDataBinding {
+  const taken = (asset.dataInterface?.bindings ?? []).map(b => b.id)
+  const name = accessor.replace(/\[\d+\]/g, '').split('.').pop() ?? accessor
+  const id = freeIdOf(taken, `${name}-${choice.kind === 'state' ? (choice.behavior as { input: string }).input : choice.kind}`)
+  const behavior = choice.behavior
+  const make = (rule: FigureDataBinding['rule'], param?: FigureDataBinding['param']): FigureDataBinding => ({ id, accessor, behavior, rule, ...(param ? { param } : {}) })
+  const domain = domainOf(node)
+  const caseMap = (each: (v: FigureDataValue) => FigureDataValue, fallback: FigureDataValue) => Object.fromEntries([...domain.map(v => [String(v), each(v)] as const), ...(domain.length ? [] : [['default', fallback] as const])])
+
+  if (behavior.kind === 'items') {
+    if (node.kind !== 'list') return make('value')
+    const fields = node.item.kind === 'object' ? node.item.fields : []
+    const pick = (...words: RegExp[]) => fields.find(f => isValue(f) && words.some(w => w.test(f.name)))?.name
+    const itemId = pick(/^id$/i, /name$/i, /id$/i) ?? fields.find(isValue)?.name
+    const type = pick(/type$/i)
+    const place = pick(/^slot/i, /place/i, /port/i)
+    const stack = pick(/stack/i, /level/i)
+    return { id, accessor, behavior: { kind: 'items', ...(itemId ? { id: itemId } : {}), ...(type ? { type } : {}), ...(place ? { place } : {}), ...(stack ? { stack } : {}) }, rule: 'value' }
   }
-  const now: FigureDataValue =
-    target.kind === 'state'
-      ? (asset.stateDefaults[target.input] ?? 0)
-      : target.kind === 'palette'
-        ? (asset.palette[target.token] ?? '#000000')
-        : ((asset.motionGroups ?? []).find(g => g.id === target.group)?.defaultClip ?? '')
-  return { id, property: property.id, transform: { kind: 'lookup', cases: domainOf(property).map(when => ({ when, value: now })) }, target }
-}
-
-/** What a property looks like when first made: a number 0 to 1, a boolean off, an enum of two values. */
-export function propertyDraftOf(asset: FigureAsset, label: string, kind: FigureDataProperty['kind']): FigureDataProperty {
-  const id = freeDataIdOf((asset.dataInterface?.properties ?? []).map(p => p.id), label)
-  if (kind === 'number') return { id, label, kind, unit: 'ratio', min: 0, max: 1, default: 0 }
-  if (kind === 'boolean') return { id, label, kind, default: false }
-  return { id, label, kind, values: ['off', 'on'], default: 'off' }
-}
-
-/** A value typed in a sample field, as the property takes it: a number, true or false, or the enum value. */
-export function sampleValueOf(property: FigureDataProperty, typed: string): FigureDataValue {
-  if (property.kind === 'number') return typed.trim() === '' ? Number.NaN : Number(typed)
-  if (property.kind === 'boolean') return typed === 'true'
-  return typed
+  if (behavior.kind === 'status') return make('value')
+  if (behavior.kind === 'palette') {
+    const now = asset.palette[behavior.token] ?? '#000000'
+    if (node.kind === 'number') return make('range', { default: now })
+    return make('map', caseMap(() => now, now))
+  }
+  if (behavior.kind === 'motion-clip') {
+    const group = (asset.motionGroups ?? []).find(g => g.id === behavior.group)
+    const clips = group?.clips ?? []
+    if (node.kind === 'text' && node.values && node.values.every(v => clips.includes(v))) return make('value')
+    return make('map', caseMap(v => (clips.includes(String(v)) ? String(v) : (group?.defaultClip ?? '')), group?.defaultClip ?? ''))
+  }
+  if (behavior.kind === 'motion-paused') {
+    if (node.kind === 'boolean') return make('value')
+    return make('map', caseMap(() => false, false))
+  }
+  if (behavior.kind === 'pose') {
+    if (node.kind !== 'number') return make('value')
+    const want = behavior.axis === 'heading' ? TO_DEG : TO_MM
+    const unit = node.unit ?? ''
+    if (unit === (behavior.axis === 'heading' ? 'deg' : 'mm')) return make('value')
+    return unit in want ? make('scale', { scale: want[unit]!, offset: 0 }) : make('value')
+  }
+  /* state and motion-speed: a number into a range. */
+  const [lo, hi, unit] =
+    behavior.kind === 'motion-speed' ? [0, FIGURE_MOTION_SPEED_MAX, 'ratio'] : [choice.min ?? 0, choice.max ?? 1, choice.unit ?? '']
+  if (node.kind === 'number') {
+    const sameUnit = behavior.kind === 'motion-speed' ? node.unit === undefined || node.unit === 'ratio' : node.unit === unit
+    const inside = node.min !== undefined && node.max !== undefined && node.min >= lo && node.max <= hi
+    if (sameUnit && inside) return make('value')
+    if (node.min !== undefined && node.max !== undefined && node.max > node.min) {
+      /* The field's range laid onto the behavior's. */
+      const scale = (hi - lo) / (node.max - node.min)
+      return make('scale', { scale: round(scale), offset: round(lo - scale * node.min) })
+    }
+    return make('value')
+  }
+  const rest = behavior.kind === 'motion-speed' ? 1 : (asset.stateDefaults[(behavior as { input: string }).input] ?? lo)
+  if (node.kind === 'boolean') return make('map', { false: behavior.kind === 'motion-speed' ? 0 : lo, true: behavior.kind === 'motion-speed' ? 1 : hi })
+  return make('map', caseMap(() => rest, rest))
+}
+const round = (v: number) => Math.round(v * 1e6) / 1e6
+
+/* ---------------------------------------------------------------- the schema as a tree */
+
+/** A row's path (`L[].F`) as the accessor a value binding reads (`L[0].F`): the first element of each list. */
+export const accessorOfRow = (path: string): string => path.replace(/\[\]/g, '[0]')
+
+/** The field at a row's path, or undefined. */
+export function fieldAt(schema: readonly FigureDataField[], path: string): FigureDataField | undefined {
+  let list: readonly FigureDataField[] = schema
+  let found: FigureDataField | undefined
+  for (const part of path.split('.')) {
+    const name = part.replace(/\[\]/g, '')
+    found = list.find(f => f.name === name)
+    if (!found) return undefined
+    let node: FigureDataNode = found
+    while (node.kind === 'list') node = node.item
+    list = node.kind === 'object' ? node.fields : []
+  }
+  return found
+}
+
+/** The fields under a row's path, where a new field goes: the top, an object's fields, a list's element's fields. */
+function fieldsUnder(schema: FigureDataField[], path: string): FigureDataField[] | undefined {
+  if (!path) return schema
+  const field = fieldAt(schema, path)
+  if (!field) return undefined
+  let node: FigureDataNode = field
+  while (node.kind === 'list') node = node.item
+  return node.kind === 'object' ? node.fields : undefined
+}
+
+/** The schema with a field added under a path ('' for the top): a copy, the given one left as it is. */
+export function schemaWithField(schema: readonly FigureDataField[], under: string, field: FigureDataField): FigureDataField[] {
+  const out = structuredClone(schema) as FigureDataField[]
+  fieldsUnder(out, under)?.push(field)
+  return out
+}
+
+/** The schema with the field at a path replaced (its name kept unless the new one says another). */
+export function schemaWithFieldReplaced(schema: readonly FigureDataField[], path: string, field: FigureDataField): FigureDataField[] {
+  const out = structuredClone(schema) as FigureDataField[]
+  const parent = path.includes('.') ? path.slice(0, path.lastIndexOf('.')) : ''
+  const list = fieldsUnder(out, parent)
+  const name = path.split('.').pop()!.replace(/\[\]/g, '')
+  const at = list?.findIndex(f => f.name === name) ?? -1
+  if (list && at >= 0) list[at] = field
+  return out
+}
+
+/** The schema without the field at a path. */
+export function schemaWithoutField(schema: readonly FigureDataField[], path: string): FigureDataField[] {
+  const out = structuredClone(schema) as FigureDataField[]
+  const parent = path.includes('.') ? path.slice(0, path.lastIndexOf('.')) : ''
+  const list = fieldsUnder(out, parent)
+  const name = path.split('.').pop()!.replace(/\[\]/g, '')
+  const at = list?.findIndex(f => f.name === name) ?? -1
+  if (list && at >= 0) list.splice(at, 1)
+  return out
 }
 
+/** A field of another kind, its name, label and json flag kept, the rest started fresh. */
+export function fieldOfKind(field: FigureDataField, kind: FigureDataNode['kind']): FigureDataField {
+  const head = { name: field.name, ...(field.label ? { label: field.label } : {}) }
+  if (kind === 'object') return { ...head, kind, fields: field.kind === 'object' ? field.fields : [] }
+  if (kind === 'list') return { ...head, kind, item: field.kind === 'list' ? field.item : { kind: 'object', fields: [] } }
+  return { ...head, kind } as FigureDataField
+}
+
+/** The rows of the schema, each with the bindings that read it (figure-model's view). */
+export const schemaRowsOf = (asset: FigureAsset): FigureDataRow[] => (asset.dataInterface ? figureDataRows(asset.dataInterface) : [])
+
+/* ---------------------------------------------------------------- reading a sample */
+
 /**
- * What a sample of values would move, as the figure would run it: the kernel's check and evaluation of the interface.
- * Refused whole when one value cannot be taken, with each one's reason, as a live snapshot is.
+ * What a sample of data would do on this figure, read the one way a placed figure reads it (things-scene's figure
+ * inputs): what it moves, or why it is refused, each value's reason. Nothing here reads data itself.
  */
-export function dataSampleOf(asset: FigureAsset, values: Record<string, FigureDataValue>): { result: FigureDataResult } | { issues: FigureDataValueIssue[] } {
-  const plan = compileFigureDataInterface(asset)
-  if (!plan) return { issues: [] }
-  const issues = validateFigureDataValues(plan, values)
-  return issues.length ? { issues } : { result: evaluateFigureDataInterface(plan, values) }
+export function sampleOf(asset: FigureAsset, sample: unknown): { issues: FigureDataValueIssue[]; result: FigureDataResult } {
+  const inputs = new FigureInputs(asset)
+  const taken = inputs.setData(sample)
+  return { issues: taken.accepted ? [] : (taken.issues[0]?.issues ?? []), result: inputs.data }
+}
+
+/** The rows a person gives a value by hand, as a board's saved values: one value, read by a binding, not inside a list. */
+export const valueRowsOf = (asset: FigureAsset): FigureDataRow[] => schemaRowsOf(asset).filter(r => isValue(r.node) && r.bindings.length > 0 && !r.path.includes('[]'))
+
+/** A value typed or chosen for a row, as its kind reads it: a number (NaN when empty), true or false, or the text. */
+export function typedValueOf(node: FigureDataNode, typed: string): FigureDataValue {
+  if (node.kind === 'number') return typed.trim() === '' ? Number.NaN : Number(typed)
+  if (node.kind === 'boolean') return typed === 'true'
+  return typed
+}
+
+/** The parts a status port may show on: the parts the figure's appearance names. */
+export const partsOf = (asset: FigureAsset): string[] => [...new Set(asset.appearance.map(a => a.target))]
+
+/** A first status port: the label as given, on the first colour token, no part yet. The kernel says whether it holds. */
+export function portDraftOf(asset: FigureAsset, label: string): FigureStatusPort {
+  const taken = (asset.dataInterface?.ports ?? []).map(p => p.id)
+  const token = Object.keys(asset.palette)[0]
+  return { id: freeIdOf(taken, label.trim() || 'status'), label: label.trim(), tokens: token ? [token] : [], parts: [] }
 }
 
+/** Whether a text is an accessor the kernel takes. */
+export const accessorTaken = (accessor: string): boolean => parseFigureAccessor(accessor) !== null
+
 /**
- * Which fields of each motion group the data interface writes: its clip (a lookup to `motion-clip`), its speed
- * (`motion-speed`). The data always writes them -- from a live value, a saved one, or the property's default -- and
- * wins over a group's own setting for that field (detail design §5.1), so a control for such a field moves nothing.
+ * Which fields of each motion group the data binds: its clip, its speed. A field bound wins over the group's own setting
+ * whenever the data, a saved value or the schema's default gives it a value, so the preview drives it through the data.
  */
 export function motionWrittenByData(asset: FigureAsset): Record<string, { clip: boolean; speed: boolean }> {
   const out: Record<string, { clip: boolean; speed: boolean }> = {}
-  for (const c of asset.dataInterface?.connections ?? []) {
-    if (c.target.kind !== 'motion-clip' && c.target.kind !== 'motion-speed') continue
-    const one = (out[c.target.group] ??= { clip: false, speed: false })
-    if (c.target.kind === 'motion-clip') one.clip = true
+  for (const b of asset.dataInterface?.bindings ?? []) {
+    if (b.behavior.kind !== 'motion-clip' && b.behavior.kind !== 'motion-speed') continue
+    const one = (out[b.behavior.group] ??= { clip: false, speed: false })
+    if (b.behavior.kind === 'motion-clip') one.clip = true
     else one.speed = true
   }
   return out
 }
 
+/* ---------------------------------------------------------------- the rotation card */
+
+/** A joint that turns without end (a roller, a fan, a turntable): its control, by the id the clips write. */
+export interface EndlessJoint {
+  input: string
+  label: string
+  unit: 'deg' | 'rad'
+}
+
+/** The joints that turn without end: revolute, with no limits, leading no one's mimic. */
+export function endlessJointsOf(asset: FigureAsset): EndlessJoint[] {
+  const out: EndlessJoint[] = []
+  for (const j of asset.joints ?? []) {
+    if (j.type !== 'revolute' || j.lowerLimit !== undefined || j.upperLimit !== undefined || j.mimic) continue
+    const input = j.state?.id ?? j.id
+    const unit = asset.document.model.inputs.find(i => i.id === input)?.unit
+    if (unit !== 'deg' && unit !== 'rad') continue
+    if (!out.some(e => e.input === input)) out.push({ input, label: asset.stateInputs?.[input]?.label ?? input, unit })
+  }
+  return out
+}
+
+/** What the rotation card is told: the joint, and the data fields that turn it on, set its speed and its direction. */
+export interface RotationChoice {
+  input: string
+  /** The motion group's name, shown to a person. */
+  label: string
+  /** A boolean field: true turns, false stops where it is. */
+  on?: string
+  /** A number field in turns per minute, and the most it gives; the field's range is set to 0..max when it has none. */
+  speed?: { path: string; max: number }
+  /** A closed text field, and its value that turns forward and the one that turns back. */
+  direction?: { path: string; forward: string; reverse: string }
+}
+
+/**
+ * The rotation card's commands (data binding design decision 1, 「회전」): a clip that turns the joint once around and
+ * keeps adding the turn (wrap, accumulating), a reverse one when a direction is given, the motion group holding them,
+ * and the bindings -- on to the group's pause, speed to its speed, direction to its clip. Nothing new runs them: they
+ * are the drivers, the group and the bindings any author could write, and stay editable one by one.
+ *
+ * The clip lasts `T = 3 × 60 / max rpm` seconds, so the most the field gives plays at the group's top speed, 3 -- the
+ * speed range is not widened. One turn per `T` at speed 1, and speed = rpm × T / 60. A stop is a pause: the joint stays
+ * where it is, where a stopped clip would jump back to its first key.
+ */
+export function rotationStepsOf(asset: FigureAsset, c: RotationChoice): FigureProposalStep[] {
+  const joint = endlessJointsOf(asset).find(j => j.input === c.input)
+  if (!joint) throw new FigureContractError('TARGET_ABSENT', c.input, `${c.input} is not a joint that turns without end`)
+  const turn = joint.unit === 'deg' ? 360 : 2 * Math.PI
+  const seconds = c.speed && c.speed.max > 0 ? round((3 * 60) / c.speed.max) : 1
+  const group = freeIdOf((asset.motionGroups ?? []).map(g => g.id), `${joint.input}-spin`)
+  const forward = group
+  const reverse = `${group}-reverse`
+  const steps: FigureProposalStep[] = []
+  const schema = asset.dataInterface?.schema ?? []
+  if (c.speed) {
+    const field = fieldAt(schema, c.speed.path)
+    if (field?.kind === 'number' && (field.min === undefined || field.max === undefined))
+      steps.push({ kind: 'set-data-schema', schema: schemaWithFieldReplaced(schema, c.speed.path, { ...field, min: field.min ?? 0, max: field.max ?? c.speed.max }) })
+  }
+  const spin = (clip: string, way: 1 | -1, inGroup: boolean): FigureProposalStep => ({
+    kind: 'set-driver',
+    state: joint.input,
+    clip,
+    duration: seconds,
+    keys: [
+      { seconds: 0, value: 0 },
+      { seconds, value: way * turn }
+    ],
+    interpolation: 'linear',
+    loop: 'wrap',
+    accumulates: true,
+    ...(inGroup ? { group } : {})
+  })
+  const clips = c.direction ? [forward, reverse] : [forward]
+  steps.push(spin(forward, 1, false))
+  steps.push({ kind: 'set-motion-group', group: { id: group, label: c.label, clips: [forward], defaultClip: forward, transitionSeconds: 0 } })
+  if (c.direction) {
+    steps.push(spin(reverse, -1, true))
+    steps.push({ kind: 'set-motion-group', group: { id: group, label: c.label, clips, defaultClip: forward, transitionSeconds: 0 } })
+  }
+  const taken = (asset.dataInterface?.bindings ?? []).map(b => b.id)
+  const bind = (base: string, binding: Omit<FigureDataBinding, 'id'>): FigureProposalStep => {
+    const id = freeIdOf(taken, base)
+    taken.push(id)
+    return { kind: 'set-data-binding', binding: { id, ...binding } }
+  }
+  if (c.on) steps.push(bind(`${group}-on`, { accessor: c.on, behavior: { kind: 'motion-paused', group }, rule: 'map', param: { true: false, false: true } }))
+  if (c.speed) steps.push(bind(`${group}-speed`, { accessor: c.speed.path, behavior: { kind: 'motion-speed', group }, rule: 'scale', param: { scale: round(seconds / 60), offset: 0 } }))
+  if (c.direction) {
+    const values = domainOf(fieldAt(schema, c.direction.path) ?? { kind: 'text' }).map(String)
+    const covered = values.every(v => v === c.direction!.forward || v === c.direction!.reverse)
+    steps.push(
+      bind(`${group}-direction`, {
+        accessor: c.direction.path,
+        behavior: { kind: 'motion-clip', group },
+        rule: 'map',
+        param: { [c.direction.forward]: forward, [c.direction.reverse]: reverse, ...(covered ? {} : { default: forward }) }
+      })
+    )
+  }
+  return steps
+}

package/client/modeller/editor.ts

@@ -750,8 +750,8 @@ export class FigureEditor extends LitElement {
     return this.lastAnchors
   }
   private lastAnchors: Record<string, ScaleAnchor> = {}
-  /** Data values tried in the data tab, run by the preview's figure; null when none are (ADR-0051 §2.2). */
-  @state() private dataSample: Record<string, unknown> | null = null
+  /** Data tried in the data tab, given to the preview's figures as their `data`; null when none is (ADR-0051 §8). */
+  @state() private dataSample: unknown = null
   /** The figure's controls: try a value, name it, set its range and travel time, keep the pose. */
   private renderControls(view: { fields: Array<{ id: string; role?: string; value: number }> }, unavailable: boolean) {
     const asset = this.shown()?.asset
@@ -1666,8 +1666,9 @@ export class FigureEditor extends LitElement {
             <figure-data-panel
               .asset=${asset}
               ?locked=${unavailable}
-              @data-sample=${(e: CustomEvent) => (this.dataSample = e.detail.values)}
+              @data-sample=${(e: CustomEvent) => (this.dataSample = e.detail.data)}
               @part-edit=${(e: CustomEvent) => this.run(() => this.session!.edit(e.detail.edit))}
+              @part-edits=${(e: CustomEvent) => this.run(() => this.session!.applyRecipe(e.detail.edits))}
             ></figure-data-panel>
           </div>
           <div panel flush ?off=${tab !== 'verdict'}><slot name="verdict"></slot></div>