foldkit-mixins-surface 0.11.0 → 0.12.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
@@ -6,10 +6,8 @@ feature boundary to a [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/
6
6
 
7
7
  The two packages answer different questions:
8
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
- ```
9
+ Surface answers what a feature may observe and which Messages it may emit.
10
+ SlotView answers where a view may be customized with Style and Behavior.
13
11
 
14
12
  `SurfaceView.define` joins them. The SlotView's input becomes exactly the
15
13
  Surface's projected value, and its Message universe becomes exactly the
@@ -125,6 +123,28 @@ A Behavior's `Input` parameter still has to be exactly the projected type — a
125
123
  `SlotView` is invariant in it, so a narrower "just the fields I happen to read"
126
124
  type is rejected by `Behavior.attach`.
127
125
 
126
+ `SurfaceView.over(surface, slots)` reads both types from the Surface once, so a
127
+ Behavior needs neither written out. It is `SlotView.over` from `foldkit-mixins`
128
+ with the projection as the input and the exposed subset as the Messages, and its
129
+ `define` names the view after the Surface:
130
+
131
+ ```ts
132
+ const Todos = SurfaceView.over(TodoList, TodoSlots)
133
+
134
+ const Archives = Todos.behavior({
135
+ archive: {
136
+ attributes: ({ input, h }) =>
137
+ Option.match(input.selectedId, {
138
+ onNone: () => [],
139
+ onSome: id => [h.OnClick(Message.ArchivedTodo({ id }))],
140
+ }),
141
+ },
142
+ })
143
+ const BoundTodoListView = Todos.define((model, slots, h) =>
144
+ h.section(slots.root.attrs(), [h.button(slots.archive.attrs(), ['Archive selected'])]),
145
+ ).pipe(Behavior.attach(Archives))
146
+ ```
147
+
128
148
  `toRenderer` is the single boundary adaptation. `Surface.view` hands a renderer
129
149
  a `ViewBuilder` with its `MessageUniverse` phantom removed; the SlotView is sound
130
150
  there because `SurfaceView.define` already restricted what it can construct to
@@ -135,24 +155,13 @@ the Surface's Message subset.
135
155
  Without this package, Surface and SlotView are both type-safe independently, but
136
156
  you can accidentally describe the same feature boundary twice:
137
157
 
138
- ```text
139
- Surface projection / Message subset
140
- X
141
- SlotView input / Message universe
142
- ```
158
+ A Surface's projection and Message subset, and a SlotView's input and Message
159
+ universe, are two descriptions of one boundary.
143
160
 
144
161
  With `SurfaceView.define`, there is one declaration:
145
162
 
146
- ```text
147
- Surface
148
- │
149
- ├─ projected value ──────────────┐
150
- └─ Message subset ────────────┐ │
151
- ▼ ▼
152
- SlotView
153
- │
154
- Style + Behavior
155
- ```
163
+ The Surface's projected value and Message subset flow into the SlotView, and Style
164
+ and Behavior attach to that.
156
165
 
157
166
  That is the whole package.
158
167
 
@@ -174,12 +183,13 @@ const html = SurfaceView.render(TodoListView, TodoList, undefined, {
174
183
 
175
184
  ## Introspection
176
185
 
177
- `SurfaceView.inspect(view)` returns serializable `{ name, slots, mixins }` with
178
- no functions. `SurfaceView.describe(surface, params, view)` merges that with
179
- `Surface.inspect` — what the Surface observes, its projection `metadata`, and
180
- what it may emit, with emitted Messages as tags — into one value.
181
- `SurfaceView.toMarkdown` renders it deterministically for docs or a CI drift
182
- check.
186
+ `SurfaceView.describe(surface, params, view)` is `SlotView.describe(view)` (the slots, and each
187
+ attachment in order with what it requires and contributes per slot, plus `findings`) merged with
188
+ `Surface.inspect`: what the Surface observes, its projection `metadata`, and what it may emit, with
189
+ emitted Messages as tags. `mixins` stays as the attachments' names. `SurfaceView.toMarkdown`
190
+ renders it deterministically for docs or a CI drift check. `SurfaceView.inspect(view)` is
191
+ deprecated for one release in favour of `SlotView.describe`; it still returns `{ name, slots,
192
+ mixins }`.
183
193
 
184
194
  Each of `define`, `toRenderer`, `render`, `inspect`, `describe`, and `toMarkdown` is also a
185
195
  direct named export if you prefer that to the `SurfaceView` namespace.
@@ -1,9 +1,15 @@
1
1
  import { MetadataSummary, Renderer, Surface } from "foldkit-surface";
2
- import { SlotView, SlotViewRender, Slots } from "foldkit-mixins";
2
+ import { SlotView, SlotViewRender, Slots, ViewDescription } from "foldkit-mixins";
3
3
  import { Html } from "foldkit/html";
4
4
  export declare const define: <Root, Model, Message, Params, Slots_>(surface: Surface<Root, Model, Message, Params>, slots: Slots_, render: SlotViewRender<Slots_, Model, Message>, options?: {
5
5
  readonly name?: string;
6
6
  }) => SlotView.SlotView<Slots_, Model, Message>;
7
+ /**
8
+ * `SlotView.over` with the input the Surface's projected Model and the Message
9
+ * universe the subset it exposes, both read from `surface`, so nothing is
10
+ * annotated. Its `define` names the view after the Surface unless told otherwise.
11
+ */
12
+ export declare const over: <Root, Model, Message, Params, Slots_>(surface: Surface<Root, Model, Message, Params>, slots: Slots_) => SlotView.Bound<Slots_, Model, Message>;
7
13
  /**
8
14
  * Adapts a SlotView to a Surface renderer. `Surface.view` hands a renderer a
9
15
  * `ViewBuilder` — the real builder with its `MessageUniverse` phantom removed —
@@ -25,8 +31,11 @@ export interface SurfaceViewInspection {
25
31
  }
26
32
  /**
27
33
  * Serializable metadata for DevTools and docs: the published slots and the
28
- * names of the attached Mixins, with no functions. It composes with
29
- * `Surface.inspect`, which reports what the Surface observes and emits.
34
+ * names of the attached Mixins, with no functions.
35
+ *
36
+ * @deprecated Use `SlotView.describe`, or `SurfaceView.describe` with a
37
+ * Surface: they add each attachment's requirements and contributions. This
38
+ * stays for one release.
30
39
  */
31
40
  export declare const inspect: <Slots_, Model, Message>(view: SlotView.SlotView<Slots_, Model, Message>) => SurfaceViewInspection;
32
41
  export interface SurfaceViewDescription {
@@ -35,7 +44,13 @@ export interface SurfaceViewDescription {
35
44
  readonly metadata: ReadonlyArray<MetadataSummary>;
36
45
  /** Emitted Message tags, not constructors, so the value stays serializable. */
37
46
  readonly emits: ReadonlyArray<string>;
38
- readonly slots: ReturnType<typeof Slots.describe>['slots'];
47
+ readonly slots: ViewDescription['slots'];
48
+ /** The patterns the view was conformed to. */
49
+ readonly conforms: ViewDescription['conforms'];
50
+ /** Each attachment in order, with what it requires and contributes per slot. */
51
+ readonly attachments: ViewDescription['attachments'];
52
+ readonly findings: ViewDescription['findings'];
53
+ /** The attachments' names; `attachments` has them and more. */
39
54
  readonly mixins: ReadonlyArray<string>;
40
55
  }
41
56
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"surfaceView.d.ts","names":[],"sources":["../src/surfaceView.ts"],"mappings":";;;qBAaa,SAAU,MAAM,OAAO,SAAS,QAAQ,QAAM,SAChD,QAAQ,MAAM,OAAO,SAAS,SAAO,OACvC,QAAM,QACL,eAAe,QAAQ,OAAO,UAAQ;WACzB;MACpB,SAAS,SAAS,QAAQ,OAAO;;;;;;;qBAWvB,aACV,QAAQ,OAAO,SAAO,MACf,SAAS,SAAS,QAAQ,OAAO,aACtC,SAAS,OAAO;;;;;;qBASR,SAAU,MAAM,OAAO,SAAS,QAAQ,QAAM,MACnD,SAAS,SAAS,QAAQ,OAAO,UAAQ,SACtC,QAAQ,MAAM,OAAO,SAAS,SAAO,QACtC,QAAM,MACR,SACL;iBAGc;;WAEN;WACA,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;qBAQN,UAAW,QAAQ,OAAO,SAAO,MACtC,SAAS,SAAS,QAAQ,OAAO,aACtC;iBAec;WACN;WACA,UAAU,kBAAkB,QAAQ;WACpC,UAAU,cAAc;;WAExB,OAAO;WACP,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;qBAQN,WAAY,MAAM,OAAO,SAAS,QAAQ,QAAM,SAClD,QAAQ,MAAM,OAAO,SAAS,SAAO,QACtC,QAAM,MACR,SAAS,SAAS,QAAQ,OAAO,aACtC;;qBAcU,aAAU,aAAiB"}
1
+ {"version":3,"file":"surfaceView.d.ts","names":[],"sources":["../src/surfaceView.ts"],"mappings":";;;qBAaa,SAAU,MAAM,OAAO,SAAS,QAAQ,QAAM,SAChD,QAAQ,MAAM,OAAO,SAAS,SAAO,OACvC,QAAM,QACL,eAAe,QAAQ,OAAO,UAAQ;WACzB;MACpB,SAAS,SAAS,QAAQ,OAAO;;;;;;qBAUvB,OAAQ,MAAM,OAAO,SAAS,QAAQ,QAAM,SAC9C,QAAQ,MAAM,OAAO,SAAS,SAAO,OACvC,WACN,SAAS,MAAM,QAAQ,OAAO;;;;;;;qBAepB,aACV,QAAQ,OAAO,SAAO,MACf,SAAS,SAAS,QAAQ,OAAO,aACtC,SAAS,OAAO;;;;;;qBASR,SAAU,MAAM,OAAO,SAAS,QAAQ,QAAM,MACnD,SAAS,SAAS,QAAQ,OAAO,UAAQ,SACtC,QAAQ,MAAM,OAAO,SAAS,SAAO,QACtC,QAAM,MACR,SACL;iBAGc;;WAEN;WACA,OAAO,kBAAkB,MAAM;WAC/B,QAAQ;;;;;;;;;;qBAWN,UAAW,QAAQ,OAAO,SAAO,MACtC,SAAS,SAAS,QAAQ,OAAO,aACtC;iBAec;WACN;WACA,UAAU,kBAAkB,QAAQ;WACpC,UAAU,cAAc;;WAExB,OAAO;WACP,OAAO;;WAEP,UAAU;;WAEV,aAAa;WACb,UAAU;;WAEV,QAAQ;;;;;;;qBAQN,WAAY,MAAM,OAAO,SAAS,QAAQ,QAAM,SAClD,QAAQ,MAAM,OAAO,SAAS,SAAO,QACtC,QAAM,MACR,SAAS,SAAS,QAAQ,OAAO,aACtC;;qBAiBU,aAAU,aAAiB"}
@@ -3,6 +3,15 @@ import { SlotView, Slots } from "foldkit-mixins";
3
3
  // src/surfaceView.ts
4
4
  const define = (surface, slots, render, options) => SlotView.define(slots, render, { name: options?.name ?? surface.name });
5
5
  /**
6
+ * `SlotView.over` with the input the Surface's projected Model and the Message
7
+ * universe the subset it exposes, both read from `surface`, so nothing is
8
+ * annotated. Its `define` names the view after the Surface unless told otherwise.
9
+ */
10
+ const over = (surface, slots) => Object.freeze({
11
+ ...SlotView.over(slots)(),
12
+ define: (render, options) => define(surface, slots, render, options)
13
+ });
14
+ /**
6
15
  * Adapts a SlotView to a Surface renderer. `Surface.view` hands a renderer a
7
16
  * `ViewBuilder` — the real builder with its `MessageUniverse` phantom removed —
8
17
  * and this is the matching boundary cast, sound because the renderer only
@@ -17,8 +26,11 @@ const toRenderer = (view) => (model, h) => view(model, h);
17
26
  const render = (view, surface, params, root) => Surface.rootView(surface, params, toRenderer(view))(root, SlotView.inertBuilder());
18
27
  /**
19
28
  * Serializable metadata for DevTools and docs: the published slots and the
20
- * names of the attached Mixins, with no functions. It composes with
21
- * `Surface.inspect`, which reports what the Surface observes and emits.
29
+ * names of the attached Mixins, with no functions.
30
+ *
31
+ * @deprecated Use `SlotView.describe`, or `SurfaceView.describe` with a
32
+ * Surface: they add each attachment's requirements and contributions. This
33
+ * stays for one release.
22
34
  */
23
35
  const inspect = (view) => ({
24
36
  name: view.name ?? "",
@@ -39,14 +51,17 @@ const constructorTag = (constructor) => {
39
51
  */
40
52
  const describe = (surface, params, view) => {
41
53
  const inspection = Surface.inspect(surface, params);
42
- const ui = inspect(view);
54
+ const ui = SlotView.describe(view);
43
55
  return {
44
56
  name: ui.name === "" ? inspection.name : ui.name,
45
57
  observes: inspection.dependencies,
46
58
  metadata: inspection.metadata,
47
59
  emits: inspection.emits.map(constructorTag),
48
60
  slots: ui.slots,
49
- mixins: ui.mixins
61
+ conforms: ui.conforms,
62
+ attachments: ui.attachments,
63
+ findings: ui.findings,
64
+ mixins: ui.attachments.map((attachment) => attachment.name)
50
65
  };
51
66
  };
52
67
  /** Deterministic Markdown for a description; stable key order, no timestamps. */
@@ -60,15 +75,9 @@ const toMarkdown = (description) => {
60
75
  for (const path of description.observes) lines.push(`- \`${path.join(".")}\``);
