@things-factory/figure-ui 10.1.45 → 10.1.47

package/client/modeller/v3-fields.ts

@@ -0,0 +1,62 @@
+/*
+ * The values a part or the figure is edited by, grouped as V2's inspector showed them: position, rotation and size
+ * as one row of three cells each (X · Y · Z read together), and the shape's own measures one to a line under their
+ * own title. Kept apart from the editor so the grouping is tested without a browser.
+ */
+export interface FieldLike {
+  id: string
+  unit: string
+  role?: string
+  value: number
+}
+
+export type Axis3 = 'x' | 'y' | 'z'
+const AXES: readonly Axis3[] = ['x', 'y', 'z']
+
+export type FieldGroup =
+  | { kind: 'vector'; name: 'position' | 'rotation' | 'size'; cells: Record<Axis3, FieldLike> }
+  | { kind: 'single'; name: string; field: FieldLike }
+
+/** The name a single value goes by: its id without the part, `dimension.` and corner numbers read as words. */
+function nameOf(rest: string): string {
+  return rest.replace(/^dimension\./, '')
+}
+
+/**
+ * The part's own values (`<part>.…`), or with no part the figure's (`size.x` …). Position, rotation and size come
+ * first, each only when all three of its axes are there; the rest follow in the order they are declared.
+ */
+export function groupFields(fields: readonly FieldLike[], part?: string): { vectors: FieldGroup[]; singles: FieldGroup[] } {
+  const prefix = part ? `${part}.` : ''
+  const own = fields.filter(f => (part ? f.id.startsWith(prefix) : !f.id.includes('.') || /^size\.[xyz]$/.test(f.id)))
+  const byId = new Map(own.map(f => [f.id, f]))
+  const used = new Set<string>()
+  const vectors: FieldGroup[] = []
+  for (const name of ['position', 'rotation', 'size'] as const) {
+    const ids = AXES.map(axis => `${prefix}${name}.${axis}`)
+    if (!ids.every(id => byId.has(id))) continue
+    ids.forEach(id => used.add(id))
+    vectors.push({ kind: 'vector', name, cells: { x: byId.get(ids[0]!)!, y: byId.get(ids[1]!)!, z: byId.get(ids[2]!)! } })
+  }
+  const singles: FieldGroup[] = own.filter(f => !used.has(f.id)).map(field => ({ kind: 'single', name: nameOf(field.id.slice(prefix.length)), field }))
+  return { vectors, singles }
+}
+
+/**
+ * The name a person reads for a body. A repeated body's id is its path through the repeats (`["roller.repeat",0,
+ * "roller.value"]`), which the list showed as it was; it reads as the repeat's name and the member's place counted
+ * from 1 -- `roller 1`, and `rack 2·3` inside two repeats. Any other id is its own name.
+ */
+export function partLabelOf(id: string): string {
+  if (!id.startsWith('[')) return id
+  let path: unknown
+  try {
+    path = JSON.parse(id)
+  } catch {
+    return id
+  }
+  if (!Array.isArray(path) || typeof path[0] !== 'string') return id
+  const places = path.filter((step): step is number => typeof step === 'number').map(n => n + 1)
+  return places.length ? `${path[0].replace(/\.repeat$/, '')} ${places.join('·')}` : id
+}
+

package/client/modeller/v3-help.ts

@@ -0,0 +1,41 @@
+import '@material/web/icon/icon.js'
+
+import { html, nothing, type ReactiveController, type ReactiveControllerHost } from 'lit'
+import { i18next } from '@operato/i18n'
+
+/**
+ * V2's help toggles: a small 「?」 beside a title opens the longer explanation under it. Explanations left open on every
+ * section made the side read as clutter (user, 2026-09-24); the author opens the one they want. What was opened stays
+ * open while the author moves between parts.
+ */
+export class HelpToggles implements ReactiveController {
+  private opened = new Set<string>()
+
+  constructor(private readonly host: ReactiveControllerHost) {
+    host.addController(this)
+  }
+
+  hostConnected() {}
+
+  isOpen(key: string) {
+    return this.opened.has(key)
+  }
+
+  toggle(key: string) {
+    if (this.opened.has(key)) this.opened.delete(key)
+    else this.opened.add(key)
+    this.host.requestUpdate()
+  }
+
+  /** The 「?」: it takes no line of its own, it sits in the title's spare width. */
+  button(key: string) {
+    const shown = this.opened.has(key)
+    return html`<button help aria-label=${i18next.t('figure.label.help')} aria-expanded=${shown ? 'true' : 'false'} @click=${() => this.toggle(key)}>
+      <md-icon>${shown ? 'help' : 'help_outline'}</md-icon>
+    </button>`
+  }
+
+  hint(key: string) {
+    return this.opened.has(key) ? html`<p hint>${i18next.t(key)}</p>` : nothing
+  }
+}

