@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/utils/reactive-layout/index.d.cts

@@ -0,0 +1,492 @@
+import { M as MeasurementAdapter, P as PreparedSegment, d as LineBreaksResult, C as CharPosition, L as LayoutCursor, I as Interval } from '../../reactive-layout-fswlBUvX.cjs';
+export { a as LayoutLine, b as LayoutNextLineContext, c as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from '../../reactive-layout-fswlBUvX.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).
+ *
+ * All adapters implement {@link MeasurementAdapter} from `reactive-layout.ts`.
+ * Sync constructors, sync `measureSegment()` — no async, no polling.
+ */
+
+type CliMeasureAdapterOptions = {
+    /** Pixel width per terminal cell (default: 8). */
+    cellPx?: number;
+};
+/**
+ * Monospace terminal measurement adapter.
+ *
+ * Width = cell count × `cellPx`. CJK / fullwidth characters count as 2 cells.
+ * No external dependencies. Works in any JS environment.
+ */
+declare class CliMeasureAdapter implements MeasurementAdapter {
+    private readonly cellPx;
+    constructor(opts?: CliMeasureAdapterOptions);
+    measureSegment(text: string, _font: string): {
+        width: number;
+    };
+}
+type PrecomputedAdapterOptions = {
+    /**
+     * Pre-computed metrics: `{ font: { segment: widthPx } }`.
+     * Outer key is the CSS font string; inner key is the text segment.
+     */
+    metrics: Record<string, Record<string, number>>;
+    /**
+     * Fallback when a segment is not found in the metrics map.
+     * - `"per-char"`: sum individual character widths from the same font map (default)
+     * - `"error"`: throw an error for unknown segments
+     */
+    fallback?: "per-char" | "error";
+};
+/**
+ * Pre-computed measurement adapter for SSR / snapshot replay.
+ *
+ * Reads from a static metrics object — zero measurement at runtime.
+ * Ideal for server-side rendering or replaying snapshotted layouts.
+ */
+declare class PrecomputedAdapter implements MeasurementAdapter {
+    private readonly metrics;
+    private readonly fallback;
+    constructor(opts: PrecomputedAdapterOptions);
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+}
+type CanvasMeasureAdapterOptions = {
+    /** Emoji width correction factor (default: 1, no correction). */
+    emojiCorrection?: number;
+};
+/**
+ * Browser measurement adapter using `OffscreenCanvas.measureText()`.
+ *
+ * Lazily creates an OffscreenCanvas and 2D context on first call.
+ * Requires a browser environment with OffscreenCanvas support.
+ */
+declare class CanvasMeasureAdapter implements MeasurementAdapter {
+    private ctx;
+    private currentFont;
+    private readonly emojiCorrection;
+    constructor(opts?: CanvasMeasureAdapterOptions);
+    private getContext;
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    clearCache(): void;
+}
+/**
+ * Canvas API subset expected from `@napi-rs/canvas` or `skia-canvas`.
+ * Passed via dependency injection — no dynamic import, no polling.
+ */
+type CanvasModule = {
+    createCanvas(width: number, height: number): {
+        getContext(type: "2d"): {
+            font: string;
+            measureText(text: string): {
+                width: number;
+            };
+        };
+    };
+};
+/**
+ * Node.js measurement adapter using an injected canvas module.
+ *
+ * ```ts
+ * import * as canvas from "@napi-rs/canvas";
+ * const adapter = new NodeCanvasMeasureAdapter(canvas);
+ * ```
+ *
+ * Works with `@napi-rs/canvas`, `skia-canvas`, or any module exposing
+ * `createCanvas(w, h).getContext("2d").measureText(text)`.
+ */
+declare class NodeCanvasMeasureAdapter implements MeasurementAdapter {
+    private ctx;
+    private currentFont;
+    private readonly canvasModule;
+    constructor(canvasModule: CanvasModule);
+    private getContext;
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    clearCache(): void;
+}
+/**
+ * SVG measurement adapter — extracts dimensions from `viewBox` attribute
+ * or explicit `width`/`height` attributes in the SVG string.
+ *
+ * Pure arithmetic: parses the SVG string for dimension attributes.
+ * No DOM required. Works in any JS environment.
+ *
+ * Browser users who need `getBBox()` should pre-measure and pass explicit
+ * `viewBox` on the content block instead.
+ */
+declare class SvgBoundsAdapter {
+    measureSvg(content: string): {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Image measurement adapter — returns pre-registered dimensions by src key.
+ *
+ * Sync-only: dimensions must be provided upfront via the `sizes` map.
+ * No I/O, no polling, no async. For browser use, pre-measure via
+ * `Image.onload` and pass natural dimensions on the content block directly,
+ * or register them here.
+ *
+ * ```ts
+ * const adapter = new ImageSizeAdapter({
+ *   "hero.png": { width: 1200, height: 630 },
+ *   "logo.svg": { width: 120, height: 40 },
+ * });
+ * ```
+ */
+declare class ImageSizeAdapter {
+    private readonly sizes;
+    constructor(sizes: Record<string, {
+        width: number;
+        height: number;
+    }>);
+    measureImage(src: string): {
+        width: number;
+        height: number;
+    };
+}
+
+/**
+ * Reactive multi-content block layout engine (roadmap §7.1 — mixed content).
+ *
+ * Extends the text-only `reactiveLayout` with support for image and SVG blocks.
+ * Pure-arithmetic layout over measured child sizes — no DOM, no async.
+ *
+ * Graph shape:
+ * ```
+ * Graph("reactive-block-layout")
+ * ├── node([], { initial: "blocks" })              — ContentBlock[] input
+ * ├── node([], { initial: "max-width" })           — container constraint
+ * ├── node([], { initial: "gap" })                 — vertical gap between blocks (px)
+ * ├── derived("measured-blocks")   — blocks → MeasuredBlock[] (per-type measurement)
+ * ├── derived("block-flow")        — measured-blocks + max-width + gap → PositionedBlock[]
+ * ├── derived("total-height")      — block-flow → total height
+ * └── meta: { block-count, layout-time-ns }
+ * ```
+ */
+
+/** Pluggable measurement backend for SVG content. */
+interface SvgMeasurer {
+    measureSvg(content: string): {
+        width: number;
+        height: number;
+    };
+}
+/** Pluggable measurement backend for image content. */
+interface ImageMeasurer {
+    measureImage(src: string): {
+        width: number;
+        height: number;
+    };
+}
+/** Adapters map for `reactiveBlockLayout`. */
+type BlockAdapters = {
+    /** Text measurement adapter (required — delegates to `reactiveLayout` internals). */
+    text: MeasurementAdapter;
+    /** SVG measurement (optional — required only if SVG blocks are present). */
+    svg?: SvgMeasurer;
+    /** Image measurement (optional — required only if image blocks without explicit dimensions are present). */
+    image?: ImageMeasurer;
+};
+/** A content block — text, image, or SVG. */
+type ContentBlock = {
+    type: "text";
+    text: string;
+    font?: string;
+    lineHeight?: number;
+} | {
+    type: "image";
+    src: string;
+    /** Natural width in px. Required if no ImageMeasurer adapter is provided. */
+    naturalWidth?: number;
+    /** Natural height in px. Required if no ImageMeasurer adapter is provided. */
+    naturalHeight?: number;
+} | {
+    type: "svg";
+    content: string;
+    /** Explicit viewBox dimensions. Required if no SvgMeasurer adapter is provided. */
+    viewBox?: {
+        width: number;
+        height: number;
+    };
+};
+/**
+ * A block after measurement — knows its natural dimensions.
+ *
+ * **Equality note:** The reactive `measured-blocks` node uses dimension-only equality
+ * (`type`, `width`, `height`, `index`). Inner text layout data (`textSegments`,
+ * `textLineBreaks`, `textCharPositions`) is NOT compared for change detection.
+ * If you need text-level reactivity, use `reactiveLayout()` directly per text block.
+ */
+type MeasuredBlock = {
+    index: number;
+    type: "text" | "image" | "svg";
+    width: number;
+    height: number;
+    /** For text blocks: the inner layout results. */
+    textSegments?: PreparedSegment[];
+    textLineBreaks?: LineBreaksResult;
+    textCharPositions?: CharPosition[];
+};
+/** A block after flow — positioned in the container. */
+type PositionedBlock = MeasuredBlock & {
+    x: number;
+    y: number;
+};
+/** Options for `reactiveBlockLayout`. */
+type ReactiveBlockLayoutOptions = {
+    adapters: BlockAdapters;
+    name?: string;
+    blocks?: ContentBlock[];
+    /** Container max width in px (clamped to ≥ 0 on init and `setMaxWidth`). */
+    maxWidth?: number;
+    /** Vertical gap between blocks in px (default 0). */
+    gap?: number;
+    /** Default font for text blocks that don't specify one. */
+    defaultFont?: string;
+    /** Default line height for text blocks that don't specify one. */
+    defaultLineHeight?: number;
+};
+/** Result bundle from `reactiveBlockLayout`. */
+type ReactiveBlockLayoutBundle = {
+    graph: Graph;
+    setBlocks: (blocks: ContentBlock[]) => void;
+    setMaxWidth: (maxWidth: number) => void;
+    setGap: (gap: number) => void;
+    measuredBlocks: Node<MeasuredBlock[]>;
+    blockFlow: Node<PositionedBlock[]>;
+    totalHeight: Node<number>;
+};
+/**
+ * Measure a single content block, returning natural (unconstrained) dimensions.
+ * Text blocks use the text layout pipeline; image/SVG use adapters or explicit dims.
+ */
+declare function measureBlock(block: ContentBlock, maxWidth: number, adapters: BlockAdapters, measureCache: Map<string, Map<string, number>>, defaultFont: string, defaultLineHeight: number, index: number): MeasuredBlock;
+/**
+ * Measure all blocks in a content array.
+ */
+declare function measureBlocks(blocks: ContentBlock[], maxWidth: number, adapters: BlockAdapters, measureCache: Map<string, Map<string, number>>, defaultFont: string, defaultLineHeight: number): MeasuredBlock[];
+/**
+ * Vertical stacking flow: blocks are placed top-to-bottom, left-aligned,
+ * separated by `gap` pixels. Pure arithmetic over measured sizes.
+ */
+declare function computeBlockFlow(measured: MeasuredBlock[], gap: number): PositionedBlock[];
+/**
+ * Compute total height from positioned blocks.
+ */
+declare function computeTotalHeight(flow: PositionedBlock[]): number;
+/**
+ * Create a reactive block layout graph for mixed content (text + image + SVG).
+ *
+ * ```
+ * Graph("reactive-block-layout")
+ * ├── node([], { initial: "blocks" })              — ContentBlock[] input
+ * ├── node([], { initial: "max-width" })           — container constraint
+ * ├── node([], { initial: "gap" })                 — vertical gap (px)
+ * ├── derived("measured-blocks")   — blocks + max-width → MeasuredBlock[]
+ * ├── derived("block-flow")        — measured-blocks + gap → PositionedBlock[]
+ * ├── derived("total-height")      — block-flow → number
+ * └── meta: { block-count, layout-time-ns }
+ * ```
+ */
+declare function reactiveBlockLayout(opts: ReactiveBlockLayoutOptions): ReactiveBlockLayoutBundle;
+
+/**
+ * Reactive flow layout — multi-column text flowing around shape obstacles
+ * (roadmap §7.1, extends `reactiveLayout`).
+ *
+ * Unlike `reactiveLayout` (single-column, one `maxWidth`) and
+ * `reactiveBlockLayout` (vertical stack of heterogeneous blocks), this engine
+ * lays out a single stream of text across **N columns** while wrapping around
+ * arbitrary **shape obstacles** (circles, rectangles). Each line's available
+ * width can differ from every other line's, enabling magazine-style editorial
+ * layouts — and the cursor carries seamlessly from column to column so text
+ * never duplicates or gaps at boundaries.
+ *
+ * ```
+ * Graph("reactive-flow-layout")
+ * ├── node([], { initial: "text" })
+ * ├── node([], { initial: "font" })
+ * ├── node([], { initial: "line-height" })
+ * ├── node([], { initial: "container" })           — { width, height, paddingX, paddingY }
+ * ├── node([], { initial: "columns" })             — { count, gap }
+ * ├── node([], { initial: "obstacles" })           — Obstacle[] (moves reactively — rAF-friendly)
+ * ├── derived("segments")          — text + font → PreparedSegment[]  (from reactiveLayout)
+ * ├── derived("flow-lines")        — segments + container + columns + obstacles + line-height
+ * │                                  → PositionedLine[]
+ * └── meta: { line-count, layout-time-ns, overflow-segments }
+ * ```
+ *
+ * Obstacle positions change every frame; `flow-lines` re-runs per change, but
+ * `segments` stays cached (text hasn't changed). Callers drive obstacles via a
+ * reactive source like `fromRaf()` piped into a state node.
+ */
+
+/** A circle obstacle. Center `(cx, cy)`, radius `r`; text keeps `padding` distance. */
+type CircleObstacle = {
+    kind: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+    /** Horizontal padding between obstacle and wrapped text (default 0). */
+    hPad?: number;
+    /** Vertical padding — band overlap tolerance (default 0). */
+    vPad?: number;
+};
+/** A rectangle obstacle. Top-left `(x, y)`, size `(w, h)`. */
+type RectObstacle = {
+    kind: "rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    hPad?: number;
+    vPad?: number;
+};
+/** Union of built-in obstacle shapes. */
+type Obstacle = CircleObstacle | RectObstacle;
+/**
+ * Compute the horizontal interval occluded by a circle at vertical band
+ * `[bandTop, bandBottom]`, or `null` if no occlusion.
+ *
+ * Exported so consumers that render obstacle outlines in sync with the flow
+ * can reuse the same geometry the flow engine uses — no divergence.
+ */
+declare function circleIntervalForBand(o: CircleObstacle, bandTop: number, bandBottom: number): Interval | null;
+/** Same as `circleIntervalForBand` for rectangles. */
+declare function rectIntervalForBand(o: RectObstacle, bandTop: number, bandBottom: number): Interval | null;
+type FlowContainer = {
+    width: number;
+    height: number;
+    paddingX?: number;
+    paddingY?: number;
+};
+type FlowColumns = {
+    count: number;
+    gap: number;
+};
+/** A single positioned line after flow layout. */
+type PositionedLine = {
+    x: number;
+    y: number;
+    /** Natural measured width of the text content. */
+    width: number;
+    /** Width of the slot this line was placed in — use this as the DOM element's
+     *  `width` when applying `text-align: justify` so the line stretches to the
+     *  obstacle edge on both sides. */
+    slotWidth: number;
+    text: string;
+    /** Which column index this line belongs to (0-based). */
+    columnIndex: number;
+    /** `true` iff the slot's right edge was carved short by an obstacle (the
+     *  slot sits to the LEFT of an obstacle). Renderers can right-align text
+     *  in these slots so single-word lines still hug the obstacle — CSS
+     *  `text-align: justify` can't stretch single-word lines, which otherwise
+     *  produces a visible asymmetry vs. the slot on the other side of the
+     *  obstacle (which is flush by default). */
+    flushToRight: boolean;
+};
+/** Options for `reactiveFlowLayout`. */
+type ReactiveFlowLayoutOptions = {
+    adapter: MeasurementAdapter;
+    name?: string;
+    text?: string;
+    font?: string;
+    lineHeight?: number;
+    container?: FlowContainer;
+    columns?: FlowColumns;
+    obstacles?: Obstacle[];
+    /** Minimum slot width (px) below which a slot is discarded rather than squeezed. Default `20`. */
+    minSlotWidth?: number;
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). When unset (or explicitly set to `null`), tracks
+     * the current `lineHeight` reactively — one line-height of visible
+     * paragraph gap, matching dense editorial layouts. Set to `0` for
+     * paragraph-preserving layout that reclaims the break line; set larger
+     * (e.g. `2 * lineHeight`) for looser manuscript settings. Reactive —
+     * update via `setParagraphSpacing(n)` or restore to track-lineHeight
+     * mode via `setParagraphSpacing(null)`.
+     */
+    paragraphSpacing?: number | null;
+};
+/** Result bundle from `reactiveFlowLayout`. */
+type ReactiveFlowLayoutBundle = {
+    graph: Graph;
+    setText: (text: string) => void;
+    setFont: (font: string) => void;
+    setLineHeight: (lh: number) => void;
+    setContainer: (c: FlowContainer) => void;
+    setColumns: (c: FlowColumns) => void;
+    setObstacles: (o: Obstacle[]) => void;
+    setParagraphSpacing: (ps: number | null) => void;
+    segments: Node<PreparedSegment[]>;
+    flowLines: Node<PositionedLine[]>;
+};
+/** Result of `computeFlowLines`. */
+type FlowLinesResult = {
+    /** Positioned lines in render order (columns inner-ordered top-to-bottom). */
+    lines: PositionedLine[];
+    /** Cursor position after the last line was placed. If
+     *  `cursor.segmentIndex < segments.length`, the layout **truncated** — the
+     *  container couldn't fit all text. */
+    cursor: LayoutCursor;
+};
+/** Optional tuning knobs for {@link computeFlowLines}. */
+type ComputeFlowLinesOptions = {
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). Defaults to `lineHeight` — one line-height of
+     * visible paragraph gap, which matches dense editorial layouts. Set to
+     * `0` for paragraph-preserving layout that reclaims the break line;
+     * set larger (e.g. `2 * lineHeight`) for looser manuscript settings.
+     */
+    paragraphSpacing?: number;
+};
+/**
+ * Lay out `segments` across N columns, wrapping each line around `obstacles`.
+ * Pure function — no reactive wiring. Exported for testing and for consumers
+ * who want to run flow layout outside a Graph.
+ *
+ * `carveTextLineSlots` guarantees left-to-right-ordered, non-overlapping slots,
+ * so this function does not sort them.
+ */
+declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number, opts?: ComputeFlowLinesOptions): FlowLinesResult;
+/**
+ * Create a reactive flow-layout graph: N columns of text wrapping around
+ * shape obstacles. Re-runs only the dependent derived nodes on any input
+ * change. Obstacle movement (e.g. rAF-driven) invalidates `flow-lines` only;
+ * `segments` stays cached as long as `text`/`font` don't change.
+ *
+ * @example
+ * ```ts
+ * import { fromRaf, reactiveFlowLayout } from "@graphrefly/graphrefly-ts";
+ *
+ * const flow = reactiveFlowLayout({
+ *   adapter: new CanvasMeasureAdapter(),
+ *   text: longEssay,
+ *   font: "18px serif",
+ *   lineHeight: 26,
+ *   container: { width: 900, height: 600, paddingX: 40, paddingY: 40 },
+ *   columns: { count: 2, gap: 32 },
+ *   obstacles: [{ kind: "circle", cx: 450, cy: 300, r: 80 }],
+ * });
+ *
+ * // Animate the obstacle via rAF:
+ * fromRaf().subscribe(([[, t]]) => {
+ *   const x = 450 + 120 * Math.sin((t as number) * 0.001);
+ *   flow.setObstacles([{ kind: "circle", cx: x, cy: 300, r: 80 }]);
+ * });
+ * ```
+ */
+declare function reactiveFlowLayout(opts: ReactiveFlowLayoutOptions): ReactiveFlowLayoutBundle;
+
+export { type BlockAdapters, CanvasMeasureAdapter, type CanvasMeasureAdapterOptions, type CanvasModule, CharPosition, type CircleObstacle, CliMeasureAdapter, type CliMeasureAdapterOptions, type ComputeFlowLinesOptions, type ContentBlock, type FlowColumns, type FlowContainer, type FlowLinesResult, type ImageMeasurer, ImageSizeAdapter, Interval, LayoutCursor, LineBreaksResult, type MeasuredBlock, MeasurementAdapter, NodeCanvasMeasureAdapter, type Obstacle, type PositionedBlock, type PositionedLine, PrecomputedAdapter, type PrecomputedAdapterOptions, PreparedSegment, type ReactiveBlockLayoutBundle, type ReactiveBlockLayoutOptions, type ReactiveFlowLayoutBundle, type ReactiveFlowLayoutOptions, type RectObstacle, SvgBoundsAdapter, type SvgMeasurer, circleIntervalForBand, computeBlockFlow, computeFlowLines, computeTotalHeight, measureBlock, measureBlocks, reactiveBlockLayout, reactiveFlowLayout, rectIntervalForBand };