@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/diagnostics/core.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Diagnostics Core Types - Unified framework for validating and tracing cell properties
+ *
+ * This file defines the core types for the Unified Diagnostics Framework, enabling:
+ * - Property resolution tracing (source → stored → computed)
+ * - Multi-domain validation (style, formula, value, etc.)
+ * - Mismatch detection between XLSX and stored state
+ * - Document diffing for import/export validation
+ *
+ */
+/**
+ * Cell coordinates (0-indexed row/col, shared across all domains).
+ * This is the minimal representation for identifying a cell within a sheet.
+ */
+export interface CellCoord {
+    /** Sheet identifier */
+    sheetId: string;
+    /** 0-indexed row number */
+    row: number;
+    /** 0-indexed column number */
+    col: number;
+}
+/**
+ * Extended cell reference with display metadata.
+ * Includes human-readable references and stable cell identity when available.
+ */
+export interface CellRef extends CellCoord {
+    /** Sheet name (for display) */
+    sheetName: string;
+    /** A1 notation (1-indexed, e.g., "C17") */
+    ref: string;
+    /** Stable cell identity if materialized (null if transient) */
+    cellId: string | null;
+}
+/**
+ * Severity level for diagnostic issues.
+ * - error: Critical mismatch requiring attention
+ * - warning: Non-critical difference or potential issue
+ * - info: Informational note about property resolution
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * Domain name for categorizing diagnostics.
+ * Each domain validates a specific aspect of cell properties.
+ */
+export type DiagnosticDomainName = 'style' | 'formula' | 'value' | 'validation' | 'conditionalFormat' | 'namedRange' | 'table' | 'pivot' | 'floating-object';
+/**
+ * Diagnostic issue describing a problem or observation.
+ * Generic structure applicable to all domains.
+ */
+export interface DiagnosticIssue {
+    /** Severity level (error/warning/info) */
+    severity: DiagnosticSeverity;
+    /** Domain that detected this issue */
+    domain: DiagnosticDomainName;
+    /** Specific property name (if applicable, e.g., 'backgroundColor') */
+    property?: string;
+    /** Machine-readable issue code (e.g., 'XLSX_STORED_MISMATCH') */
+    code: string;
+    /** Human-readable description */
+    message: string;
+    /** Source value (from XLSX or external source) */
+    sourceValue?: unknown;
+    /** Stored value (in Yjs) */
+    storedValue?: unknown;
+    /** Computed value (effective/resolved value) */
+    computedValue?: unknown;
+}
+/**
+ * Source of a resolved property value.
+ * Indicates where the property came from in the resolution cascade.
+ */
+export type ResolutionSource = 'cell' | 'row' | 'col' | 'table' | 'conditionalFormat' | 'default' | 'computed';
+/**
+ * Trace of how a property value was resolved.
+ * Documents the resolution cascade from various sources.
+ */
+export interface PropertyResolution<T = unknown> {
+    /** Property name (e.g., 'backgroundColor') */
+    property: string;
+    /** Resolved value */
+    value: T;
+    /** Where this value came from */
+    source: ResolutionSource;
+    /** ID of the source entity (cellId, rowId, tableId, etc.) */
+    sourceId?: string;
+    /** Priority level (higher = wins in cascade) */
+    priority?: number;
+}
+/**
+ * Complete diagnostic trace for a cell property.
+ * Generic type parameterized by domain-specific source/stored/computed types.
+ *
+ * @template TSource - Source data type (e.g., XLSX raw data)
+ * @template TStored - Stored data type (e.g., Yjs cell/row/col format)
+ * @template TComputed - Computed data type (e.g., effective resolved format)
+ */
+export interface DiagnosticTrace<TSource, TStored, TComputed> {
+    /** Cell being traced */
+    cell: CellRef;
+    /** Source data (XLSX, external) - null if not available */
+    source: TSource | null;
+    /** Stored data (Yjs) - null if not stored */
+    stored: TStored | null;
+    /** Computed/effective data (always present) */
+    computed: TComputed;
+    /** Resolution trace for each property */
+    resolution: PropertyResolution[];
+    /** Detected issues for this cell */
+    issues: DiagnosticIssue[];
+    /** Timestamp when trace was captured (ISO 8601) */
+    tracedAt: string;
+}
+/**
+ * Aggregate validation result across all cells and domains.
+ * Provides summary statistics and categorized issues.
+ */
+export interface ValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** Issue count by severity */
+    issueCount: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    /** All issues (flat list) */
+    issues: DiagnosticIssue[];
+    /** Issues grouped by cell (cell key -> issues) */
+    byCell: Map<string, DiagnosticIssue[]>;
+    /** Issues grouped by domain */
+    byDomain: Map<DiagnosticDomainName, DiagnosticIssue[]>;
+}
+/**
+ * Entry describing a difference between source and stored values.
+ * Used for import/export validation and reconciliation.
+ */
+export interface DiffEntry {
+    /** Cell with difference */
+    cell: CellRef;
+    /** Domain where difference was detected */
+    domain: DiagnosticDomainName;
+    /** Property name */
+    property: string;
+    /** Value from source (XLSX, external) */
+    sourceValue: unknown;
+    /** Value in storage (Yjs) */
+    storedValue: unknown;
+}
+/**
+ * Document diff result categorizing all differences.
+ * Distinguishes between modifications, missing data, and added data.
+ */
+export interface DocumentDiff {
+    /** Properties that differ between source and stored */
+    modified: DiffEntry[];
+    /** Properties in source but missing in stored */
+    missing: DiffEntry[];
+    /** Properties in stored but not in source */
+    added: DiffEntry[];
+}
+/**
+ * Interface for implementing domain-specific diagnostics.
+ * Each domain (style, formula, value, etc.) implements this interface.
+ *
+ * @template TSource - Source data type for this domain
+ * @template TStored - Stored data type for this domain
+ * @template TComputed - Computed data type for this domain
+ */
+export interface DiagnosticDomain<TSource, TStored, TComputed> {
+    /** Domain identifier */
+    readonly name: DiagnosticDomainName;
+    /**
+     * Capture source data for a cell (e.g., XLSX raw data).
+     * Returns null if source data is not available.
+     *
+     * @param ctx - Domain-specific context (XLSX workbook, external source, etc.)
+     * @returns Source data or null
+     */
+    captureSource(ctx: unknown): TSource | null;
+    /**
+     * Get stored data for a cell from Yjs.
+     * Returns null if no data is stored.
+     *
+     * @param ctx - Domain-specific context (Yjs doc, sheet state, etc.)
+     * @param cell - Cell coordinates
+     * @returns Stored data or null
+     */
+    getStored(ctx: unknown, cell: CellCoord): TStored | null | Promise<TStored | null>;
+    /**
+     * Get computed/effective data for a cell.
+     * This is the resolved value after applying all cascades.
+     * Always returns a value (uses defaults if necessary).
+     *
+     * @param ctx - Domain-specific context
+     * @param cell - Cell coordinates
+     * @returns Computed data
+     */
+    getComputed(ctx: unknown, cell: CellCoord): TComputed | Promise<TComputed>;
+    /**
+     * Resolve properties by tracing the resolution cascade.
+     * Documents where each property value came from.
+     *
+     * @param source - Source data
+     * @param stored - Stored data
+     * @param computed - Computed data
+     * @returns Property resolution trace
+     */
+    resolveProperties(source: TSource | null, stored: TStored | null, computed: TComputed): PropertyResolution[];
+    /**
+     * Detect issues by comparing source, stored, and computed values.
+     * Returns list of diagnostic issues for this cell.
+     *
+     * @param trace - Complete diagnostic trace
+     * @returns Detected issues
+     */
+    detectIssues(trace: DiagnosticTrace<TSource, TStored, TComputed>): DiagnosticIssue[];
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/diagnostics/core.d.ts.map

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

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Diagnostics - Unified framework for validating and tracing cell properties
+ *
+ * Barrel export for all diagnostics types.
+ *
+ */
+export * from './core';
+export * from './style';
+//# sourceMappingURL=index.d.ts.map

package/dist/diagnostics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/diagnostics/style.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Style Diagnostics Types - Domain-specific types for style validation
+ *
+ * This file defines types for the style domain of the Unified Diagnostics Framework.
+ * Enables tracing and validation of cell formatting from XLSX → Yjs → computed/effective.
+ *
+ */
+import type { CellFormat } from '../core';
+import type { CellCoord, DiagnosticTrace } from './core';
+/**
+ * Raw XLSX style data captured during import.
+ * Represents the low-level style information before resolution.
+ */
+export interface StyleSource {
+    /** XLSX style index (xf record reference) */
+    styleIndex: number | null;
+    /** Fill properties from XLSX */
+    fill: {
+        /** XLSX fill ID (cellXfs index) */
+        fillId: number | null;
+        /** Pattern type (solid, darkGray, etc.) */
+        patternType: string | null;
+        /** Foreground color (pattern color) */
+        fgColor: string | null;
+        /** Background color (behind pattern) */
+        bgColor: string | null;
+        /** Resolved color after theme/tint application */
+        resolved: string | null;
+    };
+    /** Font properties from XLSX */
+    font: {
+        /** XLSX font ID (font table index) */
+        fontId: number | null;
+        /** Font family name */
+        name: string | null;
+        /** Font size in points */
+        size: number | null;
+        /** Bold flag */
+        bold: boolean;
+        /** Italic flag */
+        italic: boolean;
+        /** Font color (may include theme reference) */
+        color: string | null;
+    };
+    /** Border properties from XLSX */
+    border: {
+        /** XLSX border ID (border table index) */
+        borderId: number | null;
+    };
+    /** Number format properties from XLSX */
+    numberFormat: {
+        /** XLSX number format ID */
+        numFmtId: number | null;
+        /** Number format code string */
+        formatCode: string | null;
+    };
+    /** Alignment properties from XLSX */
+    alignment: {
+        /** Horizontal alignment (left, center, right, etc.) */
+        horizontal: string | null;
+        /** Vertical alignment (top, middle, bottom, etc.) */
+        vertical: string | null;
+        /** Wrap text flag */
+        wrapText: boolean;
+    } | null;
+    /** Resolved CellFormat from XLSX (after theme/style resolution) */
+    resolvedFormat: CellFormat;
+}
+/**
+ * Stored style data from Yjs.
+ * Includes cell, row, and column format cascades.
+ */
+export interface StyleStored {
+    /** Cell-level format */
+    cell: {
+        /** Stable cell identity (null if transient) */
+        cellId: string | null;
+        /** Cell format (null if no cell-level format) */
+        format: CellFormat | null;
+    };
+    /** Row-level format */
+    row: {
+        /** Row identity */
+        rowId: string | null;
+        /** Row format (null if no row-level format) */
+        format: CellFormat | null;
+    };
+    /** Column-level format */
+    col: {
+        /** Column identity */
+        colId: string | null;
+        /** Column format (null if no column-level format) */
+        format: CellFormat | null;
+    };
+}
+/**
+ * Computed/effective style for a cell.
+ * This is the final resolved format after applying all cascades.
+ */
+export type StyleComputed = CellFormat;
+/**
+ * Style trace specialized for style domain.
+ * Type alias for readability.
+ */
+export type StyleTrace = DiagnosticTrace<StyleSource, StyleStored, StyleComputed>;
+/**
+ * Style mismatch entry describing a difference in a specific property.
+ * Used for detailed mismatch reporting.
+ */
+export interface StyleMismatch {
+    /** Cell with mismatch */
+    cell: CellCoord;
+    /** Format property with mismatch */
+    property: keyof CellFormat;
+    /** Value from XLSX */
+    xlsxValue: unknown;
+    /** Value stored in Yjs */
+    storedValue: unknown;
+    /** Computed/effective value */
+    computedValue: unknown;
+}
+/**
+ * API for style-specific diagnostic operations.
+ * Provides convenience methods for common style validation tasks.
+ */
+export interface StyleDiagnostics {
+    /**
+     * Trace a single cell's style resolution.
+     * Returns complete trace including source, stored, and computed data.
+     *
+     * @param cell - Cell coordinates or A1 reference
+     * @returns Style trace
+     */
+    traceCell(cell: CellCoord | string): StyleTrace | Promise<StyleTrace>;
+    /**
+     * Find all style mismatches between XLSX and stored data.
+     * Returns list of properties that differ.
+     *
+     * @returns Array of mismatches
+     */
+    findMismatches(): StyleMismatch[] | Promise<StyleMismatch[]>;
+    /**
+     * Find all cells with a specific XLSX style index.
+     * Useful for debugging style table issues.
+     *
+     * @param styleIndex - XLSX style index (xf record)
+     * @returns Cells using this style index
+     */
+    findByStyleIndex(styleIndex: number): CellCoord[];
+    /**
+     * Find all cells with a specific property value.
+     * Searches computed (effective) styles.
+     *
+     * @param property - Format property name
+     * @param value - Value to search for
+     * @returns Cells with matching property
+     */
+    findByProperty(property: keyof CellFormat, value: unknown): CellCoord[] | Promise<CellCoord[]>;
+    /**
+     * Find all cells with a specific fill color.
+     * Searches computed (effective) background colors.
+     *
+     * @param color - Color to search for (hex or theme reference)
+     * @returns Cells with matching fill
+     */
+    findByFill(color: string): CellCoord[] | Promise<CellCoord[]>;
+    /**
+     * Get all unique fill colors used in the sheet.
+     * Returns colors with usage counts and cell lists.
+     *
+     * @returns Array of unique fills with metadata
+     */
+    getUniqueFills(): Array<{
+        color: string;
+        count: number;
+        cells: CellCoord[];
+    }> | Promise<Array<{
+        color: string;
+        count: number;
+        cells: CellCoord[];
+    }>>;
+    /**
+     * Get all unique font configurations used in the sheet.
+     * Returns font properties with usage counts.
+     *
+     * @returns Array of unique fonts with counts
+     */
+    getUniqueFonts(): Array<{
+        font: Partial<CellFormat>;
+        count: number;
+    }> | Promise<Array<{
+        font: Partial<CellFormat>;
+        count: number;
+    }>>;
+}
+//# sourceMappingURL=style.d.ts.map

package/dist/diagnostics/style.d.ts.map

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

package/dist/document/comments.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Comments Types
+ *
+ * Defines the comment data model with threading support.
+ * Comments are first-class entities with their own identity, history, and threading.
+ *
+ * Key design decisions:
+ * - Comments reference cells via CellId (stable across structure changes)
+ * - Content is RichText for formatting support
+ * - Threading via parentId enables reply chains
+ * - NO sheetId stored - it's implicit from SheetMaps location (like merges.ts)
+ *
+ * @see STREAM-C3-COMMENTS-RICHTEXT.md
+ * @see docs/architecture/cell-identity.md
+ */
+import type { CellId } from '../cells/cell-identity';
+import type { RichText } from '../cells/rich-text';
+/**
+ * A comment attached to a cell.
+ *
+ * Design decisions:
+ * - Comments reference cells via CellId (stable across structure changes)
+ * - Content is RichText for formatting support
+ * - Threading via parentId enables reply chains
+ * - resolved flag supports review workflows
+ * - NO sheetId stored - it's implicit from SheetMaps location (like merges.ts)
+ *
+ * @example
+ * // Simple comment
+ * {
+ *   id: 'comment-123',
+ *   cellRef: 'cell-456',
+ *   author: 'Alice',
+ *   createdAt: 1704240000000,
+ *   content: [{ text: 'This looks correct' }],
+ *   threadId: 'comment-123' // First comment is its own thread root
+ * }
+ *
+ * @example
+ * // Reply to a comment
+ * {
+ *   id: 'comment-789',
+ *   cellRef: 'cell-456',
+ *   author: 'Bob',
+ *   createdAt: 1704240600000,
+ *   content: [{ text: 'Thanks for checking!' }],
+ *   threadId: 'comment-123', // Belongs to Alice's thread
+ *   parentId: 'comment-123'  // Direct reply to Alice
+ * }
+ */
+export interface Comment {
+    /** Unique identifier (UUID v7 for ordering) */
+    id: string;
+    /** Cell this comment is attached to (stable CellId, not position) */
+    cellRef: CellId;
+    /** Comment author display name */
+    author: string;
+    /** Author's user ID (for collaboration) */
+    authorId?: string;
+    /** Creation timestamp (Unix ms) */
+    createdAt: number;
+    /** Last modification timestamp */
+    modifiedAt?: number;
+    /** Rich text content */
+    content: RichText;
+    /**
+     * Thread ID for grouped comments.
+     * The first comment in a thread uses its own ID as threadId.
+     * Subsequent replies share the same threadId.
+     */
+    threadId?: string;
+    /** Parent comment ID for replies */
+    parentId?: string;
+    /** Whether the thread is resolved */
+    resolved?: boolean;
+}
+/**
+ * Legacy Excel "note" - simple text without threading.
+ * For backwards compatibility with Excel notes (not threaded comments).
+ *
+ * Excel has two concepts:
+ * - Notes: Simple text balloons (legacy, what Excel called "comments" pre-2019)
+ * - Comments: Threaded discussions (what Excel now calls "comments")
+ *
+ * We primarily use Comment (threaded) but support CellNote for import/export.
+ */
+export interface CellNote {
+    /** Note text content (plain text) */
+    text: string;
+    /** Author name (optional) */
+    author?: string;
+}
+/**
+ * Position for comment popover display.
+ * Managed by coordinator as side effect, not stored in machine context.
+ *
+ * Following the "Machine Owns State, Coordinator Owns Execution" principle:
+ * - Machine context stores targetCellId (what to show)
+ * - Coordinator calculates position from renderer state (where to show)
+ */
+export interface CommentPopoverPosition {
+    /** CellId the popover is anchored to */
+    cellId: CellId;
+    /** DOM rect of the anchor cell (for positioning calculations) */
+    anchorRect: DOMRect;
+    /** Preferred side for the popover */
+    preferredSide: 'right' | 'bottom';
+}
+//# sourceMappingURL=comments.d.ts.map

package/dist/document/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/document/comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,OAAO;IACtB,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IAEX,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAEhB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAElB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wBAAwB;IACxB,OAAO,EAAE,QAAQ,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IACpB,qCAAqC;IACrC,aAAa,EAAE,OAAO,GAAG,QAAQ,CAAC;CACnC"}