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 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).