[Aias00]

Purpose of the pull request

Related: #1140

Filling an XLSX template can leave an Excel Table at its original area after its data rows expand. A template table at A1:C2 still reopens with that reference after three list records are filled. POI row shifting can also rewrite structured-reference formulas into fixed A1 ranges, so merely resizing the table does not restore the intended formula behavior.

What's changed?

• Recognize existing native XLSX tables during collection fills and track their row ranges across repeated fills. Finalize Table and AutoFilter references through the existing workbook disposal hook before serialization.
• Support both in-memory modes, including a prototype at the last physical row, multiple existing body rows, tables shifted by inserted worksheet rows, and independently filled tables on different sheets.
• Preserve names, styles, column metadata, calculated-column definitions and totals definitions. Keep totals out of the AutoFilter range and request formula recalculation on open.
• Preserve structured-reference expressions while POI shifts ordinary A1 references in the same formula. Temporarily protect those formula cells during POI's own shift and restore them in finally, including failure cleanup.
• Reject horizontal table expansion, totals/header overwrites, overlapping tables, inconsistent column metadata, duplicate names and worksheet overflow before writing the fill.
• Document the first implementation's supported behavior in the English and Chinese fill guides, with save/reopen regressions for both modes and pristine POI sheet cloning.

The implementation uses the existing POI dependency and existing workbook finalization lifecycle. It adds no public builder option or separate table DSL.

Scope

This implements the RFC's initial row-growth behavior for existing XLSX tables with one header row and at most one totals row. Whole-row insertion affects every table intersected by those rows. Without insertion, growth cannot overwrite totals or another table.

Native calculated-column definitions are preserved for Excel to apply; Fesod does not evaluate formulas or materialize formula caches for every generated row. Empty collections leave tables unchanged. Pristine sheet cloning is verified with inMemory(true) and POI-created independent table parts/names. Cloning an already-filled sheet, advanced clone formula remapping, creating tables, and adding XLS native-table support remain outside this change.

Validation

• Before the fix, saved/reopened templates retained the original table areas in both in-memory modes; the new public fill regression failed accordingly.
• The mixed-formula regression also failed before formula protection: expected SUM(Orders[Quantity])+Data!B11, actual SUM(Data!B2:B2)+Data!B11.
• Java 8: ./mvnw -B -pl fesod-common,fesod-shaded,fesod-sheet -Dtest=StructuredTableFillTest,FillDataTest -Dsurefire.failIfNoSpecifiedTests=false package passed, 40 tests.
• ./mvnw -B -pl fesod-common,fesod-shaded,fesod-sheet -Dtest.excludedGroups=fuzz package spotless:check: passed on JDK 17, 1,904 tests (60 common + 1,844 sheet), zero failures/errors/skips.
• Checkstyle, Hawkeye (622 files), full-reactor apache-rat:check (zero unapproved/unknown licenses) and the English/Chinese Markdown lint checks passed.
• Default Javadoc generation fails at two pre-existing Lombok-generated method links in ReadSheetHolder:111 and SimpleReadCacheSelector:90. A clean checkout of base 8005480a reproduces both errors. Generation with -Ddoclint=all,-reference passes; the default reference-check failure remains explicit.
• No interactive Excel client validation was run; tests generate actual XLSX files and reopen them with POI.

Checklist

• I have read the Contributor Guide.
• I have written the necessary doc or comment.
• I have added regression tests for the changed behavior.