@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/apps/api.d.ts

@@ -0,0 +1,519 @@
+/**
+ * App Kernel API - Interface Definition
+ *
+ * This is THE contract between apps and the kernel. Apps import this interface
+ * and receive an implementation from the Shell host.
+ *
+ * The API is organized into sub-APIs for different domains:
+ * - tables: Table CRUD operations
+ * - columns: Column CRUD operations
+ * - records: Record CRUD operations
+ * - relations: Relation traversal
+ * - events: Subscribe to data changes
+ *
+ * @see plans/active/os-refactor/PHASE-F-APPS.md
+ */
+import type { AppCellValue, AppColumnId, AppColumnInfo, AppColumnSchema, AppQueryOptions, AppRecord, AppTableId, AppTableInfo, AppTableSchema, RecordId, Unsubscribe } from './types';
+import type { IUndoService } from '../services';
+import type { AppInstance, TableBinding } from './bindings';
+/**
+ * Event payload for record changes.
+ */
+export interface RecordChangeEvent {
+    type: 'created' | 'updated' | 'deleted';
+    tableId: AppTableId;
+    recordId: RecordId;
+    /** For 'updated', the fields that changed */
+    changedFields?: (AppColumnId | string)[];
+    /** For 'created' and 'updated', the new record */
+    record?: AppRecord;
+}
+/**
+ * Event payload for table schema changes.
+ */
+export interface TableSchemaChangeEvent {
+    type: 'columnAdded' | 'columnRemoved' | 'columnRenamed' | 'columnTypeChanged' | 'tableRenamed';
+    tableId: AppTableId;
+    columnId?: AppColumnId;
+    oldName?: string;
+    newName?: string;
+}
+/**
+ * Handler for record change events.
+ */
+export type RecordChangeHandler = (event: RecordChangeEvent) => void;
+/**
+ * Handler for table schema change events.
+ */
+export type TableSchemaChangeHandler = (event: TableSchemaChangeEvent) => void;
+/**
+ * API for table operations.
+ */
+export interface IAppTablesAPI {
+    /**
+     * Get a table by ID.
+     * @param tableId - Table identifier
+     * @returns Table info or null if not found
+     */
+    get(tableId: AppTableId): Promise<AppTableInfo | null>;
+    /**
+     * Find a table by name.
+     * @param name - Table name
+     * @returns Table info or null if not found
+     */
+    findByName(name: string): Promise<AppTableInfo | null>;
+    /**
+     * List all tables.
+     * @returns Array of table info
+     */
+    list(): Promise<AppTableInfo[]>;
+    /**
+     * Create a new table.
+     * @param schema - Table schema
+     * @param options - Creation options
+     * @returns Created table info
+     */
+    create(schema: AppTableSchema, options?: {
+        /** Sheet to create table in (creates new sheet if not specified) */
+        sheetId?: string;
+        /** Starting cell (A1 notation, defaults to A1) */
+        startCell?: string;
+    }): Promise<AppTableInfo>;
+    /**
+     * Rename a table.
+     * @param tableId - Table identifier
+     * @param newName - New table name
+     */
+    rename(tableId: AppTableId, newName: string): Promise<void>;
+    /**
+     * Delete a table.
+     * Note: This removes the table definition, not the underlying data.
+     * @param tableId - Table identifier
+     */
+    delete(tableId: AppTableId): Promise<void>;
+}
+/**
+ * API for column operations.
+ */
+export interface IAppColumnsAPI {
+    /**
+     * Get column info by ID.
+     * @param tableId - Table identifier
+     * @param columnId - Column identifier
+     * @returns Column info or null if not found
+     */
+    get(tableId: AppTableId, columnId: AppColumnId): Promise<AppColumnInfo | null>;
+    /**
+     * Find a column by name.
+     * @param tableId - Table identifier
+     * @param name - Column name
+     * @returns Column info or null if not found
+     */
+    findByName(tableId: AppTableId, name: string): Promise<AppColumnInfo | null>;
+    /**
+     * List all columns in a table.
+     * @param tableId - Table identifier
+     * @returns Array of column info
+     */
+    list(tableId: AppTableId): Promise<AppColumnInfo[]>;
+    /**
+     * Add a new column to a table.
+     * @param tableId - Table identifier
+     * @param schema - Column schema
+     * @param options - Creation options
+     * @returns Created column info
+     */
+    create(tableId: AppTableId, schema: AppColumnSchema, options?: {
+        /** Insert at specific position (0-indexed, defaults to end) */
+        index?: number;
+    }): Promise<AppColumnInfo>;
+    /**
+     * Update a column's schema.
+     * @param tableId - Table identifier
+     * @param columnId - Column identifier
+     * @param updates - Partial schema updates
+     */
+    update(tableId: AppTableId, columnId: AppColumnId, updates: Partial<AppColumnSchema>): Promise<void>;
+    /**
+     * Rename a column.
+     * @param tableId - Table identifier
+     * @param columnId - Column identifier
+     * @param newName - New column name
+     */
+    rename(tableId: AppTableId, columnId: AppColumnId, newName: string): Promise<void>;
+    /**
+     * Delete a column.
+     * @param tableId - Table identifier
+     * @param columnId - Column identifier
+     */
+    delete(tableId: AppTableId, columnId: AppColumnId): Promise<void>;
+}
+/**
+ * API for record (row) operations.
+ */
+export interface IAppRecordsAPI {
+    /**
+     * Get a single record by ID.
+     * @param tableId - Table identifier
+     * @param recordId - Record identifier
+     * @returns Record or null if not found
+     */
+    get(tableId: AppTableId, recordId: RecordId): Promise<AppRecord | null>;
+    /**
+     * List records with optional filtering, sorting, and pagination.
+     * @param tableId - Table identifier
+     * @param options - Query options
+     * @returns Array of records
+     */
+    list(tableId: AppTableId, options?: AppQueryOptions): Promise<AppRecord[]>;
+    /**
+     * Create a new record.
+     * @param tableId - Table identifier
+     * @param values - Field values (by column name or ID)
+     * @returns Created record
+     */
+    create(tableId: AppTableId, values: Record<string, AppCellValue>): Promise<AppRecord>;
+    /**
+     * Update a record.
+     * @param tableId - Table identifier
+     * @param recordId - Record identifier
+     * @param values - Field values to update (by column name or ID)
+     * @returns Updated record
+     */
+    update(tableId: AppTableId, recordId: RecordId, values: Record<string, AppCellValue>): Promise<AppRecord>;
+    /**
+     * Delete a record.
+     * LOAD-BEARING: This MUST actually remove the row from the table.
+     * @param tableId - Table identifier
+     * @param recordId - Record identifier
+     */
+    delete(tableId: AppTableId, recordId: RecordId): Promise<void>;
+    /**
+     * Batch create multiple records.
+     * More efficient than calling create() in a loop.
+     * @param tableId - Table identifier
+     * @param records - Array of field value objects
+     * @returns Array of created records
+     */
+    createBatch(tableId: AppTableId, records: Record<string, AppCellValue>[]): Promise<AppRecord[]>;
+    /**
+     * Batch update multiple records.
+     * @param tableId - Table identifier
+     * @param updates - Array of { id, values } objects
+     * @returns Array of updated records
+     */
+    updateBatch(tableId: AppTableId, updates: Array<{
+        id: RecordId;
+        values: Record<string, AppCellValue>;
+    }>): Promise<AppRecord[]>;
+    /**
+     * Batch delete multiple records.
+     * @param tableId - Table identifier
+     * @param recordIds - Array of record IDs to delete
+     */
+    deleteBatch(tableId: AppTableId, recordIds: RecordId[]): Promise<void>;
+}
+/**
+ * Relation link between records.
+ */
+export interface RelationLink {
+    /** Source table ID */
+    sourceTableId: AppTableId;
+    /** Source record ID */
+    sourceRecordId: RecordId;
+    /** Relation column ID in source table */
+    relationColumnId: AppColumnId;
+    /** Target table ID */
+    targetTableId: AppTableId;
+    /** Target record ID */
+    targetRecordId: RecordId;
+}
+/**
+ * API for relation traversal.
+ */
+export interface IAppRelationsAPI {
+    /**
+     * Get related records through a relation column.
+     * @param tableId - Source table ID
+     * @param recordId - Source record ID
+     * @param relationColumnId - Relation column ID
+     * @returns Array of related records
+     */
+    getRelated(tableId: AppTableId, recordId: RecordId, relationColumnId: AppColumnId): Promise<AppRecord[]>;
+    /**
+     * Get all records that link TO this record (reverse lookup).
+     * @param tableId - Target table ID
+     * @param recordId - Target record ID
+     * @param options - Optional filter by source table/column
+     * @returns Array of records that reference this record
+     */
+    getBacklinks(tableId: AppTableId, recordId: RecordId, options?: {
+        sourceTableId?: AppTableId;
+        sourceColumnId?: AppColumnId;
+    }): Promise<AppRecord[]>;
+    /**
+     * Link two records via a relation column.
+     * @param sourceTableId - Source table ID
+     * @param sourceRecordId - Source record ID
+     * @param relationColumnId - Relation column ID in source table
+     * @param targetRecordId - Target record ID to link to
+     */
+    link(sourceTableId: AppTableId, sourceRecordId: RecordId, relationColumnId: AppColumnId, targetRecordId: RecordId): Promise<void>;
+    /**
+     * Unlink two records.
+     * @param sourceTableId - Source table ID
+     * @param sourceRecordId - Source record ID
+     * @param relationColumnId - Relation column ID
+     * @param targetRecordId - Target record ID to unlink
+     */
+    unlink(sourceTableId: AppTableId, sourceRecordId: RecordId, relationColumnId: AppColumnId, targetRecordId: RecordId): Promise<void>;
+}
+/**
+ * API for subscribing to data changes.
+ */
+export interface IAppEventsAPI {
+    /**
+     * Subscribe to record changes in a table.
+     * @param tableId - Table to watch
+     * @param handler - Change handler
+     * @returns Unsubscribe function
+     */
+    onRecordChange(tableId: AppTableId, handler: RecordChangeHandler): Unsubscribe;
+    /**
+     * Subscribe to table schema changes.
+     * @param tableId - Table to watch
+     * @param handler - Change handler
+     * @returns Unsubscribe function
+     */
+    onSchemaChange(tableId: AppTableId, handler: TableSchemaChangeHandler): Unsubscribe;
+    /**
+     * Subscribe to changes on a specific record.
+     * @param tableId - Table ID
+     * @param recordId - Record ID
+     * @param handler - Change handler
+     * @returns Unsubscribe function
+     */
+    onRecordFieldChange(tableId: AppTableId, recordId: RecordId, handler: (fieldId: AppColumnId, value: AppCellValue) => void): Unsubscribe;
+}
+/**
+ * Clipboard payload for cross-app copy/paste.
+ * Simplified version for apps - the kernel manages the full payload internally.
+ */
+export interface AppClipboardPayload {
+    /**
+     * Cell values as 2D array (for spreadsheet paste).
+     * Each inner array is a row of values.
+     */
+    cells: AppCellValue[][];
+    /**
+     * Plain text representation (TSV format).
+     * Used for pasting into external apps.
+     */
+    text: string;
+    /**
+     * Table context for smart paste (optional).
+     */
+    tableContext?: {
+        /** Source table ID */
+        sourceTableId: AppTableId;
+        /** Record IDs being copied */
+        recordIds: RecordId[];
+        /** Column names in order */
+        columnNames: string[];
+    };
+}
+/**
+ * Clipboard state snapshot for apps.
+ */
+export interface AppClipboardSnapshot {
+    /** Whether clipboard has data */
+    hasData: boolean;
+    /** Current operation (copy/cut/null) */
+    operation: 'copy' | 'cut' | null;
+}
+/**
+ * API for managing app data bindings.
+ * Apps bind to tables rather than owning them directly.
+ *
+ * @see plans/archive/os-refactor/APP-DATA-BINDING-PLAN.md
+ */
+export interface IAppBindingsAPI {
+    /**
+     * Get all instances for an app type.
+     * @param appId - App identifier from manifest
+     * @returns Array of app instances
+     */
+    getInstances(appId: string): AppInstance[];
+    /**
+     * Get a specific instance.
+     * @param instanceId - Instance identifier
+     * @returns App instance or null if not found
+     */
+    getInstance(instanceId: string): AppInstance | null;
+    /**
+     * Create a new app instance.
+     * @param appId - App identifier from manifest
+     * @param name - User-given name for this instance
+     * @returns Created app instance
+     */
+    createInstance(appId: string, name: string): AppInstance;
+    /**
+     * Update instance bindings.
+     * @param instanceId - Instance identifier
+     * @param bindings - New bindings to set
+     */
+    updateBindings(instanceId: string, bindings: Record<string, TableBinding>): void;
+    /**
+     * Mark instance setup as complete.
+     * @param instanceId - Instance identifier
+     */
+    completeSetup(instanceId: string): void;
+    /**
+     * Delete an instance.
+     * @param instanceId - Instance identifier
+     */
+    deleteInstance(instanceId: string): void;
+}
+/**
+ * API for clipboard operations.
+ * Apps can copy records to clipboard for cross-app paste.
+ */
+export interface IAppClipboardAPI {
+    /**
+     * Copy data to clipboard.
+     * @param payload - Data to copy
+     */
+    copy(payload: AppClipboardPayload): void;
+    /**
+     * Cut data to clipboard (single-use).
+     * @param payload - Data to cut
+     */
+    cut(payload: AppClipboardPayload): void;
+    /**
+     * Get current clipboard state.
+     */
+    getSnapshot(): AppClipboardSnapshot;
+    /**
+     * Get the current clipboard payload data.
+     * Returns null if clipboard is empty.
+     */
+    getPayload(): AppClipboardPayload | null;
+    /**
+     * Clear clipboard.
+     */
+    clear(): void;
+    /**
+     * Subscribe to clipboard state changes.
+     * @param handler - Called when clipboard state changes
+     */
+    subscribe(handler: (snapshot: AppClipboardSnapshot) => void): Unsubscribe;
+}
+/**
+ * The App Kernel API.
+ *
+ * This is the main interface that apps use to interact with the spreadsheet kernel.
+ * Apps receive an implementation of this interface from the Shell host.
+ *
+ * Design:
+ * - Organized into logical sub-APIs (tables, columns, records, etc.)
+ * - Uses opaque ID types (apps don't see internal CellId/RowId/ColId)
+ * - Provides dual access patterns (by name and by ID)
+ *
+ * Example usage:
+ * ```typescript
+ * // Get a table by name
+ * const deals = api.tables.findByName('Deals');
+ *
+ * // Query records with filtering and sorting
+ * const openDeals = api.records.list(deals.id, {
+ *   filter: { conditions: [{ field: 'Status', operator: 'equals', value: 'Open' }] },
+ *   sort: [{ field: 'Value', direction: 'desc' }]
+ * });
+ *
+ * // Create a new record
+ * const newDeal = api.records.create(deals.id, {
+ *   'Name': 'Acme Corp Deal',
+ *   'Value': 50000,
+ *   'Status': 'Open'
+ * });
+ *
+ * // Subscribe to changes
+ * const unsubscribe = api.events.onRecordChange(deals.id, (event) => {
+ *   console.log('Record changed:', event.recordId, event.type);
+ * });
+ * ```
+ */
+export interface IAppKernelAPI {
+    /** Table operations */
+    readonly tables: IAppTablesAPI;
+    /** Column operations */
+    readonly columns: IAppColumnsAPI;
+    /** Record operations */
+    readonly records: IAppRecordsAPI;
+    /** Relation traversal */
+    readonly relations: IAppRelationsAPI;
+    /** Event subscriptions */
+    readonly events: IAppEventsAPI;
+    /** Clipboard operations (cross-app copy/paste) */
+    readonly clipboard?: IAppClipboardAPI;
+    /**
+     * App data bindings management.
+     * Optional for backward compatibility - may be undefined if bindings not yet implemented.
+     * @see plans/archive/os-refactor/APP-DATA-BINDING-PLAN.md
+     */
+    readonly bindings?: IAppBindingsAPI;
+    /**
+     * Undo/redo service for reverting changes.
+     * May be undefined if undo service is not available.
+     */
+    readonly undo?: IUndoService;
+    /**
+     * Execute multiple operations in a single transaction.
+     * All changes are batched as a single undo step.
+     * @param fn - Function containing operations to batch
+     * @param description - Description for undo history
+     */
+    batch<T>(fn: () => T, description?: string): T;
+}
+/**
+ * App metadata provided to the kernel.
+ */
+export interface AppManifest {
+    /** Unique app identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** App version */
+    version: string;
+    /** Icon (emoji or icon identifier) */
+    icon?: string;
+    /** Description */
+    description?: string;
+    /** Author */
+    author?: string;
+    /** Tables this app manages (for ensureAppTables) */
+    managedTables?: AppTableSchema[];
+    /**
+     * Views contributed by this app.
+     * These views appear in view tabs for applicable tables.
+     * @see contracts/src/apps/views.ts
+     */
+    views?: import('./views').ViewContribution[];
+}
+/**
+ * Context provided to an app when it starts.
+ */
+export interface AppContext {
+    /** App's manifest */
+    manifest: AppManifest;
+    /** The App Kernel API */
+    api: IAppKernelAPI;
+    /**
+     * Ensure app's managed tables exist.
+     * Creates tables from manifest.managedTables if they don't exist.
+     * Returns existing tables if they already exist (idempotent).
+     * @returns Map of table name to table ID
+     */
+    ensureAppTables(): Map<string, AppTableId>;
+}
+//# sourceMappingURL=api.d.ts.map

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

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

