foldkit-mixins-ui 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 +266 -34
- package/package.json +14 -3
package/README.md
CHANGED
|
@@ -1,35 +1,245 @@
|
|
|
1
|
-
# foldkit-mixins-ui
|
|
1
|
+
# `foldkit-mixins-ui`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Adapts [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui) render seams into
|
|
4
|
+
[`foldkit-mixins`](../mixins) slots.
|
|
5
5
|
|
|
6
|
-
`@foldkit/ui`
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
6
|
+
Use it when an `@foldkit/ui` component already owns the difficult state and
|
|
7
|
+
accessibility behavior, but you want callers to style or decorate the component
|
|
8
|
+
through a typed extension contract instead of copying its markup or manually
|
|
9
|
+
merging attribute arrays.
|
|
10
|
+
|
|
11
|
+
The ownership rule stays simple:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
@foldkit/ui
|
|
15
|
+
owns component state
|
|
16
|
+
owns accessibility behavior
|
|
17
|
+
owns its base attributes
|
|
18
|
+
|
|
19
|
+
foldkit-mixins-ui
|
|
20
|
+
names the component's public attribute bundles as Slots
|
|
21
|
+
|
|
22
|
+
foldkit-mixins
|
|
23
|
+
safely merges Style + Behavior into those Slots
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
This package adds **no component state and no renderer**. It is only a bridge
|
|
27
|
+
between an existing `@foldkit/ui` render seam and the Mixins resolver.
|
|
28
|
+
|
|
29
|
+
## The mental model
|
|
30
|
+
|
|
31
|
+
An `@foldkit/ui` component commonly hands its caller one or more attribute
|
|
32
|
+
bundles:
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
roles
|
|
36
|
+
aria-*
|
|
37
|
+
tabindex
|
|
38
|
+
event handlers
|
|
39
|
+
ChildAttributes
|
|
40
|
+
...
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Those bundles are meaningful, but a raw array is not a public customization
|
|
44
|
+
contract. A caller can accidentally add a second `OnClick`, replace something
|
|
45
|
+
structural, or repeat bespoke merge code at every call site.
|
|
46
|
+
|
|
47
|
+
`foldkit-mixins-ui` gives each supported bundle a stable Slot name:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
@foldkit/ui component
|
|
51
|
+
|
|
|
52
|
+
| attribute bundles
|
|
53
|
+
v
|
|
54
|
+
foldkit-mixins-ui Slots
|
|
55
|
+
|
|
|
56
|
+
| Style + Behavior
|
|
57
|
+
v
|
|
58
|
+
foldkit-mixins resolver
|
|
59
|
+
|
|
|
60
|
+
v
|
|
61
|
+
component-owned attrs + safe additions
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
So the component author keeps control of the component, while callers get a
|
|
65
|
+
typed place to extend it.
|
|
66
|
+
|
|
67
|
+
## When to use it
|
|
68
|
+
|
|
69
|
+
Use this package when:
|
|
70
|
+
|
|
71
|
+
- you already use `@foldkit/ui`;
|
|
72
|
+
- the component exposes a consumer render seam such as `toView`;
|
|
73
|
+
- you want reusable styling, ARIA decoration, analytics, or element-level
|
|
74
|
+
behavior around that component;
|
|
75
|
+
- you want conflicts to be diagnosed rather than resolved by attribute order.
|
|
76
|
+
|
|
77
|
+
Do **not** use it to add application/component state. State belongs in the
|
|
78
|
+
component's Submodel or the application Model. A Mixins `Behavior` contributes
|
|
79
|
+
element-level attributes and optional Mount behavior; it is not a hidden state
|
|
80
|
+
container.
|
|
81
|
+
|
|
82
|
+
If you are building your own view rather than adapting `@foldkit/ui`, publish
|
|
83
|
+
Slots directly with [`foldkit-mixins`](../mixins).
|
|
84
|
+
|
|
85
|
+
For Slot / Style / Behavior itself, read [Inside-out view
|
|
86
|
+
composition](../../docs/mixins.md) first.
|
|
87
|
+
|
|
88
|
+
## Install
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
pnpm add foldkit-mixins foldkit-mixins-ui @foldkit/ui
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`foldkit`, `effect`, `foldkit-mixins`, and `@foldkit/ui` are peer dependencies.
|
|
95
|
+
|
|
96
|
+
## Sixty seconds: style a Button without copying it
|
|
97
|
+
|
|
98
|
+
Start with a normal `@foldkit/ui` Button. The adapter publishes its consumer
|
|
99
|
+
attribute bundle as the `button` Slot.
|
|
10
100
|
|
|
11
101
|
```ts
|
|
12
|
-
import {
|
|
13
|
-
import {
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
102
|
+
import type { HtmlBuilder } from 'foldkit/html'
|
|
103
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
104
|
+
import * as UiButton from '@foldkit/ui/button'
|
|
105
|
+
import { Style } from 'foldkit-mixins'
|
|
106
|
+
import { Button, ButtonSlots } from 'foldkit-mixins-ui'
|
|
107
|
+
|
|
108
|
+
const Message = defineMessageUnion({ Saved: {} })
|
|
109
|
+
type Message = typeof Message.Type
|
|
110
|
+
|
|
111
|
+
const SaveStyle = Style.forSlots(ButtonSlots)({
|
|
112
|
+
button: Style.class('btn btn-primary'),
|
|
113
|
+
})
|
|
114
|
+
|
|
115
|
+
const saveButton = (h: HtmlBuilder<Message>) =>
|
|
116
|
+
UiButton.view(
|
|
117
|
+
{
|
|
118
|
+
onClick: Message.Saved({}),
|
|
119
|
+
toView: attributes => {
|
|
120
|
+
const slots = Button.resolve(attributes, [SaveStyle.mixin], {
|
|
121
|
+
input: undefined,
|
|
122
|
+
h,
|
|
123
|
+
})
|
|
124
|
+
|
|
125
|
+
return h.button(slots.button, ['Save'])
|
|
126
|
+
},
|
|
21
127
|
},
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
128
|
+
h,
|
|
129
|
+
)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The important line is:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
Button.resolve(attributes, [SaveStyle.mixin], { input, h })
|
|
25
136
|
```
|
|
26
137
|
|
|
27
|
-
|
|
28
|
-
preserved; Mixin contributions merge through the same deterministic resolver as
|
|
29
|
-
the core package. A Behavior cannot silently take over an event the component
|
|
30
|
-
already owns.
|
|
138
|
+
Conceptually:
|
|
31
139
|
|
|
32
|
-
|
|
140
|
+
```text
|
|
141
|
+
attributes from @foldkit/ui
|
|
142
|
+
+
|
|
143
|
+
Style / Behavior mixins
|
|
144
|
+
|
|
|
145
|
+
v
|
|
146
|
+
Button.resolve(...)
|
|
147
|
+
|
|
|
148
|
+
v
|
|
149
|
+
resolved slot arrays
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The caller never copies Button's internal behavior and never has to know how to
|
|
153
|
+
merge its handlers/ARIA/structural attributes safely.
|
|
154
|
+
|
|
155
|
+
## What `resolve` does
|
|
156
|
+
|
|
157
|
+
`resolve(attributes, mixins, { input, h })` receives the shaped value the
|
|
158
|
+
component passed to its render callback and returns the same shape with published
|
|
159
|
+
attribute bundles resolved through Mixins.
|
|
160
|
+
|
|
161
|
+
For a simple Button:
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
{ button: baseAttributes }
|
|
165
|
+
|
|
|
166
|
+
v
|
|
167
|
+
Button.resolve(...)
|
|
168
|
+
|
|
|
169
|
+
v
|
|
170
|
+
{ button: resolvedAttributes }
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
For richer components, non-slot values pass through untouched. Values such as
|
|
174
|
+
`animatePanel`, `isVisible`, `activeIndex`, or `selectedValue` remain component
|
|
175
|
+
data rather than becoming Mixins slots.
|
|
176
|
+
|
|
177
|
+
`input` is whatever attached Style/Behavior callbacks are allowed to read. In a
|
|
178
|
+
feature view that is often the Surface's projected Model; for purely static
|
|
179
|
+
styling it can be `undefined`.
|
|
180
|
+
|
|
181
|
+
Every adapter is available as both a component namespace (`Button.resolve`,
|
|
182
|
+
`Button.ButtonSlots`) and flat Slot exports such as `ButtonSlots`.
|
|
183
|
+
|
|
184
|
+
## What the resolver protects
|
|
185
|
+
|
|
186
|
+
This package delegates merge semantics to core `foldkit-mixins`; it does not
|
|
187
|
+
simply concatenate arrays.
|
|
188
|
+
|
|
189
|
+
The resolver guarantees that:
|
|
190
|
+
|
|
191
|
+
- component/base attributes survive;
|
|
192
|
+
- `ChildAttribute`s survive by identity, preserving Submodel routing;
|
|
193
|
+
- classes are additive;
|
|
194
|
+
- inline declarations merge by property;
|
|
195
|
+
- an event or scalar attribute has one owner;
|
|
196
|
+
- structural attributes remain protected;
|
|
197
|
+
- conflicting ownership produces a `DiagnosticError` rather than an accidental
|
|
198
|
+
second handler.
|
|
199
|
+
|
|
200
|
+
For example, if the Button already owns its click transition, a Behavior cannot
|
|
201
|
+
silently install a competing `OnClick` at the same Slot.
|
|
202
|
+
|
|
203
|
+
That is the main reason to use this adapter instead of another `className` or
|
|
204
|
+
`attributes` escape hatch.
|
|
205
|
+
|
|
206
|
+
## Submodel components remain Submodels
|
|
207
|
+
|
|
208
|
+
Some `@foldkit/ui` components publish `ChildAttribute`s carrying the child
|
|
209
|
+
state-machine dispatcher.
|
|
210
|
+
|
|
211
|
+
The resolver preserves those attributes, so adapting the render seam does **not**
|
|
212
|
+
flatten or bypass the child boundary:
|
|
213
|
+
|
|
214
|
+
```text
|
|
215
|
+
parent view
|
|
216
|
+
|
|
|
217
|
+
resolved Slot attrs
|
|
218
|
+
|
|
|
219
|
+
ChildAttribute
|
|
220
|
+
|
|
|
221
|
+
component Submodel dispatcher
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, and Calendar all rely on this
|
|
225
|
+
behavior.
|
|
226
|
+
|
|
227
|
+
Per-item components can also return structured groups rather than one flat Slot
|
|
228
|
+
array. The adapter preserves that shape. For example:
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
Tabs -> { tablist, tabs, activeIndex }
|
|
232
|
+
RadioGroup -> { group, options, selectedValue, hiddenInput }
|
|
233
|
+
Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
One Slot contribution can apply to each repeated item while every item's base
|
|
237
|
+
attributes keep their own event ownership.
|
|
238
|
+
|
|
239
|
+
## Supported components
|
|
240
|
+
|
|
241
|
+
This is reference material; you do not need to memorize it to understand the
|
|
242
|
+
adapter.
|
|
33
243
|
|
|
34
244
|
| Component | Slots |
|
|
35
245
|
| --- | --- |
|
|
@@ -47,17 +257,39 @@ already owns.
|
|
|
47
257
|
| Slider | `root`, `track`, `filledTrack`, `thumb`, `label`, `hiddenInput` |
|
|
48
258
|
| Tabs | `tablist`, `tab`, `panel` |
|
|
49
259
|
| RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
|
|
50
|
-
| Calendar |
|
|
260
|
+
| Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
|
|
261
|
+
|
|
262
|
+
## Why some components cannot be adapted
|
|
263
|
+
|
|
264
|
+
The bridge needs a **consumer-visible attribute bundle**. If a component builds
|
|
265
|
+
its entire element tree internally and exposes no `toView`-style seam, there is
|
|
266
|
+
nothing for Mixins to attach to.
|
|
267
|
+
|
|
268
|
+
Currently `Menu`, `Listbox`, `ComboBox`, and `DatePicker` fall into that category.
|
|
269
|
+
They cannot be adapted here without a change to their upstream component API.
|
|
270
|
+
That is a limitation of the exposed render seam, not of Slot resolution.
|
|
51
271
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
272
|
+
Other `@foldkit/ui` modules—`Toast`, `FileDrop`, `VirtualList`, `DragAndDrop`,
|
|
273
|
+
`Anchor`, `HoverIntent`, and `Animation`—simply do not have adapters here yet.
|
|
274
|
+
`FileDrop` does expose a render seam, so it is an example that could be added
|
|
275
|
+
without changing `@foldkit/ui`.
|
|
276
|
+
|
|
277
|
+
## Status
|
|
278
|
+
|
|
279
|
+
The API is still settling in the `0.x` series. This package should stay small:
|
|
280
|
+
|
|
281
|
+
```text
|
|
282
|
+
component state / accessibility -> @foldkit/ui
|
|
283
|
+
merge semantics -> foldkit-mixins
|
|
284
|
+
adapter metadata -> foldkit-mixins-ui
|
|
285
|
+
```
|
|
56
286
|
|
|
57
|
-
|
|
287
|
+
If behavior starts moving from the component into this package, the abstraction
|
|
288
|
+
boundary is going in the wrong direction.
|
|
58
289
|
|
|
59
|
-
|
|
60
|
-
expose no attribute bundles, so there is nothing to resolve against; they are not
|
|
61
|
-
adapted.
|
|
290
|
+
## See also
|
|
62
291
|
|
|
63
|
-
|
|
292
|
+
- [Inside-out view composition](../../docs/mixins.md) — Slot / Style / Behavior mental model.
|
|
293
|
+
- [`foldkit-mixins`](../mixins) — resolver and extension contracts.
|
|
294
|
+
- [`foldkit-mixins-surface`](../mixins-surface) — derives a SlotView boundary from a Surface.
|
|
295
|
+
- [`examples/todo-app`](../../examples/todo-app) — Button and Checkbox adapted in a complete application.
|
package/package.json
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldkit-mixins-ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Published slot contracts and mixin adapters for @foldkit/ui, built on foldkit-mixins.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"foldkit",
|
|
7
|
+
"effect",
|
|
8
|
+
"slots",
|
|
9
|
+
"styling",
|
|
10
|
+
"ui-components",
|
|
11
|
+
"headless-ui"
|
|
12
|
+
],
|
|
5
13
|
"type": "module",
|
|
6
14
|
"license": "MIT",
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
7
18
|
"author": "Patrick Glenn <doeixd@gmail.com>",
|
|
8
19
|
"repository": {
|
|
9
20
|
"type": "git",
|
|
@@ -30,7 +41,7 @@
|
|
|
30
41
|
"@foldkit/ui": "^0.158.2",
|
|
31
42
|
"effect": "^4.0.0-rc.112",
|
|
32
43
|
"foldkit": "^0.158.2",
|
|
33
|
-
"foldkit-mixins": "^0.
|
|
44
|
+
"foldkit-mixins": "^0.3.0"
|
|
34
45
|
},
|
|
35
46
|
"devDependencies": {
|
|
36
47
|
"@foldkit/ui": "0.158.2",
|
|
@@ -38,7 +49,7 @@
|
|
|
38
49
|
"foldkit": "0.158.2",
|
|
39
50
|
"tsdown": "^0.23.0",
|
|
40
51
|
"typescript": "^5.7.2",
|
|
41
|
-
"foldkit-mixins": "0.
|
|
52
|
+
"foldkit-mixins": "0.3.0"
|
|
42
53
|
},
|
|
43
54
|
"scripts": {
|
|
44
55
|
"build": "tsdown",
|