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

package/dist/editor/history.d.ts

@@ -0,0 +1,78 @@
+import { type Scene } from "../scene/schema.ts";
+/**
+ * Undo and redo for the editor, and the merge with a newer copy from the server (the ideas of
+ * smartgenius's editor draft). A step is a list of patches, one per field it changed, never a
+ * whole scene: a change that came from the server stays when someone undoes their own edit, and
+ * a server write takes only the fields it changed out of the history.
+ *
+ * A patch's path names one field:
+ * - `["scene", prop]`: size, theme, locale, slots, meta...
+ * - `["pages"]`: the order of the page ids
+ * - `["page", pageId, prop]`: a page's background, grain or name
+ * - `["layers", pageId]` and `["layers", pageId, groupId]`: the order of a list of layer ids
+ * - `["layer", pageId, layerId, prop]`: one prop of one layer, like its frame or its text
+ *
+ * A gesture records once, at release, with the scene from the press (editor.md rule E4). Edits
+ * that share a group (a typing session, a held arrow key) become one step, until the code that
+ * owns the group ends it with endEditGroup.
+ */
+export declare const HISTORY_LIMIT = 50;
+/** One field before and after an edit. A side is missing when the field did not exist. */
+export type ScenePatch = {
+    path: readonly string[];
+    before?: unknown;
+    after?: unknown;
+};
+export type EditHistory = {
+    /** Oldest first. */
+    undo: ScenePatch[][];
+    /** The next step to redo first. */
+    redo: ScenePatch[][];
+    /** The run of edits the last step belongs to, while it is open. */
+    group: string | null;
+};
+export type SceneMerge = {
+    /** Your scene with their changes in it, ready to show and save. */
+    scene: Scene;
+    /** What to compare against from now on: theirs, with the colliding fields left as they were,
+     *  so your side of a collision still counts as unsaved. */
+    base: Scene;
+    /** Fields both sides changed in different ways: their change, which `scene` does not have. */
+    conflicts: ScenePatch[];
+};
+/** Every field that differs between two scenes. */
+export declare function diffScenes(before: Scene, after: Scene): ScenePatch[];
+/**
+ * The scene with each patch's `before` or `after` side set. If the result is no longer a valid
+ * scene, the scene comes back unchanged.
+ */
+export declare function applyPatches(scene: Scene, patches: readonly ScenePatch[], side: "before" | "after"): Scene;
+export declare function emptyHistory(): EditHistory;
+/**
+ * Record an edit from `before` to `after`. With a `group` equal to the open one, the edit joins
+ * the last step, so a typing session or a held arrow key is one Undo.
+ */
+export declare function recordEdit(history: EditHistory, before: Scene, after: Scene, group?: string | null): EditHistory;
+/** Close the open run: the next edit starts a new step, even in the same group. */
+export declare function endEditGroup(history: EditHistory): EditHistory;
+export declare function undoEdit(history: EditHistory, scene: Scene): {
+    history: EditHistory;
+    scene: Scene;
+};
+export declare function redoEdit(history: EditHistory, scene: Scene): {
+    history: EditHistory;
+    scene: Scene;
+};
+/**
+ * After the server's copy moved from `before` to `server`, keep the history for every field the
+ * server did not change, so an unrelated edit stays undoable after a picture lands.
+ */
+export declare function rebaseHistory(history: EditHistory, before: Scene, server: Scene): EditHistory;
+/**
+ * Bring a newer server copy into your unsaved scene. `base` is the copy your edits started from.
+ * A field only they changed comes in; a field only you changed stays yours; a field you both
+ * changed differently keeps yours and comes back in `conflicts`, so the editor can show their
+ * change and offer "Use theirs" (applyPatches with the conflict's `after`) or "Keep mine".
+ * Lists of layers and pages merge as a whole: when you both changed one, yours stays.
+ */
+export declare function mergeScenes(draft: Scene, base: Scene, server: Scene): SceneMerge;

package/dist/editor/history.js

