@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/data/pivot.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pivot Table Contracts
+ *
+ * TS-only types for pivot table UI and engine interfaces.
+ * Core data types (PivotTableConfig, PivotTableResult, PivotField, etc.) are
+ * auto-generated from Rust in @mog/kernel/bridges/compute/compute-types.gen.
+ *
+ * This file re-exports the generated types for backward compatibility and defines
+ * types that exist only in the TS layer (no Rust counterpart).
+ */
+import type { CellValue } from '../core/core';
+export type { AggregateFunction, CalculatedField, DateGrouping, DetectedDataType, FilterOperator, LayoutForm, NumberGrouping, OutputLocation, PivotColumnHeader, PivotField, PivotFieldArea, PivotFieldPlacementFlat, PivotFilter, PivotFilterConditionFlat, PivotGrandTotals, PivotHeader, PivotRow, PivotTableConfig, PivotTableDataOptions, PivotTableLayout, PivotTableResult, PivotTableStyle, PivotTopBottomFilter, ShowValuesAs, ShowValuesAsConfig, SortByValueConfig, SubtotalLocation, TopBottomBy, TopBottomType, } from '@mog/kernel/bridges/compute/compute-types.gen';
+/** Backward-compatible alias — generated types renamed to PivotFieldPlacementFlat. */
+export type PivotFieldPlacement = import('@mog/kernel/bridges/compute/compute-types.gen').PivotFieldPlacementFlat;
+/**
+ * Sort order for pivot fields.
+ * "none" means no explicit sort — uses natural order.
+ * Maps to Option<SortDirection> on the Rust side (None = "none").
+ */
+export type SortOrder = 'asc' | 'desc' | 'none';
+/**
+ * Pivot table configuration combined with its computed result.
+ * Used by UI components to render pivot tables with their data.
+ */
+export interface PivotTableWithResult {
+    config: import('@mog/kernel/bridges/compute/compute-types.gen').PivotTableConfig;
+    result: import('@mog/kernel/bridges/compute/compute-types.gen').PivotTableResult | null;
+    error?: string;
+}
+/**
+ * Tracks which headers are expanded/collapsed.
+ * Uses Record<string, boolean> for TS ergonomics; Rust side uses HashSet<String>
+ * with custom serde that accepts both array and map formats.
+ */
+export interface PivotExpansionState {
+    expandedRows: Record<string, boolean>;
+    expandedColumns: Record<string, boolean>;
+}
+/**
+ * Provider for pivot expansion state.
+ * Implemented by the app layer (PivotExpansionManager), injected into the kernel.
+ */
+export interface PivotExpansionStateProvider {
+    getExpansionState(pivotId: string): PivotExpansionState;
+    toggleExpanded(pivotId: string, headerKey: string, isRow: boolean, sheetId?: string): boolean;
+    setAllExpanded(pivotId: string, expanded: boolean): void;
+}
+/**
+ * Interface for the pivot table computation engine
+ */
+export interface IPivotEngine {
+    compute(config: import('@mog/kernel/bridges/compute/compute-types.gen').PivotTableConfig, data: CellValue[][], expansionState?: PivotExpansionState): import('@mog/kernel/bridges/compute/compute-types.gen').PivotTableResult;
+    detectFields(data: CellValue[][]): import('@mog/kernel/bridges/compute/compute-types.gen').PivotField[];
+    drillDown(config: import('@mog/kernel/bridges/compute/compute-types.gen').PivotTableConfig, data: CellValue[][], rowKey: string, columnKey: string): number[];
+    validateConfig(config: import('@mog/kernel/bridges/compute/compute-types.gen').PivotTableConfig): string[];
+}
+/**
+ * Arguments for GETPIVOTDATA function
+ */
+export interface GetPivotDataArgs {
+    dataField: string;
+    pivotTableId: string;
+    fieldValuePairs: Array<{
+        field: string;
+        value: CellValue;
+    }>;
+}
+//# sourceMappingURL=pivot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pivot.d.ts","sourceRoot":"","sources":["../../src/data/pivot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,uBAAuB,EACvB,WAAW,EACX,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,+CAA+C,CAAC;AAEvD,sFAAsF;AACtF,MAAM,MAAM,mBAAmB,GAC7B,OAAO,+CAA+C,EAAE,uBAAuB,CAAC;AAMlF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,+CAA+C,EAAE,gBAAgB,CAAC;IACjF,MAAM,EAAE,OAAO,+CAA+C,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACxD,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9F,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1D;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CACL,MAAM,EAAE,OAAO,+CAA+C,EAAE,gBAAgB,EAChF,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,cAAc,CAAC,EAAE,mBAAmB,GACnC,OAAO,+CAA+C,EAAE,gBAAgB,CAAC;IAE5E,YAAY,CACV,IAAI,EAAE,SAAS,EAAE,EAAE,GAClB,OAAO,+CAA+C,EAAE,UAAU,EAAE,CAAC;IAExE,SAAS,CACP,MAAM,EAAE,OAAO,+CAA+C,EAAE,gBAAgB,EAChF,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,EAAE,CAAC;IAEZ,cAAc,CACZ,MAAM,EAAE,OAAO,+CAA+C,EAAE,gBAAgB,GAC/E,MAAM,EAAE,CAAC;CACb;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CAC7D"}

