@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/apps/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * App Kernel API - Type Definitions
+ *
+ * These types define the stable API surface for apps. Apps see only these types,
+ * never internal kernel types like CellId, RowId, ColId.
+ *
+ * Design principles:
+ * 1. Opaque IDs - RecordId, AppTableId, AppColumnId are branded strings
+ * 2. Dual access - AppRecord provides values by name AND by column ID
+ * 3. Stability - Internal kernel changes don't break apps
+ *
+ * @see plans/active/os-refactor/PHASE-F-APPS.md
+ */
+/**
+ * Opaque record identifier.
+ * Maps internally to RowId but apps don't need to know this.
+ */
+export type RecordId = string & {
+    readonly __brand: 'RecordId';
+};
+/**
+ * Opaque table identifier.
+ * Maps internally to table ID string but apps don't need to know this.
+ */
+export type AppTableId = string & {
+    readonly __brand: 'AppTableId';
+};
+/**
+ * Opaque column identifier.
+ * Maps internally to ColId but apps don't need to know this.
+ */
+export type AppColumnId = string & {
+    readonly __brand: 'AppColumnId';
+};
+/**
+ * Primitive cell value types that apps can work with.
+ */
+export type AppCellValuePrimitive = string | number | boolean | null;
+/**
+ * Cell error representation for apps.
+ */
+export interface AppCellError {
+    type: 'error';
+    value: string;
+    message?: string;
+}
+/**
+ * Cell value type for apps.
+ * Includes primitives and errors.
+ */
+export type AppCellValue = AppCellValuePrimitive | AppCellError;
+/**
+ * A record (row) in a table as seen by apps.
+ *
+ * LOAD-BEARING DECISION: Provides BOTH access patterns:
+ * - `values` - Keyed by column NAME (convenient for app-managed tables)
+ * - `valuesByColumnId` - Keyed by column ID (stable across renames)
+ *
+ * Apps choose based on their needs:
+ * - App-managed tables use names (app controls schema, won't rename)
+ * - User-created tables use IDs (user might rename columns)
+ */
+export interface AppRecord {
+    /** Opaque record ID (maps to internal RowId) */
+    id: RecordId;
+    /** Table this record belongs to */
+    tableId: AppTableId;
+    /**
+     * Values keyed by column NAME (convenience access).
+     * Use this for app-managed tables where you control the schema.
+     * Example: record.values["Status"]
+     */
+    values: Record<string, AppCellValue>;
+    /**
+     * Values keyed by column ID (stable access).
+     * Use this for user-created tables where columns might be renamed.
+     * Example: record.valuesByColumnId[STATUS_COL_ID]
+     */
+    valuesByColumnId: Record<AppColumnId, AppCellValue>;
+    /** Timestamp when record was created (Unix ms) */
+    createdAt?: number;
+    /** Timestamp when record was last modified (Unix ms) */
+    modifiedAt?: number;
+}
+/**
+ * Column type kinds supported by the system.
+ */
+export type AppColumnTypeKind = 'text' | 'number' | 'date' | 'checkbox' | 'formula' | 'select' | 'multiselect' | 'person' | 'file' | 'url' | 'email' | 'phone' | 'rating' | 'progress' | 'createdTime' | 'modifiedTime' | 'createdBy' | 'modifiedBy' | 'autoNumber' | 'relation' | 'lookup' | 'rollup';
+/**
+ * Select option for select/multiselect columns.
+ */
+export interface AppSelectOption {
+    id: string;
+    name: string;
+    color?: string;
+}
+/**
+ * Column type configuration.
+ */
+export interface AppColumnType {
+    kind: AppColumnTypeKind;
+    options?: AppSelectOption[];
+    format?: string;
+    min?: number;
+    max?: number;
+    includeTime?: boolean;
+    maxRating?: number;
+    formula?: string;
+    targetTableId?: AppTableId;
+    allowMultiple?: boolean;
+    relationColumnId?: AppColumnId;
+    sourceColumnId?: AppColumnId;
+    aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countAll' | 'countValues' | 'countUnique';
+}
+/**
+ * Column information as seen by apps.
+ */
+export interface AppColumnInfo {
+    /** Opaque column ID */
+    id: AppColumnId;
+    /** Column display name */
+    name: string;
+    /** Column type and configuration */
+    type: AppColumnType;
+    /** Whether the column is required (non-null) */
+    required: boolean;
+    /** Whether values must be unique */
+    unique: boolean;
+    /** Default value for new records */
+    defaultValue?: AppCellValue;
+    /** Column position (0-indexed) */
+    index: number;
+}
+/**
+ * Column schema for creating/updating columns.
+ */
+export interface AppColumnSchema {
+    /** Column display name */
+    name: string;
+    /** Column type and configuration */
+    type: AppColumnType;
+    /** Whether the column is required (non-null) */
+    required?: boolean;
+    /** Whether values must be unique */
+    unique?: boolean;
+    /** Default value for new records */
+    defaultValue?: AppCellValue;
+}
+/**
+ * Table information as seen by apps.
+ */
+export interface AppTableInfo {
+    /** Opaque table ID */
+    id: AppTableId;
+    /** Table display name */
+    name: string;
+    /** Columns in the table */
+    columns: AppColumnInfo[];
+    /** Number of records (rows) in the table */
+    recordCount: number;
+    /** ID of the sheet containing this table (opaque to apps) */
+    sheetId: string;
+}
+/**
+ * Table schema for creating tables.
+ */
+export interface AppTableSchema {
+    /** Table display name */
+    name: string;
+    /** Column schemas */
+    columns: AppColumnSchema[];
+}
+/**
+ * Filter operator for queries.
+ */
+export type AppFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'isEmpty' | 'isNotEmpty' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'isAnyOf' | 'isNoneOf';
+/**
+ * Filter condition for a single field.
+ */
+export interface AppFilterCondition {
+    /** Column to filter on (by ID or name) */
+    field: AppColumnId | string;
+    /** Filter operator */
+    operator: AppFilterOperator;
+    /** Value(s) to compare against */
+    value?: AppCellValue | AppCellValue[];
+}
+/**
+ * Combined filter expression (AND logic).
+ */
+export interface AppFilter {
+    conditions: AppFilterCondition[];
+}
+/**
+ * Sort direction.
+ */
+export type AppSortDirection = 'asc' | 'desc';
+/**
+ * Sort configuration for a single field.
+ */
+export interface AppSortConfig {
+    /** Column to sort by (by ID or name) */
+    field: AppColumnId | string;
+    /** Sort direction */
+    direction: AppSortDirection;
+}
+/**
+ * Query options for listing records.
+ */
+export interface AppQueryOptions {
+    /** Filter conditions */
+    filter?: AppFilter;
+    /** Sort configuration (applied in order) */
+    sort?: AppSortConfig[];
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip (for pagination) */
+    offset?: number;
+}
+/**
+ * Unsubscribe function returned by event subscriptions.
+ */
+export type Unsubscribe = () => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/apps/types.d.ts.map

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

