@portone/docx-editor 0.5.1 → 0.6.1

package/dist/ui/notes/NoteAreas.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The notes drawn over the paper, in the room the page layout kept for them.
+ *
+ * One component draws both kinds, since they differ only in where a page's room comes from, what
+ * the area is called, its class, whether the rule above the notes is drawn on that page, and what
+ * is drawn in it; the layer over the sheet, the row that takes its room before it is measured, the
+ * one editing view and the press that opens a note hold for both.
+ *
+ * Each area is given the height the layout kept, so one asking for more room than the page had
+ * left scrolls inside it.
+ */
+import type { CSSProperties, ReactElement } from "react";
+import type { NoteRow } from "../../editor/commands/noteQueries";
+import type { PageOverlay } from "../../page/usePageLayout";
+import { type StoryKey } from "../../schema/stories";
+import type { FontFallbacks } from "../../styles/fontStack";
+import { type NoteHeightReport, type RowEditing } from "./StoryRow";
+/** The room one page keeps for notes, as the notes drawn in it are placed and named */
+export interface NoteArea {
+    readonly page: number;
+    /** What assistive technology calls the area */
+    readonly name: string;
+    /** What the page keeps there, by story key, in the order the layout laid them */
+    readonly ids: readonly string[];
+    readonly top: number;
+    readonly left: number;
+    readonly width: number;
+    readonly height: number;
+    /** Whether the notes ask for more room than the page had left, so the area scrolls them */
+    readonly scrolls: boolean;
+    /** Whether the rule the notes are set under is drawn above this page's */
+    readonly rule: boolean;
+}
+/** The rooms each page keeps for its footnotes, which every page holding one is given */
+export declare function footnoteAreasOf(overlay: PageOverlay): readonly NoteArea[];
+/**
+ * The rooms the endnotes take after the last paragraph of the document.
+ *
+ * They are one run of notes rather than a page's own, so the rule is drawn once, above the page
+ * they begin on.
+ */
+export declare function endnoteAreasOf(overlay: PageOverlay): readonly NoteArea[];
+export interface NoteAreasProps {
+    /** Where the pages stand, which is the box the areas are placed inside */
+    readonly overlay: PageOverlay;
+    readonly areas: readonly NoteArea[];
+    /** The class each area carries, which is what tells the two kinds apart on the screen */
+    readonly areaClassName: string;
+    /** The notes these areas draw, by story key, which is what the layout laid out by id */
+    readonly rows: ReadonlyMap<string, NoteRow>;
+    readonly heights: ReadonlyMap<StoryKey, number>;
+    readonly onHeight: NoteHeightReport;
+    readonly fontFallbacks: FontFallbacks;
+    /** How the document sets its text, which the sheet's own box does not pass down to these */
+    readonly textStyle: CSSProperties;
+    readonly zoom: number;
+    /** The note the caret is in, which is the one row an editing view stands over */
+    readonly open?: StoryKey | null;
+    /** What mounts that view. Null while no note is open */
+    readonly editing?: RowEditing | null;
+    /** Whether the open note stands where nothing may be edited */
+    readonly readOnly?: boolean;
+    /** A value that differs every time the main document changes, which the open row syncs on */
+    readonly revision?: unknown;
+    /** Called for a press on a note no view stands over yet */
+    readonly onOpen?: (key: StoryKey, at: {
+        left: number;
+        top: number;
+    }) => void;
+    /** Called for a press on the number a note is drawn by, which is the way back to its reference */
+    readonly onReturn?: (key: StoryKey) => void;
+}
+export declare function NoteAreas({ overlay, areas, areaClassName, rows, heights, onHeight, fontFallbacks, textStyle, zoom, open, editing, readOnly, revision, onOpen, onReturn, }: NoteAreasProps): ReactElement;

package/dist/ui/notes/NoteAreas.js

