@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/core/core.d.ts

@@ -0,0 +1,943 @@
+/**
+ * Core spreadsheet contracts - shared types used across all packages
+ */
+/** Maximum rows in a sheet (Excel limit: 1,048,576) */
+export declare const MAX_ROWS = 1048576;
+/** Maximum columns in a sheet (Excel limit: 16,384 = XFD) */
+export declare const MAX_COLS = 16384;
+import type { FormulaA1 } from '../cells/formula-string';
+import type { RichText } from '../cells/rich-text';
+/**
+ * Primitive cell value types
+ */
+export type CellValuePrimitive = string | number | boolean | null;
+/**
+ * Cell value including error types.
+ * Used for computed/formula results and API output.
+ */
+export type CellValue = CellValuePrimitive | CellError;
+/**
+ * Raw cell input value types.
+ * Includes RichText for formatted literal text input.
+ * Formula results are never RichText - use CellValue for those.
+ *
+ * When converting from CellRawValue to CellValue, use:
+ * - `toPlainText()` from './rich-text' if value is RichText
+ * - Value as-is if it's a primitive
+ */
+export type CellRawValue = CellValuePrimitive | RichText;
+/**
+ * Machine-friendly variant names for Excel error types.
+ * Use `errorDisplayString()` to convert to the user-facing display string.
+ */
+export type ErrorVariant = 'Null' | 'Div0' | 'Value' | 'Ref' | 'Name' | 'Num' | 'Na' | 'GettingData' | 'Spill' | 'Calc' | 'Circ';
+/**
+ * Standard Excel error types
+ */
+export interface CellError {
+    type: 'error';
+    value: ErrorVariant;
+    message?: string;
+}
+/**
+ * Sheet identifier (opaque string)
+ */
+export type SheetId = string;
+/**
+ * Cell address reference
+ *
+ * NOTE: sheetId is REQUIRED to ensure explicit sheet context for all cell references.
+ * This enables proper cross-sheet formula handling and dependency tracking.
+ * If you need a cell reference without sheet context (within the active sheet),
+ * use { row, col } inline or create a local type.
+ */
+export interface CellAddress {
+    row: number;
+    col: number;
+    sheetId: string;
+}
+/**
+ * Cell range reference.
+ *
+ * This is THE canonical range type for ALL range operations in the spreadsheet.
+ * Uses flat format for simplicity and JSON compatibility.
+ *
+ * Used by: XState machines, canvas coordinates, React hooks, API, events, tables, pivots
+ */
+export interface CellRange {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+    /** True when entire column(s) selected via column header click */
+    isFullColumn?: boolean;
+    /** True when entire row(s) selected via row header click */
+    isFullRow?: boolean;
+    sheetId?: string;
+}
+/**
+ * Number format types
+ */
+export type NumberFormatType = 'general' | 'number' | 'currency' | 'accounting' | 'date' | 'time' | 'percentage' | 'fraction' | 'scientific' | 'text' | 'special' | 'custom';
+/**
+ * Excel pattern fill types.
+ *
+ * Excel supports 18 pattern types for cell backgrounds. These patterns
+ * combine a foreground color (the pattern) with a background color.
+ *
+ * Pattern visualization (8x8 pixels):
+ * - none: No fill (transparent)
+ * - solid: Solid fill (fgColor only)
+ * - darkGray/mediumGray/lightGray/gray125/gray0625: Dot density patterns
+ * - darkHorizontal/lightHorizontal: Horizontal stripe patterns
+ * - darkVertical/lightVertical: Vertical stripe patterns
+ * - darkDown/lightDown: Diagonal stripes (top-left to bottom-right)
+ * - darkUp/lightUp: Diagonal stripes (bottom-left to top-right)
+ * - darkGrid/lightGrid: Grid patterns (horizontal + vertical)
+ * - darkTrellis/lightTrellis: Cross-hatch patterns (both diagonals)
+ */
+export type PatternType = 'none' | 'solid' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray125' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+/**
+ * GradientStop — Core contracts layer. Maps to CT_GradientStop (dml-main.xsd:1539) with position + color for cell formatting.
+ */
+export interface GradientStop {
+    /**
+     * Position along the gradient (0.0 to 1.0).
+     * 0.0 = start of gradient, 1.0 = end of gradient.
+     */
+    position: number;
+    /**
+     * Color at this position.
+     * Can be absolute hex or theme reference.
+     */
+    color: string;
+}
+/**
+ * Gradient fill configuration.
+ *
+ * Excel supports two gradient types:
+ * - linear: Color transitions along a line at a specified angle
+ * - path: Color transitions radially from a center point
+ *
+ * Gradients require at least 2 stops (start and end colors).
+ */
+export interface GradientFill {
+    /**
+     * Type of gradient.
+     * - 'linear': Straight line gradient at specified degree
+     * - 'path': Radial/rectangular gradient from center point
+     */
+    type: 'linear' | 'path';
+    /**
+     * Angle of linear gradient in degrees (0-359).
+     * 0 = left-to-right, 90 = bottom-to-top, etc.
+     * Only used when type is 'linear'.
+     */
+    degree?: number;
+    /**
+     * Center point for path gradients (0.0 to 1.0 for each axis).
+     * { left: 0.5, top: 0.5 } = center of cell.
+     * Only used when type is 'path'.
+     */
+    center?: {
+        left: number;
+        top: number;
+    };
+    /**
+     * Gradient color stops.
+     * Must have at least 2 stops. Stops should be ordered by position.
+     */
+    stops: GradientStop[];
+}
+/**
+ * Cell formatting options
+ *
+ * This interface defines ALL Excel format properties that can be applied to cells.
+ * The implementation status of each property is tracked in format-registry.ts.
+ *
+ * @see FORMAT_PROPERTY_REGISTRY in format-registry.ts for implementation status
+ */
+export interface CellFormat {
+    numberFormat?: string;
+    numberFormatType?: NumberFormatType;
+    fontFamily?: string;
+    fontSize?: number;
+    /**
+     * Theme font reference for Excel-compatible "+Headings" / "+Body" fonts.
+     *
+     * When set, the cell uses the theme's majorFont (headings) or minorFont (body)
+     * instead of fontFamily. Theme fonts are resolved at render time, allowing cells
+     * to automatically update when the workbook theme changes.
+     *
+     * Behavior:
+     * - 'major': Uses theme.fonts.majorFont (e.g., 'Calibri Light' in Office theme)
+     * - 'minor': Uses theme.fonts.minorFont (e.g., 'Calibri' in Office theme)
+     * - undefined: Uses fontFamily property (or default font if not set)
+     *
+     * When fontTheme is set, fontFamily is ignored for rendering but may still be
+     * stored for fallback purposes. This matches Excel's behavior where "+Headings"
+     * cells can have a fontFamily that's used when the theme is unavailable.
+     *
+     * @see resolveThemeFonts in theme.ts for resolution
+     * @see ThemeFonts for theme font pair definition
+     */
+    fontTheme?: 'major' | 'minor';
+    /**
+     * Font color. Can be:
+     * - Absolute hex: '#4472c4' or '#ff0000'
+     * - Theme reference: 'theme:accent1' (uses current theme's accent1 color)
+     * - Theme with tint: 'theme:accent1:0.4' (40% lighter) or 'theme:accent1:-0.25' (25% darker)
+     *
+     * Theme references are resolved at render time via resolveThemeColors().
+     * This enables cells to automatically update when the workbook theme changes.
+     *
+     * @see resolveThemeColors in theme.ts for resolution
+     * @see ThemeColorSlot for valid slot names (dark1, light1, accent1-6, etc.)
+     */
+    fontColor?: string;
+    bold?: boolean;
+    italic?: boolean;
+    /**
+     * Underline type. Excel supports 4 underline styles:
+     * - 'none': No underline (default)
+     * - 'single': Standard underline under all characters
+     * - 'double': Two parallel lines under all characters
+     * - 'singleAccounting': Underline under text only (not spaces), for column alignment
+     * - 'doubleAccounting': Double underline under text only (not spaces), for column alignment
+     */
+    underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+    strikethrough?: boolean;
+    /**
+     * Superscript text (vertAlign = 'superscript' in Excel).
+     * Text is rendered smaller and raised above the baseline.
+     */
+    superscript?: boolean;
+    /**
+     * Subscript text (vertAlign = 'subscript' in Excel).
+     * Text is rendered smaller and lowered below the baseline.
+     */
+    subscript?: boolean;
+    /**
+     * Font outline effect.
+     * Draws only the outline of each character (hollow text).
+     * Rare in modern spreadsheets but supported by Excel.
+     */
+    fontOutline?: boolean;
+    /**
+     * Font shadow effect.
+     * Adds a shadow behind the text.
+     * Rare in modern spreadsheets but supported by Excel.
+     */
+    fontShadow?: boolean;
+    /**
+     * Horizontal text alignment.
+     * - 'general': Context-based (left for text, right for numbers) - Excel default
+     * - 'left': Left-align text
+     * - 'center': Center text
+     * - 'right': Right-align text
+     * - 'fill': Repeat content to fill cell width
+     * - 'justify': Justify text (distribute evenly)
+     * - 'centerContinuous': Center across selection without merging
+     * - 'distributed': Distribute text evenly with indent support
+     */
+    horizontalAlign?: 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
+    /**
+     * Vertical text alignment.
+     * - 'top': Align to top of cell
+     * - 'middle': Center vertically (also known as 'center')
+     * - 'bottom': Align to bottom of cell - Excel default
+     * - 'justify': Justify vertically (distribute lines evenly)
+     * - 'distributed': Distribute text evenly with vertical spacing
+     */
+    verticalAlign?: 'top' | 'middle' | 'bottom' | 'justify' | 'distributed';
+    wrapText?: boolean;
+    /**
+     * Text rotation angle in degrees.
+     * - 0-90: Counter-clockwise rotation
+     * - 91-180: Clockwise rotation (180 - value)
+     * - 255: Vertical text (stacked characters, read top-to-bottom)
+     */
+    textRotation?: number;
+    /**
+     * Indent level (0-15).
+     * Each level adds approximately 8 pixels of indent from the cell edge.
+     * Works with left and right horizontal alignment.
+     */
+    indent?: number;
+    /**
+     * Shrink text to fit cell width.
+     * Reduces font size to fit all text within the cell width.
+     * Mutually exclusive with wrapText in Excel behavior.
+     */
+    shrinkToFit?: boolean;
+    /**
+     * Text reading order for bidirectional text support.
+     * - 'context': Determined by first character with strong directionality
+     * - 'ltr': Left-to-right (forced)
+     * - 'rtl': Right-to-left (forced)
+     */
+    readingOrder?: 'context' | 'ltr' | 'rtl';
+    /**
+     * Background color. Can be:
+     * - Absolute hex: '#ffffff' or '#c6efce'
+     * - Theme reference: 'theme:accent1' (uses current theme's accent1 color)
+     * - Theme with tint: 'theme:accent1:0.4' (40% lighter) or 'theme:accent1:-0.25' (25% darker)
+     *
+     * Theme references are resolved at render time via resolveThemeColors().
+     * This enables cells to automatically update when the workbook theme changes.
+     *
+     * For solid fills, this is the only color needed.
+     * For pattern fills, this is the background color behind the pattern.
+     *
+     * @see resolveThemeColors in theme.ts for resolution
+     * @see ThemeColorSlot for valid slot names (dark1, light1, accent1-6, etc.)
+     */
+    backgroundColor?: string;
+    /**
+     * Pattern fill type.
+     * Excel supports 18 pattern types for cell backgrounds.
+     * When set (and not 'none' or 'solid'), the cell uses a pattern fill.
+     */
+    patternType?: PatternType;
+    /**
+     * Pattern foreground color.
+     * The color of the pattern itself (dots, lines, etc.).
+     * Only used when patternType is set to a non-solid pattern.
+     */
+    patternForegroundColor?: string;
+    /**
+     * Gradient fill configuration.
+     * When set, overrides backgroundColor and pattern fill.
+     * Excel supports linear and path (radial) gradients.
+     */
+    gradientFill?: GradientFill;
+    /** Cell borders (top, right, bottom, left, diagonal) */
+    borders?: CellBorders;
+    /**
+     * Cell is locked when sheet protection is enabled.
+     * Default is true in Excel (all cells locked by default).
+     * Only effective when the sheet's isProtected flag is true.
+     */
+    locked?: boolean;
+    /**
+     * Formula is hidden when sheet protection is enabled.
+     * When true, the cell's formula is not shown in the formula bar.
+     * The computed value is still displayed in the cell.
+     * Only effective when the sheet's isProtected flag is true.
+     */
+    hidden?: boolean;
+    /**
+     * Cell value is forced to text mode (apostrophe prefix).
+     * When true:
+     * - Raw value includes the leading apostrophe
+     * - Display value strips the apostrophe
+     * - Formula bar shows the apostrophe
+     * - Value is NOT coerced to date/number/etc.
+     *
+     * Set when user types ' as first character.
+     * Follows cell on sort/move (keyed by CellId, Cell Identity Model).
+     *
+     * @see plans/active/excel-parity/08-EDITING.md - Item 8.1
+     */
+    forcedTextMode?: boolean;
+    /**
+     * Arbitrary extension data for future features.
+     * Use namespaced keys: "myfeature.mykey"
+     * Example: { ignoreError: true } to suppress error indicators.
+     */
+    extensions?: Record<string, unknown>;
+}
+/** Dense cell format where every property is explicitly present (null when unset). Returned by formats.get(). */
+export type ResolvedCellFormat = {
+    [K in keyof CellFormat]-?: CellFormat[K] | null;
+};
+/**
+ * Border style.
+ *
+ * D3: Excel-compatible border styles. All 13 Excel border styles are supported:
+ * - Solid: 'thin', 'medium', 'thick' (varying line widths)
+ * - Dashed: 'dashed', 'mediumDashed' (varying dash lengths)
+ * - Dotted: 'dotted', 'hair' (dots and very fine lines)
+ * - Double: 'double' (two parallel lines)
+ * - Dash-dot combinations: 'dashDot', 'dashDotDot', 'mediumDashDot', 'mediumDashDotDot'
+ * - Special: 'slantDashDot' (slanted dash-dot pattern)
+ *
+ * @see cells-layer.ts getBorderDashPattern() for canvas rendering
+ * @see format-mapper.ts for XLSX import/export mapping
+ */
+export interface BorderStyle {
+    style: 'none' | 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'dashDotDot' | 'mediumDashDot' | 'mediumDashDotDot' | 'slantDashDot';
+    color?: string;
+}
+/**
+ * Cell borders
+ *
+ * ECMA-376 CT_Border: Full border specification for cells.
+ * Supports standard borders (top/right/bottom/left), diagonal borders,
+ * RTL equivalents (start/end), and internal borders for ranges (vertical/horizontal).
+ */
+export interface CellBorders {
+    top?: BorderStyle;
+    right?: BorderStyle;
+    bottom?: BorderStyle;
+    left?: BorderStyle;
+    diagonal?: BorderStyle & {
+        direction?: 'up' | 'down' | 'both';
+    };
+    /**
+     * Diagonal up flag (ECMA-376 CT_Border @diagonalUp).
+     * When true, diagonal line runs from bottom-left to top-right.
+     * Note: This is the spec-compliant representation. For convenience,
+     * diagonal.direction can also be used which derives from these flags.
+     */
+    diagonalUp?: boolean;
+    /**
+     * Diagonal down flag (ECMA-376 CT_Border @diagonalDown).
+     * When true, diagonal line runs from top-left to bottom-right.
+     * Note: This is the spec-compliant representation. For convenience,
+     * diagonal.direction can also be used which derives from these flags.
+     */
+    diagonalDown?: boolean;
+    /**
+     * RTL start border (maps to left in LTR, right in RTL).
+     * Used for bidirectional text support.
+     */
+    start?: BorderStyle;
+    /**
+     * RTL end border (maps to right in LTR, left in RTL).
+     * Used for bidirectional text support.
+     */
+    end?: BorderStyle;
+    /**
+     * Internal vertical border (between cells in a range).
+     * Only meaningful when applied to a range of cells.
+     */
+    vertical?: BorderStyle;
+    /**
+     * Internal horizontal border (between cells in a range).
+     * Only meaningful when applied to a range of cells.
+     */
+    horizontal?: BorderStyle;
+    /**
+     * Outline mode flag.
+     * When true, borders are applied as outline around the range.
+     * When false/undefined, borders apply to individual cells.
+     */
+    outline?: boolean;
+}
+/**
+ * Complete cell data
+ */
+export interface CellData {
+    value: CellValue;
+    formula?: FormulaA1;
+    format?: CellFormat;
+    borders?: CellBorders;
+    comment?: string;
+    hyperlink?: string;
+    /** Pre-formatted display string from Rust (e.g., "$1,234.50", "1/1/2024"). */
+    formatted?: string;
+}
+/**
+ * Style category for grouping styles in the UI gallery.
+ */
+export type StyleCategory = 'good-bad-neutral' | 'data-model' | 'titles-headings' | 'themed' | 'number-format' | 'custom';
+/**
+ * Named cell style that can be applied to cells.
+ *
+ * Styles are a named collection of formatting properties. When applied,
+ * the format values are copied to cells (not referenced by ID). This
+ * matches Excel behavior where style changes don't affect already-styled cells.
+ *
+ * Built-in styles are defined in code and never persisted.
+ * Custom styles are stored in Yjs for collaboration.
+ */
+export interface CellStyle {
+    /** Unique identifier (e.g., 'good', 'heading1', 'custom-abc123') */
+    id: string;
+    /** Display name shown in UI (e.g., 'Good', 'Heading 1') */
+    name: string;
+    /** Category for UI grouping */
+    category: StyleCategory;
+    /** The formatting properties to apply */
+    format: CellFormat;
+    /** True for built-in styles, false for user-created */
+    builtIn: boolean;
+}
+/**
+ * Sheet metadata
+ */
+export interface SheetInfo {
+    id: string;
+    name: string;
+    index: number;
+    hidden?: boolean;
+    tabColor?: string;
+}
+/**
+ * Per-sheet view options (persisted in Yjs).
+ * Stream F: Freeze Panes & View Options
+ */
+export interface SheetViewOptions {
+    /** Whether gridlines are visible (default: true) */
+    showGridlines: boolean;
+    /** Whether row headers (1, 2, 3...) are visible (default: true) */
+    showRowHeaders: boolean;
+    /** Whether column headers (A, B, C...) are visible (default: true) */
+    showColumnHeaders: boolean;
+    /** Whether the sheet is displayed right-to-left (default: false) */
+    rightToLeft: boolean;
+    /** Whether to display formulas instead of computed values (default: false) */
+    showFormulas: boolean;
+    /** Whether to display zero values (default: true, matching Excel) */
+    showZeros: boolean;
+    /** Zoom scale percentage, or undefined for default (100%) */
+    zoomScale?: number;
+}
+/**
+ * Direction for enter key movement after committing an edit.
+ * Issue 8: Settings Panel
+ */
+export type EnterKeyDirection = 'down' | 'right' | 'up' | 'left' | 'none';
+/**
+ * Calculation settings for the workbook.
+ * G.3: Supports iterative calculation for circular references.
+ *
+ * Excel allows formulas with circular references to calculate iteratively
+ * until they converge or reach the maximum iterations. When disabled (default),
+ * circular references result in #CALC! errors.
+ *
+ * @see plans/active/excel-parity/04-EDITING-BEHAVIORS-PLAN.md - G.3
+ */
+/** Calculation mode — when the engine recalculates formulas. */
+export type CalcMode = 'auto' | 'autoNoTable' | 'manual';
+export interface CalculationSettings {
+    /**
+     * Whether to allow iterative calculation for circular references.
+     * When true, formulas with circular references calculate iteratively.
+     * When false (default), circular references show #CALC! error.
+     */
+    enableIterativeCalculation: boolean;
+    /**
+     * Maximum number of iterations for iterative calculation.
+     * Excel default: 100
+     */
+    maxIterations: number;
+    /**
+     * Maximum change between iterations for convergence.
+     * Calculation stops when all results change by less than this amount.
+     * Excel default: 0.001
+     */
+    maxChange: number;
+    /**
+     * Calculation mode (auto/manual/autoNoTable).
+     * Default: 'auto'
+     */
+    calcMode: CalcMode;
+    /**
+     * Whether to use full (15-digit) precision for calculations.
+     * Default: true
+     */
+    fullPrecision: boolean;
+    /**
+     * Cell reference style (true = R1C1, false = A1).
+     * Default: false
+     */
+    r1c1Mode: boolean;
+    /**
+     * Whether to perform a full calculation when the file is opened.
+     * Default: false
+     */
+    fullCalcOnLoad: boolean;
+}
+/**
+ * Workbook-level settings (persisted in Yjs workbook metadata).
+ * These apply globally to the entire workbook, not per-sheet.
+ * Stream L: Settings & Toggles
+ */
+export interface WorkbookSettings {
+    /** Whether horizontal scrollbar is visible (default: true) */
+    showHorizontalScrollbar: boolean;
+    /** Whether vertical scrollbar is visible (default: true) */
+    showVerticalScrollbar: boolean;
+    /**
+     * Whether scrollbars auto-hide when not scrolling (default: false).
+     * When true, scrollbars fade out after scroll ends and reappear on hover or scroll.
+     * Plan 09 Group 7.2: Auto-Hide Scroll Bars
+     */
+    autoHideScrollBars: boolean;
+    /** Whether the tab strip is visible (default: true) */
+    showTabStrip: boolean;
+    /** Whether sheets can be reordered by dragging (default: true) */
+    allowSheetReorder: boolean;
+    /** Whether the formula bar is visible (default: true) */
+    showFormulaBar: boolean;
+    /** Whether to auto-fit column width on header double-click (default: true) */
+    autoFitOnDoubleClick: boolean;
+    /**
+     * ID of active theme.
+     * Built-in theme IDs: 'office', 'slice', 'vapor-trail', etc.
+     * Use 'custom' to indicate a custom theme is stored in customTheme.
+     * Issue 4: Page Layout - Themes
+     */
+    themeId: string;
+    /**
+     * Override for theme fonts. When set, uses this font theme instead
+     * of the fonts from the selected theme.
+     * Built-in font theme IDs: 'office', 'arial', 'times', 'calibri', etc.
+     * undefined means use fonts from themeId.
+     *
+     * Plan 12: Fonts/Typography - Theme Font UI
+     */
+    themeFontsId?: string;
+    /**
+     * Locale/culture for number, date, and currency formatting.
+     * Uses IETF language tags: 'en-US', 'de-DE', 'ja-JP', etc.
+     * Default: 'en-US'
+     *
+     * This affects:
+     * - Decimal and thousands separators (1,234.56 vs 1.234,56)
+     * - Currency symbol position ($100 vs 100 €)
+     * - Date format patterns (MM/DD/YYYY vs DD.MM.YYYY)
+     * - Month and day name translations
+     * - AM/PM designators
+     *
+     * Stream G: Culture & Localization
+     */
+    culture: string;
+    /** Whether to show cut/copy indicator (marching ants). Default: true */
+    showCutCopyIndicator: boolean;
+    /** Whether fill handle dragging is enabled. Default: true */
+    allowDragFill: boolean;
+    /** Direction to move after pressing Enter. Default: 'down' */
+    enterKeyDirection: EnterKeyDirection;
+    /** Whether cell drag-and-drop to move cells is enabled. Default: false (not yet implemented) */
+    allowCellDragDrop: boolean;
+    /**
+     * Currently selected sheet IDs for multi-sheet operations.
+     * Default: undefined (falls back to [activeSheetId])
+     *
+     * This is collaborative state - other users can see which sheets you have selected.
+     * Used for operations that broadcast to multiple sheets (formatting, structure changes).
+     *
+     * When multiple sheets are selected:
+     * - Formatting operations apply to all selected sheets
+     * - Structure operations (insert/delete rows/cols) apply to all selected sheets
+     * - The active sheet is always included in the selection
+     */
+    selectedSheetIds?: string[];
+    /**
+     * Whether the workbook structure is protected.
+     * When true, prevents adding, deleting, renaming, hiding, unhiding, or moving sheets.
+     * Default: false
+     *
+     * Plan 08: Dialogs - Task 4 (Protect Workbook Dialog)
+     */
+    isWorkbookProtected?: boolean;
+    /**
+     * Hashed protection password for workbook (optional).
+     * Uses Excel-compatible XOR hash algorithm for round-trip compatibility.
+     * Empty string or undefined means no password protection.
+     */
+    workbookProtectionPasswordHash?: string;
+    /**
+     * Workbook protection options (what operations are prevented).
+     * Only relevant when isWorkbookProtected is true.
+     * If not set, defaults to DEFAULT_WORKBOOK_PROTECTION_OPTIONS.
+     * @see WorkbookProtectionOptions in protection.ts
+     */
+    workbookProtectionOptions?: import('../document/protection').WorkbookProtectionOptions;
+    /**
+     * Calculation settings including iterative calculation for circular references.
+     * If not set, defaults to DEFAULT_CALCULATION_SETTINGS.
+     *
+     * @see plans/active/excel-parity/04-EDITING-BEHAVIORS-PLAN.md - G.3
+     */
+    calculationSettings?: CalculationSettings;
+    /**
+     * Whether the workbook uses the 1904 date system (affects all date calculations).
+     * Default: false (1900 date system).
+     */
+    date1904?: boolean;
+    /**
+     * Default table style ID for new tables created in this workbook.
+     * Can be a built-in style preset name (e.g., 'medium2', 'dark1')
+     * or a custom style ID (e.g., 'custom-abc123').
+     *
+     * When undefined, new tables use the 'medium2' preset by default.
+     *
+     * Plan 15: Tables Excel Parity - P1-8 (Set as default style)
+     */
+    defaultTableStyleId?: string;
+}
+/**
+ * Default workbook settings.
+ * Stream L: Settings & Toggles
+ *
+ * SCHEMA-DRIVEN: Defaults are derived from WORKBOOK_SETTINGS_SCHEMA.
+ * @see store/workbook-schema.ts for the single source of truth.
+ */
+/**
+ * Extended sheet settings (persisted in Yjs sheet metadata).
+ * Extends SheetViewOptions with additional per-sheet configuration.
+ * Stream L: Settings & Toggles
+ */
+export interface SheetSettings extends SheetViewOptions {
+    /** Whether the sheet is protected (default: false) */
+    isProtected: boolean;
+    /** Hashed protection password (optional, empty string if no password) */
+    protectionPasswordHash?: string;
+    /**
+     * Granular protection options (what operations are allowed when protected).
+     * Only relevant when isProtected is true.
+     * If not set, defaults to DEFAULT_PROTECTION_OPTIONS.
+     * @see SheetProtectionOptions in protection.ts
+     */
+    protectionOptions?: import('../document/protection').SheetProtectionOptions;
+    /** Whether to show zero values or display blank (default: true) */
+    showZeroValues: boolean;
+    /** Gridline color (default: '#e2e2e2') */
+    gridlineColor: string;
+    /** Right-to-left layout (default: false) */
+    rightToLeft: boolean;
+    /** Default row height for new rows in pixels (default: 21) */
+    defaultRowHeight: number;
+    /** Default column width for new columns in pixels (default: 100) */
+    defaultColWidth: number;
+}
+/**
+ * Paper size type for print settings
+ */
+export type PaperSize = 'letter' | 'legal' | 'a4' | 'a3' | 'custom';
+/**
+ * Page orientation type for print settings
+ */
+export type PageOrientation = 'portrait' | 'landscape';
+/**
+ * Page margins in inches.
+ * Full OOXML representation including header/footer margins.
+ */
+export interface PageMargins {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    header: number;
+    footer: number;
+}
+/**
+ * Header/footer configuration (OOXML CT_HeaderFooter).
+ */
+export interface HeaderFooter {
+    oddHeader: string | null;
+    oddFooter: string | null;
+    evenHeader: string | null;
+    evenFooter: string | null;
+    firstHeader: string | null;
+    firstFooter: string | null;
+    differentOddEven: boolean;
+    differentFirst: boolean;
+    scaleWithDoc: boolean;
+    alignWithMargins: boolean;
+}
+/**
+ * Full print settings for a sheet, matching the Rust domain-types canonical type.
+ *
+ * Replaces the old lossy SheetPrintSettings. All fields are nullable where the
+ * underlying OOXML attribute is optional, using `null` to mean "not set / use default".
+ *
+ * Distinct from PrintOptions (runtime-only configuration in print-export).
+ */
+export interface PrintSettings {
+    /** OOXML paper size code (1=Letter, 9=A4, etc.), null = not set */
+    paperSize: number | null;
+    /** Page orientation, null = not set (defaults to portrait) */
+    orientation: string | null;
+    /** Scale percentage (10-400), null = not set */
+    scale: number | null;
+    /** Fit to N pages wide, null = not set */
+    fitToWidth: number | null;
+    /** Fit to N pages tall, null = not set */
+    fitToHeight: number | null;
+    /** Print cell gridlines */
+    gridlines: boolean;
+    /** Print row/column headings */
+    headings: boolean;
+    /** Center content horizontally on page */
+    hCentered: boolean;
+    /** Center content vertically on page */
+    vCentered: boolean;
+    /** Page margins in inches (with header/footer margins) */
+    margins: PageMargins | null;
+    /** Header/footer configuration */
+    headerFooter: HeaderFooter | null;
+    /** Print in black and white */
+    blackAndWhite: boolean;
+    /** Draft quality */
+    draft: boolean;
+    /** First page number override, null = auto */
+    firstPageNumber: number | null;
+    /** Page order: "downThenOver" or "overThenDown", null = default */
+    pageOrder: string | null;
+    /** Use printer defaults */
+    usePrinterDefaults: boolean | null;
+    /** Horizontal DPI, null = not set */
+    horizontalDpi: number | null;
+    /** Vertical DPI, null = not set */
+    verticalDpi: number | null;
+    /** Relationship ID for printer settings binary, null = not set */
+    rId: string | null;
+    /** Whether the sheet had printOptions element in OOXML */
+    hasPrintOptions: boolean;
+    /** Whether the sheet had pageSetup element in OOXML */
+    hasPageSetup: boolean;
+    /** Whether to use firstPageNumber (vs auto) */
+    useFirstPageNumber: boolean;
+    /** How to print cell comments: "none" | "atEnd" | "asDisplayed", null = not set (defaults to none) */
+    printComments: string | null;
+    /** How to print cell errors: "displayed" | "blank" | "dash" | "NA", null = not set (defaults to displayed) */
+    printErrors: string | null;
+}
+/** @deprecated Use PrintSettings instead */
+export type SheetPrintSettings = PrintSettings;
+/**
+ * Column metadata
+ */
+export interface ColumnInfo {
+    index: number;
+    width: number;
+    hidden?: boolean;
+    format?: CellFormat;
+}
+/**
+ * Row metadata
+ */
+export interface RowInfo {
+    index: number;
+    height: number;
+    hidden?: boolean;
+    format?: CellFormat;
+}
+/**
+ * Data type detection result
+ */
+export type DetectedDataType = 'string' | 'number' | 'date' | 'boolean' | 'empty' | 'error';
+/**
+ * Utility type for 2D data arrays
+ */
+export type DataMatrix<T = CellValue> = T[][];
+/**
+ * Read-only data provider interface
+ */
+export interface IDataProvider {
+    getCellValue(address: CellAddress): CellValue;
+    getCellData(address: CellAddress): CellData | undefined;
+    getRangeValues(range: CellRange): DataMatrix;
+    getSheetInfo(sheetId: string): SheetInfo | undefined;
+    getSheetIds(): string[];
+}
+/**
+ * How a cell's value was set
+ */
+export interface CellDataSource {
+    /** How the value was entered */
+    type: 'manual' | 'import' | 'api' | 'formula' | 'remote-link';
+    /** Additional context (file name, API endpoint, formula address, etc.) */
+    source?: string;
+}
+/**
+ * Validation error for a cell
+ */
+export interface ValidationError {
+    /** Rule ID that failed (e.g., "type:number", "constraint:positive") */
+    rule: string;
+    /** Human-readable error message */
+    message: string;
+    /** Error blocks save; warning just displays */
+    severity: 'error' | 'warning';
+}
+/**
+ * Metadata attached to individual cells.
+ * Stored in a separate Yjs map for sparse, efficient storage.
+ */
+export interface CellMetadata {
+    /** User ID who last modified this cell */
+    modifiedBy?: string;
+    /** Timestamp of last modification (Unix ms) */
+    modifiedAt?: number;
+    /** How this cell's value was set */
+    dataSource?: CellDataSource;
+    /** Type validation or assertion errors */
+    validationErrors?: ValidationError[];
+    /** ID of external data connection, if any */
+    connectionId?: string;
+    /** Whether connected data is current */
+    staleness?: 'fresh' | 'stale' | 'error';
+    /** When data was last fetched from source */
+    lastFetched?: number;
+    /**
+     * Whether this cell contains an array formula (CSE - Ctrl+Shift+Enter).
+     * When true, the formula bar displays the formula with curly braces: {=FORMULA}
+     * The formula itself is stored without braces in cells.raw - this is display metadata only.
+     */
+    isArrayFormula?: boolean;
+    /**
+     * Arbitrary extension data for future features.
+     * Use namespaced keys: "myfeature.mykey"
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * All non-computational properties of a cell.
+ *
+ * This unified type merges visual formatting (CellFormat) with metadata
+ * (provenance, validation, connections) into a single structure. This enables:
+ * - Single Yjs map for all non-computational data
+ * - Unified observer for reactivity
+ * - Clear mental model: cells = computation, properties = everything else
+ *
+ * Stored in a single Yjs map for unified reactivity.
+ */
+export interface CellProperties {
+    /** Cell formatting (font, colors, alignment, etc.) */
+    format?: CellFormat;
+    /** User ID who last modified this cell */
+    modifiedBy?: string;
+    /** Timestamp of last modification (Unix ms) */
+    modifiedAt?: number;
+    /** How this cell's value was set */
+    dataSource?: CellDataSource;
+    /** Type validation or assertion errors */
+    validationErrors?: ValidationError[];
+    /** ID of external data connection, if any */
+    connectionId?: string;
+    /** Whether connected data is current */
+    staleness?: 'fresh' | 'stale' | 'error';
+    /** When data was last fetched from source */
+    lastFetched?: number;
+    /**
+     * Whether this cell contains an array formula (CSE - Ctrl+Shift+Enter).
+     * When true, the formula bar displays the formula with curly braces: {=FORMULA}
+     * The formula itself is stored without braces in cells.raw - this is display metadata only.
+     */
+    isArrayFormula?: boolean;
+    /**
+     * Arbitrary extension data for future features.
+     * Use namespaced keys: "myfeature.mykey"
+     */
+    extensions?: Record<string, unknown>;
+}
+declare const __formattedText: unique symbol;
+/**
+ * Opaque branded type for pre-formatted display text.
+ * NOT assignable to `string` — forces consumers to either:
+ * - Use `.value` for semantic data (correct for logic)
+ * - Call `displayString()` to explicitly unwrap (correct for rendering)
+ */
+export interface FormattedText {
+    readonly [__formattedText]: true;
+    /** @deprecated FormattedText is not a string. Use displayString() or .value instead. */
+    toString(): string;
+}
+export {};
+//# sourceMappingURL=core.d.ts.map