@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/data/filter.d.ts

@@ -0,0 +1,364 @@
+/**
+ * Filter Contracts - Type definitions for spreadsheet filtering.
+ *
+ * Layer 0: Filter State Foundation (Cell Identity Model)
+ *
+ * This module defines the filter state schema and interfaces for
+ * AutoFilter, Table Filters, and Advanced Filters. The filter system
+ * uses a bridge pattern: filter criteria determines which rows should
+ * be hidden, but actual visibility is controlled by the existing
+ * hiddenRows infrastructure.
+ *
+ * ARCHITECTURE (Cell Identity Model):
+ *
+ * Filter ranges are defined by CellId corner references, NOT position-based
+ * CellRange. This follows the same pattern as:
+ * - IdentityRangeRef (formulas)
+ * - IdentityRangeSchemaRef (data validation)
+ * - IdentityMergedRegion (merged cells)
+ *
+ * Why CellId-based?
+ * - Survives row/col insert/delete (positions change, CellIds stable)
+ * - CRDT-safe for concurrent structure changes
+ * - Matches the Cell Identity Model used throughout the codebase
+ *
+ * Bridge pattern:
+ *   FilterState (CellId-based) → Resolve Positions → Evaluate → hideRows() → hiddenRows → Render
+ *
+ * Single source of truth:
+ *   - Row visibility: hiddenRows Y.Array<number> (position-based, transient render state)
+ *   - Filter state: filters Y.Map<FilterState> (CellId-based, durable definition)
+ *
+ * @see docs/architecture/cell-identity.md
+ */
+import type { CellId } from '../cells/cell-identity';
+import type { CellRange, CellValue } from '../core/core';
+import type { FilterOperator } from './pivot';
+export type { FilterOperator } from './pivot';
+/**
+ * Filter type discriminator.
+ *
+ * - autoFilter: Range filter with dropdown headers (Data > Filter)
+ * - tableFilter: Filter associated with an Excel table
+ * - advancedFilter: Complex criteria-based filter (future)
+ */
+export type FilterType = 'autoFilter' | 'tableFilter' | 'advancedFilter';
+/**
+ * A single filter condition with operator and value(s).
+ *
+ * Used in condition filters where users specify rules like
+ * "greater than 100" or "contains 'error'".
+ */
+export interface FilterCondition {
+    /** The comparison operator */
+    operator: FilterOperator;
+    /** Primary comparison value (not used for isBlank/isNotBlank) */
+    value?: CellValue;
+    /** Secondary value for 'between' operator (inclusive range) */
+    value2?: CellValue;
+}
+/**
+ * Column filter criteria - what's applied to a single column.
+ *
+ * Each column in a filter range can have its own criteria.
+ * Rows must match ALL column filters (AND logic across columns).
+ */
+export interface ColumnFilterCriteria {
+    /**
+     * Type of filter applied to this column.
+     *
+     * - value: Checkbox list of specific values to include
+     * - condition: Operator-based rules (equals, contains, etc.)
+     * - color: Filter by cell background or font color
+     * - top10: Top/bottom N items or percent
+     */
+    type: 'value' | 'condition' | 'color' | 'top10';
+    /**
+     * For value filters: list of values to INCLUDE (show).
+     * Unchecked values in the dropdown are excluded (hidden).
+     * Include empty string or null to show blank cells.
+     */
+    values?: CellValue[];
+    /**
+     * For condition filters: one or two filter conditions.
+     * When two conditions are present, conditionLogic determines how they combine.
+     */
+    conditions?: FilterCondition[];
+    /**
+     * Logic for combining multiple conditions.
+     * - 'and': Row must match ALL conditions
+     * - 'or': Row must match ANY condition
+     * Default: 'and'
+     */
+    conditionLogic?: 'and' | 'or';
+    /**
+     * For color filters: filter by background or font color.
+     */
+    colorFilter?: {
+        /** Whether to filter by background fill or font color */
+        type: 'background' | 'font';
+        /** Hex color to match (e.g., '#ff0000') */
+        color: string;
+    };
+    /**
+     * For top/bottom N filters: show only the highest or lowest values.
+     */
+    topBottom?: {
+        /** Show top values or bottom values */
+        type: 'top' | 'bottom';
+        /** Number of items or percentage */
+        count: number;
+        /** Whether count is number of items or percentage */
+        by: 'items' | 'percent';
+    };
+}
+/**
+ * Sort configuration for a filter.
+ *
+ * Filters often include sort controls in their dropdown menus.
+ * This tracks the current sort state applied via the filter.
+ *
+ * Cell Identity Model: Uses CellId for the sorted column header, not column index.
+ */
+export interface FilterSortState {
+    /**
+     * CellId of the header cell being sorted.
+     * Using CellId ensures the sort follows the column on insert/delete.
+     */
+    columnCellId: CellId;
+    /** Sort direction */
+    order: 'asc' | 'desc';
+    /** What to sort by */
+    sortBy: 'value' | 'color' | 'icon';
+}
+/**
+ * Complete filter state for a range - Cell Identity Model.
+ *
+ * ARCHITECTURE: Filter ranges are defined by CellId corner references,
+ * NOT position-based CellRange. This follows the same pattern as:
+ * - IdentityRangeRef (formulas)
+ * - IdentityRangeSchemaRef (data validation)
+ * - IdentityMergedRegion (merged cells)
+ *
+ * Why CellId-based?
+ * - Survives row/col insert/delete (positions change, CellIds stable)
+ * - CRDT-safe for concurrent structure changes
+ * - Matches the Cell Identity Model used throughout the codebase
+ *
+ * This is the persisted state in Yjs. It includes:
+ * - Corner cell CellIds that define the filter range
+ * - Per-column filter criteria keyed by header CellId
+ * - Optional sort state (also by CellId)
+ * - Optional table association
+ */
+export interface FilterState {
+    /** Unique filter identifier (UUID v7) */
+    id: string;
+    /** Filter type discriminator */
+    type: FilterType;
+    /**
+     * CellId of the header row, first column (top-left of header).
+     * Example: If filter is on A1:C10, this is the CellId of A1.
+     */
+    headerStartCellId: CellId;
+    /**
+     * CellId of the header row, last column (top-right of header).
+     * Example: If filter is on A1:C10, this is the CellId of C1.
+     */
+    headerEndCellId: CellId;
+    /**
+     * CellId of the last data row, first column (defines data extent).
+     * Example: If filter is on A1:C10 (header A1:C1, data A2:C10), this is CellId of A10.
+     *
+     * Why first column? We only need to track row extent, and the column extent
+     * is already defined by headerEndCellId. Using first column is simpler.
+     */
+    dataEndCellId: CellId;
+    /**
+     * Per-column filter criteria, keyed by header cell CellId.
+     *
+     * Why CellId key (not column index)?
+     * - Column index changes on insert/delete column
+     * - CellId is stable - filter criteria follows the column
+     *
+     * Example: If column B has a filter and user inserts column at A,
+     * B becomes C but the filter criteria stays with the same CellId.
+     *
+     * Empty object means no filters are applied (show all rows).
+     */
+    columnFilters: Record<CellId, ColumnFilterCriteria>;
+    /** Current sort state applied via this filter (optional) */
+    sortState?: FilterSortState;
+    /** Associated table ID for tableFilter type (optional) */
+    tableId?: string;
+    /** When this filter was created (Unix ms) */
+    createdAt?: number;
+    /** When this filter was last modified (Unix ms) */
+    updatedAt?: number;
+}
+/**
+ * Information about a filter header cell for UI rendering.
+ *
+ * Returned by getFilterHeaderInfo() to tell the renderer whether a cell
+ * is an AutoFilter header and should show a filter dropdown button.
+ *
+ * NOTE: Table filters use a separate code path via getTableAtCell().
+ * This type is specifically for AutoFilter (non-table filters).
+ */
+export interface FilterHeaderInfo {
+    /**
+     * The filter state ID - used to open the dropdown and apply criteria.
+     */
+    filterId: string;
+    /**
+     * CellId of this header cell (NOT column index!).
+     * Used as the key for column filter operations in Layer 0.
+     */
+    headerCellId: CellId;
+    /**
+     * Whether this column has active filter criteria applied.
+     * If true, the dropdown button shows a filter indicator.
+     */
+    hasActiveFilter: boolean;
+}
+/**
+ * Result of evaluating a filter against a single row.
+ *
+ * Used internally by the filter engine to determine which rows
+ * should be hidden or shown.
+ */
+export interface FilterEvaluationResult {
+    /** Row index (0-based absolute row in sheet) */
+    row: number;
+    /** Whether the row matches all active filter criteria */
+    matches: boolean;
+}
+/**
+ * Interface for filter CRUD operations.
+ *
+ * Implemented by the filter operations module in the engine.
+ * All operations go through the coordinator pattern.
+ *
+ * ARCHITECTURE: Column operations use CellId (header cell) instead of column index.
+ * This ensures filter criteria follows columns on insert/delete operations.
+ */
+export interface IFilterManager {
+    /**
+     * Create a new filter for a range.
+     *
+     * ARCHITECTURE: Accepts position-based CellRange for convenience (API), but
+     * internally stores CellId references. This is the same pattern as formula
+     * parsing - user types A1:C10, we store CellIds.
+     *
+     * @param sheetId - Sheet to create filter in
+     * @param range - Range to filter (header row + data rows)
+     * @param type - Filter type (default: 'autoFilter')
+     * @returns The created filter state (with CellId references)
+     */
+    createFilter(sheetId: string, range: CellRange, type?: FilterType): FilterState;
+    /**
+     * Get a filter by ID.
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     * @returns Filter state or undefined if not found
+     */
+    getFilter(sheetId: string, filterId: string): FilterState | undefined;
+    /**
+     * Get filter that contains a specific range (for overlap detection).
+     *
+     * @param sheetId - Sheet to search
+     * @param range - Range to check for filter containment
+     * @returns Filter state or undefined if no filter contains the range
+     */
+    getFilterForRange(sheetId: string, range: CellRange): FilterState | undefined;
+    /**
+     * Get all filters in a sheet.
+     *
+     * @param sheetId - Sheet to get filters from
+     * @returns Array of filter states
+     */
+    getFiltersInSheet(sheetId: string): FilterState[];
+    /**
+     * Delete a filter (removes filter state, does NOT unhide rows).
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID to delete
+     */
+    deleteFilter(sheetId: string, filterId: string): void;
+    /**
+     * Set filter criteria for a specific column.
+     *
+     * ARCHITECTURE: Uses header CellId instead of column index for CRDT safety.
+     * The filter criteria follows the column on insert/delete operations.
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     * @param headerCellId - CellId of the header cell (NOT column index)
+     * @param criteria - Filter criteria to apply
+     */
+    setColumnFilter(sheetId: string, filterId: string, headerCellId: CellId, criteria: ColumnFilterCriteria): void;
+    /**
+     * Clear filter criteria for a specific column.
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     * @param headerCellId - CellId of the header cell (NOT column index)
+     */
+    clearColumnFilter(sheetId: string, filterId: string, headerCellId: CellId): void;
+    /**
+     * Clear all column filters (show all rows).
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     */
+    clearAllColumnFilters(sheetId: string, filterId: string): void;
+    /**
+     * Evaluate filter criteria against data rows.
+     *
+     * Returns which rows match/don't match without hiding anything.
+     * Useful for preview or debugging.
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     * @returns Array of evaluation results for each data row
+     */
+    evaluateFilter(sheetId: string, filterId: string): FilterEvaluationResult[];
+    /**
+     * Apply filter: evaluate criteria and hide/unhide rows.
+     *
+     * This is THE BRIDGE: resolves CellIds to positions, evaluates criteria,
+     * then calls hideRows()/unhideRows() based on filter results.
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     */
+    applyFilter(sheetId: string, filterId: string): void;
+    /**
+     * Sort data by a filter column.
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     * @param headerCellId - CellId of the header cell to sort by
+     * @param order - Sort direction
+     */
+    sortFilterColumn(sheetId: string, filterId: string, headerCellId: CellId, order: 'asc' | 'desc'): void;
+    /**
+     * Get unique values in a filter column (for populating dropdown).
+     *
+     * @param sheetId - Sheet containing the filter
+     * @param filterId - Filter ID
+     * @param headerCellId - CellId of the header cell
+     * @returns Array of unique cell values in the column
+     */
+    getUniqueValues(sheetId: string, filterId: string, headerCellId: CellId): CellValue[];
+    /**
+     * Check if a row is filtered (hidden by any filter).
+     *
+     * @param sheetId - Sheet to check
+     * @param row - Row index to check
+     * @returns true if the row is hidden due to filtering
+     */
+    isRowFiltered(sheetId: string, row: number): boolean;
+}
+//# sourceMappingURL=filter.d.ts.map

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

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

