Skip to content

Commit 46b5261

Browse files
harbournickharbournick
authored
feat(document-api): clear content command (#2300)
* feat(document-api): clear content command * chore: fix tests
1 parent 5e49613 commit 46b5261

20 files changed

Lines changed: 444 additions & 3 deletions

File tree

‎apps/cli/scripts/export-sdk-contract.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ const INTENT_NAMES = {
5757
'doc.getHtml': 'get_document_html',
5858
'doc.info': 'get_document_info',
5959
'doc.capabilities.get': 'get_capabilities',
60+
'doc.clearContent': 'clear_content',
6061
'doc.insert': 'insert_content',
6162
'doc.replace': 'replace_content',
6263
'doc.delete': 'delete_content',

‎apps/cli/src/__tests__/conformance/scenarios.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1943,6 +1943,14 @@ export const SUCCESS_SCENARIOS = {
19431943
],
19441944
};
19451945
},
1946+
'doc.clearContent': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
1947+
const stateDir = await harness.createStateDir('doc-clear-content-success');
1948+
const docPath = await harness.copyFixtureDoc('doc-clear-content');
1949+
return {
1950+
stateDir,
1951+
args: ['clear-content', docPath, '--out', harness.createOutputPath('doc-clear-content-output')],
1952+
};
1953+
},
19461954
'doc.insert': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
19471955
const stateDir = await harness.createStateDir('doc-insert-success');
19481956
const docPath = await harness.copyFixtureDoc('doc-insert');

‎apps/cli/src/cli/operation-hints.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
7878
getMarkdown: 'extracted markdown',
7979
getHtml: 'extracted html',
8080
info: 'retrieved info',
81+
clearContent: 'cleared document content',
8182
insert: 'inserted text',
8283
replace: 'replaced text',
8384
delete: 'deleted text',
@@ -240,6 +241,7 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
240241
getMarkdown: 'plain',
241242
getHtml: 'plain',
242243
info: 'documentInfo',
244+
clearContent: 'receipt',
243245
insert: 'mutationReceipt',
244246
replace: 'mutationReceipt',
245247
delete: 'mutationReceipt',
@@ -386,6 +388,7 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
386388
getMarkdown: 'markdown',
387389
getHtml: 'html',
388390
info: null,
391+
clearContent: 'receipt',
389392
insert: null,
390393
replace: null,
391394
delete: null,
@@ -561,6 +564,7 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
561564
getMarkdown: 'query',
562565
getHtml: 'query',
563566
info: 'general',
567+
clearContent: 'general',
564568
insert: 'textMutation',
565569
replace: 'textMutation',
566570
delete: 'textMutation',

‎apps/docs/document-api/available-operations.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Use the tables below to see what operations are available and where each one is
1717
| Blocks | 1 | 0 | 1 | [Reference](/document-api/reference/blocks/index) |
1818
| Capabilities | 1 | 0 | 1 | [Reference](/document-api/reference/capabilities/index) |
1919
| Comments | 5 | 0 | 5 | [Reference](/document-api/reference/comments/index) |
20-
| Core | 10 | 0 | 10 | [Reference](/document-api/reference/core/index) |
20+
| Core | 11 | 0 | 11 | [Reference](/document-api/reference/core/index) |
2121
| Create | 6 | 0 | 6 | [Reference](/document-api/reference/create/index) |
2222
| Format | 44 | 1 | 45 | [Reference](/document-api/reference/format/index) |
2323
| History | 3 | 0 | 3 | [Reference](/document-api/reference/history/index) |
@@ -50,6 +50,7 @@ Use the tables below to see what operations are available and where each one is
5050
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.getMarkdown(...)</code></span> | [`getMarkdown`](/document-api/reference/get-markdown) |
5151
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.getHtml(...)</code></span> | [`getHtml`](/document-api/reference/get-html) |
5252
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | [`info`](/document-api/reference/info) |
53+
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.clearContent(...)</code></span> | [`clearContent`](/document-api/reference/clear-content) |
5354
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.insert(...)</code></span> | [`insert`](/document-api/reference/insert) |
5455
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.replace(...)</code></span> | [`replace`](/document-api/reference/replace) |
5556
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.delete(...)</code></span> | [`delete`](/document-api/reference/delete) |

‎apps/docs/document-api/reference/_generated-manifest.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"apps/docs/document-api/reference/blocks/index.mdx",
66
"apps/docs/document-api/reference/capabilities/get.mdx",
77
"apps/docs/document-api/reference/capabilities/index.mdx",
8+
"apps/docs/document-api/reference/clear-content.mdx",
89
"apps/docs/document-api/reference/comments/create.mdx",
910
"apps/docs/document-api/reference/comments/delete.mdx",
1011
"apps/docs/document-api/reference/comments/get.mdx",
@@ -262,6 +263,7 @@
262263
"getMarkdown",
263264
"getHtml",
264265
"info",
266+
"clearContent",
265267
"insert",
266268
"replace",
267269
"delete"
@@ -604,5 +606,5 @@
604606
}
605607
],
606608
"marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
607-
"sourceHash": "d1b97baae61be333b72dc1211180bc02dd451e14a3767328d56929bf77a10132"
609+
"sourceHash": "fb9f6aa91bd10748ac21af2465aa97ce59b8e4a9043f6fd0aa07fb7e175cd5c6"
608610
}

