@grida/svg-editor 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/dom-Dw2SPHgc.d.mts

@@ -0,0 +1,239 @@
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-CcW4BVth.mjs";
+import cmath from "@grida/cmath";
+import { guide } from "@grida/cmath/_snap";
+
+//#region src/util/attention.d.ts
+/** The runtime handle returned by `create_attention_tracker`. */
+interface AttentionTracker {
+  /**
+   * `true` iff focus is inside the attention scope (the container's
+   * subtree or a registered element's subtree) OR the pointer is
+   * currently over any element of the scope. See module doc for the
+   * rationale.
+   *
+   * Pure read; no DOM mutation. Cheap enough to call once per keydown.
+   */
+  is_attended(): boolean;
+  /**
+   * `true` iff focus is inside the attention scope — the focus arm of
+   * {@link is_attended} alone, WITHOUT the pointer-over arm.
+   *
+   * Exists for the native clipboard gate (`dom.ts`): pointer-over is a
+   * sufficient signal to claim a keystroke (worst case: a stolen scroll)
+   * but NOT a copy/cut/paste gesture (worst case: destroying what the
+   * user believed they copied, or routing a paste meant for a host text
+   * field into the document). See docs/wg/feat-svg-editor/clipboard.md
+   * §Transport "Gating the native events".
+   */
+  is_focus_within(): boolean;
+  /**
+   * Register a host-chrome element into the attention scope. Editor-
+   * adjacent chrome — an inspector, a toolbar, a zoom menu; anything that
+   * drives `commands.*` — is a DOM *sibling* of the container (the
+   * container is exclusively surface-owned), so without registration the
+   * tracker cannot tell it apart from unrelated page surface: clicking
+   * its buttons moves focus out of the container, and hovering it fires
+   * the container's `pointerleave`, blacking out the whole keymap.
+   * Registered elements count for both arms — focus-within and
+   * pointer-over. Idempotent; re-adding a registered element is a no-op.
+   */
+  add(element: Element): void;
+  /**
+   * Unregister an element added via {@link add}. Also clears any
+   * still-latched pointer-over contribution from it (the element may be
+   * unmounted mid-hover — e.g. a popover closing under the cursor).
+   * Unknown elements are a no-op. The container itself cannot be
+   * removed; it is the scope's fixed root, not a registered extra.
+   */
+  remove(element: Element): void;
+  /** Detach the internal pointer-tracking listeners (container and every
+   *  registered element). */
+  dispose(): void;
+}
+//#endregion
+//#region src/core/snap/options.d.ts
+type SnapOptions = {
+  /** When false, snap behavior and snap-guide rendering are both off. */enabled: boolean;
+  /** Snap threshold in HUD canvas pixels (container CSS px in svg-editor;
+   *  whatever space the consumer feeds in). Constant across zoom because
+   *  the input rects are already in screen-equivalent units. */
+  threshold_px: number;
+};
+declare const DEFAULT_SNAP_OPTIONS: SnapOptions;
+//#endregion
+//#region src/dom.d.ts
+/**
+ * Wire a web-font settle source to the editor's geometry channel.
+ *
+ * The DOM surface re-serializes the `<svg>` on every editor tick, but a
+ * `<text>` / `<tspan>` bbox can change with NO attribute write: a web font
+ * finishing load AFTER its `font-family` / `font-size` was already written.
+ * The IR never sees that reflow, so nothing bumps `geometry_version` and
+ * every bounds-keyed consumer (snap, HUD chrome, size meter) stays stuck at
+ * the fallback-face metrics until the next real edit.
+ *
+ * Listens for `loadingdone` on `source` (a `FontFaceSet`, or any injected
+ * `EventTarget` in tests) and calls `bump` once per settle. COARSE on
+ * purpose: one bump clears the WHOLE bounds cache, not just text nodes —
+ * consistent with the package's pessimistic-invalidation stance, and far
+ * cheaper than scoping the bump to the (possibly many) reflowed runs.
+ *
+ * Also bumps once when `source.ready` resolves (when present): fonts that
+ * settled before attach — a cache hit, or `font-display` resolving the same
+ * tick the surface mounts — never re-fire `loadingdone`, so a document
+ * mounted post-settle still needs one bump to re-read at the real metrics.
+ *
+ * Returns a teardown that removes the listener and neutralizes the pending
+ * `ready` bump (leak guard) — call it on surface detach.
+ *
+ * Factored out of the surface so it can be unit-tested with a fake
+ * `EventTarget` in the node-only test env (jsdom's `FontFaceSet` is
+ * incomplete); never a real font / network.
+ */
+declare function install_font_load_geometry_bump(source: EventTarget | null, bump: () => void): () => void;
+type DomSurfaceOptions = {
+  /** Mount the SVG inside this container. */container: HTMLElement;
+  /**
+   * Install the default gesture set (wheel-pan/zoom, space-drag, middle-mouse,
+   * keyboard zoom). Default `true`. Pass `false` to start blank and bind à la
+   * carte via `handle.gestures.bind(...)`.
+   */
+  gestures?: boolean;
+  /**
+   * Wire native ClipboardEvent transport — `copy` / `cut` / `paste`
+   * listeners on the owner document, gated by the clipboard attention
+   * discipline. Default `true`. Pass `false` to route ALL clipboard
+   * traffic through the `ClipboardProvider` seam instead (the
+   * configuration under which a host's paste-time screening governs
+   * every path) — see docs/wg/feat-svg-editor/clipboard.md §Transport
+   * "Host control over the native path". Focus management (the container
+   * focusing on pointerdown) stays either way — it is a general canvas
+   * mitigation, not a clipboard feature.
+   */
+  clipboard?: boolean;
+  /**
+   * Auto-fit the document into the viewport on initial attach. Default
+   * `false`. Mirrors Excalidraw's `initialData.scrollToContent`.
+   * Subsequent `editor.load()` calls do NOT re-fit — call
+   * `handle.camera.fit("<root>")` yourself if you want that behavior.
+   */
+  fit?: boolean;
+  /**
+   * Initial camera transform. Default `cmath.transform.identity`. Ignored
+   * when `fit: true`.
+   */
+  initial_camera?: cmath.Transform;
+  /**
+   * Font-load settle source — the `EventTarget` whose `loadingdone` event
+   * signals "web fonts finished loading, text may have reflowed." Defaults
+   * to `container.ownerDocument.fonts` (the live `FontFaceSet`). The
+   * surface installs a `loadingdone` listener that advances the editor's
+   * geometry channel so text bounds re-read at the settled glyph metrics
+   * (see ../docs/geometry.md §Limitations "Text bbox depends on font").
+   *
+   * Injectable as a DOM seam: jsdom's `FontFaceSet` is incomplete, so
+   * tests pass a plain `EventTarget` stub and `dispatchEvent(new Event(
+   * "loadingdone"))` to simulate a settle without a real font / network.
+   */
+  font_load_source?: EventTarget;
+};
+/**
+ * Host-extendable attention scope — public via `handle.attention`.
+ *
+ * The document-level keymap (undo / redo / delete / tool keys) is gated on
+ * attention: focus inside the scope, or pointer over it. The scope starts
+ * as the container alone, which makes editor-adjacent host chrome — an
+ * inspector, a toolbar, a zoom menu; anything that drives `commands.*` —
+ * indistinguishable from unrelated page surface (chrome must be a DOM
+ * *sibling* of the container, never a child). Registering a chrome element
+ * keeps the full keymap live while the user works in it, with
+ * text-input focus still excluded by the keymap's own guard. The native
+ * clipboard gate (deliberately stricter: focus-only, never pointer-over)
+ * honors the registered set's focus arm the same way.
+ *
+ * `add` is idempotent; `remove` of an unregistered element is a no-op.
+ * Registrations live for the surface's lifetime — `detach()` drops them
+ * with the tracker. Hosts with mounting/unmounting chrome (popovers,
+ * panels) pair `add` on mount with `remove` on unmount.
+ */
+type AttentionScope = Pick<AttentionTracker, "add" | "remove">;
+/**
+ * Surface handle for the DOM surface. Extends the editor's core
+ * `SurfaceHandle` with the viewport-scoped concerns: pan/zoom (`camera`),
+ * pointer/wheel/keyboard gesture bindings (`gestures`), and the
+ * host-extendable attention scope (`attention`).
+ *
+ * Camera, gestures, and attention are **surface-scoped**: detaching the
+ * surface drops all three. They never appear on the headless `SvgEditor`.
+ */
+type DomSurfaceHandle = SurfaceHandle & {
+  camera: Camera;
+  gestures: Gestures;
+  attention: AttentionScope;
+};
+/**
+ * Attach a DOM surface to a headless editor. Returns a `DomSurfaceHandle`
+ * whose `detach()` is the inverse — DOM cleared, listeners removed,
+ * gestures uninstalled.
+ *
+ * Usage is one-shot per container: the surface owns the container's children
+ * for its lifetime, and `detach()` restores it to empty.
+ */
+declare function attach_dom_surface(editor: SvgEditor, options: DomSurfaceOptions): DomSurfaceHandle;
+/**
+ * Affine projection of a point through a 2×3 CTM, then offset by a
+ * container origin (in page CSS-px). Mirrors how `line_endpoints_in_container`
+ * and `shape_of` (transformed branch) bridge from local SVG coords to the
+ * HUD's container-CSS-px space (HUD keeps its own transform at identity;
+ * the SVG carries the camera as a CSS transform, which getScreenCTM
+ * folds in).
+ *
+ * Exported for headless test coverage — pure function, no DOM types.
+ */
+declare function project_point_through_ctm(px: number, py: number, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, container_offset: readonly [number, number]): [number, number];
+/**
+ * Inverse of the CTM's linear part applied to a delta vector. Drops
+ * translation. Used to convert a HUD-reported container-space drag delta
+ * back to the path's local coord space for `PathModel.translateVertices`.
+ *
+ * Throws on a degenerate (det = 0) matrix — the caller is expected to
+ * have a non-singular CTM for any visible element.
+ */
+declare function project_delta_inverse_ctm(dx: number, dy: number, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+}): [number, number];
+/**
+ * Inverse-project a doc-space rect through a CTM + container offset back
+ * into the element's local frame. The output is the AABB of the four
+ * inverse-projected corners — when the CTM has a rotation component the
+ * AABB is an approximation, but it matches what the user visually
+ * expects from a screen-aligned marquee drag.
+ *
+ * Returns `null` when the CTM's linear part is singular (degenerate
+ * camera) — the caller should skip any test that needs the local rect.
+ */
+declare function inverse_project_rect(rect: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, offset: readonly [number, number]): cmath.Rectangle | null;
+//#endregion
+export { install_font_load_geometry_bump as a, project_point_through_ctm as c, attach_dom_surface as i, DEFAULT_SNAP_OPTIONS as l, DomSurfaceHandle as n, inverse_project_rect as o, DomSurfaceOptions as r, project_delta_inverse_ctm as s, AttentionScope as t, SnapOptions as u };

