@portone/docx-editor 0.6.0 → 0.6.2

package/dist/editor/commands/noteCommands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Puts a note into the document and writes what one says, exported once per kind the way
+ * `toggleBold` and `toggleItalic` are rather than as one command taking a kind. Deleting and
+ * copying a reference need no command: the edit that does either settles the note it calls
+ * (`editor/plugins/noteLifecycle`).
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import type { Command, EditorState } from "prosemirror-state";
+import type { NoteKind } from "../../schema/stories";
+/** Writes what one note of this kind says; an editing view's edit reaches the document this way */
+export declare function noteBodyCommand(kind: NoteKind, id: string, body: PMNode): Command;
+/**
+ * Puts a footnote reference at the end of the selection, calling a new, empty footnote, and asks
+ * for that footnote to be opened. The footnote is written in the document's footnote styles where
+ * it defines them, and in superscript where it does not.
+ */
+export declare const insertFootnote: Command;
+/** Whether a footnote can go in at the end of the selection */
+export declare function canInsertFootnote(state: EditorState): boolean;
+/**
+ * Replaces what one footnote says with a `doc` node of `docxSchema`. It applies where an edit at
+ * the footnote's first reference would, and never to a separator, a footnote the text does not
+ * refer to, or a body saying what the footnote already says.
+ */
+export declare function setFootnoteBody(id: string, body: PMNode): Command;
+/**
+ * Puts the caret just after a footnote's reference and opens the footnote for editing, which is
+ * what a press on its number runs. It applies under every mode, since opening a note is reading
+ * it; a footnote opened where the body is shut takes no typing.
+ */
+export declare function openFootnote(id: string): Command;
+/**
+ * Puts an endnote reference at the end of the selection, calling a new, empty endnote, and asks
+ * for that endnote to be opened; `insertFootnote` for an endnote, which is drawn after the last
+ * paragraph of the document rather than at the foot of a page.
+ */
+export declare const insertEndnote: Command;
+/** Whether an endnote can go in at the end of the selection */
+export declare function canInsertEndnote(state: EditorState): boolean;
+/** Replaces what one endnote says with a `doc` node of `docxSchema`, as `setFootnoteBody` does */
+export declare function setEndnoteBody(id: string, body: PMNode): Command;
+/**
+ * Puts the caret just after an endnote's reference and opens the endnote for editing;
+ * `openFootnote` for an endnote, which stands at the end of the document, so this is also what
+ * takes a reader to it.
+ */
+export declare function openEndnote(id: string): Command;

package/dist/editor/commands/noteCommands.js

