@ricsam/react-spreadsheets 0.0.0 → 0.0.1

package/dist/types/grid/types.d.ts

@@ -0,0 +1,178 @@
+import type { CSSProperties, ReactNode } from 'react';
+/**
+ * Initial state for a GridChild component
+ */
+export interface GridChildInitial {
+    /** Initial X coordinate in px */
+    x: number;
+    /** Initial Y coordinate in px */
+    y: number;
+    /** Initial width in px */
+    width: number;
+    /** Initial height in px */
+    height: number;
+    /** Initial zoom/scale (default: 1) */
+    zoom?: number;
+}
+/**
+ * Represents a child component that can be positioned within the Grid.
+ * Each child has a position, size, and render function.
+ */
+export interface GridChild {
+    /** X coordinate in px */
+    x: number;
+    /** Y coordinate in px */
+    y: number;
+    /** Width in px */
+    width: number;
+    /** Height in px */
+    height: number;
+    /** Zoom/scale factor for the child (default: 1) */
+    zoom?: number;
+    /** Whether the child is minimized */
+    minimized?: boolean;
+    /** Whether the child is maximized (displayed full-screen instead of in grid) */
+    maximized?: boolean;
+    /** Initial state for reset functionality */
+    initial?: GridChildInitial;
+    /** Name of the component to render */
+    component: string;
+    /** Unique identifier for the child */
+    id: string;
+    /** Display title for the child */
+    title: string;
+    /**
+     * If true, the child will remain mounted even when outside the viewport.
+     * Useful for components that need to maintain state or perform background operations.
+     */
+    persistent?: boolean;
+    /** Whether the child can be closed */
+    canClose?: boolean;
+    /** Props for the component */
+    props?: any;
+}
+export interface ChildState {
+    /** Whether the child is selected */
+    isSelected: boolean;
+    /** Whether the child is minimized */
+    isMinimized: boolean;
+    /** Whether the child is maximized */
+    isMaximized: boolean;
+}
+export type GridComponent = (gridChild: GridChild, state: ChildState) => ReactNode;
+/**
+ * Configuration for a placeholder component that follows the mouse until placed.
+ */
+export interface PlaceholderConfig {
+    /** Type of component being placed */
+    componentType: string;
+    /** Title/name for the placeholder */
+    title: string;
+    /** Width of the placeholder in pixels */
+    width: number;
+    /** Height of the placeholder in pixels */
+    height: number;
+    /** Callback when the placeholder is placed - receives world coordinates */
+    onPlaced: (x: number, y: number) => void;
+    /** Optional callback when placement is cancelled */
+    onCancel?: () => void;
+}
+/**
+ * Options for zooming to a specific area
+ */
+export interface ZoomToOptions {
+    /** Target x coordinate */
+    x: number;
+    /** Target y coordinate */
+    y: number;
+    /** Target zoom level */
+    zoom?: number;
+    /** Whether to animate the transition (default: false) */
+    animate?: boolean;
+}
+/**
+ * Options for focusing on a child component
+ */
+export interface FocusChildOptions {
+    /** ID of the child to focus */
+    childId: string;
+    /** Padding around the child in pixels (default: 200) */
+    padding?: number;
+    /** Target zoom level (default: 1) */
+    zoom?: number;
+    /** Whether to animate the transition (default: false) */
+    animate?: boolean;
+}
+/**
+ * Grid component ref API for programmatic control
+ */
+export interface GridRef {
+    /** Zoom to a specific position and zoom level */
+    zoomTo: (options: ZoomToOptions) => void;
+    /** Focus on a specific child component */
+    focusChild: (options: FocusChildOptions) => void;
+    /** Get current viewport state */
+    getViewport: () => ViewportState;
+    /** Set viewport state */
+    setViewport: (viewport: ViewportState) => void;
+    /** Zoom in by one step */
+    zoomIn: () => void;
+    /** Zoom out by one step */
+    zoomOut: () => void;
+    /** Reset zoom to 100% */
+    resetZoom: () => void;
+}
+/**
+ * Props for the Grid component.
+ */
+export interface GridProps {
+    /** Array of child components to render in the grid */
+    children: GridChild[];
+    /** Map of component names to their render functions */
+    components: Record<string, GridComponent>;
+    /** Optional CSS styles for the grid container */
+    style?: CSSProperties;
+    /** Size of each grid cell in pixels (default: 20) */
+    gridSize?: number;
+    /** ID of the currently selected child */
+    selectedChildId?: string | null;
+    /** Callback when a child is selected */
+    onChildSelect?: (childId: string | null) => void;
+    /** Callback when a component is blurred (deselected) */
+    onComponentBlur?: (childId: string) => void;
+    /** Callback when viewport changes - used for saving state, not for controlling the viewport */
+    onViewportChange?: (viewport: ViewportState) => void;
+    /** Callback when children change (for controlled mode) */
+    onChildrenChange?: (children: GridChild[]) => void;
+    /** Callback when a child requests to be maximized/restored */
+    onMaximize?: (childId: string) => void;
+    /** Initial viewport state (used only on mount, not controlled) */
+    initialViewport?: ViewportState;
+    /** Whether to show the background grid lines (default: true) */
+    showGrid?: boolean;
+    /** Grid rendering style: 'lines' for grid lines, 'dots' for dots at intersections (default: 'lines') */
+    gridStyle?: 'lines' | 'dots';
+    /** Placeholder configuration for component placement flow */
+    placeholder?: PlaceholderConfig;
+    /** Whether to show built-in zoom controls (default: true) */
+    showZoomControls?: boolean;
+}
+/**
+ * Represents the current state of the viewport including position and zoom level.
+ */
+export interface ViewportState {
+    /** Current X offset of the viewport */
+    x: number;
+    /** Current Y offset of the viewport */
+    y: number;
+    /** Current zoom level (1.0 = 100%) */
+    zoom: number;
+}
+export type ResizeHandle = 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export declare class ViewportStream {
+    currentViewport: ViewportState;
+    constructor(initialViewport: ViewportState);
+    private subscribers;
+    subscribe(callback: (viewport: ViewportState) => void): () => void;
+    next(nextViewport: ViewportState): void;
+}

