@docx-editor.dev/react 2.35.0-canary.20261104032723.sha-43c2012 → 2.35.0

package/docs/accept-reject-without-scrolling.md

@@ -2,44 +2,37 @@
 
 # Accept or reject without scrolling
 
-When your own list drives the scroll, open an item with `useReview().setActive(key, { reveal: false })`. The caret moves to the item, and the page stays where it is. Then resolve the item with `accept(item)` or `reject(item)`. Review writes such as accept, reject, and comment never scroll the page.
+Resolve a tracked change from your own list with `useReview().accept(item)` or `reject(item)`. Review writes such as accept, reject, and comment never scroll the page, and they need no prior activation.
+
+## Resolve a change without scrolling
+
+The following row opens its item without scrolling and resolves it from two buttons:
 
 ```tsx
 import { useReview, type ReviewItemView } from '@docx-editor.dev/pro/react';
 
 export function ChangeRow({ item }: { item: ReviewItemView }) {
-  const { setActive, accept, reject } = useReview();
+  const { setActive, accept, reject, lastRefusal } = useReview();
   return (
-    <li onClick={() => setActive(item.key, { reveal: false })}>
-      {item.text}
-      <button
-        disabled={item.readOnly}
-        onClick={(event) => {
-          event.stopPropagation();
-          accept(item);
-        }}
-      >
+    <li>
+      <button onClick={() => setActive(item.key, { reveal: false })}>{item.text}</button>
+      <button disabled={item.readOnly} onClick={() => accept(item)}>
         Accept
       </button>
-      <button
-        disabled={item.readOnly}
-        onClick={(event) => {
-          event.stopPropagation();
-          reject(item);
-        }}
-      >
+      <button disabled={item.readOnly} onClick={() => reject(item)}>
         Reject
       </button>
+      {lastRefusal?.key === item.key && <p role="alert">{lastRefusal.code}</p>}
     </li>
   );
 }
 ```
 
-`accept` and `reject` return `false` when the editor refuses the decision, for example in viewing mode. Read `useReview().lastRefusal` for the diagnostic code.
+`accept` and `reject` return `false` when the editor refuses the decision, for example in viewing mode. `lastRefusal` holds the item key and the diagnostic code. In Vue it is a ref, so read `lastRefusal.value?.code` in script.
 
-The buttons stop the click from reaching the row, so a decision does not also activate the item.
+## Activate without scrolling
 
-`reveal` takes `false` or one of four placements:
+`setActive(key, { reveal: false })` moves the caret to the item and keeps the scroll position. `reveal` takes `false` or one of four placements:
 
 | Value | Where the item lands |
 | --- | --- |
@@ -50,23 +43,14 @@ The buttons stop the click from reaching the row, so a decision does not also ac
 
 Add `announce: true` to open the packaged balloon or card for the item.
 
-## Decide in a headless pipeline
+## Limits
 
-The editing API has no viewport. Load the revisions and call `Revision.accept()` or `Revision.reject()`.
+- Disable the decision buttons for items where `item.readOnly` is `true`.
+- If the whole row is clickable, stop button clicks from reaching it, so a decision does not also activate the item.
+- Headless pipelines have no viewport. To decide changes on a server, call `Revision.accept()` or `Revision.reject()`. For more information, see [Tracked changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions).
 
