foldkit-mixins-ui 0.4.0 → 0.6.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 +204 -26
- package/dist/index.d.mts +11024 -205
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +401 -30
- package/dist/index.mjs.map +1 -1
- package/package.json +11 -10
package/README.md
CHANGED
|
@@ -116,14 +116,7 @@ const saveButton = (h: HtmlBuilder<Message>) =>
|
|
|
116
116
|
UiButton.view(
|
|
117
117
|
{
|
|
118
118
|
onClick: Message.Saved({}),
|
|
119
|
-
toView:
|
|
120
|
-
const slots = Button.resolve(attributes, [SaveStyle.mixin], {
|
|
121
|
-
input: undefined,
|
|
122
|
-
h,
|
|
123
|
-
})
|
|
124
|
-
|
|
125
|
-
return h.button(slots.button, ['Save'])
|
|
126
|
-
},
|
|
119
|
+
toView: Button.toView([SaveStyle.mixin], { h }, ({ button }) => h.button(button, ['Save'])),
|
|
127
120
|
},
|
|
128
121
|
h,
|
|
129
122
|
)
|
|
@@ -132,7 +125,7 @@ const saveButton = (h: HtmlBuilder<Message>) =>
|
|
|
132
125
|
The important line is:
|
|
133
126
|
|
|
134
127
|
```ts
|
|
135
|
-
Button.
|
|
128
|
+
toView: Button.toView(mixins, { h }, draw)
|
|
136
129
|
```
|
|
137
130
|
|
|
138
131
|
Conceptually:
|
|
@@ -143,10 +136,10 @@ attributes from @foldkit/ui
|
|
|
143
136
|
Style / Behavior mixins
|
|
144
137
|
|
|
|
145
138
|
v
|
|
146
|
-
Button.
|
|
139
|
+
Button.toView(...)
|
|
147
140
|
|
|
|
148
141
|
v
|
|
149
|
-
resolved slot arrays
|
|
142
|
+
draw(resolved slot arrays)
|
|
150
143
|
```
|
|
151
144
|
|
|
152
145
|
The caller never copies Button's internal behavior and never has to know how to
|
|
@@ -154,16 +147,126 @@ merge its handlers/ARIA/structural attributes safely.
|
|
|
154
147
|
|
|
155
148
|
## Follow the click
|
|
156
149
|
|
|
157
|
-
`UiButton.view`
|
|
158
|
-
Message. `Button.
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
this adapter wrote
|
|
150
|
+
`UiButton.view` builds the component's base attributes, including the click
|
|
151
|
+
Message, and calls `toView` with them. `Button.toView` applies the style to
|
|
152
|
+
those attributes and hands the result to `draw`, which puts it on the actual
|
|
153
|
+
element with `h.button`. Clicking emits `Saved` to the parent update. The name
|
|
154
|
+
`Saved` is just the example's Message name—it does not mean this adapter wrote
|
|
155
|
+
anything to storage.
|
|
156
|
+
|
|
157
|
+
`toView` performs no I/O and holds nothing: it is a pure function from the
|
|
158
|
+
component's bundles to your markup, run on every render.
|
|
162
159
|
|
|
163
160
|
Start by adding a class. Then add a non-conflicting attribute if needed.
|
|
164
161
|
Do not install another `OnClick` to intercept the component: the resolver
|
|
165
|
-
rejects competing event owners.
|
|
166
|
-
|
|
162
|
+
rejects competing event owners. Put every resolved bundle on its element,
|
|
163
|
+
adding your own attributes beside it where you need them:
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
import * as UiInput from '@foldkit/ui/input'
|
|
167
|
+
import { Input, InputSlots } from 'foldkit-mixins-ui'
|
|
168
|
+
|
|
169
|
+
const ZipStyle = Style.forSlots(InputSlots)({ input: Style.class('zip') })
|
|
170
|
+
|
|
171
|
+
const zipInput = (h: HtmlBuilder<Message>) =>
|
|
172
|
+
UiInput.view(
|
|
173
|
+
{
|
|
174
|
+
id: 'zip',
|
|
175
|
+
toView: Input.toView([ZipStyle.mixin], { h }, ({ input }) =>
|
|
176
|
+
h.input([...input, h.Autocomplete('off')]),
|
|
177
|
+
),
|
|
178
|
+
},
|
|
179
|
+
h,
|
|
180
|
+
)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## `toView` and `resolve`
|
|
184
|
+
|
|
185
|
+
Every component adapter (all but Anchor, which is a Behavior) has both:
|
|
186
|
+
|
|
187
|
+
```text
|
|
188
|
+
Adapter.toView(mixins, { h, input? }, draw) -> the component's toView
|
|
189
|
+
Adapter.resolve(attributes, mixins, { h, input? }) -> the resolved bundles
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`toView` is `resolve` placed where the component calls back, and is the normal
|
|
193
|
+
path. It fits a stateless component's `view` and a Submodel's `viewInputs`
|
|
194
|
+
alike. The Message type comes from `h`, and a Submodel's value type (a
|
|
195
|
+
RadioGroup's or Tabs' `Value`) from where the `toView` goes, so neither needs
|
|
196
|
+
writing out.
|
|
197
|
+
|
|
198
|
+
A button drawn as a button needs no `draw` at all. `Button.view` takes the
|
|
199
|
+
label, a style, and `@foldkit/ui`'s own config:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
import { Button } from 'foldkit-mixins-ui'
|
|
203
|
+
|
|
204
|
+
const saveButton = (disabled: boolean, h: HtmlBuilder<Message>) =>
|
|
205
|
+
Button.view(
|
|
206
|
+
{
|
|
207
|
+
label: 'Save',
|
|
208
|
+
style: SaveStyle,
|
|
209
|
+
type: 'submit',
|
|
210
|
+
disabled,
|
|
211
|
+
onClick: Message.Saved(),
|
|
212
|
+
},
|
|
213
|
+
h,
|
|
214
|
+
)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
An input or a textarea places its own bundles, so its `view` takes a `draw`.
|
|
218
|
+
`Input.view` and `Textarea.view` take the value and Messages, a style, and
|
|
219
|
+
`@foldkit/ui`'s own config (`type` and `placeholder`, `rows` for a textarea):
|
|
220
|
+
|
|
221
|
+
```ts
|
|
222
|
+
import { Input } from 'foldkit-mixins-ui'
|
|
223
|
+
|
|
224
|
+
const emailField = (value: string, h: HtmlBuilder<Message>) =>
|
|
225
|
+
Input.view(
|
|
226
|
+
{
|
|
227
|
+
id: 'email',
|
|
228
|
+
value,
|
|
229
|
+
onInput: value => Message.TypedEmail({ value }),
|
|
230
|
+
type: 'email',
|
|
231
|
+
placeholder: 'you@example.com',
|
|
232
|
+
style: FieldStyle,
|
|
233
|
+
draw: ({ input, label }, h) => h.div([], [h.label(label, ['Email']), h.input(input)]),
|
|
234
|
+
},
|
|
235
|
+
h,
|
|
236
|
+
)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
`Input.field` and `Textarea.field` draw a whole field from a
|
|
240
|
+
`FieldValidation.Field`: the value, its first error or checking mark as the
|
|
241
|
+
description, and `aria-invalid` where the field is invalid. `changed` maps the
|
|
242
|
+
typed value to a Message; `label` is the text over the control; and `draw`
|
|
243
|
+
places the resolved `label`, `control`, and `description` bundles (the default
|
|
244
|
+
stacks them):
|
|
245
|
+
|
|
246
|
+
```ts
|
|
247
|
+
import { Input } from 'foldkit-mixins-ui'
|
|
248
|
+
|
|
249
|
+
const titleField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message>) =>
|
|
250
|
+
Input.field(
|
|
251
|
+
{ id: 'title', label: 'Title', field, changed: value => Message.TypedTitle({ value }) },
|
|
252
|
+
h,
|
|
253
|
+
)
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
`resolve` is the seam underneath, for bundles already in hand: a view that
|
|
257
|
+
receives a Tabs `render` as its input, or a Calendar whose Mixins read the
|
|
258
|
+
mode it is showing, which is only known once the attributes arrive:
|
|
259
|
+
```ts
|
|
260
|
+
import type { CalendarAttributes } from '@foldkit/ui/calendar'
|
|
261
|
+
import { Calendar, CalendarSlots } from 'foldkit-mixins-ui'
|
|
262
|
+
|
|
263
|
+
const CalendarStyle = Style.forSlots(CalendarSlots)({
|
|
264
|
+
root: Style.whenInput<CalendarAttributes['_tag']>(mode => mode === 'Years', Style.class('years')),
|
|
265
|
+
})
|
|
266
|
+
|
|
267
|
+
const resolveCalendar = (attributes: CalendarAttributes, h: HtmlBuilder<Message>) =>
|
|
268
|
+
Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
|
|
269
|
+
```
|
|
167
270
|
|
|
168
271
|
## What `resolve` does
|
|
169
272
|
|
|
@@ -188,11 +291,21 @@ For richer components, non-slot values pass through untouched. Values such as
|
|
|
188
291
|
data rather than becoming Mixins slots.
|
|
189
292
|
|
|
190
293
|
`input` is whatever attached Style/Behavior callbacks are allowed to read. In a
|
|
191
|
-
feature view that is often the Surface's projected Model;
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
`
|
|
294
|
+
feature view that is often the Surface's projected Model; leave it out when no
|
|
295
|
+
attached Mixin reads one.
|
|
296
|
+
|
|
297
|
+
What `resolve` returns (and `draw` receives) has a name for each adapter:
|
|
298
|
+
`ResolvedButton<Message>`, `ResolvedInput<Message>`, `ResolvedDialog<Message>`,
|
|
299
|
+
`ResolvedRadioGroup<Value, Message>` and `ResolvedRadioOption<Value, Message>`,
|
|
300
|
+
`ResolvedTabs<Value, Message>`, `ResolvedCalendar<Message>`, and so on, so a
|
|
301
|
+
helper that draws part of a component can be typed without `ReturnType`.
|
|
302
|
+
`ResolvedTextarea`'s `textarea` bundle is typed for `h.textarea`, which refuses
|
|
303
|
+
`InnerHTML`; the resolver refuses an `InnerHTML` from any Mixin, so no cast is
|
|
304
|
+
needed.
|
|
305
|
+
|
|
306
|
+
Every adapter is available as both a component namespace (`Button.toView`,
|
|
307
|
+
`Button.resolve`, `Button.ButtonSlots`) and flat Slot exports such as
|
|
308
|
+
`ButtonSlots`.
|
|
196
309
|
|
|
197
310
|
## What the resolver protects
|
|
198
311
|
|
|
@@ -278,7 +391,7 @@ adapter.
|
|
|
278
391
|
|
|
279
392
|
The adapters only name slots. `Recipes` gives those slots a look: one
|
|
280
393
|
`Style.recipeFor` per contract (`Button`, `Input`, `Textarea`, `Checkbox`,
|
|
281
|
-
`Switch`, `Dialog`, `Tabs`), built on the tokens of `foldkit-mixins/theme`.
|
|
394
|
+
`Switch`, `Dialog`, `Tabs`, `Segmented`), built on the tokens of `foldkit-mixins/theme`.
|
|
282
395
|
Select variants, hand the pieces to `Style.forSlots`, and attach the result
|
|
283
396
|
like any other Style:
|
|
284
397
|
|
|
@@ -302,7 +415,7 @@ export const sheet = Style.stylesheet(
|
|
|
302
415
|
)
|
|
303
416
|
```
|
|
304
417
|
|
|
305
|
-
`DeleteStyle.mixin` then goes to `Button.
|
|
418
|
+
`DeleteStyle.mixin` then goes to `Button.toView` as in the first example.
|
|
306
419
|
|
|
307
420
|
What a recipe assumes and does:
|
|
308
421
|
|
|
@@ -325,7 +438,14 @@ What a recipe assumes and does:
|
|
|
325
438
|
disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
|
|
326
439
|
which `@foldkit/ui` already writes; no `whenInput` is needed.
|
|
327
440
|
- **Tone and variant are independent.** A tone sets a few private custom
|
|
328
|
-
properties that `solid`, `outline`, and `ghost` read
|
|
441
|
+
properties that `solid`, `outline`, and `ghost` read — except `primary`,
|
|
442
|
+
which is ink by definition, and `icon`, which fixes its own square geometry
|
|
443
|
+
(combine it with `size: null`, since a density would un-square it).
|
|
444
|
+
- **On a colored band, unfilled buttons take the band's color.** `outline` and
|
|
445
|
+
`ghost` draw their text in the tone's ink, which reads on the page's surface
|
|
446
|
+
and not on a band of the accent. A band sets
|
|
447
|
+
`Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for its
|
|
448
|
+
headings, and their text is the band's.
|
|
329
449
|
|
|
330
450
|
Adjust a recipe with `extend` instead of forking it. Base pieces compose per
|
|
331
451
|
slot, a variant's pieces compose over the shipped ones, and compounds append:
|
|
@@ -337,6 +457,64 @@ const BrandButton = Recipes.Button.extend({
|
|
|
337
457
|
})
|
|
338
458
|
```
|
|
339
459
|
|
|
460
|
+
`Recipes.Badge` is a function rather than a variant selection: one style serves
|
|
461
|
+
badges in every state, so every tone is present at once and there is no axis
|
|
462
|
+
to select. It takes the attribute carrying the value and the value-to-tone
|
|
463
|
+
map; values the map leaves out keep the base pill:
|
|
464
|
+
|
|
465
|
+
```ts
|
|
466
|
+
const EntryStyle = Style.forSlots(EntrySlots)(
|
|
467
|
+
{
|
|
468
|
+
badge: Recipes.Badge({
|
|
469
|
+
attribute: 'data-state',
|
|
470
|
+
tones: { Published: 'success', Changed: 'warning' },
|
|
471
|
+
}).badge,
|
|
472
|
+
},
|
|
473
|
+
)
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
Like the variant recipes it reads `Theme.tokens` and `Theme.oklch` tokens and
|
|
477
|
+
keeps the base in `components` with each tone in `variants`.
|
|
478
|
+
|
|
479
|
+
`Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
|
|
480
|
+
buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
|
|
481
|
+
The pressed option rises from the tray: that rule lives on the group, so icon
|
|
482
|
+
tiles take the group piece alone. `tray` is a muted tray or a plain row (which
|
|
483
|
+
sets no `display`: the Builder owns its narrow tabs' visibility); `size` is
|
|
484
|
+
text density:
|
|
485
|
+
|
|
486
|
+
```ts
|
|
487
|
+
const SegmentedStyle = Style.forSlots(SegmentedSlots)(
|
|
488
|
+
{
|
|
489
|
+
group: Recipes.Segmented({ tray: 'plain', size: 'sm' }).group ?? Style.empty,
|
|
490
|
+
option: Recipes.Segmented({ tray: 'plain', size: 'sm' }).option ?? Style.empty,
|
|
491
|
+
},
|
|
492
|
+
{ layer: L.layer('app') },
|
|
493
|
+
)
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
## Mechanisms
|
|
497
|
+
|
|
498
|
+
`Touch` and `Icons` are style mechanisms, not components: no slots, no views.
|
|
499
|
+
Compose them into your own slots. `Touch.target` floors one control at 44px
|
|
500
|
+
where the pointer is coarse; `Touch.targets` floors every boxed control a
|
|
501
|
+
region draws. `Icons.glyph(size)` draws the icon in `--icon` before the
|
|
502
|
+
element's words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from
|
|
503
|
+
an attribute's value, where `icons` maps each value to its resolved `url(…)`:
|
|
504
|
+
|
|
505
|
+
```ts
|
|
506
|
+
const TileStyle = Style.forSlots(TileSlots)(
|
|
507
|
+
{
|
|
508
|
+
tile: Style.compose(
|
|
509
|
+
Touch.target,
|
|
510
|
+
Icons.glyph('1rem'),
|
|
511
|
+
Icons.byAttribute('data-block', { Hero: iconUrl('hero') }),
|
|
512
|
+
),
|
|
513
|
+
},
|
|
514
|
+
{ layer: L.layer('app') },
|
|
515
|
+
)
|
|
516
|
+
```
|
|
517
|
+
|
|
340
518
|
## Accessibility patterns
|
|
341
519
|
|
|
342
520
|
Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
|