@pretextbook/web-editor 0.4.3 → 0.5.1

package/dist/sectionUtils.d.ts

@@ -97,6 +97,13 @@ export declare function ensureLatexSectionWrapper(content: string, type: Documen
  * - For `\begin{section}` style: updates the `\title{…}` inside.
  */
 export declare function updateLatexSectionTitle(content: string, newTitle: string): string;
+/**
+ * Derive a LaTeX section's title directly from its header — the code
+ * editor's source-of-truth content — mirroring the two header styles
+ * {@link updateLatexSectionTitle} writes. Returns `null` when no header is
+ * found (introduction/conclusion have none), so callers leave title as-is.
+ */
+export declare function extractLatexDivisionTitle(content: string): string | null;
 /** Create a new blank LaTeX section as a `Division`. */
 export declare function createNewLatexSection(title?: string): DocumentSection;
 /** Create a blank LaTeX introduction. */
@@ -123,6 +130,22 @@ export declare function getSectionAttributes(content: string): {
     xmlId: string;
     label: string;
 };
+/**
+ * Derive a division's title, type, `xml:id`, and `label` directly from its
+ * full PreTeXt source — the code editor's content, wrapper tag included.
+ * Used to keep the TOC in sync when the user edits these directly in the
+ * source rather than through the metadata dropdown form.
+ *
+ * Returns `null` when `content` isn't well-formed XML or its root element
+ * isn't a recognised division tag (both common mid-edit), so callers can
+ * skip the update rather than clobbering existing metadata with junk.
+ */
+export declare function extractDivisionMetadata(content: string): {
+    title: string;
+    type: DivisionType;
+    xmlId: string;
+    label: string;
+} | null;
 /**
  * Update the title, tag name (type), `xml:id`, and `label` of a section.
  *
@@ -201,6 +224,26 @@ export declare function removeDivisionRef(content: string, xmlId: string): strin
  * - `afterXmlId` moves it immediately after that ref.
  */
 export declare function moveDivisionRef(content: string, xmlId: string, afterXmlId: string | null): string;
+/**
+ * Rename an existing `<plus:* ref="oldXmlId"/>` placeholder in-place to point
+ * at `newXmlId`, also updating the `*` tag name to `newType` if it changed.
+ * Unlike {@link moveDivisionRef}, the placeholder's position is left
+ * untouched — only its `ref` value and element name are rewritten.
+ *
+ * Used to keep a parent division's child placeholder in sync when the
+ * child's own `xml:id`/type are edited directly in its source, so the
+ * rename doesn't orphan the child from its parent.
+ *
+ * Returns `content` unchanged if no placeholder for `oldXmlId` is found.
+ */
+export declare function renameDivisionRef(content: string, oldXmlId: string, newXmlId: string, newType: DivisionType): string;
+/**
+ * Find the division in `divisions` whose content contains a
+ * `<plus:* ref="xmlId"/>` placeholder for `xmlId` — i.e. `xmlId`'s parent in
+ * the division tree.  Returns `null` if `xmlId` is unplaced (orphaned) or is
+ * the root.
+ */
+export declare function findDivisionParent(divisions: Division[], xmlId: string): Division | null;
 /**
  * Rewrite `content` so its `<plus:* ref="..."/>` placeholders appear in the
  * order given by `orderedXmlIds`.
@@ -270,15 +313,23 @@ export declare function assembleProjectSource(divisions: Division[], rootXmlId:
  * `<section xml:id="...">...</section>`) into a standalone PreTeXt fragment
  * document suitable for a build-server preview of just that division.
  *
- * Unlike {@link assembleProjectSource}, this never expands `<plus:* ref="..."/>`
- * placeholders — they are left as-is for the build server to handle when
- * rendering a fragment preview.
+ * This function itself never expands `<plus:* ref="..."/>` placeholders —
+ * the real build server has no notion of that placeholder syntax, so callers
+ * must resolve them first (e.g. via {@link assembleProjectSource}) before
+ * passing `divisionXml` in. Passing unresolved refs produces invalid PreTeXt
+ * and a build failure.
  *
  * `divisionType` determines the minimal wrapper needed around `divisionXml`:
  * root types (`book`/`article`/`slideshow`) need none, `chapter`/`part` are
  * wrapped in a bare `<book>`, and everything else in a bare `<article>`.
+ * The PreTeXt schema requires `<book>`/`<article>` to have a `<title>` as
+ * their first child, so a wrapper built here uses `wrapperTitle` for that —
+ * without it the build server's schema validation rejects the document,
+ * produces no output, and 500s.
  * `docinfo` (the full `<docinfo>...</docinfo>` element, or `""`) is inserted
  * as a sibling of the root element inside `<pretext>`, matching real PreTeXt
  * document shape.
+ *
+ * We need to add `label="preview"` (or really any label) since if this isn't present the build server won't know what file to return.
  */
-export declare function wrapDivisionForPreview(divisionType: DivisionType, divisionXml: string, docinfo: string): string;
+export declare function wrapDivisionForPreview(divisionType: DivisionType, divisionXml: string, docinfo: string, wrapperTitle: string): string;

package/dist/store/editorStore.d.ts

@@ -1,12 +1,24 @@
 /**
  * Per-instance Zustand store for the Editors component.
  *
- * ARCHITECTURE NOTE — host data always wins:
- * Editors.tsx syncs all controlled props into the store on every render via
- * syncState(). This means when the host pushes fresh `divisions` (e.g. after a
- * refetchOnWindowFocus), every deep component automatically re-renders with the
- * new data. Never let store mutations "win" over incoming props — always call
- * the host callbacks and let the host's state update propagate back in.
+ * ARCHITECTURE NOTE — the store owns the live editing buffer:
+ * `createEditorStore(init)` seeds the editing buffer (`divisions`, `title`,
+ * `docinfo`, `activeDivisionId`, …) from the host's initial props *once*.
+ * After that, the store is authoritative for what's being edited:
+ *   • Internal edit actions (`setDivisionContent`, `patchDivision`, `setTitle`,
+ *     …) update the store optimistically and the host callbacks are fired
+ *     purely as notifications (so the host can persist/autosave).  A host is no
+ *     longer required to echo every edit back as new props for it to display.
+ *   • Genuine external updates (a save that reconciles server-assigned ids, or
+ *     swapping to a different project) still win: Editors.tsx detects when a
+ *     controlled prop actually changes since the last render and calls
+ *     `applyExternalUpdate()` to overwrite the buffer.  A stale prop that the
+ *     host simply never updated is NOT re-applied, so it can't clobber a local
+ *     edit.
+ *
+ * Derived/config fields that are never edited locally (`source`, `sourceFormat`,
+ * `projectAssets`, `projectType`, `rootDivisionId`, …) are still mirrored from
+ * props every render via `syncState()`.
  *
  * Callback stability: createEditorStore returns a `bindCallbacks` function that
  * EditorsInner calls from useLayoutEffect after every render. Store actions
@@ -24,6 +36,20 @@ export type DivisionChanges = {
     sourceFormat?: SourceFormat;
     label?: string | null;
 };
+/**
+ * A batch of editing-buffer fields the host has genuinely changed (an external
+ * reset).  Only the provided fields are overwritten in the store; omitted
+ * fields keep their current — possibly locally edited — value.
+ */
+export interface ExternalUpdate {
+    divisions?: Division[];
+    rootDivisionId?: string;
+    activeDivisionId?: string | null;
+    title?: string;
+    docinfo?: string;
+    commonDocinfo?: string;
+    useCommonDocinfo?: boolean;
+}
 type ModalKey = "isLatexDialogOpen" | "isConvertDialogOpen" | "isDocinfoEditorOpen" | "isAssetPickerOpen";
 /**
  * All callbacks wired by Editors.tsx that deep components need to call.
@@ -71,21 +97,36 @@ export interface EditorStoreState {
     isConvertDialogOpen: boolean;
     isDocinfoEditorOpen: boolean;
     isAssetPickerOpen: boolean;
-    internalTitle: string;
-    internalDocinfo: string;
-    internalCommonDocinfo: string;
-    internalUseCommonDocinfo: boolean;
     editingId: string | null;
     editDraft: EditDraft | null;
     /** Sync a batch of derived/controlled data from Editors into the store. */
     syncState: (partial: Partial<EditorSyncableState>) => void;
+    /** Apply a genuine external update from the host (host wins). */
+    applyExternalUpdate: (partial: ExternalUpdate) => void;
+    /** Optimistically set a division's content in the local pool. */
+    setDivisionContent: (xmlId: string, content: string) => void;
+    /** Optimistically patch a division's metadata (title/type/xml:id/format). */
+    patchDivision: (xmlId: string, changes: DivisionChanges) => void;
+    /** Optimistically add a division to the local pool (no-op if it exists). */
+    addDivisionToPool: (division: Division) => void;
+    /** Optimistically remove a division from the local pool. */
+    removeDivisionFromPool: (xmlId: string) => void;
+    /** Set the active (open-for-editing) division id. */
+    setActiveDivisionId: (id: string | null) => void;
+    /** Optimistically set the document title. */
+    setTitle: (title: string) => void;
+    /** Optimistically set the docinfo-related fields together. */
+    setDocinfo: (info: {
+        docinfo: string;
+        commonDocinfo: string;
+        useCommonDocinfo: boolean;
+    }) => void;
     setShowFullPreview: (show: boolean) => void;
     setActiveTab: (tab: "editor" | "preview") => void;
     setIsNarrowScreen: (narrow: boolean) => void;
     setIsTocCollapsed: (value: boolean | ((prev: boolean) => boolean)) => void;
     openModal: (modal: ModalKey) => void;
     closeModal: (modal: ModalKey) => void;
-    setInternalTitle: (title: string) => void;
     selectSection: (id: string) => void;
     addSection: (afterId: string | null) => void;
     removeSection: (id: string) => void;
@@ -102,7 +143,7 @@ export interface EditorStoreState {
     feedbackSubmit: (feedback: FeedbackSubmission) => void;
 }
 /** The subset of EditorStoreState that Editors.tsx syncs on each render. */
-export type EditorSyncableState = Pick<EditorStoreState, "source" | "sourceFormat" | "projectAssets" | "libraryAssets" | "title" | "docinfo" | "commonDocinfo" | "useCommonDocinfo" | "projectType" | "projectUrl" | "divisions" | "rootDivisionId" | "activeDivisionId" | "canConvertToPretext" | "activeEditorSource" | "hasFeedback" | "internalDocinfo" | "internalCommonDocinfo" | "internalUseCommonDocinfo">;
+export type EditorSyncableState = Pick<EditorStoreState, "source" | "sourceFormat" | "projectAssets" | "libraryAssets" | "title" | "docinfo" | "commonDocinfo" | "useCommonDocinfo" | "projectType" | "projectUrl" | "divisions" | "rootDivisionId" | "activeDivisionId" | "canConvertToPretext" | "activeEditorSource" | "hasFeedback">;
 export interface EditorStoreInit {
     source: string;
     sourceFormat: SourceFormat;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/web-editor",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "private": false,
   "description": "A web-based editor for PreTeXt documents, with simple preview functionality",
   "keywords": [