-```ts
-import { DocxEditor } from '@docx-editor.dev/editor-api';
+## See also
 
-const runtime = await DocxEditor.createServer(bytes, { author: 'Review bot' });
-await runtime.run(async (context) => {
-  const revisions = context.document.body.revisions;
-  revisions.load('items/author');
-  await context.sync();
-  for (const revision of revisions.items) {
-    if (revision.author === 'Review bot') revision.accept();
-  }
-  await context.sync();
-});
-const saved = await runtime.save();
-runtime.dispose();
-```
+- [Tracked changes](https://www.docx-editor.dev/docs/2.x/pro/tracked-changes)
+- [Diagnostics](https://www.docx-editor.dev/docs/2.x/guides/diagnostics)
+- [Custom cards in the review rail](./custom-review-cards.md)

package/docs/comment-on-found-text.md

@@ -2,46 +2,65 @@
 
 # Comment on found text
 
-In a browser host, find the text with `editor.findMatches`, select the first match with `editor.selectMatch`, and then call `useReview().comment`. The comment is written as the editor's `author`, so set `author` on the editor and add `reviewModule()` to its modules. `selectMatch` opens the header, footer, or note that holds the match, so a match in any story works.
+Find text with `editor.findMatches`, select a match with `editor.selectMatch`, and comment with `useReview().comment`. On a server, search with `body.search` and call `Range.insertComment`.
+
+## Comment on a search result
+
+The following button comments on the first whole-word match of a term. The editor needs an `author` and `reviewModule()` in its modules.
 
 ```tsx
+import { useState } from 'react';
 import { useDocxEditor } from '@docx-editor.dev/react';
 import { useReview } from '@docx-editor.dev/pro/react';
 
 export function CommentOnTerm({ term }: { term: string }) {
   const editor = useDocxEditor();
-  const { comment } = useReview();
+  const { comment, lastRefusal } = useReview();
+  const [status, setStatus] = useState('');
   const run = () => {
     const [match] = editor?.findMatches(term, { wholeWord: true }) ?? [];
-    if (match && editor?.selectMatch(match).ok) comment(`Define "${term}".`);
+    if (!match || !editor?.selectMatch(match).ok) return setStatus('No match');
+    setStatus(comment(`Define "${term}".`) ? '' : 'Refused');
   };
-  return <button onClick={run}>Comment on {term}</button>;
+  return (
+    <>
+      <button onClick={run}>Comment on {term}</button>
+      {/* lastRefusal updates on the next render, so read it here. */}
+      <span role="status">{status === 'Refused' ? lastRefusal?.code : status}</span>
+    </>
+  );
 }
 ```
 
-`comment` returns `false` when the editor refuses the write. Read `useReview().lastRefusal` for the diagnostic code.
+Comment only after `selectMatch(match).ok` is `true`. `selectMatch` opens the header, footer, or note that holds the match. `comment` returns `false` when the editor refuses the write, and `lastRefusal` holds the diagnostic code.
 
-## Comment in a headless pipeline
+## Comment on a server
 
-On a server or in an agent pipeline, search the body and call `Range.insertComment`. The runtime writes the comment as its `author` option.
+The following example searches the body, not every story, and saves the result:
 
 ```ts
 import { DocxEditor } from '@docx-editor.dev/editor-api';
 
 const runtime = await DocxEditor.createServer(bytes, { author: 'Review bot' });
-await runtime.run(async (context) => {
-  const found = context.document.body.search(term, { matchWholeWord: true });
-  found.load('items');
-  await context.sync();
-  found.items[0]?.insertComment(`Define "${term}".`);
-  await context.sync();
-});
-const saved = await runtime.save();
-runtime.dispose();
+try {
+  await runtime.run(async (context) => {
+    const found = context.document.body.search(term, { matchWholeWord: true });
+    found.load('items');
+    await context.sync();
+    if (found.items.length === 0) return;
+    found.items[0]!.insertComment(`Define "${term}".`);
+    await context.sync();
+  });
+  const saved = await runtime.save();
+} finally {
+  runtime.dispose();
+}
 ```
 
-Both paths save the same comment markup: the same `w:comment` attributes, the same date format, and the same range markers.
+Load the search results before you read them, and end with `await context.sync()` to send the queued comment. The runtime writes the comment as its `author` option.
 
-## Reply to a thread
+## See also
 
-To answer an existing comment, call `useReview().reply(item, text)` in a browser host, or `Comment.reply(text)` in the editing API.
+- [Comments](https://www.docx-editor.dev/docs/2.x/pro/comments)
+- [Diagnostics](https://www.docx-editor.dev/docs/2.x/guides/diagnostics)
+- [Replace as a tracked change](./tracked-replacement.md)

package/docs/custom-review-cards.md

@@ -2,9 +2,11 @@
 
 # Custom cards in the review rail
 
-To draw your own cards, render `DocxEditorReview` with `preset` set to `false` and put your card component inside it. Your component reads the items from `useReview()`, measures each card, stacks the cards with `useStackedReviewPositions`, and converts positions to pixels with `useReviewRailMetrics()`.
+Render `DocxEditorReview` with `preset` set to `false` and put your card component inside it. The component reads items from `useReview()`, stacks measured cards with `useStackedReviewPositions`, and converts positions to pixels with `useReviewRailMetrics()`.
 
-Measure every card with a `ResizeObserver` and pass the heights in CSS pixels. Without measured heights, each card reserves only `defaultHeight`, and a taller card overlaps the next one.
+## Render custom cards
+
+The following example measures each card with a `ResizeObserver`, stacks the cards, and shows a refused decision:
 
 ```tsx
 import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
@@ -17,17 +19,8 @@ import {
 
 type OnHeight = (key: string, height: number) => void;
 
-function MeasuredCard({
-  id,
-  top,
-  onHeight,
-  children,
-}: {
-  id: string;
-  top: number;
-  onHeight: OnHeight;
-  children: ReactNode;
-}) {
+function MeasuredCard(props: { id: string; top: number; onHeight: OnHeight; children: ReactNode }) {
+  const { id, top, onHeight, children } = props;
   const ref = useRef<HTMLDivElement>(null);
   useEffect(() => {
     const node = ref.current!;
@@ -43,8 +36,9 @@ function MeasuredCard({
 }
 
 function MyCards() {
-  const { items, selectionAnchorY, accept } = useReview();
+  const { items, selectionAnchorY, accept, lastRefusal } = useReview();
   const metrics = useReviewRailMetrics();
+  // A new map only when a height changes, so the stack recomputes only then.
   const [heights, setHeights] = useState<ReadonlyMap<string, number>>(() => new Map());
   const onHeight = useCallback<OnHeight>(
     (key, height) =>
@@ -67,6 +61,7 @@ function MyCards() {
         >
           {item.text}
           {item.kind === 'revision' && <button onClick={() => accept(item)}>Accept</button>}
+          {lastRefusal?.key === item.key && <p>{lastRefusal.code}</p>}
         </MeasuredCard>
       ))}
       <DocxEditorReview.Draft top={top(selectionAnchorY ?? 0)} />
@@ -84,22 +79,41 @@ export function MyRail() {
 }
 ```
 
-The heights map gets a new reference only when a height changes, so the stack recomputes only then. Keep that rule if you store heights another way.
+`accept` returns `false` when the editor refuses, and `lastRefusal` names the item and the diagnostic code. `DocxEditorReview` already announces each refusal in a live region, so show it in the card as plain text. For a translated sentence, call `useReviewRefusalMessage()`.
+
+## Position cards and drafts
+
+Convert a layout position to CSS pixels with `metrics.top + position * metrics.scale`.
+
+| Input to `useStackedReviewPositions` | Description |
+| --- | --- |
+| `heights` | Measured card heights in CSS pixels, by item key. A card without a height reserves `defaultHeight`, and a taller card overlaps the next one. |
+| `scale` | `metrics.scale`, CSS pixels per layout point. |
+| `defaultHeight` | The height to reserve before a card is measured. |
+
+`DocxEditorReview.Draft` renders only while a comment draft is open. Without `top`, it takes the packaged stack's position, so pass `top` from your own stack. To keep the box clear of your cards, add an entry at `selectionAnchorY` to the list that you stack, in document order.
 
-## Root parts and card parts
+## Place review parts
 
-`DocxEditorReview` finds its parts among its own children by element type.
+`DocxEditorReview` finds its parts among its own children by element type. Fragments are transparent in React and Vue.
 
-- **Root parts** are `List`, `Markers`, `AddComment`, `Draft`, and `Balloon`. Put them as direct children of `DocxEditorReview`. Fragments are transparent in React and in Vue. The rail gives these parts geometry that only it can compute, such as the comment button's `top`. A root part inside your own wrapper component is not a part. It renders as ordinary content, without that wiring.
-- **Card parts** are `Card`, `Empty`, and the parts inside a card, such as `Author`, `Summary`, `Accept`, and `Reply`. Put them inside `DocxEditorReview.List`.
+| Part | Placement |
+| --- | --- |
+| `List`, `Markers`, `AddComment`, `Balloon` | Direct children of `DocxEditorReview`. Inside your own wrapper, a part renders as plain content without its geometry. |
+| `Draft` | A direct child, or inside your own card component. Inside a custom stack, pass `top` explicitly. |
+| `Card`, `Empty`, and card parts such as `Author`, `Summary`, `Accept`, and `Reply` | Inside `DocxEditorReview.List`. |
 
-With `preset` set to `false`, the rail adds no defaults. Root parts that you pass keep their wiring. Every other child renders as is inside the rail element, where `useReviewRailMetrics()` reads the rail's own measurement.
+With `preset` set to `false`, the rail adds no defaults, but recognized parts keep their wiring. Other children render inside the rail element.
 
-## Position the compose box
+## Limits
 
-`DocxEditorReview.Draft` renders only while a comment draft is open. A draft opens from `DocxEditorReview.AddComment` or from the `review.addComment` toolbar control. You can place `Draft` in either of these places:
+- Disconnect each observer when its card unmounts or its item changes.
+- In React, keep the heights map reference-stable. In Vue, keep it reactive.
+- In the compact rail, `metrics.compact` is `true`. Place cards at `metrics.compactCardLeft`; `Draft` does this itself.
+- Keep the column hidden while `metrics.left` is `null`.
 
-- As a direct child of `DocxEditorReview`.
-- Inside your own card component, as in the example. It still renders only while the draft is open.
+## See also
 
-Without `top`, the box sits where the packaged card stack puts it. That position comes from the packaged cards, not yours, so when you render your own cards, pass `top` from your own stack. In the narrow compact rail, the box takes the compact card's `left` in both cases, so it does not overflow the marker strip. The example places the box at the selection's anchor. To keep it clear of your cards, add an entry with the key of your choice and the anchor `selectionAnchorY` to the list that you pass to `useStackedReviewPositions`, in document order.
+- [Review cards](https://www.docx-editor.dev/docs/2.x/customization/review-cards)
+- [Tracked changes](https://www.docx-editor.dev/docs/2.x/pro/tracked-changes)
+- [Accept or reject without scrolling](./accept-reject-without-scrolling.md)

package/docs/highlight-ranges.md

@@ -2,13 +2,18 @@
 
 # Highlight ranges
 
-Use `useHighlights(name, source, options)` to mark text as a named set while a component is mounted. A function source runs again after document changes, so the marks follow the text. Highlights are view state. They do not change the document and are not saved.
+Call `useHighlights(name, source, options)` to mark text as a named set while a component is mounted. Highlights are local view state. They do not change the document and are not saved.
+
+## Highlight matching text
+
+The following component marks each whole-word match of a list of terms. Style the `glossary-term` class with your own CSS, or omit `className` for the default fill.
 
 ```tsx
 import { useCallback } from 'react';
 import { useHighlights, type Editor } from '@docx-editor.dev/react';
 
 export function GlossaryMarks({ terms }: { terms: readonly string[] }) {
+  // A stable function source, so the set refreshes only when `terms` changes.
   const findTerms = useCallback(
     (editor: Editor) => editor.findMatches(terms, { wholeWord: true }).flat(),
     [terms]
@@ -18,8 +23,24 @@ export function GlossaryMarks({ terms }: { terms: readonly string[] }) {
 }
 ```
 
-Keep a function source stable with `useCallback`.
+A function source runs again after each document change, so the marks follow the text. The set is removed when the component unmounts.
+
+## Configure a highlight set
+
+| Argument or field | Description |
+| --- | --- |
+| `name` | The set name. Two sets with the same name replace each other's ranges. |
+| `source` | The ranges, or a function of the editor that returns them. |
+| `options.className` | CSS classes added to every mark of the set. |
+| `options.activeIndex` | The range to show in the active color, such as the current result of your own search list. |
+| `applied` | The number of ranges that resolve and paint. |
+
+## Use highlights outside components
+
+Call `watchHighlights(editor, name, source, options)` from `@docx-editor.dev/core/editor` to follow document changes. Call `stop()` on the returned watch to remove the set and stop watching. For a fixed set that does not refresh, call `editor.setHighlights`.
 
-Use a unique `name` for each set. Two calls with the same name replace each other's ranges. Set `activeIndex` in the options to show one range in the active color, for example the current result of your own search list.
+## See also
 
-Outside a component, call `watchHighlights(editor, name, source, options)` from `@docx-editor.dev/core/editor`, or `editor.setHighlights` for a fixed set.
+- [Highlight text ranges](https://www.docx-editor.dev/docs/2.x/guides/navigation#highlight-text-ranges)
+- [React hooks](https://www.docx-editor.dev/docs/2.x/react/hooks#usehighlights)
+- [Vue composables](https://www.docx-editor.dev/docs/2.x/vue/composables#usehighlights)

package/docs/index.md

@@ -1,36 +1,36 @@
 <!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
 
-# Which API for which job
+# Task recipes
 
-The library has two ways to change a document. Each one fits a different host. Choose the path first, then use the symbol for your task.
+Each recipe solves one task with a complete code sample. Choose the API first, then find the symbol for your task.
 
-| Job | Use |
-| --- | --- |
-| Build a review UI in the browser | The React or Vue adapter hooks, plus the review hooks and `DocxEditorReview` from `@docx-editor.dev/pro/react` or `@docx-editor.dev/pro/vue`. |
-| Edit in a headless, server, or agent pipeline | The editing API in `@docx-editor.dev/editor-api`, which follows the Office.js object model. |
+## Which API for which job
 
-| Task | Browser host (React or Vue) | Headless, server, or agent |
+Use the React or Vue adapter hooks, the review hooks, and `DocxEditorReview` from `@docx-editor.dev/pro/react` or `@docx-editor.dev/pro/vue` to build browser review controls. Use the editing API in `@docx-editor.dev/editor-api` for document automation. It follows the Office.js object model and runs in browser and server hosts.
+
+| Task | Browser controls (React or Vue) | Document automation |
 | --- | --- | --- |
 | [Comment on found text](./comment-on-found-text.md) | `editor.findMatches`, `editor.selectMatch`, then `useReview().comment` | `body.search`, then `Range.insertComment` |
-| Reply to a thread | `useReview().reply(item, text)` | `Comment.reply(text)` |
+| [Reply to a thread](https://www.docx-editor.dev/docs/2.x/pro/comments) | `useReview().reply(item, text)` | `Comment.reply(text)` |
 | [Record a tracked replacement](./tracked-replacement.md) | Suggesting mode, then `editor.exec({ type: 'replaceMatch', match, text })` | `document.changeTrackingMode = 'TrackMineOnly'`, then `Range.insertText(text, 'Replace')` |
-| [Propose an AI rewrite as tracked changes](./propose-rewrite.md) | The same code through `DocxEditor.createBrowser` from `@docx-editor.dev/editor-api/browser` | `prepareRewrite` from `@docx-editor.dev/editor-api/agent` |
+| [Propose an AI rewrite as tracked changes](./propose-rewrite.md) | `prepareRewrite` through `DocxEditor.createBrowser` | `prepareRewrite` from `@docx-editor.dev/editor-api/agent` |
 | [Accept or reject a change](./accept-reject-without-scrolling.md) | `useReview().accept(item)` or `useReview().reject(item)` | `Revision.accept()` or `Revision.reject()` |
-| [Open or reveal a change without scrolling](./accept-reject-without-scrolling.md) | `useReview().setActive(key, { reveal: false })` | Not applicable: no viewport |
+| [Open a change without scrolling](./accept-reject-without-scrolling.md) | `useReview().setActive(key, { reveal: false })` | Not applicable: no viewport |
 | [Highlight ranges](./highlight-ranges.md) | `useHighlights(name, source, options)` | Not applicable |
-| [Custom review rail cards](./custom-review-cards.md) | `DocxEditorReview` with `preset` set to `false`, `useReview().items`, `useStackedReviewPositions`, and `useReviewRailMetrics` | Not applicable |
+| [Custom review rail cards](./custom-review-cards.md) | `DocxEditorReview` with `preset` set to `false`, `useStackedReviewPositions`, and `useReviewRailMetrics` | Not applicable |
 | Comment-on-selection button | `DocxEditorReview.AddComment` as a direct child of `DocxEditorReview`, or `useEditorCommand('review.addComment')` | Not applicable |
-| Page setup and paragraph dialogs from a custom toolbar | `DocxEditor.PageSetupDialog` or `DocxEditor.ParagraphDialog` with `open` and a close handler (`onClose` in React, `@close` in Vue); enable the button from `usePageSetup().isEnabled` or `useParagraphFormat().isEnabled` | `Section.pageSetup`, and `Paragraph` properties such as `alignment` |
+| [Page setup and paragraph dialogs](https://www.docx-editor.dev/docs/2.x/customization/dialogs) | `DocxEditor.PageSetupDialog` or `DocxEditor.ParagraphDialog` | `Section.pageSetup`, and `Paragraph` properties such as `alignment` |
 
-The review hooks need `reviewModule()` from `@docx-editor.dev/pro` in the editor's modules, and an editor `author` for comments and tracked changes. The editing API takes its author from the `author` option of `DocxEditor.createServer`, imported from `@docx-editor.dev/editor-api`, or of `DocxEditor.createBrowser`, imported from `@docx-editor.dev/editor-api/browser`.
+## Check prerequisites
 
-## Recipes
+- The review hooks need `reviewModule()` from `@docx-editor.dev/pro` in the editor's modules.
+- Comments and tracked changes need an author: the editor's `author` prop, or the runtime's `author` option.
+- Create a server runtime with `DocxEditor.createServer` from `@docx-editor.dev/editor-api`. Create a browser runtime with `DocxEditor.createBrowser` from `@docx-editor.dev/editor-api/browser`.
+- Review controls stay separate from the Office.js-shaped document model.
+- `@docx-editor.dev/pro` and `@docx-editor.dev/editor-api` require the EigenPal Pro License. For more information, see [Pro features](https://www.docx-editor.dev/docs/2.x/pro).
 
-- [Comment on found text](./comment-on-found-text.md)
-- [Replace as a tracked change](./tracked-replacement.md)
-- [Propose an AI rewrite as tracked changes](./propose-rewrite.md)
-- [Custom cards in the review rail](./custom-review-cards.md)
-- [Highlight ranges](./highlight-ranges.md)
-- [Accept or reject without scrolling](./accept-reject-without-scrolling.md)
+## See also
 
-For the full hook reference, see [React hooks](https://www.docx-editor.dev/docs/2.x/react/hooks) and [Vue composables](https://www.docx-editor.dev/docs/2.x/vue/composables). For the editing API, see [Editing API](https://www.docx-editor.dev/docs/2.x/editor-api).
+- [React hooks](https://www.docx-editor.dev/docs/2.x/react/hooks)
+- [Vue composables](https://www.docx-editor.dev/docs/2.x/vue/composables)
+- [Editing API](https://www.docx-editor.dev/docs/2.x/editor-api)