From 92a8266cab39534bab168380d39b606bf403edd2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 16:45:56 +0000 Subject: [PATCH 1/2] docs: update Suggestions for v6.0.0-beta.13 (autoCommit, summaryHtml, rename) --- api-reference/sdk/models/data-models.mdx | 31 +- async-collaboration/suggestions/overview.mdx | 76 ++++- release-notes/version-6/sdk-changelog.mdx | 30 ++ .../comments/comment-dialog-structure.mdx | 12 +- .../comments/comment-dialog/primitives.mdx | 322 +++++++++--------- .../comment-dialog/wireframe-variables.mdx | 20 +- .../comments/comment-dialog/wireframes.mdx | 304 ++++++++--------- 7 files changed, 447 insertions(+), 348 deletions(-) diff --git a/api-reference/sdk/models/data-models.mdx b/api-reference/sdk/models/data-models.mdx index 0bbbd66e1..a75e92d94 100644 --- a/api-reference/sdk/models/data-models.mdx +++ b/api-reference/sdk/models/data-models.mdx @@ -2785,11 +2785,11 @@ Props for VeltCommentDialogReplyAvatarsListItem. Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). -#### CommentDialogAgentSuggestionProps +#### CommentDialogSuggestionProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogagentsuggestion) +## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogsuggestion) -Props for VeltCommentDialogAgentSuggestion and its sub-components. +Props for VeltCommentDialogSuggestion and its sub-components. Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). @@ -8632,6 +8632,7 @@ Optional config passed to [`enableSuggestionMode()`](/api-reference/sdk/api/api- | ------------------- | ------------------------------------------------------------- | -------- | -------------------------------------------------------- | | `onTargetEditStart` | [`TargetEditStartHandler`](#targeteditstarthandlert) | No | Called when user begins editing a suggestion target | | `onTargetEditCommit`| [`TargetEditCommitHandler`](#targeteditcommithandlert) | No | Called when an edit is committed as a suggestion | +| `autoCommit` | `boolean` | No | When `true` (default) and no `onTargetEditCommit` handler is provided, every detected edit auto-commits as a suggestion using the SDK's default summary. Pass `false` for detect-only mode — the `targetEditCommit` event still fires, but nothing commits until a subscriber calls the event payload's `commitSuggestion` builder. Ignored when `onTargetEditCommit` is provided. | #### CommitSuggestionConfig\ @@ -8639,12 +8640,13 @@ Optional config passed to [`enableSuggestionMode()`](/api-reference/sdk/api/api- Passed to [`commitSuggestion()`](/api-reference/sdk/api/api-methods#commitsuggestion). -| Property | Type | Required | Description | -| ---------- | ------------------------- | -------- | --------------------------------------------- | -| `targetId` | `string` | Yes | ID of the target being committed | -| `newValue` | `T` | Yes | Proposed value to store in the suggestion | -| `summary` | `string` | No | Human-readable description of the change | -| `metadata` | `Record` | No | Arbitrary caller-supplied metadata | +| Property | Type | Required | Description | +| ------------- | ------------------------- | -------- | --------------------------------------------- | +| `targetId` | `string` | Yes | ID of the target being committed | +| `newValue` | `T` | Yes | Proposed value to store in the suggestion | +| `summary` | `string` | No | Human-readable description of the change. Becomes the seeded comment's plain text. | +| `summaryHtml` | `string` | No | Optional HTML body for the seeded suggestion comment (for example, a color-coded diff). Sanitized with DOMPurify at render time — inline `style` is preserved; script and event-handler content is stripped. | +| `metadata` | `Record` | No | Arbitrary caller-supplied metadata | ### Handler Types @@ -8685,12 +8687,13 @@ type TargetEditStartResult = void; --- -Optional return from [`TargetEditCommitHandler`](#targeteditcommithandlert) to override `summary` or `metadata` on commit. +Optional return from [`TargetEditCommitHandler`](#targeteditcommithandlert) to override `summary`, `summaryHtml`, or `metadata` on commit. -| Property | Type | Required | Description | -| ---------- | ------------------------- | -------- | ---------------------------------------- | -| `summary` | `string` | No | Override for the suggestion summary | -| `metadata` | `Record` | No | Override for the suggestion metadata | +| Property | Type | Required | Description | +| ------------- | ------------------------- | -------- | ---------------------------------------- | +| `summary` | `string` | No | Override for the suggestion summary | +| `summaryHtml` | `string` | No | Optional HTML body for the seeded suggestion comment. Sanitized with DOMPurify at render time. | +| `metadata` | `Record` | No | Override for the suggestion metadata | #### TargetEditStartHandler\ diff --git a/async-collaboration/suggestions/overview.mdx b/async-collaboration/suggestions/overview.mdx index 9cdc43c6a..f370423d4 100644 --- a/async-collaboration/suggestions/overview.mdx +++ b/async-collaboration/suggestions/overview.mdx @@ -188,11 +188,43 @@ suggestionElement.isSuggestionModeEnabled$().subscribe((isEnabled) => { #### 3. Capture Edits as Suggestions -When a user finishes an edit, you decide how it becomes a suggestion. There are three ways, from simplest to most control. Use one per target; only one of them handles any given edit. +When a user finishes an edit, you decide how it becomes a suggestion. There are four ways, from simplest to most control. Use one per target; only one of them handles any given edit. -**Option 1: Auto-commit with `onTargetEditCommit` (simplest)** +**Option 1: Zero-config auto-commit (default)** -Pass `onTargetEditCommit` when you enable suggestion mode. The SDK calls it with the old and new values every time a user finishes an edit. Return an object and the SDK creates the suggestion right away, using your `summary` and `metadata`. This is the path most apps want. (`onTargetEditStart` fires when editing begins; it's informational in v1 and its return value is reserved for future use.) +The simplest setup: enable suggestion mode with no handler at all. Every detected edit on a tagged target is committed automatically, using the SDK's default diff summary. This is controlled by the new `autoCommit` flag on [`EnableSuggestionModeConfig`](/api-reference/sdk/models/data-models#enablesuggestionmodeconfig), which **defaults to `true`**. Pass `autoCommit: false` for detect-only mode — the `targetEditCommit` event still fires, but nothing is created until you call the event's `commitSuggestion` builder (see Option 3). + + + +```jsx +const { enableSuggestionMode } = useEnableSuggestionMode(); + +// Zero-config: edits on tagged targets auto-commit as suggestions. +enableSuggestionMode(); + +// Detect-only: events fire, but nothing commits until you call the builder. +enableSuggestionMode({ autoCommit: false }); +``` + + + +```js +// Zero-config: edits on tagged targets auto-commit as suggestions. +suggestionElement.enableSuggestionMode(); + +// Detect-only: events fire, but nothing commits until you call the builder. +suggestionElement.enableSuggestionMode({ autoCommit: false }); +``` + + + + +`autoCommit` is ignored when you pass `onTargetEditCommit` (Option 2) — the handler always wins, including its `null`-return deferral contract. The flag is cleared by `disableSuggestionMode()`; re-enabling without it resets to the default. + + +**Option 2: Auto-commit with `onTargetEditCommit`** + +Pass `onTargetEditCommit` when you enable suggestion mode. The SDK calls it with the old and new values every time a user finishes an edit. Return an object and the SDK creates the suggestion right away, using your `summary`, `summaryHtml`, and `metadata`. Use this when you want per-edit control over the suggestion body without falling all the way back to the event stream. (`onTargetEditStart` fires when editing begins; it's informational in v1 and its return value is reserved for future use.) @@ -232,7 +264,7 @@ suggestionElement.enableSuggestionMode({ Don't want every edit to become a suggestion automatically? Return `null` (or leave out `onTargetEditCommit`) and handle the edit yourself with the `targetEditCommit` event below, for example to validate the value or ask the user to confirm first. -**Option 2: Decide per edit with the `targetEditCommit` event** +**Option 3: Decide per edit with the `targetEditCommit` event** If you skip `onTargetEditCommit`, subscribe to the `targetEditCommit` event instead. The event gives you the edit details plus a `commitSuggestion` function that's already tied to that edit. Call it to create the suggestion (you can override `summary` / `metadata`), or don't call it to discard the edit. Nothing is created until you call it. @@ -271,7 +303,7 @@ suggestionElement.on('targetEditCommit').subscribe(({ details, commitSuggestion -**Option 3: Create suggestions manually with `startSuggestion` / `commitSuggestion`** +**Option 4: Create suggestions manually with `startSuggestion` / `commitSuggestion`** When there's no input for the SDK to watch (a custom widget, a canvas element, or an "AI proposes a change" button), create the suggestion yourself. Call `startSuggestion(targetId)` to capture the current value as `oldValue`, then `commitSuggestion(config)` with the `newValue` to create it. @@ -318,6 +350,40 @@ const { id } = await suggestionElement.commitSuggestion({ `commitSuggestion` only works while suggestion mode is on and the `targetId` is known to the SDK (tagged in the DOM or registered via `registerTarget`). It also creates nothing when `newValue` is identical to the captured `oldValue`. +##### Rich HTML summaries with `summaryHtml` + +The suggestion card renders a seeded first comment using the `summary` you provide. Pass an optional `summaryHtml` alongside `summary` (on either `commitSuggestion(config)` or the `onTargetEditCommit` / event-builder return value) to render a formatted body — for example, a color-coded before/after diff. `summaryHtml` becomes the comment's `commentHtml`; plain `summary` (or the SDK's default diff text) stays in `commentText` as the fallback. + +If you provide neither, the SDK renders a default styled HTML diff (old value in red italic, new value in green italic). + + + +```jsx +await commitSuggestion({ + targetId: 'price-field', + newValue: 6000, + summary: 'Price: $5,000 → $6,000', + summaryHtml: '

Price: $5,000 $6,000

', +}); +``` + + + +```js +await suggestionElement.commitSuggestion({ + targetId: 'price-field', + newValue: 6000, + summary: 'Price: $5,000 -> $6,000', + summaryHtml: '

Price: $5,000 $6,000

', +}); +``` + + + + +`summaryHtml` is sanitized with DOMPurify at render time — `