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.
Files changed (2) hide show
  1. package/README.md +90 -28
  2. 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`](../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: 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
+ `@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 { 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'])
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
- h,
24
- )
62
+ h,
63
+ )
25
64
  ```
26
65
 
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.
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 | shared top-level groups plus `columnHeader`/`weekRow`/`dayCell`/`dayButton`/`monthCell`/`monthButton`/`yearCell`/`yearButton` |
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. The nested components apply one slot
55
- contribution to every item while each item's base keeps its own event ownership.
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 `DatePicker` build their own element tree and
60
- expose no attribute bundles, so there is nothing to resolve against; they are not
61
- adapted.
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
- The API is still settling (`0.1.0`). See [DESIGN.md](../../docs/design/mixins-DESIGN.md).
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.1.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.1.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.1.0"
52
+ "foldkit-mixins": "0.2.0"
42
53
  },
43
54
  "scripts": {
44
55
  "build": "tsdown",