foldkit-mixins-ui 0.2.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.
Files changed (2) hide show
  1. package/README.md +233 -63
  2. package/package.json +3 -3
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
96
+ ## Sixty seconds: style a Button without copying it
31
97
 
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.
36
-
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,117 @@ 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
+ ## 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.
72
226
 
73
- Each component is also a namespace: `Button.resolve` and `Button.ButtonSlots`,
74
- or the flat `ButtonSlots` re-export used above.
227
+ Per-item components can also return structured groups rather than one flat Slot
228
+ array. The adapter preserves that shape. For example:
75
229
 
76
- ## Components
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.
77
243
 
78
244
  | Component | Slots |
79
245
  | --- | --- |
@@ -93,33 +259,37 @@ or the flat `ButtonSlots` re-export used above.
93
259
  | RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
94
260
  | Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
95
261
 
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`.
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.
100
267
 
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.
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.
107
271
 
108
- ## Limits
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`.
109
276
 
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.
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
+ ```
117
286
 
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).
287
+ If behavior starts moving from the component into this package, the abstraction
288
+ boundary is going in the wrong direction.
119
289
 
120
290
  ## See also
121
291
 
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.
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,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-mixins-ui",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Published slot contracts and mixin adapters for @foldkit/ui, built on foldkit-mixins.",
5
5
  "keywords": [
6
6
  "foldkit",
@@ -41,7 +41,7 @@
41
41
  "@foldkit/ui": "^0.158.2",
42
42
  "effect": "^4.0.0-rc.112",
43
43
  "foldkit": "^0.158.2",
44
- "foldkit-mixins": "^0.2.0"
44
+ "foldkit-mixins": "^0.3.0"
45
45
  },
46
46
  "devDependencies": {
47
47
  "@foldkit/ui": "0.158.2",
@@ -49,7 +49,7 @@
49
49
  "foldkit": "0.158.2",
50
50
  "tsdown": "^0.23.0",
51
51
  "typescript": "^5.7.2",
52
- "foldkit-mixins": "0.2.0"
52
+ "foldkit-mixins": "0.3.0"
53
53
  },
54
54
  "scripts": {
55
55
  "build": "tsdown",