@portone/docx-editor 0.3.0 → 0.5.0

package/dist/docx/formatting/context.js

@@ -1,14 +1,20 @@
 // src/docx/formatting/context.ts
 import {
-  EMPTY_NUMBERING
+  EMPTY_NUMBERING,
+  parseNumbering
 } from "../../numbering/parseNumbering.js";
 import { NO_COMPAT } from "../documentSettings.js";
 import { NO_THEME_FONTS } from "../theme.js";
-import { readDefaultParagraphFormat, readRunDefaults } from "./direct.js";
+import {
+  readDefaultParagraphFormat,
+  readRunDefaults,
+  readRunFormat
+} from "./direct.js";
 import {
   defaultParagraphStyleIdOf,
   defaultTableStyleIdOf,
   NO_STYLES,
+  numberingStyleLinks,
   readStyles
 } from "./styles.js";
 var NO_FORMATTING = {
@@ -21,12 +27,23 @@ var NO_FORMATTING = {
   themeFonts: NO_THEME_FONTS,
   compat: NO_COMPAT
 };
-function formattingContextOf(styles, numbering, themeFonts, compat = NO_COMPAT) {
+function numberingOptionsFor(styles, themeFonts) {
+  return {
+    links: numberingStyleLinks(styles),
+    readRun: (rPr) => readRunFormat(rPr, themeFonts)
+  };
+}
+function formattingContextOf(styles, numberingXml, themeFonts, compat = NO_COMPAT) {
+  const table = styles === null ? NO_STYLES : readStyles(styles, themeFonts);
+  const numbering = parseNumbering(
+    numberingXml,
+    numberingOptionsFor(table, themeFonts)
+  );
   if (styles === null) {
     return { ...NO_FORMATTING, numbering, themeFonts, compat };
   }
   return {
-    styles: readStyles(styles, themeFonts),
+    styles: table,
     defaultParagraphStyleId: defaultParagraphStyleIdOf(styles),
     defaultTableStyleId: defaultTableStyleIdOf(styles),
     paragraphDefaults: readDefaultParagraphFormat(styles),
@@ -38,5 +55,6 @@ function formattingContextOf(styles, numbering, themeFonts, compat = NO_COMPAT)
 }
 export {
   NO_FORMATTING,
-  formattingContextOf
+  formattingContextOf,
+  numberingOptionsFor
 };

package/dist/docx/formatting/resolve.d.ts

@@ -9,13 +9,12 @@ import { type ParagraphFormat, type RunFormat } from "../../model/format";
 import type { TabStop } from "../../model/tabStops";
 import type { TableStyleOverrideType } from "../tableFormatting";
 import type { FormattingContext } from "./context";
+import { type StyleFormat } from "./styles";
 /** Where a paragraph sits when it is inside a table cell. null for body text */
 export interface ParagraphPlacement {
+    /** What the table's `w:tblStyle` names. null for a table naming none, which wears the default one */
     tableStyleId: string | null;
-    /**
-     * The conditional formats the cell takes, lowest first. Not read yet: a table style
-     * contributes the values it lays down for the whole table alone
-     */
+    /** The parts of the table the cell belongs to, lowest first (`docx/tableFormatting/conditions`) */
     conditions: readonly TableStyleOverrideType[];
 }
 /**
@@ -38,6 +37,13 @@ export interface ResolvedParagraph {
     /** The stops `format.tabStops` holds, each with the layer that laid it down */
     tabStops: readonly LayeredTabStop[];
 }
+/**
+ * The table style an object wearing this one is dressed by.
+ *
+ * A table that points at no style, or at one that is not defined, falls back on the document's
+ * default table style, which is what OOXML applies to an object with no style of its own.
+ */
+export declare function tableStyleFor(styleId: string | null, context: FormattingContext): StyleFormat | undefined;
 export declare function resolveParagraph(pPr: string | null, context: FormattingContext, placement?: ParagraphPlacement | null): ResolvedParagraph;
 /** `format` on a run mark: paragraph.styleRun < character style < the run's own rPr */
 export declare function resolveRun(rPr: string | null, paragraph: ResolvedParagraph, context: FormattingContext): RunFormat | null;

package/dist/docx/formatting/resolve.js

@@ -2,6 +2,7 @@
 import {
   toParagraphFormat
 } from "../../model/format.js";
+import { listFor } from "../../numbering/listTemplate.js";
 import {
   levelIndentPt
 } from "../../numbering/parseNumbering.js";
@@ -14,9 +15,17 @@ import {
 function directLayer(pPr) {
   return pPr === null ? {} : readParagraphFormat(parsePropsXml(pPr)) ?? {};
 }
-function tableStyleOf(placement, context) {
-  const id = placement?.tableStyleId ?? null;
-  return id === null ? void 0 : context.styles.get(id);
+function tableStyleFor(styleId, context) {
+  const named = styleId === null ? void 0 : context.styles.get(styleId);
+  const fallback = context.defaultTableStyleId === null ? void 0 : context.styles.get(context.defaultTableStyleId);
+  return named ?? fallback;
+}
+function conditionsOf(style, placement) {
+  if (!style || !placement) return [];
+  return placement.conditions.flatMap((type) => {
+    const format = style.tableConditions[type];
+    return format ? [format] : [];
+  });
 }
 function numberingLevelOf(layers, context) {
   const ref = layers.reduce(
@@ -24,7 +33,7 @@ function numberingLevelOf(layers, context) {
     void 0
   );
   if (!ref) return void 0;
-  return context.numbering.lists.get(ref.numId)?.levels.get(ref.ilvl);
+  return listFor(context.numbering, ref.numId)?.levels.get(ref.ilvl);
 }
 function numberingLayer(level) {
   return level?.tabStops ? { tabStops: level.tabStops } : {};
@@ -66,16 +75,23 @@ function orNull(values) {
   return Object.keys(values).length === 0 ? null : values;
 }
 function resolveParagraph(pPr, context, placement = null) {
-  const tableStyle = tableStyleOf(placement, context);
+  const tableStyle = placement === null ? void 0 : tableStyleFor(placement.tableStyleId, context);
+  const conditions = conditionsOf(tableStyle, placement);
   const style = paragraphStyleFormat(
     pPr,
     context.styles,
     context.defaultParagraphStyleId
   );
   const direct = directLayer(pPr);
+  const table = [
+    { values: tableStyle?.paragraph ?? {}, stops: "style" },
+    ...conditions.map(
+      (condition) => ({ values: condition.paragraph, stops: "style" })
+    )
+  ];
   const explicit = [
     { values: context.paragraphDefaults, stops: "style" },
-    { values: tableStyle?.paragraph ?? {}, stops: "style" },
+    ...table,
     { values: style?.paragraph ?? {}, stops: "style" },
     { values: direct, stops: "direct" }
   ];
@@ -83,10 +99,11 @@ function resolveParagraph(pPr, context, placement = null) {
     explicit.map((layer) => layer.values),
     context
   );
+  const belowNumbering = 1 + table.length;
   const layers = [
-    ...explicit.slice(0, 2),
+    ...explicit.slice(0, belowNumbering),
     { values: numberingLayer(level), stops: "numbering" },
-    ...explicit.slice(2)
+    ...explicit.slice(belowNumbering)
   ];
   const values = layers.reduce(
     (base, layer) => layerValues(base, layer.values),
@@ -107,8 +124,10 @@ function resolveParagraph(pPr, context, placement = null) {
     ...displayDefaults
   } = context.runDefaults;
   const styleRun = {
-    ...displayDefaults,
-    ...tableStyle?.run,
+    ...conditions.reduce(
+      (run, condition) => ({ ...run, ...condition.run }),
+      { ...displayDefaults, ...tableStyle?.run }
+    ),
     ...style?.run
   };
   return {
@@ -136,5 +155,6 @@ function inheritedRunFormat(rPr, paragraph, context) {
 export {
   inheritedRunFormat,
   resolveParagraph,
-  resolveRun
+  resolveRun,
+  tableStyleFor
 };

package/dist/docx/formatting/styles.d.ts

@@ -1,9 +1,16 @@
 /** Reads and layers styles.xml values used by the display model. */
-import { type CellMargins, type InsideBorders, type ParagraphFormat, type RunFormat, type TableFormat } from "../../model/format";
+import { type BandSizes, type CellMargins, type InsideBorders, type ParagraphFormat, type RunFormat, type TableFormat, type TableStyleOverrideType } from "../../model/format";
+import type { NumberingStyleLinks } from "../../numbering/parseNumbering";
+import { type ConditionalTableFormat } from "../tableFormatting";
 import { type ThemeFonts } from "../theme";
 import { type ParagraphFormatLayer } from "./tabStops";
+/** The kind of object a style dresses (`w:style/@w:type`, ST_StyleType) */
+export type StyleType = "paragraph" | "character" | "table" | "numbering";
+/** What a table style dresses each part of a table with, by the part it covers */
+export type TableStyleConditionFormats = Readonly<Partial<Record<TableStyleOverrideType, ConditionalTableFormat>>>;
 /** The display values one style passes down to paragraphs, to text, and to tables */
 export interface StyleFormat {
+    type: StyleType;
     paragraph: ParagraphFormatLayer;
     run: RunFormat;
     table: TableFormat;
@@ -11,6 +18,14 @@ export interface StyleFormat {
     tableInside: InsideBorders;
     /** The cell margins the style laid down. A side it says nothing about is null */
     tableCellMargins: CellMargins;
+    /** How many rows and columns one band of this table style is made of */
+    tableBands: BandSizes;
+    /**
+     * The conditional formats it wrote (`w:tblStylePr`). Each part is layered down the `basedOn`
+     * chain on its own, so a style that redresses the header row alone leaves the parts the styles
+     * it is based on dressed standing.
+     */
+    tableConditions: TableStyleConditionFormats;
 }
 /** A table looked up by style name. The `basedOn` chain has already been layered into the values */
 export type StyleTable = ReadonlyMap<string, StyleFormat>;
@@ -19,10 +34,18 @@ export declare const NO_STYLES: StyleTable;
  * Reads the style chain from styles.xml into effective values for display.
  *
  * A style name is unique across all kinds (paragraph, character, table), so we take them in
- * without telling the kinds apart.
+ * without telling the kinds apart, and each one remembers the kind it is.
  * The names a paragraph points at are only ever paragraph styles, so the other kinds are never looked up.
  */
 export declare function readStyles(styles: Document, themeFonts?: ThemeFonts): StyleTable;
+/**
+ * The list each numbering style names.
+ *
+ * A numbering style carries its list in the `w:numPr` of its paragraph properties, and that is the
+ * only way a numbering definition deferring to a style (`w:numStyleLink`) finds the levels it
+ * draws. A style naming no list, or naming the empty list `w:numId` 0, links to nothing.
+ */
+export declare function numberingStyleLinks(styles: StyleTable): NumberingStyleLinks;
 /**
  * The default table style, which for most documents is where a plain table gets its cell margins
  * and its lines from

package/dist/docx/formatting/styles.js

@@ -1,5 +1,6 @@
 // src/docx/formatting/styles.ts
 import {
+  TABLE_STYLE_CONDITIONS,
   toParagraphFormat,
   toRunFormat,
   toTableFormat
@@ -9,11 +10,16 @@ import { ST_OnOff } from "../../ooxml/simpleTypes.js";
 import { childValue, isOn, wAttr } from "../../ooxml/units.js";
 import { childByLocalName, elementChildren } from "../../ooxml/xml.js";
 import {
+  layerBandSizes,
   layerCellMargins,
+  layerCellStyleFormat,
   layerInsideBorders,
+  NO_BAND_SIZES,
   NO_CELL_MARGINS,
   NO_INSIDE_BORDERS,
+  readBandSizes,
   readCellMarginsOf,
+  readCellStyleFormat,
   readInsideBorders,
   readTableFormat
 } from "../tableFormatting.js";
@@ -35,23 +41,51 @@ function styleChain(id, sources) {
   return chain;
 }
 var EMPTY_STYLE_FORMAT = {
+  type: "paragraph",
   paragraph: {},
   run: {},
   table: {},
   tableInside: NO_INSIDE_BORDERS,
-  tableCellMargins: NO_CELL_MARGINS
+  tableCellMargins: NO_CELL_MARGINS,
+  tableBands: NO_BAND_SIZES,
+  tableConditions: {}
 };
+function conditionOf(el) {
+  const type = wAttr(el, "type");
+  return TABLE_STYLE_CONDITIONS.find((known) => known === type) ?? null;
+}
+function readConditionalFormat(el, themeFonts) {
+  const tblPr = childByLocalName(el, "tblPr");
+  return {
+    paragraph: readParagraphFormat(childByLocalName(el, "pPr")) ?? {},
+    run: readRunFormat(childByLocalName(el, "rPr"), themeFonts) ?? {},
+    table: readTableFormat(tblPr) ?? {},
+    cell: readCellStyleFormat(childByLocalName(el, "tcPr"), tblPr)
+  };
+}
+function readConditions(source, themeFonts) {
+  const conditions = {};
+  for (const el of source.tblStylePr) {
+    const type = conditionOf(el);
+    if (type !== null) conditions[type] = readConditionalFormat(el, themeFonts);
+  }
+  return conditions;
+}
 function readStyleFormat(source, themeFonts) {
   return {
+    type: source.type,
     paragraph: readParagraphFormat(source.pPr) ?? {},
     run: readRunFormat(source.rPr, themeFonts) ?? {},
     table: readTableFormat(source.tblPr) ?? {},
     tableInside: readInsideBorders(source.tblPr),
-    tableCellMargins: readCellMarginsOf(source.tblPr, "tblCellMar")
+    tableCellMargins: readCellMarginsOf(source.tblPr, "tblCellMar"),
+    tableBands: readBandSizes(source.tblPr),
+    tableConditions: readConditions(source, themeFonts)
   };
 }
 function layerStyleFormat(base, over) {
   return {
+    type: over.type,
     paragraph: layerParagraphValues(base.paragraph, over.paragraph),
     run: { ...base.run, ...over.run },
     table: { ...base.table, ...over.table },
@@ -59,12 +93,45 @@ function layerStyleFormat(base, over) {
     tableCellMargins: layerCellMargins(
       base.tableCellMargins,
       over.tableCellMargins
+    ),
+    tableBands: layerBandSizes(base.tableBands, over.tableBands),
+    tableConditions: layerConditions(
+      base.tableConditions,
+      over.tableConditions
     )
   };
 }
+function layerConditionalFormat(base, over) {
+  return {
+    paragraph: layerParagraphValues(base.paragraph, over.paragraph),
+    run: { ...base.run, ...over.run },
+    table: { ...base.table, ...over.table },
+    cell: layerCellStyleFormat(base.cell, over.cell)
+  };
+}
+function layerConditions(base, over) {
+  const conditions = {};
+  for (const type of TABLE_STYLE_CONDITIONS) {
+    const under = base[type];
+    const above = over[type];
+    const format = under && above ? layerConditionalFormat(under, above) : above ?? under;
+    if (format) conditions[type] = format;
+  }
+  return conditions;
+}
 function foldChain(chain, themeFonts) {
   return chain.map((source) => readStyleFormat(source, themeFonts)).reduce(layerStyleFormat, EMPTY_STYLE_FORMAT);
 }
+var STYLE_TYPES = [
+  "paragraph",
+  "character",
+  "table",
+  "numbering"
+];
+function styleTypeOf(el) {
+  const type = wAttr(el, "type");
+  return STYLE_TYPES.find((known) => known === type) ?? "paragraph";
+}
 function readStyles(styles, themeFonts = NO_THEME_FONTS) {
   const sources = /* @__PURE__ */ new Map();
   for (const el of elementChildren(styles.documentElement)) {
@@ -72,10 +139,14 @@ function readStyles(styles, themeFonts = NO_THEME_FONTS) {
     const id = wAttr(el, "styleId");
     if (id === null || id.length === 0) continue;
     sources.set(id, {
+      type: styleTypeOf(el),
       basedOn: childValue(el, "basedOn"),
       pPr: childByLocalName(el, "pPr"),
       rPr: childByLocalName(el, "rPr"),
-      tblPr: childByLocalName(el, "tblPr")
+      tblPr: childByLocalName(el, "tblPr"),
+      tblStylePr: elementChildren(el).filter(
+        (child) => child.localName === "tblStylePr"
+      )
     });
   }
   const table = /* @__PURE__ */ new Map();
@@ -84,6 +155,15 @@ function readStyles(styles, themeFonts = NO_THEME_FONTS) {
   }
   return table;
 }
+function numberingStyleLinks(styles) {
+  const links = /* @__PURE__ */ new Map();
+  for (const [id, format] of styles) {
+    if (format.type !== "numbering") continue;
+    const numId = format.paragraph.numbering?.numId;
+    if (numId !== void 0) links.set(id, numId);
+  }
+  return links;
+}
 function isDefaultStyle(el) {
   return ST_OnOff.parse(wAttr(el, "default")) === true;
 }
@@ -158,6 +238,7 @@ export {
   layerParagraphFormat,
   layerRunFormat,
   layerTableFormat,
+  numberingStyleLinks,
   paragraphStyleFormat,
   readParagraphStyles,
   readStyles,

package/dist/docx/headersFooters.d.ts

@@ -1,17 +1,25 @@
-/** Reads the first section's header and footer stories for the page preview. */
-import type { ParagraphAlign } from "../model/format";
-export type HeaderFooterVariant = "default" | "first" | "even";
-export type PageField = "PAGE" | "NUMPAGES";
-export type HeaderFooterSegment = {
-    kind: "text";
-    value: string;
-} | {
-    kind: "field";
-    field: PageField;
-};
-/** A display-only projection. The original part remains untouched in the package. */
+/**
+ * The header and footer stories of a document: where each one is written, which section shows it,
+ * what it reads as on a given page, and where an edited one goes back out.
+ *
+ * A header part is a story of the same schema as the body (`./story`): its blocks are read by the
+ * same readers and sliced verbatim by the same scanner, so an edit to one rides a transaction and
+ * the part it stands in goes back out as the bytes it arrived as until somebody changes it. What
+ * the page preview draws is a projection of that story rather than a reading of its own.
+ *
+ * Which story a section shows is the section's question (`./sections`): every section names its own
+ * variants, so the second section of a document draws its own header and not the first section's.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import { type ParagraphAlign } from "../model/format";
+import { type StoryKey } from "../schema/stories";
+import type { PartPlanner } from "./partPlan";
+import { type DocumentSection } from "./sections";
+import { type ImportedStory, type StoryDeps } from "./story";
+/** One story a section may show, as the document currently says it */
 export interface HeaderFooterContent {
-    segments: readonly HeaderFooterSegment[];
+    story: PMNode;
+    /** What the first paragraph of the story is aligned to, which is what the preview is drawn with */
     align: ParagraphAlign | null;
 }
 export interface HeaderFooterVariants {
@@ -26,11 +34,72 @@ export interface HeadersFooters {
     evenAndOdd: boolean;
     pageNumberStart: number;
 }
-export declare const NO_HEADERS_FOOTERS: HeadersFooters;
-/** Reads the first section's display stories and section-level selection switches. */
-export declare function readHeadersFooters(parts: Map<string, Uint8Array>, mainPartPath: string, body: Element): HeadersFooters;
+/**
+ * What picking one section's stories takes beyond the section itself.
+ *
+ * A section names a relationship, a relationship names a part, and a part is where a story stands,
+ * so the two ends are joined once when the document is opened. `w:evenAndOddHeaders` is a
+ * document-wide setting rather than a section's own (§17.15.1.29), so it rides along here.
+ */
+export interface HeaderFooterStories {
+    /**
+     * The story each header or footer relationship of the main part names. The key says which of the
+     * two kinds it is, so a `w:headerReference` naming a footer relationship names no story.
+     */
+    readonly keyByRelId: ReadonlyMap<string, StoryKey>;
+    readonly evenAndOdd: boolean;
+}
+/**
+ * Every header and footer part a section of the document names, read as a story apiece, and the
+ * relationship each one answers to.
+ *
+ * A part is read once however many relationships point at it, and a part whose root is not the
+ * element its relationship promises is passed over: the reference names nothing this can draw, and
+ * the bytes stay where they are. A part no section names is not read at all, so an orphan a
+ * producer left behind - which may hold anything, a document this one never draws included - is
+ * neither a story of this document nor a reason to refuse the file, and its bytes go back out as
+ * they came.
+ */
+export declare function readHeaderFooterStories(parts: Map<string, Uint8Array>, mainPartPath: string, referenced: ReadonlySet<string>, depsFor: (partPath: string) => StoryDeps): {
+    stories: readonly ImportedStory[];
+    refs: HeaderFooterStories;
+};
+/**
+ * The stories this section shows and the switches that pick between them.
+ *
+ * `storyOf` answers with what the document currently says rather than what the package arrived
+ * holding, so a header the editor rewrote is the one the preview draws.
+ */
+export declare function variantsFor(section: DocumentSection, refs: HeaderFooterStories, storyOf: (key: StoryKey) => PMNode | null): HeadersFooters;
+/**
+ * The number this visual page shows, counted from the start its section declares.
+ *
+ * `page` is the page's place in the whole document: the count is not restarted at a section
+ * boundary, which is what the editor's documented page numbering says.
+ */
 export declare function displayPageNumber(headersFooters: HeadersFooters, page: number): number;
-/** Resolves the section variant and evaluates PAGE and NUMPAGES for one visual page. */
-export declare function headerFooterText(variants: HeaderFooterVariants, headersFooters: HeadersFooters, page: number, totalPages: number): string | null;
-/** Resolves the direct alignment of the first paragraph in the selected story. */
-export declare function headerFooterAlign(variants: HeaderFooterVariants, headersFooters: HeadersFooters, page: number): ParagraphAlign | null;
+/**
+ * The story this page of a section shows, and null where the section declares none for it.
+ *
+ * `pageInSection` is the page's place within its own section rather than in the document:
+ * `w:titlePg` selects the `first` story for the first page of every section it is written in
+ * (§17.10.1), and the odd or even story follows the number that page would carry counting from
+ * the section's own start (§17.10.6), so a second section opening halfway down a document draws
+ * its own first page as a first page.
+ */
+export declare function headerFooterOn(variants: HeaderFooterVariants, headersFooters: HeadersFooters, pageInSection: number): HeaderFooterContent | null;
+/**
+ * What the story reads as on one visual page: its paragraphs joined by newlines, with `PAGE` and
+ * `NUMPAGES` replaced by the numbers this page actually carries.
+ *
+ * `page` is the number the page shows rather than its place on the sheet, since that is what a
+ * `PAGE` field prints (§17.16.5.45).
+ */
+export declare function headerFooterText(story: PMNode, page: number, totalPages: number): string;
+/**
+ * Writes back the header and footer parts an edit changed, and no others.
+ *
+ * A story nobody touched is not written at all, so a document opened and exported hands every
+ * header part back as the bytes it arrived as, and editing one header leaves the rest untouched.
+ */
+export declare const headerFooterPlanner: PartPlanner;