‎apps/docs/document-api/reference/capabilities/get.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -282,6 +282,11 @@ _No fields._
282282
| `operations.capabilities.get.dryRun` | boolean | yes | |
283283
| `operations.capabilities.get.reasons` | enum[] | no | |
284284
| `operations.capabilities.get.tracked` | boolean | yes | |
285+
| `operations.clearContent` | object | yes | |
286+
| `operations.clearContent.available` | boolean | yes | |
287+
| `operations.clearContent.dryRun` | boolean | yes | |
288+
| `operations.clearContent.reasons` | enum[] | no | |
289+
| `operations.clearContent.tracked` | boolean | yes | |
285290
| `operations.comments.create` | object | yes | |
286291
| `operations.comments.create.available` | boolean | yes | |
287292
| `operations.comments.create.dryRun` | boolean | yes | |
@@ -1729,6 +1734,14 @@ _No fields._
17291734
],
17301735
"tracked": true
17311736
},
1737+
"clearContent": {
1738+
"available": true,
1739+
"dryRun": true,
1740+
"reasons": [
1741+
"COMMAND_UNAVAILABLE"
1742+
],
1743+
"tracked": true
1744+
},
17321745
"comments.create": {
17331746
"available": true,
17341747
"dryRun": true,
@@ -5272,6 +5285,41 @@ _No fields._
52725285
],
52735286
"type": "object"
52745287
},
5288+
"clearContent": {
5289+
"additionalProperties": false,
5290+
"properties": {
5291+
"available": {
5292+
"type": "boolean"
5293+
},
5294+
"dryRun": {
5295+
"type": "boolean"
5296+
},
5297+
"reasons": {
5298+
"items": {
5299+
"enum": [
5300+
"COMMAND_UNAVAILABLE",
5301+
"HELPER_UNAVAILABLE",
5302+
"OPERATION_UNAVAILABLE",
5303+
"TRACKED_MODE_UNAVAILABLE",
5304+
"DRY_RUN_UNAVAILABLE",
5305+
"NAMESPACE_UNAVAILABLE",
5306+
"STYLES_PART_MISSING",
5307+
"COLLABORATION_ACTIVE"
5308+
]
5309+
},
5310+
"type": "array"
5311+
},
5312+
"tracked": {
5313+
"type": "boolean"
5314+
}
5315+
},
5316+
"required": [
5317+
"available",
5318+
"tracked",
5319+
"dryRun"
5320+
],
5321+
"type": "object"
5322+
},
52755323
"comments.create": {
52765324
"additionalProperties": false,
52775325
"properties": {
@@ -13156,6 +13204,7 @@ _No fields._
1315613204
"getMarkdown",
1315713205
"getHtml",
1315813206
"info",
13207+
"clearContent",
1315913208
"insert",
1316013209
"replace",
1316113210
"delete",

‎apps/docs/document-api/reference/clear-content.mdx‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: clearContent
3+
sidebarTitle: clearContent
4+
description: Clear all document body content, leaving a single empty paragraph.
5+
---
6+
7+
{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
8+
9+
> Alpha: Document API is currently alpha and subject to breaking changes.
10+
11+
## Summary
12+
13+
Clear all document body content, leaving a single empty paragraph.
14+
15+
- Operation ID: `clearContent`
16+
- API member path: `editor.doc.clearContent(...)`
17+
- Mutates document: `yes`
18+
- Idempotency: `conditional`
19+
- Supports tracked mode: `no`
20+
- Supports dry run: `no`
21+
- Deterministic target resolution: `yes`
22+
23+
## Expected result
24+
25+
Returns a Receipt with success status; reports NO_OP if the document is already empty.
26+
27+
## Input fields
28+
29+
_No fields._
30+
31+
### Example request
32+
33+
```json
34+
{}
35+
```
36+
37+
## Output fields
38+
39+
### Variant 1 (success=true)
40+
41+
| Field | Type | Required | Description |
42+
| --- | --- | --- | --- |
43+
| `inserted` | EntityAddress[] | no | |
44+
| `removed` | EntityAddress[] | no | |
45+
| `success` | `true` | yes | Constant: `true` |
46+
| `updated` | EntityAddress[] | no | |
47+
48+
### Variant 2 (success=false)
49+
50+
| Field | Type | Required | Description |
51+
| --- | --- | --- | --- |
52+
| `failure` | object | yes | |
53+
| `failure.code` | enum | yes | `"NO_OP"` |
54+
| `failure.details` | any | no | |
55+
| `failure.message` | string | yes | |
56+
| `success` | `false` | yes | Constant: `false` |
57+
58+
### Example response
59+
60+
```json
61+
{
62+
"inserted": [
63+
{
64+
"entityId": "entity-789",
65+
"entityType": "comment",
66+
"kind": "entity"
67+
}
68+
],
69+
"success": true,
70+
"updated": [
71+
{
72+
"entityId": "entity-789",
73+
"entityType": "comment",
74+
"kind": "entity"
75+
}
76+
]
77+
}
78+
```
79+
80+
## Pre-apply throws
81+
82+
- `CAPABILITY_UNAVAILABLE`
83+
84+
## Non-applied failure codes
85+
86+
- `NO_OP`
87+
88+
## Raw schemas
89+
90+
<Accordion title="Raw input schema">
91+
```json
92+
{
93+
"additionalProperties": false,
94+
"properties": {},
95+
"type": "object"
96+
}
97+
```
98+
</Accordion>
99+
100+
<Accordion title="Raw output schema">
101+
```json
102+
{
103+
"oneOf": [
104+
{
105+
"$ref": "#/$defs/ReceiptSuccess"
106+
},
107+
{
108+
"additionalProperties": false,
109+
"properties": {
110+
"failure": {
111+
"additionalProperties": false,
112+
"properties": {
113+
"code": {
114+
"enum": [
115+
"NO_OP"
116+
]
117+
},
118+
"details": {},
119+
"message": {
120+
"type": "string"
121+
}
122+
},
123+
"required": [
124+
"code",
125+
"message"
126+
],
127+
"type": "object"
128+
},
129+
"success": {
130+
"const": false
131+
}
132+
},
133+
"required": [
134+
"success",
135+
"failure"
136+
],
137+
"type": "object"
138+
}
139+
]
140+
}
141+
```
142+
</Accordion>
143+
144+
<Accordion title="Raw success schema">
145+
```json
146+
{
147+
"$ref": "#/$defs/ReceiptSuccess"
148+
}
149+
```
150+
</Accordion>
151+
152+
<Accordion title="Raw failure schema">
153+
```json
154+
{
155+
"additionalProperties": false,
156+
"properties": {
157+
"failure": {
158+
"additionalProperties": false,
159+
"properties": {
160+
"code": {
161+
"enum": [
162+
"NO_OP"
163+
]
164+
},
165+
"details": {},
166+
"message": {
167+
"type": "string"
168+
}
169+
},
170+
"required": [
171+
"code",
172+
"message"
173+
],
174+
"type": "object"
175+
},
176+
"success": {
177+
"const": false
178+
}
179+
},
180+
"required": [
181+
"success",
182+
"failure"
183+
],
184+
"type": "object"
185+
}
186+
```
187+
</Accordion>

‎apps/docs/document-api/reference/core/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Primary read and write operations.
2121
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-markdown"><code>getMarkdown</code></a></span> | `getMarkdown` | No | `idempotent` | No | No |
2222
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-html"><code>getHtml</code></a></span> | `getHtml` | No | `idempotent` | No | No |
2323
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/info"><code>info</code></a></span> | `info` | No | `idempotent` | No | No |
24+
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/clear-content"><code>clearContent</code></a></span> | `clearContent` | Yes | `conditional` | No | No |
2425
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/insert"><code>insert</code></a></span> | `insert` | Yes | `non-idempotent` | Yes | Yes |
2526
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/replace"><code>replace</code></a></span> | `replace` | Yes | `conditional` | Yes | Yes |
2627
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/delete"><code>delete</code></a></span> | `delete` | Yes | `conditional` | Yes | Yes |

‎apps/docs/document-api/reference/index.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Document API is currently alpha and subject to breaking changes.
2020

2121
| Namespace | Canonical ops | Aliases | Total surface | Reference |
2222
| --- | --- | --- | --- | --- |
23-
| Core | 10 | 0 | 10 | [Open](/document-api/reference/core/index) |
23+
| Core | 11 | 0 | 11 | [Open](/document-api/reference/core/index) |
2424
| Blocks | 1 | 0 | 1 | [Open](/document-api/reference/blocks/index) |
2525
| Capabilities | 1 | 0 | 1 | [Open](/document-api/reference/capabilities/index) |
2626
| Create | 6 | 0 | 6 | [Open](/document-api/reference/create/index) |
@@ -55,6 +55,7 @@ The tables below are grouped by namespace.
5555
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-markdown"><code>getMarkdown</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.getMarkdown(...)</code></span> | Extract the document content as a Markdown string. |
5656
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-html"><code>getHtml</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.getHtml(...)</code></span> | Extract the document content as an HTML string. |
5757
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/info"><code>info</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | Return document metadata including revision, node count, and capabilities. |
58+
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/clear-content"><code>clearContent</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.clearContent(...)</code></span> | Clear all document body content, leaving a single empty paragraph. |
5859
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/insert"><code>insert</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.insert(...)</code></span> | Insert content at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the `type` field. |
5960
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/replace"><code>replace</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.replace(...)</code></span> | Replace content at a target position with new text or inline content. |
6061
| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/delete"><code>delete</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.delete(...)</code></span> | Delete content at a target position. |

0 commit comments

Comments
 (0)