foldkit-builder 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Patrick Glenn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,446 @@
1
- # Temporary Holding Version
1
+ # foldkit-builder
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The page builder's state, as an ordinary [Bundle](../bundle/README.md). It
4
+ edits a [`foldkit-composition`](../composition/README.md) Document by
5
+ Operations, with a selection and undo beside it, and it is designed to be one
6
+ form key's control: the page is the key's value, so the form validates it,
7
+ submits it, and a CMS autosaves it.
8
+
9
+ > **Status:** experimental, `0.1.0`, on npm from the 0.16.0 release. The headless Builder and a plain
10
+ > view, from the [page builder design](../../docs/design/pagebuilder-DESIGN.md).
11
+ > The drawn editor is [`foldkit-mixins-builder`](../mixins-builder/README.md).
12
+
13
+ ## What it owns
14
+
15
+ | Fact | Owner |
16
+ | --- | --- |
17
+ | What a page may hold, and how each Block looks | the application: a Catalog and a Renderer |
18
+ | The page being edited | the Builder's Model, as the form key's value |
19
+ | Undo | the Builder's Model: the page is kept as a `foldkit-primitives/state` history |
20
+ | What is selected, the open panel, the viewport | the Builder's Model, beside the page |
21
+ | The last node copied or cut | the Builder's Model, as `clipboard`, and the system clipboard as text |
22
+ | Which text on the page is being edited in place, and what it said when that began | the Builder's Model, as `editing` |
23
+ | A prop's field while it holds text that does not decode yet | the Builder's Model, as `inspector` |
24
+ | The layers' keyboard focus and which rows are open | the Builder's Model, as a `TreeNavigation` placement |
25
+ | What the editor last said to assistive technology | the Builder's Model, as a `LiveAnnounce` placement |
26
+ | Saving, revisions, publishing | the form, and `foldkit-cms` around it |
27
+
28
+ The Catalog and the Renderer are vocabulary, not state. The Builder closes over
29
+ them where it is made; they never enter the Model or a placement's args.
30
+
31
+ ## Mental model
32
+
33
+ ```text
34
+ view: a click, a key ─► Builder Message ─► Composition.apply ─► next Document
35
+ │
36
+ History.push(page, document) ◄┘ one transition
37
+ Form: Control Message carries it; a change of Document is an edit; the rest is not
38
+ ```
39
+
40
+ ## Sixty seconds
41
+
42
+ ```ts
43
+ import { Builder } from 'foldkit-builder'
44
+
45
+ const PageBuilder = Builder.make('PageBuilder', {
46
+ catalog: Site,
47
+ renderer: SiteRenderer,
48
+ // What a new node of each Block starts with. The insert panel offers exactly these.
49
+ starters: { Section: {}, Heading: { text: 'New heading' } },
50
+ })
51
+
52
+ const PageForm = Form.make('PageForm', PageInput, {
53
+ inputs: { document: PageBuilder.input },
54
+ })
55
+ ```
56
+
57
+ - `Builder.make` builds a Bundle (`PageBuilder.bundle`) and the form control that
58
+ places it as a key (`PageBuilder.input`). Nothing runs until it is placed.
59
+ - In the form, `PageForm.control('document').field(model).value` is the
60
+ Builder's Model. Its `page` is an undo history whose `present` is the
61
+ Document; `PageBuilder.document(model)` reads it.
62
+ - Its view is a plain editor: a palette of the Blocks with starting props, the
63
+ layers with move, duplicate and delete for the selected node, the selected
64
+ node's text props, undo and redo, and the page drawn in edit mode.
65
+ `foldkit-mixins-form` draws it with the rest of the form. For the full
66
+ editor, `PageBuilder.inputWith(BuilderView.submodel(view))` is the same
67
+ control drawn by [`foldkit-mixins-builder`](../mixins-builder/README.md).
68
+
69
+ ## Messages
70
+
71
+ | Message | What it does |
72
+ | --- | --- |
73
+ | `Applied({ op })` | applies an Operation; a button, a key, a drag or an agent sends the same |
74
+ | `InsertAsked({ block, at })` | a new node with the Block's starting props, once an id is minted |
75
+ | `DuplicateAsked({ id, at })` | a copy of a node and what it holds, once ids are minted |
76
+ | `PatternAsked({ pattern, at })` | one of the Catalog's patterns, once ids are minted for its nodes |
77
+ | `CopyAsked({ id })`, `CutAsked({ id })`, `PasteAsked()`, `ClipboardRead({ text })` | the clipboard: see below |
78
+ | `EditingAsked({ field })`, `FieldTyped({ field, text })`, `EditingCommitted({ field, text })`, `EditingCancelled({ field })` | text edited in place: see below |
79
+ | `Minted({ ids, request })` | the ids a request waited for, answered by a Command |
80
+ | `Selected({ id })`, `Deselected()`, `Hovered({ id })`, `Unhovered()` | what the inspector and the node actions work on |
81
+ | `Undid()`, `Redid()` | a step of the page's undo history |
82
+ | `PanelChosen({ panel })`, `ViewportChosen({ viewport })` | the editor's own choices |
83
+ | `DragStarted({ source })`, `DraggedOver({ id, zone })`, `DraggedOverRegion({ id, region })`, `DraggedOff()`, `DraggedOverPage()`, `DragDropped()`, `DragCancelled()` | a pointer drag: see below |
84
+ | `PreviewChosen({ key, value })`, `PreviewCleared({ key })` | previews the page with one context key set, or unset |
85
+ | `Inspected({ id, message })` | a Message of the selected node's settings form: see below |
86
+ | `Layers.wrapper.make(...)`, `Announcer.wrapper.make(...)` | the placed tree and announcer's own Messages |
87
+
88
+ - **Ids are minted in a Command** (`Composition.newIds`), so `update` stays pure
89
+ and an Operation always carries the ids it creates. Nothing changes until
90
+ they arrive.
91
+ - **An applied Operation and its undo step change together:** the Builder
92
+ pushes the new Document onto its page history, a `foldkit-primitives/state`
93
+ history. Consecutive edits of one prop of one node share a group, so typing a
94
+ heading undoes as a whole.
95
+ - **A refused edit** leaves the page as it was and says why in `refused`, until
96
+ the next edit goes through.
97
+ - **A new node is selected**, and a removed one is no longer.
98
+
99
+ ## The inspector is a form
100
+
101
+ Each Block's props are edited through a `foldkit-form` form made from its props
102
+ Schema, once per Block, at the first use, and the input of the action each of
103
+ its events runs through one more, once per Block, event and action. A form
104
+ edits a value as the Document stores it, so a prop drawn as an `Option` is
105
+ chosen as an id or nothing, and checks each value against its whole Schema.
106
+ The node owns its values; a form only holds what its fields show:
107
+
108
+ ```text
109
+ node props ─► fill ─► field drafts ─► Inspected(Changed) ─► the form decodes each key
110
+ a key the Message changed that decodes, and the node lacks ─► setProp,
111
+ or setAction with the input's other keys
112
+ an optional key emptied ─► unsetProp, or setAction without it
113
+ a key that does not decode ─► its error, no edit
114
+ ```
115
+
116
+ - **A change that decodes is an edit**, one `setProp` per key the Message
117
+ changed, grouped in history like any other, so typing a word undoes as one.
118
+ A field left alone is never written back, and typing back the value the node
119
+ holds adds no undo step.
120
+ - **Text that does not decode** (`"abc"` for a number) stays in its field with
121
+ the form's error, and changes nothing. A required field emptied is such
122
+ text; an optional one emptied takes the value away.
123
+ - **A value the node refuses**, one that fits its field but not the Block (a
124
+ check across props), is said in `refused`, and the form shows what the node
125
+ holds again.
126
+ - **An action's input is written whole**, with only the keys its Schema names,
127
+ so one a stored input kept from an older Schema is dropped, not refused.
128
+ - **A node changed another way** (an undo, the canvas, an agent) refills every
129
+ field but one holding text that does not decode. Moving the selection drops
130
+ what was held; the next node's fields fill from its props.
131
+ - `PageBuilder.inspecting(model)` is the selected node's forms and their
132
+ Models, for a view to draw: `props`, and `on` by event. A view sends
133
+ `Inspected({ id, form: form.key, message: form.settings.encodeMessage(message) })`;
134
+ one for a node no longer selected, or a form it no longer draws, is ignored.
135
+ Each form's Model is held as JSON, so a saved Builder still is.
136
+ - A prop is labelled with its Schema's `title`, else its key spaced
137
+ (`maxItems` is "Max items"). A Block asks for a control where the Schema
138
+ does not say, with `Block.annotate(Builder.controls({ body: Input.multiline() }))`;
139
+ `Input.hidden()` leaves a prop out.
140
+ - A control of the application's own, backed by a Bundle (`Input.bundle`, a
141
+ color picker), works as it does in any form, with no Builder code; send its
142
+ Messages with `settings.control(key, message)`. The Builder runs its forms as
143
+ functions and starts nothing, so one with Subscriptions or Resources is
144
+ refused where the Builder is made: every Block's form is made there.
145
+
146
+ ## The keyboard, the layers, and what the editor says
147
+
148
+ The Builder places two `foldkit-primitives/interaction` bundles in its Model:
149
+ `TreeNavigation` for the layers panel (`Layers`, open by default) and
150
+ `LiveAnnounce` for a live region (`Announcer`). A view attaches their
151
+ Behaviors; `foldkit-mixins-builder` does.
152
+
153
+ - **Moving keyboard focus in the layers selects the node** it lands on.
154
+ - **A removed node leaves the layers' keys nearby:** with nothing selected,
155
+ `layers.current` moves to the node after it, else the one before, else the
156
+ nearest holder left, rather than falling back to the first row. With focus
157
+ in the layers, the Behavior follows it there, which selects that node.
158
+ - **`PageBuilder.commands`** is the editor's commands, one table: each has an
159
+ `id`, a `label`, its `keys`, where a drawn Builder offers it (`placement`:
160
+ the node's actions, the toolbar, or by key only), and `run(model)`, the
161
+ Message it sends now, or none while it has nothing to do. A view draws the
162
+ node's actions, the toolbar, their titles and the list of shortcuts from it,
163
+ and `PageBuilder.keyCommand(model, key, modifiers)` is derived from it: the
164
+ first command one of whose keys is pressed and which has something to do,
165
+ so a command added on a built one's key runs where that one has none. The
166
+ built table:
167
+
168
+ | Keys | What they do to the selected node |
169
+ | --- | --- |
170
+ | Alt+Up, Alt+Down | move it among its siblings |
171
+ | Alt+Left | move it out of its parent, to just after it |
172
+ | Alt+Right | move it into the node above it, last in the first Region that takes it |
173
+ | Mod+D | duplicate it, just after it, where its Region has room |
174
+ | Mod+C, Mod+X | copy it; cut it |
175
+ | Delete, Backspace | remove it |
176
+ | Mod+Z; Mod+Shift+Z or Mod+Y | undo; redo |
177
+ | Mod+V | paste inside it, or after it, as a new node of the copy's Block goes |
178
+ | Enter | edit its first text in place |
179
+ | Escape | deselect it |
180
+
181
+ Attach `keyCommand` to the layers panel and the canvas, not the whole editor,
182
+ so Delete in a text box edits the text. A move the page refuses is refused
183
+ as any edit is. A key's `mod` is Ctrl, or ⌘ on a Mac; `mod` and `alt` must be
184
+ as given, and `shift` only where given, so Delete takes Shift+Delete too.
185
+ - **`Builder.make(name, { commands: built => ... })`** changes the table: another
186
+ key for a command, one left out, one moved to the toolbar. What runs a key,
187
+ the node's actions and the toolbar all follow it.
188
+ - **Every structural edit is announced**, such as "Moved Heading, 2 of 3 in
189
+ Section body", a Block named by its label, and so are undo, redo, and a
190
+ refusal, assertively. A prop edit is not: the field being typed in already
191
+ says it.
192
+ - **What it says is its words.** `Builder.make(name, { words })` takes any of
193
+ `EditWords` over the English ones (`editWords`): each announcement, each
194
+ command's label, and each refusal the Builder makes itself. Words are text,
195
+ a value a blank in them (`'Moved {label}{at}'`), as a form's and a view's
196
+ are, so one object can hold them all. A refusal `apply` makes is worded by
197
+ `refusal`, with blanks `{code}` and `{message}`, by default its own message; the Model's `refused` holds the
198
+ worded text, so the live region and a view's alert say the same.
199
+
200
+ ## Text edited in place
201
+
202
+ A Block's view that draws a text prop with `field(key)` (see
203
+ [`foldkit-composition`](../composition/README.md#drawing-a-page-foldkit-compositionfoldkit))
204
+ can be edited on the canvas, where it shows:
205
+
206
+ ```text
207
+ double-click, or Enter ─► EditingAsked ─► editing: { id, key, initial } the field freezes at `initial`
208
+ typing ─► FieldTyped ─► setProp, in the session's one undo step
209
+ Enter or leaving it ─► EditingCommitted Escape ─► EditingCancelled: the step is taken back
210
+ ```
211
+
212
+ - **Each Message names the field as the canvas marks it**, and the Builder
213
+ checks it: text the Renderer does not draw as a field (`Renderer.fields`),
214
+ a prop that is not text, or a field other than the one being edited is
215
+ ignored.
216
+ - **One session is one undo step.** Beginning ends whatever group came
217
+ before (`History.close`), so two sessions of one prop undo apart, and a
218
+ second ask for the field being edited (a double-click inside it) begins
219
+ nothing. Escape, or text that ends where it began, takes the step back and
220
+ leaves nothing to redo (`History.revert`). Where another edit came between
221
+ (the inspector, an agent), the step is no longer the last: the text is
222
+ written back as a step of its own, and a commit writes nothing the page
223
+ already holds, so no step is empty. A session in which nothing was typed
224
+ writes nothing when it ends, so a field only looked at does not put back
225
+ over another's edit the text it showed.
226
+ - **While text is edited, the keys are the text's:** `keyCommand` offers
227
+ nothing, so Backspace deletes a letter, not the block.
228
+ - **Editing ends when its node is no longer the one selected**, as a click
229
+ elsewhere or a removal makes it, and at an undo or a redo, which change the
230
+ page under the field.
231
+ - The canvas freezes the field at `initial` so a redraw never rewrites the
232
+ element under the caret; the text is read by `foldkit-primitives`'
233
+ `EditableText`, which `foldkit-mixins-builder` attaches to the canvas.
234
+
235
+ ## Copy, cut and paste
236
+
237
+ A copy is a node and all it holds, as `Composition.takeTree` takes it. It goes
238
+ in two places: the Model's `clipboard`, and the system clipboard as JSON,
239
+ `{ "format": "foldkit-composition", "tree": … }`, so a copy made in one tab
240
+ pastes in another.
241
+
242
+ - **`CopyAsked({ id })`** keeps the copy and writes it out; **`CutAsked({ id })`**
243
+ also removes the node, as one undoable edit. A node its Region cannot do
244
+ without is not cut, and nothing is copied.
245
+ - **`PasteAsked()`** reads the system clipboard in a Command, which answers
246
+ `ClipboardRead({ text })`. Text read wins; the Model's copy is used only when
247
+ the browser would not let the clipboard be read.
248
+ - **The text is untrusted.** It is decoded strictly (a key it should not have
249
+ is refused, not dropped), checked by its own ids (`Composition.treeRefusal`),
250
+ so a refusal names what was copied, then each node gets a newly minted id by
251
+ `Composition.rekey`, and the tree goes in by one `insertTree`, which checks
252
+ every node against the Catalog. Anything that does not decode or fit (text
253
+ that is not part of a page, an unknown Block, a prop of the wrong type, a
254
+ child it names but does not hold) is refused whole: nothing goes in, and
255
+ `refused` says why. Text that is not part of a page, or no copy at all, is
256
+ `builder:nothing-to-paste`; the rest are `apply`'s own codes.
257
+ - **It goes where a new node of its root's Block would** (`placeFor`): inside
258
+ the selection when it fits there, else after it, else last among the roots,
259
+ or, for a Block that is no root, last in the last Region with room that
260
+ takes it, so a node cut and pasted with nothing selected comes back. Where
261
+ it can go nowhere, it is refused before ids are minted, as
262
+ `builder:no-place`, with the Block's label.
263
+
264
+ The announcer debounces and clears on Effect's clock through Commands named
265
+ `LiveAnnounce.read` and `LiveAnnounce.clear`. A runtime runs them beside
266
+ everything else; a test that follows each Command in turn should leave them
267
+ out, as it has no clock to wait on.
268
+
269
+ ## As a form key
270
+
271
+ `PageBuilder.input` is an `Input.bundle` control:
272
+
273
+ - the key's **value** is the Document, so the key's schema validates it, such as
274
+ `Composition.Document.check(Composition.valid(Site))`, and the form submits it;
275
+ - a Message that changes the Document is an **edit**, and one that does not,
276
+ such as a selection, is not, so a CMS autosaves only real changes;
277
+ - **filling** the key with a stored page replaces the Document and starts undo
278
+ over, and a stored form shown again is **settled**: no hover, no undo, no
279
+ refusal.
280
+
281
+ `PageBuilder.inputWith(view)` is the same control drawn by another view, with
282
+ whatever inputs that view takes, given through the form view's `controls`.
283
+
284
+ Placed alone, with `Bundle.withChild`, the same Bundle is a page editor whose
285
+ parent owns the Model.
286
+
287
+ ## The selection in the URL
288
+
289
+ A link that opens the editor on a Block is the Builder's selection mirrored
290
+ into the URL. The Builder owns the selection, and a selection does more than
291
+ set a field (the layers' focus moves, the rows above it open), so the URL
292
+ never writes it directly: a navigation becomes a `Selected` Message, and the
293
+ selection is read back out into the URL.
294
+
295
+ In, from the parent's own `update`, for a form key named `document` placed as
296
+ `page`:
297
+
298
+ ```ts
299
+ const blockIn = (url: Url): Option.Option<NodeId> =>
300
+ Option.map(
301
+ Option.filter(
302
+ Option.fromNullOr(new URLSearchParams(Option.getOrElse(url.search, () => '')).get('block')),
303
+ id => id !== '',
304
+ ),
305
+ NodeId.make,
306
+ )
307
+
308
+ const selectFrom = (url: Url) =>
309
+ Message.GotPageMessage({
310
+ message: PageForm.control('document').send(
311
+ Option.match(blockIn(url), {
312
+ onNone: () => BuilderMessage.Deselected(),
313
+ onSome: id => BuilderMessage.Selected({ id }),
314
+ }),
315
+ ),
316
+ })
317
+
318
+ const update = placements.update((model, message) =>
319
+ message._tag === 'UrlChanged'
320
+ ? {
321
+ model,
322
+ commands: [{ name: 'SelectFromUrl', effect: Effect.succeed(selectFrom(message.url)) }],
323
+ }
324
+ : { model },
325
+ )
326
+ ```
327
+
328
+ Out, as one of the parent's own Subscriptions, given to
329
+ `placements.subscriptions(selectionUrl)`:
330
+
331
+ ```ts
332
+ const selectionUrl = Subscription.make<Model, Message>()(entry => ({
333
+ selectionUrl: entry(
334
+ { block: Schema.Option(Schema.String) },
335
+ {
336
+ modelToDependencies: model => ({
337
+ block: PageForm.control('document').field(model.page).value.selected,
338
+ }),
339
+ dependenciesToStream: ({ block }) =>
340
+ Option.match(block, {
341
+ onNone: () => Stream.empty,
342
+ onSome: id => Stream.fromEffect(Navigation.replaceUrl(`?block=${id}`)).pipe(Stream.drain),
343
+ }),
344
+ },
345
+ ),
346
+ }))
347
+ ```
348
+
349
+ The Builder refuses an id its page lacks, so a link opened before the page is
350
+ loaded selects nothing: send `selectFrom` again once the form is filled.
351
+ Nothing selected leaves the URL as it is, so that link is not lost while the
352
+ page loads. An application with other query parameters builds the URL with
353
+ them. `test/url.test.ts` runs this recipe, and the CMS example's page editor
354
+ (`examples/cms`, at `/pages`) routes this way, with the page and the Block both in
355
+ the address.
356
+
357
+ ## Previewing a context
358
+
359
+ A page whose Catalog declares a `context` shows some nodes only under
360
+ conditions ([Conditions](../composition/README.md#conditions)). The Builder
361
+ keeps what the author previews the page as in `preview`, by context key,
362
+ starting from the `preview` it was made with:
363
+
364
+ ```ts
365
+ Builder.make('PageBuilder', { catalog: Site, renderer, starters, preview: { audience: 'guest' } })
366
+ ```
367
+
368
+ The page is drawn in edit mode with `preview` as its context, so a node hidden
369
+ for it is still drawn, marked `data-composition-hidden`. Previewing changes
370
+ nothing in the page and is not an edit.
371
+
372
+ ## Dragging
373
+
374
+ A pointer drag is four Messages, the facts `foldkit-primitives`' `PointerDrag`
375
+ reports. What is dragged is its `source`: a node on the page,
376
+ `{ _tag: 'Existing', id }`, or a new node of a Block, `{ _tag: 'New', block }`,
377
+ dragged from the palette.
378
+
379
+ - **`DragStarted({ source })`** puts the drag in the Model's `drag`, an
380
+ `Option`, with `over` and `at` both none, and selects a node it drags. Nothing
381
+ changes on the page yet. A node not on the page, or a Block with no starting
382
+ props, starts no drag.
383
+ - **`DraggedOver({ id, zone })`** says which node the pointer is over and in
384
+ which zone of it, `before`, `inside` or `after`; **`DraggedOff()`** that it is
385
+ over none. The Builder works out where a drop would land, `drag.at`: before
386
+ or after that node among its siblings, or last in the first of its Regions
387
+ that accepts the dragged Block. Inside a node that takes nothing is after it,
388
+ and `drag.over`'s zone says so. Where that node has no place for it, the
389
+ nearest node holding it that does is used, before it or after it, so a
390
+ Section dropped on a Section's last Heading lands after that Section, and
391
+ `drag.over` names the holder. It climbs no higher than a node being dragged,
392
+ and a drop onto a node's own place is no move, not its holder's. Each place is tried as the edit a drop would
393
+ make (a move for a node, an insert of the Block's starting props for a new
394
+ one), and where the page would refuse it, such as a node into itself, `at`
395
+ is none, so a mark never promises a drop the page refuses.
396
+ - **`DraggedOverRegion({ id, region })`** says the pointer is over a node's
397
+ empty Region, which the canvas draws as a box of its own (see Composition's
398
+ edit mode): a drop goes last in that Region, not the first that accepts the
399
+ Block, so a Columns' right column can be filled while its left is not.
400
+ `drag.over` is `{ id, zone: 'inside', region }`; `region` is none on every
401
+ other place. A Region that refuses the Block, or has no room, is weighed as
402
+ `DraggedOver` inside the node would be.
403
+ - **`DraggedOverPage()`** says a palette tile is over the page's own space,
404
+ over none of its nodes: an empty page, or the space below the last node.
405
+ It lands where a press with nothing selected would put it (`placeFor`):
406
+ last among the roots, or last in the last Region that takes it. A node
407
+ already on the page is moved only onto another.
408
+ - **`DragDropped()`** works the place out again, since the page may have
409
+ changed, and moves a node there as one edit, undone and announced like a
410
+ key's; a new node is asked for as a press on the palette asks, so it gets an
411
+ id, is added there, and is selected. With no place, nothing changes and "Not
412
+ moved", or "Not added", is announced. **`DragCancelled()`** ends the drag the
413
+ same way.
414
+
415
+ A drawing marks `drag.over` only while `drag.at` is set, so the mark is where
416
+ the node will go. The keyboard's way to move a node is `keyCommand`.
417
+
418
+ ## Helpers
419
+
420
+ Each helper that may have no answer returns an `Option`, as the Model's
421
+ `selected`, `hovered`, `refused` and `drag` are. The Model stores them as `null`
422
+ (`Schema.OptionFromNullOr`), so a saved Builder, such as a CMS draft, is JSON.
423
+
424
+ - `PageBuilder.placeFor(document, selected, block)` is where the palette puts a
425
+ new node: inside the selection when a Region there accepts it, else after the
426
+ selection, else last among the roots, or last in the last Region on the page
427
+ with room that accepts it; none where the Block can go nowhere.
428
+ - `PageBuilder.patternAt(document, selected, pattern)` is the same for a
429
+ pattern, by its root's Block; none for a pattern the Catalog lacks. Its use
430
+ is one `usePattern` edit, undone as one.
431
+ - `PageBuilder.moveBy(document, id, delta)` is the Operation that moves a node
432
+ among its siblings; none at an end.
433
+ - `PageBuilder.dropAt(document, source, target, zone)` is where a drag over
434
+ `target` would put `dragged`; none where the page refuses it.
435
+ - `PageBuilder.keyCommand(model, key, modifiers)` is the Message a shortcut
436
+ sends; none for a key it does not handle, which is what Foldkit's
437
+ `OnKeyDownPreventDefault` takes.
438
+ - `PageBuilder.replace(model, document)` and `PageBuilder.settle(model)` are what
439
+ the form control's fill and settle do.
440
+
441
+ ## Limits
442
+
443
+ - One node is selected at a time.
444
+ - The plain view is plain, and names its panels in English. The drawn editor
445
+ is `foldkit-mixins-builder`.
446
+ - A starting props value must encode with its Block's Schema.