@pixerate/editor 0.212.0 → 0.213.0

package/dist/image-editor/path-edit.d.cts

@@ -0,0 +1,97 @@
+/**
+ * Framework-free logic behind the path tools of the React and Svelte image editors (Photoshop's
+ * Path Selection, Direct Selection and Pen): hit-testing anchors, handles and segments, dragging
+ * them (one undo step per drag, the target updated live while dragging), converting, inserting and
+ * deleting anchors, drawing new subpaths with the Pen, and the overlay to draw. They edit what
+ * `controller.pathEditTarget()` names: the active path, the active shape layer or the active
+ * layer's vector mask. The components only translate DOM events and draw `overlay()`.
+ */
+import type { ImageEditorController } from './controller.cjs';
+import type { CropBox, ImagePoint } from './types.cjs';
+/** The path tools: whole components (`path-select`), anchors and handles (`direct-select`), and the Pen (`path-pen`). */
+export type PathEditTool = 'path-select' | 'direct-select' | 'path-pen';
+export declare const PATH_EDIT_TOOLS: readonly PathEditTool[];
+export declare function isPathEditTool(tool: string): tool is PathEditTool;
+/** One anchor of a target: component, subpath and anchor index. */
+export interface PathAnchorRef {
+    component: number;
+    subpath: number;
+    anchor: number;
+}
+/** What `RenderOptions.pathEdit` draws, in document pixels. */
+export interface PathEditOverlay {
+    /** The target's segments: 2 points for a line, 4 for a cubic. */
+    curves: ImagePoint[][];
+    /** Anchors shown; selected ones are drawn filled. */
+    anchors: Array<{
+        point: ImagePoint;
+        selected: boolean;
+    }>;
+    /** Direction handles of the selected anchors, with the anchor each belongs to. */
+    handles: Array<{
+        point: ImagePoint;
+        anchor: ImagePoint;
+    }>;
+    /** A marquee being dragged to select anchors. */
+    marquee: CropBox | null;
+    /** The Pen's next segment, from the last anchor to the pointer (2 or 4 points). */
+    preview: ImagePoint[] | null;
+}
+export interface PathEditModifiers {
+    shift?: boolean;
+    alt?: boolean;
+}
+/**
+ * The path tools' pointer and key handling. Call `setView` with the screen pixels per document
+ * pixel so hits are a fixed size on screen; `down` / `move` / `up` take document pixels.
+ */
+export declare class PathEditGesture {
+    private readonly controller;
+    /** Selected anchors, as `component:subpath:anchor` keys. */
+    private selected;
+    private target;
+    private drag;
+    /** The Pen's open subpath being drawn. */
+    private drawing;
+    private pointer;
+    private scale;
+    error: string | null;
+    constructor(controller: ImageEditorController);
+    /** Screen pixels per document pixel (the viewport projection's scale). */
+    setView(scale: number): void;
+    get active(): boolean;
+    /** The anchors selected now (on the current target). */
+    get selection(): PathAnchorRef[];
+    /** True while the Pen has an open subpath it adds to. */
+    get isDrawing(): boolean;
+    private get tolerance();
+    /** The target's components, or null (and the selection dropped) when the target changed or is gone. */
+    private components;
+    private anchorAt;
+    /** A handle of a selected anchor near `p`. */
+    private handleAt;
+    /** The segment near `p`: its first anchor (as `anchor`) and the parameter on it. */
+    private segmentAt;
+    /** The component under `p`: on its outline, or inside its fill. */
+    private componentAt;
+    private selectComponent;
+    private commit;
+    down(p: ImagePoint, tool: PathEditTool, mods?: PathEditModifiers): void;
+    /** Alt-click: a corner anchor becomes smooth, a smooth one a corner (one undo step). */
+    private convert;
+    private penDown;
+    move(p: ImagePoint, mods?: PathEditModifiers): void;
+    /** The pointer moving with no button down (the Pen's preview of its next segment). */
+    hover(p: ImagePoint): void;
+    up(): void;
+    /** Ends the Pen's subpath (left open). */
+    finish(): void;
+    cancel(): void;
+    /**
+     * Keys: Delete / Backspace remove the selected anchors (one undo step), Enter and Escape end the
+     * Pen's subpath, Escape also deselects. Returns true when the key was handled.
+     */
+    key(k: string): boolean;
+    /** What to draw (`RenderOptions.pathEdit`) for `tool`, or null when there is no target. */
+    overlay(tool: PathEditTool): PathEditOverlay | null;
+}

