@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/data/tables.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Table Contracts
+ *
+ * Type definitions for Excel-style tables with structured references.
+ * Tables provide named ranges with automatic formatting, filtering,
+ * total rows, and structured reference support in formulas.
+ *
+ * P0-07 Migration: Tables now use Cell Identity Model for CRDT-safe positioning.
+ * - rangeIdentity replaces range (CellRange) with CellIdRange
+ * - Position resolution happens at render time via resolveTableRange()
+ *
+ * @see plans/active/excel-parity/P0-07-STRUCTURE-COORDINATION.md
+ */
+import type { CellIdRange } from '../cells/cell-identity';
+import type { CellFormat, CellRange } from '../core/core';
+/**
+ * Table style presets matching Excel's table style gallery.
+ * Light styles (1-21), Medium styles (1-28), Dark styles (1-11).
+ */
+export type TableStylePreset = 'none' | 'light1' | 'light2' | 'light3' | 'light4' | 'light5' | 'light6' | 'light7' | 'light8' | 'light9' | 'light10' | 'light11' | 'light12' | 'light13' | 'light14' | 'light15' | 'light16' | 'light17' | 'light18' | 'light19' | 'light20' | 'light21' | 'medium1' | 'medium2' | 'medium3' | 'medium4' | 'medium5' | 'medium6' | 'medium7' | 'medium8' | 'medium9' | 'medium10' | 'medium11' | 'medium12' | 'medium13' | 'medium14' | 'medium15' | 'medium16' | 'medium17' | 'medium18' | 'medium19' | 'medium20' | 'medium21' | 'medium22' | 'medium23' | 'medium24' | 'medium25' | 'medium26' | 'medium27' | 'medium28' | 'dark1' | 'dark2' | 'dark3' | 'dark4' | 'dark5' | 'dark6' | 'dark7' | 'dark8' | 'dark9' | 'dark10' | 'dark11';
+/**
+ * Custom table style definition (user-defined).
+ * Allows fine-grained control over table appearance.
+ */
+export interface TableCustomStyle {
+    /** Header row background color */
+    headerRowFill?: string;
+    /** Header row font formatting */
+    headerRowFont?: CellFormat;
+    /** Data row background color */
+    dataRowFill?: string;
+    /** Alternating data row background (for banded rows) */
+    dataRowAltFill?: string;
+    /** Total row background color */
+    totalRowFill?: string;
+    /** Total row font formatting */
+    totalRowFont?: CellFormat;
+    /** First column highlight background */
+    firstColumnFill?: string;
+    /** Last column highlight background */
+    lastColumnFill?: string;
+}
+/**
+ * Complete table style configuration.
+ * Either uses a preset or custom style definition.
+ */
+export interface TableStyle {
+    /** Preset style name (mutually exclusive with custom) */
+    preset?: TableStylePreset;
+    /** Custom style definition (mutually exclusive with preset) */
+    custom?: TableCustomStyle;
+    /** Show alternating row colors */
+    showBandedRows?: boolean;
+    /** Show alternating column colors */
+    showBandedColumns?: boolean;
+    /** Highlight first column with special formatting */
+    showFirstColumnHighlight?: boolean;
+    /** Highlight last column with special formatting */
+    showLastColumnHighlight?: boolean;
+}
+/**
+ * Total row function types.
+ * Maps to Excel's total row dropdown options.
+ */
+export type TotalFunction = 'none' | 'sum' | 'count' | 'average' | 'min' | 'max' | 'stdDev' | 'var' | 'countNums' | 'custom';
+/**
+ * Column definition within a table.
+ * Each column has a stable ID and configurable total row behavior.
+ */
+export interface TableColumn {
+    /** Unique column ID (stable across renames) */
+    id: string;
+    /** Display name shown in header row */
+    name: string;
+    /** Column index within table (0-indexed) */
+    index: number;
+    /** Total row formula (e.g., "=SUBTOTAL(109,[Sales])") */
+    totalFormula?: string;
+    /** Total row function type for UI display */
+    totalFunction?: TotalFunction;
+    /** Column-level data validation schema ID (optional) */
+    validationSchemaId?: string;
+    /**
+     * Calculated column formula (Excel parity: Tables P0-A).
+     * When set, this formula automatically fills the entire column.
+     * New rows automatically get this formula.
+     * Uses structured references with @ shorthand (e.g., "=[@Price]*[@Quantity]").
+     */
+    calculatedFormula?: string;
+}
+/**
+ * Complete table configuration stored in Yjs.
+ * This is the source of truth for table metadata.
+ *
+ * P0-07: Tables use CellIdRange for CRDT-safe range tracking.
+ * The rangeIdentity field stores CellId corners, and position-based
+ * range is resolved at render time via resolveTableRange().
+ */
+export interface TableConfig {
+    /** Unique table identifier */
+    id: string;
+    /** Table name used in structured references (e.g., "Table1") */
+    name: string;
+    /** Sheet containing the table */
+    sheetId: string;
+    /**
+     * P0-07: CellId-based range (CRDT-safe).
+     * Automatically expands when rows/cols inserted inside table.
+     * Resolution to positions happens at render time.
+     */
+    rangeIdentity?: CellIdRange;
+    /**
+     * @deprecated Use rangeIdentity instead.
+     * Legacy position-based range - kept for migration only.
+     * Table range (includes header and total rows if present)
+     */
+    range: CellRange;
+    /** Whether table has a header row (default: true) */
+    hasHeaderRow: boolean;
+    /** Whether table has a total row (default: false) */
+    hasTotalRow: boolean;
+    /** Column definitions in order */
+    columns: TableColumn[];
+    /** Style configuration */
+    style: TableStyle;
+    /** Auto-expand when data added adjacent to table (default: true) */
+    autoExpand: boolean;
+    /** Show filter dropdowns in header row (default: true) */
+    showFilterButtons: boolean;
+    /** Created timestamp (Unix ms) */
+    createdAt?: number;
+    /** Last modified timestamp (Unix ms) */
+    updatedAt?: number;
+}
+/**
+ * Special item specifiers in structured references.
+ * Used in formulas like Table1[[#Headers],[Sales]]
+ */
+export type StructuredReferenceSpecifier = 'all' | 'data' | 'headers' | 'totals' | 'thisRow';
+/**
+ * Parsed structured reference from a formula.
+ * Represents references like Table1[[#Headers],[Sales]:[Revenue]]
+ */
+export interface StructuredReference {
+    /** Table name as it appears in the formula */
+    tableName: string;
+    /** Special item specifiers (can be multiple) */
+    specifiers: StructuredReferenceSpecifier[];
+    /** Column references (names or ranges like [Start]:[End]) */
+    columns: string[];
+    /** Whether this is a reference to the entire table (no column specifier) */
+    isWholeTable: boolean;
+}
+/**
+ * Options for creating a new table.
+ */
+export interface CreateTableOptions {
+    /** Table name (auto-generated if not provided) */
+    name?: string;
+    /** Whether first row contains headers (default: true) */
+    hasHeaderRow?: boolean;
+    /** Initial style configuration */
+    style?: TableStyle;
+    /** Auto-expand behavior (default: true) */
+    autoExpand?: boolean;
+    /** Show filter buttons (default: true) */
+    showFilterButtons?: boolean;
+}
+/**
+ * Result of resolving a structured reference to cell coordinates.
+ */
+export interface ResolvedStructuredReference {
+    /** The resolved cell range */
+    range: CellRange;
+    /** Table ID this reference belongs to */
+    tableId: string;
+    /** Whether the reference is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Table manager interface for CRUD operations on tables.
+ * Implemented in engine, integrated via coordinator.
+ */
+export interface ITableManager {
+    /**
+     * Create a new table from a cell range.
+     * @param sheetId Sheet to create the table in
+     * @param range Cell range for the table
+     * @param options Optional configuration
+     * @returns The created table configuration
+     */
+    createTable(sheetId: string, range: CellRange, options?: CreateTableOptions): TableConfig;
+    /**
+     * Get table by ID.
+     * @param tableId Table identifier
+     * @returns Table configuration or undefined if not found
+     */
+    getTable(tableId: string): TableConfig | undefined;
+    /**
+     * Get table by name.
+     * @param tableName Table name (case-insensitive)
+     * @returns Table configuration or undefined if not found
+     */
+    getTableByName(tableName: string): TableConfig | undefined;
+    /**
+     * Get all tables in a sheet.
+     * @param sheetId Sheet identifier
+     * @returns Array of table configurations
+     */
+    getTablesInSheet(sheetId: string): TableConfig[];
+    /**
+     * Get all tables in the workbook.
+     * @returns Array of all table configurations
+     */
+    getAllTables(): TableConfig[];
+    /**
+     * Update table configuration.
+     * @param tableId Table identifier
+     * @param updates Partial configuration to merge
+     */
+    updateTable(tableId: string, updates: Partial<TableConfig>): void;
+    /**
+     * Delete a table (removes table formatting but keeps cell data).
+     * @param tableId Table identifier
+     */
+    deleteTable(tableId: string): void;
+    /**
+     * Convert table back to a regular range (removes table, keeps data).
+     * @param tableId Table identifier
+     */
+    convertToRange(tableId: string): void;
+    /**
+     * Resize table to a new range.
+     * @param tableId Table identifier
+     * @param newRange New table range
+     */
+    resizeTable(tableId: string, newRange: CellRange): void;
+    /**
+     * Enable or disable the total row.
+     * @param tableId Table identifier
+     * @param enabled Whether to show total row
+     */
+    setTotalRow(tableId: string, enabled: boolean): void;
+    /**
+     * Set total row function for a column.
+     * @param tableId Table identifier
+     * @param columnIndex Column index within table
+     * @param fn Total function type
+     */
+    setColumnTotalFunction(tableId: string, columnIndex: number, fn: TotalFunction): void;
+    /**
+     * Rename a table.
+     * @param tableId Table identifier
+     * @param newName New table name
+     */
+    renameTable(tableId: string, newName: string): void;
+    /**
+     * Rename a column in a table.
+     * @param tableId Table identifier
+     * @param columnIndex Column index within table
+     * @param newName New column name
+     */
+    renameColumn(tableId: string, columnIndex: number, newName: string): void;
+    /**
+     * Check if a cell is inside any table.
+     * @param sheetId Sheet identifier
+     * @param row Row index
+     * @param col Column index
+     * @returns True if cell is inside a table
+     */
+    isInTable(sheetId: string, row: number, col: number): boolean;
+    /**
+     * Get the table containing a specific cell.
+     * @param sheetId Sheet identifier
+     * @param row Row index
+     * @param col Column index
+     * @returns Table configuration or undefined if cell is not in a table
+     */
+    getTableAtCell(sheetId: string, row: number, col: number): TableConfig | undefined;
+    /**
+     * Get the data range of a table (excludes header and total rows).
+     * @param tableId Table identifier
+     * @returns Data-only range
+     */
+    getDataRange(tableId: string): CellRange;
+    /**
+     * Get the header row range of a table.
+     * @param tableId Table identifier
+     * @returns Header row range or undefined if no header row
+     */
+    getHeaderRange(tableId: string): CellRange | undefined;
+    /**
+     * Get the total row range of a table.
+     * @param tableId Table identifier
+     * @returns Total row range or undefined if no total row
+     */
+    getTotalRange(tableId: string): CellRange | undefined;
+    /**
+     * Parse a structured reference string.
+     * @param ref Structured reference string (e.g., "Table1[Sales]")
+     * @returns Parsed reference or null if invalid syntax
+     */
+    parseStructuredReference(ref: string): StructuredReference | null;
+    /**
+     * Resolve a structured reference to a cell range.
+     * @param ref Parsed structured reference
+     * @param currentRow Current row for [#This Row] resolution (optional)
+     * @returns Resolved range with validity status
+     */
+    resolveStructuredReference(ref: StructuredReference, currentRow?: number): ResolvedStructuredReference;
+    /**
+     * Generate a structured reference string for a range within a table.
+     * @param tableId Table identifier
+     * @param range Range within the table
+     * @returns Structured reference string or null if range not in table
+     */
+    generateStructuredReference(tableId: string, range: CellRange): string | null;
+    /**
+     * Check if a table name is valid and available.
+     * @param name Proposed table name
+     * @param excludeTableId Table ID to exclude from uniqueness check (for renames)
+     * @returns True if name is valid and available
+     */
+    isValidTableName(name: string, excludeTableId?: string): boolean;
+    /**
+     * Generate a unique table name.
+     * @returns Unique name like "Table1", "Table2", etc.
+     */
+    generateTableName(): string;
+}
+//# sourceMappingURL=tables.d.ts.map

package/dist/data/tables.d.ts.map

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

package/dist/data/trace-arrows.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Trace Arrows Types
+ *
+ * Types for formula auditing trace arrows visualization.
+ *
+ * CRITICAL: Trace arrows use CellId (stable identity) not row/col (mutable positions).
+ * This ensures arrows survive structure changes (row/col insert/delete) - positions
+ * are resolved at render time via CellPositionLookup.
+ *
+ * @see docs/architecture/cell-identity.md
+ * @see plans/active/detailed-parity-implementation/STREAM-B2-FORMULA-AUDITING.md
+ *
+ * @module trace-arrows
+ */
+import type { CellId } from '../cells/cell-identity';
+import type { SheetId } from '../core/core';
+/**
+ * Type of trace arrow - indicates direction of dependency.
+ *
+ * - precedent: Arrow from a cell that this cell depends on (input)
+ * - dependent: Arrow to a cell that depends on this cell (output)
+ */
+export type TraceArrowType = 'precedent' | 'dependent';
+/**
+ * A trace arrow connecting two cells by their stable identities.
+ *
+ * IMPORTANT: Uses CellId (stable) not row/col (mutable).
+ * Positions are resolved at render time via CellPositionLookup.
+ * This ensures arrows follow cells when rows/cols are inserted/deleted.
+ *
+ * @example
+ * // User traces precedents for cell with formula =A1+B1
+ * // Creates two arrows: A1→target, B1→target
+ * const arrow: TraceArrow = {
+ *   id: 'prec-target-a1-0',
+ *   fromCellId: 'abc-123...',  // CellId of A1 (stable)
+ *   toCellId: 'def-456...',    // CellId of target (stable)
+ *   type: 'precedent',
+ *   crossSheet: false,
+ *   fromSheetId: 'sheet-1',
+ *   toSheetId: 'sheet-1',
+ *   level: 1
+ * };
+ *
+ * // After inserting column at A:
+ * // - CellIds unchanged
+ * // - Positions resolved at render time show B1→target, C1→target
+ */
+/**
+ * Position data for a trace arrow endpoint.
+ * Used as fallback when CellId lookup fails (e.g., empty cells without stored CellIds).
+ */
+export interface TraceArrowPosition {
+    sheetId: SheetId;
+    row: number;
+    col: number;
+}
+export interface TraceArrow {
+    /**
+     * Unique ID for this arrow.
+     * Used for React keys and targeted removal.
+     * Format: `{type}-{targetCellId}-{sourceCellId}-{index}`
+     */
+    id: string;
+    /**
+     * Source cell identity (stable - never changes).
+     * For precedents: the cell that is referenced
+     * For dependents: the cell containing the formula
+     */
+    fromCellId: CellId;
+    /**
+     * Target cell identity (stable - never changes).
+     * For precedents: the cell containing the formula
+     * For dependents: the cell that references this one
+     */
+    toCellId: CellId;
+    /**
+     * Arrow direction: precedent = input, dependent = output.
+     * Affects arrow color (blue for precedent, red for dependent).
+     */
+    type: TraceArrowType;
+    /**
+     * True if source and target are on different sheets.
+     * Cross-sheet arrows render with dashed lines and a sheet indicator icon.
+     */
+    crossSheet: boolean;
+    /**
+     * Sheet containing the source cell (fromCellId).
+     */
+    fromSheetId: SheetId;
+    /**
+     * Sheet containing the target cell (toCellId).
+     */
+    toSheetId: SheetId;
+    /**
+     * Trace level: 1 = direct reference, 2+ = transitive.
+     * Excel allows clicking "Trace Precedents" multiple times to show deeper levels.
+     * Level 1 arrows are shown first, then level 2, etc.
+     */
+    level: number;
+    /**
+     * Fallback position for source cell.
+     * Used when CellId lookup fails (e.g., empty cells that don't have stored CellIds).
+     * The renderer should use this position directly when getCellPosition returns null.
+     */
+    fromPosition: TraceArrowPosition;
+    /**
+     * Fallback position for target cell.
+     * Used when CellId lookup fails (e.g., empty cells that don't have stored CellIds).
+     * The renderer should use this position directly when getCellPosition returns null.
+     */
+    toPosition: TraceArrowPosition;
+}
+/**
+ * State for the trace arrows UI feature.
+ *
+ * This is ephemeral UI state (not persisted to Yjs) - when the user closes
+ * the spreadsheet, trace arrows disappear. Use Zustand slice, not Yjs.
+ */
+export interface TraceArrowsState {
+    /**
+     * Map from sheetId to arrows visible on that sheet.
+     * When switching sheets, only arrows for the current sheet are rendered.
+     * Cross-sheet arrows appear on both the source and target sheets.
+     */
+    arrowsBySheet: Map<SheetId, TraceArrow[]>;
+    /**
+     * The cell that was the "root" of the current trace operation.
+     * Used for UI highlighting and "Remove Arrows" context.
+     */
+    tracedCellId: CellId | null;
+    /**
+     * Sheet containing the traced cell.
+     */
+    tracedSheetId: SheetId | null;
+}
+/**
+ * Options for creating a trace arrow.
+ * Used by action handlers to construct TraceArrow objects.
+ */
+export interface CreateTraceArrowOptions {
+    /** Source cell identity */
+    fromCellId: CellId;
+    /** Target cell identity */
+    toCellId: CellId;
+    /** Arrow type */
+    type: TraceArrowType;
+    /** Source sheet ID */
+    fromSheetId: SheetId;
+    /** Target sheet ID */
+    toSheetId: SheetId;
+    /** Trace level (default: 1) */
+    level?: number;
+    /** Source cell position (fallback for rendering) */
+    fromPosition: {
+        row: number;
+        col: number;
+    };
+    /** Target cell position (fallback for rendering) */
+    toPosition: {
+        row: number;
+        col: number;
+    };
+}
+//# sourceMappingURL=trace-arrows.d.ts.map

package/dist/data/trace-arrows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-arrows.d.ts","sourceRoot":"","sources":["../../src/data/trace-arrows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,WAAW,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IAErB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,YAAY,EAAE,kBAAkB,CAAC;IAEjC;;;;OAIG;IACH,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IAE1C;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,IAAI,EAAE,cAAc,CAAC;IACrB,sBAAsB;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,sBAAsB;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,oDAAoD;IACpD,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C"}