Add AreaReference support for structured table references

[ken-swyfft]

Summary

Adds a constructor overload to AreaReference that transparently handles Excel structured table references (e.g., Table7[#Headers], Table1[[#Data],[Column1]]):

new AreaReference(reference, version, workbook)

When a workbook is provided, structured table references are detected and resolved automatically against the workbook's table definitions. Regular A1-style references pass through unchanged. Without a workbook, behavior is identical to before.

Also adds AreaReference.IsStructuredReference(string) for callers that need to detect structured references without resolving them.

Includes a fix for flaky TestNPOI1469 (timestamp rounding, unrelated).

Problem

When a named range's RefersToFormula contains a structured table reference, new AreaReference(formula, version) throws ArgumentException because CellReference.SeparateRefParts only handles A1-style references. NPOI already has full structured reference parsing in FormulaParser, but it was only accessible during formula evaluation — not for generic reference resolution from AreaReference.

This is a real-world issue: Excel workbooks that use Tables (ListObjects) often have named ranges pointing to structured references like Table7[#Headers] or Table7[[#Headers],[Column1]]. Code that resolves named ranges to cell positions via AreaReference crashes on these workbooks.

Usage

// Create an IFormulaParsingWorkbook from your XSSFWorkbook:
var fpb = XSSFEvaluationWorkbook.Create((XSSFWorkbook)workbook);

// The constructor transparently handles both structured and regular references:
var namedRange = workbook.GetName("FormName");
var area = new AreaReference(namedRange.RefersToFormula, SpreadsheetVersion.EXCEL2007, fpb);

// area.FirstCell / area.LastCell now contain concrete cell coordinates,
// whether the formula was "Sheet1!$A$1:$C$7" or "Table7[#Headers]".

No special branching needed — structured references "just work."

For [#This Row] references that depend on the formula's row position, pass the row index:

var area = new AreaReference("Table1[#This Row]", SpreadsheetVersion.EXCEL2007, fpb, rowIndex: 5);

Approach

The existing 2-parameter constructor chains to a new 4-parameter overload:

public AreaReference(String reference, SpreadsheetVersion version)
    : this(reference, version, null, 0) { }

public AreaReference(String reference, SpreadsheetVersion version,
    IFormulaParsingWorkbook workbook, int rowIndex = 0) { ... }

When workbook is non-null and the reference matches structured reference syntax, the constructor delegates to the existing FormulaParser.ParseStructuredReference(). Otherwise, the original A1-style parsing runs unchanged.

Tests

18 tests in TestAreaReferenceStructuredReferences organized in three groups:

Structured reference resolution (with workbook):

• #Headers, #Data, #All, #This Row specifiers
• Single column, column range, headers+column combinations
• Invalid table name → KeyNotFoundException

Backward compatibility (without workbook):

• Regular references still parse correctly (single cell, multi-cell, sheet-qualified, absolute, whole-column)
• Structured references still throw ArgumentException

Workbook + regular references:

• Regular A1-style references pass through correctly when a workbook is provided
• Sheet-qualified and single-cell references work
• Null workbook behaves identically to 2-param constructor

All existing tests continue to pass.

[ken-swyfft]

@tonyqus - Just as an FYI, we ran into this in a production scenario that wasn't adequately covered by our tests, so it hadn't turned up in our previous testing.

[ken-swyfft]

Overall: Approve. Clean, well-scoped change that solves a real problem. Reuses existing FormulaParser infrastructure rather than duplicating structured reference parsing. Constructor chaining preserves full backward compatibility. Test coverage is thorough — especially the backward compat tests after the constructor refactor.

A few optional suggestions inline — none are blocking.

[Copilot]

Pull request overview

Adds structured table reference support to AreaReference by introducing a workbook-aware constructor overload that resolves Excel table references (e.g., Table1[#Headers]) into concrete cell ranges, plus a helper to detect structured references. Also stabilizes a flaky timestamp-related test.

Changes:

• Add AreaReference(String, SpreadsheetVersion, IFormulaParsingWorkbook, int rowIndex = 0) to resolve structured references via FormulaParser.ParseStructuredReference when a workbook is provided.
• Add AreaReference.IsStructuredReference(string) for structured reference detection.
• Fix TestNPOI1469 flakiness by truncating timestamps to whole seconds before formatting/comparison.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
main/SS/Util/AreaReference.cs	Adds workbook-aware parsing path for structured references and exposes structured-reference detection helper.
testcases/ooxml/SS/Util/TestAreaReferenceStructuredReferences.cs	New NUnit tests covering structured resolution, backward compatibility, and workbook + regular references.
testcases/main/HSSF/UserModel/TestCellStyle.cs	Stabilizes TestNPOI1469 by avoiding sub-second rounding mismatches.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.