@@ -0,0 +1,131 @@
+// src/ui/notes/NoteAreas.tsx
+import { FOOTNOTE_BAND } from "../../page/demands/footnoteDemands.js";
+import { noteName } from "../../schema/stories.js";
+import { editorClassNames } from "../../styles/classNames.js";
+import { NOTE_SEPARATOR_HEIGHT, noteSeparatorWidth } from "./noteSeparator.js";
+import { StoryRow } from "./StoryRow.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function footnoteAreasOf(overlay) {
+  return overlay.pages.flatMap(
+    (page) => page.reserved.filter((room) => room.band === FOOTNOTE_BAND).map((room) => ({
+      page: page.page,
+      name: `Footnotes on page ${page.page}`,
+      ids: room.ids,
+      top: room.top,
+      left: page.left,
+      width: page.width,
+      height: room.height,
+      scrolls: room.clipped,
+      // A page's footnotes are set under a rule of their own, wherever they stand
+      rule: true
+    }))
+  );
+}
+function endnoteAreasOf(overlay) {
+  const opening = overlay.pages.find((page) => page.trailing !== null)?.page;
+  return overlay.pages.flatMap((page) => {
+    const room = page.trailing;
+    return room === null ? [] : [
+      {
+        page: page.page,
+        name: `Endnotes on page ${page.page}`,
+        ids: room.ids,
+        top: room.top,
+        left: page.left,
+        width: page.width,
+        height: room.height,
+        scrolls: room.clipped,
+        rule: page.page === opening
+      }
+    ];
+  });
+}
+function NoteAreas({
+  overlay,
+  areas,
+  areaClassName,
+  rows,
+  heights,
+  onHeight,
+  fontFallbacks,
+  textStyle,
+  zoom,
+  open = null,
+  editing = null,
+  readOnly = false,
+  revision,
+  onOpen,
+  onReturn
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: editorClassNames.noteAreas,
+      style: {
+        left: `${overlay.left}px`,
+        top: `${overlay.top}px`,
+        width: `${overlay.width}px`,
+        height: `${overlay.sheetHeight}px`
+      },
+      children: areas.map((area) => /* @__PURE__ */ jsxs(
+        "section",
+        {
+          className: areaClassName,
+          "aria-label": area.name,
+          style: {
+            ...textStyle,
+            top: `${area.top}px`,
+            left: `${area.left}px`,
+            width: `${area.width}px`,
+            height: `${area.height}px`,
+            overflowY: area.scrolls ? "auto" : "hidden"
+          },
+          children: [
+            area.rule && /* @__PURE__ */ jsx(
+              "div",
+              {
+                className: editorClassNames.noteSeparator,
+                style: {
+                  height: `${NOTE_SEPARATOR_HEIGHT}px`,
+                  width: `${noteSeparatorWidth(area.width)}px`
+                }
+              }
+            ),
+            area.ids.flatMap((id) => {
+              const row = rows.get(id);
+              if (row === void 0) return [];
+              const entered = row.key === open;
+              return [
+                /* @__PURE__ */ jsx(
+                  StoryRow,
+                  {
+                    noteKey: row.key,
+                    story: row.story,
+                    label: row.label,
+                    name: noteName(row.kind, row.label),
+                    fontFallbacks,
+                    hidden: !entered && !heights.has(row.key),
+                    onHeight,
+                    zoom,
+                    editing: entered ? editing : null,
+                    readOnly,
+                    revision: entered ? revision : void 0,
+                    onPress: onOpen === void 0 ? void 0 : (at) => onOpen(row.key, at),
+                    onReturn: onReturn === void 0 ? void 0 : () => onReturn(row.key)
+                  },
+                  row.key
+                )
+              ];
+            })
+          ]
+        },
+        area.page
+      ))
+    }
+  );
+}
+export {
+  NoteAreas,
+  endnoteAreasOf,
+  footnoteAreasOf
+};

