@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/core/worksheet-model.js

@@ -1,11 +1,3 @@
-// The field table behind `Worksheet.model`'s round-trip.
-//
-// Both directions used to be hand-written statement lists, one in the getter and one in the setter,
-// each enumerating the same nineteen fields. Nothing but a comment asked the next editor to touch
-// both, and a field exported but not imported loses data silently — the merge-loss failure the
-// model contract exists to prevent. Here each field declares both directions in one place, and the
-// registry is proved exhaustive over `keyof WorksheetModel` at compile time, so adding a field
-// without wiring it is an error naming the field rather than a review catch.
 import { cellToModel, copyCellContent } from './cell.js';
 import { cloneConditionalFormatting } from './conditional-formatting.js';
 import { overwrite, replaceContents } from './containers.js';
@@ -14,11 +6,6 @@ import { INTERNAL } from './internal.js';
 function facet(key, read, write) {
     return { key, read, write: (sheet, model) => write(sheet, model[key]) };
 }
-/**
- * Every field of a {@link WorksheetModel}, in the order a model assignment applies them. Order is
- * load-bearing: cells are placed at their exact positions before any merge exists, so a covered
- * cell's value lands where the model says instead of being routed to a region master mid-load.
- */
 export const WORKSHEET_MODEL_FACETS = [
     facet('state', (sheet) => sheet.state, (sheet, value) => {
         sheet.state = value;
@@ -40,8 +27,6 @@ export const WORKSHEET_MODEL_FACETS = [
     }),
     facet('rows', (sheet) => {
         const rows = [];
-        // A row appears here only for its formatting; the cells it holds are the `cells` field's
-        // business, and a row carrying nothing but cells has no properties to round-trip.
         for (const { number, properties } of sheet.rows()) {
             if (properties !== undefined)
                 rows.push({ number, properties: { ...properties } });
@@ -82,16 +67,10 @@ export const WORKSHEET_MODEL_FACETS = [
         for (const options of value)
             sheet.addTable(options);
     }),
-    facet('autoFilter', (sheet) => sheet.autoFilter, 
-    // Through the public setter, which re-canonicalises the range and — on `undefined` — clears any
-    // autofilter the destination held. That clearing is why the field is applied even when absent.
-    (sheet, value) => {
+    facet('autoFilter', (sheet) => sheet.autoFilter, (sheet, value) => {
         sheet.autoFilter = value;
     }),
-    facet('protection', (sheet) => sheet.protection, 
-    // A loaded credential is already hashed, so it is reinstated verbatim rather than re-derived;
-    // `protect` cannot express that, which is why this goes through the internal channel.
-    (sheet, value) => {
+    facet('protection', (sheet) => sheet.protection, (sheet, value) => {
         if (value === undefined)
             sheet.unprotect();
         else

package/dist/core/worksheet.d.ts

@@ -259,6 +259,28 @@ export declare class Worksheet {
      * other axis: a value in column E makes this 5 even if columns B–D are empty.
      */
     get columnCount(): number;
+    /**
+     * The sheet's used range as one handle — `A1` through the last row and column that carry
+     * anything — or `undefined` when there is no rectangle to name.
+     *
+     * This is {@link rowCount} and {@link columnCount} said once, so a caller stops reassembling
+     * `A1:${numberToColumn(sheet.columnCount)}${sheet.rowCount}` by hand. That is what an
+     * {@link autoFilter} covering the whole sheet wants — `sheet.autoFilter = sheet.usedRange.address`
+     * — and Excel writes exactly that ref for a filter it applies itself. A header-only ref filters
+     * nothing, which is the bug this exists to make hard to write.
+     *
+     * It inherits both counts' definition of *used*, so it spans gaps (a value in `E5` and nothing
+     * else still gives `A1:E5`) and includes a line carrying only its own formatting — a set column
+     * width, an outline level, a merge reaching past the last value. `undefined` therefore means
+     * strictly "no rectangle": an empty sheet, or one carrying only row formatting and no columns at
+     * all (or the reverse), where an axis has no extent to bound the other against.
+     *
+     * Not the same thing as the `<dimension>` a written package records. That is the *tight* box —
+     * top-left at the first used cell, formatting-only rows excluded — because Excel writes it to
+     * describe where the data is, not what the grid spans. This handle is anchored at `A1`, because
+     * a caller asking for the used range means the block to read, style or filter.
+     */
+    get usedRange(): Range | undefined;
     /** The columns carrying format properties, as handles, in ascending index order. */
     columns(): IterableIterator<Column>;
     /**