@things-factory/figure-ui 10.1.155 → 10.1.157

package/client/modeller/figure-data-panel.ts

@@ -0,0 +1,308 @@
+import '@material/web/icon/icon.js'
+
+import { css, html, LitElement, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+
+import { i18next, localize } from '@operato/i18n'
+import { FIGURE_UNITS } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureDataConnection, FigureDataProperty, FigureDataValue } from '@hatiolab/figure-model'
+
+import { connectionDraftOf, dataSampleOf, dataTargetsOf, domainOf, propertyDraftOf, sampleValueOf, targetKeyOf, type DataTargetChoice } from './data-interface.js'
+import { SidePanelStyles } from '@things-factory/figure-viewer/dist-client/side-panel-styles.js'
+import { HelpToggles } from './help.js'
+
+/**
+ * 데이터 -- the figure's public data properties and what each moves inside it (ADR-0051 §2.2). A property is a value a
+ * consumer maps its own data onto, by its id: a number with a unit and a range, a boolean, or an enum. A connection
+ * makes a property move a control, a colour, or which clip of a motion group plays and how fast. Every change is one
+ * part edit, and whether it holds is the kernel's check.
+ *
+ * The sample is not saved: values tried here, what they would move (figure-model's evaluation), and -- in the preview --
+ * the figure running on them (`data-sample`).
+ */
+@customElement('figure-data-panel')
+export class FigureDataPanel extends localize(i18next)(LitElement) {
+  private readonly help = new HelpToggles(this)
+  static styles = [SidePanelStyles, css`
+    :host {
+      display: block;
+    }
+    section[item] {
+      display: grid;
+      gap: 8px;
+      padding: 8px;
+      border: 1px solid var(--md-sys-color-outline-variant);
+      border-radius: 8px;
+    }
+    div[head] {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 30px;
+      gap: 6px;
+      align-items: center;
+    }
+    div[head] strong {
+      min-width: 0;
+      overflow-wrap: anywhere;
+    }
+    div[head] button[act] {
+      width: 30px;
+      min-height: var(--figure-control-height);
+      margin: 0;
+      padding: 0;
+    }
+    div[cases] {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) minmax(0, 1.4fr);
+      gap: 4px 6px;
+      align-items: center;
+    }
+    ul[result] {
+      margin: 0;
+      padding-left: 16px;
+    }
+    md-icon {
+      font-size: 16px;
+      width: 16px;
+      height: 16px;
+    }
+  `]
+
+  @property({ attribute: false }) asset?: FigureAsset
+  @property({ type: Boolean }) locked = false
+
+  @state() private adding = { label: '', kind: 'number' as FigureDataProperty['kind'] }
+  @state() private connecting = { property: '', target: '' }
+  /** The sample's values as typed, by property id; a property left out reads its default. */
+  @state() private sample: Record<string, FigureDataValue> = {}
+  @state() private sampling = false
+
+  render() {
+    const asset = this.asset
+    if (!asset) return nothing
+    const properties = asset.dataInterface?.properties ?? []
+    const connections = asset.dataInterface?.connections ?? []
+    return html`
+      <section>
+        <h3>${i18next.t('figure.label.data-properties')}${this.help.button('figure.text.data-properties-explained')}</h3>
+        ${this.help.hint('figure.text.data-properties-explained')}
+        ${properties.map(p => this.renderProperty(p))}
+        ${this.renderAddProperty(asset)}
+      </section>
+      <section>
+        <h3>${i18next.t('figure.label.data-connections')}${this.help.button('figure.text.data-connections-explained')}</h3>
+        ${this.help.hint('figure.text.data-connections-explained')}
+        ${connections.map(c => this.renderConnection(asset, c, properties.find(p => p.id === c.property)))}
+        ${properties.length ? this.renderAddConnection(asset, properties) : html`<p hint>${i18next.t('figure.text.data-no-properties')}</p>`}
+      </section>
+      ${properties.length ? this.renderSample(asset, properties) : nothing}
+    `
+  }
+
+  private renderProperty(p: FigureDataProperty) {
+    const set = (patch: Partial<FigureDataProperty>) => this.edit({ kind: 'set-data-property', property: { ...p, ...patch } as FigureDataProperty })
+    const value = (e: Event) => (e.target as HTMLInputElement | HTMLSelectElement).value
+    const number = (e: Event) => (e.target as HTMLInputElement).valueAsNumber
+    return html`<section item>
+      <div head>
+        <strong>${p.label} <small>(${i18next.t('figure.label.data-kind-' + p.kind)})</small></strong>
+        <button act ?disabled=${this.locked} title=${i18next.t('figure.button.remove-data-property')} @click=${() => this.edit({ kind: 'remove-data-property', id: p.id })}>
+          <md-icon>close</md-icon>
+        </button>
+      </div>
+      <div form>
+        <span>${i18next.t('figure.label.data-id')}</span>
+        <input .value=${p.id} ?disabled=${this.locked} @change=${(e: Event) => value(e).trim() !== p.id && this.edit({ kind: 'rename-data-property', id: p.id, to: value(e).trim() })} />
+        <span>${i18next.t('figure.label.name')}</span>
+        <input .value=${p.label} ?disabled=${this.locked} @change=${(e: Event) => value(e).trim() && set({ label: value(e).trim() })} />
+        ${p.kind === 'number'
+          ? html`<span>${i18next.t('figure.label.data-unit')}</span>
+              <select ?disabled=${this.locked} @change=${(e: Event) => set({ unit: value(e) as never })}>
+                ${FIGURE_UNITS.map(u => html`<option value=${u} ?selected=${u === p.unit}>${u}</option>`)}
+              </select>
+              <span>${i18next.t('figure.label.data-min')}</span>
+              <input type="number" step="any" .value=${String(p.min)} ?disabled=${this.locked} @change=${(e: Event) => set({ min: number(e) })} />
+              <span>${i18next.t('figure.label.data-max')}</span>
+              <input type="number" step="any" .value=${String(p.max)} ?disabled=${this.locked} @change=${(e: Event) => set({ max: number(e) })} />
+              <span>${i18next.t('figure.label.data-default')}</span>
+              <input type="number" step="any" .value=${String(p.default)} ?disabled=${this.locked} @change=${(e: Event) => set({ default: number(e) })} />`
+          : p.kind === 'boolean'
+            ? html`<span>${i18next.t('figure.label.data-default')}</span>
+                <select ?disabled=${this.locked} @change=${(e: Event) => set({ default: value(e) === 'true' })}>
+                  ${[false, true].map(b => html`<option value=${String(b)} ?selected=${b === p.default}>${i18next.t(b ? 'figure.label.data-true' : 'figure.label.data-false')}</option>`)}
+                </select>`
+            : html`<span>${i18next.t('figure.label.data-values')}</span>
+                <input
+                  .value=${p.values.join(', ')}
+                  ?disabled=${this.locked}
+                  @change=${(e: Event) => {
+                    const values = value(e).split(',').map(v => v.trim()).filter(Boolean)
+                    set({ values, default: values.includes(p.default) ? p.default : values[0]! } as never)
+                  }}
+                />
+                <span>${i18next.t('figure.label.data-default')}</span>
+                <select ?disabled=${this.locked} @change=${(e: Event) => set({ default: value(e) })}>
+                  ${p.values.map(v => html`<option value=${v} ?selected=${v === p.default}>${v}</option>`)}
+                </select>`}
+      </div>
+    </section>`
+  }
+
+  private renderAddProperty(asset: FigureAsset) {
+    const a = this.adding
+    return html`<div form>
+        <span>${i18next.t('figure.label.name')}</span>
+        <input .value=${a.label} @input=${(e: Event) => (this.adding = { ...a, label: (e.target as HTMLInputElement).value })} />
+        <span>${i18next.t('figure.label.data-kind')}</span>
+        <select @change=${(e: Event) => (this.adding = { ...a, kind: (e.target as HTMLSelectElement).value as FigureDataProperty['kind'] })}>
+          ${(['number', 'boolean', 'enum'] as const).map(k => html`<option value=${k} ?selected=${k === a.kind}>${i18next.t('figure.label.data-kind-' + k)}</option>`)}
+        </select>
+      </div>
+      <button
+        act
+        ?disabled=${this.locked || !a.label.trim()}
+        @click=${() => {
+          this.edit({ kind: 'set-data-property', property: propertyDraftOf(asset, a.label.trim(), a.kind) })
+          this.adding = { ...a, label: '' }
+        }}
+      >
+        <md-icon>add</md-icon>${i18next.t('figure.button.add-data-property')}
+      </button>`
+  }
+
+  private targetName(asset: FigureAsset, c: FigureDataConnection, property?: FigureDataProperty): string {
+    const choice = property ? dataTargetsOf(asset, property.kind).find(t => t.key === targetKeyOf(c.target)) : undefined
+    const name = choice?.name ?? targetKeyOf(c.target)
+    return i18next.t('figure.label.data-target-' + c.target.kind, { name })
+  }
+
+  private renderConnection(asset: FigureAsset, c: FigureDataConnection, property?: FigureDataProperty) {
+    const set = (patch: Partial<FigureDataConnection>) => this.edit({ kind: 'set-data-connection', connection: { ...c, ...patch } })
+    const number = (e: Event) => (e.target as HTMLInputElement).valueAsNumber
+    const t = c.transform
+    return html`<section item>
+      <div head>
+        <strong>${property?.label ?? c.property} → ${this.targetName(asset, c, property)}</strong>
+        <button act ?disabled=${this.locked} title=${i18next.t('figure.button.remove-data-connection')} @click=${() => this.edit({ kind: 'remove-data-connection', id: c.id })}>
+          <md-icon>close</md-icon>
+        </button>
+      </div>
+      <div form>
+        ${c.target.kind === 'state'
+          ? html`<span>${i18next.t('figure.label.data-source-mode')}</span>
+              <select ?disabled=${this.locked} @change=${(e: Event) => set({ target: { ...(c.target as { kind: 'state'; input: string }), sourceMode: (e.target as HTMLSelectElement).value as 'observed' | 'commanded' } })}>
+                ${(['observed', 'commanded'] as const).map(m => html`<option value=${m} ?selected=${c.target.kind === 'state' && c.target.sourceMode === m}>${i18next.t('figure.label.data-' + m)}</option>`)}
+              </select>`
+          : nothing}
+        ${t.kind === 'lookup'
+          ? nothing
+          : html`<span>${i18next.t('figure.label.data-transform')}</span>
+              <select ?disabled=${this.locked} @change=${(e: Event) => set({ transform: (e.target as HTMLSelectElement).value === 'affine' ? { kind: 'affine', scale: 1, offset: 0 } : { kind: 'identity' } })}>
+                <option value="identity" ?selected=${t.kind === 'identity'}>${i18next.t('figure.label.data-identity')}</option>
+                <option value="affine" ?selected=${t.kind === 'affine'}>${i18next.t('figure.label.data-affine')}</option>
+              </select>`}
+        ${t.kind === 'affine'
+          ? html`<span>${i18next.t('figure.label.data-scale')}</span>
+              <input type="number" step="any" .value=${String(t.scale)} ?disabled=${this.locked} @change=${(e: Event) => set({ transform: { ...t, scale: number(e) } })} />
+              <span>${i18next.t('figure.label.data-offset')}</span>
+              <input type="number" step="any" .value=${String(t.offset)} ?disabled=${this.locked} @change=${(e: Event) => set({ transform: { ...t, offset: number(e) } })} />`
+          : nothing}
+      </div>
+      ${t.kind === 'lookup' ? this.renderCases(asset, c, set) : nothing}
+    </section>`
+  }
+
+  /** A case per value of the property: what the target takes for it -- a number, a colour, or a clip of the group. */
+  private renderCases(asset: FigureAsset, c: FigureDataConnection, set: (patch: Partial<FigureDataConnection>) => void) {
+    if (c.transform.kind !== 'lookup') return nothing
+    const cases = c.transform.cases
+    const write = (i: number, value: FigureDataValue) => set({ transform: { kind: 'lookup', cases: cases.map((k, j) => (j === i ? { ...k, value } : k)) } })
+    const clips = c.target.kind === 'motion-clip' ? ((asset.motionGroups ?? []).find(g => c.target.kind === 'motion-clip' && g.id === c.target.group)?.clips ?? []) : []
+    return html`<div cases>
+      ${cases.map(
+        (k, i) => html`<span>${typeof k.when === 'boolean' ? i18next.t(k.when ? 'figure.label.data-true' : 'figure.label.data-false') : String(k.when)}</span>
+          ${c.target.kind === 'palette'
+            ? html`<input type="color" .value=${String(k.value)} ?disabled=${this.locked} @change=${(e: Event) => write(i, (e.target as HTMLInputElement).value)} />`
+            : c.target.kind === 'motion-clip'
+              ? html`<select ?disabled=${this.locked} @change=${(e: Event) => write(i, (e.target as HTMLSelectElement).value)}>
+                  ${clips.map(clip => html`<option value=${clip} ?selected=${clip === k.value}>${clip}</option>`)}
+                </select>`
+              : html`<input type="number" step="any" .value=${String(k.value)} ?disabled=${this.locked} @change=${(e: Event) => write(i, (e.target as HTMLInputElement).valueAsNumber)} />`}`
+      )}
+    </div>`
+  }
+
+  private renderAddConnection(asset: FigureAsset, properties: FigureDataProperty[]) {
+    const a = this.connecting
+    const property = properties.find(p => p.id === a.property) ?? properties[0]!
+    const targets = dataTargetsOf(asset, property.kind)
+    const choice = targets.find(t => t.key === a.target) ?? targets[0]
+    return html`<div form>
+        <span>${i18next.t('figure.label.data-property')}</span>
+        <select @change=${(e: Event) => (this.connecting = { ...a, property: (e.target as HTMLSelectElement).value })}>
+          ${properties.map(p => html`<option value=${p.id} ?selected=${p === property}>${p.label}</option>`)}
+        </select>
+        <span>${i18next.t('figure.label.data-target')}</span>
+        <select ?disabled=${!targets.length} @change=${(e: Event) => (this.connecting = { ...a, target: (e.target as HTMLSelectElement).value })}>
+          ${targets.map((t: DataTargetChoice) => html`<option value=${t.key} ?selected=${t === choice}>${i18next.t('figure.label.data-target-' + t.target.kind, { name: t.name })}</option>`)}
+        </select>
+      </div>
+      <button act ?disabled=${this.locked || !choice} @click=${() => this.edit({ kind: 'set-data-connection', connection: connectionDraftOf(asset, property, choice!) })}>
+        <md-icon>add</md-icon>${i18next.t('figure.button.add-data-connection')}
+      </button>`
+  }
+
+  /** Values to try: what they move, by figure-model's evaluation; in the preview, the figure running on them. */
+  private renderSample(asset: FigureAsset, properties: FigureDataProperty[]) {
+    const values = Object.fromEntries(properties.map(p => [p.id, this.sample[p.id] ?? p.default]))
+    const outcome = dataSampleOf(asset, values)
+    return html`<section>
+      <h3>${i18next.t('figure.label.data-sample')}${this.help.button('figure.text.data-sample-explained')}</h3>
+      ${this.help.hint('figure.text.data-sample-explained')}
+      <div form>
+        ${properties.map(
+          p => html`<span>${p.label}</span>
+            ${p.kind === 'number'
+              ? html`<input type="number" step="any" .value=${String(values[p.id])} @change=${(e: Event) => this.try(p, (e.target as HTMLInputElement).value)} />`
+              : html`<select @change=${(e: Event) => this.try(p, (e.target as HTMLSelectElement).value)}>
+                  ${domainOf(p).map(v => html`<option value=${String(v)} ?selected=${v === values[p.id]}>${typeof v === 'boolean' ? i18next.t(v ? 'figure.label.data-true' : 'figure.label.data-false') : v}</option>`)}
+                </select>`}`
+        )}
+      </div>
+      ${'issues' in outcome
+        ? html`<p hint>${outcome.issues.map(i => i18next.t('figure.text.data-value-' + i.reason, { property: i.property ?? '' })).join(' · ')}</p>`
+        : html`<ul result>
+            ${Object.entries(outcome.result.states).map(([input, s]) => html`<li>${asset.stateInputs?.[input]?.label ?? input} = ${s.value}</li>`)}
+            ${Object.entries(outcome.result.palette).map(([token, colour]) => html`<li>${token} = ${colour}</li>`)}
+            ${Object.entries(outcome.result.motion).map(
+              ([group, m]) => html`<li>${(asset.motionGroups ?? []).find(g => g.id === group)?.label ?? group}: ${[m.clip, m.speed === undefined ? '' : `× ${m.speed}`].filter(Boolean).join(' ')}</li>`
+            )}
+          </ul>`}
+      <label toggle>
+        <input
+          type="checkbox"
+          .checked=${this.sampling}
+          @change=${(e: Event) => {
+            this.sampling = (e.target as HTMLInputElement).checked
+            this.tell(values)
+          }}
+        />
+        ${i18next.t('figure.label.data-sample-in-preview')}
+      </label>
+    </section>`
+  }
+
+  private try(property: FigureDataProperty, typed: string) {
+    this.sample = { ...this.sample, [property.id]: sampleValueOf(property, typed) }
+    const properties = this.asset?.dataInterface?.properties ?? []
+    this.tell(Object.fromEntries(properties.map(p => [p.id, this.sample[p.id] ?? p.default])))
+  }
+
+  /** The sample to the preview while it is asked for; null lets the preview's figure go back to its own values. */
+  private tell(values: Record<string, FigureDataValue>) {
+    this.dispatchEvent(new CustomEvent('data-sample', { detail: { values: this.sampling ? values : null }, bubbles: true, composed: true }))
+  }
+
+  private edit(edit: unknown) {
+    this.dispatchEvent(new CustomEvent('part-edit', { detail: { edit }, bubbles: true, composed: true }))
+  }
+}