package/dist/ui/notes/NoteList.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The notes listed under the sheet while no page has kept room for them: the footnotes ahead of
+ * the endnotes, the order they are called in.
+ *
+ * A note stands where its own page keeps room for it (`./NoteAreas`), which needs a page that has
+ * been laid out: the guides may be off, or the first frame may not have been measured yet. Until
+ * then they are listed here, where none of them is edited in place.
+ *
+ * Each note is drawn from its story (`./StoryRow`) across the width the body is set at, so a note
+ * wraps here where it would on the page.
+ */
+import type { CSSProperties, ReactElement } from "react";
+import type { NoteRow } from "../../editor/commands/noteQueries";
+import type { PagePixels } from "../../page/pageLayout";
+import type { FontFallbacks } from "../../styles/fontStack";
+export interface NoteListProps {
+    readonly footnotes: readonly NoteRow[];
+    readonly endnotes: readonly NoteRow[];
+    /** The paper the first section is drawn on, which the list is as wide as */
+    readonly page: PagePixels;
+    readonly fontFallbacks: FontFallbacks;
+    /** How the document sets its text, which the sheet's own box does not pass down to this */
+    readonly textStyle: CSSProperties;
+}
+export declare function NoteList({ footnotes, endnotes, page, fontFallbacks, textStyle, }: NoteListProps): ReactElement | null;

package/dist/ui/notes/NoteList.js

@@ -0,0 +1,58 @@
+// src/ui/notes/NoteList.tsx
+import { noteName } from "../../schema/stories.js";
+import { editorClassNames } from "../../styles/classNames.js";
+import { NOTE_SEPARATOR_HEIGHT, noteSeparatorWidth } from "./noteSeparator.js";
+import { StoryRow } from "./StoryRow.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function listName(footnotes, endnotes) {
+  if (footnotes && endnotes) return "Footnotes and endnotes";
+  return footnotes ? "Footnotes" : "Endnotes";
+}
+function NoteList({
+  footnotes,
+  endnotes,
+  page,
+  fontFallbacks,
+  textStyle
+}) {
+  if (footnotes.length === 0 && endnotes.length === 0) return null;
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      className: editorClassNames.noteList,
+      "aria-label": listName(footnotes.length > 0, endnotes.length > 0),
+      style: {
+        ...textStyle,
+        width: `${page.pageWidth}px`,
+        paddingLeft: `${page.marginLeft}px`,
+        paddingRight: `${page.marginRight}px`
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: editorClassNames.noteSeparator,
+            style: {
+              height: `${NOTE_SEPARATOR_HEIGHT}px`,
+              width: `${noteSeparatorWidth(page.bodyWidth)}px`
+            }
+          }
+        ),
+        [...footnotes, ...endnotes].map((row) => /* @__PURE__ */ jsx(
+          StoryRow,
+          {
+            noteKey: row.key,
+            story: row.story,
+            label: row.label,
+            name: noteName(row.kind, row.label),
+            fontFallbacks
+          },
+          row.key
+        ))
+      ]
+    }
+  );
+}
+export {
+  NoteList
+};

package/dist/ui/notes/StoryRow.d.ts

