@things-factory/figure-ui 10.1.74 → 10.1.76

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

@@ -0,0 +1,267 @@
+import type { FigureFollow, FigureSizeRange } from '@hatiolab/figure-model';
+import type { FigureAsset, FigureBindingPlace, FigureFace, FigureJoint } from '@hatiolab/figure-model';
+export type Axis = 'x' | 'y' | 'z';
+export declare const AXES: readonly Axis[];
+/** What one dimension of a part is worked out from (figure-model's `FigureFollow`). */
+export type Follow = FigureFollow;
+/**
+ * `link-dimension` routes a part's dimension through `<part>.dimension.<axis>` and points its first argument at the
+ * source, directly or through the nodes that scale it. Walking back through those nodes finds the source: the
+ * instance size (`size.<axis>`), another part's dimension (`<part>.dimension.<axis>.value`) or a declared input.
+ */
+/** What one measure of a part is worked out from, read back from the graph (figure-model's reader, one copy). */
+export declare function followOf(asset: FigureAsset, part: string, axis: Axis): Follow;
+/** Whether the asset declares an instance size on an axis — only then can a dimension follow it. */
+export declare const hasInstanceSize: (asset: FigureAsset, axis: Axis) => boolean;
+/** The part this one is fastened to, or `null`. The mounting plane counts as fastened (the model names no part). */
+export declare function fastenedTo(asset: FigureAsset, part: string): string | null;
+/**
+ * What holds a part: the part it is fastened to, the plane the figure is mounted on, or nothing. The joint record says
+ * it; a part standing on the plane had read as fastened to nothing, so the form offered no way to move it and sent
+ * no replace -- the fastening was refused as already made (the door's post, 2026-09-25).
+ */
+export declare function heldBy(asset: FigureAsset, part: string): {
+    part: string;
+} | {
+    plane: true;
+} | null;
+/** Whether a dimension of this part can follow something — box-shaped, whose three sizes are X, Y and Z. */
+export declare function canFollow(asset: FigureAsset, part: string): boolean;
+/**
+ * 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.
+ */
+export declare function followableAxes(asset: FigureAsset, part: string): Axis[];
+/** 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 declare function dimensionNow(asset: FigureAsset, part: string, axis: Axis): number | undefined;
+/**
+ * The flat faces a part's shape declares, by name -- figure-model's shape definitions are the one place they are
+ * written (a portal's opening sides as well as its outer faces). A sphere has none.
+ */
+export declare function facesOf(asset: FigureAsset, part: string): string[];
+/** The axis a face of a part faces along, from the same definitions. */
+export declare function faceAxisOf(asset: FigureAsset, part: string, face: string): Axis | undefined;
+/** Whether `attach` can take this part: any part whose shape has a flat face. */
+export declare function canFasten(asset: FigureAsset, part: string): boolean;
+/**
+ * The axes a part can be made a row along (r3 §8, figure-model `make-repeat`): across the face it is fastened by, when
+ * it is fastened fixed to another part and holds nothing. None for a part that is loose, moves, stands on the floor or
+ * already repeats -- the command would refuse those, so they are not offered.
+ */
+export declare function rowAxesOf(asset: FigureAsset, part: string): Axis[];
+/** The row a part is made into, as its fastening's record keeps it. */
+export declare const rowOf: (asset: FigureAsset, part: string) => {
+    axis: import("@hatiolab/figure-model").FigureJointAxis;
+    pitch: import("@hatiolab/figure-model").FigureMeasure;
+    count?: number;
+    rise?: {
+        axis: import("@hatiolab/figure-model").FigureJointAxis;
+        mm: number;
+    };
+} | undefined;
+/** Where a part sits across the face it is fastened to, on one axis: centred, level with an edge, or a distance off centre. */
+/** `share`: the distance as a share of the figure's size on that axis, so it keeps its place when the figure is resized. */
+export type Alignment = 'centre' | 'min' | 'max' | 'mm' | 'share';
+/**
+ * The axes across the face a part is fastened to — the two a fastening does not set by itself. Edges to line up with
+ * are offered where both parts have their two outer faces on that axis; the plane the figure is mounted on has none,
+ * so on it (X and Z) only centred or a distance is offered.
+ */
+/**
+ * The mounting plane of this figure, by its placement (ADR-0093): the floor or the ceiling is Y = 0 and a part stands
+ * on it by its bottom or hangs from it by its top; a wall is Z = 0 and a part is fastened to it by its back.
+ */
+export declare function mountingPlaneOf(asset: FigureAsset): {
+    normal: Axis;
+    faces: FigureFace[];
+};
+export declare function alignAxesOf(asset: FigureAsset, part: string, target: {
+    part: string;
+    face: string;
+} | 'plane', twisted?: boolean): {
+    axis: Axis;
+    edges: boolean;
+}[];
+/** The controls a part's showing can follow: the figure's state inputs, with their range and label. */
+export declare function visibilityControlsOf(asset: FigureAsset): Array<{
+    id: string;
+    unit: string;
+    min: number;
+    max: number;
+    label: string;
+}>;
+/** When the part is drawn (figure-model `set-visibility`): always (null), or while a control is at least a value. */
+export declare function shownWhenOf(asset: FigureAsset, part: string): {
+    input: string;
+    atLeast: number;
+} | null;
+/** Whether `part` hangs from `from`, through any number of fastenings. */
+export declare function hangsFrom(asset: FigureAsset, part: string, from: string): boolean;
+/**
+ * The fastening a part has, as the fastening form holds it -- so the form opens on what is there (the face, including
+ * \`centre\`, the target and its face, the gap, the twist and where across the face) and a change is a change to that.
+ * Opening it on the defaults showed a roller fastened by its centre as fastened by its bottom, and fastening again
+ * from there broke its turning in place (walk 1, 2026-09-26). Null for a part fastened to nothing.
+ */
+export declare function fasteningOf(asset: FigureAsset, part: string): {
+    face: string;
+    toPlane: boolean;
+    target: string;
+    targetFace: string;
+    facing: 'meet' | 'flush';
+    gap: number;
+    twist: number;
+    align: Partial<Record<Axis, Alignment>>;
+    alignMm: Partial<Record<Axis, number>>;
+} | null;
+/**
+ * The alignment that keeps the part where it stands when it is fastened: on each axis across the face, its distance
+ * from the target's centre (the plane's is the origin). Fastening used to centre it -- a door set 100 mm in front of
+ * its frame slid into it (2026-09-26). Left centred where it already is, and where the target stands turned.
+ */
+export declare function placeKeptOf(asset: FigureAsset, part: string, target: {
+    part: string;
+    face: string;
+} | 'plane', twisted?: boolean): {
+    align: Partial<Record<Axis, Alignment>>;
+    alignMm: Partial<Record<Axis, number>>;
+};
+/** The `align` of an attach command from the form's choices: only the axes across that face, and centred ones left out. */
+export declare function alignOf(asset: FigureAsset, part: string, target: {
+    part: string;
+    face: string;
+} | 'plane', how: Partial<Record<Axis, Alignment>>, mm: Partial<Record<Axis, number>>, twisted?: boolean): Partial<Record<Axis, "min" | "max" | {
+    mm: number | {
+        from: {
+            of: "instance";
+            axis: Axis;
+        };
+        times: number;
+    };
+}>> | undefined;
+/**
+ * The axes on which the part's position is worked out from other values rather than being its own number. `fix-position` makes one its own number where it is now.
+ */
+export declare function positionsWorkedOut(asset: FigureAsset, part: string): Axis[];
+/**
+ * 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 declare function positionIsShare(asset: FigureAsset, part: string, axis: Axis): boolean;
+/** How a part moves, if it does: slide or turn, along which axis, driven by which control. */
+export interface Motion {
+    kind: 'slide' | 'turn' | 'continuous';
+    axis: Axis | '?';
+    control?: {
+        id: string;
+        unit?: string;
+        min?: number;
+        max?: number;
+    };
+    /** A joint that moves with another (URDF's mimic): the leader's value times `multiplier`, plus `offset`. */
+    follows?: {
+        joint: string;
+        multiplier: number;
+        offset?: number;
+    };
+    /** A slide whose distance is a part's length (plus a difference): the control is its share. */
+    travel?: {
+        part: string;
+        axis: string;
+        plus?: number;
+    };
+}
+export declare function motionOf(asset: FigureAsset, part: string): Motion | undefined;
+/** What the motion form holds: how the part moves, and either its own control or the joint it moves with. */
+export interface MotionForm {
+    kind: 'slide' | 'turn' | 'continuous';
+    axis: Axis;
+    id: string;
+    min: number;
+    max: number;
+    /** The joint this one moves with; empty for a joint with its own control. */
+    follow: string;
+    multiplier: number;
+    offset: number;
+    /**
+     * A slide whose distance follows a part's length (figure-model `travel`): `<part>:<axis>`, empty for a distance in
+     * millimetres. The control is then the share of that length, 0..1, and the stroke grows when the part does.
+     */
+    travel?: string;
+    travelPlus?: number;
+}
+/**
+ * The motion form filled from a joint as it is, so a motion can be changed where it is -- its range, the length it
+ * travels by, what it follows -- rather than taken away and made again. Taking it away is refused while another joint
+ * follows it, which left a leader's stroke fixed for good (the telescopic conveyor, 2026-09-25).
+ */
+export declare function motionFormOf(joint: FigureJoint): MotionForm;
+/**
+ * The joints a part's joint can move with (URDF's mimic): a joint that moves the same way — a slide follows a slide, a
+ * turn a turn — and has a control of its own, since a follower follows the joint that is driven.
+ */
+export declare function leadersFor(asset: FigureAsset, part: string, kind: MotionForm['kind']): FigureJoint[];
+/**
+ * The joint record the motion form writes for a part fastened by `joint`. A joint of its own gets its limits (none for
+ * a turn without end, as in USD) and a control; a follower gets the leader, the multiplier and the offset, and no
+ * control or limits of its own — its range is the leader's times the multiplier.
+ */
+export declare function motionJoint(joint: FigureJoint, m: MotionForm, part: string): FigureJoint;
+/** The select's value for what a dimension follows now. */
+export declare function choiceOf(follow: Follow): string;
+/** 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 declare function placeFacesOf(asset: FigureAsset, part: string): FigureFace[];
+/** The places things are held that sit on this part. */
+export declare function placesOn(asset: FigureAsset, part: string): FigureBindingPlace[];
+/** An id for a new place on this part, not yet taken: `<part>-<role>`, then `-2`, `-3`. */
+export declare function placeIdFor(asset: FigureAsset, part: string, role: 'seat' | 'grip'): string;
+/**
+ * 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 declare const holdsThings: (asset: FigureAsset) => boolean;
+/** What `accepts` a person typed: names split on commas, trimmed, blanks and repeats dropped. */
+export declare const acceptsOf: (typed: string) => string[];
+/**
+ * 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 figure-model'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 declare function instanceRangeOf(asset: FigureAsset): {
+    declared: FigureSizeRange;
+    measured: FigureSizeRange;
+} | undefined;
+/**
+ * The size range to declare for a figure that has none yet: its parts' extent now as the size it is authored at, and
+ * as wide as its parts allow around it (the same measure 「다시 재기」 uses). Undefined when the figure already has a
+ * size or has nothing to measure. Without a declared size a board cannot resize the figure, and no part is offered
+ * to follow its size -- every figure made in the modeller was left there (user, 2026-09-25).
+ */
+export declare function instanceRangeToDeclare(asset: FigureAsset): {
+    range: FigureSizeRange;
+    at: Record<Axis, number>;
+} | undefined;
+/** Whether measuring again would change the declared range (to a micrometre). */
+/**
+ * The declared range with one end typed by the author: the sizes a figure may be placed at are a claim about the
+ * product (a gantry spans metres, not 30 cm to 29 m), and measuring only ever widens them. Nothing when the typed
+ * value is not a number; whether the figure holds there is the command's to say.
+ */
+export declare function rangeWith(declared: FigureSizeRange, axis: Axis, bound: 'min' | 'max', value: number): FigureSizeRange | undefined;
+/**
+ * For a figure that grows by one ratio: how many of its lengths would follow the ratio, and which it leaves with their
+ * own number (not those that follow another length -- they grow with it). Nothing for a figure of another sizing.
+ */
+export declare function proportionToFollow(asset: FigureAsset): {
+    count: number;
+    kept: string[];
+} | undefined;
+/** A value of the figure as it stands, by its graph reference. */
+export declare function valueNow(asset: FigureAsset, ref: string | undefined): number | undefined;
+export declare function rangeDiffers(a: FigureSizeRange, b: FigureSizeRange): boolean;
+/**
+ * Whether the figure is a mechanism -- a part turns about a joint. Such a figure should grow by one ratio (chief
+ * architect's ruling 2026-09-24); the modeller proposes it, the author declares it.
+ */
+export declare function turnsAboutAJoint(asset: FigureAsset): boolean;