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 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.