@portone/docx-editor 0.3.0 → 0.5.0

package/dist/numbering/listRegistry.js

@@ -0,0 +1,112 @@
+// src/numbering/listRegistry.ts
+import { ST_SignedTwipsMeasure, ST_TwipsMeasure } from "../ooxml/simpleTypes.js";
+import { MAX_ILVL } from "./listTemplate.js";
+import {
+  LEVEL_ALIGNS,
+  LEVEL_SUFFIXES
+} from "./parseNumbering.js";
+import { isNumberFormat } from "./spellers.js";
+var NO_NEW_LISTS = /* @__PURE__ */ new Map();
+var NEW_LISTS_ATTR = "newLists";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toLevelIndent(value) {
+  if (!isRecord(value)) return null;
+  const { startTwips, endTwips, hangingTwips, firstLineTwips } = value;
+  const signed = (slot) => slot === null || typeof slot === "number" && ST_SignedTwipsMeasure.format(slot) !== null;
+  const unsigned = (slot) => slot === null || typeof slot === "number" && ST_TwipsMeasure.format(slot) !== null;
+  if (!signed(startTwips) || !signed(endTwips) || !unsigned(hangingTwips) || !unsigned(firstLineTwips))
+    return null;
+  return { startTwips, endTwips, hangingTwips, firstLineTwips };
+}
+function levelValue(ilvl, level) {
+  return {
+    ilvl,
+    format: level.format,
+    text: level.text,
+    start: level.start,
+    indent: level.indent,
+    restartAfterLevel: level.restartAfterLevel,
+    legal: level.legal,
+    suffix: level.suffix,
+    align: level.align
+  };
+}
+function toLevel(value) {
+  if (!isRecord(value)) return null;
+  const { ilvl, format, text, start } = value;
+  if (typeof ilvl !== "number" || !Number.isSafeInteger(ilvl) || ilvl < 0 || ilvl > MAX_ILVL)
+    return null;
+  if (typeof format !== "string" || !isNumberFormat(format)) return null;
+  if (typeof text !== "string") return null;
+  if (typeof start !== "number" || !Number.isSafeInteger(start)) return null;
+  const suffix = LEVEL_SUFFIXES.find((known) => known === value.suffix);
+  const align = LEVEL_ALIGNS.find((known) => known === value.align);
+  if (suffix === void 0 || align === void 0) return null;
+  const restartAfterLevel = value.restartAfterLevel;
+  if (restartAfterLevel !== null && (typeof restartAfterLevel !== "number" || !Number.isSafeInteger(restartAfterLevel) || restartAfterLevel < -1 || restartAfterLevel >= MAX_ILVL))
+    return null;
+  if (typeof value.legal !== "boolean") return null;
+  if (value.run !== void 0 && value.run !== null) return null;
+  if (value.tabStops !== void 0) return null;
+  const indent = toLevelIndent(value.indent);
+  if (value.indent !== null && indent === null) return null;
+  return {
+    ilvl,
+    level: {
+      format,
+      text,
+      start,
+      indent,
+      restartAfterLevel,
+      legal: value.legal,
+      suffix,
+      align,
+      run: null
+    }
+  };
+}
+function toList(value) {
+  if (!isRecord(value)) return null;
+  const { numId, levels } = value;
+  if (typeof numId !== "number" || !Number.isSafeInteger(numId) || numId <= 0)
+    return null;
+  if (!Array.isArray(levels)) return null;
+  const read = /* @__PURE__ */ new Map();
+  for (const entry of levels) {
+    const level = toLevel(entry);
+    if (level === null || read.has(level.ilvl)) return null;
+    read.set(level.ilvl, level.level);
+  }
+  return read.size === 0 ? null : { numId, list: { levels: read } };
+}
+function newListsValue(lists) {
+  if (lists.size === 0) return null;
+  return Array.from(lists).sort(([left], [right]) => left - right).map(([numId, list]) => ({
+    numId,
+    levels: Array.from(list.levels).sort(([left], [right]) => left - right).map(([ilvl, level]) => levelValue(ilvl, level))
+  }));
+}
+function newListsOf(value) {
+  if (!Array.isArray(value)) return NO_NEW_LISTS;
+  const lists = /* @__PURE__ */ new Map();
+  for (const entry of value) {
+    const read = toList(entry);
+    if (read === null || lists.has(read.numId)) return NO_NEW_LISTS;
+    lists.set(read.numId, read.list);
+  }
+  return lists;
+}
+function listsWorn(lists, worn) {
+  const dropped = [...lists.keys()].filter((numId) => !worn.has(numId));
+  if (dropped.length === 0) return lists;
+  return new Map([...lists].filter(([numId]) => worn.has(numId)));
+}
+export {
+  NEW_LISTS_ATTR,
+  NO_NEW_LISTS,
+  listsWorn,
+  newListsOf,
+  newListsValue
+};

