@things-factory/figure-ui 10.1.223 → 10.1.224

package/dist-client/modeller/data-interface.js

@@ -1,6 +1,6 @@
 /*
- * 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
+ * The figure's data and what it moves (ADR-0051 §8, ADR-0166): what the data tab offers and shows -- one binding, its
+ * method as the field's kind allows (as it is, scaled, a code table, a range table). 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.
  */
@@ -10,16 +10,14 @@ export const behaviorKeyOf = (b) => 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}`;
+        : b.kind === 'pose'
+            ? `pose:${b.axis}`
+            : b.kind === 'items'
+                ? `items:${b.slot ?? ''}`
+                : `${b.kind}:${b.group}`;
 /**
- * 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.
+ * Everything a value binding may drive: each control, each colour, each motion group's clip, speed and pause, its
+ * position and heading, and -- when it has places -- the items in them.
  */
 export function behaviorsOf(asset) {
     const out = [];
@@ -32,12 +30,10 @@ export function behaviorsOf(asset) {
     for (const token of Object.keys(asset.palette))
         add({ kind: 'palette', token }, token);
     for (const group of asset.motionGroups ?? []) {
-        add({ kind: 'motion-clip', group: group.id }, group.label);
+        add({ kind: 'motion-clip', group: group.id }, group.label, { clips: [...group.clips] });
         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'])
         add({ kind: 'pose', axis, seconds: 1 }, axis, { unit: axis === 'heading' ? 'deg' : 'mm' });
     if (asset.document.capabilities.slotLayout || asset.document.capabilities.names?.includes('Holdable'))
@@ -45,22 +41,41 @@ export function behaviorsOf(asset) {
     return out;
 }
 const isValue = (n) => 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. */
+/**
+ * Whether a field of this kind drives the behavior as it is or scaled -- the choices a value binding offers for it. A
+ * value that picks a look per code is a table (ADR-0166 2).
+ */
 export function fitsField(node, choice) {
     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;
+        return node.kind === 'boolean';
+    if (choice.kind === 'palette')
+        return node.kind === 'text' && !!node.values?.every(v => /^#[0-9a-f]{6}$/i.test(v));
+    if (choice.kind === 'motion-clip') {
+        const clips = choice.behavior.kind === 'motion-clip' ? choice.clips : undefined;
+        return node.kind === 'text' && !!node.values && (!clips || node.values.every(v => clips.includes(v)));
+    }
+    return node.kind === 'number';
+}
+/**
+ * The methods a field allows (ADR-0166 2): a number as it is, scaled or by a range table; a text or true/false by a code
+ * table, or as it is where a behavior takes it so; a list as it is (its items). A new field is made by a table.
+ */
+export function methodsOf(node, choices) {
+    if (!node)
+        return ['code', 'ranges'];
+    const fitting = choices.some(c => fitsField(node, c));
+    if (node.kind === 'number')
+        return [...(fitting ? ['value', 'scale'] : []), 'ranges'];
+    if (node.kind === 'text' || node.kind === 'boolean')
+        return [...(fitting ? ['value'] : []), 'code'];
+    return fitting ? ['value'] : [];
 }
+/** The method a binding is shown by. */
+export const methodOf = (b) => (b.rule === 'table' ? (b.lookup === 'code' ? 'code' : 'ranges') : b.rule);
 /** An id not taken among `taken`: `base`, then `base-2`, `base-3`, … made into the kernel's id shape. */
 export function freeIdOf(taken, base) {
     const used = new Set(taken);
@@ -79,19 +94,15 @@ const TO_DEG = { 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) => (node.kind === 'boolean' ? [false, true] : node.kind === 'text' && node.values ? [...node.values] : []);
 /**
- * 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.
+ * A first value 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 -- or the method the author chose. The kernel says whether it holds.
  */
-export function bindingDraftOf(asset, accessor, node, choice) {
+export function bindingDraftOf(asset, accessor, node, choice, method) {
     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.input : choice.kind}`);
     const behavior = choice.behavior;
     const make = (rule, param) => ({ id, accessor, behavior, rule, ...(param ? { param } : {}) });
