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 CHANGED
@@ -1,23 +1,89 @@
1
- # foldkit-mixins-ui
2
-
3
- Published slot contracts and mixin adapters for [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui),
4
- built on [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins).
5
-
6
- `@foldkit/ui` components do not own markup. A component works out the attributes
7
- an accessible button, dialog or calendar needs — roles, `aria-*`, tabindex,
8
- event handlers — and hands them to your `toView` callback as named bundles; you
9
- decide the elements. That already lets you style the component, but only by
10
- hand-merging arrays at each call site, and nothing stops you from clobbering the
11
- `OnClick` the component installed.
12
-
13
- This package names those bundles. It publishes each component's attribute groups
14
- as a `foldkit-mixins` `Slots` contract, so a Style or Behavior written once
15
- attaches to `button` or `panel` or `dayCell` by name. `resolve` merges the
16
- attached mixins into the component's own bundles through the core resolver:
17
- base accessibility attributes, event Messages and `ChildAttribute`s are
18
- preserved, classes are additive, and a Behavior that tries to take over an event
19
- the component already owns is a `DiagnosticError` rather than a silent second
20
- handler.
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
- ## Use it when
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
- ## Usage
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
- // Written once, against the contract this package publishes for Button.
50
- const SaveStyle = Style.forSlots(ButtonSlots)({ button: Style.class('btn btn-primary') })
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], { input: undefined, h })
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
- `resolve(attributes, mixins, { input, h })` takes the component's own bundles and
67
- returns them with contributions merged, one resolved array per published slot.
68
- Anything the component passes that is not a slot (`animatePanel`, `isVisible`,
69
- `activeIndex`, `selectedValue`) is returned unchanged. `input` is whatever your
70
- Style/Behavior callbacks read — the model you are rendering, or `undefined` if
71
- they read nothing.
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
- Each component is also a namespace: `Button.resolve` and `Button.ButtonSlots`,
74
- or the flat `ButtonSlots` re-export used above.
199
+ This package delegates merge semantics to core `foldkit-mixins`; it does not
200
+ simply concatenate arrays.
75
201
 
76
- ## Components
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
- Submodel components (Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, Calendar)
97
- publish `ChildAttribute`s, which carry the child boundary's dispatcher; the
98
- resolver preserves them by identity, so spreading a resolved bundle into the
99
- parent's markup still routes through the component's `toParentMessage`.
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
- Tabs, RadioGroup and Calendar have per-item groups, so their `resolve` returns
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
- ## Limits
307
+ What a recipe assumes and does:
109
308
 
110
- The table above is the complete adapted set. `Menu`, `Listbox`, `ComboBox` and
111
- `DatePicker` **cannot** be adapted: they build their whole element tree
112
- internally, expose no `toView`, and hand the consumer no attribute bundles, so
113
- there is nothing for `resolve` to attach to. That is a boundary of the component
114
- API, not of the mixin model. The remaining `@foldkit/ui` modules — `Toast`,
115
- `FileDrop`, `VirtualList`, `DragAndDrop`, `Anchor`, `HoverIntent`, `Animation` —
116
- have no adapter here yet.
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
- The API is still settling (`0.1.0`). See [DESIGN.md](https://github.com/doeixd/foldkit-plus/blob/main/docs/design/mixins-DESIGN.md).
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](https://github.com/doeixd/foldkit-plus/blob/main/docs/mixins.md) — the mental model,
123
- and where `@foldkit/ui` adaptation stops.
124
- - [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins) — the resolver these adapters use.
125
- - [`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app) — Button and Checkbox resolved through this package.
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.