Skip to content

Commit 49dc4ef

Browse files
harbournickharbournick
authored
feat(document-api): add 'story' targeting for parts targeting with main api functions (#2477)
* feat(document-api): add story targeting and runtime support for non-body content * fix(presentation): refresh header/footer layout after doc-api slot creation and writes * chore: add doc api story test * fix: test suite bootstrap regressions and layout test timeouts * fix(document-api): invalidate stale header/footer story runtimes on part and ref mutations * fix(super-editor): avoid eager story-runtime imports in story editor setup * fix: make story-aware refs, ranges, and writes route correctly * fix(document-api): preserve story context and stabilize header/footer writes
1 parent 4ea0ccc commit 49dc4ef

244 files changed

Lines changed: 8526 additions & 984 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -986,5 +986,5 @@
986986
}
987987
],
988988
"marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
989-
"sourceHash": "34852ca3a36fdbc4e68902541e89a9602b49b5031aacef23008f9c1f8d3f4677"
989+
"sourceHash": "4b45100573fb74d1eb2f006d5064fbcc2e5af3331272207dccbab5f0c97142ef"
990990
}

‎apps/docs/document-api/reference/create/heading.mdx‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Returns a CreateHeadingResult with the new heading block ID and address.
2929
| Field | Type | Required | Description |
3030
| --- | --- | --- | --- |
3131
| `at` | object(kind="documentStart") \\| object(kind="documentEnd") \\| object(kind="before") \\| object(kind="after") | no | One of: object(kind="documentStart"), object(kind="documentEnd"), object(kind="before"), object(kind="after") |
32+
| `in` | StoryLocator | no | StoryLocator |
3233
| `level` | integer | yes | |
3334
| `text` | string | no | |
3435

@@ -39,8 +40,11 @@ Returns a CreateHeadingResult with the new heading block ID and address.
3940
"at": {
4041
"kind": "documentStart"
4142
},
42-
"level": 1,
43-
"text": "Hello, world."
43+
"in": {
44+
"kind": "story",
45+
"storyType": "body"
46+
},
47+
"level": 1
4448
}
4549
```
4650

@@ -107,6 +111,11 @@ Returns a CreateHeadingResult with the new heading block ID and address.
107111
- `CAPABILITY_UNAVAILABLE`
108112
- `INVALID_TARGET`
109113
- `AMBIGUOUS_TARGET`
114+
- `STORY_NOT_FOUND`
115+
- `STORY_MISMATCH`
116+
- `STORY_NOT_SUPPORTED`
117+
- `CROSS_STORY_PLAN`
118+
- `MATERIALIZATION_FAILED`
110119

111120
## Non-applied failure codes
112121

@@ -180,6 +189,9 @@ Returns a CreateHeadingResult with the new heading block ID and address.
180189
}
181190
]
182191
},
192+
"in": {
193+
"$ref": "#/$defs/StoryLocator"
194+
},
183195
"level": {
184196
"description": "Heading level (1-6).",
185197
"maximum": 6,

‎apps/docs/document-api/reference/create/image.mdx‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Returns a CreateImageResult with the new image address.
3030
| --- | --- | --- | --- |
3131
| `alt` | string | no | |
3232
| `at` | object(kind="documentStart") \\| object(kind="documentEnd") \\| object(kind="before") \\| object(kind="after") \\| object(kind="inParagraph") | no | One of: object(kind="documentStart"), object(kind="documentEnd"), object(kind="before"), object(kind="after"), object(kind="inParagraph") |
33+
| `in` | StoryLocator | no | StoryLocator |
3334
| `size` | object | no | |
3435
| `size.height` | number | no | |
3536
| `size.width` | number | no | |
@@ -41,8 +42,11 @@ Returns a CreateImageResult with the new image address.
4142
```json
4243
{
4344
"alt": "example",
44-
"src": "example",
45-
"title": "example"
45+
"in": {
46+
"kind": "story",
47+
"storyType": "body"
48+
},
49+
"src": "example"
4650
}
4751
```
4852

@@ -69,6 +73,11 @@ Returns a CreateImageResult with the new image address.
6973
- `INVALID_TARGET`
7074
- `CAPABILITY_UNAVAILABLE`
7175
- `INVALID_INPUT`
76+
- `STORY_NOT_FOUND`
77+
- `STORY_MISMATCH`
78+
- `STORY_NOT_SUPPORTED`
79+
- `CROSS_STORY_PLAN`
80+
- `MATERIALIZATION_FAILED`
7281

7382
## Non-applied failure codes
7483

@@ -164,6 +173,9 @@ Returns a CreateImageResult with the new image address.
164173
}
165174
]
166175
},
176+
"in": {
177+
"$ref": "#/$defs/StoryLocator"
178+
},
167179
"size": {
168180
"additionalProperties": false,
169181
"properties": {

‎apps/docs/document-api/reference/create/paragraph.mdx‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
2929
| Field | Type | Required | Description |
3030
| --- | --- | --- | --- |
3131
| `at` | object(kind="documentStart") \\| object(kind="documentEnd") \\| object(kind="before") \\| object(kind="after") | no | One of: object(kind="documentStart"), object(kind="documentEnd"), object(kind="before"), object(kind="after") |
32+
| `in` | StoryLocator | no | StoryLocator |
3233
| `text` | string | no | |
3334

3435
### Example request
@@ -38,7 +39,10 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
3839
"at": {
3940
"kind": "documentStart"
4041
},
41-
"text": "Hello, world."
42+
"in": {
43+
"kind": "story",
44+
"storyType": "body"
45+
}
4246
}
4347
```
4448

