foldkit-mixins-surface 0.1.0 → 0.3.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 CHANGED
@@ -1,39 +1,188 @@
1
- # foldkit-mixins-surface
1
+ # `foldkit-mixins-surface`
2
2
 
3
- Bridges [`foldkit-surface`](../surface)'s projected Model and Message subset to
4
- [`foldkit-mixins`](../mixins) SlotViews.
3
+ Connects a [`foldkit-surface`](https://github.com/doeixd/foldkit-plus/tree/main/packages/surface)
4
+ feature boundary to a [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins)
5
+ `SlotView` without repeating that boundary in the view layer.
5
6
 
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.
7
+ The two packages answer different questions:
8
+
9
+ ```text
10
+ Surface -> what may this feature observe and which Messages may it emit?
11
+ SlotView -> where may this view be customized with Style and Behavior?
12
+ ```
13
+
14
+ `SurfaceView.define` joins them. The SlotView's input becomes exactly the
15
+ Surface's projected value, and its Message universe becomes exactly the
16
+ Surface's exposed subset. A Behavior cannot quietly read a root-Model field the
17
+ Surface omitted or emit a Message the feature did not expose; both mistakes are
18
+ type errors where the view is defined.
19
+
20
+ The bridge creates no state, no renderer, and no second runtime. The result is
21
+ an ordinary `SlotView` with the Surface's boundary reflected in its types.
22
+
23
+ ## Use it when
24
+
25
+ You already render a Surface and want to style or decorate that feature through
26
+ typed Mixins extension points. If you are not using `foldkit-surface`, use
27
+ `SlotView.define` / `SlotView.forMessages` from `foldkit-mixins` directly — this
28
+ package adds nothing else.
29
+
30
+ For the Mixins mental model itself (Slot, Style, Behavior, SlotView), read
31
+ [Inside-out view composition](https://github.com/doeixd/foldkit-plus/blob/main/docs/mixins.md)
32
+ first.
33
+
34
+ ## Install
35
+
36
+ ```bash
37
+ pnpm add foldkit-mixins foldkit-surface foldkit-mixins-surface
38
+ ```
39
+
40
+ `foldkit`, `effect`, `foldkit-mixins`, and `foldkit-surface` are peer
41
+ dependencies.
42
+
43
+ ## Usage
12
44
 
13
45
  ```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))
46
+ import { Schema } from 'effect'
47
+ import { defineMessageUnion } from 'foldkit/message'
48
+ import { Behavior, Capability, Event, Slot, Slots, Style } from 'foldkit-mixins'
49
+ import { SurfaceView } from 'foldkit-mixins-surface'
50
+ import { Surface } from 'foldkit-surface'
51
+
52
+ const Model = Schema.Struct({
53
+ todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
54
+ selectedId: Schema.NullOr(Schema.String),
55
+ secret: Schema.String,
56
+ })
57
+
58
+ const Message = defineMessageUnion({
59
+ SelectedTodo: { id: Schema.String },
60
+ ArchivedTodo: { id: Schema.String },
61
+ ClearedSecret: {},
62
+ })
63
+
64
+ const App = Surface.application({ Model, Message })
65
+
66
+ // Projects two of the three fields, exposes two of the three Messages.
67
+ const TodoList = App.surface('TodoList', {
68
+ model: ({ model }) => ({ todos: model.todos, selectedId: model.selectedId }),
69
+ messages: [Message.SelectedTodo, Message.ArchivedTodo],
70
+ })
71
+
72
+ const TodoSlots = Slots.define({
73
+ root: Slot.make({ capability: Capability.Container }),
74
+ archive: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
75
+ })
76
+
77
+ const TodoStyle = Style.forSlots(TodoSlots)({ root: Style.class('todo-list') })
78
+
79
+ /** What the Surface projects — the input every attachment sees. */
80
+ type ProjectedTodos = {
81
+ readonly todos: ReadonlyArray<{ readonly id: string; readonly title: string }>
82
+ readonly selectedId: string | null
83
+ }
84
+
85
+ // `input` is the projection, so `input.secret` does not type-check; `h` builds
86
+ // only `SelectedTodo` and `ArchivedTodo`.
87
+ const TodoBehavior = Behavior.forSlots(TodoSlots)<
88
+ ProjectedTodos,
89
+ typeof Message.SelectedTodo.Type | typeof Message.ArchivedTodo.Type
90
+ >({
91
+ archive: Behavior.slot({
92
+ requires: { events: [Event.Click] },
93
+ attributes: ({ input, h }) =>
94
+ input.selectedId === null ? [] : [h.OnClick(Message.ArchivedTodo({ id: input.selectedId }))],
95
+ }),
96
+ })
17
97
 
18
- Surface.view(TodoSurface, SurfaceView.toRenderer(TodoCardView))
98
+ const TodoListView = SurfaceView.define(TodoList, TodoSlots, (model, slots, h) =>
99
+ h.ul(
100
+ slots.root.attrs(),
101
+ model.todos.map(todo => h.li([], [todo.title])),
102
+ ),
103
+ ).pipe(Style.attach(TodoStyle), Behavior.attach(TodoBehavior))
104
+
105
+ // `toRenderer` adapts a SlotView to what `Surface.view`/`Surface.rootView` take.
106
+ const renderer = Surface.view(TodoList, SurfaceView.toRenderer(TodoListView))
107
+ ```
108
+
109
+ The useful part is what the render callback does **not** repeat: no type
110
+ annotation on `model` or `h`, no second Message union, and no root-Model input
111
+ type. `SurfaceView.define` gets those from the Surface.
112
+
113
+ A Behavior's `Input` parameter still has to be exactly the projected type — a
114
+ `SlotView` is invariant in it, so a narrower "just the fields I happen to read"
115
+ type is rejected by `Behavior.attach`.
116
+
117
+ `toRenderer` is the single boundary adaptation. `Surface.view` hands a renderer
118
+ a `ViewBuilder` with its `MessageUniverse` phantom removed; the SlotView is sound
119
+ there because `SurfaceView.define` already restricted what it can construct to
120
+ the Surface's Message subset.
121
+
122
+ ## What the bridge buys you
123
+
124
+ Without this package, Surface and SlotView are both type-safe independently, but
125
+ you can accidentally describe the same feature boundary twice:
126
+
127
+ ```text
128
+ Surface projection / Message subset
129
+ X
130
+ SlotView input / Message universe
19
131
  ```
20
132
 
21
- ## What the bridge enforces
133
+ With `SurfaceView.define`, there is one declaration:
134
+
135
+ ```text
136
+ Surface
137
+ │
138
+ ├─ projected value ──────────────┐
139
+ └─ Message subset ────────────┐ │
140
+ ▼ ▼
141
+ SlotView
142
+ │
143
+ Style + Behavior
144
+ ```
22
145
 
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.
146
+ That is the whole package.
147
+
148
+ ## Rendering without a runtime
149
+
150
+ `SurfaceView.render(view, surface, params, root)` projects `root` through the
151
+ Surface and renders the view with `SlotView.inertBuilder`. It returns the
152
+ `Html`, but nothing mounts and handlers are built without ever being
153
+ dispatched. It is for tests, demos, and static output, not a replacement for
154
+ `Surface.view` in a running app.
155
+
156
+ ```ts
157
+ const html = SurfaceView.render(TodoListView, TodoList, undefined, {
158
+ todos: [{ id: 't1', title: 'Write docs' }],
159
+ selectedId: 't1',
160
+ secret: 'not projected',
161
+ })
162
+ ```
30
163
 
31
164
  ## Introspection
32
165
 
33
- `SurfaceView.inspect(view)` returns serializable `{ name, slots, mixins }` with no
34
- functions. `SurfaceView.describe(surface, params, view)` merges that with
35
- `Surface.inspect` — what the Surface observes, requires, and may emit, with
36
- emitted Messages as tags — into one value, and `SurfaceView.toMarkdown` renders it
37
- deterministically for docs or a CI drift check.
166
+ `SurfaceView.inspect(view)` returns serializable `{ name, slots, mixins }` with
167
+ no functions. `SurfaceView.describe(surface, params, view)` merges that with
168
+ `Surface.inspect` — what the Surface observes, its projection `metadata`, and
169
+ what it may emit, with emitted Messages as tags — into one value.
170
+ `SurfaceView.toMarkdown` renders it deterministically for docs or a CI drift
171
+ check.
172
+
173
+ Each of `define`, `toRenderer`, `render`, `inspect`, `describe`, and `toMarkdown` is also a
174
+ direct named export if you prefer that to the `SurfaceView` namespace.
175
+
176
+ ## Status
177
+
178
+ The API is still settling in the `0.x` series. This is deliberately a small
179
+ bridge rather than a second view system; changes should keep it that way. See
180
+ [the design note](https://github.com/doeixd/foldkit-plus/blob/main/docs/design/mixins-DESIGN.md)
181
+ for the underlying Mixins decisions.
182
+
183
+ ## See also
38
184
 
39
- The API is still settling (`0.1.0`). See [DESIGN.md](../../docs/design/mixins-DESIGN.md).
185
+ - [Inside-out view composition](https://github.com/doeixd/foldkit-plus/blob/main/docs/mixins.md) — the Mixins mental model and before/after examples.
186
+ - [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins) — SlotView, Style, Behavior, and the resolver.
187
+ - [`foldkit-surface`](https://github.com/doeixd/foldkit-plus/tree/main/packages/surface) — the projection/capability boundary this package preserves.
188
+ - [`examples/mixins`](https://github.com/doeixd/foldkit-plus/tree/main/examples/mixins) — Surface → SlotView end to end.
package/dist/index.d.mts CHANGED
@@ -1,7 +1,8 @@
1
- import { Renderer, Requirement, Surface } from "foldkit-surface";
1
+ import { MetadataSummary, Renderer, Surface } from "foldkit-surface";
2
2
  import { SlotView, SlotViewRender, Slots } from "foldkit-mixins";
3
+ import { Html } from "foldkit/html";
3
4
  declare namespace surfaceView_d_exports {
4
- export { SurfaceViewDescription, SurfaceViewInspection, define, describe, inspect, toMarkdown, toRenderer };
5
+ export { SurfaceViewDescription, SurfaceViewInspection, define, describe, inspect, render, toMarkdown, toRenderer };
5
6
  }
6
7
  export declare const define: <Root, Model, Message, Params, Slots_>(surface: Surface<Root, Model, Message, Params>, slots: Slots_, render: SlotViewRender<Slots_, Model, Message>, options?: {
7
8
  readonly name?: string;
@@ -13,6 +14,12 @@ export declare const define: <Root, Model, Message, Params, Slots_>(surface: Sur
13
14
  * constructs the Surface's Message subset.
14
15
  */
15
16
  export declare const toRenderer: <Slots_, Model, Message>(view: SlotView.SlotView<Slots_, Model, Message>) => Renderer<Model, Message>;
17
+ /**
18
+ * Renders a SlotView for `surface`'s projection of `root` with an inert
19
+ * builder: no runtime, so handlers are built but never dispatched. For demos,
20
+ * tests, and static output.
21
+ */
22
+ export declare const render: <Root, Model, Message, Params, Slots_>(view: SlotView.SlotView<Slots_, Model, Message>, surface: Surface<Root, Model, Message, Params>, params: Params, root: Root) => Html;
16
23
  interface SurfaceViewInspection {
17
24
  /** The SlotView's name, defaulted from the Surface's name. */
18
25
  readonly name: string;
@@ -28,7 +35,7 @@ export declare const inspect: <Slots_, Model, Message>(view: SlotView.SlotView<S
28
35
  interface SurfaceViewDescription {
29
36
  readonly name: string;
30
37
  readonly observes: ReturnType<typeof Surface.inspect>['dependencies'];
31
- readonly requirements: ReadonlyArray<Requirement>;
38
+ readonly metadata: ReadonlyArray<MetadataSummary>;
32
39
  /** Emitted Message tags, not constructors, so the value stays serializable. */
33
40
  readonly emits: ReadonlyArray<string>;
34
41
  readonly slots: ReturnType<typeof Slots.describe>['slots'];
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/surfaceView.ts"],"mappings":";;;;;qBAaa,SAAU,MAAM,OAAO,SAAS,QAAQ,QACnD,SAAS,QAAQ,MAAM,OAAO,SAAS,SACvC,OAAO,QACP,QAAQ,eAAe,QAAQ,OAAO,UACtC;WAAqB;MACpB,SAAS,SAAS,QAAQ,OAAO;;;;;;;qBAWvB,aACV,QAAQ,OAAO,SACd,MAAM,SAAS,SAAS,QAAQ,OAAO,aACtC,SAAS,OAAO;UAIJ;;WAEN;WACA,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;qBAQN,UAAW,QAAQ,OAAO,SACrC,MAAM,SAAS,SAAS,QAAQ,OAAO,aACtC;UAec;WACN;WACA,UAAU,kBAAkB,QAAQ;WACpC,cAAc,cAAc;;WAE5B,OAAO;WACP,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;qBAQN,WAAY,MAAM,OAAO,SAAS,QAAQ,QACrD,SAAS,QAAQ,MAAM,OAAO,SAAS,SACvC,QAAQ,QACR,MAAM,SAAS,SAAS,QAAQ,OAAO,aACtC;;qBAcU,aAAc,aAAa"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/surfaceView.ts"],"mappings":";;;;;;qBAaa,SAAU,MAAM,OAAO,SAAS,QAAQ,QACnD,SAAS,QAAQ,MAAM,OAAO,SAAS,SACvC,OAAO,QACP,QAAQ,eAAe,QAAQ,OAAO,UACtC;WAAqB;MACpB,SAAS,SAAS,QAAQ,OAAO;;;;;;;qBAWvB,aACV,QAAQ,OAAO,SACd,MAAM,SAAS,SAAS,QAAQ,OAAO,aACtC,SAAS,OAAO;;;;;;qBASR,SAAU,MAAM,OAAO,SAAS,QAAQ,QACnD,MAAM,SAAS,SAAS,QAAQ,OAAO,UACvC,SAAS,QAAQ,MAAM,OAAO,SAAS,SACvC,QAAQ,QACR,MAAM,SACL;UAGc;;WAEN;WACA,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;qBAQN,UAAW,QAAQ,OAAO,SACrC,MAAM,SAAS,SAAS,QAAQ,OAAO,aACtC;UAec;WACN;WACA,UAAU,kBAAkB,QAAQ;WACpC,UAAU,cAAc;;WAExB,OAAO;WACP,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;qBAQN,WAAY,MAAM,OAAO,SAAS,QAAQ,QACrD,SAAS,QAAQ,MAAM,OAAO,SAAS,SACvC,QAAQ,QACR,MAAM,SAAS,SAAS,QAAQ,OAAO,aACtC;;qBAcU,aAAc,aAAa"}
package/dist/index.mjs CHANGED
@@ -6,6 +6,7 @@ var surfaceView_exports = /* @__PURE__ */ __exportAll({
6
6
  define: () => define,
7
7
  describe: () => describe,
8
8
  inspect: () => inspect,
9
+ render: () => render,
9
10
  toMarkdown: () => toMarkdown,
10
11
  toRenderer: () => toRenderer
11
12
  });
@@ -18,6 +19,12 @@ const define = (surface, slots, render, options) => SlotView.define(slots, rende
18
19
  */
19
20
  const toRenderer = (view) => (model, h) => view(model, h);
20
21
  /**
22
+ * Renders a SlotView for `surface`'s projection of `root` with an inert
23
+ * builder: no runtime, so handlers are built but never dispatched. For demos,
24
+ * tests, and static output.
25
+ */
26
+ const render = (view, surface, params, root) => Surface.rootView(surface, params, toRenderer(view))(root, SlotView.inertBuilder());
27
+ /**
21
28
  * Serializable metadata for DevTools and docs: the published slots and the
22
29
  * names of the attached Mixins, with no functions. It composes with
23
30
  * `Surface.inspect`, which reports what the Surface observes and emits.
@@ -45,7 +52,7 @@ const describe = (surface, params, view) => {
45
52
  return {
46
53
  name: ui.name === "" ? inspection.name : ui.name,
47
54
  observes: inspection.dependencies,
48
- requirements: inspection.requirements,
55
+ metadata: inspection.metadata,
49
56
  emits: inspection.emits.map(constructorTag),
50
57
  slots: ui.slots,
51
58
  mixins: ui.mixins
@@ -72,6 +79,6 @@ const toMarkdown = (description) => {
72
79
  return lines.join("\n");
73
80
  };
74
81
  //#endregion
75
- export { surfaceView_exports as SurfaceView, define, describe, inspect, toMarkdown, toRenderer };
82
+ export { surfaceView_exports as SurfaceView, define, describe, inspect, render, toMarkdown, toRenderer };
76
83
 
77
84
  //# sourceMappingURL=index.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../src/surfaceView.ts"],"sourcesContent":["/**\n * Binds a Surface's projected Model and Message subset to a SlotView.\n *\n * The renderer's input is the Surface's projected Model, so Style and Behavior\n * contributions can only read what the Surface projects. Its builder is typed\n * with the Surface's Message subset, so a Behavior cannot emit a Message the\n * Surface does not expose. The returned value is an ordinary `SlotView`, so the\n * core attach/pipe algebra applies unchanged.\n */\nimport type { HtmlBuilder } from 'foldkit/html'\nimport { Surface, type Requirement, type Renderer } from 'foldkit-surface'\nimport { Slots, SlotView, type SlotViewRender } from 'foldkit-mixins'\n\nexport const define = <Root, Model, Message, Params, Slots_>(\n surface: Surface<Root, Model, Message, Params>,\n slots: Slots_,\n render: SlotViewRender<Slots_, Model, Message>,\n options?: { readonly name?: string },\n): SlotView.SlotView<Slots_, Model, Message> =>\n SlotView.define<Slots_, Model, Message>(slots, render, {\n name: options?.name ?? surface.name,\n })\n\n/**\n * Adapts a SlotView to a Surface renderer. `Surface.view` hands a renderer a\n * `ViewBuilder` — the real builder with its `MessageUniverse` phantom removed —\n * and this is the matching boundary cast, sound because the renderer only\n * constructs the Surface's Message subset.\n */\nexport const toRenderer =\n <Slots_, Model, Message>(\n view: SlotView.SlotView<Slots_, Model, Message>,\n ): Renderer<Model, Message> =>\n (model, h) =>\n view(model, h as unknown as HtmlBuilder<Message>)\n\nexport interface SurfaceViewInspection {\n /** The SlotView's name, defaulted from the Surface's name. */\n readonly name: string\n readonly slots: ReturnType<typeof Slots.describe>['slots']\n readonly mixins: ReadonlyArray<string>\n}\n\n/**\n * Serializable metadata for DevTools and docs: the published slots and the\n * names of the attached Mixins, with no functions. It composes with\n * `Surface.inspect`, which reports what the Surface observes and emits.\n */\nexport const inspect = <Slots_, Model, Message>(\n view: SlotView.SlotView<Slots_, Model, Message>,\n): SurfaceViewInspection => ({\n name: view.name ?? '',\n slots: Slots.describe(view.slots as unknown as Parameters<typeof Slots.describe>[0]).slots,\n mixins: view.mixins.map(mixin => mixin.name),\n})\n\n/** Reads the tag off a Foldkit Message constructor without constructing one. */\nconst constructorTag = (constructor: unknown): string => {\n const literal = (constructor as { fields?: { _tag?: { ast?: { literal?: unknown } } } }).fields\n ?._tag?.ast?.literal\n if (typeof literal === 'string') return literal\n const name = (constructor as { readonly name?: unknown }).name\n return typeof name === 'string' ? name : 'unknown'\n}\n\nexport interface SurfaceViewDescription {\n readonly name: string\n readonly observes: ReturnType<typeof Surface.inspect>['dependencies']\n readonly requirements: ReadonlyArray<Requirement>\n /** Emitted Message tags, not constructors, so the value stays serializable. */\n readonly emits: ReadonlyArray<string>\n readonly slots: ReturnType<typeof Slots.describe>['slots']\n readonly mixins: ReadonlyArray<string>\n}\n\n/**\n * One serializable description of a Surface and the SlotView that renders it:\n * what it observes and may emit, and where Style/Behavior attach. No functions,\n * so it can be committed, diffed, or handed to DevTools and agent tooling.\n */\nexport const describe = <Root, Model, Message, Params, Slots_>(\n surface: Surface<Root, Model, Message, Params>,\n params: Params,\n view: SlotView.SlotView<Slots_, Model, Message>,\n): SurfaceViewDescription => {\n const inspection = Surface.inspect(surface, params)\n const ui = inspect(view)\n return {\n name: ui.name === '' ? inspection.name : ui.name,\n observes: inspection.dependencies,\n requirements: inspection.requirements,\n emits: inspection.emits.map(constructorTag),\n slots: ui.slots,\n mixins: ui.mixins,\n }\n}\n\n/** Deterministic Markdown for a description; stable key order, no timestamps. */\nexport const toMarkdown = (description: SurfaceViewDescription): string => {\n const lines: string[] = [`# ${description.name}`, '', '## Observes', '']\n for (const path of description.observes) lines.push(`- \\`${path.join('.')}\\``)\n lines.push('', '## May emit', '')\n for (const tag of description.emits) lines.push(`- \\`${tag}\\``)\n lines.push('', '## Slots', '')\n for (const [name, slot] of Object.entries(description.slots)) {\n const events = slot.events.length === 0 ? '' : ` (events: ${slot.events.join(', ')})`\n lines.push(`- \\`${name}\\` — ${slot.capability}${events}`)\n }\n lines.push('', '## Mixins', '')\n for (const name of description.mixins) lines.push(`- \\`${name}\\``)\n return lines.join('\\n')\n}\n"],"mappings":";;;;;;;;;;;AAaA,MAAa,UACX,SACA,OACA,QACA,YAEA,SAAS,OAA+B,OAAO,QAAQ,EACrD,MAAM,SAAS,QAAQ,QAAQ,KACjC,CAAC;;;;;;;AAQH,MAAa,cAET,UAED,OAAO,MACN,KAAK,OAAO,CAAoC;;;;;;AAcpD,MAAa,WACX,UAC2B;CAC3B,MAAM,KAAK,QAAQ;CACnB,OAAO,MAAM,SAAS,KAAK,KAAwD,CAAC,CAAC;CACrF,QAAQ,KAAK,OAAO,KAAI,UAAS,MAAM,IAAI;AAC7C;;AAGA,MAAM,kBAAkB,gBAAiC;CACvD,MAAM,UAAW,YAAwE,QACrF,MAAM,KAAK;CACf,IAAI,OAAO,YAAY,UAAU,OAAO;CACxC,MAAM,OAAQ,YAA4C;CAC1D,OAAO,OAAO,SAAS,WAAW,OAAO;AAC3C;;;;;;AAiBA,MAAa,YACX,SACA,QACA,SAC2B;CAC3B,MAAM,aAAa,QAAQ,QAAQ,SAAS,MAAM;CAClD,MAAM,KAAK,QAAQ,IAAI;CACvB,OAAO;EACL,MAAM,GAAG,SAAS,KAAK,WAAW,OAAO,GAAG;EAC5C,UAAU,WAAW;EACrB,cAAc,WAAW;EACzB,OAAO,WAAW,MAAM,IAAI,cAAc;EAC1C,OAAO,GAAG;EACV,QAAQ,GAAG;CACb;AACF;;AAGA,MAAa,cAAc,gBAAgD;CACzE,MAAM,QAAkB;EAAC,KAAK,YAAY;EAAQ;EAAI;EAAe;CAAE;CACvE,KAAK,MAAM,QAAQ,YAAY,UAAU,MAAM,KAAK,OAAO,KAAK,KAAK,GAAG,EAAE,GAAG;CAC7E,MAAM,KAAK,IAAI,eAAe,EAAE;CAChC,KAAK,MAAM,OAAO,YAAY,OAAO,MAAM,KAAK,OAAO,IAAI,GAAG;CAC9D,MAAM,KAAK,IAAI,YAAY,EAAE;CAC7B,KAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,YAAY,KAAK,GAAG;EAC5D,MAAM,SAAS,KAAK,OAAO,WAAW,IAAI,KAAK,aAAa,KAAK,OAAO,KAAK,IAAI,EAAE;EACnF,MAAM,KAAK,OAAO,KAAK,OAAO,KAAK,aAAa,QAAQ;CAC1D;CACA,MAAM,KAAK,IAAI,aAAa,EAAE;CAC9B,KAAK,MAAM,QAAQ,YAAY,QAAQ,MAAM,KAAK,OAAO,KAAK,GAAG;CACjE,OAAO,MAAM,KAAK,IAAI;AACxB"}
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../src/surfaceView.ts"],"sourcesContent":["/**\n * Binds a Surface's projected Model and Message subset to a SlotView.\n *\n * The renderer's input is the Surface's projected Model, so Style and Behavior\n * contributions can only read what the Surface projects. Its builder is typed\n * with the Surface's Message subset, so a Behavior cannot emit a Message the\n * Surface does not expose. The returned value is an ordinary `SlotView`, so the\n * core attach/pipe algebra applies unchanged.\n */\nimport type { Html, HtmlBuilder } from 'foldkit/html'\nimport { Surface, type MetadataSummary, type Renderer } from 'foldkit-surface'\nimport { Slots, SlotView, type SlotViewRender } from 'foldkit-mixins'\n\nexport const define = <Root, Model, Message, Params, Slots_>(\n surface: Surface<Root, Model, Message, Params>,\n slots: Slots_,\n render: SlotViewRender<Slots_, Model, Message>,\n options?: { readonly name?: string },\n): SlotView.SlotView<Slots_, Model, Message> =>\n SlotView.define<Slots_, Model, Message>(slots, render, {\n name: options?.name ?? surface.name,\n })\n\n/**\n * Adapts a SlotView to a Surface renderer. `Surface.view` hands a renderer a\n * `ViewBuilder` — the real builder with its `MessageUniverse` phantom removed —\n * and this is the matching boundary cast, sound because the renderer only\n * constructs the Surface's Message subset.\n */\nexport const toRenderer =\n <Slots_, Model, Message>(\n view: SlotView.SlotView<Slots_, Model, Message>,\n ): Renderer<Model, Message> =>\n (model, h) =>\n view(model, h as unknown as HtmlBuilder<Message>)\n\n/**\n * Renders a SlotView for `surface`'s projection of `root` with an inert\n * builder: no runtime, so handlers are built but never dispatched. For demos,\n * tests, and static output.\n */\nexport const render = <Root, Model, Message, Params, Slots_>(\n view: SlotView.SlotView<Slots_, Model, Message>,\n surface: Surface<Root, Model, Message, Params>,\n params: Params,\n root: Root,\n): Html =>\n Surface.rootView(surface, params, toRenderer(view))(root, SlotView.inertBuilder<Message>())\n\nexport interface SurfaceViewInspection {\n /** The SlotView's name, defaulted from the Surface's name. */\n readonly name: string\n readonly slots: ReturnType<typeof Slots.describe>['slots']\n readonly mixins: ReadonlyArray<string>\n}\n\n/**\n * Serializable metadata for DevTools and docs: the published slots and the\n * names of the attached Mixins, with no functions. It composes with\n * `Surface.inspect`, which reports what the Surface observes and emits.\n */\nexport const inspect = <Slots_, Model, Message>(\n view: SlotView.SlotView<Slots_, Model, Message>,\n): SurfaceViewInspection => ({\n name: view.name ?? '',\n slots: Slots.describe(view.slots as unknown as Parameters<typeof Slots.describe>[0]).slots,\n mixins: view.mixins.map(mixin => mixin.name),\n})\n\n/** Reads the tag off a Foldkit Message constructor without constructing one. */\nconst constructorTag = (constructor: unknown): string => {\n const literal = (constructor as { fields?: { _tag?: { ast?: { literal?: unknown } } } }).fields\n ?._tag?.ast?.literal\n if (typeof literal === 'string') return literal\n const name = (constructor as { readonly name?: unknown }).name\n return typeof name === 'string' ? name : 'unknown'\n}\n\nexport interface SurfaceViewDescription {\n readonly name: string\n readonly observes: ReturnType<typeof Surface.inspect>['dependencies']\n readonly metadata: ReadonlyArray<MetadataSummary>\n /** Emitted Message tags, not constructors, so the value stays serializable. */\n readonly emits: ReadonlyArray<string>\n readonly slots: ReturnType<typeof Slots.describe>['slots']\n readonly mixins: ReadonlyArray<string>\n}\n\n/**\n * One serializable description of a Surface and the SlotView that renders it:\n * what it observes and may emit, and where Style/Behavior attach. No functions,\n * so it can be committed, diffed, or handed to DevTools and agent tooling.\n */\nexport const describe = <Root, Model, Message, Params, Slots_>(\n surface: Surface<Root, Model, Message, Params>,\n params: Params,\n view: SlotView.SlotView<Slots_, Model, Message>,\n): SurfaceViewDescription => {\n const inspection = Surface.inspect(surface, params)\n const ui = inspect(view)\n return {\n name: ui.name === '' ? inspection.name : ui.name,\n observes: inspection.dependencies,\n metadata: inspection.metadata,\n emits: inspection.emits.map(constructorTag),\n slots: ui.slots,\n mixins: ui.mixins,\n }\n}\n\n/** Deterministic Markdown for a description; stable key order, no timestamps. */\nexport const toMarkdown = (description: SurfaceViewDescription): string => {\n const lines: string[] = [`# ${description.name}`, '', '## Observes', '']\n for (const path of description.observes) lines.push(`- \\`${path.join('.')}\\``)\n lines.push('', '## May emit', '')\n for (const tag of description.emits) lines.push(`- \\`${tag}\\``)\n lines.push('', '## Slots', '')\n for (const [name, slot] of Object.entries(description.slots)) {\n const events = slot.events.length === 0 ? '' : ` (events: ${slot.events.join(', ')})`\n lines.push(`- \\`${name}\\` — ${slot.capability}${events}`)\n }\n lines.push('', '## Mixins', '')\n for (const name of description.mixins) lines.push(`- \\`${name}\\``)\n return lines.join('\\n')\n}\n"],"mappings":";;;;;;;;;;;;AAaA,MAAa,UACX,SACA,OACA,QACA,YAEA,SAAS,OAA+B,OAAO,QAAQ,EACrD,MAAM,SAAS,QAAQ,QAAQ,KACjC,CAAC;;;;;;;AAQH,MAAa,cAET,UAED,OAAO,MACN,KAAK,OAAO,CAAoC;;;;;;AAOpD,MAAa,UACX,MACA,SACA,QACA,SAEA,QAAQ,SAAS,SAAS,QAAQ,WAAW,IAAI,CAAC,CAAC,CAAC,MAAM,SAAS,aAAsB,CAAC;;;;;;AAc5F,MAAa,WACX,UAC2B;CAC3B,MAAM,KAAK,QAAQ;CACnB,OAAO,MAAM,SAAS,KAAK,KAAwD,CAAC,CAAC;CACrF,QAAQ,KAAK,OAAO,KAAI,UAAS,MAAM,IAAI;AAC7C;;AAGA,MAAM,kBAAkB,gBAAiC;CACvD,MAAM,UAAW,YAAwE,QACrF,MAAM,KAAK;CACf,IAAI,OAAO,YAAY,UAAU,OAAO;CACxC,MAAM,OAAQ,YAA4C;CAC1D,OAAO,OAAO,SAAS,WAAW,OAAO;AAC3C;;;;;;AAiBA,MAAa,YACX,SACA,QACA,SAC2B;CAC3B,MAAM,aAAa,QAAQ,QAAQ,SAAS,MAAM;CAClD,MAAM,KAAK,QAAQ,IAAI;CACvB,OAAO;EACL,MAAM,GAAG,SAAS,KAAK,WAAW,OAAO,GAAG;EAC5C,UAAU,WAAW;EACrB,UAAU,WAAW;EACrB,OAAO,WAAW,MAAM,IAAI,cAAc;EAC1C,OAAO,GAAG;EACV,QAAQ,GAAG;CACb;AACF;;AAGA,MAAa,cAAc,gBAAgD;CACzE,MAAM,QAAkB;EAAC,KAAK,YAAY;EAAQ;EAAI;EAAe;CAAE;CACvE,KAAK,MAAM,QAAQ,YAAY,UAAU,MAAM,KAAK,OAAO,KAAK,KAAK,GAAG,EAAE,GAAG;CAC7E,MAAM,KAAK,IAAI,eAAe,EAAE;CAChC,KAAK,MAAM,OAAO,YAAY,OAAO,MAAM,KAAK,OAAO,IAAI,GAAG;CAC9D,MAAM,KAAK,IAAI,YAAY,EAAE;CAC7B,KAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,YAAY,KAAK,GAAG;EAC5D,MAAM,SAAS,KAAK,OAAO,WAAW,IAAI,KAAK,aAAa,KAAK,OAAO,KAAK,IAAI,EAAE;EACnF,MAAM,KAAK,OAAO,KAAK,OAAO,KAAK,aAAa,QAAQ;CAC1D;CACA,MAAM,KAAK,IAAI,aAAa,EAAE;CAC9B,KAAK,MAAM,QAAQ,YAAY,QAAQ,MAAM,KAAK,OAAO,KAAK,GAAG;CACjE,OAAO,MAAM,KAAK,IAAI;AACxB"}
package/package.json CHANGED
@@ -1,9 +1,19 @@
1
1
  {
2
2
  "name": "foldkit-mixins-surface",
3
- "version": "0.1.0",
3
+ "version": "0.3.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.3.0",
43
+ "foldkit-surface": "^0.2.0"
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": "0.3.0",
52
+ "foldkit-mixins-ui": "0.3.0",
53
+ "foldkit-surface": "0.2.0"
44
54
  },
45
55
  "scripts": {
46
56
  "build": "tsdown",