@@ -0,0 +1,221 @@
+import { canonical } from "../scene/render.js";
+import { layerSchema, sceneSchema } from "../scene/schema.js";
+/**
+ * Undo and redo for the editor, and the merge with a newer copy from the server (the ideas of
+ * smartgenius's editor draft). A step is a list of patches, one per field it changed, never a
+ * whole scene: a change that came from the server stays when someone undoes their own edit, and
+ * a server write takes only the fields it changed out of the history.
+ *
+ * A patch's path names one field:
+ * - `["scene", prop]`: size, theme, locale, slots, meta...
+ * - `["pages"]`: the order of the page ids
+ * - `["page", pageId, prop]`: a page's background, grain or name
+ * - `["layers", pageId]` and `["layers", pageId, groupId]`: the order of a list of layer ids
+ * - `["layer", pageId, layerId, prop]`: one prop of one layer, like its frame or its text
+ *
+ * A gesture records once, at release, with the scene from the press (editor.md rule E4). Edits
+ * that share a group (a typing session, a held arrow key) become one step, until the code that
+ * owns the group ends it with endEditGroup.
+ */
+export const HISTORY_LIMIT = 50;
+const keyOf = (path) => JSON.stringify(path);
+function same(a, b) {
+    return a === b || canonical(a) === canonical(b);
+}
+function put(fields, path, value) {
+    if (value === undefined)
+        fields.delete(keyOf(path));
+    else
+        fields.set(keyOf(path), { path, value });
+}
+/** The scene as one entry per field. Values are the scene's own objects, never copies. */
+function flatten(scene) {
+    const fields = new Map();
+    const props = (prefix, object, skip) => {
+        for (const [prop, value] of Object.entries(object))
+            if (!skip.includes(prop))
+                put(fields, [...prefix, prop], value);
+    };
+    props(["scene"], scene, ["pages"]);
+    put(fields, ["pages"], scene.pages.map((page) => page.id));
+    for (const page of scene.pages) {
+        props(["page", page.id], page, ["id", "layers"]);
+        const walk = (layers, list) => {
+            put(fields, list, layers.map((layer) => layer.id));
+            for (const layer of layers) {
+                props(["layer", page.id, layer.id], layer, ["id", "layers"]);
+                if (layer.type === "group")
+                    walk(layer.layers, ["layers", page.id, layer.id]);
+            }
+        };
+        walk(page.layers, ["layers", page.id]);
+    }
+    return fields;
+}
+const idsIn = (value) => Array.isArray(value) ? value.filter((id) => typeof id === "string") : [];
+/**
+ * The scene the fields describe, or undefined when they no longer make one. A layer whose
+ * fields no longer make a valid layer is left out, and so is one that no list holds.
+ */
+function unflatten(fields) {
+    const scene = {};
+    const pages = new Map();
+    const layers = new Map();
+    const objectFor = (map, key) => {
+        let object = map.get(key);
+        if (!object) {
+            object = {};
+            map.set(key, object);
+        }
+        return object;
+    };
+    for (const { path, value } of fields.values()) {
+        const [kind, a, b, c] = path;
+        if (kind === "scene" && a)
+            scene[a] = value;
+        else if (kind === "page" && a && b)
+            objectFor(pages, a)[b] = value;
+        else if (kind === "layer" && a && b && c)
+            objectFor(layers, keyOf([a, b]))[c] = value;
+    }
+    const placed = new Set();
+    /** The layers a list of ids names, at `path` (as flatten wrote it). */
+    const list = (pageId, path) => idsIn(fields.get(keyOf(path))?.value).flatMap((id) => {
+        const key = keyOf([pageId, id]);
+        const props = layers.get(key);
+        if (!props || placed.has(key))
+            return [];
+        placed.add(key);
+        const layer = props.type === "group"
+            ? { ...props, id, layers: list(pageId, ["layers", pageId, id]) }
+            : { ...props, id };
+        const parsed = layerSchema.safeParse(layer);
+        return parsed.success ? [parsed.data] : [];
+    });
+    const parsed = sceneSchema.safeParse({
+        ...scene,
+        pages: idsIn(fields.get(keyOf(["pages"]))?.value).map((id) => ({
+            ...pages.get(id),
+            id,
+            layers: list(id, ["layers", id]),
+        })),
+    });
+    return parsed.success ? parsed.data : undefined;
+}
+function diffFields(before, after) {
+    const patches = [];
+    for (const [key, field] of before) {
+        const next = after.get(key);
+        if (!same(field.value, next?.value))
+            patches.push({ path: field.path, before: field.value, after: next?.value });
+    }
+    for (const [key, field] of after)
+        if (!before.has(key))
+            patches.push({ path: field.path, after: field.value });
+    return patches;
+}
+/** Every field that differs between two scenes. */
+export function diffScenes(before, after) {
+    return diffFields(flatten(before), flatten(after));
+}
+/**
+ * The scene with each patch's `before` or `after` side set. If the result is no longer a valid
+ * scene, the scene comes back unchanged.
+ */
+export function applyPatches(scene, patches, side) {
+    if (patches.length === 0)
+        return scene;
+    const fields = flatten(scene);
+    for (const patch of patches)
+        put(fields, patch.path, patch[side]);
+    return unflatten(fields) ?? scene;
+}
+export function emptyHistory() {
+    return { undo: [], redo: [], group: null };
+}
+/**
+ * Record an edit from `before` to `after`. With a `group` equal to the open one, the edit joins
+ * the last step, so a typing session or a held arrow key is one Undo.
+ */
+export function recordEdit(history, before, after, group = null) {
+    const previous = group !== null && group === history.group ? history.undo.at(-1) : undefined;
+    const start = flatten(before);
+    // Where the run began: this edit's start with the run's earlier changes taken back.
+    if (previous)
+        for (const patch of previous)
+            put(start, patch.path, patch.before);
+    const step = diffFields(start, flatten(after));
+    const undo = previous ? history.undo.slice(0, -1) : history.undo;
+    // A run that came back to where it began leaves no step.
+    if (step.length === 0)
+        return previous ? { undo, redo: [], group: null } : history;
+    return { undo: [...undo, step].slice(-HISTORY_LIMIT), redo: [], group };
+}
+/** Close the open run: the next edit starts a new step, even in the same group. */
+export function endEditGroup(history) {
+    return history.group === null ? history : { ...history, group: null };
+}
+export function undoEdit(history, scene) {
+    const step = history.undo.at(-1);
+    if (!step)
+        return { history, scene };
+    return {
+        history: { undo: history.undo.slice(0, -1), redo: [step, ...history.redo], group: null },
+        scene: applyPatches(scene, step, "before"),
+    };
+}
+export function redoEdit(history, scene) {
+    const [step, ...rest] = history.redo;
+    if (!step)
+        return { history, scene };
+    return {
+        history: { undo: [...history.undo, step], redo: rest, group: null },
+        scene: applyPatches(scene, step, "after"),
+    };
+}
+/**
+ * After the server's copy moved from `before` to `server`, keep the history for every field the
+ * server did not change, so an unrelated edit stays undoable after a picture lands.
+ */
+export function rebaseHistory(history, before, server) {
+    const changed = new Set(diffScenes(before, server).map((patch) => keyOf(patch.path)));
+    if (changed.size === 0)
+        return endEditGroup(history);
+    const keep = (steps) => steps
+        .map((step) => step.filter((patch) => !changed.has(keyOf(patch.path))))
+        .filter((step) => step.length > 0);
+    return { undo: keep(history.undo), redo: keep(history.redo), group: null };
+}
+/**
+ * Bring a newer server copy into your unsaved scene. `base` is the copy your edits started from.
+ * A field only they changed comes in; a field only you changed stays yours; a field you both
+ * changed differently keeps yours and comes back in `conflicts`, so the editor can show their
+ * change and offer "Use theirs" (applyPatches with the conflict's `after`) or "Keep mine".
+ * Lists of layers and pages merge as a whole: when you both changed one, yours stays.
+ */
+export function mergeScenes(draft, base, server) {
+    const mine = flatten(draft);
+    const was = flatten(base);
+    const theirs = flatten(server);
+    if (diffFields(was, mine).length === 0)
+        return { scene: server, base: server, conflicts: [] };
+    const merged = new Map(mine);
+    const nextBase = new Map(theirs);
+    const conflicts = [];
+    const remote = diffFields(was, theirs);
+    for (const patch of remote) {
+        const own = mine.get(keyOf(patch.path))?.value;
+        if (same(own, patch.before))
+            put(merged, patch.path, patch.after);
+        else if (!same(own, patch.after)) {
+            conflicts.push(patch);
+            put(nextBase, patch.path, patch.before);
+        }
+    }
+    const scene = unflatten(merged);
+    const sceneBase = unflatten(nextBase);
+    // ponytail: fields that no longer make a scene together keep yours whole, against theirs.
+    if (!scene || !sceneBase)
+        return { scene: draft, base: server, conflicts: remote };
+    return { scene, base: sceneBase, conflicts };
+}

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;