package/dist/types/lib.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @ricsam/react-spreadsheets
+ *
+ * React spreadsheet primitives: an infinitely scrollable, virtualized grid with
+ * selection, editing, clipboard, fill handles, column/row resizing and floating
+ * overlays — plus optional bindings for `@ricsam/formula-engine`.
+ *
+ * Remember to import the stylesheet once in your app:
+ *   import "@ricsam/react-spreadsheets/styles.css";
+ */
+export { Spreadsheet, type SpreadsheetProps, type SpreadsheetRef, type SpreadsheetChild, type SpreadsheetChildInitial, type SpreadsheetChildState, type SpreadsheetComponent, } from "./spreadsheet/spreadsheet";
+export { FormulaSheet, FormulaWorkbook, WorkbookClipboardManager, WorkbookSelectionManager, } from "./workbook/workbook";
+export { coerceCellInput, getCellDisplayText, getCellDisplayValue, } from "./workbook/cell-data-type";
+export { normalizeBorderSides, hasAnyBorderSide, type BorderSides, type NormalizedBorderSides, } from "./workbook/border-sides";
+export { onCellEditError, queueCellEditError, type CellEditErrorListener, } from "./workbook/cell-edit-error";
+export type { SerializedCellValue, SpreadsheetColumnWidths, SpreadsheetRowHeights, CellRenderContext, ConditionalStyleCallbackData, } from "./types";
+export { columnToIndex, indexToColumn, getRowNumber, getCellReference, parseCellReference, rowToLetter, letterToRow, findCell, extractColumn, extractColumnByHeader, } from "./spreadsheet/utils";
+export { DEFAULT_CELL_WIDTH, DEFAULT_CELL_HEIGHT, HEADER_WIDTH, HEADER_HEIGHT, } from "./spreadsheet/constants";
+export { DEFAULT_ZOOM, MIN_ZOOM, MAX_ZOOM, ZOOM_FACTOR, CONTROLLED_ZOOM_FACTOR, } from "./spreadsheet/zoom-constants";
+export { normalizeCellSnapAnchor, getCellSnapAnchorFromRect, getRectFromCellSnapAnchor, moveCellSnapAnchorToNearestOrigin, resizeCellSnapAnchorToNearestEdges, getColumnEdgePosition, getRowEdgePosition, getNearestColumnEdgeIndex, getNearestRowEdgeIndex, type CellSnapAnchor, type CellSnapRect, type CellSnapResizeHandle, } from "./spreadsheet/snapping";
+export { ClipboardUtils, type CellDataUpdate, type ExtractedCells, } from "./clipboard/clipboard-manager";
+export { cn } from "./utils/cn";
+export { useResizeObserver } from "./utils/use-resize-observer";
+export { useColorScheme, type ColorScheme } from "./utils/use-color-scheme";
+export { useClickAway } from "./utils/use-click-away";
+export { ViewportStream, type ViewportState, type ResizeHandle } from "./grid/types";

