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 +276 -116
- package/dist/index.d.mts +71 -11
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +83 -21
- package/dist/index.mjs.map +1 -1
- package/package.json +12 -1
package/README.md
CHANGED
|
@@ -1,11 +1,51 @@
|
|
|
1
1
|
# foldkit-mixins
|
|
2
2
|
|
|
3
|
-
Typed
|
|
3
|
+
Typed extension points for Foldkit views.
|
|
4
4
|
|
|
5
|
-
A
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
125
|
+
events: [Event.Input],
|
|
57
126
|
attributes: [Attr.AriaInvalid],
|
|
58
127
|
}),
|
|
59
128
|
})
|
|
60
129
|
|
|
61
|
-
// 2.
|
|
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.
|
|
68
|
-
const Validation = Behavior.forSlots(FieldSlots)<
|
|
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
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
(input:
|
|
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(
|
|
149
|
+
h.input(
|
|
150
|
+
slots.input.attrs([
|
|
151
|
+
h.Value(input.value),
|
|
152
|
+
h.OnInput(value => Message.ChangedValue({ value })),
|
|
153
|
+
]),
|
|
154
|
+
),
|
|
81
155
|
]),
|
|
82
|
-
)
|
|
156
|
+
)
|
|
157
|
+
.pipe(Style.attach(FieldStyle), Behavior.attach(Validation))
|
|
83
158
|
```
|
|
84
159
|
|
|
85
|
-
`slots.input.attrs(base)` returns the base attributes plus every
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
##
|
|
164
|
+
## What the resolver guarantees
|
|
90
165
|
|
|
91
|
-
|
|
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,
|
|
96
|
-
events: [Event.Input],
|
|
97
|
-
attributes: [Attr.AriaInvalid],
|
|
98
|
-
hidden: false,
|
|
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**
|
|
104
|
-
|
|
105
|
-
`
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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 })` |
|
|
127
|
-
| `Style.pseudo
|
|
128
|
-
| `Style.keyframes
|
|
129
|
-
| `Theme.define
|
|
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
|
|
132
|
-
|
|
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(
|
|
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
|
|
144
|
-
Style.stylesheet(
|
|
236
|
+
CardStyle.css
|
|
237
|
+
Style.stylesheet(FieldStyle, CardStyle)
|
|
145
238
|
```
|
|
146
239
|
|
|
147
|
-
Equal rules share a class
|
|
148
|
-
|
|
149
|
-
|
|
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
|
|
155
|
-
from the view's `input` and `h`, so
|
|
156
|
-
|
|
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
|
|
160
|
-
|
|
161
|
-
requires: {
|
|
162
|
-
attributes: ({ input, h }) => (input.
|
|
163
|
-
mount: input =>
|
|
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
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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`;
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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
|
-
##
|
|
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)
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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
|
-
##
|
|
367
|
+
## Status
|
|
206
368
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
221
|
-
|
|
222
|
-
[`
|
|
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
|