@@ -0,0 +1,75 @@
+/**
+ * One note drawn from its story: as markup no editor view stands behind (`editor/stories`), and as
+ * the one editing view while the caret is in it.
+ *
+ * A row is mounted again whenever its note moves to another page, and a story no edit touched is
+ * the same node afterwards (`schema/stories`), so the markup is kept against the story node rather
+ * than against the row: only a note whose story or label changed is drawn again.
+ *
+ * A row carrying the editing view is mounted again by such a move too, so where the caret stood is
+ * handed over in `editing.caret` and the view opens there. The page is not laid out again while
+ * that view is composing (`DocxEditor`), so a move never reaches an open composition.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import type { EditorState } from "prosemirror-state";
+import { type ReactElement } from "react";
+import type { EditorDocument } from "../../editor/editorDocument";
+import { type StoryMarkupOptions } from "../../editor/stories/storyMarkup";
+import { type StoryCaret, type StoryExtensions, type StoryHost } from "../../editor/stories/storyView";
+import type { StoryKey } from "../../schema/stories";
+import type { FontFallbacks } from "../../styles/fontStack";
+export type DrawStory = (story: PMNode, options: StoryMarkupOptions) => DocumentFragment;
+/** Hands on the height a row stands at on the paper, the zoom taken back out */
+export type NoteHeightReport = (key: StoryKey, height: number) => void;
+/**
+ * What mounts the editing view over this row, which only the row the caret is in is given.
+ *
+ * It is held apart from the row's own props because a row is drawn again on every change to the
+ * document while the view over it has to stand: every field here is the same object for as long as
+ * one note is open, and what changes per edit reaches the view through `revision`.
+ */
+export interface RowEditing {
+    readonly host: StoryHost;
+    /** The values the story is edited against (`editor/editorDocument`) */
+    readonly document: EditorDocument;
+    readonly extensions: StoryExtensions;
+    /** Where the caret opens, and where it stood when the row was last taken down */
+    readonly caret: {
+        take(): StoryCaret | null;
+        keep(caret: StoryCaret): void;
+    };
+    readonly onStateChange: (state: EditorState) => void;
+}
+export interface StoryRowProps {
+    readonly noteKey: StoryKey;
+    readonly story: PMNode;
+    readonly label: string;
+    readonly fontFallbacks: FontFallbacks;
+    /** What assistive technology calls the row */
+    readonly name?: string;
+    /** A hidden row still takes its room, which is what lets it be measured before it is placed */
+    readonly hidden?: boolean;
+    /** Called whenever the row's height changes. Left out, the row is not measured */
+    readonly onHeight?: NoteHeightReport;
+    /** The visual scale the row is drawn at, which a height read off the screen is divided by */
+    readonly zoom?: number;
+    /** What draws the story; `storyMarkup` unless a test counts the drawings */
+    readonly draw?: DrawStory;
+    /** Mounted over this row while the caret is in it, and null while the row is markup */
+    readonly editing?: RowEditing | null;
+    /** A value that differs every time the main document changes, which is when the view is synced */
+    readonly revision?: unknown;
+    /** Whether the note stands where nothing may be edited, which a reader is told rather than shown */
+    readonly readOnly?: boolean;
+    /** Called for a press on a row no view stands over yet, with where on the screen it landed */
+    readonly onPress?: (at: {
+        left: number;
+        top: number;
+    }) => void;
+    /**
+     * Called for a press on the number the note is drawn by, which is the way back to the text that
+     * calls it rather than a place to put the caret
+     */
+    readonly onReturn?: () => void;
+}
+export declare const StoryRow: import("react").MemoExoticComponent<({ noteKey, story, label, fontFallbacks, name, hidden, onHeight, zoom, draw, editing, revision, readOnly, onPress, onReturn, }: StoryRowProps) => ReactElement>;

package/dist/ui/notes/StoryRow.js