61
76
  lines.push("", "## May emit", "");
62
77
  for (const tag of description.emits) lines.push(`- \`${tag}\``);
63
- lines.push("", "## Slots", "");
64
- for (const [name, slot] of Object.entries(description.slots)) {
65
- const events = slot.events.length === 0 ? "" : ` (events: ${slot.events.join(", ")})`;
66
- lines.push(`- \`${name}\` — ${slot.capability}${events}`);
67
- }
68
- lines.push("", "## Mixins", "");
69
- for (const name of description.mixins) lines.push(`- \`${name}\``);
78
+ lines.push("", SlotView.toMarkdown(description));
70
79
  return lines.join("\n");
71
80
  };
72
- export { define, describe, inspect, render, toMarkdown, toRenderer };
81
+ export { define, describe, inspect, over, render, toMarkdown, toRenderer };
73
82
 
74
83
  //# sourceMappingURL=surfaceView.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"surfaceView.js","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"}
1
+ {"version":3,"file":"surfaceView.js","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, type ViewDescription } 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 * `SlotView.over` with the input the Surface's projected Model and the Message\n * universe the subset it exposes, both read from `surface`, so nothing is\n * annotated. Its `define` names the view after the Surface unless told otherwise.\n */\nexport const over = <Root, Model, Message, Params, Slots_>(\n surface: Surface<Root, Model, Message, Params>,\n slots: Slots_,\n): SlotView.Bound<Slots_, Model, Message> =>\n Object.freeze({\n ...SlotView.over(slots)<Model, Message>(),\n define: (\n render: SlotViewRender<Slots_, Model, Message>,\n options?: { readonly name?: string },\n ) => define(surface, slots, render, options),\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.\n *\n * @deprecated Use `SlotView.describe`, or `SurfaceView.describe` with a\n * Surface: they add each attachment's requirements and contributions. This\n * stays for one release.\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: ViewDescription['slots']\n /** The patterns the view was conformed to. */\n readonly conforms: ViewDescription['conforms']\n /** Each attachment in order, with what it requires and contributes per slot. */\n readonly attachments: ViewDescription['attachments']\n readonly findings: ViewDescription['findings']\n /** The attachments' names; `attachments` has them and more. */\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 = SlotView.describe(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 conforms: ui.conforms,\n attachments: ui.attachments,\n findings: ui.findings,\n mixins: ui.attachments.map(attachment => attachment.name),\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('', SlotView.toMarkdown(description))\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;;;;;;AAOH,MAAa,QACX,SACA,UAEA,OAAO,OAAO;CACZ,GAAG,SAAS,KAAK,KAAK,CAAC,CAAiB;CACxC,SACE,QACA,YACG,OAAO,SAAS,OAAO,QAAQ,OAAO;AAC7C,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;;;;;;;;;AAiB5F,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;;;;;;AAuBA,MAAa,YACX,SACA,QACA,SAC2B;CAC3B,MAAM,aAAa,QAAQ,QAAQ,SAAS,MAAM;CAClD,MAAM,KAAK,SAAS,SAAS,IAAI;CACjC,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,UAAU,GAAG;EACb,aAAa,GAAG;EAChB,UAAU,GAAG;EACb,QAAQ,GAAG,YAAY,KAAI,eAAc,WAAW,IAAI;CAC1D;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,SAAS,WAAW,WAAW,CAAC;CAC/C,OAAO,MAAM,KAAK,IAAI;AACxB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-mixins-surface",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "description": "Bridge foldkit-surface's projected Model and Message subset to foldkit-mixins SlotViews.",
5
5
  "keywords": [
6
6
  "foldkit",
@@ -40,19 +40,19 @@
40
40
  "peerDependencies": {
41
41
  "effect": "^4.1.0",
42
42
  "foldkit": "^0.170.0",
43
- "foldkit-mixins": "^0.25.0",
44
- "foldkit-surface": "^0.14.0"
43
+ "foldkit-mixins": "^0.26.0",
44
+ "foldkit-surface": "^0.15.0"
45
45
  },
46
46
  "devDependencies": {
47
- "@effect/platform-browser": "^4.1.1",
47
+ "@effect/platform-browser": "4.1.4",
48
48
  "@foldkit/ui": "0.170.0",
49
- "effect": "^4.1.1",
49
+ "effect": "4.1.4",
50
50
  "foldkit": "0.170.0",
51
51
  "tsdown": "^0.23.1",
52
52
  "typescript": "7.0.2",
53
- "foldkit-mixins": "0.25.0",
54
- "foldkit-mixins-ui": "0.26.0",
55
- "foldkit-surface": "0.14.0"
53
+ "foldkit-mixins": "0.26.0",
54
+ "foldkit-mixins-ui": "0.27.0",
55
+ "foldkit-surface": "0.15.0"
56
56
  },
57
57
  "scripts": {
58
58
  "build": "node ../../scripts/declarations.mjs . && tsdown && node ../../scripts/declared-any.mjs .",