package/dist/dom.d.mts

@@ -1,16 +1,3 @@
-import { a as SurfaceHandle, o as SvgEditor } from "./editor-BryibVvr.mjs";
-
-//#region src/dom.d.ts
-type DomSurfaceOptions = {
-  /** Mount the SVG inside this container. */container: HTMLElement;
-};
-/**
- * Attach a DOM surface to a headless editor. Returns a `SurfaceHandle` whose
- * `detach()` is the inverse — DOM cleared, listeners removed.
- *
- * Usage is one-shot per container: the surface owns the container's children
- * for its lifetime, and `detach()` restores it to empty.
- */
-declare function attach_dom_surface(editor: SvgEditor, options: DomSurfaceOptions): SurfaceHandle;
-//#endregion
-export { DomSurfaceOptions, attach_dom_surface };
+import { C as BoundsResolver, E as CameraOptions, T as CameraConstraints, d as GestureContext, f as GestureId, g as MemoizedGeometryProvider, h as GeometrySignals, i as DomComputedResolver, m as GeometryProvider, p as Gestures, r as DomComputedPaint, u as GestureBinding, w as Camera } from "./editor-CcW4BVth.mjs";
+import { a as install_font_load_geometry_bump, c as project_point_through_ctm, i as attach_dom_surface, l as DEFAULT_SNAP_OPTIONS, n as DomSurfaceHandle, o as inverse_project_rect, r as DomSurfaceOptions, s as project_delta_inverse_ctm, t as AttentionScope, u as SnapOptions } from "./dom-Dw2SPHgc.mjs";
+export { AttentionScope, type BoundsResolver, Camera, type CameraConstraints, type CameraOptions, DEFAULT_SNAP_OPTIONS, type DomComputedPaint, type DomComputedResolver, DomSurfaceHandle, DomSurfaceOptions, type GeometryProvider, type GeometrySignals, type GestureBinding, type GestureContext, type GestureId, Gestures, MemoizedGeometryProvider, type SnapOptions, attach_dom_surface, install_font_load_geometry_bump, inverse_project_rect, project_delta_inverse_ctm, project_point_through_ctm };

