@grida/svg-editor 1.0.0-alpha.1 → 1.0.0-alpha.12

package/dist/presets.d.mts

@@ -0,0 +1,61 @@
+import { c as SvgEditor } from "./editor-BH03X8cX.mjs";
+import { n as DomSurfaceOptions, t as DomSurfaceHandle } from "./dom-DgB4f-TE.mjs";
+
+//#region src/presets/keynote.d.ts
+declare namespace keynote_d_exports {
+  export { KeynoteAttachOptions, KeynoteSurfaceHandle, attach };
+}
+type KeynoteAttachOptions = {
+  /** Container to mount the SVG into. */container: HTMLElement;
+  /**
+   * Screen-pixel breathing room between the slide and the viewport edge.
+   * 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.
+   */
+  surface?: Omit<DomSurfaceOptions, "container" | "fit" | "initial_camera">;
+};
+/**
+ * Surface handle returned by `keynote.attach`. Extends `DomSurfaceHandle`
+ * with `set_padding` so hosts can vary the slide breathing room at runtime
+ * (e.g. on a "present mode" toggle that wants margin: 0 vs the default 80).
+ */
+type KeynoteSurfaceHandle = DomSurfaceHandle & {
+  /**
+   * Update the slide padding and re-fit. Mutates the live constraint AND
+   * 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:
+ * - Mounts via `attach_dom_surface` with `fit: true` (slide is visible on
+ *   first frame).
+ * - Installs a `'cover'` camera constraint bound to the document root, so
+ *   the user can't zoom out past the slide or pan past its edges.
+ * - Subscribes to `editor.state.load_version` so every `editor.load(svg)`
+ *   re-fits the camera to the new document.
+ *
+ * Returns a `KeynoteSurfaceHandle` — same shape as `DomSurfaceHandle` plus
+ * `set_padding` for present-mode toggles. The returned `detach()`
+ * additionally tears down the load subscription.
+ */
+declare function attach(editor: SvgEditor, opts: KeynoteAttachOptions): KeynoteSurfaceHandle;
+//#endregion
+export { type KeynoteAttachOptions, type KeynoteSurfaceHandle, keynote_d_exports as keynote };

package/dist/presets.d.ts

@@ -0,0 +1,61 @@
+import { c as SvgEditor } from "./editor-Bd4-VCEJ.js";
+import { n as DomSurfaceOptions, t as DomSurfaceHandle } from "./dom-DCX-a8Kr.js";
+
+//#region \0rolldown/runtime.js
+declare namespace keynote_d_exports {
+  export { KeynoteAttachOptions, KeynoteSurfaceHandle, attach };
+}
+type KeynoteAttachOptions = {
+  /** Container to mount the SVG into. */container: HTMLElement;
+  /**
+   * Screen-pixel breathing room between the slide and the viewport edge.
+   * 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.
+   */
+  surface?: Omit<DomSurfaceOptions, "container" | "fit" | "initial_camera">;
+};
+/**
+ * Surface handle returned by `keynote.attach`. Extends `DomSurfaceHandle`
+ * with `set_padding` so hosts can vary the slide breathing room at runtime
+ * (e.g. on a "present mode" toggle that wants margin: 0 vs the default 80).
+ */
+type KeynoteSurfaceHandle = DomSurfaceHandle & {
+  /**
+   * Update the slide padding and re-fit. Mutates the live constraint AND
+   * 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:
+ * - Mounts via `attach_dom_surface` with `fit: true` (slide is visible on
+ *   first frame).
+ * - Installs a `'cover'` camera constraint bound to the document root, so
+ *   the user can't zoom out past the slide or pan past its edges.
+ * - Subscribes to `editor.state.load_version` so every `editor.load(svg)`
+ *   re-fits the camera to the new document.
+ *
+ * Returns a `KeynoteSurfaceHandle` — same shape as `DomSurfaceHandle` plus
+ * `set_padding` for present-mode toggles. The returned `detach()`
+ * additionally tears down the load subscription.
+ */
+declare function attach(editor: SvgEditor, opts: KeynoteAttachOptions): KeynoteSurfaceHandle;
+//#endregion
+export { type KeynoteAttachOptions, type KeynoteSurfaceHandle, keynote_d_exports as keynote };

package/dist/presets.js

@@ -0,0 +1,61 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_insertions = require("./insertions-BJ-6o6o5.js");
+const require_dom = require("./dom-Cvm9Towu.js");
+//#region src/presets/keynote.ts
+var keynote_exports = /* @__PURE__ */ require_insertions.__exportAll({ attach: () => attach });
+/**
+* Attach a keynote-shaped DOM surface:
+* - Mounts via `attach_dom_surface` with `fit: true` (slide is visible on
+*   first frame).
+* - Installs a `'cover'` camera constraint bound to the document root, so
+*   the user can't zoom out past the slide or pan past its edges.
+* - Subscribes to `editor.state.load_version` so every `editor.load(svg)`
+*   re-fits the camera to the new document.
+*
+* Returns a `KeynoteSurfaceHandle` — same shape as `DomSurfaceHandle` plus
+* `set_padding` for present-mode toggles. The returned `detach()`
+* additionally tears down the load subscription.
+*/
+function attach(editor, opts) {
+	const inner = require_dom.attach_dom_surface(editor, {
+		...opts.surface,
+		container: opts.container,
+		fit: true
+	});
+	let padding = opts.padding ?? 80;
+	let pan_overshoot = opts.pan_overshoot ?? 0;
+	const apply = () => {
+		inner.camera.constraints = {
+			type: "cover",
+			bounds: "<root>",
+			padding,
+			pan_overshoot
+		};
+	};
+	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,
+		set_padding(p) {
+			padding = p;
+			apply();
+			inner.camera.fit("<root>", { margin: p });
+		},
+		set_pan_overshoot(o) {
+			pan_overshoot = o;
+			apply();
+		},
+		detach: () => {
+			unsub_load();
+			inner.detach();
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "keynote", {
+	enumerable: true,
+	get: function() {
+		return keynote_exports;
+	}
+});

package/dist/presets.mjs

@@ -0,0 +1,55 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+import { t as attach_dom_surface } from "./dom-BlMk07oX.mjs";
+//#region src/presets/keynote.ts
+var keynote_exports = /* @__PURE__ */ __exportAll({ attach: () => attach });
+/**
+* Attach a keynote-shaped DOM surface:
+* - Mounts via `attach_dom_surface` with `fit: true` (slide is visible on
+*   first frame).
+* - Installs a `'cover'` camera constraint bound to the document root, so
+*   the user can't zoom out past the slide or pan past its edges.
+* - Subscribes to `editor.state.load_version` so every `editor.load(svg)`
+*   re-fits the camera to the new document.
+*
+* Returns a `KeynoteSurfaceHandle` — same shape as `DomSurfaceHandle` plus
+* `set_padding` for present-mode toggles. The returned `detach()`
+* additionally tears down the load subscription.
+*/
+function attach(editor, opts) {
+	const inner = attach_dom_surface(editor, {
+		...opts.surface,
+		container: opts.container,
+		fit: true
+	});
+	let padding = opts.padding ?? 80;
+	let pan_overshoot = opts.pan_overshoot ?? 0;
+	const apply = () => {
+		inner.camera.constraints = {
+			type: "cover",
+			bounds: "<root>",
+			padding,
+			pan_overshoot
+		};
+	};
+	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,
+		set_padding(p) {
+			padding = p;
+			apply();
+			inner.camera.fit("<root>", { margin: p });
+		},
+		set_pan_overshoot(o) {
+			pan_overshoot = o;
+			apply();
+		},
+		detach: () => {
+			unsub_load();
+			inner.detach();
+		}
+	};
+}
+//#endregion
+export { keynote_exports as keynote };

package/dist/react.d.mts

@@ -1,20 +1,37 @@
-import { d as EditorState, f as EditorStyle, k as Providers, o as SvgEditor, t as Commands } from "./editor-JY7AQrR1.mjs";
+import { B as PaintPreviewSession, E as EditorStyle, G as Providers, H as PreviewSession, I as Mode, L as NodeId, T as EditorState, X as Tool, c as SvgEditor, t as Commands } from "./editor-BH03X8cX.mjs";
+import { t as DomSurfaceHandle } from "./dom-DgB4f-TE.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
@@ -22,17 +39,40 @@ declare function SvgEditorProvider({
 type SvgEditorCanvasProps = {
   className?: string;
   style?: React.CSSProperties;
+  /**
+   * Install the default gesture set. Default `true`. See
+   * `DomSurfaceOptions.gestures`.
+   */
+  gestures?: boolean;
+  /**
+   * Auto-fit the document on initial attach. Default `false`. See
+   * `DomSurfaceOptions.fit`.
+   */
+  fit?: boolean; /** Initial camera transform. Default identity. */
+  initial_camera?: cmath.Transform;
+  /**
+   * Receives the `DomSurfaceHandle` once the surface is attached, and
+   * `null` on unmount/detach. Use this to thread `handle.camera` /
+   * `handle.gestures` into surrounding chrome (toolbars, badges, etc.).
+   */
+  onAttach?: (handle: DomSurfaceHandle | null) => void;
 };
 /**
  * Renders the editor's SVG into a `div` and wires it to the DOM surface.
  *
- * Internally calls `attach_dom_surface(editor, { container })` on mount and
- * `handle.detach()` on unmount. This is the only UI component the package
- * ships; everything else (toolbar, property panel, etc.) is consumer-built.
+ * Internally calls `attach_dom_surface(editor, { container, ... })` on
+ * mount and `handle.detach()` on unmount. Surface-scoped concerns (camera,
+ * gestures) are reached via the `onAttach` callback — there is no global
+ * context for them, because a host may mount multiple canvases in the
+ * same editor session.
  */
 declare function SvgEditorCanvas({
   className,
-  style
+  style,
+  gestures,
+  fit,
+  initial_camera,
+  onAttach
 }: SvgEditorCanvasProps): _$react_jsx_runtime0.JSX.Element;
 declare function useSvgEditor(): SvgEditor;
 /**
@@ -45,5 +85,50 @@ declare function useEditorState<T>(selector: (state: EditorState) => T, equals?:
  * re-renders (commands themselves don't change identity).
  */
 declare function useCommands(): Commands;
+/**
+ * Subscribe to a slice of `handle.camera` from a `DomSurfaceHandle`. Pass
+ * the handle (or null if it isn't attached yet) and a selector that reads
+ * what you need from the camera. The returned value updates on every
+ * camera mutation — does NOT bump `editor.state.version`.
+ *
+ * Typical use: zoom badge in a toolbar.
+ *
+ * ```tsx
+ * const zoom = useCameraSnapshot(handle, (c) => c.zoom, 1);
+ * return <div>{Math.round(zoom * 100)}%</div>;
+ * ```
+ *
+ * The `fallback` is what's returned when `handle` is `null` (before mount /
+ * after detach). It's also the SSR snapshot value — anything that won't
+ * 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;
+/** 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;
 //#endregion
-export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCommands, useEditorState, useSvgEditor };
+export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCameraSnapshot, useCanRedo, useCanUndo, useCommands, useEditorLoad, useEditorSerialize, useEditorState, useHoverOverride, useMode, usePaintPreview, usePropertyPreview, useSelection, useSvgEditor, useTool };

package/dist/react.d.ts

@@ -1,20 +1,37 @@
-import { d as EditorState, f as EditorStyle, k as Providers, o as SvgEditor, t as Commands } from "./editor-CTtU2gu4.js";
+import { B as PaintPreviewSession, E as EditorStyle, G as Providers, H as PreviewSession, I as Mode, L as NodeId, T as EditorState, X as Tool, c as SvgEditor, t as Commands } from "./editor-Bd4-VCEJ.js";
+import { t as DomSurfaceHandle } from "./dom-DCX-a8Kr.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
@@ -22,17 +39,40 @@ declare function SvgEditorProvider({
 type SvgEditorCanvasProps = {
   className?: string;
   style?: React.CSSProperties;
+  /**
+   * Install the default gesture set. Default `true`. See
+   * `DomSurfaceOptions.gestures`.
+   */
+  gestures?: boolean;
+  /**
+   * Auto-fit the document on initial attach. Default `false`. See
+   * `DomSurfaceOptions.fit`.
+   */
+  fit?: boolean; /** Initial camera transform. Default identity. */
+  initial_camera?: cmath.Transform;
+  /**
+   * Receives the `DomSurfaceHandle` once the surface is attached, and
+   * `null` on unmount/detach. Use this to thread `handle.camera` /
+   * `handle.gestures` into surrounding chrome (toolbars, badges, etc.).
+   */
+  onAttach?: (handle: DomSurfaceHandle | null) => void;
 };
 /**
  * Renders the editor's SVG into a `div` and wires it to the DOM surface.
  *
- * Internally calls `attach_dom_surface(editor, { container })` on mount and
- * `handle.detach()` on unmount. This is the only UI component the package
- * ships; everything else (toolbar, property panel, etc.) is consumer-built.
+ * Internally calls `attach_dom_surface(editor, { container, ... })` on
+ * mount and `handle.detach()` on unmount. Surface-scoped concerns (camera,
+ * gestures) are reached via the `onAttach` callback — there is no global
+ * context for them, because a host may mount multiple canvases in the
+ * same editor session.
  */
 declare function SvgEditorCanvas({
   className,
-  style
+  style,
+  gestures,
+  fit,
+  initial_camera,
+  onAttach
 }: SvgEditorCanvasProps): _$react_jsx_runtime0.JSX.Element;
 declare function useSvgEditor(): SvgEditor;
 /**
@@ -45,5 +85,50 @@ declare function useEditorState<T>(selector: (state: EditorState) => T, equals?:
  * re-renders (commands themselves don't change identity).
  */
 declare function useCommands(): Commands;
+/**
+ * Subscribe to a slice of `handle.camera` from a `DomSurfaceHandle`. Pass
+ * the handle (or null if it isn't attached yet) and a selector that reads
+ * what you need from the camera. The returned value updates on every
+ * camera mutation — does NOT bump `editor.state.version`.
+ *
+ * Typical use: zoom badge in a toolbar.
+ *
+ * ```tsx
+ * const zoom = useCameraSnapshot(handle, (c) => c.zoom, 1);
+ * return <div>{Math.round(zoom * 100)}%</div>;
+ * ```
+ *
+ * The `fallback` is what's returned when `handle` is `null` (before mount /
+ * after detach). It's also the SSR snapshot value — anything that won't
+ * 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;
+/** 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;
 //#endregion
-export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCommands, useEditorState, useSvgEditor };
+export { SvgEditorCanvas, SvgEditorCanvasProps, SvgEditorProvider, SvgEditorProviderProps, useCameraSnapshot, useCanRedo, useCanUndo, useCommands, useEditorLoad, useEditorSerialize, useEditorState, useHoverOverride, useMode, usePaintPreview, usePropertyPreview, useSelection, useSvgEditor, useTool };