package/dist/image-editor/path-edit.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Framework-free logic behind the path tools of the React and Svelte image editors (Photoshop's
+ * Path Selection, Direct Selection and Pen): hit-testing anchors, handles and segments, dragging
+ * them (one undo step per drag, the target updated live while dragging), converting, inserting and
+ * deleting anchors, drawing new subpaths with the Pen, and the overlay to draw. They edit what
+ * `controller.pathEditTarget()` names: the active path, the active shape layer or the active
+ * layer's vector mask. The components only translate DOM events and draw `overlay()`.
+ */
+import type { ImageEditorController } from './controller.js';
+import type { CropBox, ImagePoint } from './types.js';
+/** The path tools: whole components (`path-select`), anchors and handles (`direct-select`), and the Pen (`path-pen`). */
+export type PathEditTool = 'path-select' | 'direct-select' | 'path-pen';
+export declare const PATH_EDIT_TOOLS: readonly PathEditTool[];
+export declare function isPathEditTool(tool: string): tool is PathEditTool;
+/** One anchor of a target: component, subpath and anchor index. */
+export interface PathAnchorRef {
+    component: number;
+    subpath: number;
+    anchor: number;
+}
+/** What `RenderOptions.pathEdit` draws, in document pixels. */
+export interface PathEditOverlay {
+    /** The target's segments: 2 points for a line, 4 for a cubic. */
+    curves: ImagePoint[][];
+    /** Anchors shown; selected ones are drawn filled. */
+    anchors: Array<{
+        point: ImagePoint;
+        selected: boolean;
+    }>;
+    /** Direction handles of the selected anchors, with the anchor each belongs to. */
+    handles: Array<{
+        point: ImagePoint;
+        anchor: ImagePoint;
+    }>;
+    /** A marquee being dragged to select anchors. */
+    marquee: CropBox | null;
+    /** The Pen's next segment, from the last anchor to the pointer (2 or 4 points). */
+    preview: ImagePoint[] | null;
+}
+export interface PathEditModifiers {
+    shift?: boolean;
+    alt?: boolean;
+}
+/**
+ * The path tools' pointer and key handling. Call `setView` with the screen pixels per document
+ * pixel so hits are a fixed size on screen; `down` / `move` / `up` take document pixels.
+ */
+export declare class PathEditGesture {
+    private readonly controller;
+    /** Selected anchors, as `component:subpath:anchor` keys. */
+    private selected;
+    private target;
+    private drag;
+    /** The Pen's open subpath being drawn. */
+    private drawing;
+    private pointer;
+    private scale;
+    error: string | null;
+    constructor(controller: ImageEditorController);
+    /** Screen pixels per document pixel (the viewport projection's scale). */
+    setView(scale: number): void;
+    get active(): boolean;
+    /** The anchors selected now (on the current target). */
+    get selection(): PathAnchorRef[];
+    /** True while the Pen has an open subpath it adds to. */
+    get isDrawing(): boolean;
+    private get tolerance();
+    /** The target's components, or null (and the selection dropped) when the target changed or is gone. */
+    private components;
+    private anchorAt;
+    /** A handle of a selected anchor near `p`. */
+    private handleAt;
+    /** The segment near `p`: its first anchor (as `anchor`) and the parameter on it. */
+    private segmentAt;
+    /** The component under `p`: on its outline, or inside its fill. */
+    private componentAt;
+    private selectComponent;
+    private commit;
+    down(p: ImagePoint, tool: PathEditTool, mods?: PathEditModifiers): void;
+    /** Alt-click: a corner anchor becomes smooth, a smooth one a corner (one undo step). */
+    private convert;
+    private penDown;
+    move(p: ImagePoint, mods?: PathEditModifiers): void;
+    /** The pointer moving with no button down (the Pen's preview of its next segment). */
+    hover(p: ImagePoint): void;
+    up(): void;
+    /** Ends the Pen's subpath (left open). */
+    finish(): void;
+    cancel(): void;
+    /**
+     * Keys: Delete / Backspace remove the selected anchors (one undo step), Enter and Escape end the
+     * Pen's subpath, Escape also deselects. Returns true when the key was handled.
+     */
+    key(k: string): boolean;
+    /** What to draw (`RenderOptions.pathEdit`) for `tool`, or null when there is no target. */
+    overlay(tool: PathEditTool): PathEditOverlay | null;
+}

package/dist/image-editor/paths.d.cts

@@ -39,3 +39,17 @@ export declare function serializePaths(paths: readonly DocumentPath[]): Serializ
  * Path; ids are made unique.
  */
 export declare function readPaths(stored: unknown, problems?: string[]): DocumentPath[];
+/**
+ * What the path tools edit: a document path, a shape layer's components or a layer's vector mask
+ * (see `ImageEditorController.pathEditTarget`).
+ */
+export type PathEditTarget = {
+    kind: 'path';
+    id: string;
+} | {
+    kind: 'shape';
+    layerId: string;
+} | {
+    kind: 'vector-mask';
+    layerId: string;
+};

package/dist/image-editor/paths.d.ts

@@ -39,3 +39,17 @@ export declare function serializePaths(paths: readonly DocumentPath[]): Serializ
  * Path; ids are made unique.
  */
 export declare function readPaths(stored: unknown, problems?: string[]): DocumentPath[];