package/dist/apps/bindings.d.ts

@@ -0,0 +1,72 @@
+/**
+ * App Data Binding Types
+ *
+ * Apps bind to tables, they don't own tables. This enables:
+ * - Fresh start: App creates new tables on a dedicated sheet
+ * - Existing data: App binds to user's existing tables with column mappings
+ *
+ * @see plans/archive/os-refactor/APP-DATA-BINDING-PLAN.md
+ */
+import type { AppColumnId, AppTableId, AppTableInfo } from './types';
+/**
+ * Persisted app instance - represents one "installation" of an app with its data bindings.
+ * One app type can have multiple instances (e.g., "Sales CRM" and "Recruiting CRM").
+ *
+ * Stored in WorkbookSettings.appInstances and persisted with the document.
+ */
+export interface AppInstance {
+    /** Unique instance ID */
+    instanceId: string;
+    /** App type from manifest */
+    appId: string;
+    /** User-given name for this instance */
+    name: string;
+    /** Table bindings - maps app's logical tables to actual tables */
+    bindings: Record<string, TableBinding>;
+    /** Whether setup is complete */
+    setupComplete: boolean;
+    /** Created timestamp (Unix ms) */
+    createdAt: number;
+}
+/**
+ * Binding from an app's logical table to an actual table in the workbook.
+ */
+export interface TableBinding {
+    /** The actual table ID in the workbook (null = needs setup) */
+    tableId: AppTableId | null;
+    /** Column mappings: app's logical column name -> actual column */
+    columnMappings: Record<string, ColumnMapping>;
+    /** Whether this table was created by the app (vs bound to existing) */
+    isManaged: boolean;
+}
+/**
+ * Mapping from an app's logical column to an actual column.
+ */
+export interface ColumnMapping {
+    /** Target column ID */
+    columnId: AppColumnId;
+    /** Target column name (for display) */
+    columnName: string;
+}
+/**
+ * Resolved bindings passed to app components at runtime.
+ * All table IDs are guaranteed to exist.
+ */
+export interface ResolvedBindings {
+    /** Map of logical table name -> resolved table info */
+    tables: Record<string, ResolvedTableBinding>;
+}
+/**
+ * A fully resolved table binding with table info loaded.
+ */
+export interface ResolvedTableBinding {
+    /** Table ID */
+    tableId: AppTableId;
+    /** Table info */
+    table: AppTableInfo;
+    /** Map of logical column name -> actual column ID */
+    columns: Record<string, AppColumnId>;
+    /** Whether this was auto-created (managed) */
+    isManaged: boolean;
+}
+//# sourceMappingURL=bindings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/apps/bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAMrE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IAEd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAEvC,gCAAgC;IAChC,aAAa,EAAE,OAAO,CAAC;IAEvB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAE3B,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAE9C,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,QAAQ,EAAE,WAAW,CAAC;IAEtB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,eAAe;IACf,OAAO,EAAE,UAAU,CAAC;IAEpB,iBAAiB;IACjB,KAAK,EAAE,YAAY,CAAC;IAEpB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAErC,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;CACpB"}

