@a3s-lab/office 0.34.0 → 0.36.0

package/dist/core.js

@@ -5,7 +5,7 @@ import { OFFICE_COLLABORATION_PROTOCOL as WORK_OFFICE_COLLABORATION_PROTOCOL, Of
 import { directChildren, OoxmlPackage as work_ooxml_package_OoxmlPackage, parseXml, firstDescendant, directChild, descendants, createArtifact as createWorkArtifact, xmlContainsAnyElement, createOfficeId as createWorkId, attribute as work_ooxml_package_attribute } from "./4121.js";
 import { fileNameWithoutExtension, work_file_download_downloadBlob, mountWorkLiveDocumentCapture, importWorkDocumentFile, moveWorkSourceBlob, materializeWorkDocumentContent as work_document_model_codec_materializeWorkDocumentContent, createWorkDocumentModel, work_file_download_safeFileName, documentPageSurfaceGeometryForElement, registerSourceBlob as rememberWorkSourceBlob, documentModelForContent, readSourceBlob as readWorkSourceBlob, createWorkDocumentExtensions, positionWorkLiveDocumentCapture, createWorkDocumentBlob } from "./4174.js";
 import { normalizeSpreadsheetPrintTitleRows, sparseMatrixColumnCount, normalizeSpreadsheetPrintArea, parseSpreadsheetPrintTitles, isValidSpreadsheetDefinedName, formatSpreadsheetCellRanges, stripSpreadsheetSheetQualifier, editableSpreadsheetFormula, sparseArrayEntries, qualifySpreadsheetRange, refreshSpreadsheetPivotTables, parseSpreadsheetCellRanges, normalizeSpreadsheetPrintTitleColumns } from "./8715.js";
-import { xlsxColorMatches, xlsxRichTextCellText, spreadsheetCellValueWithDiagonalBorder, xlsxRichTextStyleOrigins, normalizeSpreadsheetDataValidationErrorStyle, directXlsxAlignment, spreadsheetTextOrientationFromXlsx, directXlsxFontStyle, hasXlsxDirectFontStyle, applyImportedXlsxRichText, xlsxStyleCollectionIndex, spreadsheetExplicitTextOrientationFromCell, sheetHasXlsxRichTextCells, activeXlsxNativeFill, readXlsxRichTextCells, normalizeSpreadsheetDateValidationBoundary, createXlsxRichTextReadContext, boundedSpreadsheetDataValidationText, xlsxNativeFillKey, xlsxBooleanAttribute, xlsxAlignmentMatches, xlsxBorderLineMatches, spreadsheetTextOrientationCellStyle, spreadsheetDateValidationFormula, spreadsheetDiagonalBorderFromCellValue, xlsxUnderlineStyle, spreadsheetUnderlineCellValueFromXlsx, xlsxToggleEnabled, writeXlsxRichTextCells, activeXlsxSemanticColorOrigin, xlsxNativeFillSemanticColors, spreadsheetUnderlineCellValueFromSheetJs } from "./3266.js";
+import { xlsxColorMatches, xlsxRichTextCellText, spreadsheetCellValueWithDiagonalBorder, xlsxRichTextStyleOrigins, normalizeSpreadsheetDataValidationErrorStyle, directXlsxAlignment, applyImportedXlsxRichText, spreadsheetTextOrientationFromXlsx, directXlsxFontStyle, hasXlsxDirectFontStyle, xlsxStyleCollectionIndex, spreadsheetExplicitTextOrientationFromCell, sheetHasXlsxRichTextCells, activeXlsxNativeFill, readXlsxRichTextCells, normalizeSpreadsheetDateValidationBoundary, createXlsxRichTextReadContext, boundedSpreadsheetDataValidationText, xlsxNativeFillKey, xlsxBooleanAttribute, xlsxAlignmentMatches, xlsxBorderLineMatches, spreadsheetTextOrientationCellStyle, spreadsheetDateValidationFormula, spreadsheetDiagonalBorderFromCellValue, xlsxUnderlineStyle, spreadsheetUnderlineCellValueFromXlsx, xlsxToggleEnabled, writeXlsxRichTextCells, activeXlsxSemanticColorOrigin, xlsxNativeFillSemanticColors, normalizeSpreadsheetTableCalculatedFormula, spreadsheetUnderlineCellValueFromSheetJs } from "./3266.js";
 import { freezeImportedSpreadsheetCell, readXlsxGradientFill, withXlsxPatternFill, xlsxCellStyleOriginSemanticColors, setXlsxToggleChild, withXlsxCellStyleOrigin, normalizeSpreadsheetConditionalVisualOptions, xlsxColorElementMatchesOrigin, withXlsxGradientFill, ensureXlsxStyleCollection, xlsxCellStyleOrigin, xlsxSemanticColorOriginKey, readXlsxPatternFill, isSpreadsheetConditionalComparisonOperator, registerImportedSpreadsheetMatrix, defaultSpreadsheetConditionalIconThresholds, readXlsxSemanticColorOrigin, setXlsxUnderlineChild, xlsxGradientFillFallbackColor, setXlsxColorChild, createXlsxColorResolver, resolveXlsxColor, setXlsxBorderLine, normalizeSpreadsheetConditionalIconSetFormat, defaultSpreadsheetDataBarOptions, defaultXlsxBorder, prepareXlsxSemanticPalette, importedSheetProtectionAuthority, defaultSpreadsheetColorScaleThresholds, xlsxRgbColor, writeXlsxAlignment, xlsxGradientFillKey, applyXlsxSemanticColorOrigin, spreadsheetConditionalComparisonNeedsUpperValue, sheetHasProtectionState, xlsxWorksheetCellEntries, isSpreadsheetConditionalIconSetName, setXlsxValueChild, defaultXlsxFill, spreadsheetConditionalThresholdsEqual, spreadsheetConditionalIconSetCount } from "./9333.js";
 import { updateSpreadsheetWorksheetCompatibilitySummary, inspectXlsxPivotTables, readXlsxWorksheetCharts, createXlsxFormulaCell, patchXlsxWorksheetDrawings, readXlsxWorksheetImages, writeXlsxProtection, xlsxWorksheetChartsToSheet, readXlsxFormulaFeaturesFromPackage, emptySpreadsheetWorksheetCompatibilitySummary, createSpreadsheetFormulaMetadata, createXlsxErrorCell, xlsxWorksheetImagesToSheet, readXlsxProtection, patchXlsxFormulaFeatures, patchXlsxPivotTables, writeXlsxPageSetup, XlsxCellProtectionWriter, applyImportedXlsxPivotTables, readXlsxPageSetup } from "./4166.js";
 import { WorkFileImportController, materializeWorkFileSource } from "./9356.js";
@@ -2700,9 +2700,14 @@ function parseXlsxTable(document1, partPath) {
     if (!name || !range || !columnsElement) return null;
     const columns = directChildren(columnsElement, 'tableColumn').flatMap((column)=>{
         const columnName = work_ooxml_package_attribute(column, 'name');
-        return null === columnName ? [] : [
+        if (null === columnName) return [];
+        const calculatedFormula = normalizeSpreadsheetTableCalculatedFormula(directChild(column, 'calculatedColumnFormula')?.textContent);
+        return [
             {
-                name: columnName
+                name: columnName,
+                ...calculatedFormula ? {
+                    calculatedFormula
+                } : {}
             }
         ];
     });
@@ -2742,7 +2747,12 @@ function xlsxTableXml(table, tableId, namespace) {
     ]);
     const displayName = table.displayName?.trim() || table.name;
     const filter = table.headerRow ? xlsxTableAutoFilterXml(table.filters, reference, table.totalsRow) : '';
-    const columns = table.columns.map((column, index)=>`<tableColumn id="${index + 1}" name="${work_xlsx_tables_escapeXml(column.name)}"/>`).join('');
+    const columns = table.columns.map((column, index)=>{
+        const formula = normalizeSpreadsheetTableCalculatedFormula(column.calculatedFormula);
+        const formulaElement = formula ? `<calculatedColumnFormula>${work_xlsx_tables_escapeXml(formula.replace(/^=/, ''))}</calculatedColumnFormula>` : '';
+        const opening = `<tableColumn id="${index + 1}" name="${work_xlsx_tables_escapeXml(column.name)}"`;
+        return formulaElement ? `${opening}>${formulaElement}</tableColumn>` : `${opening}/>`;
+    }).join('');
     const styleName = tableStyleName(table.style);
     const style = styleName ? `<tableStyleInfo name="${styleName}" showColumnStripes="${booleanToken(table.showColumnStripes)}" showFirstColumn="${booleanToken(table.showFirstColumn)}" showLastColumn="${booleanToken(table.showLastColumn)}" showRowStripes="${booleanToken(table.showRowStripes)}"/>` : '';
     return [

package/dist/internal/features/work/editors/presentation-editor-focus.d.ts

@@ -1,4 +1,5 @@
 import type { PresentationEditorCommands } from './presentation-command-types';
+import type { WorkSlideElement } from '../work-types';
 export interface PresentationObjectFocusState {
     editingElementId: string | null;
     selectedElementIds: readonly string[];
@@ -7,6 +8,7 @@ export interface PresentationWorkspaceFocusState extends PresentationObjectFocus
     selectedSlideId: string;
     viewMode: 'normal' | 'sorter';
 }
+export declare function presentationInitialEditingElementId(elements: readonly WorkSlideElement[]): string | null;
 export declare function restorePresentationObjectFocus(container: HTMLElement | null, getState: () => PresentationObjectFocusState, focusOrigin?: Element | null): void;
 export declare function restorePresentationWorkspaceFocus(root: HTMLElement | null, getState: () => PresentationWorkspaceFocusState, focusOrigin?: Element | null): void;
 export declare function presentationWorkspaceFocusTarget(root: HTMLElement, state: PresentationWorkspaceFocusState): HTMLElement | undefined;

package/dist/internal/features/work/editors/presentation-text-editor.d.ts

@@ -13,6 +13,13 @@ export interface PresentationTextEditorProps {
     onSelectionChange?: () => void;
 }
 export declare function PresentationTextEditor({ autoFocus, element, onChange, onEditorChange, onExitEditing, onSelectionChange, }: PresentationTextEditorProps): import("react").JSX.Element | null;
+/**
+ * Keep delayed first-open focus from overriding a deliberate focus move that
+ * happened while the rich-text editor was being created. The document body is
+ * treated as an unfocused baseline so opening from a non-focusable surface can
+ * still enter the editor normally.
+ */
+export declare function presentationFocusOwnerIsUnchanged(initialFocusTarget: HTMLElement | null): boolean;
 export declare function createPresentationTextEditorExtensions(placeholder?: string): Extensions;
 export declare function presentationTextElementHtml(element: WorkSlideElement): string;
 export declare function presentationTextValue(editor: Editor, element: WorkSlideElement): PresentationTextValue;

package/dist/internal/features/work/editors/spreadsheet-calculation-model.d.ts

@@ -1,7 +1,7 @@
 import { type Op, type Sheet } from '@fortune-sheet/core';
 import type { OfficeKernelSpreadsheetCalculatedCell, OfficeKernelSpreadsheetCoordinate, OfficeKernelSpreadsheetSessionUpdate } from '../../../kernel/office-kernel-protocol';
-import type { SpreadsheetCalculationCommand } from './spreadsheet-command-controller';
 import { type SpreadsheetKernelFallbackCell, type SpreadsheetKernelWorkbook } from './spreadsheet-calculation-projection';
+import type { SpreadsheetCalculationCommand } from './spreadsheet-command-controller';
 export declare function spreadsheetCalculationTargets(workbook: SpreadsheetKernelWorkbook, command: SpreadsheetCalculationCommand): OfficeKernelSpreadsheetCoordinate[] | undefined;
 export declare function spreadsheetCalculationSessionUpdate(previous: SpreadsheetKernelWorkbook | null, current: SpreadsheetKernelWorkbook, baseDocumentRevision: number, forceReplace?: boolean): OfficeKernelSpreadsheetSessionUpdate;
 export declare function spreadsheetCalculationFallbackCells(workbook: SpreadsheetKernelWorkbook, command: SpreadsheetCalculationCommand, includeDataTables?: boolean): SpreadsheetKernelFallbackCell[];

package/dist/internal/features/work/editors/spreadsheet-calculation-projection.d.ts

@@ -1,7 +1,10 @@
 import type { Op, Sheet } from '@fortune-sheet/core';
 import type { OfficeKernelSpreadsheetCoordinate, OfficeKernelSpreadsheetInputCell, OfficeKernelSpreadsheetInputSheet, OfficeKernelSpreadsheetSessionCellChange } from '../../../kernel/office-kernel-protocol';
-import type { WorkSpreadsheetContent, WorkSpreadsheetFormulaRangeType, WorkSpreadsheetSheet } from '../work-types';
+import type { WorkSpreadsheetContent, WorkSpreadsheetFormulaRangeType, WorkSpreadsheetSheet, WorkSpreadsheetTable } from '../work-types';
 export declare const SPREADSHEET_KERNEL_MAX_PATCH_CELLS = 10000;
+type SpreadsheetKernelSheet = Sheet & {
+    tables?: WorkSpreadsheetTable[];
+};
 export interface SpreadsheetKernelWorkbook {
     fallbackCells: SpreadsheetKernelFallbackCell[];
     sheets: OfficeKernelSpreadsheetInputSheet[];
@@ -34,7 +37,7 @@ export declare function createSpreadsheetKernelWorkbook(content: Pick<WorkSpread
  * snapshot from the updated controlled content.
  */
 export declare function prepareSpreadsheetKernelWorkbook(content: Pick<WorkSpreadsheetContent, 'sheets'>): SpreadsheetKernelWorkbookPreparation;
-export declare function refreshSpreadsheetKernelWorkbook(sheets: readonly Sheet[], fallbackCells: readonly SpreadsheetKernelFallbackCell[]): SpreadsheetKernelWorkbook | null;
+export declare function refreshSpreadsheetKernelWorkbook(sheets: readonly SpreadsheetKernelSheet[], fallbackCells: readonly SpreadsheetKernelFallbackCell[]): SpreadsheetKernelWorkbook | null;
 export declare function projectSpreadsheetKernelWorkbookOperations(previous: SpreadsheetKernelWorkbook, sheets: readonly WorkSpreadsheetSheet[], operations: readonly Op[]): SpreadsheetKernelOperationProjection | null;
 export declare function spreadsheetOperationsMayChangeCalculation(operations: readonly Op[], workbook?: SpreadsheetKernelWorkbook | null): boolean;
 export declare function spreadsheetKernelCellKey(cell: Pick<OfficeKernelSpreadsheetInputCell, 'row' | 'column'>): string;

package/dist/internal/features/work/editors/spreadsheet-command-controller.d.ts

@@ -67,6 +67,15 @@ export interface SpreadsheetCommandSelection {
     sheetId: string;
     selection: Selection;
 }
+/**
+ * Synchronous selection state shared by commands and the Fortune Sheet bridge.
+ * Fortune applies API calls through React state, so reading its imperative API
+ * twice in the same task can otherwise return the previous selection.
+ */
+export interface SpreadsheetSelectionRef {
+    current: SpreadsheetCommandSelection | null;
+    requested: SpreadsheetCommandSelection | null;
+}
 export type SpreadsheetStructureAxis = 'row' | 'column';
 export type SpreadsheetStructureInsertPosition = 'before' | 'after';
 export type SpreadsheetSortDirection = 'ascending' | 'descending';
@@ -238,6 +247,7 @@ export interface SpreadsheetCommandContext {
     onChange: (content: WorkSpreadsheetContent) => void;
     richTextFormat?: SpreadsheetRichTextFormatCommandPort | null;
     selection: SpreadsheetCommandSelection | null;
+    selectionRef?: SpreadsheetSelectionRef;
     table: SpreadsheetTableCommandPort;
     targetSheetGridSize?: SpreadsheetGridSize | null;
     targetSheetId: string;

package/dist/internal/features/work/editors/spreadsheet-command-selection.d.ts

@@ -1,3 +1,24 @@
-import type { SpreadsheetCommandContext, SpreadsheetCommandRange } from './spreadsheet-command-controller';
+import type { SpreadsheetCommandContext, SpreadsheetCommandSelection, SpreadsheetCommandRange, SpreadsheetSelectionRef } from './spreadsheet-command-controller';
 export declare function canEditSpreadsheetSelection(context: SpreadsheetCommandContext): boolean;
 export declare function spreadsheetLiveCommandRange(context: SpreadsheetCommandContext): SpreadsheetCommandRange;
+/**
+ * Returns the most recent selection known to the Office bridge. The ref is
+ * intentionally checked before Fortune's imperative API because that API is
+ * backed by React state and can lag behind a just-issued keyboard command.
+ */
+export declare function spreadsheetLiveCommandSelection(context: SpreadsheetCommandContext): SpreadsheetCommandRange | undefined;
+/**
+ * Returns all current selections while preserving the workbook's multi-range
+ * semantics. A synchronous command selection is represented as one range.
+ */
+export declare function spreadsheetLiveCommandSelections(context: SpreadsheetCommandContext): SpreadsheetCommandRange[] | undefined;
+/**
+ * Accept a Fortune selection callback unless it is older than a pending
+ * programmatic selection request. The returned value is the normalized state
+ * that should be published to React and collaboration consumers.
+ */
+export declare function acceptSpreadsheetSelectionChange(selectionRef: SpreadsheetSelectionRef, sheetId: string, selection: SpreadsheetCommandRange): SpreadsheetCommandSelection | null;
+export declare function rememberSpreadsheetCommandSelection(context: SpreadsheetCommandContext, selection: SpreadsheetCommandRange): void;
+/** Clear a pending programmatic request when a fresh user intent arrives. */
+export declare function releaseSpreadsheetSelectionRequest(selectionRef: SpreadsheetSelectionRef): void;
+export declare function sameSpreadsheetSelectionValue(left: SpreadsheetCommandRange, right: SpreadsheetCommandRange): boolean;

package/dist/internal/features/work/editors/spreadsheet-table-calculated-columns.d.ts

@@ -0,0 +1,42 @@
+import type { Cell } from '@fortune-sheet/core';
+import type { WorkSpreadsheetSheet, WorkSpreadsheetTable, WorkSpreadsheetTableColumn } from '../work-types';
+/** Keep calculated-column metadata small enough to cross every editor boundary. */
+export declare const MAX_SPREADSHEET_TABLE_CALCULATED_FORMULA_LENGTH = 8192;
+/**
+ * Normalizes the editable form of a table-column formula. Native table parts
+ * omit the leading `=`, while cell formulas and the calculation kernel keep
+ * it. Unsafe or external formulas are deliberately not treated as automatic
+ * fill rules.
+ */
+export declare function normalizeSpreadsheetTableCalculatedFormula(value: unknown): string | undefined;
+/**
+ * Finds a shared current-row formula already authored in a table column.
+ * Ordinary one-off A1 formulas are intentionally ignored so inserting a row
+ * cannot unexpectedly overwrite a user's manual exception.
+ */
+export declare function inferredSpreadsheetTableCalculatedFormula(sheet: WorkSpreadsheetSheet, table: WorkSpreadsheetTable, columnOffset: number): string | undefined;
+/**
+ * Reconciles declared calculated-column formulas with formulas authored in the
+ * controlled cell matrix. A conflicting column is made manual instead of
+ * guessing which formula should be copied into a new row.
+ */
+export declare function reconcileSpreadsheetTableCalculatedColumns(sheet: WorkSpreadsheetSheet, table: WorkSpreadsheetTable): WorkSpreadsheetTableColumn[];
+/** Returns true only for a formula safe to copy into a new table row. */
+export declare function isSpreadsheetTableCalculatedFormula(value: unknown): value is string;
+/**
+ * Applies calculated-column formulas to newly inserted body rows. The helper
+ * deliberately edits only empty cells; copied values and authored exceptions
+ * remain authoritative. Both Fortune's dense matrix and sparse `celldata`
+ * storage are updated without materializing unrelated rows or columns.
+ */
+export declare function fillSpreadsheetTableCalculatedColumns(sheet: WorkSpreadsheetSheet, table: WorkSpreadsheetTable, rows: readonly number[]): WorkSpreadsheetSheet;
+export declare function spreadsheetTableCellAt(sheet: WorkSpreadsheetSheet, row: number, column: number): Cell | null;
+export declare function spreadsheetTableCellIsEmpty(cell: Cell | null | undefined): boolean;
+/** Copy visual cell metadata without carrying a stale cached formula result. */
+export declare function spreadsheetCellWithCalculatedFormula(source: Cell | null | undefined, formula: string): Cell;
+/** Iterate formula-bearing cells without forcing a dense worksheet matrix. */
+export declare function spreadsheetTableFormulaCells(sheet: WorkSpreadsheetSheet): Array<{
+    cell: Cell;
+    column: number;
+    row: number;
+}>;

package/dist/internal/features/work/editors/use-presentation-selection.d.ts

@@ -8,4 +8,4 @@ export interface PresentationSelectionController {
     select: (elementId: string | null, additive?: boolean) => void;
     selectedElementIds: string[];
 }
-export declare function usePresentationSelection(elements: readonly WorkSlideElement[]): PresentationSelectionController;
+export declare function usePresentationSelection(elements: readonly WorkSlideElement[], initialEditingElementId?: string | null): PresentationSelectionController;

package/dist/internal/features/work/work-types.d.ts

@@ -236,6 +236,11 @@ export type WorkSpreadsheetTableStyle = {
 };
 export interface WorkSpreadsheetTableColumn {
     name: string;
+    /**
+     * A bounded native table calculated-column formula. The controlled model
+     * stores the editable form with a leading `=`; XLSX table parts omit it.
+     */
+    calculatedFormula?: string;
 }
 export type WorkSpreadsheetDynamicFilter = 'above-average' | 'below-average' | 'tomorrow' | 'today' | 'yesterday' | 'next-week' | 'this-week' | 'last-week' | 'next-month' | 'this-month' | 'last-month' | 'next-quarter' | 'this-quarter' | 'last-quarter' | 'next-year' | 'this-year' | 'last-year' | 'year-to-date' | 'quarter-1' | 'quarter-2' | 'quarter-3' | 'quarter-4' | 'month-1' | 'month-2' | 'month-3' | 'month-4' | 'month-5' | 'month-6' | 'month-7' | 'month-8' | 'month-9' | 'month-10' | 'month-11' | 'month-12';
 export type WorkSpreadsheetTableFilterCriteria = {

package/dist/internal/kernel/office-kernel-protocol.d.ts

@@ -1,6 +1,6 @@
 import { OFFICE_KERNEL_PROTOCOL_VERSION } from './office-kernel-version';
+export type { OfficeKernelSpreadsheetCalculatedCell, OfficeKernelSpreadsheetCalculationIssue, OfficeKernelSpreadsheetCalculationRequest, OfficeKernelSpreadsheetCalculationResult, OfficeKernelSpreadsheetCoordinate, OfficeKernelSpreadsheetError, OfficeKernelSpreadsheetInputCell, OfficeKernelSpreadsheetInputSheet, OfficeKernelSpreadsheetInputTable, OfficeKernelSpreadsheetSessionCalculationRequest, OfficeKernelSpreadsheetSessionCalculationResult, OfficeKernelSpreadsheetSessionCalculationScope, OfficeKernelSpreadsheetSessionCalculationStats, OfficeKernelSpreadsheetSessionCellChange, OfficeKernelSpreadsheetSessionUpdate, OfficeKernelSpreadsheetValue, } from './office-kernel-spreadsheet-protocol';
 export { OFFICE_KERNEL_PROTOCOL_VERSION };
-export type { OfficeKernelSpreadsheetCalculatedCell, OfficeKernelSpreadsheetCalculationIssue, OfficeKernelSpreadsheetCalculationRequest, OfficeKernelSpreadsheetCalculationResult, OfficeKernelSpreadsheetCoordinate, OfficeKernelSpreadsheetError, OfficeKernelSpreadsheetInputCell, OfficeKernelSpreadsheetInputSheet, OfficeKernelSpreadsheetSessionCalculationRequest, OfficeKernelSpreadsheetSessionCalculationResult, OfficeKernelSpreadsheetSessionCalculationScope, OfficeKernelSpreadsheetSessionCalculationStats, OfficeKernelSpreadsheetSessionCellChange, OfficeKernelSpreadsheetSessionUpdate, OfficeKernelSpreadsheetValue, } from './office-kernel-spreadsheet-protocol';
 import type { OfficeKernelSpreadsheetCalculationRequest, OfficeKernelSpreadsheetCalculationResult, OfficeKernelSpreadsheetSessionCalculationRequest, OfficeKernelSpreadsheetSessionCalculationResult } from './office-kernel-spreadsheet-protocol';
 export type OfficeKernelEngine = 'wasm' | 'javascript';
 export interface OfficeKernelPageMetrics {

package/dist/internal/kernel/office-kernel-spreadsheet-protocol.d.ts

@@ -29,10 +29,28 @@ export interface OfficeKernelSpreadsheetInputCell {
     formula?: string;
     value: OfficeKernelSpreadsheetValue;
 }
+/**
+ * The bounded table metadata needed to resolve native structured references.
+ * Ranges are zero-based and inclusive, matching the controlled workbook
+ * model. Styling, filters, and drawing metadata intentionally stay outside
+ * the calculation kernel.
+ */
+export interface OfficeKernelSpreadsheetInputTable {
+    name: string;
+    displayName?: string;
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+    columns: string[];
+    headerRow: boolean;
+    totalsRow: boolean;
+}
 export interface OfficeKernelSpreadsheetInputSheet {
     id: string;
     name: string;
     cells: OfficeKernelSpreadsheetInputCell[];
+    tables?: OfficeKernelSpreadsheetInputTable[];
 }
 export interface OfficeKernelSpreadsheetCalculationRequest {
     protocol: typeof OFFICE_KERNEL_PROTOCOL_VERSION;

package/dist/internal/kernel/office-kernel-spreadsheet-structured-reference.d.ts

@@ -0,0 +1,48 @@
+import type { OfficeKernelSpreadsheetInputSheet } from './office-kernel-spreadsheet-protocol';
+export interface SpreadsheetStructuredRowSelection {
+    all: boolean;
+    headers: boolean;
+    data: boolean;
+    totals: boolean;
+    current: boolean;
+}
+export interface SpreadsheetStructuredReference {
+    tableName?: string;
+    firstColumn?: string;
+    lastColumn?: string;
+    rows: SpreadsheetStructuredRowSelection;
+}
+export interface SpreadsheetStructuredReferenceArea {
+    sheetId: string;
+    sheetName: string;
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+}
+export type SpreadsheetStructuredReferenceErrorKind = 'invalid' | 'unsupported' | 'missing-table' | 'missing-column';
+export declare class SpreadsheetStructuredReferenceError extends Error {
+    readonly kind: SpreadsheetStructuredReferenceErrorKind;
+    constructor(kind: SpreadsheetStructuredReferenceErrorKind, message: string);
+}
+/** Parse one bounded table-reference token using the OOXML column grammar. */
+export declare function parseSpreadsheetStructuredReference(reference: string): SpreadsheetStructuredReference;
+/**
+ * Catalog the semantic tables in a workbook and resolve references to bounded
+ * zero-based rectangular areas. The catalog deliberately contains no cells;
+ * values remain in the calculation evaluator so dependencies stay observable.
+ */
+export declare class SpreadsheetStructuredReferenceCatalog {
+    readonly sheets: readonly OfficeKernelSpreadsheetInputSheet[];
+    private readonly definitions;
+    private readonly byName;
+    private readonly bySheet;
+    constructor(sheets: readonly OfficeKernelSpreadsheetInputSheet[]);
+    resolve(qualifier: string | undefined, reference: string, currentSheet: OfficeKernelSpreadsheetInputSheet, currentColumn: number, currentRow: number): SpreadsheetStructuredReferenceArea[];
+    private resolveTable;
+    private resolveColumns;
+    private resolveRows;
+    private dataRows;
+}
+/** Expand structured tokens to A1 ranges before invoking the scalar parser. */
+export declare function expandSpreadsheetStructuredReferences(formula: string, catalog: SpreadsheetStructuredReferenceCatalog, currentSheet: OfficeKernelSpreadsheetInputSheet, currentRow: number, currentColumn: number): string;