foldkit-mixins-ui 0.1.0 → 0.2.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 +90 -28
- package/package.json +14 -3
package/README.md
CHANGED
|
@@ -1,33 +1,77 @@
|
|
|
1
1
|
# foldkit-mixins-ui
|
|
2
2
|
|
|
3
3
|
Published slot contracts and mixin adapters for [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui),
|
|
4
|
-
built on [`foldkit-mixins`](
|
|
4
|
+
built on [`foldkit-mixins`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mixins).
|
|
5
5
|
|
|
6
|
-
`@foldkit/ui` components do not own markup
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pnpm add foldkit-mixins foldkit-mixins-ui @foldkit/ui
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`foldkit`, `effect`, `foldkit-mixins`, and `@foldkit/ui` are peer dependencies.
|
|
29
|
+
|
|
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.
|
|
36
|
+
|
|
37
|
+
## Usage
|
|
10
38
|
|
|
11
39
|
```ts
|
|
12
|
-
import {
|
|
13
|
-
import {
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
40
|
+
import type { HtmlBuilder } from 'foldkit/html'
|
|
41
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
42
|
+
import * as UiButton from '@foldkit/ui/button'
|
|
43
|
+
import { Style } from 'foldkit-mixins'
|
|
44
|
+
import { Button, ButtonSlots } from 'foldkit-mixins-ui'
|
|
45
|
+
|
|
46
|
+
const Message = defineMessageUnion({ Saved: {} })
|
|
47
|
+
type Message = typeof Message.Type
|
|
48
|
+
|
|
49
|
+
// Written once, against the contract this package publishes for Button.
|
|
50
|
+
const SaveStyle = Style.forSlots(ButtonSlots)({ button: Style.class('btn btn-primary') })
|
|
51
|
+
|
|
52
|
+
// In a view, with the view's own `h`.
|
|
53
|
+
const saveButton = (h: HtmlBuilder<Message>) =>
|
|
54
|
+
UiButton.view(
|
|
55
|
+
{
|
|
56
|
+
onClick: Message.Saved({}),
|
|
57
|
+
toView: attributes => {
|
|
58
|
+
const slots = Button.resolve(attributes, [SaveStyle.mixin], { input: undefined, h })
|
|
59
|
+
return h.button(slots.button, ['Save'])
|
|
60
|
+
},
|
|
21
61
|
},
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
)
|
|
62
|
+
h,
|
|
63
|
+
)
|
|
25
64
|
```
|
|
26
65
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
the
|
|
30
|
-
|
|
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.
|
|
72
|
+
|
|
73
|
+
Each component is also a namespace: `Button.resolve` and `Button.ButtonSlots`,
|
|
74
|
+
or the flat `ButtonSlots` re-export used above.
|
|
31
75
|
|
|
32
76
|
## Components
|
|
33
77
|
|
|
@@ -47,17 +91,35 @@ already owns.
|
|
|
47
91
|
| Slider | `root`, `track`, `filledTrack`, `thumb`, `label`, `hiddenInput` |
|
|
48
92
|
| Tabs | `tablist`, `tab`, `panel` |
|
|
49
93
|
| RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
|
|
50
|
-
| Calendar |
|
|
94
|
+
| Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
|
|
51
95
|
|
|
52
96
|
Submodel components (Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, Calendar)
|
|
53
97
|
publish `ChildAttribute`s, which carry the child boundary's dispatcher; the
|
|
54
|
-
resolver preserves them by identity
|
|
55
|
-
|
|
98
|
+
resolver preserves them by identity, so spreading a resolved bundle into the
|
|
99
|
+
parent's markup still routes through the component's `toParentMessage`.
|
|
100
|
+
|
|
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.
|
|
56
107
|
|
|
57
108
|
## Limits
|
|
58
109
|
|
|
59
|
-
`Menu`, `Listbox`, `ComboBox` and
|
|
60
|
-
|
|
61
|
-
|
|
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.
|
|
117
|
+
|
|
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).
|
|
119
|
+
|
|
120
|
+
## See also
|
|
62
121
|
|
|
63
|
-
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldkit-mixins-ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.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.2.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.2.0"
|
|
42
53
|
},
|
|
43
54
|
"scripts": {
|
|
44
55
|
"build": "tsdown",
|