package/dist/apps/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * App Kernel API - Public Exports
+ *
+ * This module exports the types and interfaces that apps use to interact
+ * with the spreadsheet kernel.
+ *
+ * @see plans/active/os-refactor/PHASE-F-APPS.md
+ */
+export type { AppCellError, AppCellValue, AppCellValuePrimitive, AppColumnId, AppColumnInfo, AppColumnSchema, AppColumnType, AppColumnTypeKind, AppFilter, AppFilterCondition, AppFilterOperator, AppQueryOptions, AppRecord, AppSelectOption, AppSortConfig, AppSortDirection, AppTableId, AppTableInfo, AppTableSchema, RecordId, Unsubscribe, } from './types';
+export type { AppClipboardPayload, AppClipboardSnapshot, AppContext, AppManifest, IAppBindingsAPI, IAppClipboardAPI, IAppColumnsAPI, IAppEventsAPI, IAppKernelAPI, IAppRecordsAPI, IAppRelationsAPI, IAppTablesAPI, RecordChangeEvent, RecordChangeHandler, RelationLink, TableSchemaChangeEvent, TableSchemaChangeHandler, } from './api';
+export type { AppInstance, ColumnMapping, ResolvedBindings, ResolvedTableBinding, TableBinding, } from './bindings';
+export type { ViewContribution, ViewProps } from './views';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/apps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACV,YAAY,EAEZ,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,aAAa,EAEb,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAElB,iBAAiB,EACjB,eAAe,EAEf,SAAS,EACT,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,UAAU,EAEV,YAAY,EACZ,cAAc,EAEd,QAAQ,EAER,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,YAAY,EAEV,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EAEV,WAAW,EAEX,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,aAAa,EAEb,aAAa,EACb,cAAc,EACd,gBAAgB,EAEhB,aAAa,EAEb,iBAAiB,EACjB,mBAAmB,EAEnB,YAAY,EACZ,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,OAAO,CAAC;AAGf,YAAY,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}