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

package/README.md

@@ -123,6 +123,156 @@ A few scenarios this is designed to handle well.
 >
 > The editor freezes the animation at `t=0` for editing, applies the position change to the static `cx` attribute, and preserves the `<animate>` block verbatim. The inspector shows a clear "animated property" badge so the user understands what they're editing.
 
+### Free-form canvas (Figma-style infinite canvas)
+
+Identity camera, default gestures, no auto-fit. Pan with the wheel, Cmd+wheel to zoom at cursor, space-drag for hand-tool, `Shift+1` to fit, `Shift+0` to reset.
+
+```tsx
+import {
+  SvgEditorCanvas,
+  SvgEditorProvider,
+  useCameraSnapshot,
+} from "@grida/svg-editor/react";
+import type { DomSurfaceHandle } from "@grida/svg-editor/dom";
+import { useState } from "react";
+
+export function FreeFormCanvas({ svg }: { svg: string }) {
+  const [handle, setHandle] = useState<DomSurfaceHandle | null>(null);
+  const zoom = useCameraSnapshot(handle, (c) => c.zoom, 1);
+  return (
+    <SvgEditorProvider svg={svg}>
+      <div style={{ position: "relative", width: "100%", height: "100vh" }}>
+        <SvgEditorCanvas onAttach={setHandle} style={{ width: "100%", height: "100%" }} />
+        <div style={{ position: "absolute", bottom: 12, right: 12 }}>
+          <button onClick={() => handle?.camera.fit("<root>")}>Fit</button>
+          <button onClick={() => handle?.camera.reset()}>100%</button>
+          <span>{Math.round(zoom * 100)}%</span>
+        </div>
+      </div>
+    </SvgEditorProvider>
+  );
+}
+```
+
+### Keynote-like canvas (fixed-viewBox slide with bounded camera)
+
+The keynote case wants more than "fit on load" — it wants **"the slide is the world"**: no zooming out past fit, no panning when the slide already fills the viewport, and clamped panning when zoomed in so the slide always covers the viewport edge-to-edge.
+
+The package doesn't ship `camera.constraints` at v1 (see [Deferred for v1](#deferred-for-v1)). The recipe is **pure imperative JS** — no React. Camera lifecycle is owned by the DOM surface, not by React render cycles, so the policy lives next to the surface and React is just orchestration glue.
+
+The reusable primitive — `create_slide_constraint(camera)` — installs a `camera.subscribe(...)` that clamps zoom (≥ fit-zoom) and pan (slide always covers the viewport) on every change. `Camera.set_transform` is idempotent, so the subscribe→clamp→set loop converges in one round. Compose it with `editor.subscribe_with_selector(s => s.structure_version, ...)` for refit-on-load:
+
+```ts
+// Pure-JS policy. No React. Construct in onAttach, dispose on detach.
+import cmath from "@grida/cmath";
+import type { Camera, Rect, SvgEditor, Unsubscribe } from "@grida/svg-editor";
+import type { DomSurfaceHandle } from "@grida/svg-editor/dom";
+
+function create_slide_constraint(camera: Camera) {
+  let slide: Rect | null = null;
+  let margin = 0;
+  const enforce = () => {
+    if (!slide) return;
+    const t = camera.transform;
+    const vp = camera.viewport_size;
+    if (vp.width <= 0 || vp.height <= 0) return;
+    const min_zoom = Math.min(
+      (vp.width - 2 * margin) / slide.width,
+      (vp.height - 2 * margin) / slide.height
+    );
+    const s = Math.max(t[0][0], min_zoom);
+    const sw = s * slide.width, sh = s * slide.height;
+    const tx = sw > vp.width
+      ? cmath.clamp(t[0][2], vp.width - s * (slide.x + slide.width), -s * slide.x)
+      : (vp.width - sw) / 2 - s * slide.x;
+    const ty = sh > vp.height
+      ? cmath.clamp(t[1][2], vp.height - s * (slide.y + slide.height), -s * slide.y)
+      : (vp.height - sh) / 2 - s * slide.y;
+    camera.set_transform([[s, 0, tx], [0, s, ty]]);
+  };
+  const unsubscribe = camera.subscribe(enforce);
+  return {
+    set_slide(next: Rect | null) { slide = next; enforce(); },
+    set_margin(next: number) { margin = next; enforce(); },
+    dispose() { unsubscribe(); },
+  };
+}
+
+class KeynotePolicy {
+  private constraint = create_slide_constraint(this.handle.camera);
+  private unsub: Unsubscribe;
+  private margin: number;
+
+  constructor(
+    private editor: SvgEditor,
+    private handle: DomSurfaceHandle,
+    opts: { margin: number }
+  ) {
+    this.margin = opts.margin;
+    this.constraint.set_margin(this.margin);
+    this.refresh();
+    this.unsub = editor.subscribe_with_selector(
+      (s) => s.structure_version,
+      () => this.refresh()
+    );
+  }
+  set_margin(m: number) {
+    this.margin = m;
+    this.constraint.set_margin(m);
+    this.handle.camera.fit("<root>", { margin: m });
+  }
+  private refresh() {
+    const root = this.editor.tree().root;
+    const vb = this.editor.document.get_attr(root, "viewBox")?.split(/[\s,]+/).map(Number);
+    this.constraint.set_slide(
+      vb?.length === 4 && vb.every(Number.isFinite)
+        ? { x: vb[0], y: vb[1], width: vb[2], height: vb[3] }
+        : null
+    );
+    this.handle.camera.fit("<root>", { margin: this.margin });
+  }
+  dispose() { this.unsub(); this.constraint.dispose(); }
+}
+```
+
+React's role drops to: instantiate the policy in `onAttach`, hold it in a ref, dispose on unmount.
+
+```tsx
+import { useCallback, useEffect, useRef } from "react";
+import {
+  SvgEditorCanvas, SvgEditorProvider, useSvgEditor,
+} from "@grida/svg-editor/react";
+import type { DomSurfaceHandle } from "@grida/svg-editor/dom";
+
+export function KeynoteCanvas({ svg }: { svg: string }) {
+  return (
+    <SvgEditorProvider svg={svg}>
+      <KeynoteHost />
+    </SvgEditorProvider>
+  );
+}
+
+function KeynoteHost() {
+  const editor = useSvgEditor();
+  const policy_ref = useRef<KeynotePolicy | null>(null);
+  const onAttach = useCallback((h: DomSurfaceHandle | null) => {
+    policy_ref.current?.dispose();
+    policy_ref.current = h ? new KeynotePolicy(editor, h, { margin: 80 }) : null;
+  }, [editor]);
+  useEffect(() => () => policy_ref.current?.dispose(), []);
+  return (
+    <div style={{ padding: 24, background: "#1f2937", height: "100vh" }}>
+      <SvgEditorCanvas fit onAttach={onAttach} style={{
+        width: "100%", height: "100%",
+        background: "#fff", boxShadow: "0 10px 40px rgba(0,0,0,0.3)",
+      }}/>
+    </div>
+  );
+}
+```
+
+Both examples ship as live demos at `/canvas/svg` (free-form) and `/canvas/svg/keynote` (constrained) in the dogfood app. Their diff is the spec for what the SDK owes its users: same editor, same camera, same gestures — different host policies layered on top, and the policy itself is plain imperative JS that any framework could reuse.
+
 ## Install
 
 ```sh
@@ -164,13 +314,68 @@ A surface is the editor's attachment seam — it mounts the SVG into a host envi
 ```ts
 import { attach_dom_surface } from "@grida/svg-editor/dom";
 
