@pixerate/editor 0.33.0 → 0.34.0

package/dist/vector/index.d.cts

@@ -1,4 +1,4 @@
-import { C as CanvasGradientDef, A as AffineMatrix, B as BezierPathInput, a as BezierPath, S as SvgGradientDef } from '../bezier-6KPx3w7Z.cjs';
+import { C as CanvasGradientDef, A as AffineMatrix, B as BezierPathInput, a as BezierPath, S as SvgGradientDef } from '../bezier-D8bsO-L0.cjs';
 import { P as Point } from '../types-BFkYA4eF.cjs';
 import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
 import { C as CommandSpec } from '../registry-D0GADKc7.cjs';
@@ -339,10 +339,222 @@ declare function parseSvgTransform(value: string | undefined): AffineMatrix;
 /** Parses SVG markup into a vector document. Throws when there is no `<svg>` element. */
 declare function parseVectorSvg(svg: string, options?: VectorSvgImportOptions): VectorDocument;
 
+/**
+ * What a guide line shows: `align` lines run from a target through the snapped point or box,
+ * `construction` lines from where a drawn point leaves, `spacing` marks equal gaps and `size`
+ * the side whose length matches another object's.
+ */
+type VectorGuideKind = 'align' | 'construction' | 'spacing' | 'size';
+/** A guide line in document units. */
+interface VectorGuideLine {
+    kind: VectorGuideKind;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** What a point or box snapped to. */
+type VectorSnapKind = 'anchor' | 'centre' | 'intersect' | 'perpendicular' | 'tangent' | 'path' | 'construction' | 'align' | 'spacing' | 'size';
+/** A guide label in document units: the snap kind's name, or a distance for gaps and sizes. */
+interface VectorGuideLabel {
+    kind: VectorSnapKind;
+    x: number;
+    y: number;
+    text: string;
+}
+interface VectorSnapGuides {
+    lines: VectorGuideLine[];
+    labels: VectorGuideLabel[];
+}
+interface VectorPointSnap extends VectorSnapGuides {
+    point: Vec2;
+    /** The rule that placed the point, or null when nothing was in reach. */
+    kind: VectorSnapKind | null;
+    /** Whether x / y were set by a target (for falling back to the grid on the other axis). */
+    x: boolean;
+    y: boolean;
+}
+interface VectorRectSnap extends VectorSnapGuides {
+    /** Correction to add to the move. */
+    dx: number;
+    dy: number;
+    x: boolean;
+    y: boolean;
+}
+interface VectorScaleSnap extends VectorSnapGuides {
+    sx: number;
+    sy: number;
+    snapped: boolean;
+}
+/**
+ * The point a drawn point leaves from (the anchor before it, a shape's start, a handle's
+ * anchor) and how it keeps to it.
+ */
+interface VectorSnapLeave {
+    at: Vec2;
+    /**
+     * Shift held: keep to 45° steps round `at` (`angle`), to a diagonal (`square`, a box's
+     * corner) or to the nearer axis (`axis`, a dragged point).
+     */
+    constrain?: 'angle' | 'square' | 'axis' | null;
+    /** Construction guide angles through `at`, degrees counter-clockwise on screen. */
+    angles?: readonly number[];
+    /** Snap to the perpendicular foot and tangent points from `at` on paths (default true). */
+    curves?: boolean;
+}
+/** The construction guide angles new editors start with. */
+declare const VECTOR_CONSTRUCTION_ANGLES: readonly number[];
+/** Where `constrain` puts `p` (unchanged without one). */
+declare function constrainToLeave(leave: VectorSnapLeave | null | undefined, p: Vec2): Vec2;
+/**
+ * Snap targets in document space, gathered once per gesture. Build them with `forMove`,
+ * `forResize`, `forDrawing`, `forAnchorDrag` or `forHandle`, then call `snapFrom`,
+ * `snapRect` or `snapScale` on every pointer move. Tolerances are in document units (screen
+ * pixels divided by the zoom).
+ */
+declare class VectorSnapTargets {
+    private readonly points;
+    private readonly xs;
+    private readonly ys;
+    private readonly segments;
+    /** Bounds of the objects a moved box spaces itself evenly with. */
+    private readonly boxes;
+    /** Side lengths of the other objects (in their own frames), which a resize may match. */
+    private readonly sizes;
+    private constructor();
+    /** How many targets of each sort were gathered. */
+    get counts(): {
+        points: number;
+        lines: number;
+        segments: number;
+        boxes: number;
+    };
+    /** Targets for moving nodes `ids`: the other art's anchors, bounds and centres, the artboard, and boxes to space evenly with. */
+    static forMove(doc: VectorDocument, ids: readonly string[]): VectorSnapTargets;
+    /** Targets for resizing nodes `ids`: as for a move, plus the other objects' sizes. */
+    static forResize(doc: VectorDocument, ids: readonly string[]): VectorSnapTargets;
+    /**
+     * Targets for a drawn point (pen, shape tools): the art but `exclude`, its anchors (as
+     * points and in line), centres, edges and segments. The anchors and segments of `exclude`
+     * (the path being drawn, whose bounds grow with it) stay targets.
+     */
+    static forDrawing(doc: VectorDocument, exclude?: readonly string[]): VectorSnapTargets;
+    /**
+     * Targets for dragging anchors: the other art with its segments, and the anchors and
+     * segments that stay put on the paths being reshaped (their bounds move along, so they are
+     * no targets). The moving anchors are left out.
+     */
+    static forAnchorDrag(doc: VectorDocument, anchors: readonly VectorAnchorRef[]): VectorSnapTargets;
+    /**
+     * Targets for dragging a handle of path `nodeId`: the other art and that path's anchors
+     * (its bounds and the segments through the handle move with it, so they would chase it).
+     */
+    static forHandle(doc: VectorDocument, nodeId: string): VectorSnapTargets;
+    /** The anchors of the paths `ids` as targets (on them and in line), and their segments when `segments`. */
+    private pushPaths;
+    private pushAnchor;
+    /** The segments of `sp` (mapped by `m`) that stay put while the anchors `moving` accepts move. */
+    private pushSegments;
+    private pushRect;
+    /** Sorts the targets for `within` (stable: of targets alike, the first gathered wins). */
+    private index;
+    /**
+     * Gathers targets from the artboard and every visible node but `exclude` (and what is inside
+     * those): each leaf's anchors (also as lines for `drawing`), its segments (`segments`,
+     * `drawing`), its bounds' corners as lines and its centre; and the top-level objects' boxes and
+     * sizes (inside a group holding an excluded node, that group's other members).
+     */
+    private static collect;
+    /** Snaps a single point (see `snapFrom`). */
+    snapPoint(p: Vec2, tol: number): VectorPointSnap;
+    /**
+     * Snaps a point `p`, drawn or dragged from `leave` when given. With `leave.constrain` it keeps
+     * to its angle round `leave.at`, sliding along that way into line with the nearest target.
+     * Otherwise it lands, in order, on an anchor or centre, an intersection of two paths, the
+     * perpendicular foot or a tangent point from `leave.at`, a path, a construction guide
+     * through `leave.at` (where a target's line crosses it if one does nearby), or else lines up
+     * with targets on x and y.
+     */
+    snapFrom(p: Vec2, leave: VectorSnapLeave | null | undefined, tol: number): VectorPointSnap;
+    private label;
+    /** The anchor or centre nearest `p`, within `tol`. */
+    private nearestPoint;
+    /**
+     * Slides `q`, on the line through `at` along `dir` (beyond `at` only for a `ray`), to where
+     * the nearest target line crosses it, at most twice `tol` away: where it lands and the
+     * target point that line comes from.
+     */
+    private slide;
+    /** The guides of a point `q` slid into line with the target at `from`: the line and "align", or the target's own label when `q` sits on it. */
+    private linedUp;
+    /** Target segments whose control box reaches `p` and which pass within `tol` of it, nearest first. */
+    private segmentsNear;
+    private onSegment;
+    /** Where two of the target segments near `p` cross, the crossing nearest `p` within `tol`. */
+    private crossing;
+    /**
+     * The foot of a perpendicular, or a tangent point, from `base` on a target segment near `p`
+     * (within `tol` of it): roots of `(B(t) − base) · B′(t)` and `(B(t) − base) × B′(t)`
+     * bracketed by sign changes of samples and narrowed by bisection.
+     */
+    private curvePoint;
+    /**
+     * Snaps a moving box `r` (the moved selection's bounds): its edge or centre nearest a target
+     * line on each axis (`axes` limits which may move). With `spacing`, an axis that lines up
+     * with nothing spaces the box evenly in its row or column. Returns the correction and guides.
+     */
+    snapRect(r: VectorBounds, tol: number, options?: {
+        spacing?: boolean;
+        axes?: {
+            x?: boolean;
+            y?: boolean;
+        };
+    }): VectorRectSnap;
+    /**
+     * Equal spacing along x (`horizontal`) or y for the moved box `r`, among the objects of its
+     * row (column): the shift within `tol` that centres it between its neighbours, or leaves it
+     * as far from the neighbour before or after it as two other objects of the row are apart;
+     * and the gaps that are equal then, as (start, end, where across).
+     */
+    private evenSpacing;
+    /** A gap mark: a line across the gap with a tick at each end, and its length as a label. */
+    private gapMarks;
+    /** The other objects' side length nearest `length`, within `tol`, or null. */
+    matchSize(length: number, tol: number): number | null;
+    /**
+     * Snaps a selection-box resize. `sx / sy` are the scale `scaleFor` gave for dragging
+     * `handle` of `frame` (in the box's own, possibly rotated frame), `mods.shift` keeps the
+     * proportions and `mods.alt` scales about the centre. The handle lands on an anchor or
+     * centre within `tol`, else the corner or the side it moves lines up with the nearest
+     * target, whatever the box's angle; a handle with one way to go (a side, or a proportional
+     * corner) slides along it until one of them is on a target. An axis that snaps to nothing
+     * may match another object's width or height instead.
+     */
+    snapScale(frame: VectorBounds & {
+        angle: number;
+    }, handle: Exclude<VectorTransformHandle, 'rotate'>, sx: number, sy: number, mods: {
+        shift?: boolean;
+        alt?: boolean;
+    }, tol: number): VectorScaleSnap;
+}
+
 interface VectorSnapOptions {
-    /** Grid size in document units (0 = off, default 0). */
+    /** Grid size in document units (0 = off, default 0). Points and boxes that snap to no object snap to it. */
     grid: number;
+    /**
+     * Snap to other objects (default true): anchors, paths and their intersections, bounding-box
+     * edges and centres, the artboard, construction angles, equal spacing and matching sizes.
+     */
+    objects: boolean;
+    /** Show smart guide lines and labels while snapping (default true). */
+    guides: boolean;
+    /** How near a target pulls, in screen pixels (default 5). */
+    threshold: number;
+    /** Construction guide angles through the point a drawn point leaves from, in degrees (default 0, 45, 90, 135). */
+    angles: readonly number[];
 }
+/** Snap options new editors start with. Hold Cmd / Ctrl (`mod`) during a drag to bypass snapping. */
+declare const DEFAULT_VECTOR_SNAP: Readonly<VectorSnapOptions>;
 interface VectorEditorOptions {
     document?: VectorDocument;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
@@ -435,6 +647,8 @@ interface VectorEditorState {
     viewport: VectorViewport;
     defaults: Readonly<Required<Pick<VectorDefaults, 'polygonSides' | 'starPoints' | 'starInnerRatio' | 'cornerRadius'>> & VectorStyle>;
     snap: VectorSnapOptions;
+    /** Smart guides of the snap in progress, in document units (null when there are none). */
+    guides: VectorSnapGuides | null;
     hitRadius: number;
     hover: VectorHover | null;
     /** A CSS cursor for the canvas. */
@@ -575,6 +789,11 @@ declare class VectorEditorController {
     private pointer;
     private drag;
     private interaction;
+    private guides;
+    /** Whether the last `snapDrawn` landed on an object (guides may be hidden). */
+    private snappedToObject;
+    /** Drawing targets for hovering the pen and shape tools, kept while the document and the excluded path stay the same. */
+    private hoverTargets;
     private spaceHeld;
     private clipboard;
     private readonly createId;
@@ -636,8 +855,23 @@ declare class VectorEditorController {
     setTool(tool: VectorTool): void;
     setDefaults(defaults: Partial<VectorDefaults>): void;
     setSnap(snap: Partial<VectorSnapOptions>): void;
+    /** Turns object snapping on or off (the toolbar's snapping toggle). */
+    toggleSnapping(on?: boolean): void;
+    private gridValue;
     private snapPoint;
-    private snapDelta;
+    /** The pull distance in document units. */
+    private snapTolerance;
+    private setGuides;
+    /**
+     * Where a drawn or dragged point `p` goes: onto the smart guide `targets` (gathered by
+     * `gather` when missing), else onto the grid, kept to `leave`'s constraint. Cmd / Ctrl
+     * bypasses snapping.
+     */
+    private snapDrawn;
+    /** Drawing targets for the pen and shape tools, reused while the document stays the same. */
+    private drawingTargets;
+    /** Where the pointer at `p` would place a point with the pen or a shape tool (and the guides showing why). */
+    private hoverSnap;
     /** Replaces the document. Undoable unless `{ history: false }` (then history is cleared). */
     setDocument(doc: VectorDocument, options?: {
         history?: boolean;
@@ -832,6 +1066,12 @@ declare class VectorEditorController {
     private downShape;
     /** Pointer moved over the canvas (with or without a button down). */
     pointerMove(screen: Vec2, input?: VectorPointerInput): void;
+    /** Snaps a move of the selection by (dx, dy): its bounds line up with targets or space evenly, else go to the grid. */
+    private snapMove;
+    /** The anchor a point drag snaps by, where it started: the grabbed one, else the moving one nearest the press. */
+    private leadAnchor;
+    /** A shape's dragged corner moved so its width or height matches another object's, when one is within reach. */
+    private matchShapeSize;
     /** Primary button released. */
     pointerUp(screen?: Vec2, input?: VectorPointerInput): void;
     /** The pointer left the canvas. */
@@ -910,6 +1150,21 @@ interface VectorRenderHandle {
     anchorY: number;
     hovered: boolean;
 }
+/** A smart guide line in screen pixels. */
+interface VectorRenderGuideLine {
+    kind: VectorGuideKind;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** A smart guide label ("anchor", "intersect", "align", "centre", a gap or a size) at a screen position. */
+interface VectorRenderGuideLabel {
+    kind: VectorSnapKind;
+    x: number;
+    y: number;
+    text: string;
+}
 interface VectorOverlayRenderData {
     /** Outlines (screen-space path data) of hovered and selected nodes. */
     outlines: {
@@ -936,6 +1191,11 @@ interface VectorOverlayRenderData {
     penPreview: string | null;
     /** Artboard rectangle, screen space. */
     artboard: VectorBounds;
+    /** Smart guides of the snap in progress, screen space (empty when nothing snapped). */
+    guides: {
+        lines: VectorRenderGuideLine[];
+        labels: VectorRenderGuideLabel[];
+    };
     /** A short status, e.g. "W 120 × H 80" or "45°". */
     status: string | null;
 }
@@ -951,6 +1211,8 @@ declare function getVectorOverlayRenderData(state: VectorEditorState): VectorOve
 /** Colours and sizes (screen pixels) the bundled canvases draw the overlay with. */
 declare const VECTOR_OVERLAY_THEME: {
     readonly accent: "#0ea5e9";
+    /** Smart guide lines and labels. */
+    readonly guide: "#ff3dfc";
     readonly handleFill: "#ffffff";
     readonly marqueeFill: "rgba(14, 165, 233, 0.08)";
     readonly transformHandleSize: 8;
@@ -1049,4 +1311,4 @@ interface VectorNodeListing {
  */
 declare function createVectorCommands(controller: VectorEditorController, options?: VectorCommandOptions): CommandSpec[];
 
-export { type AddVectorNodeOptions, AffineMatrix, IDENTITY_MATRIX, KAPPA, type NearestSegment, SvgGradientDef, VECTOR_CLIPBOARD_TYPE, VECTOR_OVERLAY_THEME, VECTOR_ROTATE_HANDLE_OFFSET, VECTOR_TOOLS, VECTOR_TOOL_GLYPHS, VECTOR_TOOL_SHORTCUTS, VECTOR_TRANSFORM_HANDLES, type Vec2, type VectorActionResult, type VectorAlign, type VectorAnchor, type VectorAnchorRef, type VectorAnchorType, type VectorArrange, type VectorBooleanOperation, type VectorBounds, type VectorCommandOptions, type VectorDefaults, type VectorDistribute, type VectorDocument, VectorEditorController, type VectorEditorOptions, type VectorEditorState, type VectorFillRule, type VectorGroupNode, type VectorHandleRef, type VectorHover, type VectorInteraction, type VectorKeyInput, type VectorLineCap, type VectorLineJoin, type VectorMatrix, type VectorModifiers, type VectorNode, type VectorNodeListing, type VectorOverlayRenderData, type VectorPaint, type VectorPathNode, type VectorPointerInput, type VectorRenderAnchor, type VectorRenderGroup, type VectorRenderHandle, type VectorRenderNode, type VectorRenderPath, type VectorSceneRenderData, type VectorSelectionBoxGeometry, type VectorSelectionFrame, type VectorSelectionStyle, type VectorShapeInput, type VectorSnapOptions, type VectorStyle, type VectorSubpath, type VectorSvgExportOptions, type VectorSvgImportOptions, type VectorTool, type VectorTransformHandle, type VectorViewport, applyMatrix, applyMatrixLinear, bezierToSubpaths, boundsFromPoints, boundsIntersect, cloneAnchor, cloneSubpath, cloneVectorDocument, cloneVectorNode, collectPathNodes, convertAnchor, createVectorCommands, decomposeRigid, ellipseSubpath, findVectorNode, getAnchor, getAnchorWorld, getEditablePathIds, getTransformHandlePositions, getVectorOverlayRenderData, getVectorSceneRenderData, getVectorSelectionBoxGeometry, getVectorSelectionFrame, getVectorSelectionStyle, getVisibleAnchors, getVisibleHandles, hasPaint, hitTestVectorNode, hitTestVectorNodes, inferAnchorType, insertAnchor, invertMatrix, isIdentityMatrix, isVectorTextTarget, lineSubpath, locateVectorNode, matrixRotation, moveAnchorHandle, multiplyMatrices, nearestSegment, nodeMatrix, parseSvgTransform, parseVectorSvg, polygonSubpath, rectSubpath, removeAnchors, reverseSubpath, rotateMatrix, roundSubpaths, scaleFor, scaleMatrix, starSubpath, subpathSegment, subpathSegmentCount, subpathsToBezier, toVectorKeyInput, toVectorModifiers, toVectorPointerInput, transformVectorNode, translateAnchor, translateMatrix, unionBounds, vectorDocumentToSvg, vectorNodeBounds, vectorNodeRotation, vectorNodeToBezier, vectorPaintToHex, vectorPaintToSvg, vectorParentMatrix, vectorPathData, vectorPathWorldBezier, vectorResizeCursor, vectorToolLabel, vectorWorldMatrix, walkVectorNodes };
+export { type AddVectorNodeOptions, AffineMatrix, DEFAULT_VECTOR_SNAP, IDENTITY_MATRIX, KAPPA, type NearestSegment, SvgGradientDef, VECTOR_CLIPBOARD_TYPE, VECTOR_CONSTRUCTION_ANGLES, VECTOR_OVERLAY_THEME, VECTOR_ROTATE_HANDLE_OFFSET, VECTOR_TOOLS, VECTOR_TOOL_GLYPHS, VECTOR_TOOL_SHORTCUTS, VECTOR_TRANSFORM_HANDLES, type Vec2, type VectorActionResult, type VectorAlign, type VectorAnchor, type VectorAnchorRef, type VectorAnchorType, type VectorArrange, type VectorBooleanOperation, type VectorBounds, type VectorCommandOptions, type VectorDefaults, type VectorDistribute, type VectorDocument, VectorEditorController, type VectorEditorOptions, type VectorEditorState, type VectorFillRule, type VectorGroupNode, type VectorGuideKind, type VectorGuideLabel, type VectorGuideLine, type VectorHandleRef, type VectorHover, type VectorInteraction, type VectorKeyInput, type VectorLineCap, type VectorLineJoin, type VectorMatrix, type VectorModifiers, type VectorNode, type VectorNodeListing, type VectorOverlayRenderData, type VectorPaint, type VectorPathNode, type VectorPointSnap, type VectorPointerInput, type VectorRectSnap, type VectorRenderAnchor, type VectorRenderGroup, type VectorRenderGuideLabel, type VectorRenderGuideLine, type VectorRenderHandle, type VectorRenderNode, type VectorRenderPath, type VectorScaleSnap, type VectorSceneRenderData, type VectorSelectionBoxGeometry, type VectorSelectionFrame, type VectorSelectionStyle, type VectorShapeInput, type VectorSnapGuides, type VectorSnapKind, type VectorSnapLeave, type VectorSnapOptions, VectorSnapTargets, type VectorStyle, type VectorSubpath, type VectorSvgExportOptions, type VectorSvgImportOptions, type VectorTool, type VectorTransformHandle, type VectorViewport, applyMatrix, applyMatrixLinear, bezierToSubpaths, boundsFromPoints, boundsIntersect, cloneAnchor, cloneSubpath, cloneVectorDocument, cloneVectorNode, collectPathNodes, constrainToLeave, convertAnchor, createVectorCommands, decomposeRigid, ellipseSubpath, findVectorNode, getAnchor, getAnchorWorld, getEditablePathIds, getTransformHandlePositions, getVectorOverlayRenderData, getVectorSceneRenderData, getVectorSelectionBoxGeometry, getVectorSelectionFrame, getVectorSelectionStyle, getVisibleAnchors, getVisibleHandles, hasPaint, hitTestVectorNode, hitTestVectorNodes, inferAnchorType, insertAnchor, invertMatrix, isIdentityMatrix, isVectorTextTarget, lineSubpath, locateVectorNode, matrixRotation, moveAnchorHandle, multiplyMatrices, nearestSegment, nodeMatrix, parseSvgTransform, parseVectorSvg, polygonSubpath, rectSubpath, removeAnchors, reverseSubpath, rotateMatrix, roundSubpaths, scaleFor, scaleMatrix, starSubpath, subpathSegment, subpathSegmentCount, subpathsToBezier, toVectorKeyInput, toVectorModifiers, toVectorPointerInput, transformVectorNode, translateAnchor, translateMatrix, unionBounds, vectorDocumentToSvg, vectorNodeBounds, vectorNodeRotation, vectorNodeToBezier, vectorPaintToHex, vectorPaintToSvg, vectorParentMatrix, vectorPathData, vectorPathWorldBezier, vectorResizeCursor, vectorToolLabel, vectorWorldMatrix, walkVectorNodes };