package/client/modeller/figure-preview.ts

@@ -196,6 +196,10 @@ export class FigurePreview extends localize(i18next)(LitElement) {
   /** Clip speeds and control values given here -- the preview's, not the figure's. */
   @state() private driving: Record<string, number> = {}
   @state() private giving: Record<string, number> = {}
+  /** Per motion group, the clip played here and how fast (ADR-0051 §3.2) -- the preview's, as a board's \`motion\`. */
+  @state() private moving: Record<string, { clip: string; speed: number }> = {}
+  /** Data values tried in the data tab: the preview's figures run on them as a live snapshot; null when none are. */
+  @property({ attribute: false }) sample: Record<string, unknown> | null = null
   /** The part chosen in the editor. The size help starts on it, so the help speaks of the part the author was working on. */
   @property() selected = ''
   @state() private setupPart = ''
@@ -215,7 +219,9 @@ export class FigurePreview extends localize(i18next)(LitElement) {
   render() {
     const asset = this.asset
     const controls = asset ? asset.document.model.inputs.filter(i => i.role === 'state') : []
-    const clips = asset ? [...new Set((asset.drivers ?? []).map(d => d.clip))] : []
+    /* Clips in a motion group are played by the group's choice of clip, not each by its own speed. */
+    const grouped = new Set((asset?.motionGroups ?? []).flatMap(g => g.clips))
+    const clips = asset ? [...new Set((asset.drivers ?? []).map(d => d.clip))].filter(c => !grouped.has(c)) : []
     let clampsByWay: ReturnType<typeof previewClampsOf> = {}
     try {
       clampsByWay = asset ? previewClampsOf(asset, this.authoredSize()) : {}
@@ -245,7 +251,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
               </select>
               <button @click=${() => this.dispatchEvent(new CustomEvent('configure-size', { detail: { part: setupPart }, bubbles: true, composed: true }))}>${i18next.t('figure.button.configure-size')}</button>
             </div>` : nothing}
-            ${controls.length + clips.length ? this.renderDrivers(asset!, controls, clips) : nothing}</div>`}`
+            ${controls.length + clips.length + (asset?.motionGroups?.length ?? 0) ? this.renderDrivers(asset!, controls, clips) : nothing}</div>`}`
   }
 
   private renderDrivers(asset: FigureAsset, controls: FigureAsset['document']['model']['inputs'], clips: string[]) {
@@ -287,9 +293,25 @@ export class FigurePreview extends localize(i18next)(LitElement) {
           <output>${value.toFixed(2)}</output>
         </label>`
       })}
