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.
Files changed (2) hide show
  1. package/README.md +112 -21
  2. package/package.json +16 -6
package/README.md CHANGED
@@ -1,32 +1,113 @@
1
1
  # foldkit-mixins-surface
2
2
 
3
- Bridges [`foldkit-surface`](../surface)'s projected Model and Message subset to
4
- [`foldkit-mixins`](../mixins) SlotViews.
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
- `SurfaceView.define(surface, slots, render)` returns an ordinary `SlotView`: the
7
- renderer's input is the Surface's projected Model, so Style and Behavior
8
- contributions can only read what the Surface projects, and its builder is typed
9
- with the Surface's Message subset, so a Behavior cannot emit a Message the
10
- Surface does not expose. `SurfaceView.toRenderer` adapts the result to the
11
- `Renderer` that `Surface.view`/`Surface.rootView` expect.
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
- const TodoCardView = SurfaceView.define(TodoSurface, TodoSlots, (model, slots, h) =>
15
- h.li(slots.root.attrs(), [model.title]),
16
- ).pipe(Style.attach(TodoCardStyle), Behavior.attach(TodoCardBehavior))
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.view(TodoSurface, SurfaceView.toRenderer(TodoCardView))
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
- ## What the bridge enforces
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
- - The renderer's input is the Surface's projected Model, so a Style/Behavior
24
- callback cannot read the root Model.
25
- - The builder is typed with the Surface's Message subset, so a Behavior cannot
26
- emit a Message the Surface does not expose.
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
- The API is still settling (`0.1.0`). See [DESIGN.md](../../docs/design/mixins-DESIGN.md).
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.1.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-surface": "^0.1.0",
33
- "foldkit-mixins": "^0.1.0"
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.1.0",
42
- "foldkit-mixins-ui": "0.1.0",
43
- "foldkit-surface": "0.1.0"
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",