Skip to content

Commit fb2e126

Browse files
zbeyenszbeyens
authored
Merge pull request #4103 from udecode/suggestion/docs
suggestion docs
2 parents 83e618f + 6fea0e9 commit fb2e126

File tree

8 files changed

+331
-4
lines changed

8 files changed

+331
-4
lines changed

‎apps/www/content/docs/en/comments.mdx‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ docs:
55
title: Comment Leaf
66
- route: /docs/components/comment-toolbar-button
77
title: Comment Toolbar Button
8+
- route: /docs/components/block-discussion
9+
title: Block Discussion
810
---
911

1012
<ComponentPreview name="comments-demo" />
@@ -32,7 +34,9 @@ import { CommentsPlugin } from '@udecode/plate-comments/react';
3234
const editor = createPlateEditor({
3335
plugins: [
3436
// ...otherPlugins,
35-
CommentsPlugin,
37+
commentsPlugin.configure({
38+
render: { aboveNodes: BlockDiscussion as any },
39+
}),
3640
],
3741
});
3842
```
@@ -45,6 +49,16 @@ const editor = createPlateEditor({
4549
</KeyTableItem>
4650
</KeyTable>
4751

52+
## Examples
53+
54+
### Plate UI
55+
56+
Refer to the preview above.
57+
58+
### Plate Plus
59+
60+
<ComponentPreviewPro name="comments-pro" />
61+
4862
## Plugins
4963

5064
### `CommentsPlugin`

‎apps/www/content/docs/en/suggestion.mdx‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
title: Suggestion
3+
docs:
4+
- route: /docs/components/suggestion-leaf
5+
title: Suggestion Leaf
6+
- route: /docs/components/suggestion-toolbar-button
7+
title: Suggestion Toolbar Button
8+
- route: /docs/components/block-suggestion
9+
title: Block suggestion
10+
- route: /docs/components/block-discussion
11+
title: Block discussion
12+
- route: /docs/components/suggestion-line-break
13+
title: Suggestion line break
14+
---
15+
16+
<ComponentPreview name="comments-demo" />
17+
18+
<PackageInfo>
19+
20+
## Features
21+
22+
- Add suggestions as text marks
23+
- Add block suggestions
24+
- Track suggestion state and users
25+
- Undo/redo suggestion changes
26+
- Note: This is an experimental feature and the API is subject to change.
27+
28+
</PackageInfo>
29+
30+
## Installation
31+
```bash
32+
npm install @udecode/plate-suggestion
33+
```
34+
35+
## Usage
36+
37+
```tsx
38+
import { SuggestionPlugin } from '@udecode/plate-suggestion/react';
39+
40+
const editor = createPlateEditor({
41+
plugins: [
42+
// ...otherPlugins,
43+
suggestionPlugin.configure({
44+
render: { belowNodes: SuggestionBelowNodes as any },
45+
}),
46+
],
47+
});
48+
```
49+
## Keyboard Shortcuts
50+
51+
<KeyTable>
52+
<KeyTableItem hotkey="Cmd + Shift + S">
53+
Add a suggestion on the selected text.
54+
</KeyTableItem>
55+
</KeyTable>
56+
57+
## Examples
58+
59+
### Plate UI
60+
61+
Refer to the preview above.
62+
63+
### Plate Plus
64+
65+
<ComponentPreviewPro name="comments-pro" />
66+
67+
## Plugins
68+
69+
### `SuggestionPlugin`
70+
71+
## API
72+
73+
### `editor.api.suggestion.addSuggestion`
74+
75+
Adds a new suggestion.
76+
77+
<API name="addSuggestion">
78+
<APIParameters>
79+
<APIItem name="value" type="WithPartial<TSuggestion, 'id' | 'userId'>">
80+
The suggestion value to add.
81+
</APIItem>
82+
</APIParameters>
83+
</API>
84+
85+
### `editor.api.suggestion.dataList`
86+
87+
Gets an array of suggestion data from a text node.
88+
89+
<API name="dataList">
90+
<APIParameters>
91+
<APIItem name="node" type="TSuggestionText">
92+
The suggestion text node.
93+
</APIItem>
94+
</APIParameters>
95+
<APIReturns type="TInlineSuggestionData[]">
96+
Array of suggestion data.
97+
</APIReturns>
98+
</API>
99+
100+
### `editor.api.suggestion.isBlockSuggestion`
101+
102+
Checks if a node is a block suggestion element.
103+
104+
<API name="isBlockSuggestion">
105+
<APIParameters>
106+
<APIItem name="node" type="TElement">
107+
The node to check.
108+
</APIItem>
109+
</APIParameters>
110+
<APIReturns type="node is TSuggestionElement">
111+
Whether the node is a block suggestion.
112+
</APIReturns>
113+
</API>
114+
115+
### `editor.api.suggestion.node`
116+
117+
Gets a suggestion node entry.
118+
119+
<API name="node">
120+
<APIOptions type="EditorNodesOptions & { id?: string; isText?: boolean }" optional>
121+
Options for finding the node.
122+
</APIOptions>
123+
<APIReturns type="NodeEntry<TSuggestionElement | TSuggestionText> | undefined">
124+
The suggestion node entry if found.
125+
</APIReturns>
126+
</API>
127+
128+
### `editor.api.suggestion.nodeId`
129+
130+
Gets the ID of a suggestion from a node.
131+
132+
<API name="nodeId">
133+
<APIParameters>
134+
<APIItem name="node" type="TElement | TSuggestionText">
135+
The node to get ID from.
136+
</APIItem>
137+
</APIParameters>
138+
<APIReturns type="string | undefined">
139+
The suggestion ID if found.
140+
</APIReturns>
141+
</API>
142+
143+
### `editor.api.suggestion.nodes`
144+
145+
Gets all suggestion node entries matching the options.
146+
147+
<API name="nodes">
148+
<APIOptions type="EditorNodesOptions" optional>
149+
Options for finding the nodes.
150+
</APIOptions>
151+
<APIReturns type="NodeEntry<TElement | TSuggestionText>[]">
152+
Array of suggestion node entries.
153+
</APIReturns>
154+
</API>
155+
156+
### `editor.api.suggestion.removeSuggestion`
157+
158+
Removes a suggestion by ID.
159+
160+
<API name="removeSuggestion">
161+
<APIParameters>
162+
<APIItem name="id" type="string | null">
163+
The ID of the suggestion to remove.
164+
</APIItem>
165+
</APIParameters>
166+
</API>
167+
168+
### `editor.api.suggestion.suggestionData`
169+
170+
Gets suggestion data from a node.
171+
172+
<API name="suggestionData">
173+
<APIParameters>
174+
<APIItem name="node" type="TElement | TSuggestionText">
175+
The node to get suggestion data from.
176+
</APIItem>
177+
</APIParameters>
178+
<APIReturns type="TInlineSuggestionData | TSuggestionElement['suggestion'] | undefined">
179+
The suggestion data if found.
180+
</APIReturns>
181+
</API>
182+
183+
### `editor.api.suggestion.updateSuggestion`
184+
185+
Updates a suggestion by ID.
186+
187+
<API name="updateSuggestion">
188+
<APIParameters>
189+
<APIItem name="id" type="string | null">
190+
The ID of the suggestion to update.
191+
</APIItem>
192+
<APIItem name="value" type="Partial<TSuggestion>">
193+
The updated suggestion values.
194+
</APIItem>
195+
</APIParameters>
196+
</API>
197+
198+
### `editor.api.suggestion.withoutSuggestions`
199+
200+
Executes a function with suggestions temporarily disabled.
201+
202+
<API name="withoutSuggestions">
203+
<APIParameters>
204+
<APIItem name="fn" type="() => void">
205+
The function to execute.
206+
</APIItem>
207+
</APIParameters>
208+
</API>
209+
210+
## Types
211+
212+
### `TSuggestionText`
213+
214+
Interface for text nodes that can contain suggestions.
215+
216+
<API name="TSuggestionText">
217+
<APIAttributes>
218+
<APIItem name="suggestion" type="boolean" optional>
219+
Indicates whether this is a suggestion.
220+
</APIItem>
221+
<APIItem name="suggestion_<id>" type="TInlineSuggestionData" optional>
222+
Contains suggestion data. Multiple suggestions can be present in a single text node.
223+
</APIItem>
224+
</APIAttributes>
225+
</API>

‎apps/www/public/r/index.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,30 @@
325325
],
326326
"type": "registry:ui"
327327
},
328+
{
329+
"dependencies": [
330+
"@udecode/plate-suggestion"
331+
],
332+
"doc": {
333+
"description": "A line break component for suggestion.",
334+
"docs": [
335+
{
336+
"route": "/docs/suggestion"
337+
}
338+
]
339+
},
340+
"files": [
341+
{
342+
"path": "plate-ui/suggestion-line-break.tsx",
343+
"type": "registry:ui"
344+
}
345+
],
346+
"name": "suggestion-line-break",
347+
"registryDependencies": [
348+
"suggestion-plugin"
349+
],
350+
"type": "registry:ui"
351+
},
328352
{
329353
"dependencies": [
330354
"@udecode/plate-date"

‎apps/www/public/r/styles/default/suggestion-line-break.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"dependencies": [
3+
"@udecode/plate-suggestion"
4+
],
5+
"doc": {
6+
"description": "A line break component for suggestion.",
7+
"docs": [
8+
{
9+
"route": "/docs/suggestion"
10+
}
11+
]
12+
},
13+
"files": [
14+
{
15+
"path": "plate-ui/suggestion-line-break.tsx",
16+
"content": "'use client';\nimport React, { useRef } from 'react';\n\nimport type { TSuggestionData } from '@udecode/plate-suggestion';\n\nimport { cn } from '@udecode/cn';\nimport { type RenderNodeWrapper, usePluginOption } from '@udecode/plate/react';\nimport { CornerDownLeftIcon } from 'lucide-react';\n\nimport {\n type SuggestionConfig,\n suggestionPlugin,\n} from '@/components/editor/plugins/suggestion-plugin';\n\nexport const SuggestionBelowNodes: RenderNodeWrapper<SuggestionConfig> = ({\n api,\n element,\n}) => {\n if (!api.suggestion.isBlockSuggestion(element)) return;\n\n const suggestionData = element.suggestion;\n\n if (!suggestionData?.isLineBreak) return;\n\n return function Component({ children }) {\n return (\n <React.Fragment>\n {children}\n <SuggestionLineBreak suggestionData={suggestionData} />\n </React.Fragment>\n );\n };\n};\n\nfunction SuggestionLineBreak({\n suggestionData,\n}: {\n suggestionData: TSuggestionData;\n}) {\n const { type } = suggestionData;\n const isRemove = type === 'remove';\n const isInsert = type === 'insert';\n\n const activeSuggestionId = usePluginOption(suggestionPlugin, 'activeId');\n const hoverSuggestionId = usePluginOption(suggestionPlugin, 'hoverId');\n\n const isActive = activeSuggestionId === suggestionData.id;\n const isHover = hoverSuggestionId === suggestionData.id;\n\n const spanRef = useRef<HTMLSpanElement>(null);\n\n return (\n <span\n ref={spanRef}\n className={cn(\n 'absolute border-b-2 border-b-brand/[.24] bg-brand/[.08] text-justify text-brand/80 no-underline transition-colors duration-200',\n isInsert &&\n (isActive || isHover) &&\n 'border-b-brand/[.60] bg-brand/[.13]',\n isRemove &&\n 'border-b-gray-300 bg-gray-300/25 text-gray-400 line-through',\n isRemove &&\n (isActive || isHover) &&\n 'border-b-gray-500 bg-gray-400/25 text-gray-500 no-underline'\n )}\n style={{\n bottom: 4.5,\n height: 21,\n }}\n contentEditable={false}\n >\n <CornerDownLeftIcon className=\"mt-0.5 size-4\" />\n </span>\n );\n}\n",
17+
"type": "registry:ui",
18+
"target": "components/plate-ui/suggestion-line-break.tsx"
19+
}
20+
],
21+
"name": "suggestion-line-break",
22+
"registryDependencies": [
23+
"suggestion-plugin"
24+
],
25+
"type": "registry:ui",
26+
"$schema": "https://platejs.org/schema/registry-item.json",
27+
"author": "udecode (https://platejs.org)"
28+
}

‎apps/www/src/__registry__/index.tsx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,21 @@ export const Index: Record<string, any> = {
195195
source: "",
196196
meta: undefined,
197197
},
198+
"suggestion-line-break": {
199+
name: "suggestion-line-break",
200+
description: "",
201+
type: "registry:ui",
202+
registryDependencies: ["suggestion-plugin"],
203+
files: [{
204+
path: "src/registry/default/plate-ui/suggestion-line-break.tsx",
205+
type: "registry:ui",
206+
target: ""
207+
}],
208+
categories: undefined,
209+
component: React.lazy(() => import("@/registry/default/plate-ui/suggestion-line-break.tsx")),
210+
source: "",
211+
meta: undefined,
212+
},
198213
"date-element": {
199214
name: "date-element",
200215
description: "",

‎apps/www/src/config/docs-plugins.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,12 @@ export const pluginsNavItems: SidebarNavItem[] = [
8080
label: 'Leaf',
8181
title: 'Comments',
8282
},
83+
{
84+
description: 'Add suggestions to text as marks.',
85+
href: '/docs/suggestion',
86+
label: 'Experimental',
87+
title: 'Suggestion',
88+
},
8389
{
8490
description: 'A visual overlay for cursors and selections.',
8591
href: '/docs/cursor-overlay',

‎apps/www/src/registry/registry-examples.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,10 +67,10 @@ export const proExamples: Registry['items'] = [
6767
},
6868
{
6969
doc: {
70-
description: `- Full stack example for Discussion and Comment
70+
description: `- Full stack example for Suggestion and Comment
71+
- Floating comments & suggestions UI with better user experience
7172
- Comment rendered with Plate editor
72-
- Discussion list in the sidebar
73-
- Beautifully crafted UI`,
73+
- Discussion list in the sidebar`,
7474
},
7575
name: 'comments-pro',
7676
type: 'registry:pro',

0 commit comments

Comments
 (0)