+      ${(asset.motionGroups ?? []).map(group => {
+        const playing = this.moving[group.id] ?? { clip: group.defaultClip, speed: 0 }
+        return html`<label>
+          <span>${group.label} <span drive>${i18next.t('figure.label.playback-speed')}</span></span>
+          <select aria-label=${group.label} @change=${(e: Event) => this.move(group.id, { ...playing, clip: (e.target as HTMLSelectElement).value })}>
+            ${group.clips.map(c => html`<option value=${c} ?selected=${c === playing.clip}>${c}</option>`)}
+          </select>
+          <input type="range" min="0" max="3" step="0.05" .value=${String(playing.speed)} @input=${(e: Event) => this.move(group.id, { ...playing, speed: Number((e.target as HTMLInputElement).value) })} />
+          <output>${playing.speed.toFixed(2)}</output>
+        </label>`
+      })}
     </div>`
   }
 
+  private move(group: string, playing: { clip: string; speed: number }) {
+    this.moving = { ...this.moving, [group]: playing }
+    this.tellInstances('motion', Object.fromEntries(Object.entries(this.moving).map(([id, m]) => [id, { ...m, paused: false }])))
+  }
+
   private renderDial(control: { unit: string; min: number; max: number }, value: number) {
     if (control.unit !== 'deg') return html`<span></span>`
     const dial = dialShape(control.min, control.max, value)
@@ -316,11 +338,23 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     this.giving = {}
   }
 
-  private tellInstances(key: 'clips' | 'parameters', values: Record<string, number>) {
-    for (const component of this.scene?.root?.components ?? []) component.set?.(key, { ...values })
+  private tellInstances(key: 'clips' | 'parameters' | 'motion' | 'figureData', values: Record<string, unknown> | null) {
+    for (const component of this.scene?.root?.components ?? []) {
+      const value = values === null ? null : { ...values }
+      /* A live snapshot is transient on the figure (its \`figureData\` accessor), never written into the saved model. */
+      if (key === 'figureData') (component as { figureData?: unknown }).figureData = value
+      else component.set?.(key, value)
+    }
+  }
+
+
+  /** The data sample to the figures standing now: a live snapshot, transient on each, never saved with the board. */
+  private tellSample() {
+    if (this.sample) this.tellInstances('figureData', { ...this.sample })
   }
 
   willUpdate(changed: Map<string, unknown>) {
+    if (changed.has('sample') && this.scene) this.tellInstances('figureData', this.sample ? { ...this.sample } : null)
     if (!this.hasUpdated) return
     if (!this.active) {
       this.stale = true
@@ -387,6 +421,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
       const again = this.scene?.rootContainer?.rebuildContentModel && this.registered === type
       if (!again) this.teardown()
       this.driving = {}
+      this.moving = {}
       registerFigure(type, asset)
       this.registered = type
       const { components, board } = previewInstances(type, size)
@@ -408,6 +443,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
           this.scene!.rootContainer!.rebuildContentModel!(model, { preserveThreeD: true })
           this.standing = signature
           this.cannot = ''
+          this.tellSample()
           return
         } catch {
           this.teardown()
@@ -425,6 +461,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
       this.scene.fit?.('ratio')
       this.scene.root?.fitCameraToModel?.()
       this.cannot = ''
+      this.tellSample()
     } catch (error) {
       this.cannot = (error as Error).message
     }

package/client/modeller/refusals.ts

@@ -237,10 +237,56 @@ export function editRefusalOf(error: unknown, say: Say): string {
     documentLimitRefusalOf(error, say) ??
     sectionRefusalOf(error, say) ??
     slotLayoutRefusalOf(error, say) ??
+    dataMotionRefusalOf(error, say) ??
     say('figure.text.edit-refused', { code: codeOf(error) ?? '' })
   )
 }
 
+/**
+ * A data property, a connection, a motion group or a clip's tracks refused (ADR-0051 §2.2, §3.2), said with the ids and
+ * numbers the kernel gave. Nothing for any other refusal.
+ */
+export function dataMotionRefusalOf(error: unknown, say: Say): string | null {
+  const invalidId = detailsOf(error, 'data-id-invalid')
+  if (invalidId) return say('figure.text.data-id-invalid', { id: invalidId.id })
+  const twice = detailsOf(error, 'data-id-duplicate')
+  if (twice) return say('figure.text.data-id-duplicate', { id: twice.id })
+  const property = detailsOf(error, 'data-property-invalid')
+  if (property) return say('figure.text.data-property-invalid-' + property.field, { property: property.property })
+  const absent = detailsOf(error, 'data-property-absent')
+  if (absent) return say('figure.text.data-property-absent', { property: absent.property })
+  const target = detailsOf(error, 'data-target-absent')
+  if (target) return say('figure.text.data-target-absent-' + target.target, { id: target.id })
+  const writers = detailsOf(error, 'data-target-duplicate')
+  if (writers) return say('figure.text.data-target-duplicate', { a: writers.connections[0], b: writers.connections[1], id: writers.id })
+  const domain = detailsOf(error, 'data-transform-domain')
+  if (domain)
+    return say('figure.text.data-transform-' + domain.why, {
+      from: domain.from ?? '',
+      to: domain.to ?? '',
+      min: domain.min === undefined ? '' : numberOf(domain.min),
+      max: domain.max === undefined ? '' : numberOf(domain.max),
+      low: domain.within ? numberOf(domain.within[0]) : '',
+      high: domain.within ? numberOf(domain.within[1]) : '',
+      value: domain.value === undefined ? '' : String(domain.value)
+    })
+  const connected = detailsOf(error, 'data-property-connected')
+  if (connected) return say('figure.text.data-property-connected', { property: connected.property, connections: connected.connections.join(', ') })
+  const clipAbsent = detailsOf(error, 'motion-clip-absent')
+  if (clipAbsent) return say('figure.text.motion-clip-absent', { clip: clipAbsent.clip, group: clipAbsent.group })
+  const shared = detailsOf(error, 'motion-clip-shared')
+  if (shared) return say('figure.text.motion-clip-shared', { clip: shared.clip, group: shared.groups[0] })
+  const many = detailsOf(error, 'driver-writers')
+  if (many) return say('figure.text.driver-writers', { state: many.state, clips: many.clips.join(', ') })
+  const which = detailsOf(error, 'driver-clip-required')
+  if (which) return say('figure.text.driver-clip-required', { state: which.state, clips: which.clips.join(', ') })
+  const setting = detailsOf(error, 'motion-setting')
+  if (setting) return say('figure.text.motion-setting-' + setting.why, { group: setting.group, clip: setting.clip ?? '' })
+  const key = codeOf(error) === 'MOTION_GROUP' ? detailsOf(error, 'value-outside-range') : undefined
+  if (key) return say('figure.text.motion-key-outside-range', { input: key.input, value: numberOf(key.value), min: numberOf(key.min), max: numberOf(key.max) })
+  return null
+}
+
 /**
  * A value outside the range its input declares, with the range and the value given. The figure's own size is named by
  * its axis; any other input by its range only.

package/dist-client/modeller/clips.d.ts

@@ -20,8 +20,38 @@ export interface Clip {
     tracks: ClipTrack[];
 }
 export declare function clipsOf(asset: FigureAsset): Clip[];
-/** The controls no clip plays yet -- the ones a new track can take. One driver per control. */
-export declare function undrivenOf(asset: FigureAsset): string[];
+/**
+ * The controls a new track of `clip` can take (ADR-0051 §3.2): one the clip does not play yet, and that no clip plays
+ * outside the clip's motion group -- `group` for a clip not made yet. A clip in no group takes only a control no clip
+ * plays. Without a clip, the controls no clip plays at all.
+ */
+export declare function undrivenOf(asset: FigureAsset, clip?: string, group?: string): string[];
+/** A motion group as the panel shows it: its setting, and the clips it holds in the clips' order. */
+export interface ClipGroup {
+    id: string;
+    label: string;
+    clips: string[];
+    defaultClip: string;
+    transitionSeconds: number;
+}
+/** The figure's motion groups, and the clips in none -- the ones a group can take. */
+export declare function clipGroupsOf(asset: FigureAsset): {
+    groups: ClipGroup[];
+    free: string[];
+};
+/** A group id not yet taken: `motion`, then `motion-2`, `motion-3`, … An id is not made from a label a person types. */
+export declare function freeGroupIdOf(asset: FigureAsset): string;
+/** The edit that writes a group back with a change: one whole group, as the kernel takes it. */
+export declare const groupEdit: (group: ClipGroup, patch?: Partial<Omit<ClipGroup, "id">>) => {
+    kind: "set-motion-group";
+    group: {
+        id: string;
+        label: string;
+        clips: string[];
+        defaultClip: string;
+        transitionSeconds: number;
+    };
+};
 /** The pose a clip gives at a moment, as one batch of state changes -- one step of the history. */
 export declare function poseAt(asset: FigureAsset, clip: string, seconds: number): FigureInputChange[];
 /** A key added at a moment, replacing one already there; the keys stay in time order. */

package/dist-client/modeller/clips.js

@@ -21,11 +21,39 @@ export function clipsOf(asset) {
     }
     return [...clips.values()];
 }
-/** The controls no clip plays yet -- the ones a new track can take. One driver per control. */
-export function undrivenOf(asset) {
-    const driven = new Set((asset.drivers ?? []).map(d => d.state));
-    return asset.document.model.inputs.filter(i => i.role === 'state' && !driven.has(i.id)).map(i => i.id);
+/**
+ * The controls a new track of `clip` can take (ADR-0051 §3.2): one the clip does not play yet, and that no clip plays
+ * outside the clip's motion group -- `group` for a clip not made yet. A clip in no group takes only a control no clip
+ * plays. Without a clip, the controls no clip plays at all.
+ */
+export function undrivenOf(asset, clip = '', group) {
+    const groupOf = new Map((asset.motionGroups ?? []).flatMap(g => g.clips.map(c => [c, g.id])));
+    const mine = group ?? (clip ? groupOf.get(clip) : undefined);
+    const taken = (state) => (asset.drivers ?? []).some(d => d.state === state && (d.clip === clip || mine === undefined || groupOf.get(d.clip) !== mine));
+    return asset.document.model.inputs.filter(i => i.role === 'state' && !taken(i.id)).map(i => i.id);
 }
+/** The figure's motion groups, and the clips in none -- the ones a group can take. */
+export function clipGroupsOf(asset) {
+    const groups = (asset.motionGroups ?? []).map(g => ({ ...g, clips: [...g.clips] }));
+    const grouped = new Set(groups.flatMap(g => g.clips));
+    const free = [...new Set((asset.drivers ?? []).map(d => d.clip))].filter(c => !grouped.has(c));
+    return { groups, free };
+}
+/** A group id not yet taken: `motion`, then `motion-2`, `motion-3`, … An id is not made from a label a person types. */
+export function freeGroupIdOf(asset) {
+    const taken = new Set((asset.motionGroups ?? []).map(g => g.id));
+    if (!taken.has('motion'))
+        return 'motion';
+    let n = 2;
+    while (taken.has(`motion-${n}`))
+        n++;
+    return `motion-${n}`;
+}
+/** The edit that writes a group back with a change: one whole group, as the kernel takes it. */
+export const groupEdit = (group, patch = {}) => ({
+    kind: 'set-motion-group',
+    group: { id: group.id, label: patch.label ?? group.label, clips: patch.clips ?? group.clips, defaultClip: patch.defaultClip ?? group.defaultClip, transitionSeconds: patch.transitionSeconds ?? group.transitionSeconds }
+});
 /** The pose a clip gives at a moment, as one batch of state changes -- one step of the history. */
 export function poseAt(asset, clip, seconds) {
     const units = new Map(asset.document.model.inputs.map(i => [i.id, i.unit]));

package/dist-client/modeller/clips.js.map

@@ -1 +1 @@
-{"version":3,"file":"clips.js","sourceRoot":"","sources":["../../client/modeller/clips.ts"],"names":[],"mappings":"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","sourcesContent":["import { driverValue } from '@hatiolab/figure-model'\nimport type { FigureAsset, FigureDriver, FigureInputChange } from '@hatiolab/figure-model'\n\n/*\n * The figure's clips: controls played by keys over time, grouped into clips that each run on one\n * clock. Kept apart from the element so the reading is tested without a browser.\n */\nexport interface ClipKey {\n  seconds: number\n  value: number\n}\nexport interface ClipTrack {\n  state: string\n  label: string\n  unit: string\n  min: number\n  max: number\n  keys: ClipKey[]\n  interpolation: 'linear' | 'step'\n  loop: 'wrap' | 'hold'\n  accumulates: boolean\n}\nexport interface Clip {\n  name: string\n  duration: number\n  tracks: ClipTrack[]\n}\n\nconst round = (n: number) => Math.round(n * 1000) / 1000\n\nexport function clipsOf(asset: FigureAsset): Clip[] {\n  const inputs = new Map(asset.document.model.inputs.map(i => [i.id, i]))\n  const clips = new Map<string, Clip>()\n  for (const d of asset.drivers ?? []) {\n    const input = inputs.get(d.state)\n    const clip = clips.get(d.clip) ?? { name: d.clip, duration: d.time.duration, tracks: [] }\n    clip.tracks.push({\n      state: d.state,\n      label: asset.stateInputs?.[d.state]?.label ?? d.state,\n      unit: input?.unit ?? '',\n      min: input?.min ?? 0,\n      max: input?.max ?? 0,\n      keys: d.keys.map(k => ({ seconds: round(k.at * d.time.duration), value: k.value })),\n      interpolation: d.interpolation,\n      loop: d.loop,\n      accumulates: d.accumulates\n    })\n    clips.set(d.clip, clip)\n  }\n  return [...clips.values()]\n}\n\n/** The controls no clip plays yet -- the ones a new track can take. One driver per control. */\nexport function undrivenOf(asset: FigureAsset): string[] {\n  const driven = new Set((asset.drivers ?? []).map(d => d.state))\n  return asset.document.model.inputs.filter(i => i.role === 'state' && !driven.has(i.id)).map(i => i.id)\n}\n\n/** The pose a clip gives at a moment, as one batch of state changes -- one step of the history. */\nexport function poseAt(asset: FigureAsset, clip: string, seconds: number): FigureInputChange[] {\n  const units = new Map(asset.document.model.inputs.map(i => [i.id, i.unit]))\n  return (asset.drivers ?? [])\n    .filter((d: FigureDriver) => d.clip === clip)\n    .map(d => {\n      const unit = units.get(d.state)!\n      return { kind: 'set-state' as const, input: d.state, unit, value: driverValue(d, seconds, unit === 'deg' || unit === 'rad' ? unit : 'other') }\n    })\n}\n\n/** A key added at a moment, replacing one already there; the keys stay in time order. */\nexport function withKey(keys: readonly ClipKey[], key: ClipKey): ClipKey[] {\n  return [...keys.filter(k => k.seconds !== key.seconds), key].sort((a, b) => a.seconds - b.seconds)\n}\n\n/** A track's keys without one; a track keeps at least its two ends, as the format asks. */\nexport function withoutKey(keys: readonly ClipKey[], index: number): ClipKey[] | null {\n  if (keys.length <= 2 || index === 0) return null\n  return keys.filter((_, i) => i !== index)\n}\n\n/** The edit that writes a track back. */\nexport const trackEdit = (clip: Clip, track: ClipTrack, patch: Partial<Pick<ClipTrack, 'keys' | 'loop' | 'interpolation'>> = {}) => ({\n  kind: 'set-driver' as const,\n  state: track.state,\n  clip: clip.name,\n  keys: patch.keys ?? track.keys,\n  loop: patch.loop ?? track.loop,\n  interpolation: patch.interpolation ?? track.interpolation\n})\n"]}
+{"version":3,"file":"clips.js","sourceRoot":"","sources":["../../client/modeller/clips.ts"],"names":[],"mappings":"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","sourcesContent":["import { driverValue } from '@hatiolab/figure-model'\nimport type { FigureAsset, FigureDriver, FigureInputChange } from '@hatiolab/figure-model'\n\n/*\n * The figure's clips: controls played by keys over time, grouped into clips that each run on one\n * clock. Kept apart from the element so the reading is tested without a browser.\n */\nexport interface ClipKey {\n  seconds: number\n  value: number\n}\nexport interface ClipTrack {\n  state: string\n  label: string\n  unit: string\n  min: number\n  max: number\n  keys: ClipKey[]\n  interpolation: 'linear' | 'step'\n  loop: 'wrap' | 'hold'\n  accumulates: boolean\n}\nexport interface Clip {\n  name: string\n  duration: number\n  tracks: ClipTrack[]\n}\n\nconst round = (n: number) => Math.round(n * 1000) / 1000\n\nexport function clipsOf(asset: FigureAsset): Clip[] {\n  const inputs = new Map(asset.document.model.inputs.map(i => [i.id, i]))\n  const clips = new Map<string, Clip>()\n  for (const d of asset.drivers ?? []) {\n    const input = inputs.get(d.state)\n    const clip = clips.get(d.clip) ?? { name: d.clip, duration: d.time.duration, tracks: [] }\n    clip.tracks.push({\n      state: d.state,\n      label: asset.stateInputs?.[d.state]?.label ?? d.state,\n      unit: input?.unit ?? '',\n      min: input?.min ?? 0,\n      max: input?.max ?? 0,\n      keys: d.keys.map(k => ({ seconds: round(k.at * d.time.duration), value: k.value })),\n      interpolation: d.interpolation,\n      loop: d.loop,\n      accumulates: d.accumulates\n    })\n    clips.set(d.clip, clip)\n  }\n  return [...clips.values()]\n}\n\n/**\n * The controls a new track of `clip` can take (ADR-0051 §3.2): one the clip does not play yet, and that no clip plays\n * outside the clip's motion group -- `group` for a clip not made yet. A clip in no group takes only a control no clip\n * plays. Without a clip, the controls no clip plays at all.\n */\nexport function undrivenOf(asset: FigureAsset, clip = '', group?: string): string[] {\n  const groupOf = new Map((asset.motionGroups ?? []).flatMap(g => g.clips.map(c => [c, g.id] as const)))\n  const mine = group ?? (clip ? groupOf.get(clip) : undefined)\n  const taken = (state: string) =>\n    (asset.drivers ?? []).some(d => d.state === state && (d.clip === clip || mine === undefined || groupOf.get(d.clip) !== mine))\n  return asset.document.model.inputs.filter(i => i.role === 'state' && !taken(i.id)).map(i => i.id)\n}\n\n/** A motion group as the panel shows it: its setting, and the clips it holds in the clips' order. */\nexport interface ClipGroup {\n  id: string\n  label: string\n  clips: string[]\n  defaultClip: string\n  transitionSeconds: number\n}\n\n/** The figure's motion groups, and the clips in none -- the ones a group can take. */\nexport function clipGroupsOf(asset: FigureAsset): { groups: ClipGroup[]; free: string[] } {\n  const groups = (asset.motionGroups ?? []).map(g => ({ ...g, clips: [...g.clips] }))\n  const grouped = new Set(groups.flatMap(g => g.clips))\n  const free = [...new Set((asset.drivers ?? []).map(d => d.clip))].filter(c => !grouped.has(c))\n  return { groups, free }\n}\n\n/** A group id not yet taken: `motion`, then `motion-2`, `motion-3`, … An id is not made from a label a person types. */\nexport function freeGroupIdOf(asset: FigureAsset): string {\n  const taken = new Set((asset.motionGroups ?? []).map(g => g.id))\n  if (!taken.has('motion')) return 'motion'\n  let n = 2\n  while (taken.has(`motion-${n}`)) n++\n  return `motion-${n}`\n}\n\n/** The edit that writes a group back with a change: one whole group, as the kernel takes it. */\nexport const groupEdit = (group: ClipGroup, patch: Partial<Omit<ClipGroup, 'id'>> = {}) => ({\n  kind: 'set-motion-group' as const,\n  group: { id: group.id, label: patch.label ?? group.label, clips: patch.clips ?? group.clips, defaultClip: patch.defaultClip ?? group.defaultClip, transitionSeconds: patch.transitionSeconds ?? group.transitionSeconds }\n})\n\n/** The pose a clip gives at a moment, as one batch of state changes -- one step of the history. */\nexport function poseAt(asset: FigureAsset, clip: string, seconds: number): FigureInputChange[] {\n  const units = new Map(asset.document.model.inputs.map(i => [i.id, i.unit]))\n  return (asset.drivers ?? [])\n    .filter((d: FigureDriver) => d.clip === clip)\n    .map(d => {\n      const unit = units.get(d.state)!\n      return { kind: 'set-state' as const, input: d.state, unit, value: driverValue(d, seconds, unit === 'deg' || unit === 'rad' ? unit : 'other') }\n    })\n}\n\n/** A key added at a moment, replacing one already there; the keys stay in time order. */\nexport function withKey(keys: readonly ClipKey[], key: ClipKey): ClipKey[] {\n  return [...keys.filter(k => k.seconds !== key.seconds), key].sort((a, b) => a.seconds - b.seconds)\n}\n\n/** A track's keys without one; a track keeps at least its two ends, as the format asks. */\nexport function withoutKey(keys: readonly ClipKey[], index: number): ClipKey[] | null {\n  if (keys.length <= 2 || index === 0) return null\n  return keys.filter((_, i) => i !== index)\n}\n\n/** The edit that writes a track back. */\nexport const trackEdit = (clip: Clip, track: ClipTrack, patch: Partial<Pick<ClipTrack, 'keys' | 'loop' | 'interpolation'>> = {}) => ({\n  kind: 'set-driver' as const,\n  state: track.state,\n  clip: clip.name,\n  keys: patch.keys ?? track.keys,\n  loop: patch.loop ?? track.loop,\n  interpolation: patch.interpolation ?? track.interpolation\n})\n"]}

package/dist-client/modeller/data-interface.d.ts

@@ -0,0 +1,42 @@
+import type { FigureAsset, FigureDataConnection, FigureDataProperty, FigureDataResult, FigureDataTarget, FigureDataValue, FigureDataValueIssue } from '@hatiolab/figure-model';
+/** Something a connection can write, with what the screen shows of it. */
+export interface DataTargetChoice {
+    /** One string per target, for a select's value. */
+    key: string;
+    target: FigureDataTarget;
+    /** The control's label, the colour token, or the group's label. */
+    name: string;
+    unit?: string;
+    min?: number;
+    max?: number;
+}
+export declare const targetKeyOf: (t: FigureDataTarget) => string;
+/**
+ * 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.
+ */
+export declare function dataTargetsOf(asset: FigureAsset, kind: FigureDataProperty['kind']): DataTargetChoice[];
+/** The values a lookup has a case for: an enum's values, or both booleans. Nothing for a number. */
+export declare const domainOf: (property: FigureDataProperty) => FigureDataValue[];
+/** An id not taken among `taken`: `base`, then `base-2`, `base-3`, … made into the kernel's id shape. */
+export declare function freeDataIdOf(taken: Iterable<string>, base: string): string;
+/**
+ * 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.
+ */
+export declare function connectionDraftOf(asset: FigureAsset, property: FigureDataProperty, choice: DataTargetChoice): FigureDataConnection;
+/** What a property looks like when first made: a number 0 to 1, a boolean off, an enum of two values. */
+export declare function propertyDraftOf(asset: FigureAsset, label: string, kind: FigureDataProperty['kind']): FigureDataProperty;
+/** A value typed in a sample field, as the property takes it: a number, true or false, or the enum value. */
+export declare function sampleValueOf(property: FigureDataProperty, typed: string): FigureDataValue;
+/**
+ * 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.
+ */
+export declare function dataSampleOf(asset: FigureAsset, values: Record<string, FigureDataValue>): {
+    result: FigureDataResult;
+} | {
+    issues: FigureDataValueIssue[];
+};