package/dist/data/slicers.d.ts

@@ -0,0 +1,417 @@
+/**
+ * Slicer Contracts - Type definitions for slicer visual filter controls.
+ *
+ * Stream ES: Slicers (Layer 2)
+ *
+ * Slicers are floating objects that provide visual multi-select filtering
+ * for Tables and Pivot Tables. They follow the Cell Identity Model and
+ * use the Bridge pattern for data source integration.
+ *
+ * Architecture Notes:
+ * - Slicers are floating objects (render on overlay layer, z-index 5)
+ * - Uses Cell Identity Model (CellId for column references, not column index)
+ * - Filter state is the source of truth - slicer selection is derived
+ * - Bridge pattern connects slicers to Tables and Pivot Tables
+ * - State machine handles interaction states (idle, hovering, multiSelecting)
+ *
+ * Key Design Decisions:
+ * 1. CellId-based column reference for table slicers (survives column insert/delete)
+ * 2. Graceful degradation when source column is deleted (shows disconnected state)
+ * 3. Cache invalidation via EventBus subscriptions (CELLS_CHANGED, FILTER_APPLIED, etc.)
+ *
+ * @see plans/active/detailed-parity-implementation/STREAM-ES-SLICERS.md
+ * @see docs/architecture/cell-identity.md
+ */
+import type { CellId } from '../cells/cell-identity';
+import type { CellValue } from '../core/core';
+import type { ObjectPosition } from '../objects/floating-objects';
+import type { ColumnFilterCriteria } from './filter';
+/**
+ * The type of data source a slicer connects to.
+ */
+export type SlicerSourceType = 'table' | 'pivot';
+/**
+ * Reference to a table field for slicer binding.
+ * Uses column header CellId for Cell Identity Model compliance.
+ *
+ * **Graceful Degradation:** If the column header cell is deleted, the slicer
+ * becomes "disconnected" and shows a placeholder state. This matches Excel
+ * behavior where slicers become invalid when their source column is deleted.
+ */
+export interface SlicerTableSource {
+    type: 'table';
+    /** Table ID to connect to */
+    tableId: string;
+    /**
+     * Column header CellId - stable across column moves.
+     * If this CellId becomes orphaned (column deleted), slicer shows disconnected state.
+     */
+    columnCellId: CellId;
+}
+/**
+ * Reference to a pivot field for slicer binding.
+ */
+export interface SlicerPivotSource {
+    type: 'pivot';
+    /** Pivot table ID to connect to */
+    pivotId: string;
+    /** Field name in the pivot (row/column/filter field) */
+    fieldName: string;
+    /** Which area the field is in */
+    fieldArea: 'row' | 'column' | 'filter';
+}
+/**
+ * Union type for slicer data sources.
+ */
+export type SlicerSource = SlicerTableSource | SlicerPivotSource;
+/**
+ * Visual state of a slicer item (button).
+ *
+ * - selected: Item is selected (filter includes this value)
+ * - available: Item is available but not selected
+ * - unavailable: Item has no matching data after other filters
+ * - noData: Item has no data at all
+ */
+export type SlicerItemState = 'selected' | 'available' | 'unavailable' | 'noData';
+/**
+ * A single item in the slicer display.
+ */
+export interface SlicerItem {
+    /** The value this item represents */
+    value: CellValue;
+    /** Display text (formatted value) */
+    displayText: string;
+    /** Current visual state */
+    state: SlicerItemState;
+    /** Count of matching rows (for display, optional) */
+    count?: number;
+}
+/**
+ * Slicer style presets matching Excel's slicer style gallery.
+ */
+export type SlicerStylePreset = 'light1' | 'light2' | 'light3' | 'light4' | 'light5' | 'light6' | 'dark1' | 'dark2' | 'dark3' | 'dark4' | 'dark5' | 'dark6' | 'other1' | 'other2';
+/**
+ * Custom slicer style definition.
+ */
+export interface SlicerCustomStyle {
+    /** Header background color */
+    headerBackgroundColor?: string;
+    /** Header text color */
+    headerTextColor?: string;
+    /** Header font size */
+    headerFontSize?: number;
+    /** Selected item background color */
+    selectedBackgroundColor?: string;
+    /** Selected item text color */
+    selectedTextColor?: string;
+    /** Available item background color */
+    availableBackgroundColor?: string;
+    /** Available item text color */
+    availableTextColor?: string;
+    /** Unavailable item background color */
+    unavailableBackgroundColor?: string;
+    /** Unavailable item text color */
+    unavailableTextColor?: string;
+    /** Border color */
+    borderColor?: string;
+    /** Border width in pixels */
+    borderWidth?: number;
+    /** Corner radius for items */
+    itemBorderRadius?: number;
+}
+/**
+ * Complete slicer style configuration.
+ */
+export interface SlicerStyle {
+    /** Style preset (mutually exclusive with custom) */
+    preset?: SlicerStylePreset;
+    /** Custom style (mutually exclusive with preset) */
+    custom?: SlicerCustomStyle;
+    /** Number of columns for item layout (default: 1) */
+    columnCount: number;
+    /** Button height in pixels */
+    buttonHeight: number;
+    /** Show item selection indicators */
+    showSelectionIndicator: boolean;
+    /** ST_SlicerCacheCrossFilter — controls cross-filtering visual indication.
+     * Replaces the previous showItemsWithNoData boolean.
+     * Default: 'showItemsWithDataAtTop' */
+    crossFilter: 'none' | 'showItemsWithDataAtTop' | 'showItemsWithNoData';
+    /** Whether to use custom sort list. Default: true */
+    customListSort: boolean;
+    /** Whether to show items with no matching data (x14 pivot-backed slicers). Default: true */
+    showItemsWithNoData: boolean;
+    /** 'dataSourceOrder' is internal-only; never read from or written to OOXML. Import defaults to 'ascending'. */
+    sortOrder: 'ascending' | 'descending' | 'dataSourceOrder';
+}
+/**
+ * Complete slicer configuration stored in Yjs.
+ *
+ * @deprecated Prefer `StoredSlicer` from `compute-types.gen` — the canonical
+ * Rust-generated persistence type. This hand-written contract is kept for
+ * consumers that cannot import from `@mog/kernel`.
+ */
+export interface SlicerConfig {
+    /** Unique slicer identifier (UUID v7) */
+    id: string;
+    /** Sheet containing the slicer */
+    sheetId: string;
+    /** Data source connection */
+    source: SlicerSource;
+    /** Slicer caption (header text) */
+    caption: string;
+    /** Style configuration */
+    style: SlicerStyle;
+    /** Position configuration (from FloatingObject) */
+    position: ObjectPosition;
+    /** Z-order within the sheet */
+    zIndex: number;
+    /** Maps to OOXML CT_Slicer.@lockedPosition — whether slicer position is locked to cell. Default: false */
+    locked: boolean;
+    /** @startItem — first visible item index (scroll position). Default: 0 */
+    startItem?: number;
+    /** Whether multi-select is enabled (default: true) */
+    multiSelect: boolean;
+    /** Show slicer header */
+    showHeader: boolean;
+    /** Created timestamp */
+    createdAt?: number;
+    /** Last modified timestamp */
+    updatedAt?: number;
+}
+/**
+ * Serialized slicer configuration for Yjs storage.
+ * Uses JSON strings for nested objects to avoid Yjs nested object issues.
+ *
+ * @deprecated Rust compute-core now handles slicer serialization directly.
+ * See `StoredSlicer` in `compute-types.gen` for the canonical type.
+ */
+export interface StoredSlicerConfig {
+    /** Unique slicer identifier (UUID v7) */
+    id: string;
+    /** Sheet containing the slicer */
+    sheetId: string;
+    /** Data source (JSON-serialized SlicerSource) */
+    source: string;
+    /** Slicer caption (header text) */
+    caption: string;
+    /** Style configuration (JSON-serialized SlicerStyle) */
+    style: string;
+    /** Position configuration (JSON-serialized ObjectPosition) */
+    position: string;
+    /** Z-order within the sheet */
+    zIndex: number;
+    /** Whether slicer is locked */
+    locked: boolean;
+    /** Show slicer header */
+    showHeader: boolean;
+    /** Created timestamp */
+    createdAt?: number;
+    /** Last modified timestamp */
+    updatedAt?: number;
+}
+/**
+ * Cached slicer data for efficient rendering.
+ * Computed from source data and filter state.
+ */
+export interface SlicerCache {
+    /** Slicer ID this cache belongs to */
+    slicerId: string;
+    /** All items with current states */
+    items: SlicerItem[];
+    /** Whether cache is stale (needs refresh) */
+    isStale: boolean;
+    /** Last refresh timestamp */
+    lastRefresh: number;
+}
+/**
+ * Current selection state within a slicer.
+ * This is UI state, NOT persisted - the filter state is the source of truth.
+ */
+export interface SlicerSelectionState {
+    /** Currently selected values (derived from filter state) */
+    selectedValues: Set<CellValue>;
+    /** Last clicked value (for shift+click range selection) */
+    lastClickedValue?: CellValue;
+    /** Whether multi-select is active (Ctrl key held) */
+    isMultiSelectActive: boolean;
+}
+/**
+ * Options for creating a new slicer.
+ */
+export interface CreateSlicerOptions {
+    /** Slicer caption (default: field/column name) */
+    caption?: string;
+    /** Style configuration */
+    style?: Partial<SlicerStyle>;
+    /** Initial position */
+    position?: Partial<ObjectPosition>;
+    /** Show header */
+    showHeader?: boolean;
+}
+/**
+ * Slicer manager interface for CRUD operations.
+ * Implemented in the engine, integrated via coordinator.
+ */
+export interface ISlicerManager {
+    /**
+     * Create a slicer for a table column.
+     *
+     * @param sheetId - Sheet to place the slicer in
+     * @param tableId - Table to connect to
+     * @param columnCellId - CellId of the column header (Cell Identity Model)
+     * @param options - Optional configuration
+     * @returns The created slicer configuration
+     */
+    createTableSlicer(sheetId: string, tableId: string, columnCellId: CellId, options?: CreateSlicerOptions): SlicerConfig;
+    /**
+     * Create a slicer for a pivot field.
+     *
+     * @param sheetId - Sheet to place the slicer in
+     * @param pivotId - Pivot table to connect to
+     * @param fieldName - Field name in the pivot
+     * @param fieldArea - Which area the field is in
+     * @param options - Optional configuration
+     * @returns The created slicer configuration
+     */
+    createPivotSlicer(sheetId: string, pivotId: string, fieldName: string, fieldArea: 'row' | 'column' | 'filter', options?: CreateSlicerOptions): SlicerConfig;
+    /**
+     * Get slicer by ID.
+     */
+    getSlicer(slicerId: string): SlicerConfig | undefined;
+    /**
+     * Get all slicers in a sheet.
+     */
+    getSlicersInSheet(sheetId: string): SlicerConfig[];
+    /**
+     * Get all slicers connected to a table.
+     */
+    getSlicersForTable(tableId: string): SlicerConfig[];
+    /**
+     * Get all slicers connected to a pivot table.
+     */
+    getSlicersForPivot(pivotId: string): SlicerConfig[];
+    /**
+     * Update slicer configuration.
+     */
+    updateSlicer(slicerId: string, updates: Partial<SlicerConfig>): void;
+    /**
+     * Delete a slicer.
+     */
+    deleteSlicer(slicerId: string): void;
+    /**
+     * Get cached items for a slicer.
+     * Returns all items with their current states.
+     */
+    getSlicerItems(slicerId: string): SlicerItem[];
+    /**
+     * Refresh slicer cache from source data.
+     * Called when source data changes.
+     */
+    refreshSlicerCache(slicerId: string): void;
+    /**
+     * Mark slicer cache as stale.
+     * Called when source data may have changed.
+     */
+    markCacheStale(slicerId: string): void;
+    /**
+     * Mark slicer as disconnected (source column deleted).
+     */
+    markDisconnected(slicerId: string): void;
+    /**
+     * Select a single value in the slicer (replaces current selection).
+     */
+    selectValue(slicerId: string, value: CellValue): void;
+    /**
+     * Toggle a value's selection (add/remove from multi-select).
+     */
+    toggleValue(slicerId: string, value: CellValue): void;
+    /**
+     * Clear all selections (show all data).
+     */
+    clearSelection(slicerId: string): void;
+    /**
+     * Select multiple values.
+     */
+    selectValues(slicerId: string, values: CellValue[]): void;
+    /**
+     * Sync slicer visual state with current filter state.
+     * Called when filter changes externally.
+     */
+    syncWithFilter(slicerId: string): void;
+    /**
+     * Get current selection as filter criteria.
+     */
+    getFilterCriteria(slicerId: string): ColumnFilterCriteria | null;
+}
+/**
+ * Timeline aggregation level.
+ * Determines how dates are grouped in the timeline display.
+ */
+export type TimelineLevel = 'years' | 'quarters' | 'months' | 'days';
+/**
+ * Timeline slicer specific configuration.
+ * Extends base slicer for date-range filtering.
+ */
+export interface TimelineSlicerConfig extends SlicerConfig {
+    /** Source must be table or pivot with date column */
+    sourceType: 'timeline';
+    /** Current aggregation level */
+    timelineLevel: TimelineLevel;
+    /** Start date of the data range */
+    dataStartDate?: number;
+    /** End date of the data range */
+    dataEndDate?: number;
+    /** Currently selected date range start */
+    selectedStartDate?: number;
+    /** Currently selected date range end */
+    selectedEndDate?: number;
+    /** Show the level selector in the header */
+    showLevelSelector: boolean;
+    /** Show the date range label */
+    showDateRangeLabel: boolean;
+}
+/**
+ * A timeline period represents a grouping of dates at a specific aggregation level.
+ */
+export interface TimelinePeriod {
+    /** Start date serial of this period (inclusive) */
+    startDate: number;
+    /** End date serial of this period (inclusive) */
+    endDate: number;
+    /** Display label for this period (e.g., "Jan", "Q1", "2024") */
+    label: string;
+    /** Short label for compact display */
+    shortLabel: string;
+    /** Whether this period is currently selected */
+    isSelected: boolean;
+    /** Whether this period has data */
+    hasData: boolean;
+    /** Count of data items in this period */
+    count: number;
+}
+/**
+ * Timeline scroll position and visible range state.
+ */
+export interface TimelineViewState {
+    /** Currently visible start date serial */
+    visibleStartDate: number;
+    /** Currently visible end date serial */
+    visibleEndDate: number;
+    /** Scroll position (0-1) */
+    scrollPosition: number;
+    /** Current zoom level */
+    level: TimelineLevel;
+}
+/**
+ * Timeline selection state during drag operation.
+ */
+export interface TimelineDragState {
+    /** Start period index */
+    startIndex: number;
+    /** Current end period index */
+    endIndex: number;
+    /** Whether drag is active */
+    isDragging: boolean;
+}
+//# sourceMappingURL=slicers.d.ts.map

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

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