@@ -0,0 +1,122 @@
+// src/ui/notes/StoryRow.tsx
+import {
+  memo,
+  useEffect,
+  useLayoutEffect,
+  useRef
+} from "react";
+import { noteNodeSpecs } from "../../editor/notes/noteSurface.js";
+import {
+  storyMarkup
+} from "../../editor/stories/storyMarkup.js";
+import {
+  caretOf,
+  createStoryView
+} from "../../editor/stories/storyView.js";
+import { editorClassNames } from "../../styles/classNames.js";
+import { jsx } from "react/jsx-runtime";
+var drawn = /* @__PURE__ */ new WeakMap();
+function markupOf(story, label, fontFallbacks, draw) {
+  const held = drawn.get(story);
+  if (held?.label === label && held.fontFallbacks === fontFallbacks && held.draw === draw) {
+    return held.markup;
+  }
+  const markup = draw(story, {
+    fontFallbacks,
+    nodeSpecs: noteNodeSpecs(() => label)
+  });
+  drawn.set(story, { label, fontFallbacks, draw, markup });
+  return markup;
+}
+function pressedTheNumber(target) {
+  return target instanceof Element && target.closest(`.${editorClassNames.noteMark}`) !== null;
+}
+var StoryRow = memo(function StoryRow2({
+  noteKey,
+  story,
+  label,
+  fontFallbacks,
+  name,
+  hidden = false,
+  onHeight,
+  zoom = 1,
+  draw = storyMarkup,
+  editing = null,
+  revision,
+  readOnly = false,
+  onPress,
+  onReturn
+}) {
+  const box = useRef(null);
+  const scale = useRef(zoom);
+  const live = useRef(null);
+  useEffect(() => {
+    scale.current = zoom;
+  });
+  useLayoutEffect(() => {
+    if (editing) return;
+    box.current?.replaceChildren(
+      markupOf(story, label, fontFallbacks, draw).cloneNode(true)
+    );
+  }, [editing, story, label, fontFallbacks, draw]);
+  useLayoutEffect(() => {
+    const row = box.current;
+    if (!row || !editing) return;
+    const mount = document.createElement("div");
+    row.replaceChildren(mount);
+    const opened = createStoryView({
+      mount,
+      host: editing.host,
+      key: noteKey,
+      document: editing.document,
+      fontFallbacks,
+      extensions: editing.extensions,
+      caret: editing.caret.take(),
+      onStateChange: editing.onStateChange
+    });
+    live.current = opened;
+    opened.view.focus();
+    return () => {
+      editing.caret.keep(caretOf(opened.view.state));
+      live.current = null;
+      opened.destroy();
+    };
+  }, [editing, noteKey, fontFallbacks]);
+  useLayoutEffect(() => {
+    live.current?.sync();
+  }, [revision]);
+  useEffect(() => {
+    const row = box.current;
+    if (!row || !onHeight || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      onHeight(noteKey, row.getBoundingClientRect().height / scale.current);
+    });
+    observer.observe(row);
+    return () => observer.disconnect();
+  }, [noteKey, onHeight]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: box,
+      className: [
+        editorClassNames.noteRow,
+        editing ? editorClassNames.noteRowOpen : null
+      ].filter(Boolean).join(" "),
+      role: name === void 0 ? void 0 : "group",
+      "aria-label": name,
+      "aria-readonly": editing && readOnly ? true : void 0,
+      style: hidden ? { visibility: "hidden" } : void 0,
+      onMouseDown: editing || !onPress && !onReturn ? void 0 : (event) => {
+        event.preventDefault();
+        if (onReturn && pressedTheNumber(event.target)) {
+          onReturn();
+          return;
+        }
+        onPress?.({ left: event.clientX, top: event.clientY });
+      }
+    }
+  );
+});
+export {
+  StoryRow
+};

