foldkit-mixins-ui 0.2.0 → 0.4.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 +334 -63
- package/dist/index.d.mts +501 -24
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +812 -14
- package/dist/index.mjs.map +1 -1
- package/package.json +11 -10
package/README.md
CHANGED
|
@@ -1,23 +1,89 @@
|
|
|
1
|
-
# foldkit-mixins-ui
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
`@foldkit/ui`
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
base
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
1
|
+
# `foldkit-mixins-ui`
|
|
2
|
+
|
|
3
|
+
Adapts [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui) render seams into
|
|
4
|
+
[`foldkit-mixins`](../mixins) slots.
|
|
5
|
+
|
|
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.
|
|
21
87
|
|
|
22
88
|
## Install
|
|
23
89
|
|
|
@@ -27,14 +93,10 @@ pnpm add foldkit-mixins foldkit-mixins-ui @foldkit/ui
|
|
|
27
93
|
|
|
28
94
|
`foldkit`, `effect`, `foldkit-mixins`, and `@foldkit/ui` are peer dependencies.
|
|
29
95
|
|
|
30
|
-
##
|
|
31
|
-
|
|
32
|
-
You render an `@foldkit/ui` component and want to style or decorate it without
|
|
33
|
-
copying it. Not every component can be adapted — see [Limits](#limits) — and a
|
|
34
|
-
mixin still owns no state: the component's open/selected/value stays in its own
|
|
35
|
-
Submodel.
|
|
96
|
+
## Sixty seconds: style a Button without copying it
|
|
36
97
|
|
|
37
|
-
|
|
98
|
+
Start with a normal `@foldkit/ui` Button. The adapter publishes its consumer
|
|
99
|
+
attribute bundle as the `button` Slot.
|
|
38
100
|
|
|
39
101
|
```ts
|
|
40
102
|
import type { HtmlBuilder } from 'foldkit/html'
|
|
@@ -46,16 +108,20 @@ import { Button, ButtonSlots } from 'foldkit-mixins-ui'
|
|
|
46
108
|
const Message = defineMessageUnion({ Saved: {} })
|
|
47
109
|
type Message = typeof Message.Type
|
|
48
110
|
|
|
49
|
-
|
|
50
|
-
|
|
111
|
+
const SaveStyle = Style.forSlots(ButtonSlots)({
|
|
112
|
+
button: Style.class('btn btn-primary'),
|
|
113
|
+
})
|
|
51
114
|
|
|
52
|
-
// In a view, with the view's own `h`.
|
|
53
115
|
const saveButton = (h: HtmlBuilder<Message>) =>
|
|
54
116
|
UiButton.view(
|
|
55
117
|
{
|
|
56
118
|
onClick: Message.Saved({}),
|
|
57
119
|
toView: attributes => {
|
|
58
|
-
const slots = Button.resolve(attributes, [SaveStyle.mixin], {
|
|
120
|
+
const slots = Button.resolve(attributes, [SaveStyle.mixin], {
|
|
121
|
+
input: undefined,
|
|
122
|
+
h,
|
|
123
|
+
})
|
|
124
|
+
|
|
59
125
|
return h.button(slots.button, ['Save'])
|
|
60
126
|
},
|
|
61
127
|
},
|
|
@@ -63,17 +129,130 @@ const saveButton = (h: HtmlBuilder<Message>) =>
|
|
|
63
129
|
)
|
|
64
130
|
```
|
|
65
131
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
132
|
+
The important line is:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
Button.resolve(attributes, [SaveStyle.mixin], { input, h })
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Conceptually:
|
|
139
|
+
|
|
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
|
+
## Follow the click
|
|
156
|
+
|
|
157
|
+
`UiButton.view` supplies the component's base attributes, including the click
|
|
158
|
+
Message. `Button.resolve` merges the style into those attributes; `h.button`
|
|
159
|
+
puts the result on the actual element. Clicking emits `Saved` to the parent
|
|
160
|
+
update. The name `Saved` is just the example's Message name—it does not mean
|
|
161
|
+
this adapter wrote anything to storage.
|
|
162
|
+
|
|
163
|
+
Start by adding a class. Then add a non-conflicting attribute if needed.
|
|
164
|
+
Do not install another `OnClick` to intercept the component: the resolver
|
|
165
|
+
rejects competing event owners. Keep the original component's attributes in
|
|
166
|
+
the call to `resolve`, including its child attributes and accessibility state.
|
|
167
|
+
|
|
168
|
+
## What `resolve` does
|
|
169
|
+
|
|
170
|
+
`resolve(attributes, mixins, { input, h })` receives the shaped value the
|
|
171
|
+
component passed to its render callback and returns the same shape with published
|
|
172
|
+
attribute bundles resolved through Mixins.
|
|
173
|
+
|
|
174
|
+
For a simple Button:
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
{ button: baseAttributes }
|
|
178
|
+
|
|
|
179
|
+
v
|
|
180
|
+
Button.resolve(...)
|
|
181
|
+
|
|
|
182
|
+
v
|
|
183
|
+
{ button: resolvedAttributes }
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
For richer components, non-slot values pass through untouched. Values such as
|
|
187
|
+
`animatePanel`, `isVisible`, `activeIndex`, or `selectedValue` remain component
|
|
188
|
+
data rather than becoming Mixins slots.
|
|
189
|
+
|
|
190
|
+
`input` is whatever attached Style/Behavior callbacks are allowed to read. In a
|
|
191
|
+
feature view that is often the Surface's projected Model; for purely static
|
|
192
|
+
styling it can be `undefined`.
|
|
193
|
+
|
|
194
|
+
Every adapter is available as both a component namespace (`Button.resolve`,
|
|
195
|
+
`Button.ButtonSlots`) and flat Slot exports such as `ButtonSlots`.
|
|
196
|
+
|
|
197
|
+
## What the resolver protects
|
|
72
198
|
|
|
73
|
-
|
|
74
|
-
|
|
199
|
+
This package delegates merge semantics to core `foldkit-mixins`; it does not
|
|
200
|
+
simply concatenate arrays.
|
|
75
201
|
|
|
76
|
-
|
|
202
|
+
The resolver guarantees that:
|
|
203
|
+
|
|
204
|
+
- component/base attributes survive;
|
|
205
|
+
- `ChildAttribute`s survive by identity, preserving Submodel routing;
|
|
206
|
+
- classes are additive;
|
|
207
|
+
- inline declarations merge by property;
|
|
208
|
+
- an event or scalar attribute has one owner;
|
|
209
|
+
- structural attributes remain protected;
|
|
210
|
+
- conflicting ownership produces a `DiagnosticError` rather than an accidental
|
|
211
|
+
second handler.
|
|
212
|
+
|
|
213
|
+
For example, if the Button already owns its click transition, a Behavior cannot
|
|
214
|
+
silently install a competing `OnClick` at the same Slot.
|
|
215
|
+
|
|
216
|
+
That is the main reason to use this adapter instead of another `className` or
|
|
217
|
+
`attributes` escape hatch.
|
|
218
|
+
|
|
219
|
+
## Submodel components remain Submodels
|
|
220
|
+
|
|
221
|
+
Some `@foldkit/ui` components publish `ChildAttribute`s carrying the child
|
|
222
|
+
state-machine dispatcher.
|
|
223
|
+
|
|
224
|
+
The resolver preserves those attributes, so adapting the render seam does **not**
|
|
225
|
+
flatten or bypass the child boundary:
|
|
226
|
+
|
|
227
|
+
```text
|
|
228
|
+
parent view
|
|
229
|
+
|
|
|
230
|
+
resolved Slot attrs
|
|
231
|
+
|
|
|
232
|
+
ChildAttribute
|
|
233
|
+
|
|
|
234
|
+
component Submodel dispatcher
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, and Calendar all rely on this
|
|
238
|
+
behavior.
|
|
239
|
+
|
|
240
|
+
Per-item components can also return structured groups rather than one flat Slot
|
|
241
|
+
array. The adapter preserves that shape. For example:
|
|
242
|
+
|
|
243
|
+
```text
|
|
244
|
+
Tabs -> { tablist, tabs, activeIndex }
|
|
245
|
+
RadioGroup -> { group, options, selectedValue, hiddenInput }
|
|
246
|
+
Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
One Slot contribution can apply to each repeated item while every item's base
|
|
250
|
+
attributes keep their own event ownership.
|
|
251
|
+
|
|
252
|
+
## Supported components
|
|
253
|
+
|
|
254
|
+
This is reference material; you do not need to memorize it to understand the
|
|
255
|
+
adapter.
|
|
77
256
|
|
|
78
257
|
| Component | Slots |
|
|
79
258
|
| --- | --- |
|
|
@@ -88,38 +267,130 @@ or the flat `ButtonSlots` re-export used above.
|
|
|
88
267
|
| Dialog | `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton` |
|
|
89
268
|
| Popover | `button`, `panel`, `backdrop`, `arrow` |
|
|
90
269
|
| Tooltip | `trigger`, `panel` |
|
|
270
|
+
| HoverIntent | `trigger`, `panel` (open and close delays with intent, for a hover card or a menu) |
|
|
91
271
|
| Slider | `root`, `track`, `filledTrack`, `thumb`, `label`, `hiddenInput` |
|
|
92
272
|
| Tabs | `tablist`, `tab`, `panel` |
|
|
93
273
|
| RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
|
|
274
|
+
| Anchor | a Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id |
|
|
94
275
|
| Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
|
|
95
276
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
277
|
+
## Recipes
|
|
278
|
+
|
|
279
|
+
The adapters only name slots. `Recipes` gives those slots a look: one
|
|
280
|
+
`Style.recipeFor` per contract (`Button`, `Input`, `Textarea`, `Checkbox`,
|
|
281
|
+
`Switch`, `Dialog`, `Tabs`), built on the tokens of `foldkit-mixins/theme`.
|
|
282
|
+
Select variants, hand the pieces to `Style.forSlots`, and attach the result
|
|
283
|
+
like any other Style:
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
import { Layers, Style } from 'foldkit-mixins'
|
|
287
|
+
import { Theme } from 'foldkit-mixins/theme'
|
|
288
|
+
import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
|
|
289
|
+
|
|
290
|
+
const DeleteStyle = Style.forSlots(ButtonSlots)(
|
|
291
|
+
Recipes.Button({ tone: 'danger', variant: 'outline', size: 'sm' }),
|
|
292
|
+
)
|
|
293
|
+
|
|
294
|
+
const L = Layers.standard
|
|
295
|
+
const palette = Theme.oklch({ accent: { h: 280, c: 0.15, l: '60%' } })
|
|
296
|
+
|
|
297
|
+
export const sheet = Style.stylesheet(
|
|
298
|
+
L.declare,
|
|
299
|
+
L.in('tokens', Theme.root(Theme.tokens)),
|
|
300
|
+
L.in('theme', Theme.root(palette)),
|
|
301
|
+
DeleteStyle,
|
|
302
|
+
)
|
|
303
|
+
```
|
|
100
304
|
|
|
101
|
-
|
|
102
|
-
the shaped record the component handed it — `{ tablist, tabs, activeIndex }`,
|
|
103
|
-
`{ group, options, selectedValue, hiddenInput }`, and one of `ResolvedDays` /
|
|
104
|
-
`ResolvedMonths` / `ResolvedYears` keyed by `_tag`. One `tab` contribution
|
|
105
|
-
applies to every tab, while each tab's base keeps its own event ownership: a
|
|
106
|
-
disabled tab publishes no click, so a Behavior may add one there and only there.
|
|
305
|
+
`DeleteStyle.mixin` then goes to `Button.resolve` as in the first example.
|
|
107
306
|
|
|
108
|
-
|
|
307
|
+
What a recipe assumes and does:
|
|
109
308
|
|
|
110
|
-
The
|
|
111
|
-
`
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
309
|
+
- **The page ships the tokens.** Every value is a `var(--fk-…)` reference to
|
|
310
|
+
`Theme.tokens` or a `Theme.oklch` palette, so a scoped theme or a knob
|
|
311
|
+
override restyles every recipe with no new CSS.
|
|
312
|
+
- **Bases sit in `components`, variants in `variants`** of `Layers.standard`,
|
|
313
|
+
so an application's `app` layer overrides both without specificity fights.
|
|
314
|
+
Every declaration is a layered rule and none is inline style, since inline
|
|
315
|
+
style beats every layer and could not be overridden this way:
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
const Red = Style.forSlots(ButtonSlots)(
|
|
319
|
+
{ button: Style.self({ background: 'red' }) },
|
|
320
|
+
{ layer: L.layer('app') },
|
|
321
|
+
)
|
|
322
|
+
// Style.stylesheet(L.declare, …, DeleteStyle, Red): Red's background wins.
|
|
323
|
+
```
|
|
324
|
+
- **State comes from the component's own attributes.** Checked, selected, and
|
|
325
|
+
disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
|
|
326
|
+
which `@foldkit/ui` already writes; no `whenInput` is needed.
|
|
327
|
+
- **Tone and variant are independent.** A tone sets a few private custom
|
|
328
|
+
properties that `solid`, `outline`, and `ghost` read.
|
|
329
|
+
|
|
330
|
+
Adjust a recipe with `extend` instead of forking it. Base pieces compose per
|
|
331
|
+
slot, a variant's pieces compose over the shipped ones, and compounds append:
|
|
332
|
+
|
|
333
|
+
```ts
|
|
334
|
+
const BrandButton = Recipes.Button.extend({
|
|
335
|
+
base: { button: Style.class('brand-button') },
|
|
336
|
+
variants: { size: { lg: { button: Style.class('brand-button-lg') } } },
|
|
337
|
+
})
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
## Accessibility patterns
|
|
341
|
+
|
|
342
|
+
Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
|
|
343
|
+
slots a widget of that kind must publish and what each must expose. The
|
|
344
|
+
catalog lists them with a `tier` (`stateful` for a Submodel, `stateless` for
|
|
345
|
+
a decorated native control), the ARIA `roles` involved, and the platform
|
|
346
|
+
`floor`: what the widget relies on the browser for (`focus-trap`,
|
|
347
|
+
`escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here
|
|
348
|
+
reimplements it and a reader or an agent can ask.
|
|
349
|
+
|
|
350
|
+
```ts
|
|
351
|
+
import { A11y } from 'foldkit-mixins'
|
|
352
|
+
import { Patterns } from 'foldkit-mixins-ui'
|
|
353
|
+
|
|
354
|
+
A11y.validate(Patterns.Tabs, MyTabsSlots) // [] when a custom tabs view publishes what tabs need
|
|
355
|
+
Patterns.catalog.find(entry => entry.name === 'dialog')?.floor // ['focus-trap', 'escape-dismiss', ...]
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
A test iterates the catalog and validates each adapter's own Slots against
|
|
359
|
+
its pattern, so an adapter cannot drift from the contract it claims. The
|
|
360
|
+
patterns are written separately from the Slots, which is what makes the
|
|
361
|
+
check mean something.
|
|
362
|
+
|
|
363
|
+
## Why some components cannot be adapted
|
|
364
|
+
|
|
365
|
+
The bridge needs a **consumer-visible attribute bundle**. If a component builds
|
|
366
|
+
its entire element tree internally and exposes no `toView`-style seam, there is
|
|
367
|
+
nothing for Mixins to attach to.
|
|
368
|
+
|
|
369
|
+
Currently `Menu`, `Listbox`, `ComboBox`, and `DatePicker` fall into that category.
|
|
370
|
+
They cannot be adapted here without a change to their upstream component API.
|
|
371
|
+
That is a limitation of the exposed render seam, not of Slot resolution.
|
|
372
|
+
|
|
373
|
+
Other `@foldkit/ui` modules—`Toast`, `FileDrop`, `VirtualList`, `DragAndDrop`,
|
|
374
|
+
and `Animation`—simply do not have adapters here yet.
|
|
375
|
+
`FileDrop` does expose a render seam, so it is an example that could be added
|
|
376
|
+
without changing `@foldkit/ui`.
|
|
377
|
+
|
|
378
|
+
## Status
|
|
379
|
+
|
|
380
|
+
The API is still settling in the `0.x` series. This package should stay small:
|
|
381
|
+
|
|
382
|
+
```text
|
|
383
|
+
component state / accessibility -> @foldkit/ui
|
|
384
|
+
merge semantics -> foldkit-mixins
|
|
385
|
+
adapter metadata -> foldkit-mixins-ui
|
|
386
|
+
```
|
|
117
387
|
|
|
118
|
-
|
|
388
|
+
If behavior starts moving from the component into this package, the abstraction
|
|
389
|
+
boundary is going in the wrong direction.
|
|
119
390
|
|
|
120
391
|
## See also
|
|
121
392
|
|
|
122
|
-
- [Inside-out view composition](
|
|
123
|
-
|
|
124
|
-
- [`foldkit-mixins`](
|
|
125
|
-
- [`examples/todo-app`](
|
|
393
|
+
- [Inside-out view composition](../../docs/mixins.md) — Slot / Style / Behavior mental model.
|
|
394
|
+
- [`foldkit-mixins`](../mixins) — resolver and extension contracts.
|
|
395
|
+
- [`foldkit-mixins-surface`](../mixins-surface) — derives a SlotView boundary from a Surface.
|
|
396
|
+
- [`examples/todo-app`](../../examples/todo-app) — Button and Checkbox adapted in a complete application.
|