package/dist/types/spreadsheet/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_CELL_WIDTH = 100;
+export declare const DEFAULT_CELL_HEIGHT = 30;
+export declare const HEADER_WIDTH = 50;
+export declare const HEADER_HEIGHT = 30;

package/dist/types/spreadsheet/snapping.d.ts

@@ -0,0 +1,22 @@
+export interface CellSnapAnchor {
+    startCol: number;
+    startRow: number;
+    endCol: number;
+    endRow: number;
+}
+export interface CellSnapRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type CellSnapResizeHandle = 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export declare const normalizeCellSnapAnchor: (anchor: CellSnapAnchor) => CellSnapAnchor;
+export declare const getColumnEdgePosition: (edgeIndex: number, columnWidths: Map<string, number>) => number;
+export declare const getRowEdgePosition: (edgeIndex: number, rowHeights: Map<number, number>) => number;
+export declare const getNearestColumnEdgeIndex: (x: number, columnWidths: Map<string, number>) => number;
+export declare const getNearestRowEdgeIndex: (y: number, rowHeights: Map<number, number>) => number;
+export declare const getCellSnapAnchorFromRect: (rect: CellSnapRect, columnWidths: Map<string, number>, rowHeights: Map<number, number>) => CellSnapAnchor;
+export declare const getRectFromCellSnapAnchor: (anchor: CellSnapAnchor, columnWidths: Map<string, number>, rowHeights: Map<number, number>) => CellSnapRect;
+export declare const moveCellSnapAnchorToNearestOrigin: (anchor: CellSnapAnchor, rect: CellSnapRect, columnWidths: Map<string, number>, rowHeights: Map<number, number>) => CellSnapAnchor;
+export declare const resizeCellSnapAnchorToNearestEdges: (anchor: CellSnapAnchor, rect: CellSnapRect, handle: CellSnapResizeHandle, columnWidths: Map<string, number>, rowHeights: Map<number, number>) => CellSnapAnchor;

package/dist/types/spreadsheet/spreadsheet.d.ts