package/dist/ui/notes/noteBands.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The footnote band: what a page keeps room for at its foot, and what is drawn in that room and
+ * after the last page.
+ *
+ * A band is two halves that have to agree. The layout is told a name, a place at the foot, the
+ * height a page adds once for the band and the height of each thing kept in it (`page/demands`),
+ * and something has to draw exactly that much. Both halves live here so a page's room and the
+ * notes drawn in it cannot drift apart, and so the component that mounts the editor asks only for
+ * the bands a document keeps and renders what it is handed.
+ *
+ * A document referring to no footnote keeps no band at all, so it is laid out through the same
+ * pass it took before a page kept room for anything.
+ */
+import type { EditorState } from "prosemirror-state";
+import type { CSSProperties, ReactElement } from "react";
+import { type NoteRow } from "../../editor/commands/noteQueries";
+import type { DemandBand } from "../../page/demands";
+import type { PagePixels, TrailingRows } from "../../page/pageLayout";
+import type { PageOverlay } from "../../page/usePageLayout";
+import type { StoryKey } from "../../schema/stories";
+import { type FontFallbacks } from "../../styles/fontStack";
+import type { NoteHeightReport, RowEditing } from "./StoryRow";
+/** What a document's notes ask of the page layout, and what is needed to draw them */
+export interface NoteBands {
+    /**
+     * The bands to lay the pages out with, by name, or undefined where the document asks for no
+     * room at all. A new value lays the pages out again, so it changes only when a height does
+     */
+    readonly bands: ReadonlyMap<string, DemandBand> | undefined;
+    /**
+     * The endnotes as rows laid after the last block of the document, or undefined where it refers
+     * to none. A new value lays the pages out again, so it changes only when a height does
+     */
+    readonly trailing: TrailingRows | undefined;
+    /**
+     * Every note the document refers to, by story key, in first-reference order.
+     *
+     * Which one a caret stands in is the mounting component's to hold, so this is the one half of
+     * the notes it reads; everything else about how they are drawn stays in `drawn`.
+     */
+    readonly rows: ReadonlyMap<StoryKey, NoteRow>;
+    /** Held for `NotesAroundPage`; nothing else reads it */
+    readonly drawn: DrawnNotes;
+}
+/** What `NotesAroundPage` draws with, kept opaque so a caller cannot take the two halves apart */
+interface DrawnNotes {
+    /** The footnotes, which are the notes drawn at the foot of the page their reference stands on */
+    readonly footnotes: ReadonlyMap<StoryKey, NoteRow>;
+    readonly endnotes: readonly NoteRow[];
+    readonly anyNotes: boolean;
+    readonly heights: ReadonlyMap<StoryKey, number>;
+    readonly onHeight: NoteHeightReport;
+    readonly fontFallbacks: FontFallbacks;
+    readonly textStyle: CSSProperties;
+}
+export interface NoteBandsOptions {
+    /** The live document's state, or null before one is opened */
+    readonly state: EditorState | null;
+    /** A value that differs for every document opened, which the measured heights are held against */
+    readonly of: unknown;
+    readonly fontFallbacks: FontFallbacks | undefined;
+}
+export declare function useNoteBands({ state, of, fontFallbacks, }: NoteBandsOptions): NoteBands;
+export interface NotesAroundPageProps {
+    readonly notes: NoteBands;
+    /**
+     * Where the pages stand, or null while none are measured, which is what decides where the notes
+     * go: a page keeps room for them only once it has been laid out
+     */
+    readonly overlay: PageOverlay | null;
+    /** The paper the first section is drawn on, which the list under the sheet is as wide as */
+    readonly page: PagePixels;
+    readonly zoom: number;
+    /** The note the caret is in, which is the one row an editing view stands over */
+    readonly open?: StoryKey | null;
+    /** What mounts that view. Null while no note is open */
+    readonly editing?: RowEditing | null;
+    /** Whether the open note stands where nothing may be edited */
+    readonly readOnly?: boolean;
+    /** A value that differs every time the main document changes, which the open row syncs on */
+    readonly revision?: unknown;
+    /** Called for a press on a note no view stands over yet */
+    readonly onOpen?: (key: StoryKey, at: {
+        left: number;
+        top: number;
+    }) => void;
+    /** Called for a press on the number a note is drawn by, which is the way back to its reference */
+    readonly onReturn?: (key: StoryKey) => void;
+}
+/**
+ * The notes around the paper: each footnote over the room its page keeps, and the endnotes over
+ * the room kept after the last paragraph.
+ *
+ * Until a page has been measured there is no room to stand in - the guides may be off, or the
+ * first frame may not have been laid out yet - and a note drawn nowhere is a note a reader cannot
+ * read, so both kinds are listed under the sheet until there is. Only a note standing in its own
+ * room is edited in place.
+ */
+export declare function NotesAroundPage({ notes, overlay, page, zoom, open, editing, readOnly, revision, onOpen, onReturn, }: NotesAroundPageProps): ReactElement | null;
+export {};