package/client/modeller/v3-keys.ts

@@ -0,0 +1,34 @@
+/*
+ * The modeller's keys (V2 had undo and redo on Ctrl+Z / Ctrl+Y; these add what a person reaches for next). Read apart
+ * from the element so the rule is tested without a browser.
+ *
+ * Typing is never taken: a key pressed in a field belongs to the field -- Backspace in a name box deletes a letter,
+ * not the part.
+ */
+export type KeyAction = 'undo' | 'redo' | 'duplicate' | 'remove' | 'deselect'
+
+export interface KeyLike {
+  key: string
+  ctrlKey?: boolean
+  metaKey?: boolean
+  shiftKey?: boolean
+  altKey?: boolean
+  /** The element the key was pressed in -- the first of the event's composed path. */
+  target?: { tagName?: string; isContentEditable?: boolean } | null
+}
+
+const TYPING = new Set(['INPUT', 'SELECT', 'TEXTAREA'])
+
+export function keyActionOf(e: KeyLike, selected: string): KeyAction | null {
+  if (e.target && (TYPING.has(String(e.target.tagName).toUpperCase()) || e.target.isContentEditable)) return null
+  if (e.altKey) return null
+  const mod = !!(e.ctrlKey || e.metaKey)
+  const key = e.key.toLowerCase()
+  if (mod && key === 'z') return e.shiftKey ? 'redo' : 'undo'
+  if (mod && key === 'y') return 'redo'
+  if (!selected) return null
+  if (mod && key === 'd') return 'duplicate'
+  if (!mod && (key === 'delete' || key === 'backspace')) return 'remove'
+  if (!mod && key === 'escape') return 'deselect'
+  return null
+}

package/client/modeller/v3-links.ts

@@ -1,5 +1,6 @@
-import { v3AttachmentsOf } from '@hatiolab/figure-model'
-import type { V3Asset } from '@hatiolab/figure-model'
+import { compileV3Graph, defaultInstanceSizeRange, foldInstanceSizeRange, v3AttachmentsOf, v3BindingsOf, v3InstanceSizeLimitsOf } from '@hatiolab/figure-model'
+import type { V3SizeRange } from '@hatiolab/figure-model'
+import type { V3Asset, V3BindingPlace, V3Face } from '@hatiolab/figure-model'
 
 /*
  * What a V3 part is tied to — the readers behind the parts' size response, fastening and motion sections (parity rows
@@ -21,7 +22,8 @@ const modelOf = (asset: V3Asset) =>
 /** What one dimension of a part is worked out from. */
 export type Follow =
   | { of: 'own' }
-  | { of: 'instance'; axis: Axis }
+  /** `times` 1 is the instance size itself; any other is a share of it -- V2's proportional rule. */
+  | { of: 'instance'; axis: Axis; times: number }
   | { of: 'part'; part: string; axis: Axis }
   | { of: 'input'; input: string }
   /** Worked out some other way (the converter writes expressions) — shown, not offered as a choice. */
