@stll/folio-core 0.52.0 → 0.53.0

package/README.md

@@ -168,6 +168,29 @@ can be enumerated, accepted, or rejected before saving. `getChanges()` includes
 inline edits, formatting, paragraph marks, and paragraph, section, table, row,
 and cell property changes.
 
+### Pending suggestions
+
+Apply operations in `"suggested"` mode to show proposed edits without writing
+them into the DOCX. Persist `reviewer.exportPendingSuggestions()` in a host store
+as JSON alongside the document. After reopening the saved DOCX, call
+`reopened.loadPendingSuggestions(records)` to revalidate and restage them:
+
+```ts
+import { FolioDocxReviewer } from "@stll/folio-core/server";
+import type { FolioPendingSuggestionRecord } from "@stll/folio-core/ai-edits";
+
+const records: FolioPendingSuggestionRecord[] = reviewer.exportPendingSuggestions();
+await saveRecords(records);
+const reopened = await FolioDocxReviewer.fromBuffer(savedDocx, { author: "Reviewer" });
+const results = reopened.loadPendingSuggestions(await loadRecords());
+```
+
+Each result is `restaged` or `stale` with a reason. A stale record leaves the
+document untouched; the host should keep it for review. The host must scope
+stored records to its document identity and authorized owner before loading them.
+`acceptAll()` resolves ordinary tracked changes and leaves suggestions pending. Use
+`acceptSuggestion(suggestionId)` to commit one explicitly.
+
 ## License
 
 [Apache-2.0](./LICENSE)

package/dist/ai-edits/apply.d.ts

@@ -1,6 +1,7 @@
 import { FolioTableTemplates } from "./table-template.js";
 import { FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
 import { WordDiffGranularity } from "./word-diff.js";
+import { Node } from "prosemirror-model";
 import { EditorState, Transaction } from "prosemirror-state";
 //#region src/ai-edits/apply.d.ts
 /**
@@ -59,6 +60,8 @@ type ApplyFolioAIEditOperationsOptions = {
   tableTemplates?: FolioTableTemplates;
   /** What a replacement does with a background the text it replaces carries. */
   replacementBackground?: FolioReplacementBackground;
+  /** What an operation naming a paragraph style the document does not define does. */
+  undefinedStyles?: FolioUndefinedStylePolicy;
 };
 /**
  * How an apply batch cuts the redline for a replacement. Word-level by
@@ -84,6 +87,18 @@ type FolioWordDiffOptions = {
  * same.
  */
 type FolioReplacementBackground = "clear" | "keep";
+/**
+ * What an operation naming a paragraph style the document does not define —
+ * no `w:style` with that id, or one of another type — does.
+ *
+ * `refuse` is the default: such a `w:pStyle` confers no formatting, so the
+ * paragraph would keep its body look while the operation reported a restyle;
+ * the operation is skipped with `missingStyle`. `keep` is for a caller that
+ * copies references another document already holds — a comparison or redline
+ * reproducing the revised document, which may itself reference a style it
+ * never defines — and writes them as given.
+ */
+type FolioUndefinedStylePolicy = "refuse" | "keep";
 /**
  * An apply result plus where the batch left the revision-id counter.
  *
@@ -103,5 +118,15 @@ type FolioAIEditApplyOutcome = FolioAIEditApplyResult & {
 };
 declare const applyFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyOutcome;
 declare const previewFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyOutcome;
+/**
+ * A preview together with the document it would leave and the provisional
+ * comment ids it placed, for a caller that checks the result before reporting
+ * it. Internal: not re-exported from the package entry points.
+ */
+declare const previewFolioAIEditOperationsWithResult: (options: ApplyFolioAIEditOperationsOptions) => {
+  outcome: FolioAIEditApplyOutcome;
+  doc: Node;
+  commentIds: readonly number[];
+};
 //#endregion
-export { FolioAIEditApplyOutcome, FolioAIEditView, FolioReplacementBackground, FolioRevisionStamp, FolioWordDiffOptions, applyFolioAIEditOperations, previewFolioAIEditOperations };
+export { FolioAIEditApplyOutcome, FolioAIEditView, FolioReplacementBackground, FolioRevisionStamp, FolioUndefinedStylePolicy, FolioWordDiffOptions, applyFolioAIEditOperations, previewFolioAIEditOperations, previewFolioAIEditOperationsWithResult };