foldkit-mixins 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,11 +1,51 @@
1
1
  # foldkit-mixins
2
2
 
3
- Typed slot contracts and inside-out Style/Behavior attachments for Foldkit.
3
+ Typed extension points for Foldkit views.
4
4
 
5
- A view publishes the structural points it is willing to customize. Style and
6
- Behavior attach to those points — from outside, without forking the view.
7
- Application state stays in the Foldkit Model; this package never owns a second
8
- runtime.
5
+ A component eventually gets used somewhere its author did not anticipate. One caller wants a
6
+ brand treatment, another wants a tooltip, another wants analytics, another needs an ARIA
7
+ attribute or a `ResizeObserver`. The usual answers are to keep adding props or to copy the
8
+ component and edit its markup.
9
+
10
+ `foldkit-mixins` takes a different approach:
11
+
12
+ > **A view declares where it may be customized once. Callers attach appearance and
13
+ > element-level behavior to those named points later.**
14
+
15
+ The view keeps its markup, state and Messages. The caller gets a typed customization surface
16
+ instead of an open-ended bag of props.
17
+
18
+ ```text
19
+ Without a slot contract With a slot contract
20
+
21
+ Button Button
22
+ ├─ className ├─ root slot
23
+ ├─ iconClassName ├─ icon slot
24
+ ├─ tooltip └─ label slot
25
+ ├─ tracking
26
+ ├─ ariaLabelOverride callers attach independently:
27
+ ├─ onFocusDecoration ├─ BrandStyle
28
+ └─ ... ├─ TooltipBehavior
29
+ └─ AnalyticsBehavior
30
+ ```
31
+
32
+ This is not a second component system and it is not a state library. A slot ultimately resolves
33
+ to ordinary Foldkit attributes.
34
+
35
+ ## The mental model
36
+
37
+ There are five ideas to learn:
38
+
39
+ | Concept | Meaning |
40
+ | --- | --- |
41
+ | **Slot** | A named extension point in a view: `root`, `input`, `label`, `trigger`, ... |
42
+ | **Slots** | The contract describing which extension points exist and what each permits. |
43
+ | **Style** | Appearance attached to a slot: classes, inline declarations and compiled CSS rules. |
44
+ | **Behavior** | Element-level interaction attached to a slot: attributes and an optional Foldkit `Mount`. Never application state. |
45
+ | **SlotView** | A pure Foldkit view that renders those slots and resolves attached Style/Behavior. |
46
+
47
+ `Style` and `Behavior` both compile to a `Mixin`. The resolver combines their contributions and
48
+ rejects ambiguous ownership instead of silently choosing a winner.
9
49
 
10
50
  ```text
11
51
  Slots contract
@@ -14,125 +54,178 @@ runtime.
14
54
  Style Behavior
15
55
  appearance interaction
16
56
  │ │
17
- └───────────┬──────────┘
57
+ └───────────┬───────────┘
18
58
  ▼
19
59
  Mixin
20
- slot contributions
60
+ │
61
+ ▼
62
+ resolver
21
63
  │
22
64
  ▼
23
65
  ordinary Foldkit attributes
24
66
  ```
25
67
 
26
- ## Why
68
+ ## Why not just `className` and props?
27
69
 
28
- - **Customize without forking.** A component publishes a slot contract; a style
29
- or behavior attaches to it. The component's markup and state are untouched.
30
- - **Appearance and interaction are separate axes.** A style does not know about a
31
- behavior; both compile to the same contribution and merge through one resolver.
32
- - **One cause model.** A behavior owns no state: state is a Foldkit
33
- Model/Submodel, a transition is `update`, a network call is Message → Command,
34
- and an element-owned effect is a `Mount`. The view's Message universe governs
35
- every attribute a mixin can build.
70
+ A class name says only "append this string." A slot is a **typed public customization point**.
71
+ It can say:
72
+
73
+ - this point is a text input rather than an arbitrary element;
74
+ - it publishes `input` but not `click`;
75
+ - callers may set `aria-invalid` but may not replace the structural `role`;
76
+ - this point is internal and cannot be targeted publicly;
77
+ - two independent behaviors may not both own the same event.
78
+
79
+ That matters once a design system, a feature, accessibility logic and product-specific behavior
80
+ all need to customize the same view without knowing about each other.
81
+
82
+ ## Use it when
83
+
84
+ Use mixins when a view should be restyled or decorated **where it is used**, not only where it is
85
+ defined, and you want those customizations checked.
86
+
87
+ Typical examples are a design system styling a feature component, a tooltip attached by a caller,
88
+ analytics on an existing action, ARIA decoration, a focus trap, a `ResizeObserver`, keyboard
89
+ behavior, or a reusable visual recipe.
90
+
91
+ **Not for state.** A widget's open/selected/value belongs in a Foldkit Model or Submodel. A
92
+ transition is `update`; a network call is Message → Command; an element-scoped effect is a
93
+ `Mount`. A Behavior that "needs state" is a signal to reach for a Submodel, not to hide an atom
94
+ inside the mixin.
95
+
96
+ ## Install
97
+
98
+ ```bash
99
+ pnpm add foldkit-mixins
100
+ ```
101
+
102
+ `foldkit` and `effect` are peer dependencies. `foldkit-mixins-surface` bridges a Surface
103
+ projection, and `foldkit-mixins-ui` adapts `@foldkit/ui` components.
36
104
 
