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

package/dist/dom-Y2QR7QSi.d.ts

@@ -0,0 +1,318 @@
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-kFTYSb_8.js";
+import cmath from "@grida/cmath";
+//#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];
+/**
+ * The matrix form of {@link project_point_through_ctm}: the full
+ * `local → container-px` affine for a CTM + container offset, as a
+ * `cmath.Transform`. Use when handing the transform to a downstream projector
+ * (e.g. HUD chrome) instead of projecting a single point.
+ *
+ * Pure function, no DOM types.
+ */
+declare function ctm_to_container_transform(ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, container_offset: readonly [number, number]): cmath.Transform;
+/**
+ * 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];
+/**
+ * Map a transform-box reduced affine (box-relative, as emitted by the HUD
+ * `transform_box` intent) into the element's path-LOCAL coordinate space,
+ * ready to feed {@link PathModel.transformVertices} (Vertex Transform Box,
+ * gridaco/grida#881).
+ *
+ * The transform box lives in container CSS-px: a rect at `box_origin` of
+ * dimensions `box_size`, rotated by `box_rotation` degrees (CCW) about
+ * `box_origin` — the box's own frame, which may be non-axis-aligned once the
+ * session has rotated it. The HUD reports its gesture as a box-relative 2×3
+ * whose translation column is normalized to `[0..1]` against `box_size` (see
+ * `@grida/hud` transform-box). The mapping composes three stages — right-to-
+ * left, so a local point is taken to container space first:
+ *
+ *     M_local = CTM⁻¹ · ( B · P · B⁻¹ ) · CTM,   B = T(o) · R(box_rotation)
+ *
+ *   - `CTM` = `local_to_container` (the element's CTM folded with the
+ *     container offset; see {@link ctm_to_container_transform}).
+ *   - `P` = `box_transform` with its translation de-normalized back to
+ *     container-px (`tx·w`, `ty·h`) — the box's transform in its own un-rotated
+ *     "box pixel" space (origin at the box's `[0,0]`).
+ *   - `B` re-anchors that box-pixel transform to the box's placement in
+ *     container space: translate to `box_origin`, rotated by `box_rotation`.
+ *     The HUD de-rotates the cursor by `-box_rotation` before reducing, so a
+ *     scale on a rotated box scales along the box's rotated axes.
+ *
+ * The result is the world→local round-trip of the box affine, so a rotate /
+ * scale composes correctly into local geometry through a scaled, rotated, or
+ * y-flipped element CTM. Pure, no DOM types. A zero-`box_size` axis is harmless
+ * (its translation contribution is `0`); guarding the gesture against a
+ * collapsed axis is the caller's job. `local_to_container` must be non-singular
+ * (any visible element's CTM is).
+ */
+declare function box_transform_to_local_affine(box_transform: cmath.Transform, box_origin: readonly [number, number], box_size: readonly [number, number], local_to_container: cmath.Transform, box_rotation?: number): cmath.Transform;
+/**
+ * Derive an oriented-bbox frame `{ origin, size, rotation }` (HUD transform-box
+ * shape; `rotation` in degrees CCW) from a rectangle's four container-px
+ * corners, given in `[nw, ne, se, sw]` order (Vertex Transform Box,
+ * gridaco/grida#881). The box's width axis is `ne − nw` and its height axis is
+ * `sw − nw`; assumes a (near-)rectangular quad — true under a similarity CTM,
+ * an approximation under a sheared one. Pure, no DOM types.
+ */
+declare function obb_frame_from_corners(corners: {
+  nw: readonly [number, number];
+  ne: readonly [number, number];
+  sw: readonly [number, number];
+}): {
+  origin: [number, number];
+  size: [number, number];
+  rotation: number;
+};
+/**
+ * Grow a baseline (local-space) bbox so each axis spans at least `min_px`
+ * container pixels, given the current local→container per-axis scale. A
+ * degenerate axis (a line, where one axis collapses) becomes a grabbable,
+ * rotatable strip; padding is centered so the strip stays on the points.
+ *
+ * Returns `null` when BOTH axes are below `min_px` (a point — no box).
+ *
+ * Pure, and evaluated against the CURRENT scale at projection time (NOT baked
+ * into the persisted session), so a line box stays a stable container-px strip
+ * across zoom / CTM changes rather than going stale at the establishment zoom
+ * (gridaco/grida#881 review).
+ */
+declare function pad_box_min_axis(bbox: cmath.Rectangle, scale_x: number, scale_y: number, min_px: number): cmath.Rectangle | null;
+/**
+ * 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 { box_transform_to_local_affine as a, inverse_project_rect as c, project_delta_inverse_ctm as d, project_point_through_ctm as f, attach_dom_surface as i, obb_frame_from_corners as l, SnapOptions as m, DomSurfaceHandle as n, ctm_to_container_transform as o, DEFAULT_SNAP_OPTIONS as p, DomSurfaceOptions as r, install_font_load_geometry_bump as s, AttentionScope as t, pad_box_min_axis as u };