-const handle = attach_dom_surface(editor, { container });
-// later:
+const handle = attach_dom_surface(editor, {
+  container,
+  gestures: true,   // default — install the bundled gesture set (see "Camera")
+  fit: false,       // default — start with identity camera (no auto-fit)
+});
+
+handle.camera; // surface-scoped pan/zoom (see "Camera")
+handle.gestures; // surface-scoped wheel/pointer/keyboard layer
 handle.detach();
 ```
 
 `@grida/svg-editor/dom` is the only place in this package that imports DOM types. The internal `Surface` type exists for tests and future work; it is not a documented extension point at v1.
 
+### Camera
+
+The camera is a **surface-scoped** pan/zoom: it lives on `handle.camera`, never on `editor.state`. View state and document state are disjoint — pan/zoom doesn't bump `state.version`, doesn't serialize, and isn't undoable. A second `attach_dom_surface(...)` gets its own camera.
+
+```ts
+handle.camera.center;            // world-space point at viewport center (Vec2)
+handle.camera.zoom;              // uniform scale; 1 = 100 %
+handle.camera.bounds;            // world Rect visible in the viewport
+handle.camera.viewport_size;     // { width, height } in screen px
+handle.camera.transform;         // underlying cmath.Transform (advanced read)
+
+handle.camera.pan({ x, y });     // translate by a screen-space delta
+handle.camera.zoom_at(factor, origin_screen);  // pinch / wheel-at-cursor
+handle.camera.set_center({ x, y });
+handle.camera.set_zoom(z, pivot_screen?);
+handle.camera.set_transform(t);  // idempotent — no notify when t === current
+
+handle.camera.fit("<root>");     // fit the document into the viewport
+handle.camera.fit("<selection>"); // fit current selection
+handle.camera.fit(nodeId);
+handle.camera.fit(rect, { margin: 64 });
+handle.camera.reset();           // identity
+
+handle.camera.subscribe(cb): Unsubscribe; // transient channel — no state.version bump
+```
+
+`set_transform` is **idempotent by contract**: when the new transform is element-wise equal to the current, the call is a no-op (no notification fires). This is what makes host-side "subscribe → derive → set" loops (constraints, snap, sync) terminate in finite steps — the [keynote example](#keynote-like-canvas-fixed-viewbox-slide-with-bounded-camera) relies on it.
+
+Default behavior: **identity on attach**. Pass `fit: true` to `attach_dom_surface(...)` and the camera fits `"<root>"` on the first frame — Excalidraw's `initialData.scrollToContent: true`, but on the surface. Subsequent `editor.load()` calls do **not** re-fit; that's a host concern (`editor.subscribe_with_selector(s => s.structure_version, () => handle.camera.fit("<root>"))` is the recipe).
+
+#### Gestures
+
+`handle.gestures` is sibling to `editor.keymap` — a layer of installable bindings. The default set is bundled on attach:
+
+| `id`               | trigger                              | effect                       |
+| ------------------ | ------------------------------------ | ---------------------------- |
+| `wheel-pan-zoom`   | plain wheel                          | `camera.pan(delta)`          |
+| `wheel-pan-zoom`   | Ctrl/Cmd + wheel, native pinch       | `camera.zoom_at(...)` at cursor |
+| `space-drag-pan`   | Space-down + drag                    | hand-tool pan                |
+| `middle-mouse-pan` | middle-button drag                   | pan                          |
+| `keyboard-zoom`    | `Shift+0` / `Shift+1` / `Shift+2`    | reset / fit root / fit selection |
+| `keyboard-zoom`    | `Cmd/Ctrl + =` / `Cmd/Ctrl + -`      | zoom in / out                |
+
+Swap as a unit (`attach_dom_surface(editor, { container, gestures: false })`) then call `handle.gestures.bind({ id, install: ctx => uninstall })` à la carte. **No per-gesture options bag** — if you disagree with a default, unbind it and bind your own. Same discipline as `editor.keymap`.
+
+#### `svg-boundary ≠ editor boundary`
+
+The SVG's intrinsic `width` / `height` / `viewBox` are *content*, not viewport. The camera frames space; the SVG sits in that space. A 1920×1080 attachment is fully serviced by `camera.fit("<root>")` + container CSS — there's no first-class "stage" concept (see [Deferred for v1](#deferred-for-v1)).
+
 ### Lifecycle
 
 ```ts
