@things-factory/figure-ui 10.1.162 → 10.1.163

package/client/modeller/figure-preview.ts

@@ -3,12 +3,12 @@ import { customElement, property, query, state } from 'lit/decorators.js'
 
 import { i18next, localize } from '@operato/i18n'
 import { compileFigureAsset } from '@hatiolab/figure-model'
-import type { FigureAsset, FigureDataProperty, FigureDataValue } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureDataRow, FigureDataValue } from '@hatiolab/figure-model'
 import { create, registerFigure, unregisterFigure } from '@hatiolab/things-scene'
 
 import { DEFAULT_VIEW, previewBoardDepth, sceneLook, WORKBENCH, type ViewSettings } from '@things-factory/figure-viewer/dist-client/figure-view.js'
 import { dialShape } from './angle-dial.js'
-import { domainOf, motionWrittenByData, sampleValueOf } from './data-interface.js'
+import { domainOf, motionWrittenByData, typedValueOf, valueRowsOf } from './data-interface.js'
 import { derivedOf, type FigureRevision } from './revision.js'
 import { authoredSizeOf, PREVIEW_FACTOR, PREVIEW_WAYS, previewClampsOf, previewInstances, previewTypeOf, setupPartOf } from '@things-factory/figure-viewer/dist-client/preview-model.js'
 
@@ -209,10 +209,10 @@ export class FigurePreview extends localize(i18next)(LitElement) {
   @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 given here, as a board's saved `figureValues`: what moves a group whose clip or speed the data writes. */
+  /** Data values given here by accessor, as a board's saved `figureValues`: what moves a group whose clip or speed the data writes. */
   @state() private valuing: Record<string, FigureDataValue> = {}
-  /** 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
+  /** Data tried in the data tab: the preview's figures take it as their \`data\`, as a board's data source gives it; null when none is. */
+  @property({ attribute: false }) sample: unknown = 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 = ''
@@ -264,7 +264,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 + (asset?.motionGroups?.length ?? 0) + (asset?.dataInterface?.properties.length ?? 0) ? this.renderDrivers(asset!, controls, clips) : nothing}</div>`}`
+            ${controls.length + clips.length + (asset?.motionGroups?.length ?? 0) + (asset ? valueRowsOf(asset).length : 0) ? this.renderDrivers(asset!, controls, clips) : nothing}</div>`}`
   }
 
   private renderDrivers(asset: FigureAsset, controls: FigureAsset['document']['model']['inputs'], clips: string[]) {
@@ -306,7 +306,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
           <output>${value.toFixed(2)}</output>
         </label>`
       })}
-      ${(asset.dataInterface?.properties ?? []).map(property => this.renderDataValue(property))}
+      ${valueRowsOf(asset).map(row => this.renderDataValue(row))}
       ${(asset.motionGroups ?? []).map(group => {
         const playing = this.moving[group.id] ?? { clip: group.defaultClip, speed: 0 }
         /* A field the data writes wins over the group's own setting, here as on a board: it is moved by the data values above. */
@@ -331,28 +331,44 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     </div>`
   }
 