package/dist/data/grouping.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Row/Column Grouping Contracts
+ *
+ * Type definitions for row and column grouping (outline) with expand/collapse.
+ * Grouping enables hierarchical data organization with collapsible sections,
+ * outline level buttons, and automatic subtotal generation.
+ *
+ * These types mirror the Rust canonical types in `domain-types::domain::grouping`.
+ * The Rust types are the source of truth; these TS definitions must stay in sync.
+ * Bridge codegen also generates these into `compute-types.gen.ts` — if the two
+ * diverge, the generated version is authoritative.
+ */
+import type { CellRange } from '../core/core';
+/** Group axis: row or column. */
+export type GroupAxis = 'row' | 'column';
+/**
+ * A row or column group definition.
+ * Groups can be nested up to 8 levels deep (matching Excel).
+ *
+ * Mirrors Rust `domain_types::domain::grouping::GroupDefinition`.
+ */
+export interface GroupDefinition {
+    /** Unique group identifier */
+    id: string;
+    /** Sheet containing the group */
+    sheetId: string;
+    /** Group axis (row or column) */
+    axis: GroupAxis;
+    /** Start index (inclusive, 0-indexed) */
+    start: number;
+    /** End index (inclusive, 0-indexed) */
+    end: number;
+    /** Outline level (1-8, where 1 is outermost) */
+    level: number;
+    /** Whether this group is currently collapsed */
+    collapsed: boolean;
+    /** Parent group ID for nested groups */
+    parentId?: string;
+    /** OOXML round-trip: whether rows/cols were hidden by this group */
+    hidden?: boolean;
+    /** OOXML round-trip: collapsed attribute was on a group member, not end+1 */
+    collapsedOnMember?: boolean;
+}
+/**
+ * Per-sheet grouping configuration.
+ * Stored in Yjs for collaboration and persistence.
+ *
+ * Mirrors Rust `domain_types::domain::grouping::SheetGroupingConfig`.
+ */
+export interface SheetGroupingConfig {
+    /** All row groups in this sheet */
+    rowGroups: GroupDefinition[];
+    /** All column groups in this sheet */
+    columnGroups: GroupDefinition[];
+    /** Whether summary rows appear below detail rows (default: true) */
+    summaryRowsBelow: boolean;
+    /** Whether summary columns appear to the right of detail (default: true) */
+    summaryColumnsRight: boolean;
+    /** Whether outline symbols (+/-) are visible in the gutter (default: true) */
+    showOutlineSymbols: boolean;
+    /** Whether outline level buttons (1,2,3...) are visible (default: true) */
+    showOutlineLevelButtons: boolean;
+}
+/**
+ * Default grouping configuration for new sheets.
+ */
+export declare const DEFAULT_SHEET_GROUPING_CONFIG: SheetGroupingConfig;
+/**
+ * Computed outline level for a single row or column.
+ * Used by the renderer to determine visibility and display.
+ */
+export interface OutlineLevel {
+    /** Row or column index (0-indexed) */
+    index: number;
+    /** Current outline level (0 = not grouped, 1-8 = grouped) */
+    level: number;
+    /** Whether this row/column is visible (not hidden by collapsed groups) */
+    visible: boolean;
+    /** Whether this is a summary row/column (contains totals) */
+    isSummary: boolean;
+    /** Group IDs this row/column belongs to (innermost to outermost) */
+    groupIds: string[];
+}
+/**
+ * Partial update for outline display settings.
+ */
+export interface OutlineSettingsUpdate {
+    summaryRowsBelow?: boolean;
+    summaryColumnsRight?: boolean;
+    showOutlineSymbols?: boolean;
+    showOutlineLevelButtons?: boolean;
+}
+/**
+ * Hit test result for outline button clicks in headers.
+ * Used by the renderer/coordinator for click handling.
+ */
+export interface OutlineButtonHitResult {
+    /** Type of button clicked */
+    type: 'expand-collapse' | 'level';
+    /** Group ID for expand/collapse buttons */
+    groupId?: string;
+    /** Level number for level buttons (1, 2, 3, etc.) */
+    level?: number;
+    /** Axis of the button */
+    axis: 'row' | 'column';
+}
+/**
+ * Subtotal aggregate function types.
+ * Maps to SUBTOTAL function codes in Excel.
+ */
+export type SubtotalFunction = 'sum' | 'count' | 'average' | 'max' | 'min' | 'product' | 'countNums' | 'stdDev' | 'stdDevP' | 'var' | 'varP';
+/**
+ * Options for the Subtotals feature.
+ * Used to create automatic subtotals with grouping.
+ */
+export interface SubtotalOptions {
+    /** Column index to group by (the "change" column) */
+    groupByColumn: number;
+    /** Column indices to calculate subtotals for */
+    subtotalColumns: number[];
+    /** Aggregate function to use */
+    function: SubtotalFunction;
+    /** Replace existing subtotals if present (default: true) */
+    replaceExisting: boolean;
+    /** Place summary row below data (default: true) */
+    summaryBelowData: boolean;
+}
+/**
+ * Result of creating subtotals.
+ */
+export interface SubtotalResult {
+    /** Number of groups created */
+    groupsCreated: number;
+    /** Number of subtotal rows inserted */
+    subtotalRowsInserted: number;
+    /** Range of affected cells */
+    affectedRange: CellRange;
+}
+/**
+ * Grouping manager interface for row/column grouping operations.
+ * Implemented in engine, integrated via coordinator.
+ */
+export interface IGroupingManager {
+    groupRows(sheetId: string, startRow: number, endRow: number): GroupDefinition;
+    groupColumns(sheetId: string, startCol: number, endCol: number): GroupDefinition;
+    ungroupRows(sheetId: string, startRow: number, endRow: number): void;
+    ungroupColumns(sheetId: string, startCol: number, endCol: number): void;
+    clearRowGrouping(sheetId: string, startRow: number, endRow: number): void;
+    clearColumnGrouping(sheetId: string, startCol: number, endCol: number): void;
+    getSheetGroupingConfig(sheetId: string): SheetGroupingConfig;
+    getGroup(groupId: string): GroupDefinition | undefined;
+    getGroups(sheetId: string, axis: 'row' | 'column'): GroupDefinition[];
+    getRowOutlineLevels(sheetId: string, startRow: number, endRow: number): OutlineLevel[];
+    getColumnOutlineLevels(sheetId: string, startCol: number, endCol: number): OutlineLevel[];
+    getMaxOutlineLevel(sheetId: string, axis: 'row' | 'column'): number;
+    isRowVisible(sheetId: string, row: number): boolean;
+    isColumnVisible(sheetId: string, col: number): boolean;
+    setGroupCollapsed(groupId: string, collapsed: boolean): void;
+    toggleGroupCollapsed(groupId: string): boolean;
+    setLevelCollapsed(sheetId: string, axis: 'row' | 'column', level: number, collapsed: boolean): void;
+    expandAll(sheetId: string, axis?: 'row' | 'column'): void;
+    collapseAll(sheetId: string, axis?: 'row' | 'column'): void;
+    setOutlineSettings(sheetId: string, settings: Partial<Pick<SheetGroupingConfig, 'summaryRowsBelow' | 'summaryColumnsRight' | 'showOutlineSymbols' | 'showOutlineLevelButtons'>>): void;
+    autoOutline(sheetId: string, range: CellRange): number;
+    createSubtotals(sheetId: string, range: CellRange, options: SubtotalOptions): SubtotalResult;
+    removeSubtotals(sheetId: string, range: CellRange): void;
+    getAffectedRowsByGroup(groupId: string): number[];
+    getAffectedColumnsByGroup(groupId: string): number[];
+}
+//# sourceMappingURL=grouping.d.ts.map

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

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

