foldkit-mixins-surface 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Patrick Glenn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,39 @@
1
+ # foldkit-mixins-surface
2
+
3
+ Bridges [`foldkit-surface`](../surface)'s projected Model and Message subset to
4
+ [`foldkit-mixins`](../mixins) SlotViews.
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.
12
+
13
+ ```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))
17
+
18
+ Surface.view(TodoSurface, SurfaceView.toRenderer(TodoCardView))
19
+ ```
20
+
21
+ ## What the bridge enforces
22
+
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.
30
+
31
+ ## Introspection
32
+
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.
38
+
39
+ The API is still settling (`0.1.0`). See [DESIGN.md](../../docs/design/mixins-DESIGN.md).
@@ -0,0 +1,47 @@
1
+ import { Renderer, Requirement, Surface } from "foldkit-surface";
2
+ import { SlotView, SlotViewRender, Slots } from "foldkit-mixins";
3
+ declare namespace surfaceView_d_exports {
4
+ export { SurfaceViewDescription, SurfaceViewInspection, define, describe, inspect, toMarkdown, toRenderer };
5
+ }
6
+ export declare const define: <Root, Model, Message, Params, Slots_>(surface: Surface<Root, Model, Message, Params>, slots: Slots_, render: SlotViewRender<Slots_, Model, Message>, options?: {
7
+ readonly name?: string;
8
+ }) => SlotView.SlotView<Slots_, Model, Message>;
9
+ /**
10
+ * Adapts a SlotView to a Surface renderer. `Surface.view` hands a renderer a
11
+ * `ViewBuilder` — the real builder with its `MessageUniverse` phantom removed —
12
+ * and this is the matching boundary cast, sound because the renderer only
13
+ * constructs the Surface's Message subset.
14
+ */
15
+ export declare const toRenderer: <Slots_, Model, Message>(view: SlotView.SlotView<Slots_, Model, Message>) => Renderer<Model, Message>;
16
+ interface SurfaceViewInspection {
17
+ /** The SlotView's name, defaulted from the Surface's name. */
18
+ readonly name: string;
19
+ readonly slots: ReturnType<typeof Slots.describe>['slots'];
20
+ readonly mixins: ReadonlyArray<string>;
21
+ }
22
+ /**
23
+ * Serializable metadata for DevTools and docs: the published slots and the
24
+ * names of the attached Mixins, with no functions. It composes with
25
+ * `Surface.inspect`, which reports what the Surface observes and emits.
26
+ */
27
+ export declare const inspect: <Slots_, Model, Message>(view: SlotView.SlotView<Slots_, Model, Message>) => SurfaceViewInspection;
28
+ interface SurfaceViewDescription {
29
+ readonly name: string;
30
+ readonly observes: ReturnType<typeof Surface.inspect>['dependencies'];
31
+ readonly requirements: ReadonlyArray<Requirement>;
32
+ /** Emitted Message tags, not constructors, so the value stays serializable. */
33
+ readonly emits: ReadonlyArray<string>;
34
+ readonly slots: ReturnType<typeof Slots.describe>['slots'];
35
+ readonly mixins: ReadonlyArray<string>;
36
+ }
37
+ /**
38
+ * One serializable description of a Surface and the SlotView that renders it:
39
+ * what it observes and may emit, and where Style/Behavior attach. No functions,
40
+ * so it can be committed, diffed, or handed to DevTools and agent tooling.
41
+ */
42
+ export declare const describe: <Root, Model, Message, Params, Slots_>(surface: Surface<Root, Model, Message, Params>, params: Params, view: SlotView.SlotView<Slots_, Model, Message>) => SurfaceViewDescription;
43
+ /** Deterministic Markdown for a description; stable key order, no timestamps. */
44
+ export declare const toMarkdown: (description: SurfaceViewDescription) => string;
45
+ //#endregion
46
+ export { surfaceView_d_exports as SurfaceView, type SurfaceViewDescription, type SurfaceViewInspection };
47
+ //# sourceMappingURL=index.d.mts.map
@@ -0,0 +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"}
package/dist/index.mjs ADDED
@@ -0,0 +1,77 @@
1
+ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
2
+ import { Surface } from "foldkit-surface";
3
+ import { SlotView, Slots } from "foldkit-mixins";
4
+ //#region src/surfaceView.ts
5
+ var surfaceView_exports = /* @__PURE__ */ __exportAll({
6
+ define: () => define,
7
+ describe: () => describe,
8
+ inspect: () => inspect,
9
+ toMarkdown: () => toMarkdown,
10
+ toRenderer: () => toRenderer
11
+ });
12
+ const define = (surface, slots, render, options) => SlotView.define(slots, render, { name: options?.name ?? surface.name });
13
+ /**
14
+ * Adapts a SlotView to a Surface renderer. `Surface.view` hands a renderer a
15
+ * `ViewBuilder` — the real builder with its `MessageUniverse` phantom removed —
16
+ * and this is the matching boundary cast, sound because the renderer only
17
+ * constructs the Surface's Message subset.
18
+ */
19
+ const toRenderer = (view) => (model, h) => view(model, h);
20
+ /**
21
+ * Serializable metadata for DevTools and docs: the published slots and the
22
+ * names of the attached Mixins, with no functions. It composes with
23
+ * `Surface.inspect`, which reports what the Surface observes and emits.
24
+ */
25
+ const inspect = (view) => ({
26
+ name: view.name ?? "",
27
+ slots: Slots.describe(view.slots).slots,
28
+ mixins: view.mixins.map((mixin) => mixin.name)
29
+ });
30
+ /** Reads the tag off a Foldkit Message constructor without constructing one. */
31
+ const constructorTag = (constructor) => {
32
+ const literal = constructor.fields?._tag?.ast?.literal;
33
+ if (typeof literal === "string") return literal;
34
+ const name = constructor.name;
35
+ return typeof name === "string" ? name : "unknown";
36
+ };
37
+ /**
38
+ * One serializable description of a Surface and the SlotView that renders it:
39
+ * what it observes and may emit, and where Style/Behavior attach. No functions,
40
+ * so it can be committed, diffed, or handed to DevTools and agent tooling.
41
+ */
42
+ const describe = (surface, params, view) => {
43
+ const inspection = Surface.inspect(surface, params);
44
+ const ui = inspect(view);
45
+ return {
46
+ name: ui.name === "" ? inspection.name : ui.name,
47
+ observes: inspection.dependencies,
48
+ requirements: inspection.requirements,
49
+ emits: inspection.emits.map(constructorTag),
50
+ slots: ui.slots,
51
+ mixins: ui.mixins
52
+ };
53
+ };
54
+ /** Deterministic Markdown for a description; stable key order, no timestamps. */
55
+ const toMarkdown = (description) => {
56
+ const lines = [
57
+ `# ${description.name}`,
58
+ "",
59
+ "## Observes",
60
+ ""
61
+ ];
62
+ for (const path of description.observes) lines.push(`- \`${path.join(".")}\``);
63
+ lines.push("", "## May emit", "");
64
+ for (const tag of description.emits) lines.push(`- \`${tag}\``);
65
+ lines.push("", "## Slots", "");
66
+ for (const [name, slot] of Object.entries(description.slots)) {
67
+ const events = slot.events.length === 0 ? "" : ` (events: ${slot.events.join(", ")})`;
68
+ lines.push(`- \`${name}\` — ${slot.capability}${events}`);
69
+ }
70
+ lines.push("", "## Mixins", "");
71
+ for (const name of description.mixins) lines.push(`- \`${name}\``);
72
+ return lines.join("\n");
73
+ };
74
+ //#endregion
75
+ export { surfaceView_exports as SurfaceView, define, describe, inspect, toMarkdown, toRenderer };
76
+
77
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +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"}
@@ -0,0 +1,13 @@
1
+ //#region \0rolldown/runtime.js
2
+ var __defProp = Object.defineProperty;
3
+ var __exportAll = (all, no_symbols) => {
4
+ let target = {};
5
+ for (var name in all) __defProp(target, name, {
6
+ get: all[name],
7
+ enumerable: true
8
+ });
9
+ if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
10
+ return target;
11
+ };
12
+ //#endregion
13
+ export { __exportAll as t };
package/package.json ADDED
@@ -0,0 +1,49 @@
1
+ {
2
+ "name": "foldkit-mixins-surface",
3
+ "version": "0.1.0",
4
+ "description": "Bridge foldkit-surface's projected Model and Message subset to foldkit-mixins SlotViews.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "Patrick Glenn <doeixd@gmail.com>",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/doeixd/foldkit-plus.git",
11
+ "directory": "packages/mixins-surface"
12
+ },
13
+ "homepage": "https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins-surface#readme",
14
+ "bugs": {
15
+ "url": "https://github.com/doeixd/foldkit-plus/issues"
16
+ },
17
+ "sideEffects": false,
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.mts",
21
+ "import": "./dist/index.mjs"
22
+ }
23
+ },
24
+ "files": [
25
+ "dist",
26
+ "README.md",
27
+ "LICENSE"
28
+ ],
29
+ "peerDependencies": {
30
+ "effect": "^4.0.0-rc.112",
31
+ "foldkit": "^0.158.2",
32
+ "foldkit-surface": "^0.1.0",
33
+ "foldkit-mixins": "^0.1.0"
34
+ },
35
+ "devDependencies": {
36
+ "@foldkit/ui": "0.158.2",
37
+ "effect": "4.0.0-rc.112",
38
+ "foldkit": "0.158.2",
39
+ "tsdown": "^0.23.0",
40
+ "typescript": "^5.7.2",
41
+ "foldkit-mixins": "0.1.0",
42
+ "foldkit-mixins-ui": "0.1.0",
43
+ "foldkit-surface": "0.1.0"
44
+ },
45
+ "scripts": {
46
+ "build": "tsdown",
47
+ "typecheck": "tsc -b"
48
+ }
49
+ }