@@ -0,0 +1,95 @@
+// src/editor/commands/noteCommands.ts
+import {
+  newNoteStory,
+  nextNoteId,
+  noteNumberRunProps,
+  takenNoteIds
+} from "../../docx/notes/newNote.js";
+import { sameStory, setStory, storyKey, storyOf } from "../../docx/story.js";
+import { docxSchema } from "../../schema/index.js";
+import { guardedCommand } from "../../schema/guards.js";
+import { isWrapperType } from "../../schema/wrappers.js";
+import { documentOf } from "../editorDocument.js";
+import {
+  noteReferenceAt,
+  openNoteCommand,
+  requestNote
+} from "../plugins/noteNavigation.js";
+function wrappersBefore(doc, pos) {
+  const $pos = doc.resolve(pos);
+  return ($pos.nodeBefore?.marks ?? $pos.marks()).filter(
+    (mark) => isWrapperType(mark.type)
+  );
+}
+function insertNoteTransaction(state, kind) {
+  const at = state.selection.to;
+  const $at = state.doc.resolve(at);
+  const type = docxSchema.nodes.noteReference;
+  if (!$at.parent.canReplaceWith($at.index(), $at.index(), type)) return null;
+  const { formatting, reservedNoteKeys } = documentOf(state);
+  const id = nextNoteId(takenNoteIds(state.doc, kind, reservedNoteKeys));
+  const reference = type.create({ kind, id }, null, [
+    docxSchema.marks.run.create({ rPr: noteNumberRunProps(kind, formatting) }),
+    ...wrappersBefore(state.doc, at)
+  ]);
+  const key = storyKey(kind, id);
+  return requestNote(
+    setStory(
+      state.tr.insert(at, reference),
+      key,
+      newNoteStory(kind, formatting)
+    ),
+    key
+  );
+}
+function insertNoteCommand(kind) {
+  return guardedCommand((state) => insertNoteTransaction(state, kind));
+}
+function noteBodyTransaction(state, kind, id, body) {
+  const key = storyKey(kind, id);
+  if (body.type !== docxSchema.nodes.doc) return null;
+  if (documentOf(state).specialNotes.has(key)) return null;
+  const found = noteReferenceAt(state.doc, kind, id);
+  if (found === null) return null;
+  if (sameStory(storyOf(state.doc, key), body)) return null;
+  return setStory(state.tr, key, body).setNodeMarkup(
+    found.pos,
+    null,
+    found.node.attrs,
+    found.node.marks
+  );
+}
+function noteBodyCommand(kind, id, body) {
+  return guardedCommand((state) => noteBodyTransaction(state, kind, id, body));
+}
+var insertFootnote = insertNoteCommand("footnote");
+function canInsertFootnote(state) {
+  return insertFootnote(state);
+}
+function setFootnoteBody(id, body) {
+  return noteBodyCommand("footnote", id, body);
+}
+function openFootnote(id) {
+  return openNoteCommand("footnote", id);
+}
+var insertEndnote = insertNoteCommand("endnote");
+function canInsertEndnote(state) {
+  return insertEndnote(state);
+}
+function setEndnoteBody(id, body) {
+  return noteBodyCommand("endnote", id, body);
+}
+function openEndnote(id) {
+  return openNoteCommand("endnote", id);
+}
+export {
+  canInsertEndnote,
+  canInsertFootnote,
+  insertEndnote,
+  insertFootnote,
+  noteBodyCommand,
+  openEndnote,
+  openFootnote,
+  setEndnoteBody,
+  setFootnoteBody
+};

package/dist/editor/commands/noteQueries.d.ts

@@ -1,7 +1,9 @@
 /** Document-level readers for imported footnotes and endnotes. */
+import type { Node as PMNode } from "prosemirror-model";
 import type { EditorState } from "prosemirror-state";
 import { DecorationSet } from "prosemirror-view";