package/dist/data/sorting.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Sorting Contracts - Type definitions for spreadsheet sorting.
+ *
+ * Stream A1: Sort System (Cell Identity Model)
+ *
+ * This module defines sort options, criteria, and events. The sort system
+ * uses the Cell Identity Model for column identification - sort criteria
+ * reference columns by header CellId (not column index) to survive
+ * concurrent structure changes.
+ *
+ * ARCHITECTURE (Cell Identity Model):
+ *
+ * Sort criteria use headerCellId (not columnIndex) for column identification.
+ * This follows the same pattern as:
+ * - FilterSortState.columnCellId (Layer 0 filters)
+ * - IdentityRangeRef (formulas)
+ * - IdentityMergedRegion (merged cells)
+ *
+ * Why CellId-based?
+ * - Survives column insert/delete (column index shifts, CellId stable)
+ * - CRDT-safe for concurrent structure changes
+ * - Consistent with Cell Identity Model used throughout codebase
+ * - Works with async/queued operations (no race conditions)
+ *
+ * Sort operation flow:
+ *   SortOptions (CellId-based) → Resolve Positions → Compute Order → Reorder Rows → Emit Event
+ *
+ * IMPORTANT: Sort updates cell POSITIONS, not cell DATA.
+ * This preserves Cell Identity - CellIds stay with their data.
+ *
+ * @see docs/architecture/cell-identity.md
+ * @see plans/active/detailed-parity-implementation/STREAM-A1-SORT.md
+ */
+import type { CellId } from '../cells/cell-identity';
+import type { CellRange, CellValue, SheetId } from '../core/core';
+import type { BaseEvent, StructureChangeSource } from '../core/event-base';
+/**
+ * Sort direction.
+ *
+ * Note: 'asc' | 'desc' matches SortOrder from pivot.ts but without 'none'.
+ * For sorting operations, we always have a direction.
+ */
+export type SortDirection = 'asc' | 'desc';
+/**
+ * What aspect of the cell to sort by.
+ *
+ * - value: Sort by cell computed value (default)
+ * - cellColor: Sort by cell background color
+ * - fontColor: Sort by cell font color
+ */
+export type SortBy = 'value' | 'cellColor' | 'fontColor';
+/**
+ * Single sort criterion - Cell Identity Model.
+ *
+ * ARCHITECTURE: Uses headerCellId for column identification, NOT column index.
+ * This ensures sort criteria survives column insert/delete operations.
+ *
+ * Example:
+ *   User sorts by column B (header "Name")
+ *   Stored as: { headerCellId: 'abc-123-...', direction: 'asc', sortBy: 'value' }
+ *   If column A is inserted, column B becomes C, but 'abc-123-...' still identifies "Name"
+ */
+export interface SortCriterion {
+    /**
+     * CellId of the header cell for this sort column.
+     *
+     * Why CellId (not column index)?
+     * - Column index changes on insert/delete column
+     * - CellId is stable - sort criterion follows the column
+     * - CRDT-safe for concurrent structure changes
+     */
+    headerCellId: CellId;
+    /** Sort direction (ascending or descending) */
+    direction: SortDirection;
+    /** What to sort by (value, cell color, or font color) */
+    sortBy: SortBy;
+    /** Custom order list for custom sort (optional) */
+    customOrder?: CellValue[];
+    /** Case sensitive string comparison (default: false) */
+    caseSensitive?: boolean;
+}
+/**
+ * Complete sort options - Cell Identity Model.
+ *
+ * The sort range itself is passed separately to sortRange().
+ * For table sort integration, this aligns with FilterSortState.
+ */
+export interface SortOptions {
+    /**
+     * Sort criteria (primary, secondary, tertiary, etc.).
+     * Each criterion uses headerCellId for column identification.
+     * Evaluated in order - primary first, then secondary for ties, etc.
+     */
+    criteria: SortCriterion[];
+    /**
+     * Does the range have a header row?
+     *
+     * If true, the first row of the range is excluded from sorting.
+     * Header cells provide display names for sort dialog columns.
+     */
+    hasHeaders?: boolean;
+    /**
+     * Sort by columns instead of rows (horizontal sort).
+     *
+     * Default is false (sort rows vertically).
+     * When true, sorts columns left-to-right based on a row's values.
+     */
+    byColumns?: boolean;
+}
+/**
+ * Sort criterion for external API (user-friendly version).
+ *
+ * Uses column index instead of CellId for API ergonomics.
+ * The SheetAPI.sortRange() method converts this to CellId-based SortCriterion.
+ *
+ * This is the same pattern as createFilter() - API accepts positions,
+ * internally stores CellIds.
+ */
+export interface ApiSortCriterion {
+    /** Column index to sort by (0-based, absolute) */
+    column: number;
+    /** Sort direction */
+    direction: SortDirection;
+    /** What to sort by (default: 'value') */
+    sortBy?: SortBy;
+    /** Custom order list (optional) */
+    customOrder?: CellValue[];
+    /** Case sensitive comparison (default: false) */
+    caseSensitive?: boolean;
+}
+/**
+ * Sort options for external API (user-friendly version).
+ *
+ * Used by SheetAPI.sortRange() for AI agent ergonomics.
+ */
+export interface ApiSortOptions {
+    /** Sort criteria using column indices */
+    sortBy: ApiSortCriterion[];
+    /** Does the range have a header row? (default: auto-detect) */
+    hasHeaders?: boolean;
+    /** Sort by columns instead of rows (default: false) */
+    byColumns?: boolean;
+}
+/**
+ * Result of a sort operation.
+ *
+ * Returned by domain module's computeSortedRowOrder() for orchestration.
+ */
+export interface SortResult {
+    /** Original row indices in sorted order */
+    sortedIndices: number[];
+    /** Number of rows that changed position */
+    rowsMoved: number;
+    /** Whether any header CellIds couldn't be resolved (deleted columns) */
+    hasUnresolvedCriteria: boolean;
+}
+/**
+ * Emitted when a range is sorted.
+ * Stream A1: Sort System
+ */
+export interface RangeSortedEvent extends BaseEvent {
+    type: 'range:sorted';
+    sheetId: SheetId;
+    /** The range that was sorted */
+    range: CellRange;
+    /** Sort options used */
+    options: SortOptions;
+    /** Number of rows that changed position */
+    rowsMoved: number;
+    source: StructureChangeSource;
+}
+//# sourceMappingURL=sorting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sorting.d.ts","sourceRoot":"","sources":["../../src/data/sorting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAM3E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC;AAMzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,+CAA+C;IAC/C,SAAS,EAAE,aAAa,CAAC;IAEzB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAE1B,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,EAAE,aAAa,EAAE,CAAC;IAE1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IAEf,qBAAqB;IACrB,SAAS,EAAE,aAAa,CAAC;IAEzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,mCAAmC;IACnC,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAE1B,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAE3B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,uDAAuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAElB,wEAAwE;IACxE,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAMD;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,wBAAwB;IACxB,OAAO,EAAE,WAAW,CAAC;IACrB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,qBAAqB,CAAC;CAC/B"}