@grida/svg-editor 1.0.0-alpha.4 → 1.0.0

package/dist/presets.d.mts

@@ -1,5 +1,7 @@
-import { o as SvgEditor } from "./editor-Uu6dZX4y.mjs";
-import { n as DomSurfaceOptions, t as DomSurfaceHandle } from "./dom-DJnZhtOd.mjs";
+import { c as SvgEditor } from "./editor-CZgwg8BK.mjs";
+import { n as DomSurfaceHandle, r as DomSurfaceOptions } from "./dom-BEjG2bSw.mjs";
+
+//#region src/presets/keynote.d.ts
 declare namespace keynote_d_exports {
   export { KeynoteAttachOptions, KeynoteSurfaceHandle, attach };
 }
@@ -10,6 +12,13 @@ type KeynoteAttachOptions = {
    * Used for both initial fit and the cover-constraint clamp. Default 80.
    */
   padding?: number;
+  /**
+   * Screen-pixel scroll slack past the slide edge when zoomed in past fit.
+   * Forwarded to the cover constraint's `pan_overshoot`. Default 0 — strict
+   * cover behavior (no panning past the slide edge). Applies only when an
+   * axis is scrollable; a fitted axis stays locked at center.
+   */
+  pan_overshoot?: number;
   /**
    * Forward additional surface options (e.g. `gestures: false`). `container`,
    * `fit`, and `initial_camera` are owned by the preset.
@@ -27,6 +36,12 @@ type KeynoteSurfaceHandle = DomSurfaceHandle & {
    * the captured padding used by load-triggered refits.
    */
   set_padding(p: number): void;
+  /**
+   * Update the scroll-past slack at runtime. Mutates the live constraint;
+   * `reenforce()` pulls a previously over-panned transform back into the
+   * new range when the value is decreased.
+   */
+  set_pan_overshoot(o: number): void;
 };
 /**
  * Attach a keynote-shaped DOM surface:

package/dist/presets.d.ts

@@ -1,5 +1,7 @@
-import { o as SvgEditor } from "./editor-D2l_CDr0.js";
-import { n as DomSurfaceOptions, t as DomSurfaceHandle } from "./dom-Cn-RtjRL.js";
+import { c as SvgEditor } from "./editor-kFTYSb_8.js";
+import { n as DomSurfaceHandle, r as DomSurfaceOptions } from "./dom-Y2QR7QSi.js";
+
+//#region \0rolldown/runtime.js
 declare namespace keynote_d_exports {
   export { KeynoteAttachOptions, KeynoteSurfaceHandle, attach };
 }
@@ -10,6 +12,13 @@ type KeynoteAttachOptions = {
    * Used for both initial fit and the cover-constraint clamp. Default 80.
    */
   padding?: number;
+  /**
+   * Screen-pixel scroll slack past the slide edge when zoomed in past fit.
+   * Forwarded to the cover constraint's `pan_overshoot`. Default 0 — strict
+   * cover behavior (no panning past the slide edge). Applies only when an
+   * axis is scrollable; a fitted axis stays locked at center.
+   */
+  pan_overshoot?: number;
   /**
    * Forward additional surface options (e.g. `gestures: false`). `container`,
    * `fit`, and `initial_camera` are owned by the preset.
@@ -27,6 +36,12 @@ type KeynoteSurfaceHandle = DomSurfaceHandle & {
    * the captured padding used by load-triggered refits.
    */
   set_padding(p: number): void;
