@shbernal/ts-xlsx 1.2.0 → 1.3.1

package/README.md

@@ -236,6 +236,11 @@ npx skills add ./node_modules/@shbernal/ts-xlsx     # offline, matches your inst
 npx skills add shbernal/ts-xlsx                     # or straight from the repo
 ```
 
+That writes the skill under `.agents/skills/`, links it into whichever agent directories it
+finds, and records what it did in `skills-lock.json`. Track the lock file and ignore the
+copies: they are derived, `npx skills experimental_install` rebuilds them from the lock, and
+`npx skills update` overwrites them in place.
+
 It covers triage (is this bug ours or your file's?), reducing a failure to a script that
 builds its own input, and — because spreadsheets carry real data — never uploading a
 workbook to a public tracker. Once the reproduction stands on its own, it files without

package/dist/core/workbook.d.ts

@@ -89,12 +89,24 @@ export declare const DEFAULT_WORKBOOK_VIEW: {
     readonly height: 12220;
     readonly activeTab: 0;
 };
-/** Document-level metadata written to the package's core properties. */
+/**
+ * Document-level metadata — what Excel's File ▸ Info panel shows. Mostly the package's core
+ * properties (`docProps/core.xml`); `company` is the exception and lives in the extended part,
+ * because that is where OOXML puts it. One interface either way: which part a field lands in is
+ * the format's business, not the caller's.
+ */
 export interface WorkbookProperties {
+    /** `dc:title` — the document's title, as Excel's File ▸ Info shows it. */
+    title?: string;
     creator?: string;
     lastModifiedBy?: string;
     created?: Date;
     modified?: Date;
+    /**
+     * `Company` in the extended properties (`docProps/app.xml`), not the core ones — the only
+     * field here that does not live beside the others, because OOXML puts it in the other part.
+     */
+    company?: string;
 }
 /**
  * A named reference in the workbook — the entries Excel surfaces in its Name Manager. A name maps

package/dist/core/worksheet.d.ts

@@ -51,6 +51,15 @@ export interface SheetView {
     ySplit?: number;
     /** The cell anchoring the bottom-right scrolling pane; defaults to the first unfrozen cell. */
     topLeftCell?: string;
+    /**
+     * Whether the grid's cell lines are drawn on screen. Absent means Excel's default, which is on,
+     * so only `false` is worth setting: a sheet that paints its own fills and borders reads as a
+     * document rather than a spreadsheet once the grid behind it is off.
+     *
+     * On screen only, and unrelated to {@link PrintOptions.gridLines}, which decides whether the grid
+     * is *printed*. Excel exposes them as two separate checkboxes because the answers differ.
+     */
+    showGridLines?: boolean;
 }
 /**
  * Per-column formatting. A column may exist purely to carry these, with no cells. The style

package/dist/io/opc/zip-mtime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Modification time stamped on every zip entry, so package bytes depend on the workbook alone.
+ * Encodes as 2001-01-01 12:00:00 in the DOS date field on any machine, in any timezone.
+ */
+export declare const FIXED_ENTRY_MTIME: number;

package/dist/io/opc/zip-mtime.js

@@ -0,0 +1 @@
+export const FIXED_ENTRY_MTIME = new Date(2001, 0, 1, 12, 0, 0, 0).getTime();

package/dist/io/xlsx/edit-vba.js

@@ -3,6 +3,7 @@ import { VbaAuthorError } from '../../vba/errors.js';
 import { addVbaReference, removeVbaModule, } from '../../vba/project-editor.js';
 import { relsPathFor } from '../opc/part-paths.js';
 import { parseRelationshipRecords, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from '../opc/read-opc.js';
+import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 const OFFICE_DOCUMENT_REL = 'officeDocument';
 const VBA_PROJECT_REL = 'vbaProject';
 const VBA_SIGNATURE_REL_INFIX = 'vbaProjectSignature';
@@ -21,7 +22,7 @@ function applyToVbaProjectPart(xlsx, apply) {
     }
     files[binPath] = apply(bin);
     dropStaleSignature(files, binPath);
-    return zipSync(files);
+    return zipSync(files, { mtime: FIXED_ENTRY_MTIME });
 }
 function locateVbaProjectPart(files) {
     const rootRels = textPart(files, '_rels/.rels');

package/dist/io/xlsx/read-worksheet.js

@@ -200,6 +200,7 @@ export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
                     break;
                 case 'tabColor':
                 case 'outlinePr':
+                case 'sheetView':
                 case 'pane':
                 case 'pageSetUpPr':
                 case 'printOptions':
@@ -312,6 +313,11 @@ function applySheetProperties(local, attrs, sheet) {
             if (attrs.summaryRight !== undefined)
                 sheet.outline.summaryRight = boolPresent(attrs.summaryRight);
             break;
+        case 'sheetView':
+            if (attrs.showGridLines !== undefined && !boolPresent(attrs.showGridLines)) {
+                sheet.view.showGridLines = false;
+            }
+            break;
         case 'pane':
             if (attrs.state === 'frozen' || attrs.state === 'frozenSplit') {
                 sheet.view.state = 'frozen';

package/dist/io/xlsx/read.js

@@ -53,6 +53,9 @@ export function readXlsx(data, options = {}) {
     const core = partText('docProps/core.xml');
     if (core !== undefined)
         applyCoreProperties(workbook, core);
+    const app = partText('docProps/app.xml');
+    if (app !== undefined)
+        applyAppProperties(workbook, app);
     workbook.protection = parseWorkbookProtection(workbookXml);
     applyWorkbookView(workbook.view, workbookXml);
     readWorkbookPersons(workbookRelsXml, pkg, workbook);
@@ -436,7 +439,13 @@ function parseWorkbookDefinedNames(xml, sheetOrder) {
     });
     return names;
 }
-const CORE_PROPERTY_LOCAL_NAMES = new Set(['creator', 'lastModifiedBy', 'created', 'modified']);
+const CORE_PROPERTY_LOCAL_NAMES = new Set([
+    'title',
+    'creator',
+    'lastModifiedBy',
+    'created',
+    'modified',
+]);
 function applyCoreProperties(workbook, xml) {
     let capture = '';
     let text = '';
@@ -453,7 +462,9 @@ function applyCoreProperties(workbook, xml) {
         onClose(name) {
             if (capture === '' || localName(name) !== capture)
                 return;
-            if (capture === 'creator')
+            if (capture === 'title')
+                workbook.properties.title = text;
+            else if (capture === 'creator')
                 workbook.properties.creator = text;
             else if (capture === 'lastModifiedBy')
                 workbook.properties.lastModifiedBy = text;
@@ -470,3 +481,23 @@ function applyCoreProperties(workbook, xml) {
         },
     });
 }
+function applyAppProperties(workbook, xml) {
+    let capture = false;
+    let text = '';
+    parseXml(xml, {
+        onOpen(name) {
+            capture = localName(name) === 'Company';
+            text = '';
+        },
+        onText(chunk) {
+            if (capture)
+                text += chunk;
+        },
+        onClose(name) {
+            if (!capture || localName(name) !== 'Company')
+                return;
+            workbook.properties.company = text;
+            capture = false;
+        },
+    });
+}

package/dist/io/xlsx/sheet-properties.js

@@ -4,10 +4,11 @@ import { attr, boolAttr, escapeAttr, escapeText, numberText } from '../../xml/xm
 import { colorAttrs } from './color-xml.js';
 export function sheetViewsXml(view, active) {
     const selected = active ? ' tabSelected="1"' : '';
+    const gridLines = view.showGridLines === false ? ' showGridLines="0"' : '';
     const xSplit = view.xSplit ?? 0;
     const ySplit = view.ySplit ?? 0;
     if (view.state !== 'frozen' || (xSplit === 0 && ySplit === 0)) {
-        return `<sheetViews><sheetView${selected} workbookViewId="0"/></sheetViews>`;
+        return `<sheetViews><sheetView${gridLines}${selected} workbookViewId="0"/></sheetViews>`;
     }
     const topLeftCell = view.topLeftCell ?? encodeAddress(xSplit + 1, ySplit + 1);
     const activePane = xSplit > 0 && ySplit > 0 ? 'bottomRight' : xSplit > 0 ? 'topRight' : 'bottomLeft';
@@ -16,7 +17,7 @@ export function sheetViewsXml(view, active) {
         (ySplit > 0 ? ` ySplit="${ySplit}"` : '') +
         ` topLeftCell="${escapeAttr(topLeftCell)}" activePane="${activePane}" state="frozen"/>`;
     const selection = `<selection pane="${activePane}" activeCell="${escapeAttr(topLeftCell)}" sqref="${escapeAttr(topLeftCell)}"/>`;
-    return `<sheetViews><sheetView${selected} workbookViewId="0">${pane}${selection}</sheetView></sheetViews>`;
+    return `<sheetViews><sheetView${gridLines}${selected} workbookViewId="0">${pane}${selection}</sheetView></sheetViews>`;
 }
 export function sheetPrXml(sheet) {
     const children = (sheet.tabColor !== undefined ? `<tabColor ${colorAttrs(sheet.tabColor)}/>` : '') +

package/dist/io/xlsx/workbook-xml.d.ts

@@ -9,4 +9,4 @@ export declare function workbookXml(workbook: Workbook, preservedRels: readonly
 export declare const FIXED_WORKBOOK_REL_COUNT = 2;
 export declare function workbookRelsXml(sheetCount: number, hasSharedStrings: boolean, personsRelId: string | null, preservedRels: readonly PreservedWorkbookRel[], pivots: readonly PivotPlan[]): string;
 export declare function corePropsXml(properties: WorkbookProperties): string;
-export declare function appPropsXml(): string;
+export declare function appPropsXml(properties: WorkbookProperties): string;

package/dist/io/xlsx/workbook-xml.js

@@ -232,6 +232,9 @@ export function workbookRelsXml(sheetCount, hasSharedStrings, personsRelId, pres
 }
 export function corePropsXml(properties) {
     const parts = [];
+    if (properties.title !== undefined) {
+        parts.push(`<dc:title>${escapeText(properties.title)}</dc:title>`);
+    }
     if (properties.creator !== undefined) {
         parts.push(`<dc:creator>${escapeText(properties.creator)}</dc:creator>`);
     }
@@ -253,7 +256,8 @@ export function corePropsXml(properties) {
 function w3cdtf(element, date) {
     return `<dcterms:${element} xsi:type="dcterms:W3CDTF">${date.toISOString()}</dcterms:${element}>`;
 }
-export function appPropsXml() {
+export function appPropsXml(properties) {
+    const company = properties.company === undefined ? '' : `<Company>${escapeText(properties.company)}</Company>`;
     return (XML_DECLARATION +
-        `<Properties xmlns="${NS.extProps}"><Application>ts-xlsx</Application></Properties>`);
+        `<Properties xmlns="${NS.extProps}"><Application>ts-xlsx</Application>${company}</Properties>`);
 }

package/dist/io/xlsx/write-stream.js

@@ -6,6 +6,7 @@ import { INTERNAL } from '../../core/internal.js';
 import { isSharedFormulaValue } from '../../core/value.js';
 import { Workbook } from '../../core/workbook.js';
 import { AuthoringError } from '../../errors.js';
+import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 import { buildColumnDefaults, buildPackageParts, createStyleRegistry, Extent, renderRow, } from './write.js';
 export class StreamedRow {
     #cells;
@@ -244,6 +245,7 @@ function streamZipPackage(parts, onChunk) {
         });
         for (const [name, data] of Object.entries(parts)) {
             const entry = new ZipDeflate(name, { level: 6 });
+            entry.mtime = FIXED_ENTRY_MTIME;
             zip.add(entry);
             entry.push(data, true);
         }

package/dist/io/xlsx/write.d.ts

@@ -37,6 +37,10 @@ export interface InternalWriteOptions extends WriteOptions {
 /**
  * Serialise a workbook into an `.xlsx` package.
  *
+ * The bytes are a pure function of the workbook: an unchanged model written twice produces two
+ * identical archives, because entry timestamps are pinned to a fixed date rather than taken from the
+ * clock. A committed `.xlsx` therefore only changes when something about it changed.
+ *
  * @throws {AuthoringError} if the workbook has no worksheets (a zero-sheet package is corrupt),
  *   or holds a value the writer cannot yet represent.
  */
@@ -44,7 +48,7 @@ export declare function writeXlsx(workbook: Workbook, options?: WriteOptions): U
 /**
  * Serialise a workbook into an `.xlsx` package, deflating off the calling thread.
  *
- * Produces the same package {@link writeXlsx} does — every part compresses to identical bytes — and
+ * Produces the same package {@link writeXlsx} does — byte for byte, entry timestamps included — and
  * exists for one reason: DEFLATE dominates the cost of writing a large workbook, and {@link writeXlsx}
  * spends all of it on the caller's thread. Here `fflate` deflates each part in a worker, so the event
  * loop keeps turning (stalls drop from the whole write to tens of milliseconds) and parts compress in

package/dist/io/xlsx/write.js

@@ -3,6 +3,7 @@ import { DEFAULT_THEME_XML } from '../../core/theme.js';
 import { AuthoringError } from '../../errors.js';
 import { THEME_PART_PATH } from '../opc/part-paths.js';
 import { relsPartXml } from '../opc/rels.js';
+import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 import { collectComments, commentsXml, vmlDrawingXml } from './comments.js';
 import { collectHyperlinks, planHyperlinks } from './hyperlinks.js';
 import { drawingRelsXml, drawingXml } from './images.js';
@@ -17,12 +18,12 @@ import { appPropsXml, contentTypesXml, corePropsXml, FIXED_WORKBOOK_REL_COUNT, r
 import { worksheetRelsXml, worksheetXml, } from './worksheet-xml.js';
 export { buildColumnDefaults, Extent, renderRow, } from './worksheet-xml.js';
 export function writeXlsx(workbook, options = {}) {
-    return zipSync(buildPackageParts(workbook, options), { level: 6 });
+    return zipSync(buildPackageParts(workbook, options), { level: 6, mtime: FIXED_ENTRY_MTIME });
 }
 export async function writeXlsxAsync(workbook, options = {}) {
     const parts = buildPackageParts(workbook, options);
     return await new Promise((resolve, reject) => {
-        zip(parts, { level: 6 }, (error, data) => {
+        zip(parts, { level: 6, mtime: FIXED_ENTRY_MTIME }, (error, data) => {
             if (error)
                 reject(error);
             else
@@ -177,7 +178,7 @@ export function buildPackageParts(workbook, options = {}) {
         '[Content_Types].xml': strToU8(contentTypesXml(sheets.length, allTables, commentNumbers, drawingNumbers, printerSettingsNumbers, media.extensions, hasSharedStrings, preserved.parts, allPivots, preservedWorkbookRels, threadedCommentNumbers, persons.length > 0)),
         '_rels/.rels': strToU8(rootRelsXml(preserved.root)),
         'docProps/core.xml': strToU8(corePropsXml(workbook.properties)),
-        'docProps/app.xml': strToU8(appPropsXml()),
+        'docProps/app.xml': strToU8(appPropsXml(workbook.properties)),
         'xl/workbook.xml': strToU8(workbookXml(workbook, preservedWorkbookRels, allPivots)),
         'xl/_rels/workbook.xml.rels': strToU8(workbookRelsXml(sheets.length, hasSharedStrings, personsRelId, preservedWorkbookRels, allPivots)),
         'xl/styles.xml': strToU8(styles.toXml()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
   "license": "MIT",
   "author": "shbernal",