@@ -0,0 +1,88 @@
+import { type Format, SelectionManager, type SelectionManagerState } from '@ricsam/selection-manager';
+import React, { type ReactNode } from 'react';
+import type { CellRenderContext, SerializedCellValue, SpreadsheetColumnWidths, SpreadsheetRowHeights } from '../types';
+import { type CellSnapAnchor } from './snapping';
+export interface SpreadsheetChildInitial {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    zoom?: number;
+}
+export interface SpreadsheetChild {
+    id: string;
+    title: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    zoom?: number;
+    snapToCells?: boolean;
+    cellAnchor?: CellSnapAnchor;
+    minimized?: boolean;
+    initial?: SpreadsheetChildInitial;
+    component: string;
+    canClose?: boolean;
+    persistent?: boolean;
+    props?: any;
+}
+export interface SpreadsheetChildState {
+    isSelected: boolean;
+    isMinimized: boolean;
+}
+export type SpreadsheetComponent = (child: SpreadsheetChild, state: SpreadsheetChildState) => ReactNode;
+export interface SpreadsheetProps {
+    style?: React.CSSProperties;
+    /** Extra class name applied to the outer `.rsp-root` element. */
+    className?: string;
+    containerProps?: React.HTMLAttributes<HTMLDivElement>;
+    cellData?: Map<string, SerializedCellValue>;
+    onCellDataChange?: (data: Map<string, SerializedCellValue>) => void;
+    onCellDataChangeError?: (error: unknown) => void;
+    columnWidths?: SpreadsheetColumnWidths;
+    onColumnWidthsChange?: (columnWidths: SpreadsheetColumnWidths) => void;
+    rowHeights?: SpreadsheetRowHeights;
+    onRowHeightsChange?: (rowHeights: SpreadsheetRowHeights) => void;
+    customCellStyle?: (cell: CellRenderContext) => React.CSSProperties;
+    customCellRenderer?: (cell: CellRenderContext) => React.ReactNode;
+    /**
+     * Used for saving the value to the cell data. Most useful for parsing a pasted
+     * string value to a number.
+     */
+    parseValue?: (value: string, cell: {
+        id: string;
+        row: number;
+        col: string;
+        rowIndex: number;
+        colIndex: number;
+    }) => string | number;
+    selection?: {
+        initialState?: Partial<SelectionManagerState>;
+        state?: SelectionManagerState;
+        onStateChange?: (state: SelectionManagerState) => void;
+        effects?: (selectionManager: SelectionManager) => (() => void) | void;
+        formats?: Format[];
+    };
+    components?: Record<string, SpreadsheetComponent>;
+    overlayChildren?: SpreadsheetChild[];
+    selectedOverlayId?: string | null;
+    onOverlaySelect?: (childId: string | null) => void;
+    onOverlayChildrenChange?: (children: SpreadsheetChild[]) => void;
+    overlayPlaceholder?: {
+        componentType: string;
+        title: string;
+        width: number;
+        height: number;
+        onPlaced: (x: number, y: number) => void;
+        onCancel?: () => void;
+    };
+    /** Whether the parent component is selected (used to gate overlay selection) */
+    parentSelected?: boolean;
+}
+export interface SpreadsheetRef {
+    focus: () => void;
+    blur: () => void;
+}
+export declare const Spreadsheet: React.ForwardRefExoticComponent<SpreadsheetProps & {
+    disableClipboard?: boolean;
+} & React.RefAttributes<SpreadsheetRef | undefined>>;

package/dist/types/spreadsheet/utils.d.ts

@@ -0,0 +1,28 @@
+export declare const columnToIndex: (col: string) => number;
+export declare const indexToColumn: (index: number) => string;
+export declare function getRowNumber(index: number): number;
+export declare function getCellReference({ rowIndex, colIndex }: {
+    rowIndex: number;
+    colIndex: number;
+}): string;
+export declare function rowToLetter(row: number): string;
+export declare function letterToRow(letter: string): number;
+export declare const parseCellReference: (cellReference: string) => {
+    column: string;
+    row: number;
+    columnIndex: number;
+    rowIndex: number;
+};
+export declare function findCell(map: Map<string, string | number>, search: string): {
+    cellReference: string;
+    column: string;
+    row: number;
+    columnIndex: number;
+    rowIndex: number;
+} | undefined;
+/**
+ * Returns the values that belong to the column whose header equals `header`,
+ * in strict top-to-bottom order (H2, H3, H4 …).
+ */
+export declare function extractColumnByHeader(map: Map<string, string | number>, header: string): (string | number)[];
+export declare function extractColumn(map: Map<string, string | number>, colIndex: number, rowIndex?: number, handleEmpty?: (rowIndex: number) => string | number): (string | number)[];