package/dist/numbering/listTemplate.d.ts

@@ -1,29 +1,38 @@
 /**
- * The standard shape of a newly started list.
+ * A list started while editing: the definition it is started with, the number it takes, and the
+ * `<w:abstractNum>` that definition is written out as.
  *
- * The definition of a new list is not kept in the document model.
- * So its shape has to be derivable from the list number (numId) alone, and that rule
- * lives here. Even numbers are numbered lists, odd numbers are bullet lists.
- *
- * Drawing the markers on screen and writing the definitions into numbering.xml both look
- * at the same template.
+ * Nothing here reads anything into the number. The definition is a value the editor registers
+ * (`./listRegistry`), the same value the markers are drawn from and the one written into
+ * numbering.xml, so a list goes out as what it was started as.
  */
-import type { LevelIndent, Numbering, NumberingList } from "./parseNumbering";
+import type { LevelIndent, NewList, Numbering, NumberingList } from "./parseNumbering";
 export type ListKind = "numbered" | "bullet";
 /** A list has nine levels (the count OOXML defines) */
 export declare const LEVEL_COUNT = 9;
 export declare const MAX_ILVL: number;
 export declare function templateIndent(ilvl: number): LevelIndent;
-export declare function listKindOf(numId: number): ListKind;
+/** The definition a list of this kind is started with */
+export declare function templateList(kind: ListKind): NewList;
+/**
+ * The definition standing behind this number: the one the document wrote down, or the one a list
+ * started while editing was registered with. Undefined for a number nothing defines, which is a
+ * list neither drawn nor written.
+ */
+export declare function listFor(numbering: Numbering, numId: number): NumberingList | undefined;
+/** Reserves safe positive ids, using gaps if incrementing the highest id would lose precision. */
+export declare function numberingIdAllocator(ids: Iterable<number>): () => number;
 /**
- * The list definition for this number.
- * A number the document's numbering.xml does not know is read as the standard template
- * (which is the case for a list that was just started).
+ * A number for a new list, and the numbering that now defines it under that number.
+ *
+ * `used` names the numbers the document already spends, the ones no definition stands behind
+ * included: a number a paragraph already wears would otherwise join that paragraph to the new list.
  */
-export declare function listFor(numbering: Numbering, numId: number): NumberingList;
-/** The next number not yet in use. Picks the even or odd one matching the shape */
-export declare function nextNumId(used: Iterable<number>, kind: ListKind): number;
-/** Writes one template out as a `<w:abstractNum>` definition */
-export declare function abstractNumXml(abstractNumId: number, kind: ListKind): string;
+export declare function allocateList(numbering: Numbering, used: Iterable<number>, list: NewList): {
+    numId: number;
+    numbering: Numbering;
+};
+/** Writes one registered definition out as a `<w:abstractNum>` */
+export declare function abstractNumXml(abstractNumId: number, list: NewList): string;
 /** The `<w:num>` that ties a list number to a definition */
 export declare function numXml(numId: number, abstractNumId: number): string;

package/dist/numbering/listTemplate.js

