@things-factory/figure-ui 10.1.223 → 10.1.225

package/client/modeller/canvas.ts

@@ -7,7 +7,7 @@ import type { FigureRenderPart } from './renderer.js'
 import { DEFAULT_VIEW, sceneLook, WORKBENCH, type ViewSettings } from '@things-factory/figure-viewer/dist-client/figure-view.js'
 import { boardFor, changedKeys, componentOf, gizmoResultOf, needsRefit, type Board } from './stage-model.js'
 import { JOINT_FAN } from './joint-fan.js'
-import { SLOT_MARK } from './slot-layout-host.js'
+import { SLOT_MARK, SLOT_MARK_CHOSEN } from './slot-layout-host.js'
 import { PREVIEW, TARGET_FACE } from './command-preview.js'
 import { ownerOf } from './fields.js'
 
@@ -256,7 +256,7 @@ export class FigureCanvas extends LitElement {
     /* The fan in the accent colour, translucent; `capturable: false` keeps clicks, the marquee and the gizmo off it. */
     const fan = this.fan ? componentOf(this.fan, { ...this.palette, [JOINT_FAN]: this.palette['palette.accent'] ?? FAN_COLOUR }, this.board!) : null
     const accent = this.palette['palette.accent'] ?? FAN_COLOUR
-    const slots = this.marks.map(part => componentOf(part, { ...this.palette, [SLOT_MARK]: this.palette['palette.secondary'] ?? accent }, this.board!))
+    const slots = this.marks.map(part => componentOf(part, { ...this.palette, [SLOT_MARK]: this.palette['palette.secondary'] ?? accent, [SLOT_MARK_CHOSEN]: this.palette['palette.primary'] ?? accent }, this.board!))
     const shown = [...(fan ? [fan] : []), ...slots, ...this.ghost.map(part => componentOf(part, { ...this.palette, [PREVIEW]: accent, [TARGET_FACE]: accent }, this.board!)), ...(this.highlight ? [componentOf(this.highlight, { ...this.palette, [TARGET_FACE]: accent }, this.board!)] : [])]
     return [...parts, ...shown.filter((c): c is Record<string, unknown> => !!c).map(c => ({ ...c, capturable: false, locked: true }))]
   }

package/client/modeller/consumer-capabilities.ts