+/**
+ * What the path tools edit: a document path, a shape layer's components or a layer's vector mask
+ * (see `ImageEditorController.pathEditTarget`).
+ */
+export type PathEditTarget = {
+    kind: 'path';
+    id: string;
+} | {
+    kind: 'shape';
+    layerId: string;
+} | {
+    kind: 'vector-mask';
+    layerId: string;
+};

package/dist/image-editor/renderer.d.cts

@@ -1,3 +1,4 @@
+import type { PathEditOverlay } from './path-edit.cjs';
 import type { Annotation, CropBox, ImagePoint, ExportOptions, ImageEditorFit, ImageEditorState } from './types.cjs';
 import type { PixelTransform } from './color-management.cjs';
 import { type ImageHistogram } from './histogram.cjs';
@@ -80,6 +81,8 @@ export interface RenderOptions {
             }>;
         };
     } | null;
+    /** The path tools' target outline, anchors, handles, marquee and Pen preview in natural pixels (`PathEditGesture.overlay()`). */
+    pathEdit?: PathEditOverlay | null;
 }
 /**
  * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.

package/dist/image-editor/renderer.d.ts

@@ -1,3 +1,4 @@
+import type { PathEditOverlay } from './path-edit.js';
 import type { Annotation, CropBox, ImagePoint, ExportOptions, ImageEditorFit, ImageEditorState } from './types.js';
 import type { PixelTransform } from './color-management.js';
 import { type ImageHistogram } from './histogram.js';
@@ -80,6 +81,8 @@ export interface RenderOptions {
             }>;
         };
     } | null;
+    /** The path tools' target outline, anchors, handles, marquee and Pen preview in natural pixels (`PathEditGesture.overlay()`). */
+    pathEdit?: PathEditOverlay | null;
 }
 /**
  * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.

package/dist/image-editor/tool-groups.d.cts

@@ -25,8 +25,8 @@ export declare function imageToolForShortcut(key: string, shift?: boolean): Imag
 /** How a canvas handles pointer gestures for a tool (the Svelte and React canvases' `mode`). */
 export type ImageToolCanvasMode = 'transform' | 'crop' | 'select' | 'paint' | 'annotate';
 /**
- * The canvas mode a tool works in. Move picks and transforms layers; shapes, type and the
- * annotations draw in `annotate`.
+ * The canvas mode a tool works in. Move picks and transforms layers; shapes, type, the path tools
+ * and the annotations draw in `annotate`.
  */
 export declare function imageToolCanvasMode(tool: ImageEditorTool): ImageToolCanvasMode;
 /** The `layerPanels` panel holding a tool's options, or null when it has none. */

package/dist/image-editor/tool-groups.d.ts

@@ -25,8 +25,8 @@ export declare function imageToolForShortcut(key: string, shift?: boolean): Imag
 /** How a canvas handles pointer gestures for a tool (the Svelte and React canvases' `mode`). */
 export type ImageToolCanvasMode = 'transform' | 'crop' | 'select' | 'paint' | 'annotate';
 /**
- * The canvas mode a tool works in. Move picks and transforms layers; shapes, type and the
- * annotations draw in `annotate`.
+ * The canvas mode a tool works in. Move picks and transforms layers; shapes, type, the path tools
+ * and the annotations draw in `annotate`.
  */
 export declare function imageToolCanvasMode(tool: ImageEditorTool): ImageToolCanvasMode;
 /** The `layerPanels` panel holding a tool's options, or null when it has none. */

package/dist/image-editor/types.d.cts

@@ -280,7 +280,9 @@ export type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'a
 /** Live shape layers (see `ShapeDrawGesture`). */
  | 'shape'
 /** Live type layers, edited on the canvas (see `TypeToolGesture`). */
- | 'type';
+ | 'type'
+/** The path tools (see `PathEditGesture`): Path Selection, Direct Selection and the Pen for paths. */
+ | 'path-select' | 'direct-select' | 'path-pen';
 export type ImageEditorFit = 'contain' | 'margin';
 import type { DocumentColorMode, DocumentColorProfile, ProofSetup } from './color-management.cjs';
 import type { BitDepth } from '../raster/deep.cjs';

package/dist/image-editor/types.d.ts

@@ -280,7 +280,9 @@ export type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'a
 /** Live shape layers (see `ShapeDrawGesture`). */
  | 'shape'
 /** Live type layers, edited on the canvas (see `TypeToolGesture`). */
- | 'type';
+ | 'type'
+/** The path tools (see `PathEditGesture`): Path Selection, Direct Selection and the Pen for paths. */
+ | 'path-select' | 'direct-select' | 'path-pen';
 export type ImageEditorFit = 'contain' | 'margin';
 import type { DocumentColorMode, DocumentColorProfile, ProofSetup } from './color-management.js';
 import type { BitDepth } from '../raster/deep.js';