package/dist/dom.d.ts

@@ -1,16 +1,3 @@
-import { a as SurfaceHandle, o as SvgEditor } from "./editor-klT8wu-x.js";
-
-//#region src/dom.d.ts
-type DomSurfaceOptions = {
-  /** Mount the SVG inside this container. */container: HTMLElement;
-};
-/**
- * Attach a DOM surface to a headless editor. Returns a `SurfaceHandle` whose
- * `detach()` is the inverse — DOM cleared, listeners removed.
- *
- * Usage is one-shot per container: the surface owns the container's children
- * for its lifetime, and `detach()` restores it to empty.
- */
-declare function attach_dom_surface(editor: SvgEditor, options: DomSurfaceOptions): SurfaceHandle;
-//#endregion
-export { DomSurfaceOptions, attach_dom_surface };
+import { C as BoundsResolver, E as CameraOptions, T as CameraConstraints, d as GestureContext, f as GestureId, g as MemoizedGeometryProvider, h as GeometrySignals, i as DomComputedResolver, m as GeometryProvider, p as Gestures, r as DomComputedPaint, u as GestureBinding, w as Camera } from "./editor-CxqRhhzP.js";
+import { a as install_font_load_geometry_bump, c as project_point_through_ctm, i as attach_dom_surface, l as DEFAULT_SNAP_OPTIONS, n as DomSurfaceHandle, o as inverse_project_rect, r as DomSurfaceOptions, s as project_delta_inverse_ctm, t as AttentionScope, u as SnapOptions } from "./dom-CQkWJNrK.js";
+export { AttentionScope, type BoundsResolver, Camera, type CameraConstraints, type CameraOptions, DEFAULT_SNAP_OPTIONS, type DomComputedPaint, type DomComputedResolver, DomSurfaceHandle, DomSurfaceOptions, type GeometryProvider, type GeometrySignals, type GestureBinding, type GestureContext, type GestureId, Gestures, MemoizedGeometryProvider, type SnapOptions, attach_dom_surface, install_font_load_geometry_bump, inverse_project_rect, project_delta_inverse_ctm, project_point_through_ctm };