+  /**
+   * Update the scroll-past slack at runtime. Mutates the live constraint;
+   * `reenforce()` pulls a previously over-panned transform back into the
+   * new range when the value is decreased.
+   */
+  set_pan_overshoot(o: number): void;
 };
 /**
  * Attach a keynote-shaped DOM surface:

package/dist/presets.js

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dom = require("./dom-CoVZzFqy.js");
+const require_model = require("./model-tywvTGZv.js");
+const require_dom = require("./dom-DYD1BHTo.js");
 //#region src/presets/keynote.ts
-var keynote_exports = /* @__PURE__ */ require_dom.__exportAll({ attach: () => attach });
+var keynote_exports = /* @__PURE__ */ require_model.__exportAll({ attach: () => attach });
 /**
 * Attach a keynote-shaped DOM surface:
 * - Mounts via `attach_dom_surface` with `fit: true` (slide is visible on
@@ -16,30 +17,34 @@ var keynote_exports = /* @__PURE__ */ require_dom.__exportAll({ attach: () => at
 * additionally tears down the load subscription.
 */
 function attach(editor, opts) {
-	let padding = opts.padding ?? 80;
 	const inner = require_dom.attach_dom_surface(editor, {
 		...opts.surface,
 		container: opts.container,
 		fit: true
 	});
-	inner.camera.constraints = {
-		type: "cover",
-		bounds: "<root>",
-		padding
+	let padding = opts.padding ?? 80;
+	let pan_overshoot = opts.pan_overshoot ?? 0;
+	const apply = () => {
+		inner.camera.constraints = {
+			type: "cover",
+			bounds: "<root>",
+			padding,
+			pan_overshoot
+		};
 	};
-	const unsub_load = editor.subscribe_with_selector((s) => s.load_version, () => inner.camera.fit("<root>", { margin: padding }));
+	apply();
+	const unsub_load = editor.subscribe_with_selector((s) => s.load_version, () => inner.camera.fit("<root>", { margin: inner.camera.constraints?.padding ?? 0 }));
 	return {
-		camera: inner.camera,
-		gestures: inner.gestures,
+		...inner,
 		set_padding(p) {
 			padding = p;
-			inner.camera.constraints = {
-				type: "cover",
-				bounds: "<root>",
-				padding: p
-			};
+			apply();
 			inner.camera.fit("<root>", { margin: p });
 		},
+		set_pan_overshoot(o) {
+			pan_overshoot = o;
+			apply();
+		},
 		detach: () => {
 			unsub_load();
 			inner.detach();

package/dist/presets.mjs

@@ -1,5 +1,5 @@
-import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
-import { t as attach_dom_surface } from "./dom-CmOu0HvI.mjs";
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
+import { t as attach_dom_surface } from "./dom-tM3Dr1EK.mjs";
 //#region src/presets/keynote.ts
 var keynote_exports = /* @__PURE__ */ __exportAll({ attach: () => attach });
 /**
@@ -16,30 +16,34 @@ var keynote_exports = /* @__PURE__ */ __exportAll({ attach: () => attach });
 * additionally tears down the load subscription.
 */
 function attach(editor, opts) {
-	let padding = opts.padding ?? 80;
 	const inner = attach_dom_surface(editor, {
 		...opts.surface,
 		container: opts.container,
 		fit: true
 	});
-	inner.camera.constraints = {
-		type: "cover",
-		bounds: "<root>",
-		padding
+	let padding = opts.padding ?? 80;
+	let pan_overshoot = opts.pan_overshoot ?? 0;
+	const apply = () => {
+		inner.camera.constraints = {
+			type: "cover",
+			bounds: "<root>",
+			padding,
+			pan_overshoot
+		};
 	};
-	const unsub_load = editor.subscribe_with_selector((s) => s.load_version, () => inner.camera.fit("<root>", { margin: padding }));
+	apply();
+	const unsub_load = editor.subscribe_with_selector((s) => s.load_version, () => inner.camera.fit("<root>", { margin: inner.camera.constraints?.padding ?? 0 }));
 	return {
-		camera: inner.camera,
-		gestures: inner.gestures,
+		...inner,
 		set_padding(p) {
 			padding = p;
-			inner.camera.constraints = {
-				type: "cover",
-				bounds: "<root>",
-				padding: p
-			};
+			apply();
 			inner.camera.fit("<root>", { margin: p });
 		},
+		set_pan_overshoot(o) {
+			pan_overshoot = o;
+			apply();
+		},
 		detach: () => {
 			unsub_load();
 			inner.detach();

package/dist/react.d.mts

@@ -1,26 +1,40 @@
-import { B as Providers, C as EditorStyle, S as EditorState, o as SvgEditor, t as Commands } from "./editor-Uu6dZX4y.mjs";
-import { t as DomSurfaceHandle } from "./dom-DJnZhtOd.mjs";
+import { A as EditorState, H as Mode, J as PickEvent, K as PaintPreviewSession, Q as Providers, U as NodeId, Y as PreviewSession, c as SvgEditor, j as EditorStyle, rt as Tool, t as Commands } from "./editor-CZgwg8BK.mjs";
+import { n as DomSurfaceHandle } from "./dom-BEjG2bSw.mjs";
 import cmath from "@grida/cmath";
 import { ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/react.d.ts
 type SvgEditorProviderProps = {
-  svg: string;
+  /**
+   * Initial document for the editor. Read **once** on first render —
+   * subsequent changes to this prop are silently ignored. For live updates
+   * (file open, page switch, reset to a snapshot), pull the editor from
+   * context with `useSvgEditor()` and call `editor.load(...)` imperatively.
+   *
+   * This is the same shape Lexical (`initialConfig.editorState`), Slate
+   * (`initialValue`), and TipTap (`content` option) settled on for the
+   * same reason: a reactive document prop creates a feedback loop with the
+   * editor's own emissions. The editor instance is the source of truth
+   * for the document during a session; React state is not.
+   */
+  initialSvg: string;
   providers?: Providers;
   style?: Partial<EditorStyle>;
   children: ReactNode;
 };
 /**
  * Owns the headless editor and exposes it via context. The editor is created
- * once on first render; subsequent prop changes to `svg` call `editor.load()`.
+ * once on first render with `initialSvg`; subsequent changes to that prop are
+ * silently ignored. To replace the document at runtime, call
+ * `useSvgEditor().load(...)` imperatively, or remount the provider with a
+ * different `key`.
  */
 declare function SvgEditorProvider({
-  svg,
+  initialSvg,
   providers,
   style,
   children
-}: SvgEditorProviderProps): _$react_jsx_runtime0.JSX.Element;
+}: SvgEditorProviderProps): import("react/jsx-runtime").JSX.Element;
 type SvgEditorCanvasProps = {
   className?: string;
   style?: React.CSSProperties;
@@ -33,7 +47,13 @@ type SvgEditorCanvasProps = {
    * Auto-fit the document on initial attach. Default `false`. See
    * `DomSurfaceOptions.fit`.
    */
-  fit?: boolean; /** Initial camera transform. Default identity. */
+  fit?: boolean;
+  /**
+   * Wire native ClipboardEvent transport (copy/cut/paste). Default `true`.
+   * Pass `false` to route all clipboard traffic through the
+   * `ClipboardProvider` seam. See `DomSurfaceOptions.clipboard`.
+   */
+  clipboard?: boolean; /** Initial camera transform. Default identity. */
   initial_camera?: cmath.Transform;
   /**
    * Receives the `DomSurfaceHandle` once the surface is attached, and
@@ -56,9 +76,10 @@ declare function SvgEditorCanvas({
   style,
   gestures,
   fit,
+  clipboard,
   initial_camera,
   onAttach
-}: SvgEditorCanvasProps): _$react_jsx_runtime0.JSX.Element;
+}: SvgEditorCanvasProps): import("react/jsx-runtime").JSX.Element;
 declare function useSvgEditor(): SvgEditor;
 /**
  * Subscribe to a slice of `editor.state`. Re-renders when the selected slice
@@ -88,5 +109,62 @@ declare function useCommands(): Commands;
  * mismatch with the first client render.
  */
 declare function useCameraSnapshot<T>(handle: DomSurfaceHandle | null, selector: (camera: DomSurfaceHandle["camera"]) => T, fallback: T): T;
+/** Current selection (frozen, identity-stable across no-op emits). */
+declare function useSelection(): readonly NodeId[];
+/** Active tool. Identity-stable when `set_tool` is a no-op. */
+declare function useTool(): Tool;
+/** Current mode (`"select"` | `"edit-content"`). */
+declare function useMode(): Mode;
+/**
+ * What kind of content-edit is active, or `null` when not in content-edit.
+ *
+ * Symmetric with `useMode()` but at a finer grain — resolves whether the
+ * single selected node is a path or a text node so consumers (e.g. the
+ * vector-edit toolbar) can render the right affordances. Mirrors the
+ * dispatch logic in the host's `enter_content_edit` router which checks
+ * `tag_of(id) === "path"` vs `"text" / "tspan"`.
+ *
+ * Returns `null` for the (defensive) case of `edit-content` with no
+ * selection, and for any tag that's neither path nor text.
+ */
+declare function useContentEditKind(): "path" | "text" | null;
+/** Whether the history stack has an undoable entry. */
+declare function useCanUndo(): boolean;
+/** Whether the history stack has a redoable entry. */
+declare function useCanRedo(): boolean;
+/** Hook-owned `PaintPreviewSession`. See block comment above. */
+declare function usePaintPreview(channel: "fill" | "stroke"): PaintPreviewSession;
+/** Hook-owned `PreviewSession` for a CSS/SVG property. See block comment above. */
+declare function usePropertyPreview(name: string): PreviewSession;
+/** Bound `editor.load(svg)`. Stable across renders. */
+declare function useEditorLoad(): (svg: string) => void;
+/** Bound `editor.serialize()`. Stable across renders. */
+declare function useEditorSerialize(): () => string;
+/**
+ * Push a hover override into the HUD surface — e.g. when the user hovers
+ * a row in a layers panel. The HUD will render the override's outline.
+ *
+ * Pass `null` to clear and let the pointer pick take over again. On
+ * unmount, the hook clears any override it set last so the canvas
+ * doesn't stay highlighted on a node that no longer has a panel row.
+ */
+declare function useHoverOverride(): (id: NodeId | null) => void;
+/**
+ * Observe pick (tap) outcomes — a discrete click on the canvas, reporting the
+ * document-space `point`, the `node_id` under it (`null` for empty canvas),
+ * the `button`, and `mods`. The handler fires once per tap, after the editor's
+ * own selection handling. Observe-only: it cannot prevent or alter selection.
+ *
+ * This is the React edge-wire over `editor.subscribe_pick`. The handler is
+ * kept in a ref so re-subscription is never triggered by handler identity —
+ * pass an inline closure freely. Pick is editor-scoped (it survives surface
+ * detach), so this is a hook, not a `SvgEditorCanvas` prop.
+ *
+ * Typical use: a comment / annotation tool anchors a popover at `e.point` and
+ * scopes its action to `e.node_id` (or to the whole document when `null`).
+ *
+ * @unstable See {@link PickEvent}.
+ */
+declare function useEditorPick(handler: (e: PickEvent) => void): void;
 //#endregion
-export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCameraSnapshot, useCommands, useEditorState, useSvgEditor };
+export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCameraSnapshot, useCanRedo, useCanUndo, useCommands, useContentEditKind, useEditorLoad, useEditorPick, useEditorSerialize, useEditorState, useHoverOverride, useMode, usePaintPreview, usePropertyPreview, useSelection, useSvgEditor, useTool };

package/dist/react.d.ts

@@ -1,26 +1,40 @@
-import { B as Providers, C as EditorStyle, S as EditorState, o as SvgEditor, t as Commands } from "./editor-D2l_CDr0.js";
-import { t as DomSurfaceHandle } from "./dom-Cn-RtjRL.js";
+import { A as EditorState, H as Mode, J as PickEvent, K as PaintPreviewSession, Q as Providers, U as NodeId, Y as PreviewSession, c as SvgEditor, j as EditorStyle, rt as Tool, t as Commands } from "./editor-kFTYSb_8.js";
+import { n as DomSurfaceHandle } from "./dom-Y2QR7QSi.js";
 import cmath from "@grida/cmath";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { ReactNode } from "react";
 
 //#region src/react.d.ts
 type SvgEditorProviderProps = {
-  svg: string;
+  /**
+   * Initial document for the editor. Read **once** on first render —
+   * subsequent changes to this prop are silently ignored. For live updates
+   * (file open, page switch, reset to a snapshot), pull the editor from
+   * context with `useSvgEditor()` and call `editor.load(...)` imperatively.
+   *
+   * This is the same shape Lexical (`initialConfig.editorState`), Slate
+   * (`initialValue`), and TipTap (`content` option) settled on for the
+   * same reason: a reactive document prop creates a feedback loop with the
+   * editor's own emissions. The editor instance is the source of truth
+   * for the document during a session; React state is not.
+   */
+  initialSvg: string;
   providers?: Providers;
   style?: Partial<EditorStyle>;
   children: ReactNode;
 };
 /**
  * Owns the headless editor and exposes it via context. The editor is created
- * once on first render; subsequent prop changes to `svg` call `editor.load()`.
+ * once on first render with `initialSvg`; subsequent changes to that prop are
+ * silently ignored. To replace the document at runtime, call
+ * `useSvgEditor().load(...)` imperatively, or remount the provider with a
+ * different `key`.
  */
 declare function SvgEditorProvider({
-  svg,
+  initialSvg,
   providers,
   style,
   children
-}: SvgEditorProviderProps): _$react_jsx_runtime0.JSX.Element;
+}: SvgEditorProviderProps): import("react/jsx-runtime").JSX.Element;
 type SvgEditorCanvasProps = {
   className?: string;
   style?: React.CSSProperties;
@@ -33,7 +47,13 @@ type SvgEditorCanvasProps = {
    * Auto-fit the document on initial attach. Default `false`. See
    * `DomSurfaceOptions.fit`.
    */
-  fit?: boolean; /** Initial camera transform. Default identity. */
+  fit?: boolean;
+  /**
+   * Wire native ClipboardEvent transport (copy/cut/paste). Default `true`.
+   * Pass `false` to route all clipboard traffic through the
+   * `ClipboardProvider` seam. See `DomSurfaceOptions.clipboard`.
+   */
+  clipboard?: boolean; /** Initial camera transform. Default identity. */
   initial_camera?: cmath.Transform;
   /**
    * Receives the `DomSurfaceHandle` once the surface is attached, and
@@ -56,9 +76,10 @@ declare function SvgEditorCanvas({
   style,
   gestures,
   fit,
+  clipboard,
   initial_camera,
   onAttach
-}: SvgEditorCanvasProps): _$react_jsx_runtime0.JSX.Element;
+}: SvgEditorCanvasProps): import("react/jsx-runtime").JSX.Element;
 declare function useSvgEditor(): SvgEditor;
 /**
  * Subscribe to a slice of `editor.state`. Re-renders when the selected slice
@@ -88,5 +109,62 @@ declare function useCommands(): Commands;
  * mismatch with the first client render.
  */
 declare function useCameraSnapshot<T>(handle: DomSurfaceHandle | null, selector: (camera: DomSurfaceHandle["camera"]) => T, fallback: T): T;
+/** Current selection (frozen, identity-stable across no-op emits). */
+declare function useSelection(): readonly NodeId[];
+/** Active tool. Identity-stable when `set_tool` is a no-op. */
+declare function useTool(): Tool;
+/** Current mode (`"select"` | `"edit-content"`). */
+declare function useMode(): Mode;
+/**
+ * What kind of content-edit is active, or `null` when not in content-edit.
+ *
+ * Symmetric with `useMode()` but at a finer grain — resolves whether the
+ * single selected node is a path or a text node so consumers (e.g. the
+ * vector-edit toolbar) can render the right affordances. Mirrors the
+ * dispatch logic in the host's `enter_content_edit` router which checks
+ * `tag_of(id) === "path"` vs `"text" / "tspan"`.
+ *
+ * Returns `null` for the (defensive) case of `edit-content` with no
+ * selection, and for any tag that's neither path nor text.
+ */
+declare function useContentEditKind(): "path" | "text" | null;
+/** Whether the history stack has an undoable entry. */
+declare function useCanUndo(): boolean;
+/** Whether the history stack has a redoable entry. */
+declare function useCanRedo(): boolean;
+/** Hook-owned `PaintPreviewSession`. See block comment above. */
+declare function usePaintPreview(channel: "fill" | "stroke"): PaintPreviewSession;
+/** Hook-owned `PreviewSession` for a CSS/SVG property. See block comment above. */
+declare function usePropertyPreview(name: string): PreviewSession;
+/** Bound `editor.load(svg)`. Stable across renders. */
+declare function useEditorLoad(): (svg: string) => void;
+/** Bound `editor.serialize()`. Stable across renders. */
+declare function useEditorSerialize(): () => string;
+/**
+ * Push a hover override into the HUD surface — e.g. when the user hovers
+ * a row in a layers panel. The HUD will render the override's outline.
+ *
+ * Pass `null` to clear and let the pointer pick take over again. On
+ * unmount, the hook clears any override it set last so the canvas
+ * doesn't stay highlighted on a node that no longer has a panel row.
+ */
+declare function useHoverOverride(): (id: NodeId | null) => void;
+/**
+ * Observe pick (tap) outcomes — a discrete click on the canvas, reporting the
+ * document-space `point`, the `node_id` under it (`null` for empty canvas),
+ * the `button`, and `mods`. The handler fires once per tap, after the editor's
+ * own selection handling. Observe-only: it cannot prevent or alter selection.
+ *
+ * This is the React edge-wire over `editor.subscribe_pick`. The handler is
+ * kept in a ref so re-subscription is never triggered by handler identity —
+ * pass an inline closure freely. Pick is editor-scoped (it survives surface
+ * detach), so this is a hook, not a `SvgEditorCanvas` prop.
+ *
+ * Typical use: a comment / annotation tool anchors a popover at `e.point` and
+ * scopes its action to `e.node_id` (or to the whole document when `null`).
+ *
+ * @unstable See {@link PickEvent}.
+ */
+declare function useEditorPick(handler: (e: PickEvent) => void): void;
 //#endregion
-export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCameraSnapshot, useCommands, useEditorState, useSvgEditor };
+export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCameraSnapshot, useCanRedo, useCanUndo, useCommands, useContentEditKind, useEditorLoad, useEditorPick, useEditorSerialize, useEditorState, useHoverOverride, useMode, usePaintPreview, usePropertyPreview, useSelection, useSvgEditor, useTool };