37
105
  ## Quick start
38
106
 
107
+ The component author publishes the extension points. Style and Behavior can then be authored
108
+ elsewhere and attached by the caller.
109
+
39
110
  ```ts
40
- import {
41
- Attr,
42
- Behavior,
43
- Capability,
44
- Event,
45
- Slot,
46
- Slots,
47
- SlotView,
48
- Style,
49
- } from 'foldkit-mixins'
50
-
51
- // 1. The view publishes the attachment points it will honor.
111
+ import { Schema } from 'effect'
112
+ import { defineMessageUnion } from 'foldkit/message'
113
+ import { Attr, Behavior, Capability, Event, Slot, Slots, SlotView, Style } from 'foldkit-mixins'
114
+
115
+ const Message = defineMessageUnion({ ChangedValue: { value: Schema.String } })
116
+ type Message = typeof Message.Type
117
+
118
+ type FieldInput = { readonly value: string; readonly invalid: boolean }
119
+
120
+ // 1. The component author publishes the extension points it supports.
52
121
  const FieldSlots = Slots.define({
53
122
  root: Slot.make({ capability: Capability.Container }),
54
123
  input: Slot.make({
55
124
  capability: Capability.TextInput,
56
- events: [Event.Input, Event.Focus],
125
+ events: [Event.Input],
57
126
  attributes: [Attr.AriaInvalid],
58
127
  }),
59
128
  })
60
129
 
61
- // 2. Style attaches to slots.
130
+ // 2. Appearance can live in a design system or another module.
62
131
  const FieldStyle = Style.forSlots(FieldSlots)({
63
132
  root: Style.compose(Style.class('field'), Style.inline({ display: 'grid' })),
64
133
  input: Style.class('field-input'),
65
134
  })
66
135
 
67
- // 3. Behavior attaches to slots, built from the view's input and h.
68
- const Validation = Behavior.forSlots(FieldSlots)<{ readonly invalid: boolean }, Message>({
136
+ // 3. Element-level behavior can be authored independently.
137
+ const Validation = Behavior.forSlots(FieldSlots)<FieldInput, Message>({
69
138
  input: Behavior.slot({
70
139
  requires: { capability: Capability.TextInput, attributes: [Attr.AriaInvalid] },
71
140
  attributes: ({ input, h }) => [h.AriaInvalid(input.invalid)],
72
141
  }),
73
142
  })
74
143
 
75
- // 4. The view publishes slots through its render function.
76
- const Field = SlotView.define(
77
- FieldSlots,
78
- (input: { readonly value: string; readonly invalid: boolean }, slots, h) =>
144
+ // 4. The pure view renders through the slots. Attachments return a new view;
145
+ // the original view is unchanged.
146
+ const Field = SlotView.forMessages<Message>()
147
+ .define(FieldSlots, (input: FieldInput, slots, h) =>
79
148
  h.label(slots.root.attrs(), [
80
- h.input(slots.input.attrs([h.Value(input.value)])),
149
+ h.input(
150
+ slots.input.attrs([
151
+ h.Value(input.value),
152
+ h.OnInput(value => Message.ChangedValue({ value })),
153
+ ]),
154
+ ),
81
155
  ]),
82
- ).pipe(Style.attach(FieldStyle), Behavior.attach(Validation))
156
+ )
157
+ .pipe(Style.attach(FieldStyle), Behavior.attach(Validation))
83
158
  ```
84
159
 
85
- `slots.input.attrs(base)` returns the base attributes plus every attached
86
- contribution, resolved deterministically. Base attributes, event Messages and any
87
- `ChildAttribute` are preserved; the resolver is the only place merge policy lives.
160
+ `slots.input.attrs(base)` returns the view's base attributes plus every resolved contribution.
161
+ Base attributes, event Messages and any `ChildAttribute` survive. The caller did not copy the
162
+ markup or add a `validationBehavior` prop to the component.
88
163
 