@@ -29,7 +29,12 @@ function templateLevel(kind, ilvl) {
     format: numbered ? cycled(NUMBER_CYCLE, ilvl, "decimal") : "bullet",
     text: numbered ? `%${ilvl + 1}.` : cycled(BULLET_CYCLE, ilvl, "\u25CF"),
     start: 1,
-    indent: templateIndent(ilvl)
+    indent: templateIndent(ilvl),
+    restartAfterLevel: null,
+    legal: false,
+    suffix: "tab",
+    align: "left",
+    run: null
   };
 }
 function templateList(kind) {
@@ -39,19 +44,35 @@ function templateList(kind) {
   }
   return { levels };
 }
-var TEMPLATES = {
-  numbered: templateList("numbered"),
-  bullet: templateList("bullet")
-};
-function listKindOf(numId) {
-  return numId % 2 === 0 ? "numbered" : "bullet";
-}
 function listFor(numbering, numId) {
-  return numbering.lists.get(numId) ?? TEMPLATES[listKindOf(numId)];
+  return numbering.lists.get(numId) ?? numbering.added.get(numId);
 }
-function nextNumId(used, kind) {
-  const from = Math.max(0, ...used) + 1;
-  return listKindOf(from) === kind ? from : from + 1;
+function numberingIdAllocator(ids) {
+  const used = new Set(ids);
+  let highest = 0;
+  for (const id of used) if (id > highest) highest = id;
+  let next = Number.isSafeInteger(highest + 1) ? highest + 1 : 1;
+  return () => {
+    while (used.has(next)) next += 1;
+    const id = next;
+    used.add(id);
+    next = Number.isSafeInteger(id + 1) ? id + 1 : 1;
+    return id;
+  };
+}
+function allocateList(numbering, used, list) {
+  const numId = numberingIdAllocator([
+    ...numbering.lists.keys(),
+    ...numbering.added.keys(),
+    ...used
+  ])();
+  return {
+    numId,
+    numbering: {
+      ...numbering,
+      added: new Map([...numbering.added, [numId, list]])
+    }
+  };
 }
 function indXml(indent) {
   const slots = [
@@ -68,8 +89,33 @@ function indXml(indent) {
     [{ name: "ind", xml: elementXml(wName("ind"), attrs) }]
   );
 }
+function lvlRestartXml(restartAfterLevel) {
+  if (restartAfterLevel === null) return null;
+  return {
+    name: "lvlRestart",
+    xml: elementXml(wName("lvlRestart"), [
+      [wName("val"), `${restartAfterLevel + 1}`]
+    ])
+  };
+}
+function isLglXml(legal) {
+  return legal ? { name: "isLgl", xml: elementXml(wName("isLgl"), []) } : null;
+}
+function suffXml(suffix) {
+  if (suffix === "tab") return null;
+  return {
+    name: "suff",
+    xml: elementXml(wName("suff"), [[wName("val"), suffix]])
+  };
+}
 function levelXml(ilvl, level) {
   const ind = indXml(level.indent);
+  const optional = [
+    lvlRestartXml(level.restartAfterLevel),
+    isLglXml(level.legal),
+    suffXml(level.suffix),
+    ind === "" ? null : { name: "pPr", xml: ind }
+  ];
   return orderedElement(
     wName("lvl"),
     [[wName("ilvl"), `${ilvl}`]],
@@ -88,15 +134,14 @@ function levelXml(ilvl, level) {
       },
       {
         name: "lvlJc",
-        xml: elementXml(wName("lvlJc"), [[wName("val"), "left"]])
+        xml: elementXml(wName("lvlJc"), [[wName("val"), level.align]])
       },
-      ...ind === "" ? [] : [{ name: "pPr", xml: ind }]
+      ...optional.filter((child) => child !== null)
     ]
   );
 }
-function abstractNumXml(abstractNumId, kind) {
-  const levels = TEMPLATES[kind].levels;
-  const body = Array.from(levels.entries()).map(([ilvl, level]) => levelXml(ilvl, level)).join("");
+function abstractNumXml(abstractNumId, list) {
+  const body = Array.from(list.levels.entries()).map(([ilvl, level]) => levelXml(ilvl, level)).join("");
   return elementXml(
     wName("abstractNum"),
     [[wName("abstractNumId"), `${abstractNumId}`]],
@@ -114,9 +159,10 @@ export {
   LEVEL_COUNT,
   MAX_ILVL,
   abstractNumXml,
+  allocateList,
   listFor,
-  listKindOf,
-  nextNumId,
   numXml,
-  templateIndent
+  numberingIdAllocator,
+  templateIndent,
+  templateList
 };

package/dist/numbering/markers.d.ts

@@ -4,21 +4,30 @@
  * A pure computation that never touches the document model: the same paragraphs with the
  * same numbering definitions always yield the same numbers.
  */
-import type { NumberingRef } from "../model/format";
-import { type LevelIndentPt, type Numbering } from "./parseNumbering";
+import type { NumberingRef, RunFormat } from "../model/format";
+import { type LevelAlign, type LevelIndentPt, type LevelSuffix, type Numbering } from "./parseNumbering";
 /** The number to draw in front of one paragraph */
 export interface ListMarker {
+    /**
+     * The number as it is drawn, the space a level asking for one (`w:suff`) included: a separator
+     * made of a character belongs to the marker, while the tab every other level asks for is the
+     * width the number sits in rather than anything to draw
+     */
     text: string;
     /**
      * The indent defined by the level this paragraph belongs to. Used when the paragraph
      * records none of its own
      */
     indent: LevelIndentPt;
+    /** Whether the number sits in a width of its own, which is what a tab suffix asks for */
+    suffix: LevelSuffix;
+    align: LevelAlign;
+    /** The formatting the level puts on the number, which dresses the number and nothing else */
+    run: RunFormat | null;
 }
 /**
- * A slot is null for a paragraph that is not a list item, or whose level shape could not
- * be found.
- * A number the document does not know (a list started fresh while editing) is drawn with
- * the standard template's shape.
+ * A slot is null for a paragraph that is not a list item, or whose level shape could not be found.
+ * A number nothing defines - neither numbering.xml nor a list started while editing - draws no
+ * marker, which is what Word does with a `w:numId` no `w:num` answers.
  */
 export declare function computeMarkers(paragraphs: readonly (NumberingRef | null)[], numbering: Numbering): (ListMarker | null)[];

package/dist/numbering/markers.js

@@ -3,71 +3,31 @@ import { listFor } from "./listTemplate.js";
 import {
   levelIndentPt
 } from "./parseNumbering.js";
-var ROMAN = [
-  [1e3, "M"],
-  [900, "CM"],
-  [500, "D"],
-  [400, "CD"],
-  [100, "C"],
-  [90, "XC"],
-  [50, "L"],
-  [40, "XL"],
-  [10, "X"],
-  [9, "IX"],
-  [5, "V"],
-  [4, "IV"],
-  [1, "I"]
-];
-function toRoman(value) {
-  let rest = value;
-  let out = "";
-  for (const [amount, sign] of ROMAN) {
-    while (rest >= amount) {
-      out += sign;
-      rest -= amount;
-    }
-  }
-  return out;
-}
-function toLetters(value) {
-  const index = (value - 1) % 26;
-  const repeat = Math.floor((value - 1) / 26) + 1;
-  return String.fromCharCode(65 + index).repeat(repeat);
-}
+import { spellNumber } from "./spellers.js";
 var MAX_MARKER_CHARS = 64;
-var MAX_SPELLED_VALUE = {
-  decimal: Number.POSITIVE_INFINITY,
-  bullet: Number.POSITIVE_INFINITY,
-  lowerLetter: 26 * MAX_MARKER_CHARS,
-  upperLetter: 26 * MAX_MARKER_CHARS,
-  lowerRoman: 1e3 * MAX_MARKER_CHARS
-};
-function formatNumber(value, format) {
-  if (value < 1 || value > MAX_SPELLED_VALUE[format]) return `${value}`;
-  switch (format) {
-    case "lowerLetter":
-      return toLetters(value).toLowerCase();
-    case "upperLetter":
-      return toLetters(value);
-    case "lowerRoman":
-      return toRoman(value).toLowerCase();
-    default:
-      return `${value}`;
-  }
-}
-function fillLevels(text, list, counters) {
+function fillLevels(text, list, counters, legal) {
   return text.replaceAll(/%([1-9])/g, (_, digit) => {
     const ilvl = Number(digit) - 1;
     const level = list.levels.get(ilvl);
     if (!level) return "";
-    return formatNumber(counters.get(ilvl) ?? level.start, level.format);
+    const count = counters.get(ilvl) ?? level.start;
+    return spellNumber(
+      count,
+      legal ? "decimal" : level.format,
+      MAX_MARKER_CHARS
+    );
   });
 }
+function restartedBy(level, ilvl) {
+  return level?.restartAfterLevel ?? ilvl - 1;
+}
 function advance(counters, list, ilvl, start) {
   const current = counters.get(ilvl);
   counters.set(ilvl, current === void 0 ? start : current + 1);
   for (const deeper of [...counters.keys(), ...list.levels.keys()]) {
-    if (deeper > ilvl) counters.delete(deeper);
+    if (deeper > ilvl && restartedBy(list.levels.get(deeper), deeper) >= ilvl) {
+      counters.delete(deeper);
+    }
   }
 }
 var MARKER_SEGMENTER = new Intl.Segmenter();
@@ -87,17 +47,24 @@ function computeMarkers(paragraphs, numbering) {
   return paragraphs.map((ref) => {
     if (!ref) return null;
     const list = listFor(numbering, ref.numId);
-    const level = list.levels.get(ref.ilvl);
-    if (!level) return null;
+    const level = list?.levels.get(ref.ilvl);
+    if (!list || !level) return null;
     let counters = countersByList.get(ref.numId);
     if (!counters) {
       counters = /* @__PURE__ */ new Map();
       countersByList.set(ref.numId, counters);
     }
     advance(counters, list, ref.ilvl, level.start);
-    const shape = level.format === "bullet" ? level.text : fillLevels(level.text, list, counters);
-    const text = capped(shape);
-    return text ? { text, indent: levelIndentPt(level.indent) } : null;
+    const shape = level.format === "bullet" ? level.text : fillLevels(level.text, list, counters, level.legal);
+    const drawn = capped(shape);
+    if (!drawn) return null;
+    return {
+      text: level.suffix === "space" ? `${drawn} ` : drawn,
+      indent: levelIndentPt(level.indent),
+      suffix: level.suffix,
+      align: level.align,
+      run: level.run
+    };
   });
 }
 export {

package/dist/numbering/parseNumbering.d.ts

@@ -5,11 +5,11 @@
  * numbering.xml itself goes out as the original bytes on export, so this reading never
  * disturbs the file.
  */
+import type { RunFormat } from "../model/format";
 import type { TabStopDirective } from "../model/tabStops";
 import { type XmlParser } from "../ooxml/xml";
-/** The number formats actually used across every fixture */
-declare const NUMBER_FORMATS: readonly ["decimal", "bullet", "lowerLetter", "upperLetter", "lowerRoman"];
-export type NumberFormat = (typeof NUMBER_FORMATS)[number];
+import { type NumberFormat } from "./spellers";
+export type { NumberFormat } from "./spellers";
 /**
  * The indent a level defines. The unit is twips (1/20 of a point), and a slot that is
  * not recorded is null
@@ -20,6 +20,10 @@ export interface LevelIndent {
     hangingTwips: number | null;
     firstLineTwips: number | null;
 }
+/** What stands between a level's number and the text of the paragraph (`w:suff`, §17.9.28) */
+export type LevelSuffix = "tab" | "space" | "nothing";
+/** Where a level's number sits in the space kept for it (`w:lvlJc`, §17.9.7) */
+export type LevelAlign = "left" | "center" | "right";
 export interface NumberingLevel {
     format: NumberFormat;
     /**
@@ -32,14 +36,58 @@ export interface NumberingLevel {
     indent: LevelIndent | null;
     /** Custom stops contributed by this level's paragraph properties. */
     tabStops?: readonly TabStopDirective[];
+    /**
+     * The deepest level whose advance sends this one back to its start (`w:lvlRestart`, §17.9.10),
+     * as a level number: any level above that one restarts it too. A level of -1 never restarts, and
+     * null is the default, the level right above this one.
+     */
+    restartAfterLevel: number | null;
+    /** Every level in this level's text spelled as a decimal, whatever format it counts in (`w:isLgl`, §17.9.4) */
+    legal: boolean;
+    suffix: LevelSuffix;
+    align: LevelAlign;
+    /**
+     * The formatting of the number itself (`w:rPr`, §17.9.24). It dresses the number alone and
+     * never the text of the paragraph the number stands in front of.
+     * Null where the level writes none, and where the caller handed in no reader for it.
+     */
+    run: RunFormat | null;
 }
+/**
+ * How a level's `w:rPr` is read into display values.
+ * The vocabulary of run properties belongs with the reader that holds styles.xml and the theme
+ * fonts, which this folder cannot reach, so it is handed in.
+ */
+export type ReadLevelRun = (rPr: Element) => RunFormat | null;
 export interface NumberingList {
     /** The shape for each level (ilvl) */
-    levels: Map<number, NumberingLevel>;
+    levels: ReadonlyMap<number, NumberingLevel>;
+}
+/**
+ * A level a list started while editing is registered with.
+ *
+ * It is a level minus the two things the writer of a new definition cannot spell where it stands:
+ * the formatting of the number (`w:rPr`) and the tab stops its paragraphs contribute (`w:tabs`)
+ * are written by `docx/`, which stands above this folder. Leaving them out of what may be
+ * registered is what keeps a registered definition from reaching the file with a part of it
+ * silently dropped.
+ */
+export interface NewListLevel extends NumberingLevel {
+    readonly run: null;
+    readonly tabStops?: undefined;
+}
+/** A list started while editing, whose definition the export writes into numbering.xml as it stands */
+export interface NewList {
+    levels: ReadonlyMap<number, NewListLevel>;
 }
 export interface Numbering {
     /** The list for each numId */
     lists: Map<number, NumberingList>;
+    /**
+     * The lists started while editing, by the number each was given. numbering.xml defines none of
+     * them yet; the export writes the definition registered here.
+     */
+    added: ReadonlyMap<number, NewList>;
 }
 export declare const EMPTY_NUMBERING: Numbering;
 /**
@@ -62,6 +110,17 @@ export declare const NO_LEVEL_INDENT: LevelIndentPt;
  * OOXML rule).
  */
 export declare function levelIndentPt(indent: LevelIndent | null): LevelIndentPt;
+export declare const LEVEL_SUFFIXES: readonly LevelSuffix[];
+/** The justifications a number can take, which are the ones `w:lvlJc` offers a number */
+export declare const LEVEL_ALIGNS: readonly LevelAlign[];
+/**
+ * The list each numbering style names, by the style's id.
+ *
+ * A numbering style is never worn by a paragraph: it is a name on a list, which an abstract
+ * definition reaches through `w:numStyleLink` (§17.9.21). The map is built from styles.xml, which
+ * this folder cannot read for itself.
+ */
+export type NumberingStyleLinks = ReadonlyMap<string, number>;
 /** What a caller may say about reading numbering beyond handing over the XML */
 export interface NumberingOptions {
     /**
@@ -69,10 +128,16 @@ export interface NumberingOptions {
      * runtime carrying none refuses the read with `no-xml-parser`.
      */
     xmlParser?: XmlParser;
+    /**
+     * The list each numbering style of the document names. Left out, a definition deferring to a
+     * numbering style is read through the definition that declares it stands behind that style.
+     */
+    links?: NumberingStyleLinks;
+    /** How the formatting a level puts on its number is read. Left out, no level carries any */
+    readRun?: ReadLevelRun;
 }
 /**
  * The lists this numbering XML defines. `null` is the document that has no numbering part, which
  * defines none and asks nothing of a parser.
  */
 export declare function parseNumbering(xml: string | null, options?: NumberingOptions): Numbering;
-export {};