@@ -105,6 +109,11 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
105109
- `CAPABILITY_UNAVAILABLE`
106110
- `INVALID_TARGET`
107111
- `AMBIGUOUS_TARGET`
112+
- `STORY_NOT_FOUND`
113+
- `STORY_MISMATCH`
114+
- `STORY_NOT_SUPPORTED`
115+
- `CROSS_STORY_PLAN`
116+
- `MATERIALIZATION_FAILED`
108117

109118
## Non-applied failure codes
110119

@@ -178,6 +187,9 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
178187
}
179188
]
180189
},
190+
"in": {
191+
"$ref": "#/$defs/StoryLocator"
192+
},
181193
"text": {
182194
"description": "Paragraph text content.",
183195
"type": "string"

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
3131
| Field | Type | Required | Description |
3232
| --- | --- | --- | --- |
3333
| `behavior` | DeleteBehavior | no | DeleteBehavior |
34+
| `in` | StoryLocator | no | StoryLocator |
3435
| `target` | SelectionTarget | yes | SelectionTarget |
3536
| `target.end` | SelectionPoint | yes | SelectionPoint |
3637
| `target.kind` | `"selection"` | yes | Constant: `"selection"` |
@@ -41,13 +42,18 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
4142
| Field | Type | Required | Description |
4243
| --- | --- | --- | --- |
4344
| `behavior` | DeleteBehavior | no | DeleteBehavior |
45+
| `in` | StoryLocator | no | StoryLocator |
4446
| `ref` | string | yes | |
4547

4648
### Example request
4749

4850
```json
4951
{
5052
"behavior": "selection",
53+
"in": {
54+
"kind": "story",
55+
"storyType": "body"
56+
},
5157
"target": {
5258
"end": {
5359
"blockId": "block-abc123",
@@ -191,6 +197,11 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
191197
- `CAPABILITY_UNAVAILABLE`
192198
- `INVALID_TARGET`
193199
- `INVALID_INPUT`
200+
- `STORY_NOT_FOUND`
201+
- `STORY_MISMATCH`
202+
- `STORY_NOT_SUPPORTED`
203+
- `CROSS_STORY_PLAN`
204+
- `MATERIALIZATION_FAILED`
194205

195206
## Non-applied failure codes
196207

@@ -209,6 +220,9 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
209220
"$ref": "#/$defs/DeleteBehavior",
210221
"description": "Delete behavior: 'selection' (default) or 'exact'."
211222
},
223+
"in": {
224+
"$ref": "#/$defs/StoryLocator"
225+
},
212226
"target": {
213227
"$ref": "#/$defs/SelectionTarget",
214228
"description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle."
@@ -226,6 +240,9 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
226240
"$ref": "#/$defs/DeleteBehavior",
227241
"description": "Delete behavior: 'selection' (default) or 'exact'."
228242
},
243+
"in": {
244+
"$ref": "#/$defs/StoryLocator"
245+
},
229246
"ref": {
230247
"description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting.",
231248
"type": "string"

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item
2828

2929
| Field | Type | Required | Description |
3030
| --- | --- | --- | --- |
31+
| `in` | StoryLocator | no | StoryLocator |
3132
| `limit` | integer | no | |
3233
| `offset` | integer | no | |
3334
| `options` | object | no | |
@@ -44,7 +45,10 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item
4445

4546
```json
4647
{
47-
"limit": 50,
48+
"in": {
49+
"kind": "story",
50+
"storyType": "body"
51+
},
4852
"select": {
4953
"caseSensitive": true,
5054
"mode": "contains",
@@ -94,6 +98,11 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item
9498
- `CAPABILITY_UNAVAILABLE`
9599
- `INVALID_INPUT`
96100
- `ADDRESS_STALE`
101+
- `STORY_NOT_FOUND`
102+
- `STORY_MISMATCH`
103+
- `STORY_NOT_SUPPORTED`
104+
- `CROSS_STORY_PLAN`
105+
- `MATERIALIZATION_FAILED`
97106

98107
## Non-applied failure codes
99108

@@ -106,6 +115,9 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item
106115
{
107116
"additionalProperties": false,
108117
"properties": {
118+
"in": {
119+
"$ref": "#/$defs/StoryLocator"
120+
},
109121
"limit": {
110122
"type": "integer"
111123
},

‎apps/docs/document-api/reference/format/apply.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
3030

3131
| Field | Type | Required | Description |
3232
| --- | --- | --- | --- |
33+
| `in` | StoryLocator | no | StoryLocator |
3334
| `inline` | object | yes | |
3435
| `inline.bCs` | boolean \\| null | no | One of: boolean, null |
3536
| `inline.bold` | boolean \\| null | no | One of: boolean, null |
@@ -83,6 +84,7 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
8384

8485
| Field | Type | Required | Description |
8586
| --- | --- | --- | --- |
87+
| `in` | StoryLocator | no | StoryLocator |
8688
| `inline` | object | yes | |
8789
| `inline.bCs` | boolean \\| null | no | One of: boolean, null |
8890
| `inline.bold` | boolean \\| null | no | One of: boolean, null |
@@ -133,6 +135,10 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
133135

134136
```json
135137
{
138+
"in": {
139+
"kind": "story",
140+
"storyType": "body"
141+
},
136142
"inline": {
137143
"bold": true,
138144
"italic": true
@@ -280,6 +286,11 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
280286
- `CAPABILITY_UNAVAILABLE`
281287
- `INVALID_TARGET`
282288
- `INVALID_INPUT`
289+
- `STORY_NOT_FOUND`
290+
- `STORY_MISMATCH`
291+
- `STORY_NOT_SUPPORTED`
292+
- `CROSS_STORY_PLAN`
293+
- `MATERIALIZATION_FAILED`
283294

284295
## Non-applied failure codes
285296

@@ -294,6 +305,9 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
294305
{
295306
"additionalProperties": false,
296307
"properties": {
308+
"in": {
309+
"$ref": "#/$defs/StoryLocator"
310+
},
297311
"inline": {
298312
"additionalProperties": false,
299313
"description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold.",
@@ -1118,6 +1132,9 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
11181132
{
11191133
"additionalProperties": false,
11201134
"properties": {
1135+
"in": {
1136+
"$ref": "#/$defs/StoryLocator"
1137+
},
11211138
"inline": {
11221139
"additionalProperties": false,
11231140
"description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold.",

‎apps/docs/document-api/reference/format/b-cs.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
191191
- `CAPABILITY_UNAVAILABLE`
192192
- `INVALID_TARGET`
193193
- `INVALID_INPUT`
194+
- `STORY_NOT_FOUND`
195+
- `STORY_MISMATCH`
196+
- `STORY_NOT_SUPPORTED`
197+
- `CROSS_STORY_PLAN`
198+
- `MATERIALIZATION_FAILED`
194199

195200
## Non-applied failure codes
196201

‎apps/docs/document-api/reference/format/bold.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
191191
- `CAPABILITY_UNAVAILABLE`
192192
- `INVALID_TARGET`
193193
- `INVALID_INPUT`
194+
- `STORY_NOT_FOUND`
195+
- `STORY_MISMATCH`
196+
- `STORY_NOT_SUPPORTED`
197+
- `CROSS_STORY_PLAN`
198+
- `MATERIALIZATION_FAILED`
194199

195200
## Non-applied failure codes
196201

‎apps/docs/document-api/reference/format/border.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
194194
- `CAPABILITY_UNAVAILABLE`
195195
- `INVALID_TARGET`
196196
- `INVALID_INPUT`
197+
- `STORY_NOT_FOUND`
198+
- `STORY_MISMATCH`
199+
- `STORY_NOT_SUPPORTED`
200+
- `CROSS_STORY_PLAN`
201+
- `MATERIALIZATION_FAILED`
197202

198203
## Non-applied failure codes
199204

0 commit comments

Comments
 (0)