89
- ## Slots
164
+ ## What the resolver guarantees
90
165
 
91
- A slot is named metadata, not a DOM node:
166
+ Attachments are not concatenated and left to renderer order. The resolver applies explicit rules:
167
+
168
+ - classes are additive and deduplicated into one `Class`;
169
+ - inline styles merge per property, with later attachments winning per property;
170
+ - an event or scalar attribute has exactly one owner — a second owner is an error;
171
+ - a `ChildAttribute` (a Submodel's published handler) is preserved by identity;
172
+ - `Key` and `InnerHTML` are structural and cannot be overridden;
173
+ - multiple mount contributions compose into exactly one `OnMount`.
174
+
175
+ Conflicts throw `Diagnostics.DiagnosticError` with stable codes such as
176
+ `mixins:event-conflict` and `mixins:protected-attribute`, so tests, DevTools and editor tooling can
177
+ all speak the same diagnostic language.
178
+
179
+ ## Slots: the public contract
180
+
181
+ A slot is metadata, not a DOM node:
92
182
 
93
183
  ```ts
94
184
  Slot.make({
95
- capability: Capability.TextInput, // what it structurally is
96
- events: [Event.Input], // what it emits
97
- attributes: [Attr.AriaInvalid], // what it exposes
98
- hidden: false, // internal attachment points are hidden
185
+ capability: Capability.TextInput,
186
+ events: [Event.Input],
187
+ attributes: [Attr.AriaInvalid],
188
+ hidden: false,
99
189
  protected: { events: [Event.Click], attributes: [Attr.Role], style: ['position'] },
100
190
  })
101
191
  ```
102
192
 
103
- - **Capability** is a hierarchy (`Base → Interactive → { Container, Focusable →
104
- TextInput, Draggable }`). A behavior that requires `Interactive` attaches to a
105
- `TextInput`. Extend it with `Capability.make(name, { extends })`.
106
- - **Event** and **Attr** are branded tokens; `Event.make`/`Attr.make` add custom
107
- ones. They are metadata: they do not install handlers.
108
- - **Requirements** are platform tokens (`Requirement.Keyboard`, …).
109
- - `hidden` reserves an internal point that public mixins cannot target.
110
- - `protected` keeps structural pieces (an event, an attribute, a style property)
111
- from being replaced by an attachment.
193
+ - **Capability** describes structural compatibility. The built-in hierarchy is
194
+ `Base → Interactive → { Container, Focusable → TextInput, Draggable }`, plus
195
+ `Base → Collection`. A behavior that requires `Interactive` may attach to a `TextInput`.
196
+ Extend it with `Capability.make(name, { extends })`.
197
+ - **Event** and **Attr** are branded metadata tokens. `Event.make` and `Attr.make` add custom ones;
198
+ declaring them does not install handlers.
199
+ - **Requirement** tokens name platform needs such as `Keyboard`, `Pointer` and `Clipboard` for
200
+ tooling to inspect.
201
+ - `hidden` reserves an internal extension point: public Style and Behavior specs do not even offer
202
+ that key.
203
+ - `protected` keeps structural events, attributes or style properties from being replaced by an
204
+ attachment.
112
205
 
113
- Names come from the `Slots.define` keys, never repeated inside the value.
206
+ Names come from the keys passed to `Slots.define`; they are never repeated inside each slot.
114
207
 
115
- ## Style
208
+ ## Style: appearance as data
116
209
 
117
- Pure data; it never touches the DOM.
210
+ Style is pure data. It never touches the DOM.
118
211
 
119
212
  | Primitive | Meaning |
120
213
  | --- | --- |
121
214
  | `Style.class(...)` | class tokens |
122
215
  | `Style.inline({...})` | inline declarations |
123
- | `Style.compose(...)` | concatenate classes, later declarations win per property |
216
+ | `Style.compose(...)` | concatenate classes; later declarations win per property |
124
217
  | `Style.when(condition, piece)` | a boolean known at authoring time |
125
218
  | `Style.whenInput(predicate, piece)` | a condition read from the view input at render time |
126
- | `Style.recipe({ base, variants, defaults, compound })` | a typed variant selector |
127
- | `Style.pseudo`/`media`/`supports`/`container`/`nest` | rule-based appearance |
128
- | `Style.keyframes`/`global` | class-independent CSS |
129
- | `Theme.define`/`variable`/`variables` | typed tokens and CSS custom properties |
219
+ | `Style.recipe({ base, variants, defaults, compound })` | returns `selection => StyleValue` |
220
+ | `Style.pseudo` / `media` / `supports` / `container` / `nest` | rule-based appearance |
221
+ | `Style.keyframes` / `global` | class-independent CSS |
222
+ | `Theme.define` / `variable` / `variables` | typed tokens and CSS custom properties |
130
223
 
131
- Rule-based styles compile to **one deterministic class** (an FNV-1a hash of the
132
- canonical rule text) plus CSS as data:
224
+ Rule-based Style compiles to one deterministic class (an FNV-1a hash of canonical rule text) plus
225
+ CSS as data:
133
226
 
134
227
  ```ts
135
- const CardStyle = Style.forSlots(CardSlots)({
228
+ const CardStyle = Style.forSlots(FieldSlots)({
136
229
  root: Style.compose(
137
230
  Style.class('card'),
138
231
  Style.pseudo(':hover', { boxShadow: '0 1px 2px' }),
@@ -140,44 +233,74 @@ const CardStyle = Style.forSlots(CardSlots)({
140
233
  ),
141
234
  })
142
235
 
143
- CardStyle.css // `.style-…:hover{box-shadow:0 1px 2px}@media (min-width: 40rem){…}`
144
- Style.stylesheet(CardStyle, OtherStyle) // deduplicated, deterministic
236
+ CardStyle.css
237
+ Style.stylesheet(FieldStyle, CardStyle)
145
238
  ```
146
239
 
147
- Equal rules share a class; nothing mutates the DOM, so the server and the client
148
- derive the same class and rules. Rules inside `Style.whenInput` are rejected
149
- (`style:conditional-rules-unsupported`) because the class is static while the
150
- condition is not. See [DESIGN.md](../../docs/design/mixins-DESIGN.md) for the compiler's scope.
240
+ Equal rules share a class, so server and client derive the same class and CSS. Rules inside
241
+ `Style.whenInput` are rejected (`style:conditional-rules-unsupported`) because the class is static
242
+ while the condition is not.
151
243
 
152
- ## Behavior
244
+ ## Behavior: reusable element-level interaction
153
245
 
154
- A named set of interaction contributions. Attributes are built while resolving,
155
- from the view's `input` and `h`, so the view's Message universe is the only one a
156
- behavior can emit into.
246
+ A Behavior is a reusable bundle of element-level interaction that does **not** own application
247
+ state. Its attributes are built while resolving from the view's `input` and `h`, so it can only
248
+ emit Messages from the view's own Message universe.
157
249
 
158
250
  ```ts
159
- const Archive = Behavior.forSlots(CardSlots)<CardInput, CardMessage>({
160
- archive: Behavior.slot({
161
- requires: { events: [Event.Click] },
162
- attributes: ({ input, h }) => (input.archived ? [h.AriaDisabled(true)] : []),
163
- mount: input => MeasureCard(input.id), // a Foldkit `Mount.define*` action
251
+ const Focus = Behavior.forSlots(FieldSlots)<FieldInput, Message>({
252
+ input: Behavior.slot({
253
+ requires: { capability: Capability.TextInput },
254
+ attributes: ({ input, h }) => (input.invalid ? [h.AriaInvalid(true)] : []),
255
+ mount: input => MeasureField(input.value), // your own Mount.define* action
164
256
  }),
165
257
  })
166
258
  ```
167
259
 
168
- A behavior owns no state. A stateful widget is a Foldkit Submodel; a continuous
169
- element listener is a `Mount`; a network call is Message → `update` → Command.
170
- Multiple mount contributions compose into **one** `OnMount` per element.
260
+ `requires` is checked against the slot contract at definition time. A behavior that requires
261
+ `Event.Click` cannot attach to a slot that did not publish click. Multiple mount contributions
262
+ compose into one `OnMount` per element.
171
263
 
172
264
  ## SlotView
173
265
 
174
266
  `SlotView.define(slots, render)` is a pure view that publishes slots. Attach with
175
- `SlotView.attach`, `Style.attach` or `Behavior.attach`; the view is immutable.
176
- For a component whose render payload has **per-item** groups (tabs, options,
177
- calendar cells), call `SlotView.buildersFor(slots, mixins, { input, h })` and map
178
- the items yourself.
267
+ `SlotView.attach`, `Style.attach` or `Behavior.attach`; each returns a new view.
268
+
269
+ Nothing but the render callback's builder names the view's Message universe, so plain `define`
270
+ infers it from an explicit `h: HtmlBuilder<Message>` annotation. Without one, `Message` becomes
271
+ `unknown` and the eventual variance error is hard to read.
272
+ `SlotView.forMessages<Message>().define(slots, render)` fixes the universe up front instead;
273
+ `Input` still comes from the callback's own `input` annotation.
274
+
275
+ `Behavior.attach` uses the behavior's `Input` as the attached view's `Input`, so declare a
276
+ behavior over the view's input type, not merely the subset of fields it happens to read.
277
+
278
+ For per-item groups such as tabs, options or calendar cells, use
279
+ `SlotView.buildersFor(slots, mixins, { input, h })` and map the items yourself. One contribution
280
+ then applies to every item while each item's base attributes retain their own event ownership.
281
+
282
+ ## With `foldkit-surface`
283
+
284
+ Mixins do not require Surface, but the two fit naturally: Surface says **what a feature may
285
+ observe and emit**; slots say **where that feature may be customized**.
286
+
287
+ `foldkit-mixins-surface` renders a Surface projection through a `SlotView`, so a Behavior reads the
288
+ projected input rather than the root application Model, and its builder carries the Surface's
289
+ Message subset.
290
+
291
+ ```text
292
+ Application Model / Message
293
+ │
294
+ Surface
295
+ what may be seen/emitted
296
+ │
297
+ SlotView
298
+ where it may be customized
299
+ │
300
+ Style + Behavior
301
+ ```
179
302
 
180
- ## A11y
303
+ ## Accessibility contracts
181
304
 
182
305
  ```ts
183
306
  const DialogPattern = A11y.pattern({
@@ -185,38 +308,75 @@ const DialogPattern = A11y.pattern({
185
308
  content: { capability: Capability.Container },
186
309
  })
187
310
 
188
- A11y.validate(DialogPattern, DialogSlots) // ReadonlyArray<A11yDiagnostic>
311
+ A11y.validate(DialogPattern, DialogSlots)
312
+ ```
313
+
314
+ `A11y.validate` is pure and DOM-independent. It checks the declared contract for missing or hidden
315
+ slots, capability mismatches and unpublished events or attributes. An optional requirement
316
+ tolerates an absent slot but still checks a present one. It does **not** certify WCAG compliance.
317
+
318
+ ## Introspection
319
+
320
+ The contracts are data:
321
+
322
+ - `Slots.describe(contract)` and `Slot.describe(slot)` return serializable metadata.
323
+ - `Mixin.compose` combines mixins; `Mixin.make`, `Mixin.dynamic` and `Mixin.empty` build them.
324
+ - diagnostics have stable codes and structured `details`, so the same information can feed tests,
325
+ DevTools, documentation or agent tooling.
326
+
327
+ ## Testing and static output
328
+
329
+ `SlotView.inertBuilder<Message>()` is an `HtmlBuilder` with no runtime behind it. Rendering a
330
+ view with it builds the same tagged attributes and elements, but nothing mounts and handlers are
331
+ never dispatched. Use it in tests, demos and static output, not as a renderer.
332
+
333
+ `Attributes` reads a resolved bundle, such as the result of `slots.x.attrs(base)`, by tag.
334
+ `Attributes.find(bundle, tag)` returns the **first** match typed as that variant, so `value`,
335
+ `message` or `action` need no cast; `Attributes.filter` returns every match in bundle order;
336
+ `Attributes.tagOf` returns an entry's tag. Opaque `ChildAttribute` entries have no readable tag
337
+ and are skipped.
338
+
339
+ ```ts
340
+ import { Attributes, type SlotAttributes } from 'foldkit-mixins'
341
+
342
+ let input: SlotAttributes<Message> = []
343
+ const Probe = SlotView.forMessages<Message>()
344
+ .define(FieldSlots, (field: FieldInput, slots, h) => {
345
+ input = slots.input.attrs([h.Value(field.value)])
346
+ return h.input(input)
347
+ })
348
+ .pipe(Style.attach(FieldStyle), Behavior.attach(Validation))
349
+
350
+ Probe({ value: 'Ada', invalid: true }, SlotView.inertBuilder<Message>())
351
+
352
+ Attributes.find(input, 'Class')?.value // 'field-input'
353
+ Attributes.find(input, 'AriaInvalid')?.value // true
189
354
  ```
190
355
 
191
- `validate` is pure and DOM-independent: it checks the declared contract, never a
192
- rendered tree, and reports missing or hidden slots, capability mismatches and
193
- unpublished events or attributes in authored order. It does not certify WCAG.
356
+ ## `@foldkit/ui`
194
357
 
195
- ## Introspection and diagnostics
358
+ `foldkit-mixins-ui` adapts `@foldkit/ui` components that expose attribute bundles or a consumer
359
+ render seam. Button, Input, Checkbox, Disclosure, Dialog, Popover, Tooltip, Slider, Tabs,
360
+ RadioGroup, Calendar and others are covered.
196
361
 
197
- - `Slots.describe(contract)` and `Slot.describe(slot)` return serializable
198
- metadata.
199
- - Conflicts throw a `Diagnostics.DiagnosticError` with a stable code
200
- (`mixins:event-conflict`, `mixins:protected-attribute`, …) and a `details`
201
- record, so tests, DevTools and editor tooling share one shape.
202
- - `Mixin.compose` merges mixins; `Mixin.make`/`Mixin.dynamic`/`Mixin.empty` build
203
- them.
362
+ Some components build their entire element tree internally and expose no attachment seam; those
363
+ cannot be adapted without changing the component API. Others simply do not have an adapter yet.
364
+ See the [guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/mixins.md) for the current
365
+ boundary.
204
366
 
205
- ## Adapters
367
+ ## Status
206
368
 
207
- - [`foldkit-mixins-ui`](../mixins-ui) publishes `@foldkit/ui` attribute bundles as
208
- slots (Button, Input, Checkbox, Disclosure, Dialog, Popover, Tooltip, Slider,
209
- Tabs, RadioGroup, Calendar, …).
210
- - [`foldkit-mixins-surface`](../mixins-surface) binds a `foldkit-surface`
211
- projection and Message subset to a `SlotView`.
369
+ The API is still settling (`0.2.x`). This package replaces none of Foldkit's state or effect
370
+ machinery — Commands, Subscriptions, Mounts, ManagedResources, Models or Submodels. Its job is
371
+ narrower: make view customization explicit, typed and composable.
212
372
 
213
- ## Boundaries
373
+ The [design note](https://github.com/doeixd/foldkit-plus/blob/main/docs/design/mixins-DESIGN.md)
374
+ records the substrate probes and implementation decisions.
214
375
 
215
- This package does not introduce local reactive state, hooks, a query cache, a
216
- second update loop, mutable element handles as the default path, or an event bus.
217
- It does not replace Foldkit Commands, Subscriptions, Mounts, ManagedResources or
218
- `@foldkit/ui`.
376
+ ## See also
219
377
 
220
- The API is still settling (`0.1.0`). [DESIGN.md](../../docs/design/mixins-DESIGN.md) records the
221
- substrate probes and the decisions they forced;
222
- [`examples/mixins`](../../examples/mixins) is a runnable trace.
378
+ - [Inside-out view composition](https://github.com/doeixd/foldkit-plus/blob/main/docs/mixins.md) — the mental model and when to use it.
379
+ - [`foldkit-mixins-surface`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins-surface) — bind a Surface projection and Message subset to a SlotView.
380
+ - [`foldkit-mixins-ui`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins-ui) — adapters for `@foldkit/ui`.
381
+ - [`examples/mixins`](https://github.com/doeixd/foldkit-plus/tree/main/examples/mixins) — a focused runnable trace.
382
+ - [`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app) — a whole application styled this way.
package/dist/index.d.mts CHANGED
@@ -304,6 +304,30 @@ type Contribution<Message> = {
304
304
  type StaticContributionMap<Message> = {
305
305
  readonly [slot: string]: StaticContribution<Message> | undefined;
306
306
  };
307
+ declare namespace resolver_d_exports {
308
+ export { ResolveOptions, SlotAttributes, resolve };
309
+ }
310
+ type SlotAttributes<Message> = ReadonlyArray<Attribute<Message> | ChildAttribute>;
311
+ interface ResolveOptions {
312
+ readonly slot?: string;
313
+ readonly protected?: SlotProtection;
314
+ }
315
+ declare const resolve: <Message>(base: SlotAttributes<Message> | undefined, contributions: ReadonlyArray<StaticContribution<Message>>, options?: ResolveOptions) => SlotAttributes<Message>;
316
+ declare namespace attributes_d_exports {
317
+ export { Of, Tag, filter, find, tagOf };
318
+ }
319
+ /** Every Foldkit attribute tag: `'Class'`, `'OnClick'`, `'DataAttribute'`, … */
320
+ type Tag = Attribute<never>['_tag'];
321
+ /** The attribute variant carrying `T`. */
322
+ type Of<Message, T extends Tag> = Extract<Attribute<Message>, {
323
+ readonly _tag: T;
324
+ }>;
325
+ /** The tag of one bundle entry; `undefined` for an opaque `ChildAttribute`. */
326
+ declare const tagOf: <Message>(attribute: SlotAttributes<Message>[number]) => Tag | undefined;
327
+ /** The first attribute with `tag`, typed as that variant. */
328
+ declare const find: <Message, T extends Tag>(attributes: SlotAttributes<Message>, tag: T) => Of<Message, T> | undefined;
329
+ /** Every attribute with `tag`, in bundle order. */
330
+ declare const filter: <Message, T extends Tag>(attributes: SlotAttributes<Message>, tag: T) => ReadonlyArray<Of<Message, T>>;
307
331
  declare namespace mixin_d_exports {
308
332
  export { AnyMixin, Mixin, MixinFor, StaticMixin, compose, contributionsFor, dynamic, empty, evaluate, isDynamic, make };
309
333
  }
@@ -329,17 +353,8 @@ declare const dynamic: <Message = never>(name: string, contributions: Contributi
329
353
  declare const empty: <Message = never>() => StaticMixin<Message>;
330
354
  declare const compose: <Message = never>(...mixins: ReadonlyArray<MixinFor<Message>>) => Mixin<Message>;
331
355
  declare const contributionsFor: <Message>(mixin: Mixin<Message> | StaticMixin<Message>, slot: string) => SlotContribution<Message> | undefined;
332
- declare namespace resolver_d_exports {
333
- export { ResolveOptions, SlotAttributes, resolve };
334
- }
335
- type SlotAttributes<Message> = ReadonlyArray<Attribute<Message> | ChildAttribute>;
336
- interface ResolveOptions {
337
- readonly slot?: string;
338
- readonly protected?: SlotProtection;
339
- }
340
- declare const resolve: <Message>(base: SlotAttributes<Message> | undefined, contributions: ReadonlyArray<StaticContribution<Message>>, options?: ResolveOptions) => SlotAttributes<Message>;
341
356
  declare namespace slotView_d_exports {
342
- export { SlotBuilder, SlotBuilders, SlotView, SlotViewRender, SlotViewTransform, SlotViewTransformFor, attach$1 as attach, buildersFor, define$1 as define };
357
+ export { MessageSlotView, SlotBuilder, SlotBuilders, SlotView, SlotViewRender, SlotViewTransform, SlotViewTransformFor, attach$1 as attach, buildersFor, define$1 as define, forMessages, inertBuilder };
343
358
  }
344
359
  type SlotBuilder<Message> = {
345
360
  readonly attrs: (base?: SlotAttributes<Message>) => SlotAttributes<Message>;
@@ -358,9 +373,47 @@ declare const buildersFor: <Slots, Message, Input>(slots: Slots, mixins: Readonl
358
373
  readonly input: Input;
359
374
  readonly h: HtmlBuilder<Message>;
360
375
  }) => SlotBuilders<Slots, Message>;
376
+ /**
377
+ * Defines a view over published Slots.
378
+ *
379
+ * `Message` has no anchor but the render callback's builder, so it is inferred
380
+ * from an explicit `h: HtmlBuilder<Message>` annotation on that parameter.
381
+ * Without one it resolves to `unknown`, and the first error appears later and
382
+ * elsewhere — an invariance mismatch at `Style.attach`/`Behavior.attach` that
383
+ * does not name the missing annotation. `forMessages<Message>()` fixes the
384
+ * Message universe up front instead, and leaves `h` contextually typed.
385
+ */
361
386
  declare const define$1: <Slots, Input, Message>(slots: Slots, render: SlotViewRender<Slots, Input, Message>, options?: {
362
387
  readonly name?: string;
363
388
  }) => SlotView<Slots, Input, Message>;
389
+ /**
390
+ * Foldkit's `inertHtml` typed for a Message universe, for rendering a view
391
+ * outside a runtime (tests, demos, static description). `inertHtml` is
392
+ * `HtmlBuilder<never>`, and the builder is invariant in `Message`, so this is
393
+ * the one cast: sound because inert handlers are never dispatched.
394
+ */
395
+ declare const inertBuilder: <Message>() => HtmlBuilder<Message>;
396
+ /** The `SlotView` constructors with `Message` already fixed. */
397
+ interface MessageSlotView<Message> {
398
+ readonly define: <Slots, Input>(slots: Slots, render: SlotViewRender<Slots, Input, Message>, options?: {
399
+ readonly name?: string;
400
+ }) => SlotView<Slots, Input, Message>;
401
+ }
402
+ /**
403
+ * Binds the view constructors to one Message universe, so the render callback
404
+ * no longer has to annotate `h` to pin it. `Input` is still inferred from the
405
+ * callback's own `input` annotation.
406
+ *
407
+ * @example
408
+ * ```ts
409
+ * const Field = SlotView.forMessages<Message>().define(
410
+ * FieldSlots,
411
+ * (input: FieldInput, slots, h) =>
412
+ * h.input(slots.input.attrs([h.OnInput(value => Message.ChangedValue({ value }))])),
413
+ * )
414
+ * ```
415
+ */
416
+ declare const forMessages: <Message>() => MessageSlotView<Message>;
364
417
  /** A transform on any view, used by Message-free static mixins such as Style. */
365
418
  type SlotViewTransform = <Slots, Input, Message>(view: SlotView<Slots, Input, Message>) => SlotView<Slots, Input, Message>;
366
419
  /** A transform restricted to one Message universe, for Behavior mixins. */
@@ -395,6 +448,13 @@ declare const slot: <Options extends BehaviorSlotOptions<any, any>>(options: Opt
395
448
  declare const forSlots: <Slots>(slots: Slots) => <Input, Message>(spec: BehaviorSpec<Slots, Input, Message>, options?: {
396
449
  readonly name?: string;
397
450
  }) => NamedBehavior<Slots, Input, Message>;
451
+ /**
452
+ * Attaches a Behavior to a view. The behavior's `Input` becomes the attached
453
+ * view's `Input`: a behavior declared over only the fields it reads is rejected
454
+ * even though those fields are a subset, and one declared over extra fields
455
+ * widens what the view must be called with. Declare `Input` as the view's own
456
+ * input type.
457
+ */
398
458
  declare const attach: <BehaviorSlots, Message, Input>(behavior: NamedBehavior<BehaviorSlots, Input, Message>) => <ViewSlots>(view: SlotView<ViewSlots, Input, Message>) => SlotView<ViewSlots, Input, Message>;
399
459
  declare const Behavior: {
400
460
  readonly slot: <Options extends BehaviorSlotOptions<any, any>>(options: Options) => Options;
@@ -539,5 +599,5 @@ export declare const Theme: {
539
599
  readonly variables: <T extends ThemeTokens>(theme: T) => StyleValue;
540
600
  };
541
601
  //#endregion
542
- export { a11y_d_exports as A11y, type A11yDiagnostic, type A11yDiagnosticCode, type Pattern as A11yPattern, type SlotRequirement as A11yRequirement, type Any as AnyCapability, type AnyMixin, attr_d_exports as Attr, type AttrToken, behavior_d_exports as Behavior, type BehaviorSlotOptions, type BehaviorSpec, capability_d_exports as Capability, type Contribution, type ContributionContext, type Diagnostic, type DiagnosticCode, diagnostics_d_exports as Diagnostics, type DynamicContribution, event_d_exports as Event, type EventToken, type InputContribution, metadataToken_d_exports as MetadataToken, mixin_d_exports as Mixin, type MixinFor, type Mixin as MixinValue, type NamedBehavior, type NamedStyle, requirement_d_exports as Requirement, type RequirementToken, type ResolveOptions, resolver_d_exports as Resolver, type Satisfies, slot_d_exports as Slot, type SlotAttributes, type SlotBuilder, type SlotBuilders, type SlotContribution, type SlotProtection, type SlotRequirements, slotView_d_exports as SlotView, type SlotViewRender, type SlotViewTransform, type SlotViewTransformFor, slots_d_exports as Slots, type Contract as SlotsContract, type StaticContribution, type StaticContributionMap, type StaticMixin, type StyleCondition, type StylePieces, type StyleRule, type StyleValue, type Theme as ThemeValue, type ThemeTokens, type UnnamedSlot };
602
+ export { a11y_d_exports as A11y, type A11yDiagnostic, type A11yDiagnosticCode, type Pattern as A11yPattern, type SlotRequirement as A11yRequirement, type Any as AnyCapability, type AnyMixin, attr_d_exports as Attr, type AttrToken, attributes_d_exports as Attributes, behavior_d_exports as Behavior, type BehaviorSlotOptions, type BehaviorSpec, capability_d_exports as Capability, type Contribution, type ContributionContext, type Diagnostic, type DiagnosticCode, diagnostics_d_exports as Diagnostics, type DynamicContribution, event_d_exports as Event, type EventToken, type InputContribution, type MessageSlotView, metadataToken_d_exports as MetadataToken, mixin_d_exports as Mixin, type MixinFor, type Mixin as MixinValue, type NamedBehavior, type NamedStyle, requirement_d_exports as Requirement, type RequirementToken, type ResolveOptions, resolver_d_exports as Resolver, type Satisfies, slot_d_exports as Slot, type SlotAttributes, type SlotBuilder, type SlotBuilders, type SlotContribution, type SlotProtection, type SlotRequirements, slotView_d_exports as SlotView, type SlotViewRender, type SlotViewTransform, type SlotViewTransformFor, slots_d_exports as Slots, type Contract as SlotsContract, type StaticContribution, type StaticContributionMap, type StaticMixin, type StyleCondition, type StylePieces, type StyleRule, type StyleValue, type Theme as ThemeValue, type ThemeTokens, type UnnamedSlot };
543
603
  //# sourceMappingURL=index.d.mts.map