-    const domain = domainOf(node);
-    const caseMap = (each, fallback) => Object.fromEntries([...domain.map(v => [String(v), each(v)]), ...(domain.length ? [] : [['default', fallback]])]);
     if (behavior.kind === 'items') {
         if (node.kind !== 'list')
             return make('value');
@@ -103,53 +114,141 @@ export function bindingDraftOf(asset, accessor, node, choice) {
         const stack = pick(/stack/i, /level/i);
         return { id, accessor, behavior: { kind: 'items', ...(itemId ? { id: itemId } : {}), ...(type ? { type } : {}), ...(place ? { place } : {}), ...(stack ? { stack } : {}) }, rule: 'value' };
     }
-    if (behavior.kind === 'status')
+    if (node.kind !== 'number')
         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'))
+        if (method === 'value' || unit === (behavior.axis === 'heading' ? 'deg' : 'mm') || (method === undefined && !(unit in want)))
             return make('value');
-        return unit in want ? make('scale', { scale: want[unit], offset: 0 }) : make('value');
+        return make('scale', { scale: want[unit] ?? 1, offset: 0 });
     }
     /* 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) });
-        }
+    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 (method === 'value' || (method === undefined && 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) });
     }
-    const rest = behavior.kind === 'motion-speed' ? 1 : (asset.stateDefaults[behavior.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));
+    return method === 'scale' ? make('scale', { scale: 1, offset: 0 }) : make('value');
+}
+/* ---------------------------------------------------------------- tables (ADR-0166 3) */
+/** The first code a new code table names, and the next ones: `CODE`, `CODE2`, … */
+export function freeCodeOf(taken) {
+    if (!taken.includes('CODE'))
+        return 'CODE';
+    let n = 2;
+    while (taken.includes(`CODE${n}`))
+        n++;
+    return `CODE${n}`;
+}
+/** A legend role from a binding's id: lower case letters, digits and `-`. */
+export const legendRoleOf = (id) => id
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'legend';
+/**
+ * A first table on a field (ADR-0166 10): a row per value of a closed field, an open field's rows typed later, one
+ * interval over the whole of a number. A new field is made by the table (P2): a code table's a text whose values are the
+ * table's keys, starting with one code; a range table's a number. Returns the binding and, for a new field, the schema
+ * with it.
+ */
+export function tableDraftOf(asset, field, method, targets) {
+    const taken = (asset.dataInterface?.bindings ?? []).map(b => b.id);
+    const made = 'name' in field;
+    const name = made ? field.name : (field.path.replace(/\[\]/g, '').split('.').pop() ?? field.path);
+    const id = freeIdOf(taken, name.toLowerCase());
+    const node = made ? (method === 'code' ? { kind: 'text', values: ['CODE'] } : { kind: 'number' }) : field.node;
+    const accessor = made ? field.name : accessorOfRow(field.path);
+    const table = method === 'code' ? Object.fromEntries(domainOf(node).map(v => [String(v), {}])) : { [`${node.kind === 'number' ? (node.min ?? '') : ''}~`]: {} };
+    const binding = { id, accessor, rule: 'table', lookup: method, targets: tidyTargets(targets), table };
+    if (!made)
+        return { binding };
+    const schema = [...(asset.dataInterface?.schema ?? []), { name: field.name, ...node }];
+    return { binding, schema };
+}
+/** Targets with empty lists left out, as the kernel keeps them. */
+const tidyTargets = (t) => ({
+    ...(t.parts?.length ? { parts: [...t.parts] } : {}),
+    ...(t.inputs?.length ? { inputs: [...t.inputs] } : {}),
+    ...(t.group ? { group: t.group } : {})
+});
+/** A look with only the columns its targets take: a target taken away takes its columns with it. */
+function lookFor(look, t) {
+    const out = {};
+    if (t.parts?.length) {
+        if (look.color !== undefined)
+            out.color = look.color;
+        if (look.effect !== undefined)
+            out.effect = look.effect;
+    }
+    if (t.inputs?.length && look.values) {
+        const values = Object.fromEntries(Object.entries(look.values).filter(([id]) => t.inputs.includes(id)));
+        if (Object.keys(values).length)
+            out.values = values;
+    }
+    if (t.group) {
+        if (look.clip !== undefined)
+            out.clip = look.clip;
+        if (look.speed !== undefined)
+            out.speed = look.speed;
+        if (look.paused !== undefined)
+            out.paused = look.paused;
+    }
+    return out;
+}
+/** The table with these targets: each look keeps only the columns they take. */
+export function tableWithTargets(b, targets) {
+    const t = tidyTargets(targets);
+    return { ...b, targets: t, table: Object.fromEntries(Object.entries(b.table).map(([k, look]) => [k, lookFor(look, t)])) };
+}
+/** The table with one look set: the whole look given, a column left out cleared. */
+export const tableWithLook = (b, key, look) => ({ ...b, table: { ...b.table, [key]: lookFor(look, b.targets) } });
+/** The table's rows renamed, added or taken away, in order; `default` kept last. */
+export function tableWithKeys(b, rows) {
+    const d = b.table.default;
+    return { ...b, table: { ...Object.fromEntries(rows), ...(d !== undefined ? { default: d } : {}) } };
+}
+/**
+ * The columns a table's targets give its looks, as the row editor shows them: colour and effect for parts, a value per
+ * state input (its unit and range), the clip, speed and pause of the group.
+ */
+export function tableColumnsOf(asset, b) {
+    const out = [];
+    if (b.targets.parts?.length)
+        out.push({ kind: 'color' }, { kind: 'effect' });
+    for (const id of b.targets.inputs ?? []) {
+        const input = asset.document.model.inputs.find(i => i.id === id);
+        out.push({ kind: 'value', id, label: asset.stateInputs?.[id]?.label ?? id, unit: input?.unit, min: input?.min, max: input?.max });
+    }
+    if (b.targets.group) {
+        const group = (asset.motionGroups ?? []).find(g => g.id === b.targets.group);
+        out.push({ kind: 'clip', clips: group?.clips ?? [] }, { kind: 'speed' }, { kind: 'paused' });
+    }
+    return out;
+}
+/** The state inputs a table may give values to: each control, with its label. */
+export const stateInputsOf = (asset) => asset.document.model.inputs.filter(i => i.role === 'state').map(i => ({ id: i.id, label: asset.stateInputs?.[i.id]?.label ?? i.id }));
+/**
+ * A code table's field follows its keys (ADR-0166 risk 3): when the field is a closed text, its values are the table's
+ * codes. The schema with the field so, or undefined when the field is open or already so.
+ */
+export function schemaFollowingCodes(asset, b, codes) {
+    const schema = asset.dataInterface?.schema ?? [];
+    const path = b.accessor.replace(/\[\d+\]/g, '[]');
+    const field = fieldAt(schema, path);
+    if (field?.kind !== 'text' || !field.values || !codes.length)
+        return undefined;
+    if (field.values.length === codes.length && field.values.every((v, i) => v === codes[i]))
+        return undefined;
+    const next = { ...field, values: [...codes] };
+    if (next.default !== undefined && !codes.includes(next.default))
+        delete next.default;
+    return schemaWithFieldReplaced(schema, path, next);
 }
 const round = (v) => Math.round(v * 1e6) / 1e6;
 /* ---------------------------------------------------------------- the schema as a tree */
