@grida/svg-editor 1.0.0-alpha.1

package/dist/editor-CTtU2gu4.d.ts

@@ -0,0 +1,607 @@
+import { Keybinding, Platform } from "@grida/keybinding";
+
+//#region src/commands/registry.d.ts
+/**
+ * Command registry.
+ *
+ * A passive id-keyed registry of handlers. Built so that:
+ *
+ *  - keybindings (in `src/keymap`) can address commands by stable id;
+ *  - new commands can be added in ONE place (`src/commands/defaults.ts`)
+ *    without growing the public surface of the editor;
+ *  - "one key, many meanings" can be expressed via chain semantics: a
+ *    handler returns `true` if it consumed, `false`/`void` otherwise,
+ *    and the dispatcher tries the next candidate in the chain.
+ *
+ * Handlers are plain closures — they capture whatever editor reference
+ * they need. The registry itself stays unaware of the editor's type,
+ * which avoids a circular type dependency between editor and registry.
+ */
+/** Stable, dotted id for a command, e.g. `"history.undo"`. */
+type CommandId = string;
+/**
+ * A command handler.
+ *
+ * Return `true` if the handler consumed the invocation. Return `false`
+ * or `undefined` to signal "did not apply" — the dispatcher will try
+ * the next candidate registered for the same key.
+ *
+ * Handlers are closures: they capture their editor reference. No
+ * editor parameter is passed — keep handlers self-contained.
+ */
+type CommandHandler = (args?: unknown) => boolean | void;
+declare class CommandRegistry {
+  private readonly map;
+  /**
+   * Register a command. Returns an unregister function. Re-registering
+   * the same id replaces the previous handler (last writer wins).
+   */
+  register(id: CommandId, handler: CommandHandler): () => void;
+  /**
+   * Invoke a command by id. Returns `true` if the handler consumed,
+   * `false` otherwise (including unknown ids and handlers that returned
+   * `false`/`undefined`).
+   */
+  invoke(id: CommandId, args?: unknown): boolean;
+  has(id: CommandId): boolean;
+  /** All registered ids, for debugging / introspection. */
+  ids(): readonly CommandId[];
+}
+//#endregion
+//#region src/keymap/keymap.d.ts
+type KeymapBinding = {
+  /** Declarative key combination. Build with `kb()` / `c()` / `seq()`. */keybinding: Keybinding; /** Command id to invoke on match. */
+  command: CommandId; /** Forwarded as the `args` parameter to the command handler. */
+  args?: unknown; /** Higher priorities run first in the chain. Default 0. */
+  priority?: number;
+  /**
+   * Reserved for V2; not honored by the V1 dispatcher. When added, this
+   * will be evaluated before the handler runs; if false, the binding is
+   * skipped without invoking the handler.
+   */
+  when?: (ctx: unknown) => boolean;
+};
+declare class Keymap {
+  private readonly commands;
+  private readonly platformGetter;
+  /**
+   * Bindings bucketed by canonical chunk-key hash, computed per
+   * `@grida/keybinding`'s `chunkKey`. Each list is the chain for that
+   * key, sorted in dispatch order (priority desc, then registration
+   * order).
+   */
+  private readonly buckets;
+  /** Insert order, so ties on priority are deterministic. */
+  private seq;
+  constructor(commands: CommandRegistry, platformGetter?: () => Platform);
+  /**
+   * Bind a key combination to a command. Returns an unbind function.
+   * The same `Keybinding` can be bound to multiple commands — they will
+   * all be tried in chain order on dispatch.
+   */
+  bind(binding: KeymapBinding): () => void;
+  /**
+   * Remove bindings matching the spec. If both filters are passed, only
+   * bindings that match BOTH are removed.
+   */
+  unbind(spec: {
+    keybinding?: Keybinding;
+    command?: CommandId;
+  }): void;
+  /** All registered bindings, for introspection. Order is not guaranteed. */
+  bindings(): readonly KeymapBinding[];
+  /**
+   * Match the event against bound chunks, then run candidates in chain
+   * order. Returns `true` and calls `preventDefault()` on the first
+   * handler that consumes; returns `false` if nothing matched or all
+   * matches fell through.
+   */
+  dispatch(event: KeyboardEvent): boolean;
+  /**
+   * Compute the set of canonical hashes a `Keybinding` lights up. A
+   * binding with aliases (multiple sequences) contributes one hash per
+   * single-chunk alias; multi-chunk sequences (chords) are skipped in
+   * V1.
+   */
+  private chunkKeysFor;
+  private has_safe_mod;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Stable identifier for a node in the editor's document model.
+ *
+ * Independent of any backing representation. Generated when the document is
+ * parsed.
+ */
+type NodeId = string;
+type Vec2 = {
+  x: number;
+  y: number;
+};
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type Mode = "select" | "edit-content";
+type Provenance = {
+  /** CSS cascade origin (css-cascade-5 §6.2). */origin: "author" | "user_agent"; /** Editor metadata — where in the file the winning declaration lives. */
+  carrier: "presentation_attribute" | "inline_style" | "stylesheet" | "inherited" | "defaulted";
+};
+type InvalidComputedValue = {
+  error: "invalid_at_computed_value_time";
+  reason: string;
+};
+type PropertyValue<T = string | number> = {
+  declared: string | null;
+  computed: T | InvalidComputedValue | null;
+  provenance: Provenance;
+};
+type Color = {
+  kind: "rgb";
+  value: string;
+} | {
+  kind: "current_color";
+};
+type PaintFallback = {
+  kind: "none";
+} | {
+  kind: "color";
+  value: Color;
+};
+type Paint = {
+  kind: "none";
+} | {
+  kind: "color";
+  value: Color;
+} | {
+  kind: "ref";
+  id: string;
+  fallback?: PaintFallback;
+} | {
+  kind: "context_fill";
+} | {
+  kind: "context_stroke";
+};
+type PaintValue = {
+  declared: string | null;
+  computed: Paint | InvalidComputedValue | null;
+  provenance: Provenance;
+};
+type GradientStop = {
+  offset: number;
+  color: string;
+  opacity?: number;
+};
+type LinearGradientDefinition = {
+  kind: "linear";
+  stops: GradientStop[];
+  x1?: number;
+  y1?: number;
+  x2?: number;
+  y2?: number;
+  gradient_units?: "user_space_on_use" | "object_bounding_box";
+  spread_method?: "pad" | "reflect" | "repeat";
+};
+type RadialGradientDefinition = {
+  kind: "radial";
+  stops: GradientStop[];
+  cx?: number;
+  cy?: number;
+  r?: number;
+  fx?: number;
+  fy?: number;
+  gradient_units?: "user_space_on_use" | "object_bounding_box";
+  spread_method?: "pad" | "reflect" | "repeat";
+};
+type GradientDefinition = LinearGradientDefinition | RadialGradientDefinition;
+type GradientEntry = {
+  id: string;
+  definition: GradientDefinition;
+  ref_count: number;
+};
+type EditorStyle = {
+  chrome_color: string;
+  handle_size: number;
+  handle_fill: string;
+  handle_stroke: string;
+  endpoint_dot_radius: number;
+  selection_outline_width: number;
+  /**
+   * Color for measurement guides (distance lines + numeric pills). Distinct
+   * from `chrome_color` so the user can tell at a glance whether something
+   * is selection chrome or a measurement readout.
+   */
+  measurement_color: string;
+};
+declare const DEFAULT_STYLE: EditorStyle;
+type ClipboardProvider = {
+  read(): Promise<string | null>;
+  write(text: string): Promise<void>;
+};
+type FontResolver = {
+  resolve(family: string): Promise<{
+    available: boolean;
+    metrics?: {
+      ascent: number;
+      descent: number;
+      unitsPerEm: number;
+    };
+  }>;
+};
+type FileIOProvider = {
+  openSvg(): Promise<string | null>;
+  saveSvg(svg: string, suggestedName?: string): Promise<void>;
+};
+type Providers = {
+  clipboard?: ClipboardProvider;
+  fonts?: FontResolver;
+  file_io?: FileIOProvider;
+};
+type EditorState = {
+  readonly selection: ReadonlyArray<NodeId>;
+  readonly scope: NodeId | null;
+  readonly mode: Mode;
+  readonly dirty: boolean;
+  readonly can_undo: boolean;
+  readonly can_redo: boolean;
+  /**
+   * Bumps on every editor emission. Use this when you need to react to
+   * any change — selection, history, mutation. NOT a good cache key for
+   * tree-shape views because it fires on attribute writes too (e.g. x/y
+   * during a drag).
+   */
+  readonly version: number;
+  /**
+   * Bumps only when the document's tree shape or display-label-affecting
+   * data changes — node added/removed/reordered, text content, or the
+   * `id` attribute. Stable across pure presentation-attribute writes.
+   *
+   * The right cache key for hierarchy / layers panels: snapshot once per
+   * `structure_version` so a drag doesn't invalidate the tree view.
+   */
+  readonly structure_version: number;
+};
+type Unsubscribe = () => void;
+type ReorderDirection = "bring_forward" | "send_backward" | "bring_to_front" | "send_to_back";
+type PreviewSession = {
+  update(value: string): void;
+  commit(): void;
+  discard(): void;
+};
+type PaintPreviewSession = {
+  update(paint: Paint): void;
+  commit(): void;
+  discard(): void;
+};
+//#endregion
+//#region src/core/parser.d.ts
+type AttrToken = {
+  /** Verbatim source name including any prefix, e.g. "xlink:href". */raw_name: string; /** Prefix or null. */
+  prefix: string | null; /** Local name. */
+  local: string; /** Resolved namespace URI, or null if unprefixed and no default ns. */
+  ns: string | null; /** Raw attribute value string (entity-decoded). */
+  value: string; /** Trivia before the attribute name (whitespace, usually `" "`). */
+  pre: string; /** Trivia between `=` and the value (usually empty). */
+  eq_trivia: string; /** Quote character (`"` or `'`). */
+  quote: '"' | "'";
+};
+type ElementNode = {
+  kind: "element";
+  id: NodeId;
+  parent: NodeId | null; /** Verbatim tag name with prefix. */
+  raw_tag: string;
+  prefix: string | null;
+  local: string;
+  ns: string | null;
+  attrs: AttrToken[];
+  children: NodeId[]; /** True if the source wrote `<tag/>` (no children). */
+  self_closing: boolean; /** Trivia inside the tag before `>` or `/>` (e.g. `" "` in `<tag />`). */
+  open_tag_trailing: string; /** Trivia between `</` and tag name in the close, e.g. usually empty. */
+  close_tag_leading: string; /** Trivia after the closing tag name before `>`, usually empty. */
+  close_tag_trailing: string;
+};
+type TextNode = {
+  kind: "text";
+  id: NodeId;
+  parent: NodeId | null; /** Verbatim text, entity-decoded. */
+  value: string;
+};
+type CommentNode = {
+  kind: "comment";
+  id: NodeId;
+  parent: NodeId | null; /** Comment body (between `<!--` and `-->`). */
+  value: string;
+};
+type CDataNode = {
+  kind: "cdata";
+  id: NodeId;
+  parent: NodeId | null;
+  value: string;
+};
+type PiNode = {
+  kind: "pi";
+  id: NodeId;
+  parent: NodeId | null; /** PI target, e.g. "xml" for `<?xml ... ?>`. */
+  target: string;
+  value: string;
+};
+type DoctypeNode = {
+  kind: "doctype";
+  id: NodeId;
+  parent: NodeId | null; /** Full doctype declaration body, e.g. `svg PUBLIC "..." "..."`. */
+  value: string;
+};
+type AnyNode = ElementNode | TextNode | CommentNode | CDataNode | PiNode | DoctypeNode;
+//#endregion
+//#region src/core/document.d.ts
+interface DocumentEvents {
+  /** Fires after any structural mutation. */
+  on_change(fn: () => void): () => void;
+}
+declare class SvgDocument implements DocumentEvents {
+  private nodes;
+  private prolog;
+  private epilog;
+  /** Snapshot of the input string, used for `reset()`. */
+  private source;
+  /** Original parse result, for `reset()`. */
+  private original;
+  readonly root: NodeId;
+  private listeners;
+  /**
+   * Counter that bumps ONLY when something the hierarchy view cares about
+   * changes — tree topology (`insert`/`remove`), text-node content
+   * (`set_text`), or the `id` attribute (which feeds display labels). Pure
+   * presentation-attribute writes (x, y, fill, …) do NOT bump it.
+   *
+   * Why a separate counter: consumers like the layers panel cache snapshots
+   * keyed on this. During a drag, x/y writes fire `emit()` repeatedly but
+   * `structure_version` stays stable, so the panel's snapshot reference
+   * stays the same and React skips the re-render of the whole tree.
+   */
+  private _structure_version;
+  constructor(svg: string);
+  static parse(svg: string): SvgDocument;
+  /** Reload from the original parse, discarding all edits. */
+  reset_to_original(): void;
+  /** Replace document with new svg source (clears edits + history-owned state). */
+  load(svg: string): void;
+  on_change(fn: () => void): () => void;
+  /** See `_structure_version` for what this counter signals. */
+  get structure_version(): number;
+  private emit;
+  /** Notify subscribers — for callers that mutate directly via setAttr/etc. */
+  notify(): void;
+  get(id: NodeId): AnyNode | null;
+  is_element(id: NodeId): boolean;
+  parent_of(id: NodeId): NodeId | null;
+  children_of(id: NodeId): readonly NodeId[];
+  /** Element children only — text/comment/cdata filtered out. */
+  element_children_of(id: NodeId): readonly NodeId[];
+  next_sibling_of(id: NodeId): NodeId | null;
+  next_element_sibling_of(id: NodeId): NodeId | null;
+  tag_of(id: NodeId): string;
+  contains(ancestor: NodeId, descendant: NodeId): boolean;
+  all_nodes(): readonly NodeId[];
+  all_elements(): readonly NodeId[];
+  find_by_tag(ancestor: NodeId, tag: string): readonly NodeId[];
+  /** Read attribute by local name, optionally namespace-filtered. */
+  get_attr(id: NodeId, name: string, ns?: string | null): string | null;
+  /**
+   * Set / remove an attribute. If the attribute exists, it is mutated in place
+   * (preserving source position). If it doesn't, it's appended.
+   */
+  set_attr(id: NodeId, name: string, value: string | null, ns?: string | null): void;
+  attributes_of(id: NodeId): {
+    name: string;
+    ns: string | null;
+    value: string;
+  }[];
+  get_style(id: NodeId, property: string): string | null;
+  set_style(id: NodeId, property: string, value: string | null): void;
+  get_all_styles(id: NodeId): Array<{
+    property: string;
+    value: string;
+  }>;
+  text_of(id: NodeId): string;
+  /** Replace all direct text children with a single text node carrying `value`. */
+  set_text(id: NodeId, value: string): void;
+  insert(id: NodeId, parent: NodeId, before: NodeId | null): void;
+  remove(id: NodeId): void;
+  /** Create a new element node and register it (not yet inserted). */
+  create_element(local: string, opts?: {
+    prefix?: string | null;
+    ns?: string | null;
+  }): NodeId;
+  serialize(): string;
+  private emit_node;
+  private emit_attr;
+}
+//#endregion
+//#region src/core/defs.d.ts
+interface GradientsApi {
+  list(): ReadonlyArray<GradientEntry>;
+  get(id: string): GradientEntry | null;
+  upsert(definition: GradientDefinition, opts?: {
+    id?: string;
+  }): string;
+  remove(id: string): void;
+  subscribe(fn: (entries: ReadonlyArray<GradientEntry>) => void): Unsubscribe;
+}
+type Defs = {
+  gradients: GradientsApi;
+};
+//#endregion
+//#region src/core/properties.d.ts
+declare function read_property(doc: SvgDocument, id: NodeId, property: string): PropertyValue;
+//#endregion
+//#region src/core/editor.d.ts
+/** Resolved paint from the DOM-attached cascade. `resolved_paint` mirrors the
+ *  shape of `PaintValue.computed` so consumers can treat it uniformly with
+ *  the headless cascade. */
+type DomComputedPaint = {
+  computed: string;
+  resolved_paint: Paint | InvalidComputedValue | null;
+};
+/** Contract the DOM surface implements to delegate cascade resolution to
+ *  `getComputedStyle()`. Registered via `editor._internal.set_computed_resolver`
+ *  on attach. */
+type DomComputedResolver = {
+  computed_property(id: NodeId, name: string): string | null;
+  computed_paint(id: NodeId, channel: "fill" | "stroke"): DomComputedPaint | null;
+};
+type CreateSvgEditorOptions = {
+  svg: string;
+  providers?: Providers;
+  style?: Partial<EditorStyle>;
+};
+type SvgEditor = ReturnType<typeof createSvgEditor>;
+type Surface = {
+  paint(snapshot: unknown): void;
+  hit_test(x: number, y: number): NodeId | null;
+  on_input(listener: (event: unknown) => void): Unsubscribe;
+  dispose(): void;
+};
+type SurfaceHandle = {
+  detach(): void;
+};
+type Commands = {
+  select(target: NodeId | ReadonlyArray<NodeId>, opts?: {
+    additive?: boolean;
+  }): void;
+  deselect(): void;
+  enter_scope(group: NodeId): void;
+  exit_scope(): void;
+  set_mode(mode: Mode): void;
+  set_property(name: string, value: string | null): void;
+  preview_property(name: string): PreviewSession;
+  set_paint(channel: "fill" | "stroke", paint: Paint): void;
+  preview_paint(channel: "fill" | "stroke"): PaintPreviewSession;
+  set_paint_from_gradient(channel: "fill" | "stroke", definition: GradientDefinition, opts?: {
+    reuse_existing?: boolean;
+  }): {
+    gradient_id: string;
+  };
+  translate(delta: {
+    dx: number;
+    dy: number;
+  }): void;
+  reorder(direction: ReorderDirection): void;
+  remove(): void;
+  set_text(value: string): void;
+  load_svg(svg: string): void;
+  serialize_svg(): string;
+  undo(): void;
+  redo(): void;
+  /**
+   * Register a command handler under a stable id. Returns an unregister
+   * function. Re-registering the same id replaces the previous handler.
+   *
+   * Handlers return `true` if they consumed the invocation; `false` or
+   * `undefined` signal "did not apply" — the keymap dispatcher will try
+   * the next candidate in the chain.
+   */
+  register(id: CommandId, handler: CommandHandler): () => void;
+  /**
+   * Invoke a registered command by id. Returns `true` if a handler
+   * consumed the invocation, `false` otherwise (including unknown ids).
+   */
+  invoke(id: CommandId, args?: unknown): boolean; /** Whether an id has a registered handler. */
+  has(id: CommandId): boolean;
+};
+declare function createSvgEditor(opts: CreateSvgEditorOptions): {
+  /**
+   * Low-level IR handle. Mutating directly bypasses history; prefer
+   * `editor.commands` for app code.
+   */
+  document: SvgDocument;
+  readonly state: EditorState;
+  subscribe: (fn: (state: EditorState) => void) => Unsubscribe;
+  subscribe_with_selector: <T>(selector: (s: EditorState) => T, fn: (value: T, prev: T) => void, equals?: (a: T, b: T) => boolean) => Unsubscribe;
+  node_properties: (id: NodeId, names: ReadonlyArray<string>) => {
+    readonly [name: string]: ReturnType<typeof read_property>;
+  };
+  node_paint: (id: NodeId, channel: "fill" | "stroke") => PaintValue;
+  dom_computed_property: (id: NodeId, name: string) => string | null;
+  dom_computed_paint: (id: NodeId, channel: "fill" | "stroke") => DomComputedPaint | null;
+  /**
+   * Enter content-edit mode on a `<text>` node. Returns `false` (no-op)
+   * when no DOM surface is attached.
+   */
+  enter_content_edit: (target?: NodeId) => boolean;
+  defs: Defs;
+  commands: Commands;
+  /**
+   * Human-readable label for hierarchy panels. SVG has no native "name";
+   * this is the package's single source of truth so panels don't reinvent
+   * the rule.
+   *
+   * Rule:
+   *   - `<text>` → text content, whitespace-collapsed and truncated at
+   *     ~40 chars (falls back to `"text"` for empty content).
+   *   - Otherwise → tag name, suffixed with `#id` when the `id` attribute
+   *     is present (e.g. `"rect #sun"`).
+   *
+   * `opts.tagLabel` lets callers substitute a friendlier or localized
+   * term for the raw tag (e.g. `"rect"` → `"Rectangle"`). Only invoked
+   * on the non-text branch.
+   */
+  display_label(id: NodeId, opts?: {
+    tagLabel?: (tag: string) => string;
+  }): string;
+  tree(): {
+    root: NodeId;
+    nodes: ReadonlyMap<NodeId, {
+      id: NodeId;
+      tag: string;
+      name?: string;
+      parent: NodeId | null;
+      children: ReadonlyArray<NodeId>;
+    }>;
+  };
+  /**
+   * The effective hover from the attached HUD surface — what's under the
+   * pointer, OR whatever `set_surface_hover_override` last pushed. Used
+   * by out-of-canvas UI (layers panel, breadcrumbs) to mirror the canvas
+   * highlight. Returns `null` when nothing is hovered.
+   */
+  surface_hover(): NodeId | null;
+  /**
+   * 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 and (when applicable) drive measurement to that node.
+   * Pass `null` to clear and let the pointer pick take over again.
+   */
+  set_surface_hover_override(id: NodeId | null): void;
+  /**
+   * Subscribe to changes in the effective surface hover. Fires when the
+   * HUD reports a new pointer pick AND when an override is set/cleared.
+   * Cheap channel — does NOT bump `state.version`.
+   */
+  subscribe_surface_hover(cb: () => void): () => void;
+  modes: readonly Mode[];
+  readonly style: Readonly<EditorStyle>;
+  set_style: (partial: Partial<EditorStyle>) => void;
+  load: (svg: string) => void;
+  serialize: () => string;
+  reset: () => void;
+  attach: (surface: Surface) => SurfaceHandle;
+  detach: () => void;
+  dispose: () => void;
+  providers: Providers;
+  _internal: {
+    doc: SvgDocument;
+    set_content_edit_driver(fn: ((target: NodeId) => boolean) | null): void;
+    /** Fires the driver immediately with the current override so the
+     *  surface can sync state on attach. */
+    set_surface_hover_override_driver(fn: ((id: NodeId | null) => void) | null): void;
+    push_surface_hover(id: NodeId | null): void;
+    set_computed_resolver(fn: DomComputedResolver | null): void;
+  };
+  keymap: Keymap;
+};
+//#endregion
+export { RadialGradientDefinition as A, PaintFallback as C, PropertyValue as D, PreviewSession as E, KeymapBinding as F, CommandHandler as I, CommandId as L, ReorderDirection as M, Unsubscribe as N, Provenance as O, Vec2 as P, Paint as S, PaintValue as T, GradientStop as _, SurfaceHandle as a, Mode as b, ClipboardProvider as c, EditorState as d, EditorStyle as f, GradientEntry as g, GradientDefinition as h, DomComputedResolver as i, Rect as j, Providers as k, Color as l, FontResolver as m, CreateSvgEditorOptions as n, SvgEditor as o, FileIOProvider as p, DomComputedPaint as r, createSvgEditor as s, Commands as t, DEFAULT_STYLE as u, InvalidComputedValue as v, PaintPreviewSession as w, NodeId as x, LinearGradientDefinition as y };