@@ -0,0 +1,66 @@
+/*
+ * A product's capabilities in the modeller (ADR-0167 3, 9, 12): the descriptors registered with the scene, which ones
+ * the figure wears, what each still needs, and its settings on the asset as its descriptor draws them -- parts picked,
+ * an input and a value per fixed key. The descriptor's own check says what the settings lack. Kept apart from the
+ * element so it is tested without a browser.
+ */
+import { isFigureConsumerCapability } from '@hatiolab/figure-model'
+import type { FigureAsset } from '@hatiolab/figure-model'
+import { figureCapabilityDescriptors, type FigureCapabilityDescriptor, type FigureCapabilitySetting } from '@hatiolab/things-scene'
+
+/** The products' capabilities this modeller knows: registered descriptors with a namespaced name. */
+export const consumerDescriptors = (): FigureCapabilityDescriptor[] => figureCapabilityDescriptors().filter(d => isFigureConsumerCapability(d.name))
+
+/** The products' capabilities the figure declares that this modeller has no descriptor for: kept, said, removable. */
+export function unknownConsumerNames(asset: FigureAsset): string[] {
+  const known = new Set(consumerDescriptors().map(d => d.name))
+  return (asset.document.capabilities.names ?? []).filter(n => isFigureConsumerCapability(n) && !known.has(n))
+}
+
+/** What a capability still needs on this figure: a shared or a product's name not declared, or the item mark. */
+export function needsMissing(descriptor: FigureCapabilityDescriptor, asset: FigureAsset): string[] {
+  const names = new Set(asset.document.capabilities.names ?? [])
+  const has = (need: string) => (need === 'item' ? !!asset.item : names.has(need))
+  return descriptor.needs.filter(need => (Array.isArray(need) ? !need.some(has) : !has(need as string))).map(need => (Array.isArray(need) ? need.join(' | ') : (need as string)))
+}
+
+/** The names with a product's capability put on or taken off; the shared ones as they are. */
+export function namesWith(asset: FigureAsset, name: string, on: boolean): string[] {
+  const names = asset.document.capabilities.names ?? []
+  return on ? [...new Set([...names, name])] : names.filter(n => n !== name)
+}
+
+/** A capability's settings on the asset, or an empty object. */
+export const settingsOf = (asset: FigureAsset, name: string): Record<string, unknown> => ({ ...(asset.document.capabilities.extensions?.[name] ?? {}) })
+
+/** The parts a parts setting holds. */
+export function partsAt(settings: Record<string, unknown>, key: string): string[] {
+  const v = settings[key]
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
+}
+
+/** The settings with a parts setting changed; none is left out. */
+export function withParts(settings: Record<string, unknown>, key: string, parts: string[]): Record<string, unknown> {
+  const next = { ...settings }
+  if (parts.length) next[key] = [...parts]
+  else delete next[key]
+  return next
+}
+
+/** An input table as held: the input, and a value per fixed key (the descriptor's start where none is given yet). */
+export function inputTableAt(settings: Record<string, unknown>, setting: Extract<FigureCapabilitySetting, { kind: 'input-table' }>): { input?: string; values: Record<string, number> } {
+  const v = settings[setting.key] as { input?: unknown; values?: Record<string, unknown> } | undefined
+  const values = Object.fromEntries(setting.keys.map(k => [k, typeof v?.values?.[k] === 'number' ? (v.values[k] as number) : setting.start[k]!]))
+  return { ...(typeof v?.input === 'string' ? { input: v.input } : {}), values }
+}
+
+/** The settings with an input table changed: an input chosen writes every fixed key's value; none takes the table away. */
+export function withInputTable(settings: Record<string, unknown>, setting: Extract<FigureCapabilitySetting, { kind: 'input-table' }>, input: string | undefined, values: Record<string, number>): Record<string, unknown> {
+  const next = { ...settings }
+  if (input) next[setting.key] = { input, values: Object.fromEntries(setting.keys.map(k => [k, values[k] ?? setting.start[k]!])) }
+  else delete next[setting.key]
+  return next
+}
+
+/** What the capability's own check says of the settings now; nothing when it has no check. */
+export const settingsIssues = (descriptor: FigureCapabilityDescriptor, asset: FigureAsset): string[] => descriptor.check?.(asset.document.capabilities.extensions?.[descriptor.name], asset) ?? []

package/client/modeller/data-interface.ts

