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.
Files changed (2) hide show
  1. package/README.md +266 -34
  2. package/package.json +14 -3
package/README.md CHANGED
@@ -1,35 +1,245 @@
1
- # foldkit-mixins-ui
1
+ # `foldkit-mixins-ui`
2
2
 
3
- Published slot contracts and mixin adapters for [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui),
4
- built on [`foldkit-mixins`](../mixins).
3
+ Adapts [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui) render seams into
4
+ [`foldkit-mixins`](../mixins) slots.
5
5
 
6
- `@foldkit/ui` components do not own markup: they build typed attribute bundles
7
- and hand them to a consumer `toView` callback. This package formalizes those
8
- bundles as `Slots` contracts and resolves attached Style/Behavior Mixins around
9
- them, so you can customize an official component without copying it.
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 { Button as UiButton } from 'foldkit-mixins-ui'
13
- import { Button } from '@foldkit/ui/button'
14
-
15
- Button.view(
16
- {
17
- onClick: Saved(),
18
- toView: attributes => {
19
- const slots = UiButton.resolve(attributes, [SaveStyle.mixin], { input, h })
20
- return h.button(slots.button, ['Save'])
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
- h,
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
- Base accessibility attributes, event Messages and any `ChildAttribute` are
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
- ## Components
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 | shared top-level groups plus `columnHeader`/`weekRow`/`dayCell`/`dayButton`/`monthCell`/`monthButton`/`yearCell`/`yearButton` |
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
- Submodel components (Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, Calendar)
53
- publish `ChildAttribute`s, which carry the child boundary's dispatcher; the
54
- resolver preserves them by identity. The nested components apply one slot
55
- contribution to every item while each item's base keeps its own event ownership.
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
- ## Limits
287
+ If behavior starts moving from the component into this package, the abstraction
288
+ boundary is going in the wrong direction.
58
289
 
59
- `Menu`, `Listbox`, `ComboBox` and `DatePicker` build their own element tree and
60
- expose no attribute bundles, so there is nothing to resolve against; they are not
61
- adapted.
290
+ ## See also
62
291
 
63
- The API is still settling (`0.1.0`). See [DESIGN.md](../../docs/design/mixins-DESIGN.md).
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.1.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.1.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.1.0"
52
+ "foldkit-mixins": "0.3.0"
42
53
  },
43
54
  "scripts": {
44
55
  "build": "tsdown",