foldkit-mixins 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 +21 -0
- package/README.md +222 -0
- package/dist/index.d.mts +543 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +1171 -0
- package/dist/index.mjs.map +1 -0
- package/dist/rolldown-runtime-D7D4PA-g.mjs +13 -0
- package/package.json +43 -0
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,222 @@
|
|
|
1
|
+
# foldkit-mixins
|
|
2
|
+
|
|
3
|
+
Typed slot contracts and inside-out Style/Behavior attachments for Foldkit.
|
|
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.
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
Slots contract
|
|
12
|
+
│
|
|
13
|
+
┌───────────┴───────────┐
|
|
14
|
+
Style Behavior
|
|
15
|
+
appearance interaction
|
|
16
|
+
│ │
|
|
17
|
+
└───────────┬──────────┘
|
|
18
|
+
▼
|
|
19
|
+
Mixin
|
|
20
|
+
slot contributions
|
|
21
|
+
│
|
|
22
|
+
▼
|
|
23
|
+
ordinary Foldkit attributes
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Why
|
|
27
|
+
|
|
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.
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
```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.
|
|
52
|
+
const FieldSlots = Slots.define({
|
|
53
|
+
root: Slot.make({ capability: Capability.Container }),
|
|
54
|
+
input: Slot.make({
|
|
55
|
+
capability: Capability.TextInput,
|
|
56
|
+
events: [Event.Input, Event.Focus],
|
|
57
|
+
attributes: [Attr.AriaInvalid],
|
|
58
|
+
}),
|
|
59
|
+
})
|
|
60
|
+
|
|
61
|
+
// 2. Style attaches to slots.
|
|
62
|
+
const FieldStyle = Style.forSlots(FieldSlots)({
|
|
63
|
+
root: Style.compose(Style.class('field'), Style.inline({ display: 'grid' })),
|
|
64
|
+
input: Style.class('field-input'),
|
|
65
|
+
})
|
|
66
|
+
|
|
67
|
+
// 3. Behavior attaches to slots, built from the view's input and h.
|
|
68
|
+
const Validation = Behavior.forSlots(FieldSlots)<{ readonly invalid: boolean }, Message>({
|
|
69
|
+
input: Behavior.slot({
|
|
70
|
+
requires: { capability: Capability.TextInput, attributes: [Attr.AriaInvalid] },
|
|
71
|
+
attributes: ({ input, h }) => [h.AriaInvalid(input.invalid)],
|
|
72
|
+
}),
|
|
73
|
+
})
|
|
74
|
+
|
|
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) =>
|
|
79
|
+
h.label(slots.root.attrs(), [
|
|
80
|
+
h.input(slots.input.attrs([h.Value(input.value)])),
|
|
81
|
+
]),
|
|
82
|
+
).pipe(Style.attach(FieldStyle), Behavior.attach(Validation))
|
|
83
|
+
```
|
|
84
|
+
|
|
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.
|
|
88
|
+
|
|
89
|
+
## Slots
|
|
90
|
+
|
|
91
|
+
A slot is named metadata, not a DOM node:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
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
|
|
99
|
+
protected: { events: [Event.Click], attributes: [Attr.Role], style: ['position'] },
|
|
100
|
+
})
|
|
101
|
+
```
|
|
102
|
+
|
|
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.
|
|
112
|
+
|
|
113
|
+
Names come from the `Slots.define` keys, never repeated inside the value.
|
|
114
|
+
|
|
115
|
+
## Style
|
|
116
|
+
|
|
117
|
+
Pure data; it never touches the DOM.
|
|
118
|
+
|
|
119
|
+
| Primitive | Meaning |
|
|
120
|
+
| --- | --- |
|
|
121
|
+
| `Style.class(...)` | class tokens |
|
|
122
|
+
| `Style.inline({...})` | inline declarations |
|
|
123
|
+
| `Style.compose(...)` | concatenate classes, later declarations win per property |
|
|
124
|
+
| `Style.when(condition, piece)` | a boolean known at authoring time |
|
|
125
|
+
| `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 |
|
|
130
|
+
|
|
131
|
+
Rule-based styles compile to **one deterministic class** (an FNV-1a hash of the
|
|
132
|
+
canonical rule text) plus CSS as data:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
const CardStyle = Style.forSlots(CardSlots)({
|
|
136
|
+
root: Style.compose(
|
|
137
|
+
Style.class('card'),
|
|
138
|
+
Style.pseudo(':hover', { boxShadow: '0 1px 2px' }),
|
|
139
|
+
Style.media('(min-width: 40rem)', { gridTemplateColumns: '1fr 1fr' }),
|
|
140
|
+
),
|
|
141
|
+
})
|
|
142
|
+
|
|
143
|
+
CardStyle.css // `.style-…:hover{box-shadow:0 1px 2px}@media (min-width: 40rem){…}`
|
|
144
|
+
Style.stylesheet(CardStyle, OtherStyle) // deduplicated, deterministic
|
|
145
|
+
```
|
|
146
|
+
|
|
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.
|
|
151
|
+
|
|
152
|
+
## Behavior
|
|
153
|
+
|
|
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.
|
|
157
|
+
|
|
158
|
+
```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
|
|
164
|
+
}),
|
|
165
|
+
})
|
|
166
|
+
```
|
|
167
|
+
|
|
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.
|
|
171
|
+
|
|
172
|
+
## SlotView
|
|
173
|
+
|
|
174
|
+
`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.
|
|
179
|
+
|
|
180
|
+
## A11y
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
const DialogPattern = A11y.pattern({
|
|
184
|
+
trigger: { capability: Capability.Interactive, events: [Event.Click] },
|
|
185
|
+
content: { capability: Capability.Container },
|
|
186
|
+
})
|
|
187
|
+
|
|
188
|
+
A11y.validate(DialogPattern, DialogSlots) // ReadonlyArray<A11yDiagnostic>
|
|
189
|
+
```
|
|
190
|
+
|
|
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.
|
|
194
|
+
|
|
195
|
+
## Introspection and diagnostics
|
|
196
|
+
|
|
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.
|
|
204
|
+
|
|
205
|
+
## Adapters
|
|
206
|
+
|
|
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`.
|
|
212
|
+
|
|
213
|
+
## Boundaries
|
|
214
|
+
|
|
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`.
|
|
219
|
+
|
|
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.
|