-  /** A data property's value, as the board's data values give it: a number on a slider, a boolean or an enum chosen. */
-  private renderDataValue(property: FigureDataProperty) {
-    const value = this.valuing[property.id] ?? property.default
-    if (property.kind === 'number') {
-      const step = Math.max((property.max - property.min) / 100, 0.01)
+  /** A value the data's bindings read, as the board's saved values give it: a number on a slider when it has a range, a choice when it is closed. */
+  private renderDataValue(row: FigureDataRow) {
+    const node = row.node
+    const label = row.label ?? row.path
+    const fallback = 'default' in node ? node.default : undefined
+    const value = this.valuing[row.path] ?? fallback
+    if (node.kind === 'number') {
+      const ranged = node.min !== undefined && node.max !== undefined && node.max > node.min
       return html`<label>
-        <span>${property.label} <span drive>${property.unit}</span></span>
+        <span>${label} <span drive>${node.unit ?? ''}</span></span>
         <span></span>
-        <input type="range" min=${property.min} max=${property.max} step=${step} .value=${String(value)} @input=${(e: Event) => this.value(property, (e.target as HTMLInputElement).value)} />
-        <output>${Number(value).toFixed(2)}</output>
+        ${ranged
+          ? html`<input type="range" min=${node.min!} max=${node.max!} step=${Math.max((node.max! - node.min!) / 100, 0.01)} .value=${String(value ?? node.min)} @input=${(e: Event) => this.value(row, (e.target as HTMLInputElement).value)} />
+              <output>${value === undefined ? '' : Number(value).toFixed(2)}</output>`
+          : html`<input type="number" step="any" .value=${value === undefined ? '' : String(value)} @change=${(e: Event) => this.value(row, (e.target as HTMLInputElement).value)} />
+              <span></span>`}
       </label>`
     }
+    const domain = domainOf(node)
+    if (!domain.length)
+      return html`<label>
+        <span>${label}</span>
+        <input aria-label=${label} .value=${value === undefined ? '' : String(value)} @change=${(e: Event) => this.value(row, (e.target as HTMLInputElement).value)} />
+      </label>`
     return html`<label>
-      <span>${property.label}</span>
-      <select aria-label=${property.label} @change=${(e: Event) => this.value(property, (e.target as HTMLSelectElement).value)}>
-        ${domainOf(property).map(v => html`<option value=${String(v)} ?selected=${v === value}>${typeof v === 'boolean' ? i18next.t(v ? 'figure.label.data-true' : 'figure.label.data-false') : v}</option>`)}
+      <span>${label}</span>
+      <select aria-label=${label} @change=${(e: Event) => this.value(row, (e.target as HTMLSelectElement).value)}>
+        ${domain.map(v => html`<option value=${String(v)} ?selected=${v === value}>${typeof v === 'boolean' ? i18next.t(v ? 'figure.label.data-true' : 'figure.label.data-false') : v}</option>`)}
       </select>
     </label>`
   }
 
-  private value(property: FigureDataProperty, typed: string) {
-    this.valuing = { ...this.valuing, [property.id]: sampleValueOf(property, typed) }
+  private value(row: FigureDataRow, typed: string) {
+    const value = typedValueOf(row.node, typed)
+    const next = { ...this.valuing }
+    if (typeof value === 'number' && Number.isNaN(value)) delete next[row.path]
+    else next[row.path] = value
+    this.valuing = next
     this.tellInstances('figureValues', this.valuing)
   }
 
@@ -387,23 +403,23 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     this.giving = {}
   }
 
-  private tellInstances(key: 'clips' | 'parameters' | 'motion' | 'figureData' | 'figureValues', 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)
-    }
+  private tellInstances(key: 'clips' | 'parameters' | 'motion' | 'figureValues', values: Record<string, unknown> | null) {
+    for (const component of this.scene?.root?.components ?? []) component.set?.(key, values === null ? null : { ...values })
+  }
+
+  /** The tried data to the figures standing now, as their \`data\`: the preview's board is not saved. */
+  private tellData(data: unknown) {
+    for (const component of this.scene?.root?.components ?? []) component.set?.('data', data === null || data === undefined ? null : structuredClone(data))
   }
 
 
-  /** The data sample to the figures standing now: a live snapshot, transient on each, never saved with the board. */
+  /** The data sample to the figures standing now. */
   private tellSample() {
-    if (this.sample) this.tellInstances('figureData', { ...this.sample })
+    if (this.sample !== null && this.sample !== undefined) this.tellData(this.sample)
   }
 
   willUpdate(changed: Map<string, unknown>) {
-    if (changed.has('sample') && this.scene) this.tellInstances('figureData', this.sample ? { ...this.sample } : null)
+    if (changed.has('sample') && this.scene) this.tellData(this.sample)
     if (!this.hasUpdated) return
     if (!this.active) {
       this.stale = true

package/client/modeller/refusals.ts

@@ -243,25 +243,27 @@ export function editRefusalOf(error: unknown, say: Say): string {
 }
 
 /**
- * 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.
+ * A data field, a binding, a status port, a motion group or a clip's tracks refused (ADR-0051 §8, §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')
+  const field = detailsOf(error, 'data-field-invalid')
+  if (field) return say('figure.text.data-field-invalid-' + field.what, {})
+  const fieldTwice = detailsOf(error, 'data-field-duplicate')
+  if (fieldTwice) return say('figure.text.data-field-duplicate', { name: fieldTwice.name })
+  const accessor = detailsOf(error, 'data-accessor-invalid')
+  if (accessor) return say('figure.text.data-accessor-invalid-' + accessor.why, { accessor: accessor.accessor })
+  const behavior = detailsOf(error, 'data-behavior-absent')
+  if (behavior) return say('figure.text.data-behavior-absent-' + behavior.behavior, { id: behavior.id })
+  const writers = detailsOf(error, 'data-behavior-duplicate')
+  if (writers) return say('figure.text.data-behavior-duplicate', { a: writers.bindings[0], b: writers.bindings[1], id: writers.id })
+  const domain = detailsOf(error, 'data-rule-domain')
   if (domain)
-    return say('figure.text.data-transform-' + domain.why, {
+    return say('figure.text.data-rule-' + domain.why, {
       from: domain.from ?? '',
       to: domain.to ?? '',
       min: domain.min === undefined ? '' : numberOf(domain.min),
@@ -270,8 +272,10 @@ export function dataMotionRefusalOf(error: unknown, say: Say): string | null {
       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 port = detailsOf(error, 'data-port-invalid')
+  if (port) return say('figure.text.data-port-invalid-' + port.what, { port: port.port, id: port.id ?? '' })
+  const bound = detailsOf(error, 'data-port-bound')
+  if (bound) return say('figure.text.data-port-bound', { port: bound.port, bindings: bound.bindings.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')

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

@@ -1,49 +1,72 @@
-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. */
+import type { FigureAsset, FigureDataBehavior, FigureDataBinding, FigureDataField, FigureDataNode, FigureDataRow, FigureDataValue, FigureDataValueIssue, FigureStatusPort } from '@hatiolab/figure-model';
+import { type FigureDataResult } from '@hatiolab/things-scene';
+/** 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 declare const targetKeyOf: (t: FigureDataTarget) => string;
+export declare const behaviorKeyOf: (b: FigureDataBehavior) => 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.
+ * 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 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[];
+export declare function behaviorsOf(asset: FigureAsset): BehaviorChoice[];
+/** Whether a field of this kind can drive the behavior, by some rule -- the choices offered for it. */
+export declare function fitsField(node: FigureDataNode, choice: BehaviorChoice): boolean;
 /** 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;
+export declare function freeIdOf(taken: Iterable<string>, base: string): string;
+/** The values a closed field takes: a closed text's values, both booleans. Empty when open. */
+export declare const domainOf: (node: FigureDataNode) => FigureDataValue[];
 /**
- * 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 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;
+export declare function bindingDraftOf(asset: FigureAsset, accessor: string, node: FigureDataNode, choice: BehaviorChoice): FigureDataBinding;
+/** A row's path (`L[].F`) as the accessor a value binding reads (`L[0].F`): the first element of each list. */
+export declare const accessorOfRow: (path: string) => string;
+/** The field at a row's path, or undefined. */
+export declare function fieldAt(schema: readonly FigureDataField[], path: string): FigureDataField | undefined;
+/** The schema with a field added under a path ('' for the top): a copy, the given one left as it is. */
+export declare function schemaWithField(schema: readonly FigureDataField[], under: string, field: FigureDataField): FigureDataField[];
+/** The schema with the field at a path replaced (its name kept unless the new one says another). */
+export declare function schemaWithFieldReplaced(schema: readonly FigureDataField[], path: string, field: FigureDataField): FigureDataField[];
+/** The schema without the field at a path. */
+export declare function schemaWithoutField(schema: readonly FigureDataField[], path: string): FigureDataField[];
+/** A field of another kind, its name, label and json flag kept, the rest started fresh. */
+export declare function fieldOfKind(field: FigureDataField, kind: FigureDataNode['kind']): FigureDataField;
+/** The rows of the schema, each with the bindings that read it (figure-model's view). */
+export declare const schemaRowsOf: (asset: FigureAsset) => FigureDataRow[];
 /**
- * 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 declare function dataSampleOf(asset: FigureAsset, values: Record<string, FigureDataValue>): {
-    result: FigureDataResult;
-} | {
+export declare function sampleOf(asset: FigureAsset, sample: unknown): {
     issues: FigureDataValueIssue[];
+    result: FigureDataResult;
 };
+/** 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 declare const valueRowsOf: (asset: FigureAsset) => FigureDataRow[];
+/** 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 declare function typedValueOf(node: FigureDataNode, typed: string): FigureDataValue;
+/** The parts a status port may show on: the parts the figure's appearance names. */
+export declare const partsOf: (asset: FigureAsset) => string[];
+/** A first status port: the label as given, on the first colour token, no part yet. The kernel says whether it holds. */
+export declare function portDraftOf(asset: FigureAsset, label: string): FigureStatusPort;
+/** Whether a text is an accessor the kernel takes. */
+export declare const accessorTaken: (accessor: string) => boolean;
 /**
- * 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 declare function motionWrittenByData(asset: FigureAsset): Record<string, {
     clip: boolean;