@a3s-lab/office 0.35.0 → 0.36.0

package/README.md

@@ -56,9 +56,8 @@ workflows, and a separate Rust automation plane.
 
 ## Latest on `main`
 
-The `0.35.0` release plus the current `main` branch expose these capabilities
-as normal user-facing Playground templates, with matching implementation
-detail in the documentation:
+The `0.36.0` release exposes these capabilities as normal user-facing
+Playground templates, with matching implementation detail in the documentation:
 
 | Editor | Latest capability | Public entry |
 | --- | --- | --- |
@@ -69,12 +68,13 @@ detail in the documentation:
 | Writer | Native character shading with exact `w:shd` patterns, foreground/background color identity, explicit resets, authoring, and DOCX reopen | Playground **Latest capabilities → 字符底纹** · [Document reference](docs/latest/en/components/document.mdx#native-character-shading) |
 | Writer | Independent Latin, East Asian, and bidi proofing languages plus explicit `w:noProof` inclusion/exclusion | Playground **Latest capabilities → 校对语言** · [Document reference](docs/latest/en/components/document.mdx#native-proofing-languages) |
 | Spreadsheet | Complete common Data Validation input, blank/dropdown, and Stop/Warning/Information error settings with native XLSX round trips | Playground **Latest capabilities → 数据验证** · [Spreadsheet reference](docs/latest/en/components/spreadsheet.mdx#data-validation) |
+| Spreadsheet | Bounded structured-reference calculation plus automatic calculated-column fill for table names/display names, contiguous columns, header/data/totals selectors, qualified references, and table-local current-row formulas across Rust/WASM and JavaScript fallback | Playground **Latest capabilities → 结构化引用** · [Spreadsheet reference](docs/latest/en/components/spreadsheet.mdx#structured-reference-calculation) |
 | PDF | Insert, delete, rotate, reorder, extract, merge, and split pages through a dedicated Web Worker, with Blob-level Undo/Redo and independent binary reopen verification | Playground **Latest capabilities → 组织 PDF 页面** · [PDF reference](docs/latest/en/components/pdf.mdx#page-organization) |
 
-All eight entries are reachable from the first Playground viewport. The
+All nine entries are reachable from the first Playground viewport. The
 filterable capability gallery groups releases by editor, publishes the source
 release on every card, and grows from one shared metadata list instead of a
-fixed-width strip. The seven content templates also remain under **新建**;
+fixed-width strip. The eight content templates also remain under **新建**;
 **组织 PDF 页面** opens the normal PDF file workflow because page organization
 must operate on host-provided source bytes.
 
@@ -151,8 +151,8 @@ baseline rather than one specific release.
 | Cells, sheets, navigation, and history | **Supported** — multiple sheets, sparse editing, search, clipboard, four-direction fill, exact formula/value copy from above, and undo/redo | Mature grid workflows across desktop and web |
 | Formatting and style rendering | **Partial** — native fonts, colors, borders, alignment, number formats, cell styles, all 17 native non-solid OOXML pattern fills, native linear/path XLSX gradients, and one Format Cells surface that authors none, solid, pattern, or gradient fills with exact geometry and 2–256 ordered stops; static date/time entry, contrast-safe font preview, native XLSX rich-text runs, selected-text font formatting, direct formula-bar/F2 insertion or deletion, and bounded authenticated formatted-HTML paste | Disjoint multi-edit rich-text authoring, broader themes, locale formats, and advanced style effects |
 | Ribbon and shortcuts | **Partial** — common Office-style Home/Data/View commands, grid-scoped shortcuts, and focused Font-dialog aliases | Larger command catalog and platform-specific accelerators |
-| Formulas and recalculation | **Partial** — dependency-aware calculation and common formula paths | Wider functions, arrays, volatile semantics, and calculation parity |
-| Tables, pivots, charts, and rules | **Partial** — native tables, pivots, charts, conditional formatting, and common validation rules with complete input/error-setting authoring | Calculated columns, slicers, pivot charts, custom/dependent validation rules, advanced analysis, and broader browser alert flows |
+| Formulas and recalculation | **Partial** — dependency-aware calculation plus bounded structured references (`Table[Column]`, contiguous ranges, `#All`/`#Headers`/`#Data`/`#Totals`/`#This Row`, and `[@Column]`) in the shared Rust/WASM and JavaScript paths | Wider functions, arrays, volatile semantics, and calculation parity |
+| Tables, pivots, charts, and rules | **Partial** — native tables, bounded structured-reference formulas, calculated-column formulas with automatic fill for newly inserted body rows, pivots, charts, conditional formatting, and common validation rules with complete input/error-setting authoring | Complete totals-row authoring, slicers, pivot charts, custom/dependent validation rules, advanced analysis, and broader browser alert flows |
 | Large worksheets | **Supported with boundaries** — maximum-dimension sparse import/editing and viewport-bounded Canvas painting | Highly optimized native grid with hardware-dependent limits |
 | Files and printing | **Partial** — XLS/XLSX/ODS/CSV import, XLSX export, and PDF output | Broader round trips, external data, print fidelity, and legacy conversion |
 | External data, macros, and specialist analysis | **Gap** — active macros are never executed; bounded models are still needed for data connections and solver-like tools | Established data, macro/add-in, scenario, and optimization ecosystems |
@@ -740,9 +740,25 @@ stable IDs, workbook-unique names, zero-based ranges, ordered columns, filters,
 header/totals flags, and built-in style identity. XLSX import and export keep
 native table parts and relationships. Table styling is resolved only for the
 visible Canvas cells; converting a table to a range materializes the confirmed
-appearance without densifying unrelated worksheet space. Structured-reference
-calculation, calculated columns, complete totals authoring, slicers, and
-external/query tables are not yet claimed.
+appearance without densifying unrelated worksheet space.
+
+The calculation kernel resolves a bounded common structured-reference subset:
+table names or `displayName`, worksheet-qualified tables, contiguous column
+ranges, `#All`, `#Headers`, `#Data`, `#Totals`, `#This Row`, and table-local
+`[@Column]` formulas. Rust/WASM and JavaScript fallback share the parser,
+catalog, dependency graph, and no-history projection path. Requests accept at
+most 1,024 tables and materialize at most 100,000 cells per structured range;
+whole-row/column, three-dimensional, external, disjoint, missing, or
+over-budget references fail closed. A validated calculated-column rule is
+inferred from matching current-row formulas and fills only newly inserted table
+body rows. Existing values, formulas, and manual exceptions always win; a
+conflicting column fails closed and drops its automatic rule. XLSX
+`<calculatedColumnFormula>` metadata round-trips with the leading `=` restored
+in the controlled model, while unsafe or external formulas are omitted.
+The Playground's **结构化引用** template shows a calculated `Revenue` column,
+an insertion hint, a totals row, and a worksheet-qualified summary. Complete
+totals-row authoring, slicers, and external/query tables remain explicit
+boundaries.
 
 Use `downloadArtifact` to start a browser download or
 `createArtifactBlob` when your application owns upload and persistence.
@@ -1625,6 +1641,7 @@ keep working without hard-coded return URLs.
 
 - [Live Playground](https://a3s-lab.github.io/Office/playground/)
 - [Documentation center](https://a3s-lab.github.io/Office/docs/)
+- [A3S Office 0.36.0 documentation](https://a3s-lab.github.io/Office/docs/0.36.0/)
 - [A3S Office 0.34.0 documentation](https://a3s-lab.github.io/Office/docs/0.34.0/)
 - [A3S Office 0.33.0 documentation](https://a3s-lab.github.io/Office/docs/0.33.0/)
 - [A3S Office 0.32.0 documentation](https://a3s-lab.github.io/Office/docs/0.32.0/)

package/dist/0~7048.js

@@ -1462,6 +1462,7 @@ function validateSpreadsheetCalculationRequest(request) {
         if (!sheet.id.trim() || utf8ByteLength(sheet.id) > MAX_SPREADSHEET_IDENTIFIER_BYTES || !sheet.name.trim() || utf8ByteLength(sheet.name) > MAX_SPREADSHEET_IDENTIFIER_BYTES || sheetIds.has(sheet.id) || sheetNames.has(normalizedName)) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.sheet_invalid', 'Spreadsheet sheet IDs and names must be unique and non-empty.');
         sheetIds.add(sheet.id);
         sheetNames.add(normalizedName);
+        validateSpreadsheetTables(sheet, request.sheets);
         const coordinates = new Set();
         for (const cell of sheet.cells){
             const key = `${cell.row}:${cell.column}`;
@@ -1473,6 +1474,68 @@ function validateSpreadsheetCalculationRequest(request) {
     }
     for (const target of request.targets ?? [])if (!sheetIds.has(target.sheetId) || !boundedSpreadsheetIndex(target.row, office_kernel_spreadsheet_protocol_OFFICE_KERNEL_SPREADSHEET_MAX_ROWS) || !boundedSpreadsheetIndex(target.column, 16384)) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.target_invalid', 'Spreadsheet calculation targets must reference an existing, bounded cell.');
 }
+function validateSpreadsheetTables(sheet, sheets) {
+    const tables = sheet.tables ?? [];
+    const tableCount = sheets.reduce((count, candidate)=>count + (candidate.tables?.length ?? 0), 0);
+    if (tableCount > 1024) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_limit_exceeded', 'A Spreadsheet calculation request may contain at most 1024 tables.');
+    const aliases = new Map();
+    for (const candidate of sheets)for (const [tableIndex, table] of (candidate.tables ?? []).entries()){
+        const identity = `${candidate.id}\u0000${tableIndex}`;
+        for (const alias of [
+            table.name,
+            table.displayName
+        ]){
+            if (!alias) continue;
+            const normalized = alias.toLocaleLowerCase();
+            const existing = aliases.get(normalized);
+            if (existing && existing !== identity) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet table name '${alias}' is ambiguous.`);
+            aliases.set(normalized, identity);
+        }
+    }
+    const ranges = [];
+    for (const table of tables){
+        for (const [kind, value] of [
+            [
+                'startRow',
+                table.startRow
+            ],
+            [
+                'endRow',
+                table.endRow
+            ],
+            [
+                'startColumn',
+                table.startColumn
+            ],
+            [
+                'endColumn',
+                table.endColumn
+            ]
+        ])if (!boundedSpreadsheetIndex(value, kind.endsWith('Row') ? office_kernel_spreadsheet_protocol_OFFICE_KERNEL_SPREADSHEET_MAX_ROWS : 16384)) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet table '${table.name}' has an out-of-bounds ${kind}.`);
+        if (table.startRow > table.endRow || table.startColumn > table.endColumn || table.columns.length !== table.endColumn - table.startColumn + 1) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet table '${table.name}' has an invalid range or column count.`);
+        validateTableName(table.name, 'name');
+        if (void 0 !== table.displayName) validateTableName(table.displayName, 'displayName');
+        const columnNames = new Set();
+        for (const column of table.columns){
+            validateTableName(column, 'column');
+            const normalized = column.toLocaleLowerCase();
+            if (columnNames.has(normalized)) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet table '${table.name}' contains duplicate column names.`);
+            columnNames.add(normalized);
+        }
+        if (table.headerRow && table.totalsRow && table.startRow === table.endRow) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet table '${table.name}' cannot use header and totals rows in one row.`);
+        for (const previous of ranges)if (table.startRow <= previous.endRow && table.endRow >= previous.startRow && table.startColumn <= previous.endColumn && table.endColumn >= previous.startColumn) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet tables '${previous.name}' and '${table.name}' overlap.`);
+        ranges.push({
+            startRow: table.startRow,
+            endRow: table.endRow,
+            startColumn: table.startColumn,
+            endColumn: table.endColumn,
+            name: table.name
+        });
+    }
+}
+function validateTableName(value, kind) {
+    if (!value.trim() || utf8ByteLength(value) > MAX_SPREADSHEET_IDENTIFIER_BYTES) throw office_kernel_spreadsheet_fallback_validation_kernelError('office.kernel.spreadsheet.table_invalid', `Spreadsheet table ${kind} must contain 1-${MAX_SPREADSHEET_IDENTIFIER_BYTES} UTF-8 bytes.`);
+}
 function boundedSpreadsheetIndex(value, exclusiveMaximum) {
     return Number.isSafeInteger(value) && value >= 0 && value < exclusiveMaximum;
 }
@@ -1566,6 +1629,428 @@ function isParserErrorValue(value) {
     const withSuffix = '#DIV/0' === normalized ? '#DIV/0!' : normalized;
     return isOfficeKernelSpreadsheetError(withSuffix);
 }
+class SpreadsheetStructuredReferenceError extends Error {
+    kind;
+    constructor(kind, message){
+        super(message);
+        this.name = 'SpreadsheetStructuredReferenceError';
+        this.kind = kind;
+    }
+}
+function parseSpreadsheetStructuredReference(reference) {
+    const open = reference.indexOf('[');
+    if (open < 0) throw invalidReference(reference);
+    const tableName = reference.slice(0, open) || void 0;
+    const content = outerGroup(reference.slice(open));
+    if (null === content) throw invalidReference(reference);
+    const rows = {
+        all: false,
+        headers: false,
+        data: false,
+        totals: false,
+        current: false
+    };
+    let firstColumn;
+    let lastColumn;
+    if (content.startsWith('@')) {
+        rows.current = true;
+        const column = parseCurrentColumn(content.slice(1), reference);
+        firstColumn = column;
+        lastColumn = column;
+    } else if (content.startsWith('[')) [firstColumn, lastColumn] = parseNestedSelection(content, reference, rows);
+    else {
+        const item = tableItem(content);
+        if (item) applyTableItem(rows, item, reference);
+        else {
+            const column = parsePlainColumn(content, reference);
+            firstColumn = column;
+            lastColumn = column;
+        }
+    }
+    if (!rows.all && !rows.headers && !rows.data && !rows.totals && !rows.current) rows.data = true;
+    return {
+        tableName,
+        firstColumn,
+        lastColumn,
+        rows
+    };
+}
+class SpreadsheetStructuredReferenceCatalog {
+    sheets;
+    definitions = [];
+    byName = new Map();
+    bySheet = new Map();
+    constructor(sheets){
+        this.sheets = sheets;
+        for (const sheet of sheets){
+            const indexes = [];
+            for (const table of sheet.tables ?? []){
+                const definition = {
+                    ...table,
+                    sheetId: sheet.id,
+                    sheetName: sheet.name
+                };
+                const index = this.definitions.length;
+                this.definitions.push(definition);
+                indexes.push(index);
+                for (const alias of [
+                    table.name,
+                    table.displayName
+                ]){
+                    if (!alias) continue;
+                    const key = alias.toLocaleLowerCase();
+                    if (!this.byName.has(key)) this.byName.set(key, index);
+                }
+            }
+            this.bySheet.set(sheet.id, indexes);
+        }
+    }
+    resolve(qualifier, reference, currentSheet, currentColumn, currentRow) {
+        const parsed = parseSpreadsheetStructuredReference(reference);
+        const table = this.resolveTable(parsed, reference, currentSheet, currentColumn, currentRow);
+        if (qualifier && table.sheetName.toLocaleLowerCase() !== qualifier.toLocaleLowerCase()) throw new SpreadsheetStructuredReferenceError('missing-table', `Spreadsheet table '${table.name}' is not on worksheet '${qualifier}'.`);
+        if (parsed.rows.current && currentSheet.id !== table.sheetId) throw new SpreadsheetStructuredReferenceError('unsupported', `Structured reference #This Row requires the current formula cell to be on table '${table.name}'.`);
+        const [startColumn, endColumn] = this.resolveColumns(table, parsed);
+        return this.resolveRows(table, parsed.rows, currentRow).map(([startRow, endRow])=>({
+                sheetId: table.sheetId,
+                sheetName: table.sheetName,
+                startRow,
+                endRow,
+                startColumn,
+                endColumn
+            }));
+    }
+    resolveTable(parsed, reference, currentSheet, currentColumn, currentRow) {
+        if (parsed.tableName) {
+            const index = this.byName.get(parsed.tableName.toLocaleLowerCase());
+            if (void 0 === index) throw new SpreadsheetStructuredReferenceError('missing-table', `Spreadsheet table '${parsed.tableName}' does not exist.`);
+            const table = this.definitions[index];
+            if (!table) throw invalidReference(reference);
+            return table;
+        }
+        const matching = (this.bySheet.get(currentSheet.id) ?? []).map((index)=>this.definitions[index]).filter((table)=>void 0 !== table && currentRow >= table.startRow && currentRow <= table.endRow && currentColumn >= table.startColumn && currentColumn <= table.endColumn);
+        if (!matching.length) throw new SpreadsheetStructuredReferenceError('missing-table', `Table-local structured reference '${reference}' requires the current formula cell to be inside a Spreadsheet table.`);
+        if (matching.length > 1) throw new SpreadsheetStructuredReferenceError('unsupported', `Table-local structured reference '${reference}' is ambiguous at the current formula cell.`);
+        return matching[0];
+    }
+    resolveColumns(table, parsed) {
+        let first = 0;
+        let last = table.columns.length - 1;
+        if (void 0 !== parsed.firstColumn && void 0 !== parsed.lastColumn) {
+            first = table.columns.findIndex((column)=>column.toLocaleLowerCase() === parsed.firstColumn.toLocaleLowerCase());
+            last = table.columns.findIndex((column)=>column.toLocaleLowerCase() === parsed.lastColumn.toLocaleLowerCase());
+            if (first < 0) throw new SpreadsheetStructuredReferenceError('missing-column', `Spreadsheet table '${table.name}' has no column '${parsed.firstColumn}'.`);
+            if (last < 0) throw new SpreadsheetStructuredReferenceError('missing-column', `Spreadsheet table '${table.name}' has no column '${parsed.lastColumn}'.`);
+            if (first > last) throw new SpreadsheetStructuredReferenceError('unsupported', `Structured-reference column range '${parsed.firstColumn}:${parsed.lastColumn}' is reversed.`);
+        }
+        if (first < 0 || last < first || table.startColumn + last > table.endColumn) throw invalidReference(table.name);
+        return [
+            table.startColumn + first,
+            table.startColumn + last
+        ];
+    }
+    resolveRows(table, rows, currentRow) {
+        const selected = [];
+        if (rows.all) selected.push([
+            table.startRow,
+            table.endRow
+        ]);
+        if (rows.headers) {
+            if (!table.headerRow) throw missingRows(table, '#Headers');
+            selected.push([
+                table.startRow,
+                table.startRow
+            ]);
+        }
+        if (rows.data) selected.push(this.dataRows(table));
+        if (rows.totals) {
+            if (!table.totalsRow) throw missingRows(table, '#Totals');
+            selected.push([
+                table.endRow,
+                table.endRow
+            ]);
+        }
+        if (rows.current) {
+            const [start, end] = this.dataRows(table);
+            if (currentRow < start || currentRow > end) throw new SpreadsheetStructuredReferenceError('unsupported', `Structured reference #This Row requires the current formula row to be inside table '${table.name}'.`);
+            selected.push([
+                currentRow,
+                currentRow
+            ]);
+        }
+        selected.sort((left, right)=>left[0] - right[0]);
+        const merged = [];
+        for (const [start, end] of selected){
+            const previous = merged.at(-1);
+            if (previous && start <= previous[1] + 1) previous[1] = Math.max(previous[1], end);
+            else merged.push([
+                start,
+                end
+            ]);
+        }
+        if (!merged.length) throw new SpreadsheetStructuredReferenceError('unsupported', 'Structured reference selects no table rows.');
+        return merged;
+    }
+    dataRows(table) {
+        const start = table.startRow + (table.headerRow ? 1 : 0);
+        const end = table.endRow - (table.totalsRow ? 1 : 0);
+        if (start > end) throw new SpreadsheetStructuredReferenceError('unsupported', `Spreadsheet table '${table.name}' has no data rows.`);
+        return [
+            start,
+            end
+        ];
+    }
+}
+function expandSpreadsheetStructuredReferences(formula, catalog, currentSheet, currentRow, currentColumn) {
+    const hasEquals = formula.startsWith('=');
+    const source = hasEquals ? formula.slice(1) : formula;
+    let output = '';
+    let cursor = 0;
+    while(cursor < source.length){
+        const character = source[cursor] ?? '';
+        if ('"' === character) {
+            const end = quotedStringEnd(source, cursor);
+            output += source.slice(cursor, end);
+            cursor = end;
+            continue;
+        }
+        const token = scanStructuredReference(source, cursor);
+        if (!token) {
+            output += character;
+            cursor += 1;
+            continue;
+        }
+        const areas = catalog.resolve(token.qualifier, token.reference, currentSheet, currentColumn, currentRow);
+        if (areas.length > 1) throw new SpreadsheetStructuredReferenceError('unsupported', `Structured reference '${token.reference}' resolves to disjoint row areas; the JavaScript fallback requires a contiguous range.`);
+        const ranges = areas.map((area)=>{
+            const prefix = area.sheetId === currentSheet.id ? '' : `${quoteSheetName(area.sheetName)}!`;
+            const start = cellAddress(area.startRow, area.startColumn);
+            const end = cellAddress(area.endRow, area.endColumn);
+            return `${prefix}${start}${start === end ? '' : `:${end}`}`;
+        });
+        output += 1 === ranges.length ? ranges[0] : `(${ranges.join(',')})`;
+        cursor = token.end;
+    }
+    return hasEquals ? `=${output}` : output;
+}
+function scanStructuredReference(source, start) {
+    const qualified = scanQualifier(source, start);
+    let cursor = qualified?.end ?? start;
+    const qualifier = qualified?.name;
+    if ('[' === source[cursor]) {
+        const end = matchingBracket(source, cursor);
+        if (null === end) return null;
+        const content = source.slice(cursor + 1, end - 1);
+        if (!content.startsWith('@') && !content.startsWith('#') && !content.startsWith('[')) return null;
+        return {
+            end,
+            qualifier,
+            reference: source.slice(cursor, end)
+        };
+    }
+    const nameStart = cursor;
+    if (!isNameStart(source[cursor] ?? '')) return null;
+    cursor += 1;
+    while(cursor < source.length && isNameContinue(source[cursor]))cursor += 1;
+    if ('[' !== source[cursor]) return null;
+    const end = matchingBracket(source, cursor);
+    if (null === end) throw invalidReference(source.slice(nameStart, source.length));
+    return {
+        end,
+        qualifier,
+        reference: source.slice(nameStart, end)
+    };
+}
+function scanQualifier(source, start) {
+    if ("'" === source[start]) {
+        let cursor = start + 1;
+        let decoded = '';
+        while(cursor < source.length){
+            const character = source[cursor];
+            if ("'" === character) {
+                if ("'" === source[cursor + 1]) {
+                    decoded += "'";
+                    cursor += 2;
+                    continue;
+                }
+                if ('!' === source[cursor + 1]) return {
+                    name: decoded,
+                    end: cursor + 2
+                };
+                break;
+            }
+            decoded += character;
+            cursor += 1;
+        }
+        return null;
+    }
+    let cursor = start;
+    while(cursor < source.length && isQualifierCharacter(source[cursor]))cursor += 1;
+    if ('!' !== source[cursor] || cursor === start) return null;
+    return {
+        name: source.slice(start, cursor),
+        end: cursor + 1
+    };
+}
+function matchingBracket(source, start) {
+    let depth = 0;
+    for(let cursor = start; cursor < source.length; cursor += 1){
+        const character = source[cursor];
+        if ("'" === character) {
+            cursor += "'" === source[cursor + 1] ? 1 : 0;
+            continue;
+        }
+        if ('[' === character) depth += 1;
+        else if (']' === character) {
+            depth -= 1;
+            if (0 === depth) return cursor + 1;
+            if (depth < 0) break;
+        }
+    }
+    return null;
+}
+function outerGroup(value) {
+    if (!value.startsWith('[')) return null;
+    const end = matchingBracket(value, 0);
+    return end === value.length ? value.slice(1, -1) : null;
+}
+function bracketAtom(value) {
+    if (!value.startsWith('[')) return null;
+    const end = matchingBracket(value, 0);
+    return null === end ? null : {
+        atom: value.slice(1, end - 1),
+        consumed: end
+    };
+}
+function parseCurrentColumn(value, reference) {
+    if (value.startsWith('[')) {
+        const atom = bracketAtom(value);
+        if (!atom || atom.consumed !== value.length) throw invalidReference(reference);
+        const column = decodeAtom(atom.atom);
+        if (!column) throw invalidReference(reference);
+        return column;
+    }
+    return parsePlainColumn(value, reference);
+}
+function parseNestedSelection(content, reference, rows) {
+    const atoms = [];
+    const separators = [];
+    let cursor = 0;
+    while(cursor < content.length){
+        const atom = bracketAtom(content.slice(cursor));
+        if (!atom) throw invalidReference(reference);
+        atoms.push(atom.atom);
+        cursor += atom.consumed;
+        if (cursor === content.length) break;
+        const separator = content[cursor];
+        if (',' !== separator && ':' !== separator) throw invalidReference(reference);
+        separators.push(separator);
+        cursor += 1;
+    }
+    const columns = [];
+    atoms.forEach((atom, index)=>{
+        const item = tableItem(atom);
+        if (item) applyTableItem(rows, item, reference);
+        else {
+            const column = decodeAtom(atom);
+            if (!column) throw invalidReference(reference);
+            columns.push({
+                index,
+                name: column
+            });
+        }
+    });
+    if (0 === columns.length) {
+        if (separators.includes(':')) throw invalidReference(reference);
+        return [
+            void 0,
+            void 0
+        ];
+    }
+    if (1 === columns.length) {
+        if (separators.includes(':')) throw invalidReference(reference);
+        return [
+            columns[0].name,
+            columns[0].name
+        ];
+    }
+    const first = columns[0];
+    const last = columns[1];
+    if (2 === columns.length && last.index === first.index + 1 && ':' === separators[first.index] && separators.every((separator, index)=>index === first.index || ',' === separator)) return [
+        first.name,
+        last.name
+    ];
+    throw new SpreadsheetStructuredReferenceError('unsupported', 'Disjoint structured-reference columns are not supported.');
+}
+function tableItem(value) {
+    const normalized = value.toLocaleLowerCase();
+    if ('#all' === normalized) return 'all';
+    if ('#headers' === normalized) return 'headers';
+    if ('#data' === normalized) return 'data';
+    if ('#totals' === normalized) return 'totals';
+    if ('#this row' === normalized) return 'current';
+}
+function applyTableItem(rows, item, reference) {
+    rows['current' === item ? 'current' : item] = true;
+    if (rows.current && (rows.all || rows.headers || rows.data || rows.totals)) throw new SpreadsheetStructuredReferenceError('unsupported', `Structured reference '${reference}' cannot combine #This Row with another item.`);
+}
+function parsePlainColumn(value, reference) {
+    if (!value || /[[\],:]/u.test(value)) throw invalidReference(reference);
+    const column = decodeAtom(value);
+    if (!column) throw invalidReference(reference);
+    return column;
+}
+function decodeAtom(value) {
+    let output = '';
+    for(let cursor = 0; cursor < value.length; cursor += 1){
+        const character = value[cursor];
+        if ("'" === character) {
+            const escaped = value[cursor + 1];
+            if (void 0 === escaped) throw invalidReference(value);
+            output += escaped;
+            cursor += 1;
+        } else output += character;
+    }
+    return output;
+}
+function missingRows(table, item) {
+    return new SpreadsheetStructuredReferenceError('unsupported', `Structured reference ${item} requires table '${table.name}' to contain that row.`);
+}
+function invalidReference(reference) {
+    return new SpreadsheetStructuredReferenceError('invalid', `Structured reference '${reference}' is not in a supported canonical form.`);
+}
+function quotedStringEnd(source, start) {
+    for(let cursor = start + 1; cursor < source.length; cursor += 1)if ('"' === source[cursor]) {
+        if ('"' === source[cursor + 1]) {
+            cursor += 1;
+            continue;
+        }
+        return cursor + 1;
+    }
+    return source.length;
+}
+function cellAddress(row, column) {
+    let value = column + 1;
+    let label = '';
+    while(value > 0){
+        value -= 1;
+        label = String.fromCharCode(65 + value % 26) + label;
+        value = Math.floor(value / 26);
+    }
+    return `${label}${row + 1}`;
+}
+function quoteSheetName(name) {
+    return /^[A-Za-z_][A-Za-z0-9_.]*$/u.test(name) ? name : `'${name.replaceAll("'", "''")}'`;
+}
+function isNameStart(value) {
+    return /^[A-Za-z_\\?]$/u.test(value);
+}
+function isNameContinue(value) {
+    return /^[A-Za-z0-9_.\\?]$/u.test(value);
+}
+function isQualifierCharacter(value) {
+    return /^[A-Za-z0-9_.\\?[\]:$]$/u.test(value);
+}
 async function calculateSpreadsheetInJavaScript(request) {
     validateSpreadsheetCalculationRequest(request);
     const formulaParser = await import("@fortune-sheet/formula-parser");
@@ -1581,9 +2066,11 @@ class JavaScriptSpreadsheetEvaluator {
     stack = [];
     calculationOrder = [];
     issues = [];
+    tableCatalog;
     constructor(request, formulaParser){
         this.request = request;
         this.formulaParser = formulaParser;
+        this.tableCatalog = new SpreadsheetStructuredReferenceCatalog(request.sheets);
         for (const sheet of request.sheets){
             this.sheetsByName.set(sheet.name.toLowerCase(), sheet);
             for (const cell of sheet.cells)this.cells.set(cellKey(sheet.id, cell.row, cell.column), {
@@ -1654,6 +2141,13 @@ class JavaScriptSpreadsheetEvaluator {
     }
     evaluateFormula(coordinate, indexed) {
         const formula = indexed.cell.formula ?? '';
+        let expandedFormula;
+        try {
+            expandedFormula = expandSpreadsheetStructuredReferences(formula, this.tableCatalog, indexed.sheet, coordinate.row, coordinate.column);
+        } catch (error) {
+            const message = error instanceof SpreadsheetStructuredReferenceError ? error.message : 'Structured reference expansion failed.';
+            return failedEvaluation(indexed.cell.value, calculationIssue(coordinate, 'office.kernel.spreadsheet.formula_unsupported', message));
+        }
         const parser = new this.formulaParser.Parser();
         let unresolvedDependency = false;
         let unsupportedReference = false;
@@ -1687,7 +2181,7 @@ class JavaScriptSpreadsheetEvaluator {
                 return true;
             }));
         });
-        const parsed = parser.parse(normalizeFormulaForFortuneParser(formula), {
+        const parsed = parser.parse(normalizeFormulaForFortuneParser(expandedFormula), {
             sheetId: indexed.sheet.id
         });
         if (unsupportedFunction) return failedEvaluation(indexed.cell.value, calculationIssue(coordinate, 'office.kernel.spreadsheet.formula_unsupported', `Formula function '${unsupportedFunction}' is not supported.`));
@@ -1711,7 +2205,8 @@ class JavaScriptSpreadsheetEvaluator {
     }
     rangeValues(currentSheet, start, end, onUnresolvedDependency, onUnsupportedReference, reserveRangeCells) {
         const startCoordinate = this.resolveCoordinate(currentSheet, start);
-        const endCoordinate = this.resolveCoordinate(currentSheet, end);
+        const rangeSheet = start.sheetName ? this.sheetsByName.get(start.sheetName.toLowerCase()) : currentSheet;
+        const endCoordinate = rangeSheet ? this.resolveCoordinate(rangeSheet, end) : null;
         if (!startCoordinate || !endCoordinate || startCoordinate.sheetId !== endCoordinate.sheetId) {
             onUnsupportedReference();
             return [];