package/dist/dom.js

@@ -1,3 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dom = require("./dom-CfP_ZURh.js");
+const require_dom = require("./dom-CuK0LFUY.js");
+exports.Camera = require_dom.Camera;
+exports.DEFAULT_SNAP_OPTIONS = require_dom.DEFAULT_SNAP_OPTIONS;
+exports.Gestures = require_dom.Gestures;
+exports.MemoizedGeometryProvider = require_dom.MemoizedGeometryProvider;
 exports.attach_dom_surface = require_dom.attach_dom_surface;
+exports.install_font_load_geometry_bump = require_dom.install_font_load_geometry_bump;
+exports.inverse_project_rect = require_dom.inverse_project_rect;
+exports.project_delta_inverse_ctm = require_dom.project_delta_inverse_ctm;
+exports.project_point_through_ctm = require_dom.project_point_through_ctm;

package/dist/dom.mjs

@@ -1,2 +1,2 @@
-import { t as attach_dom_surface } from "./dom-kA8NDuVh.mjs";
-export { attach_dom_surface };
+import { a as project_point_through_ctm, c as MemoizedGeometryProvider, i as project_delta_inverse_ctm, l as Camera, n as install_font_load_geometry_bump, o as Gestures, r as inverse_project_rect, s as DEFAULT_SNAP_OPTIONS, t as attach_dom_surface } from "./dom-DHaTIObb.mjs";
+export { Camera, DEFAULT_SNAP_OPTIONS, Gestures, MemoizedGeometryProvider, attach_dom_surface, install_font_load_geometry_bump, inverse_project_rect, project_delta_inverse_ctm, project_point_through_ctm };