foldkit-mixins-surface 0.1.0 → 0.2.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/README.md +112 -21
- package/package.json +16 -6
package/README.md
CHANGED
|
@@ -1,32 +1,113 @@
|
|
|
1
1
|
# foldkit-mixins-surface
|
|
2
2
|
|
|
3
|
-
Bridges [`foldkit-surface`](
|
|
4
|
-
[`foldkit-mixins`](
|
|
3
|
+
Bridges [`foldkit-surface`](https://github.com/doeixd/foldkit-plus/tree/main/packages/surface)'s projected Model and Message subset to
|
|
4
|
+
[`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins) SlotViews.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
6
|
+
A Surface is a narrowed window onto an application: it projects a few fields of
|
|
7
|
+
the root Model and names the few Messages it may emit. A SlotView is a view that
|
|
8
|
+
publishes attachment points for Style and Behavior. On their own, nothing
|
|
9
|
+
connects the two: `SlotView.define` takes whatever input type and Message
|
|
10
|
+
universe you annotate, so nothing stops an attachment from reading a field the
|
|
11
|
+
Surface does not project, or emitting a Message it does not expose.
|
|
12
|
+
|
|
13
|
+
`SurfaceView.define` closes that gap. It is one function that pins a SlotView's
|
|
14
|
+
input type to the Surface's projection and its Message universe to the Surface's
|
|
15
|
+
subset. A Style or Behavior attached to the result can only read projected
|
|
16
|
+
fields, and can only emit exposed Messages — both are compile errors otherwise,
|
|
17
|
+
in the attachment rather than at the application boundary. It creates no state
|
|
18
|
+
and no rendering machinery; the result is an ordinary `SlotView`.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm add foldkit-mixins foldkit-surface foldkit-mixins-surface
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`foldkit`, `effect`, `foldkit-mixins`, and `foldkit-surface` are peer
|
|
27
|
+
dependencies.
|
|
28
|
+
|
|
29
|
+
## Use it when
|
|
30
|
+
|
|
31
|
+
You already render a Surface and want to style or decorate it from outside.
|
|
32
|
+
If you are not using `foldkit-surface`, use `SlotView.define` from
|
|
33
|
+
`foldkit-mixins` directly — this package adds nothing else.
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
12
36
|
|
|
13
37
|
```ts
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
38
|
+
import { Schema } from 'effect'
|
|
39
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
40
|
+
import { Behavior, Capability, Event, Slot, Slots, Style } from 'foldkit-mixins'
|
|
41
|
+
import { SurfaceView } from 'foldkit-mixins-surface'
|
|
42
|
+
import { Projection, Surface } from 'foldkit-surface'
|
|
43
|
+
|
|
44
|
+
const Model = Schema.Struct({
|
|
45
|
+
todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
|
|
46
|
+
selectedId: Schema.NullOr(Schema.String),
|
|
47
|
+
secret: Schema.String,
|
|
48
|
+
})
|
|
49
|
+
|
|
50
|
+
const Message = defineMessageUnion({
|
|
51
|
+
SelectedTodo: { id: Schema.String },
|
|
52
|
+
ArchivedTodo: { id: Schema.String },
|
|
53
|
+
ClearedSecret: {},
|
|
54
|
+
})
|
|
17
55
|
|
|
18
|
-
Surface.
|
|
56
|
+
const App = Surface.application({ Model, Message })
|
|
57
|
+
|
|
58
|
+
// Projects two of the three fields, exposes two of the three Messages.
|
|
59
|
+
const TodoList = Surface.make(App, 'TodoList', {
|
|
60
|
+
model: ({ model }) => Projection.struct({ todos: model.todos, selectedId: model.selectedId }),
|
|
61
|
+
messages: [Message.SelectedTodo, Message.ArchivedTodo],
|
|
62
|
+
})
|
|
63
|
+
|
|
64
|
+
const TodoSlots = Slots.define({
|
|
65
|
+
root: Slot.make({ capability: Capability.Container }),
|
|
66
|
+
archive: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
|
|
67
|
+
})
|
|
68
|
+
|
|
69
|
+
const TodoStyle = Style.forSlots(TodoSlots)({ root: Style.class('todo-list') })
|
|
70
|
+
|
|
71
|
+
/** What the Surface projects — the input every attachment sees. */
|
|
72
|
+
type ProjectedTodos = {
|
|
73
|
+
readonly todos: ReadonlyArray<{ readonly id: string; readonly title: string }>
|
|
74
|
+
readonly selectedId: string | null
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// `input` is the projection, so `input.secret` does not type-check; `h` builds
|
|
78
|
+
// only `SelectedTodo` and `ArchivedTodo`.
|
|
79
|
+
const TodoBehavior = Behavior.forSlots(TodoSlots)<
|
|
80
|
+
ProjectedTodos,
|
|
81
|
+
typeof Message.SelectedTodo.Type | typeof Message.ArchivedTodo.Type
|
|
82
|
+
>({
|
|
83
|
+
archive: Behavior.slot({
|
|
84
|
+
requires: { events: [Event.Click] },
|
|
85
|
+
attributes: ({ input, h }) =>
|
|
86
|
+
input.selectedId === null ? [] : [h.OnClick(Message.ArchivedTodo({ id: input.selectedId }))],
|
|
87
|
+
}),
|
|
88
|
+
})
|
|
89
|
+
|
|
90
|
+
const TodoListView = SurfaceView.define(TodoList, TodoSlots, (model, slots, h) =>
|
|
91
|
+
h.ul(
|
|
92
|
+
slots.root.attrs(),
|
|
93
|
+
model.todos.map(todo => h.li([], [todo.title])),
|
|
94
|
+
),
|
|
95
|
+
).pipe(Style.attach(TodoStyle), Behavior.attach(TodoBehavior))
|
|
96
|
+
|
|
97
|
+
// `toRenderer` adapts a SlotView to what `Surface.view`/`Surface.rootView` take.
|
|
98
|
+
const renderer = Surface.view(TodoList, SurfaceView.toRenderer(TodoListView))
|
|
19
99
|
```
|
|
20
100
|
|
|
21
|
-
|
|
101
|
+
Note what the render callback does not need: no type annotation on `model` or
|
|
102
|
+
`h`. `SlotView.define` infers its Message universe from the builder you annotate;
|
|
103
|
+
`SurfaceView.define` takes it from the Surface. A Behavior's `Input` parameter,
|
|
104
|
+
though, has to be exactly the projected type — a `SlotView` is invariant in it,
|
|
105
|
+
so a narrower "just the fields I read" type is rejected by `Behavior.attach`.
|
|
22
106
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
- The result is an ordinary core `SlotView`, so the core attach/pipe algebra
|
|
28
|
-
applies unchanged. `toRenderer` is the single boundary cast, the same one
|
|
29
|
-
`Surface.rootView` makes.
|
|
107
|
+
`toRenderer` is the single boundary cast, the same one `Surface.rootView` makes:
|
|
108
|
+
`Surface.view` hands a renderer a `ViewBuilder` — the real builder with its
|
|
109
|
+
`MessageUniverse` phantom removed — and this is the matching adaptation, sound
|
|
110
|
+
because the renderer can only construct the Surface's Messages.
|
|
30
111
|
|
|
31
112
|
## Introspection
|
|
32
113
|
|
|
@@ -36,4 +117,14 @@ functions. `SurfaceView.describe(surface, params, view)` merges that with
|
|
|
36
117
|
emitted Messages as tags — into one value, and `SurfaceView.toMarkdown` renders it
|
|
37
118
|
deterministically for docs or a CI drift check.
|
|
38
119
|
|
|
39
|
-
|
|
120
|
+
Each of `define`, `toRenderer`, `inspect`, `describe` and `toMarkdown` is also a
|
|
121
|
+
direct named export, if you prefer that to the `SurfaceView` namespace.
|
|
122
|
+
|
|
123
|
+
The API is still settling (`0.1.0`). See [DESIGN.md](https://github.com/doeixd/foldkit-plus/blob/main/docs/design/mixins-DESIGN.md).
|
|
124
|
+
|
|
125
|
+
## See also
|
|
126
|
+
|
|
127
|
+
- [Inside-out view composition](https://github.com/doeixd/foldkit-plus/blob/main/docs/mixins.md) — the mental model.
|
|
128
|
+
- [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins) — the resolver, Style, and Behavior; [`foldkit-surface`](https://github.com/doeixd/foldkit-plus/tree/main/packages/surface) — the
|
|
129
|
+
projection this bridges.
|
|
130
|
+
- [`examples/mixins`](https://github.com/doeixd/foldkit-plus/tree/main/examples/mixins) — Surface to SlotView, end to end.
|
package/package.json
CHANGED
|
@@ -1,9 +1,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldkit-mixins-surface",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Bridge foldkit-surface's projected Model and Message subset to foldkit-mixins SlotViews.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"foldkit",
|
|
7
|
+
"effect",
|
|
8
|
+
"slots",
|
|
9
|
+
"projection",
|
|
10
|
+
"view-composition"
|
|
11
|
+
],
|
|
5
12
|
"type": "module",
|
|
6
13
|
"license": "MIT",
|
|
14
|
+
"publishConfig": {
|
|
15
|
+
"access": "public"
|
|
16
|
+
},
|
|
7
17
|
"author": "Patrick Glenn <doeixd@gmail.com>",
|
|
8
18
|
"repository": {
|
|
9
19
|
"type": "git",
|
|
@@ -29,8 +39,8 @@
|
|
|
29
39
|
"peerDependencies": {
|
|
30
40
|
"effect": "^4.0.0-rc.112",
|
|
31
41
|
"foldkit": "^0.158.2",
|
|
32
|
-
"foldkit-
|
|
33
|
-
"foldkit-
|
|
42
|
+
"foldkit-mixins": "^0.2.0",
|
|
43
|
+
"foldkit-surface": "^0.1.1"
|
|
34
44
|
},
|
|
35
45
|
"devDependencies": {
|
|
36
46
|
"@foldkit/ui": "0.158.2",
|
|
@@ -38,9 +48,9 @@
|
|
|
38
48
|
"foldkit": "0.158.2",
|
|
39
49
|
"tsdown": "^0.23.0",
|
|
40
50
|
"typescript": "^5.7.2",
|
|
41
|
-
"foldkit-mixins": "0.
|
|
42
|
-
"foldkit-mixins
|
|
43
|
-
"foldkit-surface": "0.1.
|
|
51
|
+
"foldkit-mixins-ui": "0.2.0",
|
|
52
|
+
"foldkit-mixins": "0.2.0",
|
|
53
|
+
"foldkit-surface": "0.1.1"
|
|
44
54
|
},
|
|
45
55
|
"scripts": {
|
|
46
56
|
"build": "tsdown",
|