-import type { NoteKind } from "../../docx/notes";
+import { type StoryKey } from "../../docx/story";
+import type { NoteKind } from "../../schema/stories";
 export interface DocumentNote {
     readonly kind: NoteKind;
     readonly id: string;
@@ -9,6 +11,17 @@ export interface DocumentNote {
     readonly text: string;
     readonly referencePos: number;
 }
+/** One note the body refers to, as the notes drawn around the page draw it */
+export interface NoteRow {
+    readonly key: StoryKey;
+    readonly kind: NoteKind;
+    readonly id: string;
+    readonly label: string;
+    /** The note's story, the same node for as long as it says the same thing (`schema/stories`) */
+    readonly story: PMNode;
+    /** Where the first reference to it stands, which is the place in the text it is called from */
+    readonly referencePos: number;
+}
 interface NoteProjection {
     notes: readonly DocumentNote[];
     /**
@@ -17,11 +30,17 @@ interface NoteProjection {
      * says is a story on the document and not an attr of the reference.
      */
     tooltips: DecorationSet;
+    /** The footnotes whose story the document holds, by story key, in first-reference order */
+    footnotes: ReadonlyMap<StoryKey, NoteRow>;
+    /** The endnotes whose story the document holds, in first-reference order */
+    endnotes: readonly NoteRow[];
+    /** Every note of both kinds by story key, which the surface over the open note reads rows from */
+    rows: ReadonlyMap<StoryKey, NoteRow>;
 }
 /**
  * Which notes the document refers to is the document's to decide, so the list is worked out once
- * per edit (`editor/plugins/documentProjection`) rather than once per render of the panel under
- * the page.
+ * per edit (`editor/plugins/documentProjection`) rather than once per render of the notes drawn
+ * around the page.
  */
 export declare const noteProjection: import("../plugins/documentProjection").DocumentProjection<NoteProjection>;
 /** The distinct notes referenced by the main document story, in first-reference order. */

package/dist/editor/commands/noteQueries.js

@@ -8,35 +8,43 @@ function stringAttr(value) {
 function noteKindOf(node) {
   return node.attrs.kind === "endnote" ? "endnote" : "footnote";
 }
-function noteText(doc, kind, id) {
-  return storyText(storyOf(doc, storyKey(kind, id)));
-}
 function deriveNotes(doc) {
   const notes = [];
   const tooltips = [];
+  const footnotes = /* @__PURE__ */ new Map();
+  const endnotes = [];
+  const rows = /* @__PURE__ */ new Map();
   const seen = /* @__PURE__ */ new Set();
   doc.descendants((node, pos) => {
     if (node.type.name !== "noteReference") return true;
     const id = stringAttr(node.attrs.id);
     if (id === null) return true;
     const kind = noteKindOf(node);
-    const text = noteText(doc, kind, id);
+    const key = storyKey(kind, id);
+    const story = storyOf(doc, key);
+    const text = storyText(story);
     if (text !== "") {
       tooltips.push(Decoration.node(pos, pos + node.nodeSize, { title: text }));
     }
-    const key = `${kind}:${id}`;
     if (seen.has(key)) return true;
     seen.add(key);
-    notes.push({
-      kind,
-      id,
-      label: stringAttr(node.attrs.label) ?? "?",
-      text,
-      referencePos: pos
-    });
+    const label = stringAttr(node.attrs.label) ?? "?";
+    notes.push({ kind, id, label, text, referencePos: pos });
+    if (story !== null) {
+      const row = { key, kind, id, label, story, referencePos: pos };
+      rows.set(key, row);
+      if (kind === "footnote") footnotes.set(key, row);
+      else endnotes.push(row);
+    }
     return true;
   });
-  return { notes, tooltips: DecorationSet.create(doc, tooltips) };
+  return {
+    notes,
+    tooltips: DecorationSet.create(doc, tooltips),
+    footnotes,
+    endnotes,
+    rows
+  };
 }
 var noteProjection = documentProjection(
   "docxEditorNotes",

package/dist/editor/createEditor.js

@@ -6,6 +6,7 @@ import { keymap } from "prosemirror-keymap";
 import { EditorState } from "prosemirror-state";
 import { tableEditing } from "prosemirror-tables";
 import { EditorView } from "prosemirror-view";
+import { withNoteLabels } from "../docx/notes/numbering.js";
 import { pageDecorations } from "../page/pageDecorations.js";
 import { pageGeometryStyle, pagePixels } from "../page/pageLayout.js";
 import { editsShut } from "../schema/protectionState.js";
@@ -27,6 +28,7 @@ import { columnResize } from "./plugins/columnResize.js";
 import { commentComposer } from "./plugins/commentComposer.js";
 import { commentDecorations } from "./plugins/commentDecorations.js";
 import { commentRestoration } from "./plugins/commentRestoration.js";
+import { compositionSelection } from "./plugins/compositionSelection.js";
 import {
   displayDerivation,
   withDerivedDisplay
@@ -37,6 +39,9 @@ import { docxKeymap, historyKeys } from "./plugins/keymap.js";
 import { linkPanel } from "./plugins/linkPanel.js";
 import { listInputRules } from "./plugins/listInputRules.js";
 import { lockedContent } from "./plugins/lockedContent.js";
+import { noteLifecycle } from "./plugins/noteLifecycle.js";
+import { noteNavigation } from "./plugins/noteNavigation.js";
+import { noteNumbering } from "./plugins/noteNumbering.js";
 import { numberingMarkers } from "./plugins/numberingDecorations.js";
 import { rowResize } from "./plugins/rowResize.js";
 import { tabCaret } from "./plugins/tabCaret.js";
@@ -58,8 +63,13 @@ function createEditorState(doc, options = {}) {
   } = options;
   return EditorState.create({
     // The values the document arrived with were worked out against whatever opened it; the
-    // state's are worked out against its own snapshot, tables' shared lines included
-    doc: withDerivedDisplay(doc, document),
+    // state's are worked out against its own snapshot, tables' shared lines and note labels
+    // included
+    doc: withNoteLabels(
+      withDerivedDisplay(doc, document),
+      document.noteNumbering,
+      document.specialNotes
+    ),
     plugins: [
       // Consumer plugins lead the array. ProseMirror walks the plugins in order and takes the
       // first answer for a keypress, a paste, a drop or any other DOM event, so this is the
@@ -70,9 +80,12 @@ function createEditorState(doc, options = {}) {
       editorDocument(document),
       // Refuses every edit no guard in `schema/guards` lets through, whoever asked for it. It is
       // not optional: a document that locked a part of itself stays locked in every consumer, and
-      // the preserved bookmark markers and note references stay where the file put them.
+      // the preserved bookmark markers stay where the file put them.
       lockedContent(),
       documentProtection({ protection, author, editableComments }),
+      // Ahead of the keys and the clipboard: the plugin registered first sees a DOM event first,
+      // and this one hands every composition on
+      compositionSelection(),
       history(),
       keymap(docxKeymap),
       historyKeys(),
@@ -100,8 +113,13 @@ function createEditorState(doc, options = {}) {
       // A comment outlives the text it was written for: an edit that sweeps its reference away has
       // it put back where the deletion left, detached from the page (`plugins/commentRestoration`)
       commentRestoration(),
+      // A note goes with the last reference to it, and a copied reference gets a note of its own.
+      // It stands ahead of the numbering, which then labels what it settled
+      noteLifecycle(),
+      noteNumbering(),
       // What the notes under the page are, worked out from the document the same way
       noteProjection.plugin,
+      noteNavigation(),
       // Adjacent text tabs still need separate DOM ranges for layout and pointer selection.
       tabDecorations(),
       tabPointer(),

package/dist/editor/documentStyles.d.ts

@@ -36,6 +36,9 @@ export declare function documentGeometry(state: EditorState): PageGeometry;
  * section is where the document says it is, and the snapshot holds the first section's paper
  * alone. Reading it walks every block, so a caller drawing a whole document asks once and looks
  * its positions up (`page/pageLayout`) rather than calling this per block.
+ *
+ * A side story writes down no section, so its own blocks say nothing about the paper: what it is
+ * drawn on is the paper of the place it is called from, which its snapshot carries.
  */
 export declare function sectionGeometryAt(state: EditorState, pos: number): PageGeometry;
 /** The document-wide interval between automatic tab stops, in points. */

package/dist/editor/documentStyles.js

@@ -19,7 +19,8 @@ function documentGeometry(state) {
   return documentOf(state).geometry;
 }
 function sectionGeometryAt(state, pos) {
-  return sectionAt(state.doc, pos).props.geometry;
+  const document = documentOf(state);
+  return document.sideStory ? document.geometry : sectionAt(state.doc, pos).props.geometry;
 }
 function documentDefaultTabStopPt(state) {
   return documentOf(state).defaultTabStopPt;

package/dist/editor/editorDocument.d.ts

@@ -10,9 +10,11 @@
 import type { Node as PMNode } from "prosemirror-model";
 import { type EditorState, Plugin } from "prosemirror-state";
 import { type FormattingContext, type ParagraphStyleOption } from "../docx/formatting";
+import { type NoteNumbering } from "../docx/notes/reading";
 import { type PageGeometry } from "../docx/pageGeometry";
 import type { SessionStore } from "../docx/session";
 import type { DocumentDefaults } from "../model/format";
+import { type StoryKey } from "../schema/stories";
 /** The document-level values one editing state is built on */
 export interface EditorDocument {
     /** The document these values were read from. Null for a state built without one */
@@ -30,12 +32,26 @@ export interface EditorDocument {
     readonly canStartNewList: boolean;
     /** The paper the document is written on, which decides the width a new table is fitted to */
     readonly geometry: PageGeometry;
+    /**
+     * Whether these values stand for a side story rather than for the body, whose paper is then the
+     * geometry above rather than anything the story's own blocks say (`editor/documentStyles`).
+     */
+    readonly sideStory: boolean;
     /** The distance between automatic tab stops when no custom stop applies */
     readonly defaultTabStopPt: number;
     /** Every id already present in the opened Comments part, including unreferenced entries */
     readonly reservedCommentIds: ReadonlySet<string>;
     /** Every paragraph id present in the opened comment parts, including orphan extension entries */
     readonly reservedCommentParaIds: ReadonlySet<string>;
+    /** How the document counts its footnotes and endnotes, which the note labels are spelled in */
+    readonly noteNumbering: NoteNumbering;
+    /** The note entries that lay out the page rather than number a note: separators and the continuation notice */
+    readonly specialNotes: ReadonlySet<StoryKey>;
+    /**
+     * Every entry of an editable kind the opened notes parts hold, separators and entries no
+     * reference names included, which a new note may not take the id of
+     */
+    readonly reservedNoteKeys: ReadonlySet<StoryKey>;
 }
 /** What a state built without an opened document answers: the same as nothing being written down */
 export declare const NO_DOCUMENT: EditorDocument;
@@ -51,6 +67,14 @@ export declare function documentOf(state: EditorState): EditorDocument;
  * both leave the same object behind, allowing the sheet's style to be cached against that identity.
  */
 export declare function editorDocument(document: EditorDocument): Plugin<EditorDocument>;
+/**
+ * The snapshot one side story is edited against: the document's own values, with the two a story
+ * answers differently.
+ *
+ * A story has nowhere of its own to write a list definition, and the paper its text wraps at is
+ * the paper of the place it is called from rather than anything the story says.
+ */
+export declare function storyDocument(document: EditorDocument, geometry: PageGeometry): EditorDocument;
 /** The comment ids the opened document already spent, which a new comment may not take */
 export declare function reservedCommentIds(state: EditorState): ReadonlySet<string>;
 /** The paragraph ids the opened comment parts already spent */

package/dist/editor/editorDocument.js

@@ -6,9 +6,17 @@ import {
   NO_FORMATTING
 } from "../docx/formatting.js";
 import { canDefineNewList } from "../docx/newLists.js";
+import {
+  DEFAULT_NOTE_NUMBERING
+} from "../docx/notes/reading.js";
 import { A4_PORTRAIT } from "../docx/pageGeometry.js";
 import { NEW_LISTS_ATTR, newListsOf } from "../numbering/listRegistry.js";
+import {
+  EDITABLE_NOTE_KINDS,
+  STORIES_ATTR
+} from "../schema/stories.js";
 var NO_IDS = /* @__PURE__ */ new Set();
+var NO_NOTE_KEYS = /* @__PURE__ */ new Set();
 var NO_PARAGRAPH_STYLES = [];
 var NO_DOCUMENT = {
   session: null,
@@ -17,9 +25,13 @@ var NO_DOCUMENT = {
   paragraphStyles: NO_PARAGRAPH_STYLES,
   canStartNewList: true,
   geometry: A4_PORTRAIT,
+  sideStory: false,
   defaultTabStopPt: DEFAULT_TAB_STOP_PT,
   reservedCommentIds: NO_IDS,
-  reservedCommentParaIds: NO_IDS
+  reservedCommentParaIds: NO_IDS,
+  noteNumbering: DEFAULT_NOTE_NUMBERING,
+  specialNotes: NO_NOTE_KEYS,
+  reservedNoteKeys: NO_NOTE_KEYS
 };
 function reservedParaIds(session) {
   const paraIds = /* @__PURE__ */ new Set();
@@ -46,9 +58,17 @@ function editorDocumentOf(session, doc) {
     paragraphStyles: session.paragraphStyles,
     canStartNewList: canDefineNewList(session),
     geometry: session.geometry,
+    sideStory: false,
     defaultTabStopPt: session.defaultTabStopPt,
     reservedCommentIds: new Set(session.comments.byId.keys()),
-    reservedCommentParaIds: reservedParaIds(session)
+    reservedCommentParaIds: reservedParaIds(session),
+    noteNumbering: session.noteNumbering,
+    specialNotes: session.specialNotes,
+    reservedNoteKeys: new Set(
+      Array.from(session.stories.values()).flatMap(
+        (story) => EDITABLE_NOTE_KINDS.some((kind) => kind === story.kind) ? [story.key] : []
+      )
+    )
   };
 }
 var editorDocumentKey = new PluginKey("docxEditorDocument");
@@ -61,15 +81,24 @@ function derived(current, doc) {
     formatting: formattingWithNewLists(current.formatting, doc)
   } : editorDocumentOf(current.session, doc);
 }
+function onlyStoriesMoved(next, before) {
+  const names = Object.keys(next.attrs);
+  return next.attrs[STORIES_ATTR] !== before.attrs[STORIES_ATTR] && names.length === Object.keys(before.attrs).length && names.every(
+    (name) => name === STORIES_ATTR || next.attrs[name] === before.attrs[name]
+  );
+}
 function editorDocument(document) {
   return new Plugin({
     key: editorDocumentKey,
     state: {
       init: () => document,
-      apply: (tr, current, old) => tr.doc.attrs === old.doc.attrs ? current : derived(current, tr.doc)
+      apply: (tr, current, old) => tr.doc.attrs === old.doc.attrs || onlyStoriesMoved(tr.doc, old.doc) ? current : derived(current, tr.doc)
     }
   });
 }
+function storyDocument(document, geometry) {
+  return { ...document, sideStory: true, canStartNewList: false, geometry };
+}
 function reservedCommentIds(state) {
   return documentOf(state).reservedCommentIds;
 }
@@ -82,5 +111,6 @@ export {
   editorDocument,
   editorDocumentOf,
   reservedCommentIds,
-  reservedCommentParaIds
+  reservedCommentParaIds,
+  storyDocument
 };

package/dist/editor/notes/noteSurface.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What a footnote or an endnote draws and does differently from any other story.
+ *
+ * A note's story opens with a mark of its own (`w:footnoteRef`, `w:endnoteRef`), which the file
+ * keeps as a preserved chip. Word draws that mark as the number the reference carries, so it is
+ * drawn here as that label in superscript, the way the reference in the body is.
+ *
+ * The rest is what the story view asks a kind of story for (`editor/stories`): the host every
+ * edit leaves through, and the extensions that give a note its chip, its key rule, the number it
+ * keeps through an edit, and what a paste into one may carry.
+ */
+import type { EditorView } from "prosemirror-view";
+import { type StoryKey } from "../../schema/stories";
+import { type SliceNormalizer } from "../clipboard/normalizers";
+import type { StoryNodeSpecs } from "../stories/storyMarkup";
+import { type StoryExtensions, type StoryHost } from "../stories/storyView";
+/** The node specs a note's story is drawn with, its own reference mark drawn as `labelOf` answers */
+export declare function noteNodeSpecs(labelOf: () => string): StoryNodeSpecs;
+/**
+ * Takes out of a paste what the notes part cannot be written with: an image, and a link.
+ *
+ * Either needs a relationship of the part it stands in, and the notes part writer writes none, so
+ * both would go out naming a relationship the file does not hold. A link or an image the file
+ * itself wrote inside a note stays; this is about what a paste would add.
+ */
+export declare const dropUnwritableContent: SliceNormalizer;
+/**
+ * Takes a note reference out of a paste: a note may not hold a note.
+ *
+ * The lifecycle, the numbering and the writer all walk the body alone, so a reference inside a
+ * story would call a note nothing numbers, counts or settles, and one copied from beside the note
+ * it was pasted into would have that note calling itself. The text it stood in stays, the way the
+ * other anchors leave theirs (`editor/clipboard/normalizers`).
+ */
+export declare const dropNoteReferences: SliceNormalizer;
+/**
+ * Puts the caret back just after the reference that calls this note and takes the body's focus,
+ * which is what leaves the note: Escape and a press on the note's own number both run it.
+ */
+export declare function returnToReference(main: EditorView, key: StoryKey): void;
+/**
+ * The host a note's editing view writes through, whichever kind of note stands under the key.
+ *
+ * Every edit leaves as that kind's own body command, so a lock around the reference and the
+ * editing protection judge a note edit where they judge a body edit, and the main document keeps
+ * the one history both share.
+ */
+export declare function noteHost(main: EditorView, activate: StoryHost["activate"]): StoryHost;
+/**
+ * What a note adds to the story view: its chip, the number it keeps first, its key rule, and what
+ * a paste may bring in
+ */
+export declare function noteExtensions(main: EditorView, key: StoryKey, labelOf: () => string): StoryExtensions;