package/dist/types/spreadsheet/zoom-constants.d.ts

@@ -0,0 +1,5 @@
+export declare const ZOOM_FACTOR = 0.05;
+export declare const CONTROLLED_ZOOM_FACTOR = 0.01;
+export declare const DEFAULT_ZOOM = 1;
+export declare const MIN_ZOOM = 0.5;
+export declare const MAX_ZOOM = 3;

package/dist/types/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Core value types.
+ *
+ * These mirror `@ricsam/formula-engine` so the components can be used with or
+ * without the engine installed. The engine is an optional peer dependency; the
+ * grid itself only ever needs to know that a cell holds a primitive.
+ */
+export type SerializedCellValue = string | number | boolean | undefined;
+/** Column widths keyed by column letter, e.g. `{ A: 160 }`. */
+export type SpreadsheetColumnWidths = Record<string, number>;
+/** Row heights keyed by 1-based row number, e.g. `{ 1: 40 }`. */
+export type SpreadsheetRowHeights = Record<number, number>;
+/** Data passed to `customCellStyle` / `customCellRenderer`. */
+export type CellRenderContext = {
+    /** A1-style identifier, e.g. `"B7"`. */
+    id: string;
+    /** 1-based row number. */
+    row: number;
+    /** Column letter. */
+    col: string;
+    /** 0-based row index. */
+    rowIndex: number;
+    /** 0-based column index. */
+    colIndex: number;
+    value: SerializedCellValue;
+    isSelected: boolean;
+    isBeingEdited: boolean;
+};
+/**
+ * @deprecated Use {@link CellRenderContext}. Kept as an alias for consumers
+ * migrating from the original internal component.
+ */
+export type ConditionalStyleCallbackData = CellRenderContext;

package/dist/types/utils/cn.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Minimal class name joiner.
+ *
+ * Deliberately dependency-free: this library ships no styling framework and
+ * only needs truthy filtering + joining for CSS module class composition.
+ */
+export type ClassValue = string | number | null | undefined | false | ClassValue[] | Record<string, boolean | null | undefined>;
+export declare function cn(...values: ClassValue[]): string;

package/dist/types/utils/use-click-away.d.ts

@@ -0,0 +1 @@
+export declare const useClickAway: (ref: HTMLElement | null, callback: (away: boolean) => void) => void;

package/dist/types/utils/use-color-scheme.d.ts

@@ -0,0 +1,10 @@
+export type ColorScheme = "light" | "dark";
+/**
+ * Resolves the effective color scheme for canvas painting.
+ *
+ * CSS handles theming through `light-dark()`, but the 2D canvas context cannot
+ * use it, so grid lines need a concrete resolved value. When an element is
+ * supplied we read its computed `color-scheme`, which lets a consumer pin a
+ * subtree to one mode; otherwise we fall back to the OS preference.
+ */
+export declare function useColorScheme(element?: HTMLElement | null): ColorScheme;

package/dist/types/utils/use-resize-observer.d.ts

@@ -0,0 +1,15 @@
+export interface ResizeObserverSize {
+    width: number;
+    height: number;
+}
+/**
+ * Observes the size of an element via a callback ref.
+ *
+ * Returns `[size, ref]` so the consumer can spread the ref onto any element.
+ * Falls back to `getBoundingClientRect` once on attach so the first paint has
+ * usable dimensions even before the observer fires.
+ */
+export declare function useResizeObserver<T extends HTMLElement = HTMLDivElement>(): [
+    ResizeObserverSize,
+    (element: T | null) => void
+];

package/dist/types/workbook/border-sides.d.ts