package/dist/apps/views.d.ts

@@ -0,0 +1,142 @@
+/**
+ * View Contribution Types for Apps
+ *
+ * Apps can contribute custom views that appear in the view tabs for applicable tables.
+ * This enables apps to provide specialized visualizations for their data.
+ *
+ * @see plans/active/os-refactor/PHASE-F-APPS.md (F6: View Discovery)
+ */
+import type { AppTableInfo } from './types';
+/** Framework-agnostic component type. Consumers cast to their framework's component type. */
+type ComponentType<P> = (props: P) => unknown;
+/**
+ * Props passed to view components contributed by apps.
+ *
+ * Views receive the kernel API and table/view context.
+ * The config object is view-specific and can be persisted.
+ */
+export interface ViewProps {
+    /**
+     * Unique view instance ID.
+     * Multiple instances of the same view type can exist.
+     */
+    viewId: string;
+    /**
+     * The table this view is rendering.
+     */
+    tableId: string;
+    /**
+     * View-specific configuration (persisted).
+     * Structure depends on the view type.
+     * @example { groupByColumn: 'Status', cardSize: 'medium' }
+     */
+    config: Record<string, unknown>;
+    /**
+     * Callback to update view configuration.
+     * Shell persists the updated config.
+     */
+    onConfigChange?: (config: Record<string, unknown>) => void;
+}
+/**
+ * A view contribution from an app.
+ *
+ * Views appear in the view tabs for tables where they're applicable.
+ * Apps can contribute specialized views (e.g., CRM Pipeline, Project Gantt).
+ *
+ * Design principle: Views are discovered at runtime and filtered by applicability.
+ *
+ * @example
+ * ```typescript
+ * const pipelineView: ViewContribution = {
+ *   id: 'crm-pipeline',
+ *   name: 'Pipeline',
+ *   icon: '🔄',
+ *   appId: 'crm',
+ *   scope: 'app-tables-only',
+ *   applicableWhen: (table) => table.name === 'Deals',
+ *   component: PipelineViewComponent,
+ *   defaultConfig: { cardSize: 'medium' }
+ * };
+ * ```
+ */
+export interface ViewContribution {
+    /**
+     * Unique view ID (scoped to app).
+     * Format: `{appId}-{viewName}` recommended.
+     * @example 'crm-pipeline', 'analytics-chart'
+     */
+    id: string;
+    /**
+     * Display name shown in view tabs.
+     * @example 'Pipeline', 'Chart', 'Board'
+     */
+    name: string;
+    /**
+     * Icon for the view tab (emoji or icon identifier).
+     * @example '🔄', 'chart-bar', '📊'
+     */
+    icon?: string;
+    /**
+     * The app that contributes this view.
+     * Used to scope view visibility and determine ownership.
+     */
+    appId: string;
+    /**
+     * Scope determines where this view appears.
+     *
+     * - 'app-tables-only': Only for tables created/owned by this app.
+     *   Use this for app-specific views that only make sense for the app's data.
+     *   @example CRM Pipeline view only for Deals table
+     *
+     * - 'all-tables': For any table that matches applicableWhen.
+     *   Use this for generic views that work on any compatible table structure.
+     *   @example Generic chart view for tables with numeric columns
+     */
+    scope: 'app-tables-only' | 'all-tables';
+    /**
+     * Determines if this view is applicable for a given table.
+     *
+     * Called for each table to filter view tabs.
+     * Should check table structure (columns, types) to determine compatibility.
+     *
+     * Performance note: Keep this function fast - it's called frequently.
+     * Avoid async operations or expensive computations.
+     *
+     * @param table - Table metadata to check
+     * @returns true if this view can render the table
+     *
+     * @example
+     * // Kanban requires a select/status column
+     * (table) => table.columns.some(c => c.type.kind === 'select')
+     *
+     * @example
+     * // Timeline requires start/end date columns
+     * (table) => {
+     *   const hasStart = table.columns.some(c => c.type.kind === 'date');
+     *   return hasStart;
+     * }
+     */
+    applicableWhen: (table: AppTableInfo) => boolean;
+    /**
+     * The React component that renders this view.
+     * Receives ViewProps with kernel API and configuration.
+     *
+     * Component should be exported from the app and can use any React features.
+     * The Shell handles mounting, unmounting, and prop updates.
+     */
+    component: ComponentType<ViewProps>;
+    /**
+     * Default configuration for new instances of this view.
+     * Merged with user-specific config.
+     *
+     * @example
+     * {
+     *   cardSize: 'medium',
+     *   groupByColumn: null, // auto-detect
+     *   showEmptyGroups: true
+     * }
+     */
+    defaultConfig?: Record<string, unknown>;
+}
+export {};
+//# sourceMappingURL=views.d.ts.map

