@graphrefly/graphrefly 0.23.0 → 0.25.0

package/dist/{index-jEtF4N7L.d.ts → index-OXImXMq6.d.ts}

@@ -1,5 +1,5 @@
-import { N as Node } from './node-C7PD3sn9.js';
-import { G as Graph } from './graph-CEO2FkLY.js';
+import { N as Node } from './node-B-f-Lu-k.js';
+import { G as Graph } from './graph-B6NFqv3z.js';
 
 /** Pluggable measurement backend. */
 interface MeasurementAdapter {
@@ -46,6 +46,35 @@ type LineBreaksResult = {
     lines: LayoutLine[];
     lineCount: number;
 };
+/**
+ * A position within `PreparedSegment[]` — segment + grapheme offset.
+ * `graphemeIndex: 0` at segment boundaries.
+ *
+ * Used by {@link layoutNextLine} for cursor-based line walking; needed when
+ * lines have varying widths (multi-column flow, text wrapping around obstacles).
+ */
+type LayoutCursor = {
+    segmentIndex: number;
+    graphemeIndex: number;
+};
+/** A horizontal span `[left, right]` in pixels — used by flow-layout slot carving. */
+type Interval = {
+    left: number;
+    right: number;
+};
+/** Result of a single `layoutNextLine` call. */
+type LayoutNextLineResult = {
+    text: string;
+    width: number;
+    start: LayoutCursor;
+    end: LayoutCursor;
+};
+/** Optional context for `layoutNextLine` — enables soft-hyphen visible-hyphen rendering. */
+type LayoutNextLineContext = {
+    adapter?: MeasurementAdapter;
+    font?: string;
+    cache?: Map<string, Map<string, number>>;
+};
 /** Result of the reactive layout graph's describe-accessible state. */
 type ReactiveLayoutBundle = {
     graph: Graph;
@@ -82,6 +111,42 @@ declare function analyzeAndMeasure(text: string, font: string, adapter: Measurem
  * - Hard breaks (forced newline)
  */
 declare function computeLineBreaks(segments: PreparedSegment[], maxWidth: number, adapter: MeasurementAdapter, font: string, cache: Map<string, Map<string, number>>): LineBreaksResult;
+/**
+ * Lay out the next single line starting from `cursor`, fitting into `slotWidth`.
+ *
+ * Unlike `computeLineBreaks`, which consumes whole text with one `maxWidth`,
+ * this is the cursor-based primitive needed when successive lines have different
+ * widths (multi-column flow, text wrapping around shape obstacles, mixed
+ * column+pullquote layouts).
+ *
+ * Returns `null` when the cursor is past all segments (text exhausted).
+ * At a hard-break with no preceding content, returns an empty line and advances
+ * the cursor past the break so the caller can continue.
+ *
+ * ```ts
+ * let cursor: LayoutCursor = { segmentIndex: 0, graphemeIndex: 0 };
+ * while (true) {
+ *   const line = layoutNextLine(segments, cursor, availableWidth);
+ *   if (line === null) break;
+ *   render(line);
+ *   cursor = line.end;
+ * }
+ * ```
+ */
+declare function layoutNextLine(segments: PreparedSegment[], cursor: LayoutCursor, slotWidth: number, ctx?: LayoutNextLineContext): LayoutNextLineResult | null;
+/**
+ * Subtract blocked horizontal intervals from a base interval, producing
+ * remaining ordered, non-overlapping slots wide enough to fit text.
+ *
+ * Pure geometry — no text dependency. Used by flow-layout to turn obstacle
+ * intersections into per-line layout slots.
+ *
+ * ```ts
+ * carveTextLineSlots({left: 0, right: 600}, [{left: 200, right: 280}])
+ * // → [{left: 0, right: 200}, {left: 280, right: 600}]
+ * ```
+ */
+declare function carveTextLineSlots(base: Interval, blocked: Interval[], minSlotWidth?: number): Interval[];
 /** Compute per-character x,y positions from line breaks and segments. */
 declare function computeCharPositions(lineBreaks: LineBreaksResult, segments: PreparedSegment[], lineHeight: number): CharPosition[];
 type ReactiveLayoutOptions = {
@@ -392,6 +457,142 @@ declare function computeTotalHeight(flow: PositionedBlock[]): number;
  */
 declare function reactiveBlockLayout(opts: ReactiveBlockLayoutOptions): ReactiveBlockLayoutBundle;
 
+/** 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;
+};
+/** 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;
+    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;
+};
+/**
+ * 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): 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;
+
 /**
  * Reactive layout pattern — standalone subpath export.
  *
@@ -406,44 +607,63 @@ declare const index_CanvasMeasureAdapter: typeof CanvasMeasureAdapter;
 type index_CanvasMeasureAdapterOptions = CanvasMeasureAdapterOptions;
 type index_CanvasModule = CanvasModule;
 type index_CharPosition = CharPosition;
+type index_CircleObstacle = CircleObstacle;
 type index_CliMeasureAdapter = CliMeasureAdapter;
 declare const index_CliMeasureAdapter: typeof CliMeasureAdapter;
 type index_CliMeasureAdapterOptions = CliMeasureAdapterOptions;
 type index_ContentBlock = ContentBlock;
+type index_FlowColumns = FlowColumns;
+type index_FlowContainer = FlowContainer;
+type index_FlowLinesResult = FlowLinesResult;
 type index_ImageMeasurer = ImageMeasurer;
 type index_ImageSizeAdapter = ImageSizeAdapter;
 declare const index_ImageSizeAdapter: typeof ImageSizeAdapter;
+type index_Interval = Interval;
+type index_LayoutCursor = LayoutCursor;
 type index_LayoutLine = LayoutLine;
+type index_LayoutNextLineContext = LayoutNextLineContext;
+type index_LayoutNextLineResult = LayoutNextLineResult;
 type index_LineBreaksResult = LineBreaksResult;
 type index_MeasuredBlock = MeasuredBlock;
 type index_MeasurementAdapter = MeasurementAdapter;
 type index_NodeCanvasMeasureAdapter = NodeCanvasMeasureAdapter;
 declare const index_NodeCanvasMeasureAdapter: typeof NodeCanvasMeasureAdapter;
+type index_Obstacle = Obstacle;
 type index_PositionedBlock = PositionedBlock;
+type index_PositionedLine = PositionedLine;
 type index_PrecomputedAdapter = PrecomputedAdapter;
 declare const index_PrecomputedAdapter: typeof PrecomputedAdapter;
 type index_PrecomputedAdapterOptions = PrecomputedAdapterOptions;
 type index_PreparedSegment = PreparedSegment;
 type index_ReactiveBlockLayoutBundle = ReactiveBlockLayoutBundle;
 type index_ReactiveBlockLayoutOptions = ReactiveBlockLayoutOptions;
+type index_ReactiveFlowLayoutBundle = ReactiveFlowLayoutBundle;
+type index_ReactiveFlowLayoutOptions = ReactiveFlowLayoutOptions;
 type index_ReactiveLayoutBundle = ReactiveLayoutBundle;
 type index_ReactiveLayoutOptions = ReactiveLayoutOptions;
+type index_RectObstacle = RectObstacle;
 type index_SegmentBreakKind = SegmentBreakKind;
 type index_SegmentMeasureStats = SegmentMeasureStats;
 type index_SvgBoundsAdapter = SvgBoundsAdapter;
 declare const index_SvgBoundsAdapter: typeof SvgBoundsAdapter;
 type index_SvgMeasurer = SvgMeasurer;
 declare const index_analyzeAndMeasure: typeof analyzeAndMeasure;
+declare const index_carveTextLineSlots: typeof carveTextLineSlots;
+declare const index_circleIntervalForBand: typeof circleIntervalForBand;
 declare const index_computeBlockFlow: typeof computeBlockFlow;
 declare const index_computeCharPositions: typeof computeCharPositions;
+declare const index_computeFlowLines: typeof computeFlowLines;
 declare const index_computeLineBreaks: typeof computeLineBreaks;
 declare const index_computeTotalHeight: typeof computeTotalHeight;
+declare const index_layoutNextLine: typeof layoutNextLine;
 declare const index_measureBlock: typeof measureBlock;
 declare const index_measureBlocks: typeof measureBlocks;
 declare const index_reactiveBlockLayout: typeof reactiveBlockLayout;
+declare const index_reactiveFlowLayout: typeof reactiveFlowLayout;
 declare const index_reactiveLayout: typeof reactiveLayout;
+declare const index_rectIntervalForBand: typeof rectIntervalForBand;
 declare namespace index {
-  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, type index_CharPosition as CharPosition, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ContentBlock as ContentBlock, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, type index_LayoutLine as LayoutLine, type index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, type index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_PositionedBlock as PositionedBlock, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, type index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveLayoutBundle as ReactiveLayoutBundle, type index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_SegmentBreakKind as SegmentBreakKind, type index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveLayout as reactiveLayout };
+  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, type index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, type index_Interval as Interval, type index_LayoutCursor as LayoutCursor, type index_LayoutLine as LayoutLine, type index_LayoutNextLineContext as LayoutNextLineContext, type index_LayoutNextLineResult as LayoutNextLineResult, type index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, type index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, type index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, type index_ReactiveLayoutBundle as ReactiveLayoutBundle, type index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, type index_SegmentBreakKind as SegmentBreakKind, type index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
 }
 
-export { reactiveBlockLayout as A, type BlockAdapters as B, CanvasMeasureAdapter as C, reactiveLayout as D, type ImageMeasurer as I, type LayoutLine as L, type MeasurementAdapter as M, NodeCanvasMeasureAdapter as N, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, type SegmentBreakKind as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CharPosition as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ContentBlock as f, ImageSizeAdapter as g, type LineBreaksResult as h, index as i, type MeasuredBlock as j, PrecomputedAdapter as k, type PrecomputedAdapterOptions as l, type PreparedSegment as m, type ReactiveBlockLayoutOptions as n, type ReactiveLayoutBundle as o, type ReactiveLayoutOptions as p, type SegmentMeasureStats as q, SvgBoundsAdapter as r, type SvgMeasurer as s, analyzeAndMeasure as t, computeBlockFlow as u, computeCharPositions as v, computeLineBreaks as w, computeTotalHeight as x, measureBlock as y, measureBlocks as z };
+export { reactiveFlowLayout as $, type RectObstacle as A, type BlockAdapters as B, CanvasMeasureAdapter as C, type SegmentMeasureStats as D, SvgBoundsAdapter as E, type FlowColumns as F, type SvgMeasurer as G, analyzeAndMeasure as H, type ImageMeasurer as I, carveTextLineSlots as J, circleIntervalForBand as K, type LayoutCursor as L, type MeasurementAdapter as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, computeBlockFlow as Q, type ReactiveBlockLayoutBundle as R, type SegmentBreakKind as S, computeCharPositions as T, computeFlowLines as U, computeLineBreaks as V, computeTotalHeight as W, layoutNextLine as X, measureBlock as Y, measureBlocks as Z, reactiveBlockLayout as _, type CanvasMeasureAdapterOptions as a, reactiveLayout as a0, rectIntervalForBand as a1, type CanvasModule as b, type CharPosition as c, type CircleObstacle as d, CliMeasureAdapter as e, type CliMeasureAdapterOptions as f, type ContentBlock as g, type FlowContainer as h, index as i, type FlowLinesResult as j, ImageSizeAdapter as k, type Interval as l, type LayoutLine as m, type LayoutNextLineContext as n, type LayoutNextLineResult as o, type LineBreaksResult as p, type MeasuredBlock as q, type PositionedLine as r, PrecomputedAdapter as s, type PrecomputedAdapterOptions as t, type PreparedSegment as u, type ReactiveBlockLayoutOptions as v, type ReactiveFlowLayoutBundle as w, type ReactiveFlowLayoutOptions as x, type ReactiveLayoutBundle as y, type ReactiveLayoutOptions as z };