@@ -0,0 +1,20 @@
+import type { CellStyle } from "@ricsam/formula-engine";
+export type BorderSides = NonNullable<CellStyle["borderSides"]>;
+export type NormalizedBorderSides = {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+};
+/**
+ * Normalizes a partial border-sides record into a fully specified one.
+ *
+ * When `borderSides` is omitted entirely the style is interpreted as "all
+ * sides", which matches how a plain `borderColor` is expected to behave.
+ *
+ * @param sides Partial per-side flags from a `CellStyle`.
+ * @param defaultAllWhenUnset Value used for every side when `sides` is undefined.
+ */
+export declare function normalizeBorderSides(sides: BorderSides | undefined, defaultAllWhenUnset?: boolean): NormalizedBorderSides;
+/** True when at least one side should be drawn. */
+export declare function hasAnyBorderSide(sides: NormalizedBorderSides): boolean;

package/dist/types/workbook/cell-data-type.d.ts

@@ -0,0 +1,15 @@
+import type { CellDataType, SerializedCellValue } from "@ricsam/formula-engine";
+/**
+ * Converts raw editor input into the value to store for a cell.
+ *
+ * - Formulas (leading `=`) are always preserved verbatim.
+ * - `"general"` infers number/boolean, otherwise keeps the string.
+ * - An explicit data type forces that interpretation, falling back to the raw
+ *   string when the input cannot be represented.
+ * - An empty string clears the cell (`undefined`).
+ */
+export declare function coerceCellInput(value: string, dataType?: CellDataType): SerializedCellValue;
+/** Formats an evaluated value for display, with thousands separators. */
+export declare function getCellDisplayText(value: SerializedCellValue): string;
+/** Serializes a value for the clipboard (unformatted, round-trippable). */
+export declare function getCellDisplayValue(value: SerializedCellValue): string;

package/dist/types/workbook/cell-edit-error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cell edit error reporting.
+ *
+ * The original component reported rejected edits through an app-specific
+ * snackbar. A reusable library must not own UI for that, so errors are routed
+ * through a subscribable sink instead: by default they are logged, and a host
+ * app can subscribe to render them however it likes.
+ */
+export type CellEditErrorListener = (error: unknown) => void;
+/**
+ * Subscribes to cell edit errors (e.g. the engine rejecting a formula).
+ *
+ * @returns An unsubscribe function.
+ */
+export declare function onCellEditError(listener: CellEditErrorListener): () => void;
+/**
+ * Default `onCellDataChangeError` handler.
+ *
+ * Notifies subscribers; if there are none it falls back to `console.error` so
+ * failures are never silently swallowed during development.
+ */
+export declare function queueCellEditError(error: unknown): void;

package/dist/types/workbook/workbook-selection-manager.d.ts

