werkmap 0.1.0 → 0.3.0

package/README.md

@@ -88,7 +88,7 @@ werkmap writes the slice of the format a report needs, and refuses the rest.
 **It does not fit when:**
 
 - You need to read, edit or convert an existing workbook.
-- You need formulas, charts, pivot tables, conditional formatting, data validation, hyperlinks, comments or sheet protection.
+- You need formulas, charts, pivot tables, conditional formatting, data validation, hyperlinks, comments, sheet protection, or a page header and footer.
 - You need column widths or row heights. A reader sizes columns from its own defaults.
 - You have more rows than fit in memory. There is no streaming, row-at-a-time output.
 
@@ -141,6 +141,14 @@ One merged range across `width` columns of `row`, starting at the 1-based column
 
 Freeze the top `rows` rows. `0` clears.
 
+### `sheet.print(setup)`
+
+How this worksheet prints: `{ margin, size, orientation, fit, titles }`, every key optional. `margin` is all four page margins in points, `size` one of `letter`, `tabloid`, `legal`, `A3`, `A4`, `A5`, `orientation` either `portrait` or `landscape`, and `fit: true` scales the sheet to one page wide and as many pages tall as it takes.
+
+A worksheet that never calls this carries **no print setup at all**, so a reader applies its own defaults rather than this writer's opinion. Calls merge, so two calls naming different keys both take effect. Print setup is per worksheet, which is where OOXML puts it.
+
+`titles: n` repeats the top `n` rows at the top of every printed page — the paper counterpart of `freeze`, which keeps them in view on screen. `0` clears it, as it does for a freeze. This one is written as a `_xlnm.Print_Titles` defined name in `xl/workbook.xml` rather than in the sheet part, and it is scoped to this worksheet alone, so each sheet of a workbook repeats its own rows.
+
 ### `sheet.place(id, { row, col, width, height })`
 
 One floating picture anchored to the top-left of a 1-based cell, drawn at `width` × `height` CSS pixels at 96 dpi.
@@ -173,7 +181,7 @@ There is nothing to configure. Each of these is a property of the writer rather
 
 - **Text is always interned** into the shared string table.
 - **Style tables are always interned.**
-- **Dates are the 1900 system**, converted in UTC. A reader's timezone is never consulted, and the phantom 1900-02-29 is accounted for, so a date before March 1900 lands on the day it names.
+- **Dates are the 1900 system**, converted in UTC. A reader's timezone never enters the conversion. This writer counts Excel's phantom 1900-02-29, so a date before March 1900 lands on the day it names in Excel. ECMA-376 defines the 1900 system with that fictitious day. LibreOffice Calc omits it and shows those dates one day early. No single serial satisfies both readers, so this writer follows the specification. A date from 1900-03-01 on reads the same in both, which covers every date a report is likely to hold.
 - **A date with no format of its own** gets the short-date built-in, so it reads back as a day rather than as the number underneath it.
 - **Media deduplicates by bytes.**
 - **Every element is written in the Open XML SDK's child order.**

package/lib/index.d.ts

@@ -75,6 +75,22 @@ export interface Placement {
   height: number;
 }
 
+/** How a worksheet prints. Every key is optional. */
+export interface PrintSetup {
+  /** All four page margins, in points. Defaults to the reader's own. */
+  margin?: number;
+  /** A paper size OOXML names. There is no arbitrary width and height. */
+  size?: "letter" | "tabloid" | "legal" | "A3" | "A4" | "A5";
+  orientation?: "portrait" | "landscape";
+  /** Scale the sheet to one page wide, and as many pages tall as it takes. */
+  fit?: boolean;
+  /**
+   * Repeat the top `rows` rows at the top of every printed page. `0` clears,
+   * the way a `freeze` of `0` does. Scoped to this worksheet alone.
+   */
+  titles?: number;
+}
+
 export interface Sheet {
   /** This sheet's name. */
   readonly name: string;
@@ -90,6 +106,12 @@ export interface Sheet {
   merge(row: number, at: number, width: number): void;
   /** Freeze the top `count` rows. `0` clears. */
   freeze(count: number): void;
+  /**
+   * How this worksheet prints. A worksheet that never calls this carries no
+   * print setup at all, so a reader applies its own defaults. Calls merge, so
+   * two calls naming different keys both take effect.
+   */
+  print(setup: PrintSetup): void;
   /** Float a picture over the sheet, anchored to one cell. */
   place(id: number, at: Placement): void;
 }