foldkit-mixins-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 +481 -2
- package/dist/index.d.mts +446 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +1057 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +62 -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,482 @@
|
|
|
1
|
-
#
|
|
1
|
+
# foldkit-mixins-builder
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Status:** experimental, `0.1.0`, on npm from the 0.16.0 release.
|
|
4
|
+
|
|
5
|
+
Draws a [`foldkit-builder`](../builder/README.md) page Builder as accessible
|
|
6
|
+
HTML, with every element published as a [`foldkit-mixins`](../mixins/README.md)
|
|
7
|
+
Slot. The Builder owns the page being edited and the editor's state; this
|
|
8
|
+
package decides which elements show it and wires the keyboard and pointer to
|
|
9
|
+
the Builder's own Messages; your Style and Behavior attachments decide how it
|
|
10
|
+
looks.
|
|
11
|
+
|
|
12
|
+
## What it owns
|
|
13
|
+
|
|
14
|
+
| Fact | Owner |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| The Document, undo, the selection, the viewport, the layers' focus | `foldkit-builder` |
|
|
17
|
+
| How a Block looks on the page | the site's `Renderer` (`foldkit-composition/foldkit`) |
|
|
18
|
+
| Which element draws each part of the editor, and its accessibility wiring | `foldkit-mixins-builder` |
|
|
19
|
+
| Classes, inline style, extra attributes and events | your `Style` / `Behavior` attachments |
|
|
20
|
+
|
|
21
|
+
It holds no state and adds no Messages. Every event it installs dispatches one
|
|
22
|
+
of the Builder's own, so a Builder drawn this way and a Builder driven by a
|
|
23
|
+
test or an agent go through the same `update`.
|
|
24
|
+
|
|
25
|
+
## Mental model
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
Builder.make(...) the Builder: Model, update, a plain view
|
|
29
|
+
|
|
|
30
|
+
BuilderView.define(builder) the editor, as a SlotView over BuilderSlots,
|
|
31
|
+
| .pipe(Style.attach(...)) with its keyboard and pointer Behaviors
|
|
32
|
+
BuilderView.submodel(view) a Submodel view, drawn with BuilderView.inputs({ data })
|
|
33
|
+
|
|
|
34
|
+
builder.bundle.pipe(Bundle.withView(...)) placed on its own, or
|
|
35
|
+
builder.inputWith(...) as a form key whose value is the page
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The page on the canvas is drawn by the site's Renderer, the same one the public
|
|
39
|
+
page uses, in edit mode: each node is wrapped in an element carrying its id, so
|
|
40
|
+
a click or hover on the page names the node under it.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
pnpm add effect foldkit foldkit-bundle foldkit-builder foldkit-composition foldkit-form foldkit-mixins foldkit-mixins-builder
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Start without customization
|
|
49
|
+
|
|
50
|
+
Given `PageBuilder`, a `Builder.make` result from the
|
|
51
|
+
[Builder's example](../builder/README.md#sixty-seconds):
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { Bundle } from 'foldkit-bundle'
|
|
55
|
+
import { BuilderView } from 'foldkit-mixins-builder'
|
|
56
|
+
|
|
57
|
+
const PageEditing = BuilderView.define(PageBuilder)
|
|
58
|
+
const Drawn = PageBuilder.bundle.pipe(Bundle.withView(BuilderView.submodel(PageEditing)))
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Place `Drawn` as you would any Bundle. Its view draws:
|
|
62
|
+
|
|
63
|
+
- a **palette**: one button per Block with starting props, named
|
|
64
|
+
"Add <label>" and grouped, each titled with where it would go ("Adds it
|
|
65
|
+
inside the Section") or disabled, saying why, where the selection leaves no
|
|
66
|
+
place for it (by `aria-disabled`, as every button of the editor is, so a
|
|
67
|
+
button stays focusable when its own press leaves it nothing to do; style
|
|
68
|
+
`[aria-disabled="true"]`, not `:disabled`); the Catalog's patterns follow
|
|
69
|
+
in a group of their own,
|
|
70
|
+
"Patterns", each placed where its root's Block would go;
|
|
71
|
+
- the **layers**: a `role="tree"` of the page's nodes, one `treeitem` row each,
|
|
72
|
+
with a roving tab stop on the selected row; a row shows its Block's label and
|
|
73
|
+
the node's first text in brief, and one that holds others has a toggle that
|
|
74
|
+
opens and closes it; pointing at a row marks its node on the page, as
|
|
75
|
+
pointing at the page does;
|
|
76
|
+
- an **inspector**: the selected node's Block, what it is for, and its
|
|
77
|
+
**actions** (move up, down, out and in; duplicate; delete; each titled with
|
|
78
|
+
its shortcut), then its settings under Content, Style, Visibility and
|
|
79
|
+
Interactions; with nothing selected, how to begin and the shortcuts;
|
|
80
|
+
- **undo** and **redo**, a **breadcrumb** of where the selection is (the
|
|
81
|
+
page, then each node holding it; a press selects that one), a **viewport**
|
|
82
|
+
picker, and the reason the last edit was refused, as a `role="alert"`;
|
|
83
|
+
- the **canvas**: the page in edit mode, in a frame as wide as the viewport,
|
|
84
|
+
saying how to begin (the `empty` Slot) while the page holds nothing;
|
|
85
|
+
- a **live region** the Builder's announcements are read from.
|
|
86
|
+
|
|
87
|
+
## The keyboard and the pointer
|
|
88
|
+
|
|
89
|
+
Five Behaviors are attached, each from `foldkit-primitives`:
|
|
90
|
+
|
|
91
|
+
| Where | Behavior | What it does |
|
|
92
|
+
| --- | --- | --- |
|
|
93
|
+
| `tree`, `row` | `TreeNavigation` | Up, Down, Home and End move focus between rows; Right opens a row, then moves to its first child; Left closes it, then moves to its parent. Focus moving selects the row's node. |
|
|
94
|
+
| `layers`, `canvas` | the Builder's `keyCommand`, from its commands | Alt with an arrow moves the selected node; Mod+D duplicates; Delete removes; Mod+Z, Mod+Shift+Z and Mod+Y undo and redo; Escape deselects. |
|
|
95
|
+
| `canvas` | `Targets` | The pointer over a node marks it hovered; a press selects it and does not follow a link. |
|
|
96
|
+
| `canvas` | `EditableText` | A double-click on text the page draws as a field, or Enter on its node, edits it where it is: typing sets the prop, Enter or leaving commits, Escape puts it back. A press in it selects text rather than dragging the node. |
|
|
97
|
+
| `layers`, `canvas` | `KeepInView` | Whatever became selected (a click, a shortcut, an insert, the address) is scrolled into view, its row in the layers and its element on the page. |
|
|
98
|
+
| `tree`, `canvas` | `PointerDrag` | A row or a node pressed and moved 4px is dragged; over another, the drop lands before it, inside it or after it by which third of it the pointer is in; releasing moves it there, and Escape cancels. |
|
|
99
|
+
| `palette` | `PointerDrag`, onto the canvas | A Block's tile dragged onto the page lands the same way and adds a new node of it there; a press without a drag adds it where its title says. A pattern's tile is pressed, not dragged. |
|
|
100
|
+
|
|
101
|
+
The shortcuts are on the layers panel and the canvas, not the whole editor,
|
|
102
|
+
so Delete in a text box edits the text. The canvas is focusable, so a press on
|
|
103
|
+
the page leaves focus where the shortcuts are. The node's action buttons, the
|
|
104
|
+
toolbar's and the list of shortcuts are all drawn from the Builder's commands
|
|
105
|
+
(`PageBuilder.commands`), so a command given another key or left out there
|
|
106
|
+
changes each of them, and a button sends what its key does. Keys are written
|
|
107
|
+
for the author's platform, given as a view input
|
|
108
|
+
(`BuilderView.inputs({ platform: 'mac' })` writes ⌘D, else Ctrl+D). A drag is the pointer's way to do what Alt with an arrow does;
|
|
109
|
+
it adds no roles or keys to the tree, and a drop is announced like a key's
|
|
110
|
+
move.
|
|
111
|
+
|
|
112
|
+
A structural edit is announced, such as "Moved Heading, 2 of 3 in Section
|
|
113
|
+
body". The Builder owns the words; this package draws the region.
|
|
114
|
+
|
|
115
|
+
## Styling
|
|
116
|
+
|
|
117
|
+
`BuilderSlots` names every element; attach a Style as to any SlotView:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { Style } from 'foldkit-mixins'
|
|
121
|
+
import { BuilderSlots, BuilderView } from 'foldkit-mixins-builder'
|
|
122
|
+
|
|
123
|
+
const PageEditing = BuilderView.define(PageBuilder).pipe(
|
|
124
|
+
Style.attach(
|
|
125
|
+
Style.forSlots(BuilderSlots)({
|
|
126
|
+
root: Style.class('builder'),
|
|
127
|
+
row: Style.class('builder-row'),
|
|
128
|
+
canvas: Style.class('builder-canvas'),
|
|
129
|
+
}),
|
|
130
|
+
),
|
|
131
|
+
)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`define` draws the panels in four regions, so a layout places four things,
|
|
135
|
+
and a new panel lands in its region without moving the rest:
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
root the container `builder`
|
|
139
|
+
├── panelTabs a narrow editor's tabs (see below)
|
|
140
|
+
├── regions
|
|
141
|
+
│ ├── start palette, layers
|
|
142
|
+
│ ├── bar toolbar, crumbs, viewports, preview
|
|
143
|
+
│ ├── stage alert, canvas
|
|
144
|
+
│ └── end inspector
|
|
145
|
+
└── live
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`root` is a container (`container: builder / inline-size`, the Builder's
|
|
149
|
+
default Style), so the regions may be laid out by the editor's own width,
|
|
150
|
+
`@container builder (max-width: 64rem)`, rather than the window's: an editor
|
|
151
|
+
in a narrow column stacks in a wide window. The example lays `regions` out as
|
|
152
|
+
a grid of `start`, `bar` over `stage`, and `end`. A layout of your own
|
|
153
|
+
(`assemble`) draws none of these. An inline-size container takes no width from
|
|
154
|
+
what it holds, so give the editor one: as a flex item that does not grow, an
|
|
155
|
+
`auto` grid column, `inline-block` or `fit-content`, it is 0 wide.
|
|
156
|
+
|
|
157
|
+
A node's props are drawn by its Block's settings form, a `foldkit-mixins-form`
|
|
158
|
+
view the Builder makes. Give its Styles to `define` (or `parts`), and they are
|
|
159
|
+
attached to every Block's settings form:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
import { FieldSlots, FormSlots } from 'foldkit-mixins-form'
|
|
163
|
+
|
|
164
|
+
const PageEditing = BuilderView.define(PageBuilder, {
|
|
165
|
+
settings: {
|
|
166
|
+
field: Style.attach(Style.forSlots(FieldSlots)({ label: Style.class('setting-label') })),
|
|
167
|
+
form: Style.attach(Style.forSlots(FormSlots)({ root: Style.class('settings') })),
|
|
168
|
+
},
|
|
169
|
+
})
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
A control kind of the application's own (`Input.kind`) is drawn by the
|
|
173
|
+
renderers the application gives, the same ones its form views take. Each
|
|
174
|
+
Block's settings form has Messages of its own, so they are given as a
|
|
175
|
+
function of the Message, as `Cms.controlRenderers` is:
|
|
176
|
+
`BuilderView.define(PageBuilder, { settings: { renderers: Cms.controlRenderers } })`.
|
|
177
|
+
Without one, the inspector says which renderer is missing.
|
|
178
|
+
|
|
179
|
+
The page on the canvas is the site's own markup, so it is styled by the site's
|
|
180
|
+
CSS, and the editor marks it by drawing over it: the `selectionBox` Slot sits
|
|
181
|
+
over the selected node, with its Block's label in `selectionLabel`, and the
|
|
182
|
+
`hoverBox` Slot over the node under the pointer. They are placed from where
|
|
183
|
+
the nodes are measured to be (`Measure`, from `foldkit-primitives/dom`),
|
|
184
|
+
scroll with the page, and take no pointer; the Builder places them, and a
|
|
185
|
+
Style says how they look:
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
Style.forSlots(BuilderSlots)({
|
|
189
|
+
selectionBox: Style.self({ outline: '2px solid Highlight', outlineOffset: '3px' }),
|
|
190
|
+
selectionLabel: Style.self({ background: 'Highlight', color: 'HighlightText', fontSize: '0.75rem' }),
|
|
191
|
+
hoverBox: Style.self({ outline: '1px dashed GrayText', outlineOffset: '3px' }),
|
|
192
|
+
})
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
A node's wrapper still carries `data-composition-mark` (`selected`, or
|
|
196
|
+
`hovered`; a node that is both is `selected`), which is what the boxes are
|
|
197
|
+
measured from, and `data-composition-drop` (`before`, `inside` or `after`) on
|
|
198
|
+
the node a drop would land at. A wrapper is `display: contents` and draws
|
|
199
|
+
nothing, so style the element inside it. The layer rows carry
|
|
200
|
+
`data-builder-drop` and `data-builder-dragging` the same way.
|
|
201
|
+
|
|
202
|
+
```css
|
|
203
|
+
[data-composition-drop='before'] > * { box-shadow: 0 -3px 0 Highlight; }
|
|
204
|
+
[data-composition-drop='after'] > * { box-shadow: 0 3px 0 Highlight; }
|
|
205
|
+
[data-composition-drop='inside'] > * { outline: 2px dashed Highlight; }
|
|
206
|
+
[data-builder-dragging] { opacity: 0.5; }
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Your own layout
|
|
210
|
+
|
|
211
|
+
`BuilderView.define` places every part of the editor. To leave some out, move
|
|
212
|
+
them, or draw your own elements among them, take the parts and assemble them:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
const parts = BuilderView.parts(PageBuilder)
|
|
216
|
+
const Compact = BuilderView.assemble((_model, slots, h, draw) =>
|
|
217
|
+
h.div(slots.root.attrs(), [
|
|
218
|
+
h.h1([], ['Home page']),
|
|
219
|
+
draw(parts.Palette),
|
|
220
|
+
draw(parts.Canvas),
|
|
221
|
+
draw(parts.Inspector),
|
|
222
|
+
]),
|
|
223
|
+
)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
The parts are `Panels`, `Palette`, `Layers`, `Inspector`, `Toolbar`, `Crumbs`,
|
|
227
|
+
`Viewports`, `Preview`, `Alert`, `Canvas` and `Live`. Each brings its own
|
|
228
|
+
Behaviors: `Layers` its tree keyboard and dragging, `Canvas` the pointer, and
|
|
229
|
+
both the shortcuts. A layout without `Layers` has no tree keyboard. Styles
|
|
230
|
+
attach to `Compact` as to `define`'s view.
|
|
231
|
+
|
|
232
|
+
Each part names the Model fields it reads and is drawn again only when one of
|
|
233
|
+
them changed: a hover redraws the canvas and nothing else. A Style that reads
|
|
234
|
+
the Model (`Style.whenInput`) attached to the whole view makes every part it
|
|
235
|
+
reaches redraw on every change. It is still correct, just not cached.
|
|
236
|
+
|
|
237
|
+
## A narrow editor
|
|
238
|
+
|
|
239
|
+
Where the editor is narrow, it can show one of its three panels at a time:
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
const PageEditing = BuilderView.define(PageBuilder).pipe(
|
|
243
|
+
Style.attach(BuilderView.narrow('52rem')),
|
|
244
|
+
)
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
- **The width is the editor's own, not the window's.** Below `width` of the
|
|
248
|
+
container `builder`, the Builder's root, the `Panels` part shows: a
|
|
249
|
+
`role="group"` of three buttons (Add, Layers, Settings), the chosen one
|
|
250
|
+
`aria-pressed`, as the viewports are, and only the panel the Builder's
|
|
251
|
+
`panel` names shows. Wider, the buttons are hidden (the Builder's default
|
|
252
|
+
Style) and every panel shows. They are not ARIA tabs, which would promise
|
|
253
|
+
arrow keys and a roving tab stop.
|
|
254
|
+
- **The Builder chooses the panel as it always has:** a button sends
|
|
255
|
+
`PanelChosen`, and selecting a node on the page chooses Settings; a row
|
|
256
|
+
clicked in the layers selects its node and keeps the layers showing. Each panel carries its
|
|
257
|
+
`id`, `data-panel` and `data-panel-shown`, and each button `aria-controls`
|
|
258
|
+
it; a layout of your own that draws `Panels` should draw the three panels.
|
|
259
|
+
- **It is in the `app` layer**, so it outranks an application's placing of
|
|
260
|
+
the panels in `app` or an earlier layer; an unlayered style outranks every
|
|
261
|
+
layer, and would show a hidden panel. `narrow(width, { layer })` puts it
|
|
262
|
+
elsewhere.
|
|
263
|
+
|
|
264
|
+
## As a form key
|
|
265
|
+
|
|
266
|
+
`builder.inputWith(view)` is the Builder's form control, `builder.input`, drawn
|
|
267
|
+
by another view. The form draws a Bundle-backed control with the Bundle's own
|
|
268
|
+
view, so no renderer is needed. With `PageInput` from the
|
|
269
|
+
[Builder's example](../builder/README.md#sixty-seconds):
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
import { Form } from 'foldkit-form'
|
|
273
|
+
|
|
274
|
+
const PageForm = Form.make('PageForm', PageInput, {
|
|
275
|
+
inputs: { document: PageBuilder.inputWith(BuilderView.submodel(PageEditing)) },
|
|
276
|
+
})
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
The CMS example (`examples/cms`) places its page form this way.
|
|
280
|
+
|
|
281
|
+
## The canvas and the page's data
|
|
282
|
+
|
|
283
|
+
A Query or Surface Block draws from its node's read, which is the
|
|
284
|
+
application's, not the Builder's. The page's parent reads them, as it must to
|
|
285
|
+
preview or publish the page, and gives them to the canvas as the Builder's view
|
|
286
|
+
inputs; the Builder keeps no copy:
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
EditorSlot.view(model, h, {
|
|
290
|
+
controls: {
|
|
291
|
+
document: BuilderView.inputs({ data: reads.data(model) }),
|
|
292
|
+
},
|
|
293
|
+
})
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
`reads` is `QueryBlock.active(...)` (or `SurfaceBlock.active(...)`), the same
|
|
297
|
+
active Surface that fetches them. Placed on its own, the drawn Builder takes
|
|
298
|
+
the same inputs: `placed.view(model, h, BuilderView.inputs({ data }))`. The
|
|
299
|
+
canvas draws with `Renderer.make`, so a Block's actions do not run there.
|
|
300
|
+
|
|
301
|
+
## What the inspector draws
|
|
302
|
+
|
|
303
|
+
The selected node's props are its Block's settings form, a `foldkit-form` form
|
|
304
|
+
that `foldkit-builder` makes (see its README), drawn by `foldkit-mixins-form`'s
|
|
305
|
+
`FormView`. So each prop gets the control a form would give it, and its fields
|
|
306
|
+
are styled through `FieldSlots` and `FormSlots`, as any form's are:
|
|
307
|
+
|
|
308
|
+
| Prop Schema | Control |
|
|
309
|
+
| --- | --- |
|
|
310
|
+
| `Schema.Boolean` | `input type="checkbox"` |
|
|
311
|
+
| `Schema.Literals([...])` | `select` of the literals, text or numbers; a number is stored as a number |
|
|
312
|
+
| `Schema.Number` | `input type="text"`, so "1." is kept while it is typed |
|
|
313
|
+
| `Schema.String`, and a brand of it such as `Url` | `input type="text"` |
|
|
314
|
+
| anything else | its JSON, shown and not edited |
|
|
315
|
+
|
|
316
|
+
A control of the application's own, such as a color picker given with
|
|
317
|
+
`Builder.controls({ tint: Input.bundle(...) })`, is drawn with its Bundle's
|
|
318
|
+
view, as any form draws it. A field is labelled with its Schema's `title`,
|
|
319
|
+
else its prop key, spaced. A change that decodes is one `setProp`, and typing
|
|
320
|
+
a word is one undo step. One that does not (`abc` for a number, an address its
|
|
321
|
+
brand refuses) shows its error at its field and changes nothing.
|
|
322
|
+
|
|
323
|
+
Where the Schema alone does not say, the Block asks for a control through
|
|
324
|
+
metadata. `Input.multiline()` draws a `textarea`, and `Input.hidden()` leaves
|
|
325
|
+
the prop out:
|
|
326
|
+
|
|
327
|
+
```ts
|
|
328
|
+
import { Schema } from 'effect'
|
|
329
|
+
import { Block, Content } from 'foldkit-composition'
|
|
330
|
+
import { Builder } from 'foldkit-builder'
|
|
331
|
+
import { Input } from 'foldkit-form'
|
|
332
|
+
|
|
333
|
+
const Quote = Block.define('Quote', {
|
|
334
|
+
Props: Schema.Struct({
|
|
335
|
+
text: Schema.String.annotate({ title: 'Quotation' }),
|
|
336
|
+
ref: Schema.String,
|
|
337
|
+
}),
|
|
338
|
+
provides: [Content.Flow],
|
|
339
|
+
}).pipe(Block.annotate(Builder.controls({ text: Input.multiline(), ref: Input.hidden() })))
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
The hint is `foldkit-builder`'s, kept on the Block beside any other package's
|
|
343
|
+
metadata; `foldkit-composition` does not read it. A later annotation's prop
|
|
344
|
+
replaces an earlier one's.
|
|
345
|
+
|
|
346
|
+
### What the editor calls a Block
|
|
347
|
+
|
|
348
|
+
A Block's `label`, `description` and palette `group` are its words, from
|
|
349
|
+
`foldkit-composition`, which an agent's tool reads too:
|
|
350
|
+
|
|
351
|
+
```ts
|
|
352
|
+
const Described = Quote.pipe(Block.words({ group: 'Text', description: 'Words someone said' }))
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
The label defaults to the Block's name spaced (`PostList` is "Post list"), and
|
|
356
|
+
Blocks given no group share one, "Blocks"; a group is headed only when there is
|
|
357
|
+
more than one. The palette shows the label and the description, and a layer row
|
|
358
|
+
the label and the node's first text prop, cut to forty characters. Palette
|
|
359
|
+
buttons and layer rows carry `data-block` with the Block's name, so a Style can
|
|
360
|
+
give each an icon; a pattern's button carries `data-pattern` with its name.
|
|
361
|
+
|
|
362
|
+
### A prop that points at the application's things
|
|
363
|
+
|
|
364
|
+
A prop holding an id, such as the category a list shows, asks for a picker:
|
|
365
|
+
`Input.relationOne(Category)` draws a `select`, and `Input.relationMany(Tag)`
|
|
366
|
+
a group of checkboxes over a prop that is an array of ids. What they choose
|
|
367
|
+
from is the application's rows, loaded by its own query as a form's picker
|
|
368
|
+
options are; the page's parent gives them in the Builder's view inputs, keyed
|
|
369
|
+
`'Block.prop'`:
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
const Featured = Block.define('Featured', {
|
|
373
|
+
Props: Schema.Struct({ category: Schema.NullOr(Schema.String) }),
|
|
374
|
+
provides: [Content.Flow],
|
|
375
|
+
}).pipe(Block.annotate(Builder.controls({ category: Input.relationOne(Category) })))
|
|
376
|
+
|
|
377
|
+
EditorSlot.view(model, h, {
|
|
378
|
+
controls: {
|
|
379
|
+
document: BuilderView.inputs({
|
|
380
|
+
options: { 'Featured.category': categories.map(c => ({ value: c.id, label: c.name })) },
|
|
381
|
+
}),
|
|
382
|
+
},
|
|
383
|
+
})
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
A `relationOne` always offers "none", stored as `null` where the Schema admits
|
|
387
|
+
it; choosing it for a prop that needs an id says so at the field. A chosen id
|
|
388
|
+
the choices lack (a row since deleted, or choices not loaded yet) is shown as
|
|
389
|
+
`? id`; in a `relationMany` it stays chosen until it is unchecked. The
|
|
390
|
+
inspector lists the choices it is given and has no search box.
|
|
391
|
+
|
|
392
|
+
A node whose Block the Catalog does not know is shown, with its props, but not
|
|
393
|
+
edited. A stored value a `select` does not offer, such as a choice an older
|
|
394
|
+
version made, is shown as `? value` and chosen, with its error, rather than as
|
|
395
|
+
the blank.
|
|
396
|
+
|
|
397
|
+
The props are under Content, labelled by their Schema's `title`, else their
|
|
398
|
+
key spaced (`text` is "Text"). Under Style, each appearance axis the Block
|
|
399
|
+
offers: one of up to four values is a row of buttons, "Default" and each value,
|
|
400
|
+
the chosen one pressed (a stored value the axis lacks is shown pressed as
|
|
401
|
+
`? value`); one with more values is a `select`, with a blank for the default. A
|
|
402
|
+
choice is one `setAppearance`, and choosing the default for the last one
|
|
403
|
+
removes the node's `appearance`. A responsive token axis is a `select` per
|
|
404
|
+
breakpoint (`Space at md`), blank for unchanged; with only the base chosen, one
|
|
405
|
+
name is stored.
|
|
406
|
+
|
|
407
|
+
Then, under Visibility, when the Catalog declares a `context`, one field per
|
|
408
|
+
context key says when the node shows: `Shown when audience is` is a `select` of
|
|
409
|
+
the key's literals (a
|
|
410
|
+
flag's is `true` and `false`, other keys are typed in), with a blank for
|
|
411
|
+
always. A choice is one `setWhen` holding an `eq` condition for that key;
|
|
412
|
+
conditions of other kinds are kept as they are, and clearing the last removes
|
|
413
|
+
the node's `when`.
|
|
414
|
+
|
|
415
|
+
Last, under Interactions, each event the Block names says what it runs:
|
|
416
|
+
`On press` is a `select`
|
|
417
|
+
of the Catalog's actions, blank for nothing, and under it the chosen action's
|
|
418
|
+
input as a form of its own, drawn and styled as the props are; its ids are
|
|
419
|
+
`<Block>-<event>-<action>-<key>`. Choosing an action starts its input from
|
|
420
|
+
each field's empty value as stored (`''`, `null`, `false`), else zero or a
|
|
421
|
+
select's first choice (`inputOf(block, event, action).seed()` in
|
|
422
|
+
`foldkit-builder`); a start the action's Schema still refuses is refused and
|
|
423
|
+
shown in the alert. Each change to the input is one
|
|
424
|
+
`setAction` with the changed keys over the rest, and choosing nothing removes
|
|
425
|
+
it.
|
|
426
|
+
|
|
427
|
+
The looks and the conditions stay the Builder's own controls, drawn through
|
|
428
|
+
`BuilderSlots`: each is a choice from a fixed list, which a form would draw no
|
|
429
|
+
better.
|
|
430
|
+
|
|
431
|
+
## The editor's words
|
|
432
|
+
|
|
433
|
+
Every word the editor shows of its own, from "Add a block" to the shortcut
|
|
434
|
+
list's headings, is one of `BuilderWords`, English by default
|
|
435
|
+
(`builderWords`). Give any of them as a view input:
|
|
436
|
+
|
|
437
|
+
```ts
|
|
438
|
+
BuilderView.inputs({
|
|
439
|
+
words: { palette: 'Bloque nuevo', addBlock: 'Añadir {label}' },
|
|
440
|
+
})
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
Keep the words in one value made once, not built in the view: each part that
|
|
444
|
+
draws words is drawn again when the object it is given is another one.
|
|
445
|
+
|
|
446
|
+
Words are text: a word that takes a value names it as a blank (`'Add {label}'`),
|
|
447
|
+
so a translation puts it where its language does. They are not functions,
|
|
448
|
+
because they are a view input, and Foldkit throws on a function nested in
|
|
449
|
+
one; being text, one object can hold a form's words and these. The Catalog's
|
|
450
|
+
words (a Block's label and description, its group) and the command table's
|
|
451
|
+
labels are the application's already, and are not among them; so are key
|
|
452
|
+
names, but for the named keys (Enter, Delete), which `keyNames` words. A test draws the editor with every word replaced by a marker
|
|
453
|
+
and finds nothing else of its own left.
|
|
454
|
+
|
|
455
|
+
## Previewing a context
|
|
456
|
+
|
|
457
|
+
With a Catalog `context`, a `role="group"` labelled "Preview as" (the
|
|
458
|
+
`preview` Slot) holds one field per key, a blank for unset. The canvas draws
|
|
459
|
+
the page for that context: a node hidden there is still drawn, marked
|
|
460
|
+
`data-composition-hidden`, which the site's CSS can dim:
|
|
461
|
+
|
|
462
|
+
```css
|
|
463
|
+
[data-composition-hidden] > * { opacity: 0.4; }
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## Limits
|
|
467
|
+
|
|
468
|
+
- Rich text on the canvas is not edited in place: its Block's props are shown
|
|
469
|
+
in the inspector.
|
|
470
|
+
- A drag moves one node, the selected one; there is no multiple selection.
|
|
471
|
+
- Two Builders on one page need different names: the inspector's form is placed
|
|
472
|
+
under the Builder's name, and one drawn twice is a crash that says so. Its
|
|
473
|
+
fields' ids are `<Block>Settings-<prop>`, so two Builders over one Catalog
|
|
474
|
+
showing the same Block also share ids.
|
|
475
|
+
- A drag does not scroll the layers or the canvas when the pointer nears an
|
|
476
|
+
edge.
|
|
477
|
+
- The viewport frame sets a width: `--fk-frame-width` on the frame, read by
|
|
478
|
+
the Builder's one default rule (in `components`, so any application style
|
|
479
|
+
overrides it). It does not load the page in an iframe, so the page's media
|
|
480
|
+
queries see the editor's width. The frame is the page's container
|
|
481
|
+
(`PAGE_CONTAINER`), so a look written with container queries or `cqi` units
|
|
482
|
+
follows the frame: see `Theme.inContainer`.
|