@@ -34,15 +36,23 @@ export type Follow =
  */
 export function followOf(asset: V3Asset, part: string, axis: Axis): Follow {
   const m = modelOf(asset)
+  /*
+    A link routes the dimension through `<part>.dimension.<axis>`; before any link the shape reads its measure directly,
+    and that may already be worked out -- the converter writes V2's rules there (ROBOT_ARM's flange filled what was left).
+  */
   const node = m.nodes.find(n => n.id === `${part}.dimension.${axis}`)
-  if (!node) return { of: 'own' }
+  const start = node ? node.args[0] : m.nodes.find(n => n.id === `${part}.shape`)?.args[AXES.indexOf(axis)]
+  if (!start || m.constants.some(c => c.id === start)) return { of: 'own' }
   const writerOf = (ref: string) => m.nodes.find(n => Object.values(n.outputs).includes(ref))
   const seen = new Set<string>()
+  const constant = (ref: string) => m.constants.find(c => c.id === ref)
+  /* The constant factors met on the way back: a share of the instance size is `size × share`. */
+  let times = 1
   const walk = (ref: string): Follow => {
     if (seen.has(ref)) return { of: 'expression' }
     seen.add(ref)
     const instance = /^size\.([xyz])$/.exec(ref)
-    if (instance) return { of: 'instance', axis: instance[1] as Axis }
+    if (instance) return { of: 'instance', axis: instance[1] as Axis, times: Math.round(times * 1e6) / 1e6 }
     const other = /^(.+)\.dimension\.([xyz])\.value$/.exec(ref)
     if (other) return { of: 'part', part: other[1]!, axis: other[2] as Axis }
     const input = m.inputs.find(i => i.id === ref)
@@ -50,10 +60,19 @@ export function followOf(asset: V3Asset, part: string, axis: Axis): Follow {
     const writer = writerOf(ref)
     if (!writer) return { of: 'expression' }
     /* Follow the one argument that is not a constant factor. */
-    const onward = writer.args.filter(arg => !m.constants.some(c => c.id === arg))
-    return onward.length === 1 ? walk(onward[0]!) : { of: 'expression' }
+    const onward = writer.args.filter(arg => !constant(arg))
+    if (onward.length !== 1) return { of: 'expression' }
+    /*
+      Only a product is a share of its source. A sum with a number is not (V2's 「fill what is left」 is the size plus a
+      negative gap -- ROBOT_ARM's tool flange), nor anything else; those read as worked out some other way.
+    */
+    const factors = writer.args.filter(arg => constant(arg)).map(arg => constant(arg)!.value)
+    if (writer.op === 'mul@1') times *= factors.reduce((a, b) => a * b, 1)
+    else if (writer.op === 'div@1' && writer.args[0] === onward[0] && factors.length === 1 && factors[0] !== 0) times /= factors[0]!
+    else if (factors.some(v => v !== 0) || !['mul@1', 'div@1', 'add@1', 'sub@1'].includes(writer.op)) return { of: 'expression' }
+    return walk(onward[0]!)
   }
-  return walk(node.args[0]!)
+  return walk(start)
 }
 
 /** Whether the asset declares an instance size on an axis — only then can a dimension follow it. */
@@ -66,8 +85,34 @@ export function fastenedTo(asset: V3Asset, part: string): string | null {
 
 /** Whether a dimension of this part can follow something — box-shaped, whose three sizes are X, Y and Z. */
 export function canFollow(asset: V3Asset, part: string): boolean {
+  return followableAxes(asset, part).length > 0
+}
+
+/**
+ * The axes whose size can follow something, by the shape's own measures: a box's X · Y · Z; a cylinder's radius (read
+ * as X) and length (Y) -- its shape takes those two, so it has no Z of its own (V2's sizing cards had the cylinder's
+ * two as well).
+ */
+export function followableAxes(asset: V3Asset, part: string): Axis[] {
   const shape = modelOf(asset).nodes.find(n => n.id === `${part}.shape`)
-  return !!shape && (shape.op === 'box-shape@1' || shape.op === 'rounded-box@1')
+  if (!shape) return []
+  if (shape.op === 'box-shape@1' || shape.op === 'rounded-box@1') return [...AXES]
+  if (shape.op === 'cylinder-shape@1') return ['x', 'y']
+  return []
+}
+
+/** What a part's own measure on an axis is now (a box's side, a cylinder's radius or length), at the design as it stands. */
+export function dimensionNow(asset: V3Asset, part: string, axis: Axis): number | undefined {
+  const m = modelOf(asset)
+  const ref = m.nodes.find(n => n.id === `${part}.shape`)?.args[AXES.indexOf(axis)]
+  if (!ref) return undefined
+  try {
+    const values = compileV3Graph(asset.document.model as never).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values as Record<string, number>
+    const value = values[ref]
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+  } catch {
+    return undefined
+  }
 }
 
 /** Whether `attach` can take this part: a box, or a cylinder (figure-model measures its faces since 0.1.47). */
@@ -89,6 +134,17 @@ export function positionsWorkedOut(asset: V3Asset, part: string): Axis[] {
   return AXES.filter((_axis, i) => !own(pose.args[i]!) && !constant(pose.args[i]!))
 }
 
+/**
+ * Whether the part's position on an axis is a share of the instance size (`scale-position`): `size.<axis> × share`.
+ * Such a position is worked out too, but it already grows with the figure, so it is not offered again.
+ */
+export function positionIsShare(asset: V3Asset, part: string, axis: Axis): boolean {
+  const m = modelOf(asset)
+  const ref = m.nodes.find(n => n.id === `${part}.pose`)?.args[AXES.indexOf(axis)]
+  const writer = ref ? m.nodes.find(n => Object.values(n.outputs).includes(ref)) : undefined
+  return !!writer && writer.op === 'mul@1' && writer.args[0] === `size.${axis}` && m.constants.some(c => c.id === writer.args[1])
+}
+
 /** How a part moves, if it does: slide or turn, along which axis, driven by which control. */
 export interface Motion {
   kind: 'slide' | 'turn'
@@ -127,7 +183,7 @@ export function choiceOf(follow: Follow): string {
     case 'own':
       return 'own'
     case 'instance':
-      return `instance:${follow.axis}`
+      return follow.times === 1 ? `instance:${follow.axis}` : `share:${follow.axis}`
     case 'part':
       return `part:${follow.part}:${follow.axis}`
     case 'input':
@@ -136,3 +192,63 @@ export function choiceOf(follow: Follow): string {
       return 'expression'
   }
 }
+
+/** The faces a place can sit on for this part: a box's six, a rounded box's top and bottom, none for a round body. */
+export function placeFacesOf(asset: V3Asset, part: string): V3Face[] {
+  const shape = modelOf(asset).nodes.find(n => n.id === `${part}.shape`)
+  if (shape?.op === 'box-shape@1') return ['left', 'right', 'bottom', 'top', 'back', 'front']
+  if (shape?.op === 'rounded-box@1') return ['bottom', 'top']
+  return []
+}
+
+/** The places things are held that sit on this part. */
+export function placesOn(asset: V3Asset, part: string): V3BindingPlace[] {
+  return v3BindingsOf(asset).filter(one => one.part === part)
+}
+
+/** An id for a new place on this part, not yet taken: `<part>-<role>`, then `-2`, `-3`. */
+export function placeIdFor(asset: V3Asset, part: string, role: 'seat' | 'grip'): string {
+  const taken = new Set(asset.document.capabilities.bindings.map(b => b.id))
+  const base = `${part}-${role}`
+  if (!taken.has(base)) return base
+  let n = 2
+  while (taken.has(`${base}-${n}`)) n++
+  return `${base}-${n}`
+}
+
+/**
+ * Whether a board will hand this figure anything: a place is a slot only on a figure that declares it holds things
+ * (`Capacity`, or `FlowNode`, which includes it). Without it the places are declared and nothing arrives.
+ */
+export const holdsThings = (asset: V3Asset) => (asset.document.capabilities.names ?? []).some(n => n === 'Capacity' || n === 'FlowNode')
+
+/** What `accepts` a person typed: names split on commas, trimmed, blanks and repeats dropped. */
+export const acceptsOf = (typed: string) => [...new Set(typed.split(',').map(one => one.trim()).filter(Boolean))]
+
+/**
+ * The sizes a board may give this figure: the range it declares now, and the range measured afresh -- the default
+ * (1 mm to ten times the authored size) narrowed only where the figure cannot follow, by the converter's own functions.
+ * A range measured when a part filled what the others left (ROBOT_ARM: Y from 1,854 mm) stays narrow after the part is
+ * made to grow with the figure; measuring again gives the figure its whole range back. Nothing when no size is declared.
+ */
+export function instanceRangeOf(asset: V3Asset): { declared: V3SizeRange; measured: V3SizeRange } | undefined {
+  const inputs = modelOf(asset).inputs
+  const declared = {} as V3SizeRange
+  const authored = {} as Record<Axis, number>
+  for (const axis of AXES) {
+    const input = inputs.find(i => i.id === `size.${axis}` && i.role === 'design')
+    const at = asset.designInputs[`size.${axis}`]
+    if (!input || typeof at !== 'number') return undefined
+    declared[axis] = { min: input.min ?? 0, max: input.max ?? Infinity }
+    authored[axis] = at
+  }
+  const start = defaultInstanceSizeRange(authored)
+  const measured = foldInstanceSizeRange(start, v3InstanceSizeLimitsOf(asset, start)).range
+  return { declared, measured }
+}
+
+/** Whether measuring again would change the declared range (to a micrometre). */
+export function rangeDiffers(a: V3SizeRange, b: V3SizeRange): boolean {
+  return AXES.some(axis => Math.abs(a[axis].min - b[axis].min) > 1e-3 || Math.abs(a[axis].max - b[axis].max) > 1e-3)
+}
+

package/client/modeller/v3-live.ts

@@ -0,0 +1,79 @@
+import { compileV3Asset, editV3Part } from '@hatiolab/figure-model'
+import type { V3Asset, V3PartEdit } from '@hatiolab/figure-model'
+
+import { drawableV3Parts, type V3RenderPart } from './v3-renderer.js'
+
+/*
+ * The figure while a value is in hand: evaluated with the values being typed or dragged, drawn at once and written
+ * nowhere. The panels committed on release only, so the canvas stood still while a number was typed, a spinner held,
+ * a label scrubbed, a slider or the glow dragged (user, 2026-09-24: "make the editor move naturally while the value
+ * changes"). The value in hand shows here; the release is the one step of the history.
+ *
+ * What is in hand is either input values -- a design value (a size, a position) or a pose -- or one part edit (the
+ * glow of a material). A design value is a change of the figure's design, so it is shown by evaluating a copy with
+ * that value; a pose is a state override, as the preview gives it.
+ */
+
+export interface LiveValues {
+  /** Input values in hand, design or state, by input id. */
+  values: Record<string, number>
+  /** A part edit in hand, not yet committed. */
+  edit?: V3PartEdit
+}
+
+export const NOTHING_LIVE: LiveValues = { values: {} }
+
+/** Known inputs with a number, split by what they are. An id the figure does not declare is dropped. */
+export function liveOverridesOf(asset: V3Asset, values: Record<string, number>): { design: Record<string, number>; state: Record<string, number> } {
+  const roles = new Map(asset.document.model.inputs.map(i => [i.id, i.role]))
+  const design: Record<string, number> = {},
+    state: Record<string, number> = {}
+  for (const [id, value] of Object.entries(values)) {
+    if (!Number.isFinite(value)) continue
+    const role = roles.get(id)
+    if (role === 'state') state[id] = value
+    else if (role !== undefined) design[id] = value
+  }
+  return { design, state }
+}
+
+export function isLive(live: LiveValues): boolean {
+  return !!live.edit || Object.keys(live.values).length > 0
+}
+
+/**
+ * The bodies to draw with what is in hand, or null when nothing is -- then the evaluation as it stands is drawn.
+ *
+ * Also null when the figure cannot take the value in hand (a size of 0 on the way to typing 0.5, a glow the material
+ * refuses): the canvas keeps the figure as it stands until the release, and the release reports why through the same
+ * refusal every committed edit gets. A preview never invents a figure the commit would not make.
+ */
+export function livePartsOf(asset: V3Asset, live: LiveValues): V3RenderPart[] | null {
+  if (!isLive(live)) return null
+  const { design, state } = liveOverridesOf(asset, live.values)
+  try {
+    let next = live.edit ? editV3Part(asset, live.edit) : asset
+    if (Object.keys(design).length) next = { ...next, designInputs: { ...next.designInputs, ...design } }
+    return drawableV3Parts(compileV3Asset(next).evaluate(state).geometry)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * How much one pixel of a label drag moves a value: a degree for an angle, a hundredth for a ratio, and for a length a
+ * step that suits its size -- a millimetre under 100, ten over 1,000 -- so a 12 m wall and a 5 mm pin both scrub at a
+ * usable pace. Shift makes it ten times finer.
+ */
+export function scrubStep(unit: string, value: number, fine = false): number {
+  const base =
+    unit === 'deg' ? 1 : unit === 'ratio' ? 0.01 : Math.max(1, Math.pow(10, Math.floor(Math.log10(Math.max(1, Math.abs(value)))) - 2))
+  return fine ? base / 10 : base
+}
+
+/** A scrubbed value on the step's grid, so a drag does not leave 1203.0000000002 behind. */
+export function scrubbed(start: number, pixels: number, step: number): number {
+  const value = start + pixels * step
+  const digits = Math.max(0, -Math.floor(Math.log10(step)))
+  return Number(value.toFixed(digits))
+}