foldkit-cms 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 +279 -0
- package/dist/index.d.mts +1204 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +1150 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +66 -0
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
ADDED
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
# foldkit-cms
|
|
2
|
+
|
|
3
|
+
What a CMS adds to a domain that is already declared. The domain is a
|
|
4
|
+
[`foldkit-entity`](../entity/README.md) Entity, editing it is a
|
|
5
|
+
[`foldkit-form`](../form/README.md) form, and the screens are
|
|
6
|
+
[`foldkit-crud`](../crud/README.md)'s. None of that is CMS-specific. Three things
|
|
7
|
+
are: **audience** (a visitor sees what is published, an author sees everything),
|
|
8
|
+
**time** (drafts, revisions, a schedule), and **address** (a slug).
|
|
9
|
+
|
|
10
|
+
> **Status: built, unpublished.** Roles, content types, the three Entities, the
|
|
11
|
+
> operations, the lifecycle, the kinds, and the authoring editor's state. Its
|
|
12
|
+
> server is [`foldkit-cms-drizzle`](../cms-drizzle/README.md), which runs every
|
|
13
|
+
> operation and enforces the audience boundary, and
|
|
14
|
+
> [`examples/cms`](../../examples/cms) runs the two together. What
|
|
15
|
+
> [the design](../../docs/design/cms-DESIGN.md#13-build-order) set out is built
|
|
16
|
+
> but for a browser mode of the example. Neither package is on npm.
|
|
17
|
+
|
|
18
|
+
## What it owns
|
|
19
|
+
|
|
20
|
+
| Fact | Owner |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| Published content | your tables, read as any Entity is |
|
|
23
|
+
| What an author has entered and not published | a draft, kept **beside** the row, never in it |
|
|
24
|
+
| Which state a piece of content is in | nobody stores it: `Cms.state` derives it |
|
|
25
|
+
| Which transitions that state offers | `Cms.offers`, before anyone asks who is asking |
|
|
26
|
+
| Who may make a transition | your `allow`, asked by the server |
|
|
27
|
+
| The draft being typed | `foldkit-form`, in your Model, inside the editor's slice |
|
|
28
|
+
| How far the saves have got | `Cms.editor`, in that slice |
|
|
29
|
+
| The draft's `updatedAt`, the entry's `revision` | Remote's store: read, never copied |
|
|
30
|
+
|
|
31
|
+
It reads no database.
|
|
32
|
+
|
|
33
|
+
## Mental model
|
|
34
|
+
|
|
35
|
+
**A draft is an unsent form.** The content row holds what is published. A draft
|
|
36
|
+
is what an author has entered and not sent: the input of the operation that
|
|
37
|
+
would publish it, saved. So publishing is your own mutation, run with the
|
|
38
|
+
draft's value; a visitor's read cannot reach unfinished work, because it never
|
|
39
|
+
touches drafts; a revision is the same value, kept; and a half-filled form that
|
|
40
|
+
does not validate can be saved, which a row with a `not null` title cannot hold.
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
Entry ── Draft ── publish ──> your own mutation ──> content row ──> a visitor's read
|
|
44
|
+
└── Revision <── appended ──┘
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
An **Entry** is a piece of content from its first keystroke to its archive. It
|
|
48
|
+
exists before the row does, and after the row is hidden.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
pnpm add effect foldkit foldkit-entity foldkit-form foldkit-crud foldkit-remote foldkit-cms
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Example
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { Cms } from 'foldkit-cms'
|
|
60
|
+
|
|
61
|
+
// Which members play a CMS part is a fact about the Entity: metadata, by a pipe step.
|
|
62
|
+
const Post = Blog.Post.pipe(
|
|
63
|
+
Cms.roles({ label: 'title', slug: 'slug', published: 'publishedAt' }),
|
|
64
|
+
)
|
|
65
|
+
|
|
66
|
+
// How a type of content is authored is a fact about the application.
|
|
67
|
+
const Posts = Cms.content('posts', {
|
|
68
|
+
entity: Post,
|
|
69
|
+
form: PostForm, // an ordinary form: Form.make('PostForm', Entity.input(Post, PostInput))
|
|
70
|
+
publish: { create: CreatePostMutation, update: UpdatePostMutation },
|
|
71
|
+
words: { one: 'Post', many: 'Posts' },
|
|
72
|
+
// Optional: how a value would look in the store, for in-app preview.
|
|
73
|
+
preview: (value, id) => [{ entity: 'Post', id, values: value }],
|
|
74
|
+
})
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- `Post` is the same Entity as `Blog.Post`; only its metadata changed. Register
|
|
78
|
+
and bind the annotated one.
|
|
79
|
+
- A role names a member that can play it. `slug` on a number, or `published` on a
|
|
80
|
+
field that admits no `null`, is a type error and throws.
|
|
81
|
+
- `publish.create`'s input is the form's value and its output names the row;
|
|
82
|
+
`publish.update`'s input is that value and the row's id. A mutation of another
|
|
83
|
+
shape is a type error. They are your own mutations: what publishing a post
|
|
84
|
+
*does* stays your code.
|
|
85
|
+
- **A capability is declared, never implied.** No `slug` role, no slug handling.
|
|
86
|
+
No `published` role, no unpublish, and every row is visible.
|
|
87
|
+
|
|
88
|
+
`Cms.rolesOf(Post)` reads the roles back as Fields. Anything may: the server's
|
|
89
|
+
audience policy, a `bySlug` query, a sitemap this package knows nothing of.
|
|
90
|
+
|
|
91
|
+
## The lifecycle
|
|
92
|
+
|
|
93
|
+
State is derived from facts and a clock. Nothing stores a status, so it cannot
|
|
94
|
+
disagree with what is true.
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
Cms.state({ archivedAt: null, row: 'visible', draft: { scheduledFor, scheduleError: null } }, now)
|
|
98
|
+
// { _tag: 'Changed', schedule: { at, overdue: false, error: null } }
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
| State | Facts |
|
|
102
|
+
| --- | --- |
|
|
103
|
+
| `New` | no row yet |
|
|
104
|
+
| `Published` | a row a visitor sees, and no draft |
|
|
105
|
+
| `Changed` | a row a visitor sees, and unpublished work beside it |
|
|
106
|
+
| `Unpublished` | a row hidden by its `published` role |
|
|
107
|
+
| `Archived` | the entry was archived; nothing else applies until it is restored |
|
|
108
|
+
|
|
109
|
+
A `schedule` rides beside a state that has a draft. **A scheduled publish that
|
|
110
|
+
did not happen reads `overdue`, with the reason**, because that is true; it does
|
|
111
|
+
not read `Published`.
|
|
112
|
+
|
|
113
|
+
`Cms.offers(facts, now, content)` is the transitions an entry offers now:
|
|
114
|
+
`save`, `discard`, `publish`, `schedule`, `unschedule`, `unpublish`, `archive`,
|
|
115
|
+
`unarchive`, `restore`. It is what a view enables and what a server checks
|
|
116
|
+
before it asks who is asking. `unpublish` is offered only to a content type with
|
|
117
|
+
a `published` role.
|
|
118
|
+
|
|
119
|
+
## The editor
|
|
120
|
+
|
|
121
|
+
`Cms.editor` is the authoring screen's state: a form, the entry it belongs to,
|
|
122
|
+
and the draft that keeps what the author has entered. It is a Bundle, placed
|
|
123
|
+
like any other; the view is the form's own.
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
const Editor = Cms.editor('PostEditor', { content: Posts })
|
|
127
|
+
const Slot = Bundle.declare(Editor.bundle, 'editor') // its Model and its Messages, in yours
|
|
128
|
+
|
|
129
|
+
const PostEditor = Editor.at({ data: Data, model: App.model.editor })
|
|
130
|
+
const Placed = Page.at(Slot, { onOut: PostEditor.onOut })
|
|
131
|
+
const update = PostEditor.after(Page.assemble(Placed).update(yourUpdate))
|
|
132
|
+
|
|
133
|
+
Data.subscriptions({ ...yourSurfaces, ...PostEditor.actives })
|
|
134
|
+
|
|
135
|
+
Placed.helpers.open(entryId) // resume the draft, else show what is published
|
|
136
|
+
Placed.helpers.create(Cms.newEntryId()) // something new; its first save makes the entry
|
|
137
|
+
Editor.Message.PublishAsked() // also: ScheduleAsked({ at }), UnscheduleAsked, DiscardAsked,
|
|
138
|
+
// RestoreAsked({ revision }), UnpublishAsked, ArchiveAsked, UnarchiveAsked, ReloadAsked, OverwriteAsked
|
|
139
|
+
|
|
140
|
+
PostEditor.status(model) // Opened | Editing | Saving | Saved | Conflict | Publishing | Published | ...
|
|
141
|
+
PostEditor.state(model) // the entry's lifecycle state, as the server last derived it
|
|
142
|
+
PostEditor.pageId(model) // the row's id, or the entry's until there is a row: what a preview shows under
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
- **Saving is automatic and is not publishing.** Each edit starts a rest (`rest`,
|
|
146
|
+
one second by default), and the edit that is still the last one when its rest
|
|
147
|
+
ends saves the form as it stands, valid or not. There is no Save button to
|
|
148
|
+
forget, and a validation error never costs an author their work.
|
|
149
|
+
- **`Editing` means there are edits that are not saved yet**, and `Opened` means
|
|
150
|
+
the form is as it was found. A draft the editor filled the form from is on the
|
|
151
|
+
server already, so it reads `Saved`.
|
|
152
|
+
- A draft is listed by what its author called it, valid or not, and `untitled`
|
|
153
|
+
until they have. Publish pressed twice asks once.
|
|
154
|
+
- **Publishing submits the form**, so its rules and checks decide, and an invalid
|
|
155
|
+
form publishes nothing and says why in place. What is published is the saved
|
|
156
|
+
draft, so a publish saves first when the last edit has not.
|
|
157
|
+
- **Scheduling is a publish promised for later**: `ScheduleAsked({ at })` submits
|
|
158
|
+
and saves the form now, and the server keeps the promise. The entry's `state`
|
|
159
|
+
says for when, and whether it happened. The form's own submit is always a
|
|
160
|
+
publish now.
|
|
161
|
+
- **Leaving within the rest.** `open`, `create` and `close` drop what is in the
|
|
162
|
+
form. Run `PostEditor.flush(model)` first, as
|
|
163
|
+
[the example](../../examples/cms/src/app.ts) does: it saves what has not been
|
|
164
|
+
saved, now, and does nothing when there is nothing to save.
|
|
165
|
+
- **A draft never fails to open.** The saved Model is tried first, guarded by the
|
|
166
|
+
form's name and `version`; then the saved values, key by key, keeping what the
|
|
167
|
+
form still accepts; then what is published. `PostEditor.resumed(model)` says
|
|
168
|
+
which: `Model` (shown with nothing in flight: a check that was running when it
|
|
169
|
+
was saved will never answer), `Values`, `Published`, `Blank`, or `Lost`, which is worth
|
|
170
|
+
telling the author. Bump `version` when you change the form incompatibly.
|
|
171
|
+
- **A second author's save is a `Conflict`**, with the text still in the form.
|
|
172
|
+
`ReloadAsked` shows the server's copy; `OverwriteAsked` saves over it, based on
|
|
173
|
+
it. Merging is not attempted.
|
|
174
|
+
- **A taken address lands on the address.** A publish refused with
|
|
175
|
+
`CmsSlugTaken` marks the slug's own field invalid, keeping what was typed, and
|
|
176
|
+
clears when the author edits it. Nothing to wire: the editor does it.
|
|
177
|
+
- **Restoring** a revision replaces what is in the form with that value, as a
|
|
178
|
+
draft. It publishes nothing.
|
|
179
|
+
- **Preview is the application's own views.** Give the content type `preview`,
|
|
180
|
+
the operations an optimistic publish of a value would show, and `PreviewShown`
|
|
181
|
+
lays what is in the form over Remote's store until `PreviewHidden`: every
|
|
182
|
+
Selection and view draws it, edit by edit, and nothing is sent. Only what
|
|
183
|
+
decodes is shown. It is lifted when the editor closes, reloads or discards. No
|
|
184
|
+
`preview`, no preview: `PostEditor.canPreview` says which.
|
|
185
|
+
- **Discarding** shows what is published again; something never published has
|
|
186
|
+
nothing left, and the editor closes.
|
|
187
|
+
- What the server holds is read from Remote and never copied: a save is based on
|
|
188
|
+
the draft's `updatedAt` in the store, a publish on the entry's `revision`. The
|
|
189
|
+
server answers each operation with patches, so nothing is refetched to know them.
|
|
190
|
+
- `create` takes the id so that `update` stays pure: make it in a Command or an
|
|
191
|
+
event handler.
|
|
192
|
+
|
|
193
|
+
## Kinds, and how they are drawn
|
|
194
|
+
|
|
195
|
+
Two controls and two displays, made with `Input.kind` and `Display.kind` exactly
|
|
196
|
+
as you make your own. There is no CMS view package: a kind and its renderer are
|
|
197
|
+
all a view needs.
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
201
|
+
inputs: {
|
|
202
|
+
slug: Cms.slug('title', { prefix: '/blog/' }), // follows the title until the author writes it
|
|
203
|
+
goesLiveAt: Cms.dateTime(), // a datetime-local input, submitted as an ISO string
|
|
204
|
+
},
|
|
205
|
+
})
|
|
206
|
+
|
|
207
|
+
FormView.define(PostForm, { renderers: Cms.controlRenderers() })
|
|
208
|
+
EntryTable({ page, renderers: Cms.displayRenderers() }, h)
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
| Kind | What it is |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| `Cms.Input.Slug` | Text shown after the address it completes. `Cms.slug(from, { prefix?, through? })` makes one that follows `from` through `Cms.slugify`. A form filled with a published slug does not follow: an address must not move because its title did. |
|
|
214
|
+
| `Cms.Input.DateTime` | A moment. Text that is none is `Invalid`, not submitted. |
|
|
215
|
+
| `Cms.Display.State` | An entry's state as words: `Changed, scheduled`, `New, overdue`. `of({ words })` takes yours. Its renderer is a `span` with `data-cms-state` and `data-cms-schedule` to style. |
|
|
216
|
+
| `Cms.Display.Moment` | A time. `of({ now })` reads relative to that clock (`3 days ago`), and you decide how often it moves; without one it is the date and time. Its renderer is a `time`. |
|
|
217
|
+
|
|
218
|
+
`Cms.Entities` already say how they are shown: an entry's `state` is a `State`,
|
|
219
|
+
and its times are `Moment`s, so a `Crud.list` over `Cms.Entries` needs only the
|
|
220
|
+
renderers.
|
|
221
|
+
|
|
222
|
+
## Entities and operations
|
|
223
|
+
|
|
224
|
+
`Cms.Entities` is `Entry`, `Draft` and `Revision`, related: an entry has one
|
|
225
|
+
optional draft and many revisions. They are ordinary Entities. Register them
|
|
226
|
+
with Remote beside your own, and list them with `Crud.list`; an entry's
|
|
227
|
+
`state` is a derived member the server supplies with its clock.
|
|
228
|
+
|
|
229
|
+
`Cms.Operations` is what an author may ask, as Remote mutations: `SaveDraft`,
|
|
230
|
+
`DiscardDraft`, `Publish`, `Unpublish`, `Schedule`, `Unschedule`, `Archive`,
|
|
231
|
+
`Unarchive`, `Restore`. They are the same for every content type. `SaveDraft`
|
|
232
|
+
and `Publish` each carry what they were based on, so a second author's save or
|
|
233
|
+
publish is a conflict and not an overwrite. `Cms.operations` is the list, for
|
|
234
|
+
`Remote.make({ mutations })`.
|
|
235
|
+
|
|
236
|
+
An entry's id is `EntryId`, branded, so an entry is not opened with a post's id.
|
|
237
|
+
The client names something new (`Cms.newEntryId()`), and the first save of an id
|
|
238
|
+
nobody has makes the entry, so an editor need not wait to learn what it edits.
|
|
239
|
+
|
|
240
|
+
## API
|
|
241
|
+
|
|
242
|
+
| Call | Meaning |
|
|
243
|
+
| --- | --- |
|
|
244
|
+
| `Cms.roles({ label?, slug?, published? })` | Pipe step: the members of an Entity that play a CMS part. |
|
|
245
|
+
| `Cms.rolesOf(entity)` | Those roles, as Fields; `undefined` for a part nobody named. |
|
|
246
|
+
| `Cms.content(name, { entity, form, publish, words, preview? })` | A type of content: its Entity, form, publish operations, and name. |
|
|
247
|
+
| `Cms.editor(name, { content, rest?, version?, untitled? })` | The authoring editor: `bundle`, `Message`, and `at({ data, model })`. |
|
|
248
|
+
| `Cms.newEntryId()` | An id for something new. |
|
|
249
|
+
| `Cms.editorView(view)` | A form's Submodel view as its editor's, for `Bundle.withView`. |
|
|
250
|
+
| `Cms.slug(from, options?)`, `Cms.dateTime()`, `Cms.slugify(text)` | Controls for a form's `inputs`. |
|
|
251
|
+
| `Cms.Input.{Slug, DateTime}`, `Cms.Display.{State, Moment}` | The kinds: `.of(data)`, `.is(x)`. |
|
|
252
|
+
| `Cms.controlRenderers()`, `Cms.displayRenderers()` | Their renderers, to spread beside the mixins' own. |
|
|
253
|
+
| `Cms.state(facts, now)` | The state of an entry, with its schedule. |
|
|
254
|
+
| `Cms.offers(facts, now, content)` | The transitions it offers now. |
|
|
255
|
+
| `Cms.Entities`, `Cms.Operations`, `Cms.operations` | The CMS's own Entities and mutations. |
|
|
256
|
+
| `Cms.Entries` | The worklist query: one content type's entries, by label, archived or not. |
|
|
257
|
+
| `Cms.bySlug(content)` | The query `<name>BySlug`: the content at an address, a connection of one or none. Throws with no `slug` role. |
|
|
258
|
+
| `Cms.slugTaken.key(message)` | The form key a server's `CmsSlugTaken: ...` error names, or `undefined`. |
|
|
259
|
+
|
|
260
|
+
## Example
|
|
261
|
+
|
|
262
|
+
[`examples/cms`](../../examples/cms) takes a post from its first keystroke to being
|
|
263
|
+
taken off show, from a writer's, an editor's and a visitor's chair, over SQLite,
|
|
264
|
+
with its transcript pinned by a test.
|
|
265
|
+
|
|
266
|
+
## Limits
|
|
267
|
+
|
|
268
|
+
- A revision list is a `Crud.list` you declare over `Cms.Entities.Revision`.
|
|
269
|
+
- Preview is for the author, in their own session. A link someone else can open
|
|
270
|
+
is an audience, and is [later](../../docs/design/cms-DESIGN.md#14-later-and-how-each-would-attach).
|
|
271
|
+
- The editor has no view of its own: render the form with `foldkit-mixins-form`,
|
|
272
|
+
and the status and buttons yourself.
|
|
273
|
+
- An address is checked while typing by `Cms.addressFree('posts')`, added with
|
|
274
|
+
the `Form.checks` step. It is advice, not the rule: two authors can both be
|
|
275
|
+
told an address is free and both publish, and the server refuses the second on
|
|
276
|
+
the same key. Put a unique index on the column.
|
|
277
|
+
- One working draft per entry, not one per author.
|
|
278
|
+
- Media, rich text, localization, and review states beyond "who may publish" are
|
|
279
|
+
[later](../../docs/design/cms-DESIGN.md#14-later-and-how-each-would-attach).
|