@grafloria/element 0.3.20 → 0.3.21

package/src/libs/engine/src/models/LinkModel.d.ts

@@ -1,395 +0,0 @@
-import { DiagramEntity } from './DiagramEntity';
-import type { DiagramModel } from './DiagramModel';
-import type { Point, LinkStyle, LinkLabel, SerializedEntity, PathSegment } from '../types';
-/**
- * Wave 4 (Edges & links), Card 5 — where each of the three edge label SLOTS sits
- * along the path.
- *
- * Pulled IN from the endpoints on purpose: at exactly 0 and 1 a slot label would
- * land under the arrowhead and on top of the port. 0.12 / 0.88 clears both while
- * still reading as "at the start / at the end of this edge".
- *
- * ONE definition, shared by the model (LinkModel.addLabel), the renderer
- * (LabelRenderer) and the edge optimizer — three places that must never disagree
- * about where a label actually is.
- */
-export declare const LINK_LABEL_SLOT_POSITIONS: Record<'start' | 'center' | 'end', number>;
-/**
- * The position along the path (0-1) a label resolves to.
- *
- * `slot` WINS over `position`. Naming a slot is an explicit act; `position` is a
- * required field that most slot users only fill in to satisfy the type, so
- * letting it win would make `slot` silently do nothing.
- */
-export declare function linkLabelPosition(label: Pick<LinkLabel, 'position' | 'slot'>): number;
-/**
- * Wave 5 (Edge routing) — Card 0. `pathType` conflated two independent choices:
- * WHERE the line goes (routing geometry) and HOW the polyline is drawn
- * (connector rendering). They are now two orthogonal, per-link, serializable
- * settings, with `pathType` kept as the back-compat shorthand that derives both
- * when the explicit fields are absent.
- *
- * Router names resolve against the engine's RoutingEngine registry, so a custom
- * registered router is addressable per link by its registration name.
- */
-export type LinkRouterName = 'straight' | 'orthogonal' | 'manhattan' | 'avoid' | 'elk' | (string & {});
-export type LinkConnectorName = 'straight' | 'rounded' | 'smooth' | 'bezier' | (string & {});
-export interface SerializedLink extends SerializedEntity {
-    sourcePortId: string;
-    targetPortId: string;
-    sourceNodeId?: string;
-    targetNodeId?: string;
-    pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier';
-    /** Card 0: explicit routing geometry; absent = derived from pathType. */
-    router?: LinkRouterName;
-    /** Card 0: explicit polyline rendering; absent = derived from pathType. */
-    connector?: LinkConnectorName;
-    points: Point[];
-    segments: PathSegment[];
-    labels: LinkLabel[];
-    state: 'default' | 'selected' | 'hovered' | 'highlighted';
-    style: Partial<LinkStyle>;
-    data: Record<string, any>;
-}
-export declare class LinkModel extends DiagramEntity {
-    /**
-     * Wave 9 — Card 7. Back-reference to the owning diagram, set by
-     * `DiagramModel.installLink`. NodeModel has had one since Phase 1.6a; LinkModel
-     * did not, so a LinkModel mutator could not see the document's read-only lock —
-     * and waypoints, control points, labels and reconnection are ALL LinkModel
-     * mutators. Without this, read-only would have been unenforceable on exactly the
-     * edits the interaction controller performs most.
-     *
-     * NON-ENUMERABLE (defined in the constructor, mirroring NodeModel): an enumerable
-     * back-reference to the diagram would make every LinkModel a circular object and
-     * blow up deep-clone and JSON serialization.
-     */
-    diagram?: DiagramModel;
-    sourcePortId: string;
-    targetPortId: string;
-    sourceNodeId?: string;
-    targetNodeId?: string;
-    pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier';
-    /**
-     * Card 0: WHERE the line goes. When unset, derived from pathType — see
-     * {@link effectiveRouter}. Setting it does NOT touch pathType, so legacy
-     * consumers keep working; the explicit field simply wins.
-     */
-    router?: LinkRouterName;
-    /** Card 0: HOW the polyline is drawn. Unset = derived from pathType. */
-    connector?: LinkConnectorName;
-    points: Point[];
-    segments: PathSegment[];
-    labels: LinkLabel[];
-    state: 'default' | 'selected' | 'hovered' | 'highlighted';
-    style: Partial<LinkStyle>;
-    data: Record<string, any>;
-    /**
-     * Whether source endpoint handle is selected
-     * Used for dragging endpoint to reconnect
-     */
-    isSourceEndpointSelected: boolean;
-    /**
-     * Whether target endpoint handle is selected
-     * Used for dragging endpoint to reconnect
-     */
-    isTargetEndpointSelected: boolean;
-    constructor(sourcePortId: string, targetPortId: string, pathType?: 'direct' | 'orthogonal' | 'smooth' | 'bezier');
-    /**
-     * Wave 9 — Card 7. Is a document write to this link forbidden right now?
-     * True only when the link belongs to a diagram that is locked (read-only) and we
-     * are not inside a system write. A detached link (not yet added to any diagram)
-     * is freely mutable — you must be able to BUILD a link before adding it, and
-     * `DiagramModel.addLink` is what refuses.
-     */
-    private writeBlocked;
-    /**
-     * Wave 4 (Edges & links) — Card 4: is this link a SELF-LOOP, i.e. do both
-     * ends live on the same node?
-     *
-     * Reads the cached owning-node ids, which `DiagramModel.installLink` backfills
-     * for every link that reaches a diagram (including ones built with
-     * `new LinkModel()` + `addLink`, which carry no ids of their own). A link that
-     * has never been installed has no ids and is — correctly — not a self-loop as
-     * far as anything can tell.
-     *
-     * A self-loop between two DIFFERENT ports of the same node counts, and so does
-     * one that starts and ends on the SAME port.
-     */
-    isSelfLoop(): boolean;
-    /**
-     * Wave 4 — Card 4: the unordered node pair this link connects, as a stable
-     * key. UNORDERED on purpose: A→B and B→A are the same visual bundle and must
-     * fan out together, or a bidirectional pair would draw both links on the same
-     * centre line. Returns null when the owning nodes are unknown.
-     */
-    getNodePairKey(): string | null;
-    /**
-     * Set source port
-     */
-    setSourcePort(portId: string, nodeId?: string): void;
-    /**
-     * Set target port
-     */
-    setTargetPort(portId: string, nodeId?: string): void;
-    /**
-     * Set path type
-     */
-    setPathType(pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier'): void;
-    /**
-     * Card 0: set the routing geometry explicitly. Clears the cached route the
-     * same way setPathType does — the old polyline belongs to the old router.
-     */
-    setRouter(router: LinkRouterName | undefined): void;
-    /** Card 0: set the polyline rendering explicitly. Pure re-render; the routed
-     * points are still valid, so the cache is NOT cleared. */
-    setConnector(connector: LinkConnectorName | undefined): void;
-    /**
-     * The router actually in force: the explicit field, else derived from
-     * pathType exactly as the renderer always derived it (direct → straight,
-     * orthogonal → orthogonal, smooth/bezier → straight-with-curved-rendering).
-     */
-    effectiveRouter(): LinkRouterName;
-    /**
-     * The connector actually in force: the explicit field, else implied by an
-     * explicitly axis-aligned ROUTER, else derived from pathType.
-     *
-     * The router rung exists because `{ router: 'orthogonal' }` with the default
-     * pathType used to draw a smooth SPLINE through Manhattan waypoints — the
-     * route was orthogonal, the picture was wavy (the screenshot audit caught the
-     * demo's own readout saying "orthogonal" over a curve). Asking for an
-     * axis-aligned router IS asking for axis-aligned rendering; rounded corners
-     * are that family's standard look. An explicit `connector` still overrides.
-     */
-    effectiveConnector(): LinkConnectorName;
-    /**
-     * Set points for custom path
-     */
-    setPoints(points: Point[]): void;
-    /**
-     * Add point to path
-     */
-    addPoint(point: Point, index?: number): void;
-    /**
-     * Remove point from path
-     */
-    removePoint(index: number): Point | undefined;
-    /**
-     * Update segments based on points
-     */
-    private updateSegments;
-    /**
-     * Generate path based on type
-     */
-    generatePath(sourcePoint: Point, targetPoint: Point, sourceDirection?: 'left' | 'right' | 'top' | 'bottom', targetDirection?: 'left' | 'right' | 'top' | 'bottom'): void;
-    /**
-     * Generate direct path (straight line)
-     */
-    private generateDirectPath;
-    /**
-     * Generate orthogonal path (right angles)
-     * Uses React Flow's smoothstep algorithm with port directions for proper routing
-     */
-    private generateOrthogonalPath;
-    /**
-     * Apply gap offset in port direction
-     */
-    private applyGapOffset;
-    /**
-     * Get direction vector for port orientation
-     */
-    private getDirectionVector;
-    /**
-     * Get routing direction from source to target
-     */
-    private getRoutingDirection;
-    /**
-     * Wave 3 (Edges & links): the curve tightness of a smooth/bezier link.
-     *
-     * `style.curvature` is a multiplier of the endpoint distance for the
-     * control-point offset. It used to be DEAD (declared on LinkStyle, read by
-     * nobody); it is now the single knob both this model and the SVG renderer
-     * read, so a per-link value produces the same curve whichever produced the
-     * path. Default 0.5 = the historical hardcoded factor; negatives are clamped
-     * to 0 (a straight chord).
-     */
-    static readonly DEFAULT_CURVATURE = 0.5;
-    getCurvature(): number;
-    /**
-     * Generate smooth/bezier path
-     */
-    private generateSmoothPath;
-    /**
-     * Add label
-     *
-     * Wave 4 (Card 5): `position` is no longer required when the label names a
-     * `slot` — and every other LinkLabel field (html, template, slot, autoOffset,
-     * rotation…) is now carried through instead of being silently dropped. The old
-     * body hand-copied five fields, so a label created here could not be an HTML
-     * label, could not auto-rotate and could not opt into auto-placement.
-     */
-    addLabel(label: Partial<LinkLabel> & {
-        text: string;
-    } & ({
-        position: number;
-    } | {
-        slot: NonNullable<LinkLabel['slot']>;
-    })): void;
-    /**
-     * Remove label by ID
-     */
-    removeLabel(labelId: string): LinkLabel | undefined;
-    /**
-     * Remove label by index
-     */
-    removeLabelAt(index: number): LinkLabel | undefined;
-    /**
-     * Update label by index
-     */
-    updateLabel(index: number, updates: Partial<LinkLabel>): void;
-    /**
-     * REPLACE the whole label collection — the write `addLabel`/`updateLabel` cannot express.
-     *
-     * `SetLinkLabelsCommand` used to do this by assigning `link.labels` directly on BOTH
-     * execute and undo. A plain field write does not pass `trackChange()` — the one funnel
-     * collab captures from — so the command emitted ZERO ops in BOTH directions: authoring
-     * a link's labels was invisible to every other peer, and so was taking it back. (The
-     * `UpdateLinkStyleCommand` defect at least emitted one op on execute; this emitted none
-     * at all.) `replaceStyle` is the same seam for the same reason.
-     */
-    setLabels(labels: LinkLabel[]): void;
-    /**
-     * Overloaded label read.
-     *
-     * - `getLabel()` — no argument — is the CANONICAL display-label accessor
-     *   inherited from DiagramEntity (metadata.label, with the legacy
-     *   data['label'] fallback). It is what the DSL generator exports and what
-     *   feeds the renderer's simple edge label (svg-renderer reads
-     *   link.getMetadata('label')).
-     * - `getLabel(labelId)` is the pre-existing lookup into the POSITIONED
-     *   multi-label API (`labels: LinkLabel[]` / addLabel / updateLabel), a
-     *   different feature that happens to share the verb. The overload keeps
-     *   both callable without forking the canonical name.
-     */
-    getLabel(): string | undefined;
-    getLabel(labelId: string): LinkLabel | undefined;
-    /**
-     * Set state
-     */
-    setState(state: 'default' | 'selected' | 'hovered' | 'highlighted'): void;
-    /**
-     * Update style
-     */
-    updateStyle(style: Partial<LinkStyle>): void;
-    /**
-     * REPLACE the whole style object — the write `updateStyle` cannot express.
-     *
-     * `updateStyle` merges, so it can never REMOVE a key; restoring a snapshot has to
-     * assign wholesale. `UpdateLinkStyleCommand.undo()` used to do that with a direct
-     * field write (`link.style = restored`), which never passes `trackChange()` — the
-     * single funnel collab captures from. Measured: execute emitted 1 op, undo emitted 0,
-     * so every peer kept the styled link forever while the author saw it correctly
-     * reverted. See collab/style-undo.spec.ts.
-     */
-    replaceStyle(style: Partial<LinkStyle>): void;
-    /**
-     * Set data property
-     */
-    setData(key: string, value: any): void;
-    /**
-     * Get data property
-     */
-    getData(key: string): any;
-    /**
-     * Phase 1: Reconnect source endpoint to new port
-     * Used for link reconnection workflow
-     */
-    reconnectSource(newPortId: string, newNodeId?: string): void;
-    /**
-     * Phase 1: Reconnect target endpoint to new port
-     * Used for link reconnection workflow
-     */
-    reconnectTarget(newPortId: string, newNodeId?: string): void;
-    /**
-     * Phase 1: Get source endpoint position
-     * Returns the first point in the path (source end)
-     */
-    getSourceEndpoint(): Point;
-    /**
-     * Phase 1: Get target endpoint position
-     * Returns the last point in the path (target end)
-     */
-    getTargetEndpoint(): Point;
-    /**
-     * Phase 1: Select source endpoint handle
-     */
-    selectSourceEndpoint(): void;
-    /**
-     * Phase 1: Select target endpoint handle
-     */
-    selectTargetEndpoint(): void;
-    /**
-     * Phase 1: Deselect all endpoint handles
-     */
-    deselectEndpoints(): void;
-    /**
-     * Phase 1: Check if any endpoint is selected
-     */
-    hasSelectedEndpoint(): boolean;
-    /**
-     * Get point at position along link (0-1)
-     */
-    getPointAtPosition(t: number): Point | null;
-    /**
-     * Get total path length
-     */
-    getTotalLength(): number;
-    /**
-     * Get segment length
-     */
-    private getSegmentLength;
-    /**
-     * Get point on segment
-     */
-    private getPointOnSegment;
-    /**
-     * Get path length (alias for getTotalLength for API consistency)
-     */
-    getLength(): number;
-    /**
-     * Get tangent (direction vector) at position along path (0-1)
-     * Returns normalized direction vector
-     */
-    getTangentAt(t: number): Point | null;
-    /**
-     * Get tangent on a specific segment
-     */
-    private getTangentOnSegment;
-    /**
-     * Get normal (perpendicular vector) at position along path (0-1)
-     * Returns normalized perpendicular vector (90° counter-clockwise from tangent)
-     */
-    getNormalAt(t: number): Point | null;
-    /**
-     * Get closest point on path to a given point
-     * Returns the closest point, distance, and normalized position (t)
-     */
-    getClosestPoint(point: Point): {
-        point: Point;
-        distance: number;
-        t: number;
-    } | null;
-    /**
-     * Get angle at position along path (0-1) in degrees
-     * Useful for label rotation
-     */
-    getAngleAt(t: number): number | null;
-    /**
-     * Serialize to JSON
-     */
-    serialize(): SerializedLink;
-    /**
-     * Deserialize from JSON
-     */
-    static fromJSON(data: SerializedLink): LinkModel;
-}