package/dist/data/index.d.ts

@@ -0,0 +1,12 @@
+export * from './charts';
+export * from './conditional-format';
+export * from './filter';
+export * from './grouping';
+export * from './named-ranges';
+export * from './pivot';
+export * from './slicers';
+export * from './sorting';
+export * from './sparklines';
+export * from './tables';
+export * from './trace-arrows';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}

package/dist/data/named-ranges.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Named Ranges (Defined Names) Contracts
+ *
+ * Type definitions for the named ranges system (Stream B1).
+ *
+ * CRITICAL ARCHITECTURE DECISION: Named ranges MUST use IdentityFormula
+ * for the refersTo field, NOT A1 strings. This ensures:
+ * - CRDT-safe storage (concurrent structure changes compose correctly)
+ * - Insert/delete row/col operations don't corrupt named ranges
+ * - Display regenerated at render time from stable CellIds
+ *
+ * @example
+ * User creates "SalesData" → =Sheet1!$A$1:$B$10
+ *
+ * With A1 string storage (WRONG):
+ *   refersTo: "=Sheet1!$A$1:$B$10"
+ *   After concurrent column insert at A: still "=Sheet1!$A$1:$B$10" ❌
+ *
+ * With IdentityFormula storage (CORRECT):
+ *   refersTo: { template: "{0}", refs: [{ startId, endId }] }
+ *   After column insert: CellIds unchanged, positions shifted
+ *   Display regenerates: "=Sheet1!$B$1:$C$10" ✓
+ *
+ * @see plans/active/detailed-parity-implementation/STREAM-B1-NAMED-RANGES.md
+ */
+import type { IdentityFormula } from '../cells/cell-identity';
+import type { SheetId } from '../core/core';
+/**
+ * A defined name stored in Yjs.
+ *
+ * Uses IdentityFormula for CRDT-safe structure-change handling.
+ * This is the same approach used for formula storage throughout the codebase.
+ */
+export interface DefinedName {
+    /** Unique identifier for the defined name */
+    id: string;
+    /**
+     * The name (e.g., "SalesData", "TaxRate").
+     * Case-insensitive for lookup, but preserves original case.
+     */
+    name: string;
+    /**
+     * What the name refers to - stored as IdentityFormula for CRDT safety.
+     *
+     * Examples:
+     * - Range: { template: "{0}", refs: [{ type: 'range', startId: '...', endId: '...' }] }
+     * - Cell: { template: "{0}", refs: [{ type: 'cell', id: '...' }] }
+     * - Constant: { template: "42", refs: [] }
+     * - Formula: { template: "OFFSET({0},0,0,COUNTA({1}),1)", refs: [...] }
+     */
+    refersTo: IdentityFormula;
+    /**
+     * Scope of the name:
+     * - undefined/null = workbook scope (available everywhere)
+     * - sheetId = sheet scope (only available in that sheet)
+     *
+     * Sheet-scoped names have higher precedence than workbook-scoped
+     * names with the same name.
+     */
+    scope?: SheetId;
+    /** Optional comment/description */
+    comment?: string;
+    /**
+     * Whether the name is visible in Name Manager.
+     * Hidden names (visible: false) are typically system-generated.
+     * @default true
+     */
+    visible?: boolean;
+}
+/**
+ * Input for creating or updating a defined name.
+ *
+ * User provides A1 string, domain module converts to IdentityFormula internally.
+ * This keeps the API simple while maintaining CRDT safety in storage.
+ */
+export interface DefinedNameInput {
+    /** The name to define */
+    name: string;
+    /**
+     * A1-style reference that will be converted to IdentityFormula.
+     * Examples:
+     * - "=Sheet1!$A$1:$B$10"
+     * - "=$A$1"
+     * - "=42" (constant)
+     * - "=OFFSET(A1,0,0,COUNTA(A:A),1)" (dynamic formula)
+     */
+    refersToA1: string;
+    /** Scope: undefined = workbook, sheetId = sheet-local */
+    scope?: SheetId;
+    /** Optional comment */
+    comment?: string;
+}
+/**
+ * Result of name validation.
+ */
+export interface NameValidationResult {
+    /** Whether the name is valid */
+    valid: boolean;
+    /** Error type if invalid */
+    error?: 'invalid_characters' | 'starts_with_number' | 'reserved_name' | 'duplicate_name' | 'too_long' | 'cell_reference' | 'r1c1_reference' | 'empty';
+    /** Human-readable error message */
+    message?: string;
+}
+//# sourceMappingURL=named-ranges.d.ts.map

package/dist/data/named-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-ranges.d.ts","sourceRoot":"","sources":["../../src/data/named-ranges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;OAQG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IAEf,4BAA4B;IAC5B,KAAK,CAAC,EACF,oBAAoB,GACpB,oBAAoB,GACpB,eAAe,GACf,gBAAgB,GAChB,UAAU,GACV,gBAAgB,GAChB,gBAAgB,GAChB,OAAO,CAAC;IAEZ,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}