digital-tools 2.0.2 → 2.1.1

package/src/entities/spreadsheet.js

@@ -0,0 +1,1341 @@
+/**
+ * Spreadsheet Entity Types (Nouns)
+ *
+ * Semantic type definitions for spreadsheets that support
+ * Google Sheets, Microsoft Excel/XLSX, and CSV formats.
+ * Each entity defines:
+ * - Properties: The data fields
+ * - Actions: Operations that can be performed (Verbs)
+ * - Events: State changes that occur
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Spreadsheet
+// =============================================================================
+/**
+ * Spreadsheet entity
+ *
+ * Represents a spreadsheet workbook containing one or more sheets.
+ * Supports Google Sheets, Microsoft Excel/XLSX, and CSV formats.
+ */
+export const Spreadsheet = {
+    singular: 'spreadsheet',
+    plural: 'spreadsheets',
+    description: 'A spreadsheet workbook for organizing and analyzing data',
+    properties: {
+        // Identity
+        title: {
+            type: 'string',
+            description: 'Spreadsheet title',
+        },
+        slug: {
+            type: 'string',
+            optional: true,
+            description: 'URL-friendly identifier',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Spreadsheet description',
+        },
+        // Format
+        format: {
+            type: 'string',
+            description: 'Spreadsheet format: xlsx, gsheet, csv, tsv, ods',
+            examples: ['xlsx', 'gsheet', 'csv', 'tsv', 'ods'],
+        },
+        fileSize: {
+            type: 'number',
+            optional: true,
+            description: 'File size in bytes',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Spreadsheet status: draft, active, archived',
+            examples: ['draft', 'active', 'archived'],
+        },
+        visibility: {
+            type: 'string',
+            description: 'Visibility: private, internal, public',
+            examples: ['private', 'internal', 'public'],
+        },
+        // Structure
+        sheetCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of sheets in the workbook',
+        },
+        totalRows: {
+            type: 'number',
+            optional: true,
+            description: 'Total rows across all sheets',
+        },
+        totalColumns: {
+            type: 'number',
+            optional: true,
+            description: 'Total columns across all sheets',
+        },
+        totalCells: {
+            type: 'number',
+            optional: true,
+            description: 'Total cells across all sheets',
+        },
+        // Settings
+        locale: {
+            type: 'string',
+            optional: true,
+            description: 'Locale for number and date formatting',
+        },
+        timezone: {
+            type: 'string',
+            optional: true,
+            description: 'Timezone for date/time values',
+        },
+        defaultDateFormat: {
+            type: 'string',
+            optional: true,
+            description: 'Default date format string',
+        },
+        defaultNumberFormat: {
+            type: 'string',
+            optional: true,
+            description: 'Default number format string',
+        },
+        currency: {
+            type: 'string',
+            optional: true,
+            description: 'Default currency code',
+        },
+        // Recalculation
+        autoRecalculate: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether formulas auto-recalculate',
+        },
+        iterativeCalculation: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether iterative calculation is enabled',
+        },
+        maxIterations: {
+            type: 'number',
+            optional: true,
+            description: 'Maximum calculation iterations',
+        },
+        // Collaboration
+        allowComments: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether comments are enabled',
+        },
+        shareMode: {
+            type: 'string',
+            optional: true,
+            description: 'Sharing mode: view, comment, edit',
+            examples: ['view', 'comment', 'edit'],
+        },
+        allowDownload: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether download is allowed',
+        },
+        allowCopy: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether copying is allowed',
+        },
+        allowPrint: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether printing is allowed',
+        },
+        // Protection
+        protected: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether spreadsheet is protected',
+        },
+        password: {
+            type: 'string',
+            optional: true,
+            description: 'Protection password',
+        },
+        // Templates
+        isTemplate: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether this is a template',
+        },
+        templateId: {
+            type: 'string',
+            optional: true,
+            description: 'ID of template this was created from',
+        },
+        templateCategory: {
+            type: 'string',
+            optional: true,
+            description: 'Template category',
+            examples: ['budget', 'schedule', 'tracker', 'analysis', 'report'],
+        },
+        // Integration
+        externalId: {
+            type: 'string',
+            optional: true,
+            description: 'External system ID (Google Sheets ID, OneDrive ID, etc.)',
+        },
+        externalUrl: {
+            type: 'url',
+            optional: true,
+            description: 'URL in external system',
+        },
+        syncEnabled: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether sync is enabled',
+        },
+        lastSyncedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last sync timestamp',
+        },
+        dataSource: {
+            type: 'json',
+            optional: true,
+            description: 'External data source configuration',
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for categorization',
+        },
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'Spreadsheet category',
+        },
+        folder: {
+            type: 'string',
+            optional: true,
+            description: 'Folder or workspace path',
+        },
+        customMetadata: {
+            type: 'json',
+            optional: true,
+            description: 'Custom metadata fields',
+        },
+        // Analytics
+        viewCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of views',
+        },
+        editCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of edits',
+        },
+        downloadCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of downloads',
+        },
+        lastViewedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last view timestamp',
+        },
+        lastEditedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last edit timestamp',
+        },
+    },
+    relationships: {
+        owner: {
+            type: 'Contact',
+            description: 'Spreadsheet owner',
+        },
+        creator: {
+            type: 'Contact',
+            description: 'User who created the spreadsheet',
+        },
+        lastEditor: {
+            type: 'Contact',
+            required: false,
+            description: 'User who last edited',
+        },
+        sheets: {
+            type: 'Sheet[]',
+            backref: 'spreadsheet',
+            description: 'Sheets in this workbook',
+        },
+        charts: {
+            type: 'Chart[]',
+            backref: 'spreadsheet',
+            description: 'Charts in the spreadsheet',
+        },
+        pivotTables: {
+            type: 'PivotTable[]',
+            backref: 'spreadsheet',
+            description: 'Pivot tables in the spreadsheet',
+        },
+        collaborators: {
+            type: 'Contact[]',
+            description: 'Users with access',
+        },
+    },
+    actions: [
+        'create',
+        'open',
+        'edit',
+        'save',
+        'saveAs',
+        'duplicate',
+        'rename',
+        'delete',
+        'restore',
+        'export',
+        'download',
+        'print',
+        'share',
+        'unshare',
+        'archive',
+        'unarchive',
+        'move',
+        'copy',
+        'protect',
+        'unprotect',
+        'addSheet',
+        'removeSheet',
+        'reorderSheets',
+        'makeTemplate',
+        'createFromTemplate',
+        'importData',
+        'exportData',
+        'refreshData',
+        'calculate',
+        'sort',
+        'filter',
+        'search',
+        'findAndReplace',
+        'insertChart',
+        'insertPivotTable',
+        'merge',
+        'split',
+        'freeze',
+        'unfreeze',
+        'hideSheet',
+        'unhideSheet',
+    ],
+    events: [
+        'created',
+        'opened',
+        'edited',
+        'saved',
+        'renamed',
+        'deleted',
+        'restored',
+        'exported',
+        'downloaded',
+        'printed',
+        'shared',
+        'unshared',
+        'archived',
+        'unarchived',
+        'moved',
+        'copied',
+        'protected',
+        'unprotected',
+        'sheetAdded',
+        'sheetRemoved',
+        'sheetReordered',
+        'dataImported',
+        'dataExported',
+        'dataRefreshed',
+        'calculated',
+        'chartInserted',
+        'pivotTableInserted',
+        'collaboratorAdded',
+        'collaboratorRemoved',
+        'permissionChanged',
+        'synced',
+        'viewed',
+    ],
+};
+// =============================================================================
+// Sheet
+// =============================================================================
+/**
+ * Sheet entity
+ *
+ * Represents a single worksheet within a spreadsheet workbook.
+ */
+export const Sheet = {
+    singular: 'sheet',
+    plural: 'sheets',
+    description: 'A worksheet within a spreadsheet workbook',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Sheet name',
+        },
+        index: {
+            type: 'number',
+            description: 'Sheet position in workbook (0-based)',
+        },
+        sheetId: {
+            type: 'string',
+            optional: true,
+            description: 'Internal sheet identifier',
+        },
+        // Dimensions
+        rowCount: {
+            type: 'number',
+            description: 'Number of rows',
+        },
+        columnCount: {
+            type: 'number',
+            description: 'Number of columns',
+        },
+        frozenRows: {
+            type: 'number',
+            optional: true,
+            description: 'Number of frozen rows',
+        },
+        frozenColumns: {
+            type: 'number',
+            optional: true,
+            description: 'Number of frozen columns',
+        },
+        // Visibility
+        hidden: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether sheet is hidden',
+        },
+        veryHidden: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether sheet is very hidden (Excel)',
+        },
+        // Color and styling
+        tabColor: {
+            type: 'string',
+            optional: true,
+            description: 'Sheet tab color (hex)',
+        },
+        gridLinesVisible: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether grid lines are visible',
+        },
+        gridLinesColor: {
+            type: 'string',
+            optional: true,
+            description: 'Grid line color',
+        },
+        // Protection
+        protected: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether sheet is protected',
+        },
+        protectedRanges: {
+            type: 'json',
+            optional: true,
+            description: 'Protected cell ranges',
+        },
+        // Data
+        data: {
+            type: 'json',
+            optional: true,
+            description: 'Sheet data as 2D array or object',
+        },
+        hasHeaders: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether first row contains headers',
+        },
+        dataRange: {
+            type: 'string',
+            optional: true,
+            description: 'Range containing data (e.g., A1:Z100)',
+        },
+        // Filters and sorts
+        hasFilters: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether filters are applied',
+        },
+        filterRange: {
+            type: 'string',
+            optional: true,
+            description: 'Range with filters applied',
+        },
+        sortSpecs: {
+            type: 'json',
+            optional: true,
+            description: 'Active sort specifications',
+        },
+        // Named ranges
+        namedRanges: {
+            type: 'json',
+            optional: true,
+            description: 'Named ranges in this sheet',
+        },
+        // Conditional formatting
+        conditionalFormats: {
+            type: 'json',
+            optional: true,
+            description: 'Conditional formatting rules',
+        },
+        // Data validation
+        dataValidations: {
+            type: 'json',
+            optional: true,
+            description: 'Data validation rules by range',
+        },
+        // Metadata
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Sheet notes or description',
+        },
+        metadata: {
+            type: 'json',
+            optional: true,
+            description: 'Custom metadata',
+        },
+    },
+    relationships: {
+        spreadsheet: {
+            type: 'Spreadsheet',
+            backref: 'sheets',
+            description: 'Parent spreadsheet',
+        },
+        charts: {
+            type: 'Chart[]',
+            backref: 'sheet',
+            description: 'Charts in this sheet',
+        },
+        pivotTables: {
+            type: 'PivotTable[]',
+            backref: 'sheet',
+            description: 'Pivot tables in this sheet',
+        },
+    },
+    actions: [
+        'create',
+        'rename',
+        'delete',
+        'duplicate',
+        'move',
+        'hide',
+        'unhide',
+        'protect',
+        'unprotect',
+        'clear',
+        'clearFormats',
+        'clearData',
+        'insertRow',
+        'insertRows',
+        'deleteRow',
+        'deleteRows',
+        'insertColumn',
+        'insertColumns',
+        'deleteColumn',
+        'deleteColumns',
+        'freeze',
+        'unfreeze',
+        'sort',
+        'filter',
+        'clearFilter',
+        'autoResize',
+        'setTabColor',
+        'addChart',
+        'addPivotTable',
+        'addConditionalFormat',
+        'addDataValidation',
+        'addNamedRange',
+        'merge',
+        'unmerge',
+        'format',
+        'copyFormat',
+        'pasteFormat',
+    ],
+    events: [
+        'created',
+        'renamed',
+        'deleted',
+        'duplicated',
+        'moved',
+        'hidden',
+        'unhidden',
+        'protected',
+        'unprotected',
+        'cleared',
+        'rowInserted',
+        'rowDeleted',
+        'columnInserted',
+        'columnDeleted',
+        'frozen',
+        'unfrozen',
+        'sorted',
+        'filtered',
+        'filterCleared',
+        'chartAdded',
+        'pivotTableAdded',
+        'conditionalFormatAdded',
+        'dataValidationAdded',
+        'namedRangeAdded',
+        'cellsMerged',
+        'cellsUnmerged',
+        'formatted',
+    ],
+};
+// =============================================================================
+// Cell
+// =============================================================================
+/**
+ * Cell entity
+ *
+ * Represents a single cell in a spreadsheet.
+ */
+export const Cell = {
+    singular: 'cell',
+    plural: 'cells',
+    description: 'A single cell in a spreadsheet',
+    properties: {
+        // Location
+        row: {
+            type: 'number',
+            description: 'Row index (0-based)',
+        },
+        column: {
+            type: 'number',
+            description: 'Column index (0-based)',
+        },
+        address: {
+            type: 'string',
+            optional: true,
+            description: 'Cell address (e.g., A1, B2)',
+        },
+        // Value
+        value: {
+            type: 'string',
+            optional: true,
+            description: 'Display value',
+        },
+        rawValue: {
+            type: 'string',
+            optional: true,
+            description: 'Raw value before formatting',
+        },
+        dataType: {
+            type: 'string',
+            optional: true,
+            description: 'Data type: string, number, boolean, date, formula, error',
+            examples: ['string', 'number', 'boolean', 'date', 'formula', 'error', 'null'],
+        },
+        // Formula
+        formula: {
+            type: 'string',
+            optional: true,
+            description: 'Cell formula',
+        },
+        hasFormula: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether cell contains a formula',
+        },
+        // Formatting
+        format: {
+            type: 'json',
+            optional: true,
+            description: 'Cell format configuration',
+        },
+        numberFormat: {
+            type: 'string',
+            optional: true,
+            description: 'Number format string',
+        },
+        fontFamily: {
+            type: 'string',
+            optional: true,
+            description: 'Font family',
+        },
+        fontSize: {
+            type: 'number',
+            optional: true,
+            description: 'Font size in points',
+        },
+        fontWeight: {
+            type: 'string',
+            optional: true,
+            description: 'Font weight: normal, bold',
+            examples: ['normal', 'bold'],
+        },
+        fontStyle: {
+            type: 'string',
+            optional: true,
+            description: 'Font style: normal, italic',
+            examples: ['normal', 'italic'],
+        },
+        textColor: {
+            type: 'string',
+            optional: true,
+            description: 'Text color (hex)',
+        },
+        backgroundColor: {
+            type: 'string',
+            optional: true,
+            description: 'Background color (hex)',
+        },
+        horizontalAlignment: {
+            type: 'string',
+            optional: true,
+            description: 'Horizontal alignment: left, center, right',
+            examples: ['left', 'center', 'right'],
+        },
+        verticalAlignment: {
+            type: 'string',
+            optional: true,
+            description: 'Vertical alignment: top, middle, bottom',
+            examples: ['top', 'middle', 'bottom'],
+        },
+        wrapText: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether text wraps',
+        },
+        // Borders
+        borders: {
+            type: 'json',
+            optional: true,
+            description: 'Border configuration',
+        },
+        // Validation
+        dataValidation: {
+            type: 'json',
+            optional: true,
+            description: 'Data validation rules',
+        },
+        isValid: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether value passes validation',
+        },
+        // Merge
+        isMerged: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether cell is part of merged range',
+        },
+        mergeRange: {
+            type: 'string',
+            optional: true,
+            description: 'Merged cell range',
+        },
+        // Notes and comments
+        note: {
+            type: 'string',
+            optional: true,
+            description: 'Cell note',
+        },
+        hasComment: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether cell has a comment',
+        },
+        // Links
+        hyperlink: {
+            type: 'url',
+            optional: true,
+            description: 'Hyperlink URL',
+        },
+        // Protection
+        locked: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether cell is locked',
+        },
+    },
+    relationships: {
+        sheet: {
+            type: 'Sheet',
+            description: 'Parent sheet',
+        },
+    },
+    actions: [
+        'setValue',
+        'setFormula',
+        'clear',
+        'clearFormat',
+        'format',
+        'merge',
+        'unmerge',
+        'lock',
+        'unlock',
+        'addNote',
+        'removeNote',
+        'addComment',
+        'addHyperlink',
+        'removeHyperlink',
+        'copy',
+        'cut',
+        'paste',
+        'validate',
+    ],
+    events: [
+        'valueChanged',
+        'formulaSet',
+        'cleared',
+        'formatted',
+        'merged',
+        'unmerged',
+        'locked',
+        'unlocked',
+        'noteAdded',
+        'noteRemoved',
+        'commentAdded',
+        'hyperlinkAdded',
+        'hyperlinkRemoved',
+        'copied',
+        'pasted',
+    ],
+};
+// =============================================================================
+// Range
+// =============================================================================
+/**
+ * Range entity
+ *
+ * Represents a range of cells in a spreadsheet.
+ */
+export const Range = {
+    singular: 'range',
+    plural: 'ranges',
+    description: 'A range of cells in a spreadsheet',
+    properties: {
+        // Location
+        startRow: {
+            type: 'number',
+            description: 'Starting row index (0-based)',
+        },
+        startColumn: {
+            type: 'number',
+            description: 'Starting column index (0-based)',
+        },
+        endRow: {
+            type: 'number',
+            description: 'Ending row index (0-based)',
+        },
+        endColumn: {
+            type: 'number',
+            description: 'Ending column index (0-based)',
+        },
+        address: {
+            type: 'string',
+            optional: true,
+            description: 'Range address (e.g., A1:B10)',
+        },
+        // Dimensions
+        rowCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of rows in range',
+        },
+        columnCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of columns in range',
+        },
+        cellCount: {
+            type: 'number',
+            optional: true,
+            description: 'Total number of cells',
+        },
+        // Data
+        values: {
+            type: 'json',
+            optional: true,
+            description: 'Cell values as 2D array',
+        },
+        formulas: {
+            type: 'json',
+            optional: true,
+            description: 'Cell formulas as 2D array',
+        },
+        // Named range
+        name: {
+            type: 'string',
+            optional: true,
+            description: 'Named range identifier',
+        },
+        isNamed: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether this is a named range',
+        },
+        // Format
+        format: {
+            type: 'json',
+            optional: true,
+            description: 'Range format configuration',
+        },
+        // Protection
+        protected: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether range is protected',
+        },
+    },
+    relationships: {
+        sheet: {
+            type: 'Sheet',
+            description: 'Parent sheet',
+        },
+    },
+    actions: [
+        'select',
+        'setValue',
+        'setValues',
+        'setFormula',
+        'setFormulas',
+        'clear',
+        'clearFormat',
+        'clearData',
+        'format',
+        'copy',
+        'cut',
+        'paste',
+        'merge',
+        'unmerge',
+        'sort',
+        'filter',
+        'protect',
+        'unprotect',
+        'autoFill',
+        'insertRows',
+        'insertColumns',
+        'deleteRows',
+        'deleteColumns',
+        'name',
+        'unname',
+    ],
+    events: [
+        'selected',
+        'valuesChanged',
+        'formulasSet',
+        'cleared',
+        'formatted',
+        'copied',
+        'pasted',
+        'merged',
+        'unmerged',
+        'sorted',
+        'filtered',
+        'protected',
+        'unprotected',
+        'autoFilled',
+        'rowsInserted',
+        'columnsInserted',
+        'rowsDeleted',
+        'columnsDeleted',
+        'named',
+        'unnamed',
+    ],
+};
+// =============================================================================
+// Chart
+// =============================================================================
+/**
+ * Chart entity
+ *
+ * Represents a chart or graph in a spreadsheet.
+ */
+export const Chart = {
+    singular: 'chart',
+    plural: 'charts',
+    description: 'A chart or graph visualizing spreadsheet data',
+    properties: {
+        // Identity
+        title: {
+            type: 'string',
+            description: 'Chart title',
+        },
+        subtitle: {
+            type: 'string',
+            optional: true,
+            description: 'Chart subtitle',
+        },
+        // Type
+        type: {
+            type: 'string',
+            description: 'Chart type',
+            examples: [
+                'line',
+                'bar',
+                'column',
+                'pie',
+                'scatter',
+                'area',
+                'combo',
+                'histogram',
+                'waterfall',
+                'candlestick',
+                'treemap',
+                'gauge',
+                'radar',
+            ],
+        },
+        subtype: {
+            type: 'string',
+            optional: true,
+            description: 'Chart subtype variant',
+        },
+        // Data source
+        dataRange: {
+            type: 'string',
+            description: 'Source data range',
+        },
+        hasHeaders: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether data includes headers',
+        },
+        series: {
+            type: 'json',
+            optional: true,
+            description: 'Data series configuration',
+        },
+        // Position and size
+        position: {
+            type: 'json',
+            optional: true,
+            description: 'Chart position on sheet',
+        },
+        width: {
+            type: 'number',
+            optional: true,
+            description: 'Chart width in pixels',
+        },
+        height: {
+            type: 'number',
+            optional: true,
+            description: 'Chart height in pixels',
+        },
+        // Axes
+        xAxis: {
+            type: 'json',
+            optional: true,
+            description: 'X-axis configuration',
+        },
+        yAxis: {
+            type: 'json',
+            optional: true,
+            description: 'Y-axis configuration',
+        },
+        secondaryAxis: {
+            type: 'json',
+            optional: true,
+            description: 'Secondary axis configuration',
+        },
+        // Legend
+        showLegend: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to show legend',
+        },
+        legendPosition: {
+            type: 'string',
+            optional: true,
+            description: 'Legend position: top, bottom, left, right',
+            examples: ['top', 'bottom', 'left', 'right'],
+        },
+        // Styling
+        theme: {
+            type: 'string',
+            optional: true,
+            description: 'Chart theme',
+        },
+        colors: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Custom colors for series',
+        },
+        backgroundColor: {
+            type: 'string',
+            optional: true,
+            description: 'Background color',
+        },
+        // Options
+        showDataLabels: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to show data labels',
+        },
+        showGridLines: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to show grid lines',
+        },
+        stacked: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether chart is stacked',
+        },
+        smooth: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to smooth line charts',
+        },
+        // Interaction
+        interactive: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether chart is interactive',
+        },
+        allowFiltering: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether filtering is allowed',
+        },
+        // Metadata
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Chart description',
+        },
+    },
+    relationships: {
+        spreadsheet: {
+            type: 'Spreadsheet',
+            backref: 'charts',
+            description: 'Parent spreadsheet',
+        },
+        sheet: {
+            type: 'Sheet',
+            backref: 'charts',
+            description: 'Sheet containing the chart',
+        },
+    },
+    actions: [
+        'create',
+        'edit',
+        'delete',
+        'duplicate',
+        'move',
+        'resize',
+        'refresh',
+        'changeType',
+        'updateData',
+        'export',
+        'copyImage',
+        'setTitle',
+        'setTheme',
+        'showLegend',
+        'hideLegend',
+        'addSeries',
+        'removeSeries',
+    ],
+    events: [
+        'created',
+        'edited',
+        'deleted',
+        'duplicated',
+        'moved',
+        'resized',
+        'refreshed',
+        'typeChanged',
+        'dataUpdated',
+        'exported',
+        'titleSet',
+        'themeSet',
+        'seriesAdded',
+        'seriesRemoved',
+    ],
+};
+// =============================================================================
+// PivotTable
+// =============================================================================
+/**
+ * PivotTable entity
+ *
+ * Represents a pivot table for data analysis and summarization.
+ */
+export const PivotTable = {
+    singular: 'pivot table',
+    plural: 'pivot tables',
+    description: 'A pivot table for analyzing and summarizing data',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Pivot table name',
+        },
+        // Source
+        sourceRange: {
+            type: 'string',
+            description: 'Source data range',
+        },
+        targetRange: {
+            type: 'string',
+            optional: true,
+            description: 'Target range for pivot table output',
+        },
+        // Configuration
+        rows: {
+            type: 'json',
+            description: 'Row field configuration',
+        },
+        columns: {
+            type: 'json',
+            optional: true,
+            description: 'Column field configuration',
+        },
+        values: {
+            type: 'json',
+            description: 'Value field configuration with aggregations',
+        },
+        filters: {
+            type: 'json',
+            optional: true,
+            description: 'Filter field configuration',
+        },
+        // Aggregation
+        aggregationFunctions: {
+            type: 'json',
+            optional: true,
+            description: 'Aggregation functions by field',
+        },
+        // Sorting
+        sortBy: {
+            type: 'string',
+            optional: true,
+            description: 'Field to sort by',
+        },
+        sortOrder: {
+            type: 'string',
+            optional: true,
+            description: 'Sort order: asc, desc',
+            examples: ['asc', 'desc'],
+        },
+        // Filtering
+        activeFilters: {
+            type: 'json',
+            optional: true,
+            description: 'Active filter values',
+        },
+        // Display
+        showGrandTotals: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to show grand totals',
+        },
+        showSubtotals: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to show subtotals',
+        },
+        compactLayout: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to use compact layout',
+        },
+        // Refresh
+        autoRefresh: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to auto-refresh on data change',
+        },
+        lastRefreshedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last refresh timestamp',
+        },
+        // Calculated fields
+        calculatedFields: {
+            type: 'json',
+            optional: true,
+            description: 'Custom calculated field definitions',
+        },
+    },
+    relationships: {
+        spreadsheet: {
+            type: 'Spreadsheet',
+            backref: 'pivotTables',
+            description: 'Parent spreadsheet',
+        },
+        sheet: {
+            type: 'Sheet',
+            backref: 'pivotTables',
+            description: 'Sheet containing the pivot table',
+        },
+    },
+    actions: [
+        'create',
+        'edit',
+        'delete',
+        'refresh',
+        'addField',
+        'removeField',
+        'moveField',
+        'setAggregation',
+        'filter',
+        'clearFilter',
+        'sort',
+        'expand',
+        'collapse',
+        'expandAll',
+        'collapseAll',
+        'addCalculatedField',
+        'removeCalculatedField',
+        'showFieldList',
+        'export',
+    ],
+    events: [
+        'created',
+        'edited',
+        'deleted',
+        'refreshed',
+        'fieldAdded',
+        'fieldRemoved',
+        'fieldMoved',
+        'aggregationSet',
+        'filtered',
+        'filterCleared',
+        'sorted',
+        'expanded',
+        'collapsed',
+        'calculatedFieldAdded',
+        'calculatedFieldRemoved',
+        'exported',
+    ],
+};
+// =============================================================================
+// Export all entities as a schema
+// =============================================================================
+/**
+ * All spreadsheet entity types
+ */
+export const SpreadsheetEntities = {
+    Spreadsheet,
+    Sheet,
+    Cell,
+    Range,
+    Chart,
+    PivotTable,
+};
+/**
+ * Entity categories for organization
+ */
+export const SpreadsheetCategories = {
+    spreadsheets: ['Spreadsheet', 'Sheet', 'Cell', 'Range', 'Chart', 'PivotTable'],
+};