@@ -597,16 +802,18 @@ import {
   useSvgEditor,
   useEditorState,
   useCommands,
+  useCameraSnapshot,
 } from "@grida/svg-editor/react";
 ```
 
 That's the whole public surface.
 
 - `SvgEditorProvider` — owns the headless editor, puts it in context.
-- `SvgEditorCanvas` — the only UI component we ship; internally calls `attach_dom_surface(editor, { container: div })` on mount and `detach()` on unmount.
+- `SvgEditorCanvas` — the only UI component we ship; internally calls `attach_dom_surface(editor, { container: div, gestures, fit, initial_camera })` on mount and `detach()` on unmount. Pass `onAttach={setHandle}` to receive the `DomSurfaceHandle` (for `handle.camera` / `handle.gestures`).
 - `useSvgEditor()` — returns the editor instance from context.
-- `useEditorState(selector, equals?)` — subscribes to a slice of `editor.state` and re-renders on change. The subscription primitive.
+- `useEditorState(selector, equals?)` — subscribes to a slice of `editor.state` and re-renders on change.
 - `useCommands()` — sugar for `useSvgEditor().commands`.
+- `useCameraSnapshot(handle, selector, fallback)` — sibling to `useEditorState`, for the camera channel. Returns the selected value and re-renders on camera mutation; uses `fallback` while `handle` is null. The recipe lives in the package because both demos wrote it identically (see `/canvas/svg` and `/canvas/svg/keynote`).
 
 Top-level wiring:
 
@@ -803,6 +1010,9 @@ What v1 explicitly doesn't ship. Each is documented elsewhere with the v1 workar
 - **Non-DOM surfaces** (worker, React Native, headless test harness).
 - **Paint-server validity warnings** (dangling `url(#id)` references).
 - **Rotation gesture in the HUD.**
+- **Stage / bounded working area + `camera.constraints`.** *svg-boundary ≠ editor boundary*: the editor models an infinite canvas; the SVG's intrinsic `width` / `height` / `viewBox` are content, not viewport. Host code that wants Keynote-style bounded camera (lower-bounded zoom at fit; pan clamped so the slide always covers the viewport) writes ~25 lines of `subscribe + clamp + set_transform` against the public API — the recipe lives in the [keynote example above](#keynote-like-canvas-fixed-viewbox-slide-with-bounded-camera) and as a hook in the live demo at `/canvas/svg/keynote`. `Camera.set_transform` is intentionally idempotent so this loop terminates. A first-class `handle.camera.constraints = { bounds, padding, behavior }` (peer-validated via tldraw's `TLCameraConstraints`) is reserved for v2 — once we see a second use case, the recipe graduates.
+- **Persisted camera state.** Camera is surface-scoped and never enters `editor.state` / `editor.serialize()` / history. Hosts that want view bookmarks persist `handle.camera.transform` themselves.
+- **Gesture momentum / inertia / animated `fit`.** The `animate` shape isn't reserved in the type — it'll be added when delivered, not before.
 
 ## Anti-goals
 
@@ -820,7 +1030,7 @@ If a consumer needs any of the above, the right answer is "this is the wrong too
 
 ## Status
 
-`v1.0.0-alpha.1` — selection, translate, paint editing (solid + gradient), gradient defs, history, reorder, remove, set_text, keyboard shortcuts.
+`v1.0.0-alpha.3` — selection, translate, paint editing (solid + gradient), gradient defs, history, reorder, remove, set_text, keyboard shortcuts, **surface-scoped camera** (pan / zoom / fit with idempotent `set_transform`), **gestures layer** sibling to `editor.keymap` (wheel-pan-zoom, space-drag, middle-mouse-drag, keyboard zoom).
 
 Round-trip fidelity (P1) is the design invariant; the v1 surface is deliberately minimal and the [Low-level API](#low-level-api) is the escape hatch when the high-level API doesn't yet cover what you need.