package/dist/apps/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/apps/views.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,6FAA6F;AAC7F,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;OAUG;IACH,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAEjD;;;;;;OAMG;IACH,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAEpC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC"}

package/dist/bridges/chart-bridge.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Chart Bridge Interface
+ *
+ * Defines the contract for chart rendering and data resolution.
+ * This interface bridges the charts library to the engine's reactive system.
+ *
+ * Features:
+ * - Compiled marks caching (invalidated on data/spec changes)
+ * - Event subscriptions for reactive updates
+ * - Error state management
+ * - Data resolution from CellIdRange to actual values
+ *
+ * @see engine/src/state/bridges/chart-bridge.ts - Implementation
+ */
+import type { CellRange, SheetId } from '../core';
+/**
+ * Chart error codes for rendering and data resolution errors.
+ */
+export type ChartErrorCode = 'DATA_UNAVAILABLE' | 'INVALID_SPEC' | 'CHART_NOT_FOUND' | 'RENDER_FAILED' | 'COMPILE_FAILED' | 'EMPTY_DATA';
+/**
+ * Chart error structure.
+ */
+export interface ChartError {
+    /** Error code */
+    code: ChartErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Chart ID that caused the error */
+    chartId: string;
+    /** Additional error details */
+    details?: unknown;
+}
+/**
+ * A single row of chart data.
+ */
+export interface ChartDataRow {
+    [key: string]: unknown;
+}
+/**
+ * Result of resolving chart data from cell range.
+ */
+export type ChartDataResult = {
+    success: true;
+    data: ChartDataRow[];
+} | {
+    success: false;
+    error: ChartError;
+};
+/**
+ * Mark primitives for chart rendering.
+ * These are the low-level rendering instructions.
+ */
+export interface ChartMark {
+    /** Mark type */
+    type: 'rect' | 'path' | 'arc' | 'text' | 'symbol' | 'line' | 'area';
+    /** X position */
+    x?: number;
+    /** Y position */
+    y?: number;
+    /** Width (for rect) */
+    width?: number;
+    /** Height (for rect) */
+    height?: number;
+    /** Path data (for path) */
+    path?: string;
+    /** Text content (for text) */
+    text?: string;
+    /** Fill color */
+    fill?: string;
+    /** Stroke color */
+    stroke?: string;
+    /** Stroke width */
+    strokeWidth?: number;
+    /** Opacity (0-1) */
+    opacity?: number;
+    /** Associated data */
+    data?: unknown;
+}
+/**
+ * Bounding box for chart rendering.
+ */
+export interface ChartBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Bridge interface for chart rendering.
+ *
+ * This interface provides methods for resolving chart data, compiling marks,
+ * and rendering charts to canvas.
+ */
+export interface IChartBridge {
+    /**
+     * Start the chart bridge - subscribe to events for reactive updates.
+     *
+     * @returns Cleanup function to stop the bridge
+     */
+    start(): () => void;
+    /**
+     * Stop the chart bridge and clean up subscriptions.
+     */
+    stop(): void;
+    /**
+     * Destroy the bridge - alias for stop().
+     */
+    destroy(): void;
+    /**
+     * Resolve chart data from CellIdRange to actual values.
+     *
+     * @param sheetId - Sheet containing the chart
+     * @param chartId - Chart ID
+     * @returns Resolved data or error
+     */
+    resolveChartData(sheetId: SheetId, chartId: string): Promise<ChartDataResult>;
+    /**
+     * Get compiled marks for a chart.
+     * Returns cached marks if available, otherwise compiles the chart spec.
+     *
+     * @param sheetId - Sheet ID
+     * @param chartId - Chart ID
+     * @returns Compiled marks or error
+     */
+    getMarks(sheetId: SheetId, chartId: string): Promise<ChartMark[] | ChartError>;
+    /**
+     * Render a chart to a canvas context.
+     *
+     * @param chartId - Chart ID
+     * @param ctx - Canvas 2D rendering context
+     * @param bounds - Bounding box for the chart
+     */
+    render(chartId: string, ctx: CanvasRenderingContext2D, bounds: ChartBounds): Promise<void>;
+    /**
+     * Invalidate a chart's compiled marks cache.
+     *
+     * @param chartId - Chart ID
+     */
+    invalidateChart(chartId: string): void;
+    /**
+     * Check if a chart is dirty (needs recompilation).
+     *
+     * @param chartId - Chart ID
+     * @returns True if chart needs recompilation
+     */
+    isChartDirty(chartId: string): boolean;
+    /**
+     * Clear the dirty flag for a chart after rendering.
+     *
+     * @param chartId - Chart ID
+     */
+    clearDirtyFlag(chartId: string): void;
+    /**
+     * Clear all caches. Useful for testing or full refresh.
+     */
+    clearAllCaches(): void;
+    /**
+     * Get charts that are affected by changes in a specific cell range.
+     *
+     * @param sheetId - Sheet ID
+     * @param range - Cell range
+     * @returns Array of chart IDs
+     */
+    getChartsAffectedByRange(sheetId: SheetId, range: CellRange): Promise<string[]>;
+    /**
+     * Get all dirty charts that need re-rendering.
+     *
+     * @returns Array of chart IDs
+     */
+    getDirtyCharts(): string[];
+}
+//# sourceMappingURL=chart-bridge.d.ts.map

