@portone/docx-editor 0.2.1 → 0.4.0

package/dist/docx/session.d.ts

@@ -9,9 +9,9 @@
  */
 import type { Node as PMNode } from "prosemirror-model";
 import type { DocumentDefaults } from "../model/format";
-import { type Numbering } from "../numbering/parseNumbering";
+import { type Numbering, type NumberingOptions } from "../numbering/parseNumbering";
 import type { ImportedComments } from "./comments";
-import type { ParagraphFormatLayer, ParagraphStyleOption, StyleTable } from "./formatting";
+import { type FormattingContext, type ParagraphStyleOption } from "./formatting";
 import type { HeadersFooters } from "./headersFooters";
 import type { PageGeometry } from "./pageGeometry";
 export interface ImportedBlock {
@@ -28,9 +28,23 @@ export interface ImportedBlock {
 export interface DocxSession {
     readonly kind: "docxSession";
 }
+/** What names one open document, which a block key is written against */
+export interface SessionIdentity {
+    readonly sessionId: string;
+}
+/**
+ * A name for one open document.
+ *
+ * Opening the same bytes twice opens two documents, so this is drawn fresh each time rather than
+ * worked out from what was opened. It carries no `:`, which is what lets a block key be read back
+ * however many colons the story it names holds.
+ */
+export declare function newSessionId(): string;
 /** What the package's own layers read the open document off */
-export declare class SessionStore implements DocxSession {
+export declare class SessionStore implements DocxSession, SessionIdentity {
     readonly kind = "docxSession";
+    /** Which open document this is. Every block key of it names it, so a block of another document is not taken for one of this one */
+    readonly sessionId: string;
     readonly parts: Map<string, Uint8Array>;
     readonly mainPartPath: string;
     readonly documentPrefix: string;
@@ -41,19 +55,12 @@ export declare class SessionStore implements DocxSession {
     readonly defaults: DocumentDefaults;
     /** The effective automatic tab interval read from settings.xml. Used for display only. */
     readonly defaultTabStopPt: number;
-    /** The paragraph properties at the base of the OOXML formatting hierarchy. */
-    readonly paragraphDefaults: ParagraphFormatLayer;
     /** The paper this document is written on, read from the first section. Used for display only: the `w:sectPr` itself goes back out in the preserved tail */
     readonly geometry: PageGeometry;
-    /** The style chain from styles.xml. Used only to fold the style a paragraph points at into its displayed values */
-    readonly styles: StyleTable;
+    /** Everything the display values of a paragraph or a run are resolved against: the style chain, the defaults, the list definitions */
+    readonly formatting: FormattingContext;
     /** The paragraph styles this document defines, in the order styles.xml lists them. What the style picker offers */
     readonly paragraphStyles: ParagraphStyleOption[];
-    /**
-     * The paragraph style every paragraph with no `w:pStyle` of its own wears (`w:default="1"`,
-     * usually Normal). null when the document marks none
-     */
-    readonly defaultParagraphStyleId: string | null;
     /** The raw text of numbering.xml. Kept around so list numbers can be drawn on screen. null if there is none */
     readonly numberingXml: string | null;
     /** Where numbering.xml sits inside the zip. When a new list is exported it is rewritten at that spot. null if there is none */
@@ -76,6 +83,27 @@ export declare function sessionOf(session: DocxSession): SessionStore;
 /** Where the body part sits inside the package, which is the one part an export rewrites */
 export declare function documentPartPath(session: DocxSession): string;
 /** The list definitions the document carries, which is what a paragraph's numbering points into */
-export declare function documentNumbering(session: DocxSession): Numbering;
-/** Finds which original block a node came from. undefined for a node newly created during editing */
+export declare function documentNumbering(session: DocxSession, options?: NumberingOptions): Numbering;
+/** The story a block key names when the block stood in the main document body */
+export declare const BODY_STORY_KEY = "body";
+/** A block key read back: which open document the block came from, which story of it, and where in that story */
+export interface BlockKey {
+    sessionId: string;
+    storyKey: string;
+    index: number;
+}
+/** Where a block stands, as the one string a node carries on its `srcId` */
+export declare function blockKey(session: SessionIdentity, storyKey: string, index: number): string;
+/**
+ * The three parts of a block key, or null for a string that is not one.
+ *
+ * A story key holds colons of its own (`comment:4`), so the key is read from both ends rather
+ * than split: the first segment is the document, the last is the place in the story, and
+ * everything between them is the story itself.
+ */
+export declare function splitBlockKey(key: string): BlockKey | null;
+/**
+ * Finds which original block a node came from. undefined for a node newly created during editing,
+ * and for one that came in from another document, whose original is in that file and not this one.
+ */
 export declare function originalBlock(node: PMNode, session: SessionStore): ImportedBlock | undefined;

package/dist/docx/session.js

@@ -1,7 +1,19 @@
 // src/docx/session.ts
-import { parseNumbering } from "../numbering/parseNumbering.js";
+import {
+  parseNumbering
+} from "../numbering/parseNumbering.js";
+import {
+  numberingOptionsFor
+} from "./formatting.js";
+var sessionsOpened = 0;
+function newSessionId() {
+  sessionsOpened += 1;
+  return `d${sessionsOpened}-${Math.random().toString(36).slice(2, 10)}`;
+}
 var SessionStore = class {
   kind = "docxSession";
+  /** Which open document this is. Every block key of it names it, so a block of another document is not taken for one of this one */
+  sessionId;
   parts;
   mainPartPath;
   documentPrefix;
@@ -12,19 +24,12 @@ var SessionStore = class {
   defaults;
   /** The effective automatic tab interval read from settings.xml. Used for display only. */
   defaultTabStopPt;
-  /** The paragraph properties at the base of the OOXML formatting hierarchy. */
-  paragraphDefaults;
   /** The paper this document is written on, read from the first section. Used for display only: the `w:sectPr` itself goes back out in the preserved tail */
   geometry;
-  /** The style chain from styles.xml. Used only to fold the style a paragraph points at into its displayed values */
-  styles;
+  /** Everything the display values of a paragraph or a run are resolved against: the style chain, the defaults, the list definitions */
+  formatting;
   /** The paragraph styles this document defines, in the order styles.xml lists them. What the style picker offers */
   paragraphStyles;
-  /**
-   * The paragraph style every paragraph with no `w:pStyle` of its own wears (`w:default="1"`,
-   * usually Normal). null when the document marks none
-   */
-  defaultParagraphStyleId;
   /** The raw text of numbering.xml. Kept around so list numbers can be drawn on screen. null if there is none */
   numberingXml;
   /** Where numbering.xml sits inside the zip. When a new list is exported it is rewritten at that spot. null if there is none */
@@ -36,6 +41,7 @@ var SessionStore = class {
   /** First-section header and footer stories projected for the page preview. */
   headersFooters;
   constructor(opened) {
+    this.sessionId = opened.sessionId;
     this.parts = opened.parts;
     this.mainPartPath = opened.mainPartPath;
     this.documentPrefix = opened.documentPrefix;
@@ -44,11 +50,9 @@ var SessionStore = class {
     this.blocks = opened.blocks;
     this.defaults = opened.defaults;
     this.defaultTabStopPt = opened.defaultTabStopPt;
-    this.paragraphDefaults = opened.paragraphDefaults;
     this.geometry = opened.geometry;
-    this.styles = opened.styles;
+    this.formatting = opened.formatting;
     this.paragraphStyles = opened.paragraphStyles;
-    this.defaultParagraphStyleId = opened.defaultParagraphStyleId;
     this.numberingXml = opened.numberingXml;
     this.numberingPartPath = opened.numberingPartPath;
     this.comments = opened.comments;
@@ -63,17 +67,49 @@ function sessionOf(session) {
 function documentPartPath(session) {
   return sessionOf(session).mainPartPath;
 }
-function documentNumbering(session) {
-  return parseNumbering(sessionOf(session).numberingXml);
+function documentNumbering(session, options) {
+  const store = sessionOf(session);
+  return parseNumbering(store.numberingXml, {
+    ...numberingOptionsFor(
+      store.formatting.styles,
+      store.formatting.themeFonts
+    ),
+    ...options
+  });
+}
+var BODY_STORY_KEY = "body";
+function blockKey(session, storyKey, index) {
+  return `${session.sessionId}:${storyKey}:${index}`;
+}
+function splitBlockKey(key) {
+  const first = key.indexOf(":");
+  const last = key.lastIndexOf(":");
+  if (first < 1 || last <= first + 1) return null;
+  const indexText = key.slice(last + 1);
+  if (!/^\d+$/.test(indexText)) return null;
+  const index = Number(indexText);
+  if (!Number.isSafeInteger(index)) return null;
+  return {
+    sessionId: key.slice(0, first),
+    storyKey: key.slice(first + 1, last),
+    index
+  };
 }
 function originalBlock(node, session) {
   const srcId = node.attrs.srcId;
-  return typeof srcId === "number" ? session.blocks[srcId] : void 0;
+  if (typeof srcId !== "string") return void 0;
+  const key = splitBlockKey(srcId);
+  if (key === null || key.sessionId !== session.sessionId) return void 0;
+  return key.storyKey === BODY_STORY_KEY ? session.blocks[key.index] : void 0;
 }
 export {
+  BODY_STORY_KEY,
   SessionStore,
+  blockKey,
   documentNumbering,
   documentPartPath,
+  newSessionId,
   originalBlock,
-  sessionOf
+  sessionOf,
+  splitBlockKey
 };

package/dist/docx/tableFormatting/conditions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which parts of a table one cell belongs to, and what its table style dresses those parts with.
+ *
+ * A table style says one thing for the header row, another for the first column, another for the
+ * banded rows (`w:tblStylePr`), and `w:tblLook` says which of those a table takes at all. Every
+ * caller that asks what a cell falls back on - the import, a table created fresh, the lines derived
+ * again after the grid moved, and a cell formatting edit - asks here, so a cell is dressed the same
+ * whichever of them asked.
+ *
+ * A conditional format writes the lines of the part it dresses rather than of every cell in it:
+ * its four sides are drawn where a cell lies on the edge of that part and its inside lines between
+ * the cells within it, which is the same rule the table's own lines are drawn by.
+ */
+import type { BandSizes, CellMargins, InsideBorders, TableFormat, TableStyleConditions, TableStyleOverrideType } from "../../model/format";
+import { type CellDefaults, type GridRect, type GridSize } from "./reading";
+/** Which parts of its table style a table takes (`w:tblLook`, §17.4.55) */
+export interface TableLook {
+    firstRow: boolean;
+    lastRow: boolean;
+    firstColumn: boolean;
+    lastColumn: boolean;
+    noHBand: boolean;
+    noVBand: boolean;
+}
+/**
+ * What a table writing no `w:tblLook` at all takes: the banded rows and columns, and neither the
+ * header row, the last row, nor the edge columns (§17.4.55). Switching the banding off is
+ * something a table has to say, which is why both band settings are worded as `no`.
+ */
+export declare const NO_LOOK: TableLook;
+/**
+ * Which parts of its table style this table takes.
+ *
+ * The six attributes are what a document writes today; where one of them is missing the legacy
+ * bitmask answers for it, so a document written either way reads the same.
+ */
+export declare function readTableLook(tblPr: Element | null): TableLook;
+/** One conditional format a cell takes, and the part of the grid it dresses */
+export interface CellCondition {
+    type: TableStyleOverrideType;
+    /** Its four lines are drawn on the edge of this block, and its inside lines within it */
+    region: GridRect;
+}
+/** Where a cell sits, and which parts of the table it therefore belongs to */
+export interface CellPlacement {
+    rect: GridRect;
+    grid: GridSize;
+    /** Lowest first, in the order §17.7.6 lays them over one another */
+    conditions: readonly CellCondition[];
+}
+/**
+ * The parts of the table this cell belongs to, lowest first.
+ *
+ * A cell sits in a row band by the row it starts in and in a column band by the column it starts
+ * in, and it is a corner only where the table takes both the row and the column that meet there.
+ */
+export declare function cellPlacement(rect: GridRect, grid: GridSize, look: TableLook, bands: BandSizes): CellPlacement;
+/** What a table lays down for its cells to draw. What its style laid down is not in the `tblPr`, so it comes along separately */
+export interface TableCellSources {
+    outer: TableFormat | null;
+    inside: InsideBorders;
+    margins: CellMargins;
+    /** The parts of its style the table takes */
+    look: TableLook;
+    bands: BandSizes;
+    /** What the style dresses each of those parts with */
+    conditions: TableStyleConditions;
+    /** The style the paragraphs inside the cells resolve against. null for a table wearing none */
+    styleId: string | null;
+}
+export declare const NO_CELL_SOURCES: TableCellSources;
+/**
+ * What the cell covering this block of the grid falls back on: the table's own lines and margins,
+ * with every conditional format its style dresses a part it belongs to with laid over them.
+ */
+export declare function cellDefaultsFor(rect: GridRect, grid: GridSize, sources: TableCellSources): CellDefaults;

package/dist/docx/tableFormatting/conditions.js

@@ -0,0 +1,196 @@
+// src/docx/tableFormatting/conditions.ts
+import { ST_OnOff } from "../../ooxml/simpleTypes.js";
+import { borderLineOfCss, wAttr } from "../../ooxml/units.js";
+import { childByLocalName } from "../../ooxml/xml.js";
+import {
+  layerCellMargins,
+  NO_BAND_SIZES,
+  NO_CELL_MARGINS,
+  NO_INSIDE_BORDERS,
+  NO_TABLE_STYLE_CONDITIONS
+} from "./reading.js";
+var NO_LOOK = {
+  firstRow: false,
+  lastRow: false,
+  firstColumn: false,
+  lastColumn: false,
+  noHBand: false,
+  noVBand: false
+};
+var LEGACY_LOOK_BITS = {
+  firstRow: 32,
+  lastRow: 64,
+  firstColumn: 128,
+  lastColumn: 256,
+  noHBand: 512,
+  noVBand: 1024
+};
+var SHORT_HEX = /^[0-9a-fA-F]{4}$/;
+function legacyLook(value) {
+  const bits = value !== null && SHORT_HEX.test(value) ? Number.parseInt(value, 16) : 0;
+  return {
+    firstRow: (bits & LEGACY_LOOK_BITS.firstRow) !== 0,
+    lastRow: (bits & LEGACY_LOOK_BITS.lastRow) !== 0,
+    firstColumn: (bits & LEGACY_LOOK_BITS.firstColumn) !== 0,
+    lastColumn: (bits & LEGACY_LOOK_BITS.lastColumn) !== 0,
+    noHBand: (bits & LEGACY_LOOK_BITS.noHBand) !== 0,
+    noVBand: (bits & LEGACY_LOOK_BITS.noVBand) !== 0
+  };
+}
+function readTableLook(tblPr) {
+  const el = tblPr ? childByLocalName(tblPr, "tblLook") : null;
+  if (!el) return NO_LOOK;
+  const legacy = legacyLook(wAttr(el, "val"));
+  const written = (name) => ST_OnOff.parse(wAttr(el, name)) ?? legacy[name];
+  return {
+    firstRow: written("firstRow"),
+    lastRow: written("lastRow"),
+    firstColumn: written("firstColumn"),
+    lastColumn: written("lastColumn"),
+    noHBand: written("noHBand"),
+    noVBand: written("noVBand")
+  };
+}
+function bandWidth(size) {
+  return size ?? 1;
+}
+function bandedRows(grid, look) {
+  return [look.firstRow ? 1 : 0, look.lastRow ? grid.rows - 1 : grid.rows];
+}
+function bandedColumns(grid, look) {
+  return [
+    look.firstColumn ? 1 : 0,
+    look.lastColumn ? grid.cols - 1 : grid.cols
+  ];
+}
+function bandAt(at, [from, to], size) {
+  if (at < from || at >= to) return null;
+  const index = Math.floor((at - from) / size);
+  return {
+    first: index % 2 === 0,
+    start: from + index * size,
+    end: Math.min(from + (index + 1) * size, to)
+  };
+}
+function rowsOf(grid, top, bottom) {
+  return { top, bottom, left: 0, right: grid.cols };
+}
+function columnsOf(grid, left, right) {
+  return { top: 0, bottom: grid.rows, left, right };
+}
+function cellPlacement(rect, grid, look, bands) {
+  const found = [];
+  const add = (type, region) => {
+    found.push({ type, region });
+  };
+  add("wholeTable", rowsOf(grid, 0, grid.rows));
+  const column = look.noVBand ? null : bandAt(rect.left, bandedColumns(grid, look), bandWidth(bands.col));
+  if (column) {
+    add(
+      column.first ? "band1Vert" : "band2Vert",
+      columnsOf(grid, column.start, column.end)
+    );
+  }
+  const row = look.noHBand ? null : bandAt(rect.top, bandedRows(grid, look), bandWidth(bands.row));
+  if (row) {
+    add(
+      row.first ? "band1Horz" : "band2Horz",
+      rowsOf(grid, row.start, row.end)
+    );
+  }
+  const firstRow = look.firstRow && rect.top === 0;
+  const lastRow = look.lastRow && rect.bottom === grid.rows && grid.rows > 1;
+  const firstCol = look.firstColumn && rect.left === 0;
+  const lastCol = look.lastColumn && rect.right === grid.cols && grid.cols > 1;
+  if (firstRow) add("firstRow", rowsOf(grid, 0, 1));
+  if (lastRow) add("lastRow", rowsOf(grid, grid.rows - 1, grid.rows));
+  if (firstCol) add("firstCol", columnsOf(grid, 0, 1));
+  if (lastCol) add("lastCol", columnsOf(grid, grid.cols - 1, grid.cols));
+  const corner = (type, top, left) => {
+    add(type, { top, bottom: top + 1, left, right: left + 1 });
+  };
+  if (firstRow && firstCol) corner("nwCell", 0, 0);
+  if (firstRow && lastCol) corner("neCell", 0, grid.cols - 1);
+  if (lastRow && firstCol) corner("swCell", grid.rows - 1, 0);
+  if (lastRow && lastCol) corner("seCell", grid.rows - 1, grid.cols - 1);
+  return { rect, grid, conditions: found };
+}
+var NO_CELL_SOURCES = {
+  outer: null,
+  inside: NO_INSIDE_BORDERS,
+  margins: NO_CELL_MARGINS,
+  look: NO_LOOK,
+  bands: NO_BAND_SIZES,
+  conditions: NO_TABLE_STYLE_CONDITIONS,
+  styleId: null
+};
+function edgesIn(rect, region) {
+  return {
+    top: rect.top === region.top,
+    bottom: rect.bottom === region.bottom,
+    left: rect.left === region.left,
+    right: rect.right === region.right
+  };
+}
+function tableBorderDefaults(edges, outer, inside) {
+  return {
+    top: borderLineOfCss(
+      edges.top ? outer?.borderTop ?? null : inside.horizontal
+    ),
+    bottom: borderLineOfCss(
+      edges.bottom ? outer?.borderBottom ?? null : inside.horizontal
+    ),
+    left: borderLineOfCss(
+      edges.left ? outer?.borderLeft ?? null : inside.vertical
+    ),
+    right: borderLineOfCss(
+      edges.right ? outer?.borderRight ?? null : inside.vertical
+    )
+  };
+}
+function conditionBorderDefaults(base, format, edges) {
+  const line = (onEdge, edge, within) => borderLineOfCss(onEdge ? edge : within);
+  return {
+    top: line(edges.top, format.borders.top, format.inside.horizontal) ?? base.top,
+    bottom: line(edges.bottom, format.borders.bottom, format.inside.horizontal) ?? base.bottom,
+    left: line(edges.left, format.borders.left, format.inside.vertical) ?? base.left,
+    right: line(edges.right, format.borders.right, format.inside.vertical) ?? base.right
+  };
+}
+function cellDefaultsFor(rect, grid, sources) {
+  const placement = cellPlacement(rect, grid, sources.look, sources.bands);
+  const whole = { top: 0, bottom: grid.rows, left: 0, right: grid.cols };
+  let borders = tableBorderDefaults(
+    edgesIn(rect, whole),
+    sources.outer,
+    sources.inside
+  );
+  let margins = sources.margins;
+  let background = null;
+  let verticalAlign = null;
+  for (const { type, region } of placement.conditions) {
+    const format = sources.conditions[type];
+    if (!format) continue;
+    borders = conditionBorderDefaults(borders, format, edgesIn(rect, region));
+    margins = layerCellMargins(margins, format.margins);
+    background = format.background ?? background;
+    verticalAlign = format.verticalAlign ?? verticalAlign;
+  }
+  return {
+    borders,
+    margins,
+    background,
+    verticalAlign,
+    placement: {
+      tableStyleId: sources.styleId,
+      conditions: placement.conditions.map((condition) => condition.type)
+    }
+  };
+}
+export {
+  NO_CELL_SOURCES,
+  NO_LOOK,
+  cellDefaultsFor,
+  cellPlacement,
+  readTableLook
+};

package/dist/docx/tableFormatting/editing.d.ts

@@ -3,8 +3,8 @@
  * only the child and attributes named by the edit are changed, and unsupported formatting stays
  * untouched.
  */
-import type { CellFormat, CellMargins, CellVerticalAlign, RowFormat } from "../../model/format";
-import { type CellBorderDefaults } from "./reading";
+import type { CellFormat, CellVerticalAlign, RowFormat } from "../../model/format";
+import { type CellDefaults } from "./reading";
 export interface CellProps {
     /** The whole `<w:tcPr>...</w:tcPr>` XML. null for a cell with no formatting */
     tcPr: string | null;
@@ -45,11 +45,15 @@ export type CellFormatEdit =
 /**
  * The cell formatting XML and display values after one piece of formatting is changed.
  *
+ * What the cell falls back on is what an edit measures against: switching a side off writes `none`
+ * over whatever line was being drawn there, and recoloring writes only where a line is drawn at
+ * all, so the defaults handed in have to be the ones the cell is actually drawn with.
+ *
  * null when there is nothing to do: a fragment whose shape could not be made out, a value that
  * cannot be written into the document, or a cell already in the state the job wants. In every one
  * of those cases the cell keeps its original XML.
  */
-export declare function editCellProps(tcPr: string | null, edit: CellFormatEdit, defaults?: CellBorderDefaults, margins?: CellMargins): CellProps | null;
+export declare function editCellProps(tcPr: string | null, edit: CellFormatEdit, defaults?: CellDefaults): CellProps | null;
 /**
  * Whether the cell's own formatting draws a line on any side.
  * A border color has nothing to act on when it does not, because the lines on screen are then the