@@ -225,12 +324,19 @@ export const schemaRowsOf = (asset) => (asset.dataInterface ? figureDataRows(ass
 /* ---------------------------------------------------------------- reading a sample */
 /**
  * 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.
+ * inputs): what it moves, or why it is refused, each value's reason; each table's look and where it came from, and what
+ * of a legend was left out. `legends`: sample legends by role, as a scene's legend of the role's name would be.
  */
-export function sampleOf(asset, sample) {
+export function sampleOf(asset, sample, legends = {}) {
     const inputs = new FigureInputs(asset);
+    inputs.setThemes({ legends: Object.fromEntries(Object.entries(legends).map(([role, legend]) => [role, { legend, source: 'domain', name: role }])) });
     const taken = inputs.setData(sample);
-    return { issues: taken.accepted ? [] : (taken.issues[0]?.issues ?? []), result: inputs.data };
+    return {
+        issues: taken.accepted ? [] : (taken.issues[0]?.issues ?? []),
+        result: inputs.data,
+        uses: inputs.tableUses,
+        notes: inputs.diagnostics().filter(i => i.severity === 'note')
+    };
 }
 /** 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) => schemaRowsOf(asset).filter(r => isValue(r.node) && r.bindings.length > 0 && !r.path.includes('[]'));
@@ -242,14 +348,8 @@ export function typedValueOf(node, typed) {
         return typed === 'true';
     return typed;
 }
-/** The parts a status port may show on: the parts the figure's appearance names. */
+/** The parts a table may show on: the parts the figure's appearance names. */
 export const partsOf = (asset) => [...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, label) {
-    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) => parseFigureAccessor(accessor) !== null;
 /**
@@ -259,6 +359,17 @@ export const accessorTaken = (accessor) => parseFigureAccessor(accessor) !== nul
 export function motionWrittenByData(asset) {
     const out = {};
     for (const b of asset.dataInterface?.bindings ?? []) {
+        if (b.rule === 'table') {
+            if (!b.targets.group)
+                continue;
+            const one = (out[b.targets.group] ??= { clip: false, speed: false });
+            const looks = Object.values(b.table);
+            if (looks.some(l => l.clip !== undefined))
+                one.clip = true;
+            if (looks.some(l => l.speed !== undefined))
+                one.speed = true;
+            continue;
+        }
         if (b.behavior.kind !== 'motion-clip' && b.behavior.kind !== 'motion-speed')
             continue;
         const one = (out[b.behavior.group] ??= { clip: false, speed: false });
@@ -287,7 +398,7 @@ export function endlessJointsOf(asset) {
 /**
  * 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
+ * and the bindings -- on, by a table, to the group's pause, speed to its speed, direction, by a table, 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
@@ -338,7 +449,7 @@ export function rotationStepsOf(asset, c) {
         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 } }));
+        steps.push(bind(`${group}-on`, { accessor: c.on, rule: 'table', lookup: 'code', targets: { group }, table: { true: { paused: false }, false: { paused: 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) {
@@ -346,9 +457,10 @@ export function rotationStepsOf(asset, c) {
         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 }) }
+            rule: 'table',
+            lookup: 'code',
+            targets: { group },
+            table: { [c.direction.forward]: { clip: forward }, [c.direction.reverse]: { clip: reverse }, ...(covered ? {} : { default: { clip: forward } }) }
         }));
     }
     return steps;