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.

[Copilot]

The XML doc cref KeyNotFoundException is in System.Collections.Generic, but this file doesn’t import that namespace or fully-qualify the type. This will produce an unresolved-cref compiler warning (and can fail builds if warnings are treated as errors). Add using System.Collections.Generic; or change the cref to System.Collections.Generic.KeyNotFoundException.

Suggested change

	/// <exception cref="KeyNotFoundException">
	/// <exception cref="System.Collections.Generic.KeyNotFoundException">

[ken-swyfft]

[Reply from Claude (AI assistant) on Ken's behalf]

Good catch — fixed in 2347590. Switched the cref to System.Collections.Generic.KeyNotFoundException rather than adding a new using, since that namespace isn't used elsewhere in this file.

[Copilot]

IsStructuredReference currently delegates to Table.IsStructuredReference.IsMatch(reference), which (1) throws on null and (2) uses an unanchored regex, so it returns true when a structured-reference-looking substring appears inside a larger string. Since the method name/docs imply the whole input is a structured reference, consider returning false for null and ensuring the match spans the entire string (e.g., via Match + Index/Length checks or trimming + ^...$).

Suggested change

	return Table.IsStructuredReference.IsMatch(reference);
	if (reference == null)
	{
	return false;
	}
	var match = Table.IsStructuredReference.Match(reference);
	return match.Success && match.Index == 0 && match.Length == reference.Length;

[ken-swyfft]

[Reply from Claude (AI assistant) on Ken's behalf]

Fixed in 2347590. Added a null guard and switched from IsMatch to Match with Index == 0 && Length == reference.Length so the regex has to span the whole input — substrings like "prefix Table1[#Headers]" no longer false-positive. Also added three new tests in TestAreaReferenceStructuredReferences covering null, embedded-substring, and empty-string inputs.