@@ -1,12 +1,26 @@
 /*
- * 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.
  */
 import { FIGURE_PART_ID, FIGURE_MOTION_SPEED_MAX, FigureContractError, figureAxesOf, figureDataRows, motionStateIdOf, 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'
+import type {
+  FigureAsset,
+  FigureDataBehavior,
+  FigureDataBinding,
+  FigureDataField,
+  FigureDataNode,
+  FigureDataRow,
+  FigureDataTableBinding,
+  FigureDataTableEntry,
+  FigureDataTargets,
+  FigureDataValue,
+  FigureDataValueBinding,
+  FigureDataValueIssue,
+  FigureProposalStep
+} from '@hatiolab/figure-model'
+import { FigureInputs, type FigureDataResult, type FigureRuntimeIssue, type FigureTableUse } from '@hatiolab/things-scene'
 
 /** Something a binding can move, with what the screen shows of it. */
 export interface BehaviorChoice {
@@ -15,11 +29,13 @@ export interface BehaviorChoice {
   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. */
+  /** The control's label, the colour token, the group's label, the axis. */
   name: string
   unit?: string
   min?: number
   max?: number
+  /** A motion group's clips. */
+  clips?: string[]
 }
 
 export const behaviorKeyOf = (b: FigureDataBehavior): string =>
@@ -27,17 +43,15 @@ export const behaviorKeyOf = (b: FigureDataBehavior): string =>
     ? `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: FigureAsset): BehaviorChoice[] {
   const out: BehaviorChoice[] = []
@@ -48,11 +62,10 @@ export function behaviorsOf(asset: FigureAsset): BehaviorChoice[] {
   }
   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'] 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
@@ -60,17 +73,40 @@ export function behaviorsOf(asset: FigureAsset): BehaviorChoice[] {
 
 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. */
+/**
+ * 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: 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
+  if (choice.kind === 'motion-paused') 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'
+}
+
+/** How a binding turns a value into what the figure shows (ADR-0166 1): the screen's four methods. */
+export type DataMethod = 'value' | 'scale' | 'code' | 'ranges'
+
+/**
+ * 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: FigureDataNode | null, choices: BehaviorChoice[]): DataMethod[] {
+  if (!node) return ['code', 'ranges']
+  const fitting = choices.some(c => fitsField(node, c))
+  if (node.kind === 'number') return [...(fitting ? (['value', 'scale'] as const) : []), 'ranges']
+  if (node.kind === 'text' || node.kind === 'boolean') return [...(fitting ? (['value'] as const) : []), 'code']
+  return fitting ? ['value'] : []
 }
 
+/** The method a binding is shown by. */
+export const methodOf = (b: FigureDataBinding): DataMethod => (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: Iterable<string>, base: string): string {
   const used = new Set(taken)
@@ -90,19 +126,15 @@ const TO_DEG: Record<string, number> = { deg: 1, rad: 180 / Math.PI }
 export const domainOf = (node: FigureDataNode): FigureDataValue[] => (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: FigureAsset, accessor: string, node: FigureDataNode, choice: BehaviorChoice): FigureDataBinding {
+export function bindingDraftOf(asset: FigureAsset, accessor: string, node: FigureDataNode, choice: BehaviorChoice, method?: 'value' | 'scale'): FigureDataValueBinding {
   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])])
+  const make = (rule: 'value' | 'scale', param?: FigureDataValueBinding['param']): FigureDataValueBinding => ({ id, accessor, behavior, rule, ...(param ? { param } : {}) })
 
   if (behavior.kind === 'items') {
     if (node.kind !== 'list') return make('value')
@@ -114,47 +146,152 @@ export function bindingDraftOf(asset: FigureAsset, accessor: string, node: Figur
     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') 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 (node.kind !== 'number') return make('value')
   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')
+    if (method === 'value' || unit === (behavior.axis === 'heading' ? 'deg' : 'mm') || (method === undefined && !(unit in want))) return 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) })
-    }
-    return make('value')
+  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 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))
+  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: string[]): string {
+  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: string): string =>
+  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: FigureAsset,
+  field: { path: string; node: FigureDataNode } | { name: string },
+  method: 'code' | 'ranges',
+  targets: FigureDataTargets
+): { binding: FigureDataTableBinding; schema?: FigureDataField[] } {
+  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: FigureDataNode = made ? (method === 'code' ? { kind: 'text', values: ['CODE'] } : { kind: 'number' }) : field.node
+  const accessor = made ? field.name : accessorOfRow(field.path)
+  const table: Record<string, FigureDataTableEntry> =
+    method === 'code' ? Object.fromEntries(domainOf(node).map(v => [String(v), {}])) : { [`${node.kind === 'number' ? (node.min ?? '') : ''}~`]: {} }
+  const binding: FigureDataTableBinding = { id, accessor, rule: 'table', lookup: method, targets: tidyTargets(targets), table }
+  if (!made) return { binding }
+  const schema = [...(asset.dataInterface?.schema ?? []), { name: field.name, ...node } as FigureDataField]
+  return { binding, schema }
+}
+
+/** Targets with empty lists left out, as the kernel keeps them. */
+const tidyTargets = (t: FigureDataTargets): FigureDataTargets => ({
+  ...(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: FigureDataTableEntry, t: FigureDataTargets): FigureDataTableEntry {
+  const out: FigureDataTableEntry = {}
+  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: FigureDataTableBinding, targets: FigureDataTargets): FigureDataTableBinding {
+  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: FigureDataTableBinding, key: string, look: FigureDataTableEntry): FigureDataTableBinding => ({ ...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: FigureDataTableBinding, rows: Array<[string, FigureDataTableEntry]>): FigureDataTableBinding {
+  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: FigureAsset, b: FigureDataTableBinding): TableColumn[] {
+  const out: TableColumn[] = []
+  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
+}
+export type TableColumn =
+  | { kind: 'color' | 'effect' | 'speed' | 'paused' }
+  | { kind: 'value'; id: string; label: string; unit?: string; min?: number; max?: number }
+  | { kind: 'clip'; clips: string[] }
+
+/** The state inputs a table may give values to: each control, with its label. */
+export const stateInputsOf = (asset: FigureAsset): Array<{ id: string; label: string }> =>
+  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: FigureAsset, b: FigureDataTableBinding, codes: string[]): FigureDataField[] | undefined {
+  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] } as FigureDataField & { default?: string }
+  if (next.default !== undefined && !codes.includes(next.default)) delete next.default
+  return schemaWithFieldReplaced(schema, path, next)
+}
+
 const round = (v: number) => Math.round(v * 1e6) / 1e6
 
 /* ---------------------------------------------------------------- the schema as a tree */
@@ -231,12 +368,23 @@ export const schemaRowsOf = (asset: FigureAsset): FigureDataRow[] => (asset.data
 
 /**
  * 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: FigureAsset, sample: unknown): { issues: FigureDataValueIssue[]; result: FigureDataResult } {
+export function sampleOf(
+  asset: FigureAsset,
+  sample: unknown,
+  legends: Record<string, unknown> = {}
+): { issues: FigureDataValueIssue[]; result: FigureDataResult; uses: Readonly<Record<string, FigureTableUse>>; notes: FigureRuntimeIssue[] } {
   const inputs = new FigureInputs(asset)
+  inputs.setThemes({ legends: Object.fromEntries(Object.entries(legends).map(([role, legend]) => [role, { legend, source: 'domain' as const, 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. */
@@ -249,16 +397,9 @@ export function typedValueOf(node: FigureDataNode, typed: string): FigureDataVal
   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: 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
 
@@ -269,6 +410,14 @@ export const accessorTaken = (accessor: string): boolean => parseFigureAccessor(
 export function motionWrittenByData(asset: FigureAsset): Record<string, { clip: boolean; speed: boolean }> {
   const out: Record<string, { clip: boolean; speed: boolean }> = {}
   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 })
     if (b.behavior.kind === 'motion-clip') one.clip = true
@@ -315,7 +464,7 @@ export interface RotationChoice {
 /**
  * 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
@@ -359,12 +508,12 @@ export function rotationStepsOf(asset: FigureAsset, c: RotationChoice): FigurePr
     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 bind = (base: string, binding: Omit<FigureDataValueBinding, 'id'> | Omit<FigureDataTableBinding, 'id'>): FigureProposalStep => {
     const id = freeIdOf(taken, base)
     taken.push(id)
-    return { kind: 'set-data-binding', binding: { id, ...binding } }
+    return { kind: 'set-data-binding', binding: { id, ...binding } as FigureDataBinding }
   }
-  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.on) 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) {
     const values = domainOf(fieldAt(schema, c.direction.path) ?? { kind: 'text' }).map(String)
@@ -372,9 +521,10 @@ export function rotationStepsOf(asset: FigureAsset, c: RotationChoice): FigurePr
     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 } }) }
       })
     )
   }

package/client/modeller/editor-styles.ts

@@ -339,11 +339,12 @@ export const EditorStyles = css`
     min-height: 0;
     overflow: auto;
   }
-  /* Which part the panel speaks of. */
+  /* Which part the panel speaks of. Above z-index 1: a chip's label (md-filter-chip) sits at 1 and, coming later, was
+     drawn over it when the panel scrolled (sweep 2026-10-27 U2). */
   div[subject] {
     position: sticky;
     top: 0;
-    z-index: 1;
+    z-index: 2;
     display: grid;
     gap: 4px;
     padding: 10px 12px;

package/client/modeller/editor.ts

@@ -47,7 +47,7 @@ import { paletteRecipe } from './palette.js'
 import { meshChoicesOf, meshPartOf } from './mesh-import.js'
 import './figure-mesh-choice.js'
 import { uploadFigureMesh } from '../graphql/index.js'
-import { slotMarksOf } from './slot-layout-host.js'
+import { placeMarksOf, slotMarksOf } from './slot-layout-host.js'
 
 const NO_MARKS: FigureRenderPart[] = []
 import { apexOver, drawnOf } from './section-drawing.js'
@@ -950,6 +950,8 @@ export class FigureEditor extends LitElement {
   }
   /** 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
+  /** Sample legends by role, pasted in the data tab: the preview shows the figure's tables by them. Not saved. */
+  @state() private legendSample: Record<string, unknown> = {}
   /** 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
@@ -1574,18 +1576,20 @@ export class FigureEditor extends LitElement {
     return { ...(this.selected ? { part: this.selected } : {}), ...(trying ? { trying } : {}) }
   }
   /**
-   * The slots the figure's slot layout unfolds to, where they fall now (ADR-0118): drawn while the places are being
-   * edited. Made again only when the evaluation is new, so the canvas is not stood up again for nothing.
+   * The places things are held, where they fall now (ADR-0118): the slots the slot layout unfolds to and the places held
+   * one by one, drawn while the places are being edited, the selected part's in the primary colour. Made again only when the
+   * evaluation or the selection is new, so the canvas is not stood up again for nothing.
    */
-  private slotMarks(view: { bindings?: readonly unknown[] }, asset: unknown) {
+  private slotMarks(view: { bindings?: readonly unknown[]; geometry: readonly unknown[] }, asset: unknown) {
     const places = view.bindings ?? []
-    if (this.slotMarksDrawn?.of !== places) {
+    if (this.slotMarksDrawn?.of !== places || this.slotMarksDrawn.selected !== this.selected) {
       const layout = (asset as { document?: { capabilities?: { slotLayout?: { layout: never } } } })?.document?.capabilities?.slotLayout?.layout
-      this.slotMarksDrawn = { of: places, marks: slotMarksOf(places as never, layout) as never }
+      const marks = [...slotMarksOf(places as never, layout), ...(asset ? placeMarksOf(places as never, asset as never, view.geometry as never, this.selected) : [])]
+      this.slotMarksDrawn = { of: places, selected: this.selected, marks: marks as never }
     }
     return this.slotMarksDrawn.marks
   }
-  private slotMarksDrawn?: { of: readonly unknown[]; marks: FigureRenderPart[] }
+  private slotMarksDrawn?: { of: readonly unknown[]; selected: string; marks: FigureRenderPart[] }
   private choose(id: string) {
     /* A copy on the canvas selects its repeat: the part the author made. */
     this.selected = id ? ownerOf(id) : id
@@ -1868,6 +1872,7 @@ export class FigureEditor extends LitElement {
               .view=${this.view}
               .selected=${this.selected}
               .sample=${this.dataSample}
+              .legends=${this.legendSample}
               @configure-size=${async (e: CustomEvent<{ part: string }>) => {
                 this.middle = 'edit'
                 this.selected = e.detail.part
@@ -1938,7 +1943,9 @@ export class FigureEditor extends LitElement {
                     @part-live=${(e: CustomEvent) => this.hold({}, e.detail.edit)}
                   ></figure-material-panel>
                   ${this.renderMore(part, view.palette ?? {}, unavailable)}`
-              : view.geometry.length === 0
+              : view.loading || !view.context
+                ? nothing
+                : view.geometry.length === 0
                 ? html`${this.renderSubject()}<section empty-figure>
                     <p>${i18next.t('figure.text.empty-figure-next')}</p>
                     <details>
@@ -1976,8 +1983,10 @@ export class FigureEditor extends LitElement {
             ${this.renderSubject()}
             <figure-data-panel
               .asset=${asset}
+              .selected=${this.selected}
               ?locked=${unavailable}
               @data-sample=${(e: CustomEvent) => (this.dataSample = e.detail.data)}
+              @legend-sample=${(e: CustomEvent) => (this.legendSample = e.detail.legends)}
               @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>