package/dist/bridges/chart-bridge.d.ts.map

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

package/dist/bridges/equation-bridge.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Equation Bridge Interface
+ *
+ * Defines the contract for equation parsing (OMML and LaTeX).
+ * This interface abstracts the equation parsers from the rest of the engine,
+ * enabling:
+ * - Parser access without direct internal module imports
+ * - Caching of parsed expressions
+ * - Error handling and normalization
+ * - Platform-agnostic API
+ *
+ * ARCHITECTURE: Bridge Pattern (Section 9 of Architecture Checklist)
+ * - Interface defined in contracts (this file)
+ * - Implementation in engine/src/state/bridges/equation-bridge.ts
+ * - Access via ctx.equationBridge from coordinators
+ *
+ * @see engine/src/state/bridges/equation-bridge.ts - Implementation
+ * @see plans/active/excel-parity/equation/README.md - Equation feature plans
+ */
+import type { EquationParseError, MathNode, Result } from '../equation';
+/**
+ * Bridge interface for equation parsing.
+ *
+ * This interface provides all the methods needed by the engine to
+ * parse equations from OMML (file import) and LaTeX (user input).
+ *
+ * NOTE: Both parseOmml() and parseLatex() are defined here upfront
+ * to enable parallel development of the two parsers (Wave 2).
+ * Each parser implementation can be developed independently
+ * against this shared contract.
+ */
+export interface IEquationBridge {
+    /**
+     * Parse OMML XML string to MathNode AST.
+     *
+     * Used for importing equations from XLSX files.
+     * OMML is the Office Math Markup Language defined in ECMA-376.
+     *
+     * @param omml - OMML XML string (e.g., "<m:oMath>...</m:oMath>")
+     * @returns Result with MathNode[] AST or ParseError
+     *
+     * @example
+     * ```typescript
+     * const result = ctx.equationBridge.parseOmml('<m:oMath><m:f>...</m:f></m:oMath>');
+     * if (result.ok) {
+     *   // result.value is MathNode[] AST
+     * } else {
+     *   // result.error is ParseError
+     * }
+     * ```
+     */
+    parseOmml(omml: string): Result<MathNode[], EquationParseError>;
+    /**
+     * Parse LaTeX string to MathNode AST.
+     *
+     * Used for user input in the Equation Editor dialog.
+     * Supports a subset of LaTeX math syntax sufficient for common equations.
+     *
+     * @param latex - LaTeX math string (e.g., "\\frac{1}{2}")
+     * @returns Result with MathNode[] AST or ParseError
+     *
+     * @example
+     * ```typescript
+     * const result = ctx.equationBridge.parseLatex('\\frac{a}{b}');
+     * if (result.ok) {
+     *   // result.value is MathNode[] AST
+     * } else {
+     *   // result.error is ParseError
+     * }
+     * ```
+     */
+    parseLatex(latex: string): Result<MathNode[], EquationParseError>;
+}
+//# sourceMappingURL=equation-bridge.d.ts.map

