@ideare/kit 0.0.0-stage → 0.1.0-next.1

package/dist/editor/operations.d.ts

@@ -0,0 +1,112 @@
+import { type Guides, type Handle, type Point } from "../scene/frame.ts";
+import type { Frame, Layer, Lock, Scene } from "../scene/schema.ts";
+/**
+ * The editor's scene operations: pure functions from a scene to a new scene, with no DOM, so the
+ * studio, an agent and a test all edit the same way (docs/spikes/editor.md). Layers are found by
+ * id on a page, inside groups too. Positions come in the page's space and are turned into each
+ * layer's own parent space here, so a layer inside a turned group still follows the finger.
+ * Layers an operation does not touch keep their objects, so an editor can skip them.
+ *
+ * A gesture is computed from the scene at the press on every frame (`resizeLayers(start, ...)`),
+ * never from the last frame, so rounding never adds up.
+ */
+/** What an operation that changes the picked layers gives back: the scene and the new pick. */
+export type Edit = {
+    scene: Scene;
+    selection: string[];
+};
+export type AlignMode = "left" | "center" | "right" | "top" | "middle" | "bottom";
+export type ZOrder = "front" | "forward" | "backward" | "back";
+/** How far a copy lands from its original, down and to the right, in design units. */
+export declare const DUPLICATE_OFFSET = 24;
+/** The most pages a scene holds, as its schema says. */
+export declare const MAX_PAGES = 20;
+/**
+ * Path data scaled by kx across and ky down. ponytail: an arc's radii scale with the axes, which
+ * is exact for upright arcs only, and data whose numbers do not split into whole commands (arc
+ * flags written with no space, like `a1 1 0 0110 10`) comes back unchanged.
+ */
+export declare function scalePath(d: string, kx: number, ky: number): string;
+/** The page-space frame of a layer and the layer itself, found by id anywhere on the page. */
+export declare function findLayer(scene: Scene, page: number, id: string): {
+    layer: Layer;
+    frame: Frame;
+} | undefined;
+/**
+ * The box the editor draws around the pick: one layer's own frame, turned with it, or the
+ * upright box around several. Its `rotate` is where a turn gesture starts.
+ */
+export declare function selectionFrame(scene: Scene, page: number, ids: readonly string[]): Frame | undefined;
+/**
+ * Where a moving pick can land: the page's edges and middle, and the edges and middles of the
+ * other visible layers on the page. Feed it to snapBox with the stage's scale.
+ */
+export declare function snapTargets(scene: Scene, page: number, ids: readonly string[]): Guides;
+/** Put a layer on top of the page. Ids already taken on the page get a number. */
+export declare function addLayer(scene: Scene, page: number, layer: Layer): Edit;
+/** Take layers off the page. Locked ones stay, and stay picked. */
+export declare function removeLayers(scene: Scene, page: number, ids: readonly string[]): Edit;
+/** A copy of each picked layer right above it, moved by `offset` on the page. */
+export declare function duplicateLayers(scene: Scene, page: number, ids: readonly string[], offset?: number): Edit;
+/** Move the picked layers by dx and dy on the page. Layers locked in place stay. */
+export declare function moveLayers(scene: Scene, page: number, ids: readonly string[], dx: number, dy: number): Scene;
+/**
+ * Pull a handle of the pick to `to`, a point on the page (the handle's start plus the pointer's
+ * travel), from the scene at the press. One layer resizes in its own turned frame with the
+ * opposite corner or side held still; a corner also scales its type, radii and strokes, and a
+ * group's layers. Several layers, and a group, resize from the corners only: the box around
+ * them scales, and every layer in it, about the opposite corner.
+ */
+export declare function resizeLayers(start: Scene, page: number, ids: readonly string[], handle: Handle, to: Point, options?: {
+    min?: number;
+    keepRatio?: boolean;
+}): Scene;
+/**
+ * Turn the pick to `angle` degrees, from the scene at the press. One layer turns about its own
+ * center to that angle. Several turn together by `angle` about the center of the box around
+ * them, which starts every gesture upright (selectionFrame's `rotate` is 0). Use turnAngle for
+ * the angle a handle gives.
+ */
+export declare function rotateLayers(start: Scene, page: number, ids: readonly string[], angle: number): Scene;
+/**
+ * Line the pick up: one layer with the page, several with the box around them. It uses each
+ * layer's upright box, so a turned layer lines up by what it covers.
+ */
+export declare function alignLayers(scene: Scene, page: number, ids: readonly string[], mode: AlignMode): Scene;
+/**
+ * Space three or more layers evenly: the first and the last stay, and the gaps between the
+ * others' upright boxes become equal. Layers locked in place are left out.
+ */
+export declare function distributeLayers(scene: Scene, page: number, ids: readonly string[], direction: "horizontal" | "vertical"): Scene;
+/**
+ * Change the drawing order: to the front or the back of their list, or one step past the next
+ * layer that is not picked. Picked layers keep their order among themselves, and a layer inside
+ * a group moves within its group.
+ */
+export declare function reorderLayers(scene: Scene, page: number, ids: readonly string[], order: ZOrder): Scene;
+/**
+ * Put two or more layers that share a list into one group, where the top one of them was. The
+ * group is the upright box around them, and they keep their place on the page.
+ */
+export declare function groupLayers(scene: Scene, page: number, ids: readonly string[], id?: string): Edit;
+/**
+ * Break picked groups apart: their layers take the group's place, keep their place on the page,
+ * and take on the group's opacity and hidden state. ponytail: a group's blend mode goes to each
+ * layer that has none, which blends them one by one instead of as one picture.
+ */
+export declare function ungroupLayers(scene: Scene, page: number, ids: readonly string[]): Edit;
+/** Lock the picked layers (true: all five locks), unlock them (false), or set some locks. */
+export declare function lockLayers(scene: Scene, page: number, ids: readonly string[], lock: Lock | boolean): Scene;
+/**
+ * A text box's new height (from its lines, as someone types), with its turned top-left corner
+ * held still, so turned text never slides (rule E2).
+ */
+export declare function setTextHeight(scene: Scene, page: number, id: string, h: number): Scene;
+/** A blank page at `at` (the end by default), on the same background as the page before it. */
+export declare function addPage(scene: Scene, at?: number): Scene;
+/** A copy of a page, right after it. */
+export declare function duplicatePage(scene: Scene, index: number): Scene;
+/** Take a page out. The last page always stays. */
+export declare function removePage(scene: Scene, index: number): Scene;
+/** Move a page from one place in the order to another. */
+export declare function movePage(scene: Scene, from: number, to: number): Scene;