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 +21 -0
- package/README.md +445 -2
- package/dist/index.d.mts +2996 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +1711 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +63 -3
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
|
-
#
|
|
1
|
+
# foldkit-builder
|
|
2
2
|
|
|
3
|
-
|
|
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.
|