Patterns / Suggest a change
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.
The components
- Selection actionsProThe toolbar over the person's selection in your document, with one action: Suggest a change (Pro).
- LocaleFreeA nested provider that renames the ask action inside the reader only.
- Prose diffProThe agent's proposal word by word against the passage, each change kept or rejected, nothing applied until decided (Pro).
- LockedFreeSave says why it can't be used until every change is decided.
See it working
The code
The reader: select a passage, Suggest a change, the proposal as a ProseDiff, and Save only once each change is decided.
"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>
)
}
Install
Each component brings in what it depends on. The free ones install as they are; Pro and Premium ones need a licence key.
Good to know
- 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
onRewriteandonKeep; use that when the change is made in place, without the chat.