package/dist/bridges/equation-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equation-bridge.d.ts","sourceRoot":"","sources":["../../src/bridges/equation-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAMxE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAK9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,kBAAkB,CAAC,CAAC;IAMhE;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,kBAAkB,CAAC,CAAC;CASnE"}

package/dist/bridges/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bridge Interfaces
+ *
+ * This module defines the contract interfaces for bridges that connect
+ * the spreadsheet engine to external computation engines.
+ *
+ * Bridge interfaces enable:
+ * - Clean boundaries between engine and external packages
+ * - Dependency injection for testing
+ * - Independent package extraction
+ *
+ * @see plans/active/refactor/05a-extraction-prerequisites.md - Task 2
+ */
+export type { IPivotBridge, PivotCacheStats, PivotResultCallback, } from './pivot-bridge';
+export type { IPivotEngine } from '../data/pivot';
+export type { CellWithErrors, ISchemaBridge, SchemaValidationOptions, ValidationErrorSummary, ValidationRecalcAnnotation, } from './schema-bridge';
+export type { ISchemaRegistry, ISchemaValidator } from '../core/schema';
+export type { ILocaleBridge, LocaleNormalizationResult, PartialCellFormat, } from './locale-bridge';
+export type { ChartBounds, ChartDataResult, ChartDataRow, ChartError, ChartErrorCode, ChartMark, IChartBridge, } from './chart-bridge';
+export type { IInkRecognitionBridge, RecognitionThresholds, ShapeRecognitionResult, TextRecognitionResult, } from './ink-recognition-bridge';
+export { DEFAULT_RECOGNITION_THRESHOLDS } from './ink-recognition-bridge';
+export type { ComputedLayoutCache, ISmartArtBridge, NodeMoveDirection, NodePosition, } from './smartart-bridge';
+export type { IEquationBridge, } from './equation-bridge';
+export type { IWordArtRenderingBridge } from './wordart-bridge';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridges/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,YAAY,EAEV,YAAY,EAEZ,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAMlD,YAAY,EAEV,cAAc,EAEd,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAMxE,YAAY,EAEV,aAAa,EAEb,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAMzB,YAAY,EAEV,WAAW,EACX,eAAe,EACf,YAAY,EACZ,UAAU,EACV,cAAc,EACd,SAAS,EAET,YAAY,GACb,MAAM,gBAAgB,CAAC;AAMxB,YAAY,EAEV,qBAAqB,EAErB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAM1E,YAAY,EAEV,mBAAmB,EAEnB,eAAe,EACf,iBAAiB,EACjB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EAEV,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC"}