foldkit-mixins-surface 0.2.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,21 +1,35 @@
1
- # foldkit-mixins-surface
1
+ # `foldkit-mixins-surface`
2
2
 
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.
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
- 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.
7
+ The two packages answer different questions:
12
8
 
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`.
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.
19
33
 
20
34
  ## Install
21
35
 
@@ -26,12 +40,6 @@ pnpm add foldkit-mixins foldkit-surface foldkit-mixins-surface
26
40
  `foldkit`, `effect`, `foldkit-mixins`, and `foldkit-surface` are peer
27
41
  dependencies.
28
42
 
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
43
  ## Usage
36
44
 
37
45
  ```ts
@@ -39,7 +47,7 @@ import { Schema } from 'effect'
39
47
  import { defineMessageUnion } from 'foldkit/message'
40
48
  import { Behavior, Capability, Event, Slot, Slots, Style } from 'foldkit-mixins'
41
49
  import { SurfaceView } from 'foldkit-mixins-surface'
42
- import { Projection, Surface } from 'foldkit-surface'
50
+ import { Surface } from 'foldkit-surface'
43
51
 
44
52
  const Model = Schema.Struct({
45
53
  todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
@@ -56,8 +64,8 @@ const Message = defineMessageUnion({
56
64
  const App = Surface.application({ Model, Message })
57
65
 
58
66
  // 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 }),
67
+ const TodoList = App.surface('TodoList', {
68
+ model: ({ model }) => ({ todos: model.todos, selectedId: model.selectedId }),
61
69
  messages: [Message.SelectedTodo, Message.ArchivedTodo],
62
70
  })
63
71
 
@@ -98,33 +106,83 @@ const TodoListView = SurfaceView.define(TodoList, TodoSlots, (model, slots, h) =
98
106
  const renderer = Surface.view(TodoList, SurfaceView.toRenderer(TodoListView))
99
107
  ```
100
108
 
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`.
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
106
123
 
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.
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
131
+ ```
132
+
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
+ ```
145
+
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
+ ```
111
163
 
112
164
  ## Introspection
113
165
 
114
- `SurfaceView.inspect(view)` returns serializable `{ name, slots, mixins }` with no
115
- functions. `SurfaceView.describe(surface, params, view)` merges that with
116
- `Surface.inspect` — what the Surface observes, requires, and may emit, with
117
- emitted Messages as tags — into one value, and `SurfaceView.toMarkdown` renders it
118
- 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.
119
175
 
120
- Each of `define`, `toRenderer`, `inspect`, `describe` and `toMarkdown` is also a
121
- direct named export, if you prefer that to the `SurfaceView` namespace.
176
+ ## Status
122
177
 
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).
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.
124
182
 
125
183
  ## See also
126
184
 
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.
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,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-mixins-surface",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Bridge foldkit-surface's projected Model and Message subset to foldkit-mixins SlotViews.",
5
5
  "keywords": [
6
6
  "foldkit",
@@ -39,8 +39,8 @@
39
39
  "peerDependencies": {
40
40
  "effect": "^4.0.0-rc.112",
41
41
  "foldkit": "^0.158.2",
42
- "foldkit-mixins": "^0.2.0",
43
- "foldkit-surface": "^0.1.1"
42
+ "foldkit-mixins": "^0.3.0",
43
+ "foldkit-surface": "^0.2.0"
44
44
  },
45
45
  "devDependencies": {
46
46
  "@foldkit/ui": "0.158.2",
@@ -48,9 +48,9 @@
48
48
  "foldkit": "0.158.2",
49
49
  "tsdown": "^0.23.0",
50
50
  "typescript": "^5.7.2",
51
- "foldkit-mixins-ui": "0.2.0",
52
- "foldkit-mixins": "0.2.0",
53
- "foldkit-surface": "0.1.1"
51
+ "foldkit-mixins": "0.3.0",
52
+ "foldkit-mixins-ui": "0.3.0",
53
+ "foldkit-surface": "0.2.0"
54
54
  },
55
55
  "scripts": {
56
56
  "build": "tsdown",