@@ -0,0 +1,71 @@
+import type { RangeAddress } from '@ricsam/formula-engine';
+import type { SelectionManager } from '@ricsam/selection-manager';
+interface ManagerContext {
+    workbookName: string;
+    sheetName: string;
+}
+export declare class WorkbookSelectionManager {
+    private managers;
+    private lastFocusedManager;
+    private listeners;
+    private cleanupFunctions;
+    private smAreaToSpreadsheetRange;
+    /**
+     * Register a SelectionManager with its workbook/sheet context
+     * Returns a cleanup function to unregister
+     */
+    add(manager: SelectionManager, context: ManagerContext): () => void;
+    /**
+     * Get the SelectionManager that was last focused or had selection activity
+     */
+    getLastFocusedSelectionManager(): {
+        sm: SelectionManager;
+        context: ManagerContext;
+    } | null;
+    /**
+     * Get all current selections from the last focused manager.
+     */
+    getSelections(): RangeAddress[];
+    /**
+     * Get the last/primary selection from the last focused manager
+     */
+    getLastSelection(): RangeAddress | null;
+    /**
+     * Subscribe to selection changes
+     * Returns cleanup function
+     */
+    onSelectionChange(callback: (selections: RangeAddress[]) => void): () => void;
+    /**
+     * Format the last selection as a range string
+     * e.g., "[Workbook]Sheet!A1:C10" or "[Workbook]'My Sheet'!A1:INFINITY"
+     */
+    formatLastSelectionAsRange(): string;
+    /**
+     * Blur all selection managers (remove focus from all)
+     * This should be called when the component loses focus
+     */
+    blur(): void;
+    /**
+     * Focus the selection manager for a specific workbook (first sheet found).
+     * This is useful when programmatically switching focus, e.g., after maximizing a window.
+     */
+    focusWorkbook(workbookName: string): void;
+    /**
+     * Focus the selection manager for a specific sheet without changing the cell selection.
+     */
+    focusSheet(workbookName: string, sheetName: string): boolean;
+    /**
+     * Focus a specific cell in a specific workbook and sheet.
+     * Finds the matching SelectionManager, sets its selection to the given cell,
+     * and focuses it.
+     *
+     * @returns true if the cell was successfully focused, false if no matching
+     *          manager was found (e.g. the sheet is not currently rendered).
+     */
+    focusCell(workbookName: string, sheetName: string, row: number, col: number): boolean;
+    /**
+     * Notify all listeners of selection change
+     */
+    private emitChange;
+}
+export {};

package/dist/types/workbook/workbook.d.ts

