@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/rendering/coordinates.d.ts

@@ -0,0 +1,452 @@
+/**
+ * Coordinate System Types for Canvas Rendering
+ *
+ * These types define the coordinate spaces and dimension interfaces used
+ * throughout the renderer. Moved to contracts to enable decoupling of
+ * canvas and state subsystems.
+ *
+ * Coordinate Spaces:
+ * 1. CELL SPACE - Logical cell references { row: 0, col: 0 } = A1
+ * 2. DOCUMENT SPACE - Full document coordinates in pixels (no scroll, no zoom)
+ * 3. VIEWPORT SPACE - Canvas-absolute coordinates (accounts for scroll, zoom, includes headers)
+ * 4. LAYER SPACE - Layer-relative coordinates (accounts for scroll, zoom, NO headers - canvas translation handles headers)
+ * 5. CANVAS SPACE - Physical pixels on canvas (viewport * devicePixelRatio)
+ *
+ * @module @mog/spreadsheet-contracts/rendering/coordinates
+ */
+import type { CellRange } from '../core';
+import type { Point, Rect } from '../viewport';
+import type { HitTestResult } from './hit-test';
+import type { CellCoord } from './primitives';
+export type { CellCoord } from './primitives';
+/** Brand for document coordinate space (unzoomed, from sheet origin) */
+declare const DocumentBrand: unique symbol;
+/** Brand for viewport coordinate space (zoomed, from canvas origin, includes headers) */
+declare const ViewportBrand: unique symbol;
+/** Brand for layer-relative coordinate space (zoomed, from cell area origin, no headers) */
+declare const LayerBrand: unique symbol;
+/**
+ * Point in document coordinates.
+ * - Origin: Top-left of sheet content (cell A1)
+ * - Units: Unzoomed pixels
+ * - Scroll: Not affected by scroll position
+ * - Use: Storage, formulas, cell references, floating object positions
+ */
+export type DocumentPoint = Point & {
+    readonly [DocumentBrand]: true;
+};
+/**
+ * Point in viewport coordinates.
+ * - Origin: Top-left of canvas element
+ * - Units: Screen pixels (zoomed)
+ * - Headers: Includes row header width (50px) and column header height (24px)
+ * - Use: Mouse events, canvas dimensions, absolute positioning, input handling
+ */
+export type ViewportPoint = Point & {
+    readonly [ViewportBrand]: true;
+};
+/**
+ * Point in layer-relative coordinates.
+ * - Origin: Top-left of cell area (after headers)
+ * - Units: Screen pixels (zoomed)
+ * - Headers: Does NOT include header offsets (canvas ctx.translate() handles them)
+ * - Use: Render layers, HitMap paths (paths are registered in layer-relative space)
+ */
+export type LayerPoint = Point & {
+    readonly [LayerBrand]: true;
+};
+/**
+ * Rectangle in document coordinates.
+ * @see DocumentPoint for coordinate space details
+ */
+export type DocumentRect = Rect & {
+    readonly [DocumentBrand]: true;
+};
+/**
+ * Rectangle in viewport coordinates.
+ * @see ViewportPoint for coordinate space details
+ */
+export type ViewportRect = Rect & {
+    readonly [ViewportBrand]: true;
+};
+/**
+ * Rectangle in layer-relative coordinates.
+ * @see LayerPoint for coordinate space details
+ */
+export type LayerRect = Rect & {
+    readonly [LayerBrand]: true;
+};
+/**
+ * ScrollViewport bounds - defines the visible area and scroll position.
+ * Named ScrollViewport to distinguish from contracts Viewport which is
+ * a high-level rendering viewport with bounds, cellRange, scrollOffset, zoom.
+ */
+export interface ScrollViewport {
+    /** Pixels scrolled from top */
+    scrollTop: number;
+    /** Pixels scrolled from left */
+    scrollLeft: number;
+    /** Viewport width in CSS pixels */
+    width: number;
+    /** Viewport height in CSS pixels */
+    height: number;
+}
+/**
+ * Frozen pane configuration.
+ * Frozen rows/cols stay visible regardless of scroll position.
+ */
+export interface FrozenPanes {
+    /** Number of frozen rows (0 = none) */
+    rows: number;
+    /** Number of frozen cols (0 = none) */
+    cols: number;
+}
+/**
+ * Visible regions accounting for frozen panes.
+ * With frozen panes, the viewport is divided into up to 4 regions.
+ *
+ * Layout:
+ * +-------------+-------------------------+
+ * |frozenCorner | frozenRows              |
+ * | (fixed)     | (scrolls horizontally)  |
+ * +-------------+-------------------------+
+ * | frozenCols  | main                    |
+ * | (scrolls    | (scrolls both ways)     |
+ * |  vertically)|                         |
+ * +-------------+-------------------------+
+ */
+export interface VisibleRegions {
+    /** Frozen corner - always visible at top-left (null if no frozen panes) */
+    frozenCorner: CellRange | null;
+    /** Frozen rows - scrolls horizontally only (null if no frozen rows) */
+    frozenRows: CellRange | null;
+    /** Frozen columns - scrolls vertically only (null if no frozen cols) */
+    frozenCols: CellRange | null;
+    /** Main scrollable area - scrolls both horizontally and vertically */
+    main: CellRange;
+}
+/**
+ * Minimal interface for viewport position index lookups.
+ * The concrete implementation is ViewportPositionIndex in @mog/grid-renderer.
+ */
+export interface ViewportPositionIndexLike {
+    /** O(1) - pixel position of row's top edge */
+    getRowTop(row: number): number;
+    /** O(1) - pixel position of column's left edge */
+    getColLeft(col: number): number;
+    /** O(1) - row height */
+    getRowHeight(row: number): number;
+    /** O(1) - column width */
+    getColWidth(col: number): number;
+    /** Whether position data is available */
+    readonly hasData: boolean;
+    /** Total number of rows in the sheet */
+    readonly totalRows: number;
+    /** Total number of columns in the sheet */
+    readonly totalCols: number;
+    /** Binary search for the row at a given Y position */
+    findRowAtY(y: number): number | null;
+    /** Binary search for the column at a given X position */
+    findColAtX(x: number): number | null;
+    /** Whether the given row is hidden */
+    isRowHidden(row: number): boolean;
+    /** Whether the given column is hidden */
+    isColHidden(col: number): boolean;
+}
+/**
+ * Minimal merge region shape returned by merge index lookups.
+ */
+export interface MergeRegionLike {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+/**
+ * Minimal interface for viewport merge index lookups.
+ * The concrete implementation is ViewportMergeIndex in @mog/grid-renderer.
+ */
+export interface ViewportMergeIndexLike {
+    /** O(1) - returns the merge region containing (row, col), or null */
+    getMergedRegion(row: number, col: number): MergeRegionLike | null;
+}
+/**
+ * The CoordinateSystem is the single source of truth for all coordinate conversions.
+ *
+ * IMPORTANT: All components that need to convert between coordinate spaces
+ * MUST use this service. Do not implement coordinate math elsewhere.
+ *
+ * Type Safety: Methods use branded types (DocumentPoint, ViewportPoint, LayerPoint, etc.)
+ * to prevent coordinate space mismatches at compile time.
+ * @see plans/active/refactor/COORDINATE-SPACE-TYPE-SAFETY.md
+ */
+export interface CoordinateSystem {
+    /**
+     * Get the document-space rectangle for a cell.
+     * Accounts for: column widths, row heights, merged cells
+     * Does NOT account for: scroll, frozen panes, hidden rows/cols in position
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param cell - The cell coordinate
+     */
+    cellToDocument(sheetId: string, cell: CellCoord): DocumentRect;
+    /**
+     * Get the cell at a document-space point.
+     * Returns null if point is out of bounds.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param point - The document-space point
+     */
+    documentToCell(sheetId: string, point: DocumentPoint): CellCoord | null;
+    /**
+     * Get document-space bounding rectangle for a range.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param range - The cell range
+     */
+    rangeToDocument(sheetId: string, range: CellRange): DocumentRect;
+    /**
+     * Convert document rectangle to viewport coordinates (includes header offsets).
+     * Accounts for: scroll offset, frozen panes, zoom, header offsets
+     * Returns null if the rect is not visible in the viewport.
+     *
+     * Use this for: Input handling (mouse events to document coords)
+     * Do NOT use for: Render layers (they should use documentToLayerViewport)
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param rect - Rectangle in document coordinates
+     */
+    documentToViewport(sheetId: string, rect: DocumentRect): ViewportRect | null;
+    /**
+     * Convert document rectangle to layer-relative viewport coordinates.
+     *
+     * Unlike documentToViewport() which includes header offsets for input handling,
+     * this method returns coordinates suitable for render layers where the canvas
+     * translation (ctx.translate(vp.bounds.x, vp.bounds.y)) already accounts for headers.
+     *
+     * Coordinate spaces:
+     * - documentToViewport(): Returns canvas-absolute coords (for mouse events)
+     * - documentToLayerViewport(): Returns layer-relative coords (for rendering)
+     *
+     * Use this for: Render layers (overlay, selection, etc.)
+     * Use documentToViewport() for: Input handling (mouse events)
+     *
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param rect - Rectangle in document coordinates
+     * @returns Rectangle in layer-relative viewport coordinates, or null if not visible
+     */
+    documentToLayerViewport(sheetId: string, rect: DocumentRect): LayerRect | null;
+    /**
+     * Convert viewport point to document coordinates.
+     * Used for hit testing: viewport click -> document point -> cell
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param point - Point in viewport coordinates
+     */
+    viewportToDocument(sheetId: string, point: ViewportPoint): DocumentPoint;
+    /**
+     * Convert viewport point to layer-relative coordinates.
+     * Subtracts header offsets (ROW_HEADER_WIDTH, COL_HEADER_HEIGHT).
+     * Use for: Converting mouse events to layer space for HitMap queries.
+     */
+    viewportToLayer(point: ViewportPoint): LayerPoint;
+    /**
+     * Convert layer-relative point to viewport coordinates.
+     * Adds header offsets (ROW_HEADER_WIDTH, COL_HEADER_HEIGHT).
+     */
+    layerToViewport(point: LayerPoint): ViewportPoint;
+    /**
+     * Get the viewport-space rectangle for a cell.
+     * Returns null if cell is not currently visible.
+     * This is the most common operation for rendering.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param cell - The cell coordinate
+     */
+    cellToViewport(sheetId: string, cell: CellCoord): ViewportRect | null;
+    /**
+     * Get the cell at a viewport-space point (e.g., mouse click).
+     * This is the most common operation for hit testing.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param point - Point in viewport coordinates (e.g., mouse click position)
+     */
+    viewportToCell(sheetId: string, point: ViewportPoint): CellCoord | null;
+    /**
+     * Get viewport rectangles for a range.
+     * May return multiple rects if range spans frozen/non-frozen boundary.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param range - The cell range
+     */
+    rangeToViewport(sheetId: string, range: CellRange): ViewportRect[];
+    /**
+     * Get the click position relative to a cell's top-left corner.
+     * Correctly handles frozen panes, zoom, and header offsets.
+     *
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param point - Click position in viewport coordinates
+     * @param cell - The cell to get relative position within
+     * @returns Position within cell and cell dimensions, or null if cell not visible
+     *
+     * @note ALWAYS use this method instead of manually calculating
+     * `cellLeft - viewport.scrollLeft`. The manual calculation doesn't
+     * account for frozen panes, zoom, or header offsets.
+     */
+    getClickPositionInCell(sheetId: string, point: ViewportPoint, cell: CellCoord): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Get the range of cells currently visible in the viewport.
+     * Critical for virtualized rendering - only render these cells.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     */
+    getVisibleRange(sheetId: string): CellRange;
+    /**
+     * Get visible range split by frozen panes.
+     * Returns up to 4 regions for frozen rows + frozen cols.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     */
+    getVisibleRegions(sheetId: string): VisibleRegions;
+    /**
+     * Check if a cell is currently visible in the viewport.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param cell - The cell coordinate to check
+     */
+    isCellVisible(sheetId: string, cell: CellCoord): boolean;
+    /**
+     * Check if a cell is in the frozen region.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param cell - The cell coordinate to check
+     */
+    isCellFrozen(sheetId: string, cell: CellCoord): boolean;
+    /**
+     * Classify a viewport point for hit testing.
+     * Returns what type of element is at the given viewport coordinates.
+     *
+     * Used by components to determine if a click is on:
+     * - A cell (main grid area)
+     * - Column header (for column selection)
+     * - Row header (for row selection)
+     * - Column/row resize handle
+     * - Fill handle
+     * - Frozen corner (select all)
+     * - Empty area
+     *
+     * Plan 09 Group 10.3: Touch Target Sizing
+     * When isTouch is true, hit areas are expanded to meet touch target guidelines.
+     *
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param point - Point in viewport coordinates (e.g., mouse click position)
+     * @param isTouch - Whether the input is from a touch device (larger hit areas)
+     */
+    classifyPoint(sheetId: string, point: ViewportPoint, isTouch?: boolean): HitTestResult;
+    /**
+     * Calculate scroll offset to bring a cell into view.
+     * Returns null if cell is already visible.
+     *
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     * @param cell - The cell to scroll to
+     * @param padding - Optional padding in pixels from viewport edge
+     */
+    getScrollToCell(sheetId: string, cell: CellCoord, padding?: number): {
+        top: number;
+        left: number;
+    } | null;
+    /**
+     * Get the maximum scroll bounds.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     */
+    getScrollBounds(sheetId: string): {
+        maxScrollTop: number;
+        maxScrollLeft: number;
+    };
+    /**
+     * Get viewport bounds for auto-scroll edge detection.
+     * Returns the scrollable region boundaries (excluding frozen panes and headers).
+     * Used by auto-scroll service during drag operations.
+     * @param sheetId - The sheet ID to use for coordinate calculations
+     */
+    getViewportBounds(sheetId: string): {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** Update viewport (scroll position, size) */
+    setViewport(viewport: ScrollViewport): void;
+    /** Get current viewport */
+    getViewport(): ScrollViewport;
+    /** Update frozen panes */
+    setFrozenPanes(panes: FrozenPanes): void;
+    /** Get current frozen panes */
+    getFrozenPanes(): FrozenPanes;
+    /**
+     * Get the current sheet ID being rendered.
+     * Returns null if no sheet is active.
+     *
+     * Used by callers that need the active sheet ID but don't have it
+     * available through other means (e.g., scroll coordination helpers).
+     */
+    getCurrentSheetId(): string | null;
+    /**
+     * Get the underlying position index (alias for getViewportPositionIndex).
+     * Convenience method used by scroll coordination and object coordination
+     * for snap-to-cell and pixel-to-cell conversion.
+     */
+    getPositionIndex(): ViewportPositionIndexLike | null;
+    /**
+     * Set the viewport position index for O(1) position lookups.
+     *
+     * @param index - The ViewportPositionIndex instance, or null to clear
+     */
+    setViewportPositionIndex(index: ViewportPositionIndexLike | null): void;
+    /**
+     * Get the viewport position index.
+     * Returns null if no position index has been set.
+     */
+    getViewportPositionIndex(): ViewportPositionIndexLike | null;
+    /** Update zoom level (1.0 = 100%) */
+    setZoom(zoom: number): void;
+    /** Get current zoom level */
+    getZoom(): number;
+    /** Get device pixel ratio (for canvas scaling) */
+    getDevicePixelRatio(): number;
+    /**
+     * Set the viewport merge index for merge-aware coordinate lookups.
+     *
+     * @param index - The ViewportMergeIndex instance, or null to clear
+     */
+    setViewportMergeIndex(index: ViewportMergeIndexLike | null): void;
+    /**
+     * Get the viewport merge index.
+     * Returns null if no merge index has been set.
+     */
+    getViewportMergeIndex(): ViewportMergeIndexLike | null;
+    /**
+     * Set outline gutter dimensions based on grouping state.
+     * This shifts all content (headers + cells) right/down to make room.
+     *
+     * @param rowGutterWidth - Width of row outline gutter (0 if no row groups)
+     * @param colGutterHeight - Height of column outline gutter (0 if no col groups)
+     */
+    setOutlineGutter(rowGutterWidth: number, colGutterHeight: number): void;
+    /**
+     * Get current outline gutter dimensions.
+     * @returns Object with rowGutterWidth and colGutterHeight
+     */
+    getOutlineGutter(): {
+        rowGutterWidth: number;
+        colGutterHeight: number;
+    };
+    /**
+     * Set header visibility.
+     * When headers are hidden, their dimensions are treated as 0 for coordinate calculations.
+     *
+     * @param visibility - Header visibility configuration
+     */
+    setHeaderVisibility(visibility: import('./constants').HeaderVisibility): void;
+    /**
+     * Get current header visibility settings.
+     * Used by layers to determine header offsets for positioning.
+     *
+     * @returns Header visibility configuration
+     */
+    getHeaderVisibility(): import('./constants').HeaderVisibility;
+}
+//# sourceMappingURL=coordinates.d.ts.map

package/dist/rendering/coordinates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinates.d.ts","sourceRoot":"","sources":["../../src/rendering/coordinates.ts"],"names":[],"mappings":"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"}

package/dist/rendering/coordinator-interfaces.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Coordinator Interfaces
+ *
+ * Pure interfaces extracted from the coordinator type definitions that have
+ * no app-internal dependencies. These enable cross-zone references to
+ * coordinator capabilities without creating DAG violations.
+ *
+ * @module @mog/spreadsheet-contracts/rendering
+ */
+import type { CellFormat, SheetViewOptions } from '../core';
+import type { IFloatingObjectManager } from '../kernel/floating-object-manager';
+import type { Point } from '../viewport/viewport';
+import type { SplitViewportConfig } from '../viewport/viewport-config';
+import type { CellCoord, FrozenPanes, GridRenderer, RendererFactory } from './index';
+import type { ViewportReader } from '../api';
+/**
+ * Minimal interface for coordinator access in mutations and object coordination.
+ *
+ * This interface defines the subset of coordinator methods needed by:
+ * - Object mutations (moveObject, resizeObject, rotateObject, etc.)
+ * - Object coordination module (for ink mode checking)
+ *
+ * Both SheetCoordinator and GridCoordinator implement this interface,
+ * allowing them to be used interchangeably in these contexts.
+ *
+ * @see plans/active/refactor/unified-floating-object-operations.md
+ */
+export interface FloatingObjectCoordinator {
+    /** Get the FloatingObjectManager for object CRUD operations */
+    getFloatingObjectManager(): IFloatingObjectManager | null;
+    /** Check if ink mode is active (for input isolation) */
+    isInkActive(): boolean;
+}
+/**
+ * PointerCaptureManager interface.
+ *
+ * Coordinator owns this manager and orchestrates pointer capture lifecycle
+ * based on state machine transitions (drag states).
+ *
+ * ARCHITECTURE:
+ * - Machines are PURE (no DOM access, no side effects)
+ * - Coordinator subscribes to machine state transitions
+ * - When drag state is entered -> coordinator calls onDragStart()
+ * - When drag state is exited -> coordinator calls onDragEnd()
+ * - Component provides DOM element via setContainerElement()
+ *
+ * @see plans/active/excel-parity/P0-01-POINTER-CAPTURE.md
+ */
+export interface PointerCaptureManager {
+    /**
+     * Set the DOM element that will capture pointer events.
+     * Called by the component/hook when container mounts.
+     */
+    setContainerElement(element: HTMLElement | null): void;
+    /**
+     * Called by coordinator when a drag state is entered.
+     * Captures the pointer so events continue outside the window.
+     */
+    onDragStart(pointerId: number): void;
+    /**
+     * Called by coordinator when a drag state is exited.
+     * Releases the pointer capture.
+     */
+    onDragEnd(pointerId: number): void;
+    /**
+     * Check if pointer is currently captured.
+     */
+    isCapturing(): boolean;
+    /**
+     * Get the currently captured pointer ID (or null if not capturing).
+     */
+    getCapturedPointerId(): number | null;
+}
+/**
+ * Interface for providing sheet state to the coordinator.
+ * The spreadsheet store implements this interface.
+ *
+ * This pattern ensures:
+ * 1. TypeScript enforces that all required methods are provided
+ * 2. Single point of wiring instead of many individual callbacks
+ * 3. New state accessors can be added by extending this interface
+ */
+export interface SheetStateProvider {
+    /** Get frozen panes configuration for a sheet */
+    getFrozenPanes(sheetId: string): FrozenPanes;
+    /** Get view options (gridlines, headers visibility, etc.) for a sheet */
+    getSheetViewOptions(sheetId: string): SheetViewOptions;
+    /**
+     * Get the workbook culture setting.
+     * Returns IETF language tag (e.g., 'en-US', 'de-DE').
+     * Used to apply initial culture on renderer initialization.
+     */
+    getCulture(): string;
+    /**
+     * Get split view configuration for a sheet.
+     * Returns null if no split is configured.
+     * Used to restore split view on initialization and sheet switch.
+     */
+    getSplitConfig(sheetId: string): SplitViewportConfig | null;
+    /** Get cell-level scroll position for a sheet (ground truth from Rust/Yrs). */
+    getScrollPosition(sheetId: string): {
+        topRow: number;
+        leftCol: number;
+    };
+}
+/**
+ * Dependencies needed by the coordinator to execute renderer side effects.
+ * These are provided by the component after mount since they require React hooks.
+ */
+export interface RendererDependencies {
+    /**
+     * ViewportReader for sync dimension data.
+     * The renderer execution creates position indices internally from this.
+     */
+    viewport?: ViewportReader;
+    /** Factory function to create the renderer */
+    rendererFactory: RendererFactory;
+    /**
+     * Get cell display value.
+     * Receives sheetId at call time from RenderContext.currentSheetId.
+     * This eliminates stale closure bugs when sheets switch.
+     */
+    getCellValue: (sheetId: string, cell: CellCoord) => unknown;
+    /**
+     * Get cell format.
+     * Receives sheetId at call time from RenderContext.currentSheetId.
+     * This eliminates stale closure bugs when sheets switch.
+     */
+    getCellFormat: (sheetId: string, cell: CellCoord) => CellFormat | undefined;
+    /** Initial sheet ID */
+    initialSheetId: string;
+    /** Total rows */
+    totalRows?: number;
+    /** Total cols */
+    totalCols?: number;
+    /** Provides sheet state (frozen panes, view options) - required for correct initialization */
+    sheetStateProvider: SheetStateProvider;
+    /**
+     * Get the initial scroll position for a sheet.
+     * Called when switching to a sheet to restore scroll position.
+     * Returns {x: 0, y: 0} if no saved position exists.
+     */
+    getInitialScrollPosition?: (sheetId: string) => Point;
+    /**
+     * Notify when scroll position changes for a sheet.
+     * Called on scroll events to save scroll position per sheet.
+     */
+    onScrollPositionChanged?: (sheetId: string, position: Point) => void;
+    /**
+     * Reset the input system's internal scroll position without triggering events.
+     * Called during sheet switch after renderer.setScroll() restores the scroll position,
+     * so the InputCoordinator's physics engine syncs to the restored position.
+     * Without this, the next scroll gesture would jump from the stale position.
+     */
+    onScrollPositionReset?: (position: Point) => void;
+    /**
+     * Called when the renderer is created.
+     * Use this to wire bridges (SmartArt, WordArt, Equation) that need the renderer.
+     * The renderer is guaranteed to exist when this callback is invoked.
+     */
+    onRendererCreated?: (renderer: GridRenderer) => void;
+}
+//# sourceMappingURL=coordinator-interfaces.d.ts.map

package/dist/rendering/coordinator-interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-interfaces.d.ts","sourceRoot":"","sources":["../../src/rendering/coordinator-interfaces.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAM7C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,wBAAwB,IAAI,sBAAsB,GAAG,IAAI,CAAC;IAC1D,wDAAwD;IACxD,WAAW,IAAI,OAAO,CAAC;CACxB;AAMD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;IAEvD;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAAC;CACvC;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7C,yEAAyE;IACzE,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvD;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAMD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,8CAA8C;IAC9C,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IAC5D;;;;OAIG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,UAAU,GAAG,SAAS,CAAC;IAC5E,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,kBAAkB,EAAE,kBAAkB,CAAC;IAMvC;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;IAEtD;;;OAGG;IACH,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,KAAK,IAAI,CAAC;IAErE;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,KAAK,IAAI,CAAC;IAMlD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;CACtD"}