# Suggest a change to a document through the agent

When a document changes only through an agent, so that every change is on the record, the person needs a way to point at a passage and ask. Selecting text is that way: no button on every paragraph, and the request quotes exactly what the person chose.

Put `SelectionActions` over the reader with `source`, a ref to the element holding the document, and `actions={["ask"]}`. Wrap it in a nested `LocaleProvider` that sets `selectionActions.ask` to "Suggest a change": the words change inside the reader only, and the rest of the app keeps Candor's. `onAction` gets the selected text: open your docked chat with it quoted.

The agent's proposal comes back as the passage before and after. Show it in a `ProseDiff`, where the person keeps or rejects each change, word by word. `onResolve` hands you the passage once every change is decided, and a Save button, locked until then with the reason, sends it. The document doesn't change until Save.

Web page: https://candor.themethodic.com/patterns/suggest-a-change

## Components

- **Selection actions** (`selection-actions`, Pro; https://candor.themethodic.com/docs/selection-actions.md): The toolbar over the person's selection in your document, with one action: Suggest a change (Pro).
- **Locale** (`locale`, free; https://candor.themethodic.com/docs/locale.md): A nested provider that renames the ask action inside the reader only.
- **Prose diff** (`prose-diff`, Pro; https://candor.themethodic.com/docs/prose-diff.md): The agent's proposal word by word against the passage, each change kept or rejected, nothing applied until decided (Pro).
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): Save says why it can't be used until every change is decided.

## Install

```bash
npx candor-ui@4 add selection-actions prose-diff locale locked
```

## Code

`document-reader.tsx`: The reader: select a passage, Suggest a change, the proposal as a ProseDiff, and Save only once each change is decided.

```tsx
"use client"

import * as React from "react"
import { LocaleProvider } from "@/components/candor/locale"
import { SelectionActions } from "@/components/candor/selection-actions"
import { ProseDiff } from "@/components/candor/prose-diff"
import { Locked } from "@/components/candor/locked"
import { Button } from "@/components/candor/ui/button"

/** The agent's proposal for one passage: the passage as it stands, and as the agent would write it. */
type Proposal = { original: string; revised: string }

export function DocumentReader({ text, onSuggest, onSave }: {
  /** The document, from your server. */
  text: string
  /** Opens your docked chat with the person's selection quoted; resolves with the agent's proposal. */
  onSuggest: (quote: string) => Promise<Proposal>
  /** Saves the passage as the person decided it. Your server refuses it if the passage has changed since. */
  onSave: (original: string, decided: string) => Promise<void>
}) {
  const reader = React.useRef<HTMLDivElement>(null)
  const [proposal, setProposal] = React.useState<Proposal | null>(null)
  // The passage once every change is kept or rejected. Nothing is saved until the person presses Save.
  const [decided, setDecided] = React.useState<string | null>(null)

  async function suggest(quote: string) {
    setDecided(null)
    setProposal(await onSuggest(quote))
  }

  async function save() {
    if (!proposal || decided === null) return
    await onSave(proposal.original, decided)
    setProposal(null)
  }

  return (
    <div className="flex flex-col gap-4">
      <div ref={reader} className="text-base leading-relaxed whitespace-pre-wrap">
        {text}
      </div>
      {/* Only here, the toolbar's ask action reads "Suggest a change"; elsewhere it keeps Candor's words. */}
      <LocaleProvider strings={{ selectionActions: { ask: "Suggest a change" } }}>
        <SelectionActions source={reader} actions={["ask"]} onAction={(_action, quote) => void suggest(quote)} />
      </LocaleProvider>
      {proposal && (
        <>
          <ProseDiff key={proposal.revised} original={proposal.original} revised={proposal.revised} onResolve={setDecided} />
          <div className="flex gap-2">
            <Locked reason={decided === null ? "Keep or reject each change first." : null}>
              <Button onClick={save}>Save the change</Button>
            </Locked>
            <Button variant="outline" onClick={() => setProposal(null)}>
              Discard
            </Button>
          </div>
        </>
      )}
    </div>
  )
}

```

## Notes

- The quote is the person's selection, drawn as text. Send it with your request so the agent works on what they chose, not on what it guesses they meant.
- Save the passage against the original your server sent, and refuse the save if the document has changed since: the person decided against that text.
- SelectionActions can also offer your own rewrites with `onRewrite` and `onKeep`; use that when the change is made in place, without the chat.