@@ -0,0 +1,86 @@
+import { FormulaEngine, type CellAddress } from '@ricsam/formula-engine';
+import type { SelectionManager } from '@ricsam/selection-manager';
+import React from 'react';
+import { type SpreadsheetProps } from '../spreadsheet/spreadsheet';
+import type { CellRenderContext, SpreadsheetColumnWidths, SpreadsheetRowHeights } from '../types';
+import type { WorkbookSelectionManager } from './workbook-selection-manager';
+import { type CellDataUpdate, ClipboardUtils } from '../clipboard/clipboard-manager';
+type SpreadsheetLayout = {
+    columnWidths?: SpreadsheetColumnWidths;
+    rowHeights?: SpreadsheetRowHeights;
+};
+interface FormulaSheetProps extends Omit<SpreadsheetProps, 'selection' | 'customCellStyle' | 'customCellRenderer' | 'components' | 'overlayChildren' | 'selectedOverlayId' | 'onOverlaySelect' | 'onOverlayChildrenChange' | 'overlayPlaceholder' | 'parentSelected'> {
+    clipboardManager?: WorkbookClipboardManager;
+    sheetName: string;
+    workbookName: string;
+    engine: FormulaEngine;
+    verboseErrors?: boolean;
+    selection?: SpreadsheetProps['selection'];
+    selectionManager?: WorkbookSelectionManager;
+    customCellStyle?: (cell: CellRenderContext, internalStyle: React.CSSProperties) => React.CSSProperties;
+    customCellRenderer?: (cell: CellRenderContext, internalElement: React.ReactNode) => React.ReactNode;
+    components?: SpreadsheetProps['components'];
+    overlayChildren?: SpreadsheetProps['overlayChildren'];
+    selectedOverlayId?: SpreadsheetProps['selectedOverlayId'];
+    onOverlaySelect?: SpreadsheetProps['onOverlaySelect'];
+    onOverlayChildrenChange?: SpreadsheetProps['onOverlayChildrenChange'];
+    overlayPlaceholder?: SpreadsheetProps['overlayPlaceholder'];
+    /** Whether the grid child is selected (controls interactivity) */
+    isSelected?: boolean;
+    /** Optional toolbar to render above the sheet */
+    toolbar?: React.ReactNode;
+    /** When true, cells display raw formulas instead of computed values */
+    showFormulas?: boolean;
+}
+export declare class WorkbookClipboardManager extends ClipboardUtils {
+    private engine;
+    constructor(engine: FormulaEngine);
+    copiedCells: CellAddress[];
+    signature: string;
+    isCut: boolean;
+    triggerCopy(context: {
+        workbookName: string;
+        sheetName: string;
+        selectionManager: SelectionManager;
+        copyType: 'value' | 'formula';
+        cut?: boolean;
+    }): void;
+    triggerPaste(context: {
+        workbookName: string;
+        sheetName: string;
+        selectionManager: SelectionManager;
+        updates: CellDataUpdate[];
+        rawString: string;
+        pasteType: 'value' | 'formula';
+    }): void;
+}
+export declare function FormulaSheet({ sheetName, workbookName, engine, verboseErrors, selection, selectionManager, customCellStyle, customCellRenderer, onCellDataChangeError, components, overlayChildren, selectedOverlayId, onOverlaySelect, onOverlayChildrenChange, overlayPlaceholder, clipboardManager: controlledClipboardManager, isSelected, toolbar, showFormulas, ...rest }: FormulaSheetProps): React.JSX.Element;
+interface FormulaWorkbookProps extends Omit<SpreadsheetProps, 'cellData' | 'onCellDataChange' | 'selection' | 'customCellStyle' | 'customCellRenderer' | 'components' | 'overlayChildren' | 'selectedOverlayId' | 'onOverlaySelect' | 'onOverlayChildrenChange' | 'overlayPlaceholder' | 'parentSelected' | 'columnWidths' | 'onColumnWidthsChange' | 'rowHeights' | 'onRowHeightsChange'> {
+    workbookName: string;
+    clipboardManager?: WorkbookClipboardManager;
+    engine: FormulaEngine;
+    activeSheet?: string;
+    onActiveSheetChange?: (sheetName: string) => void;
+    verboseErrors?: boolean;
+    selection?: SpreadsheetProps['selection'];
+    selectionManager?: WorkbookSelectionManager;
+    customCellStyle?: (cell: CellRenderContext, internalStyle: React.CSSProperties) => React.CSSProperties;
+    customCellRenderer?: (cell: CellRenderContext, internalElement: React.ReactNode) => React.ReactNode;
+    components?: SpreadsheetProps['components'];
+    sheetOverlayChildren?: Record<string, SpreadsheetProps['overlayChildren']>;
+    sheetSelectedOverlayIds?: Record<string, SpreadsheetProps['selectedOverlayId']>;
+    sheetLayouts?: Record<string, SpreadsheetLayout>;
+    onSheetColumnWidthsChange?: (sheetName: string, columnWidths: SpreadsheetColumnWidths) => void;
+    onSheetRowHeightsChange?: (sheetName: string, rowHeights: SpreadsheetRowHeights) => void;
+    onOverlaySelect?: (sheetName: string, overlayId: string | null) => void;
+    onOverlayChildrenChange?: (sheetName: string, children: NonNullable<SpreadsheetProps['overlayChildren']>) => void;
+    overlayPlaceholder?: SpreadsheetProps['overlayPlaceholder'];
+    /** Whether the grid child is selected (controls interactivity) */
+    isSelected?: boolean;
+    /** Optional toolbar to render above the workbook */
+    toolbar?: React.ReactNode;
+    /** When true, cells display raw formulas instead of computed values */
+    showFormulas?: boolean;
+}
+export declare function FormulaWorkbook({ clipboardManager: controlledClipboardManager, workbookName, engine, activeSheet: controlledActiveSheet, onActiveSheetChange, verboseErrors, selectionManager, components, sheetOverlayChildren, sheetSelectedOverlayIds, sheetLayouts, onSheetColumnWidthsChange, onSheetRowHeightsChange, onOverlaySelect, onOverlayChildrenChange, overlayPlaceholder, isSelected, toolbar, showFormulas, ...rest }: FormulaWorkbookProps): React.JSX.Element;
+export { WorkbookSelectionManager } from './workbook-selection-manager';