foldkit-mixins-ui 0.3.0 → 0.5.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 CHANGED
@@ -116,14 +116,7 @@ const saveButton = (h: HtmlBuilder<Message>) =>
116
116
  UiButton.view(
117
117
  {
118
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
- },
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.resolve(attributes, [SaveStyle.mixin], { input, h })
128
+ toView: Button.toView(mixins, { h }, draw)
136
129
  ```
137
130
 
138
131
  Conceptually:
@@ -143,15 +136,121 @@ attributes from @foldkit/ui
143
136
  Style / Behavior mixins
144
137
  |
145
138
  v
146
- Button.resolve(...)
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
153
146
  merge its handlers/ARIA/structural attributes safely.
154
147
 
148
+ ## Follow the click
149
+
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.
159
+
160
+ Start by adding a class. Then add a non-conflicting attribute if needed.
161
+ Do not install another `OnClick` to intercept the component: the resolver
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
+ `resolve` is the seam underneath, for bundles already in hand: a view that
240
+ receives a Tabs `render` as its input, or a Calendar whose Mixins read the
241
+ mode it is showing, which is only known once the attributes arrive:
242
+ ```ts
243
+ import type { CalendarAttributes } from '@foldkit/ui/calendar'
244
+ import { Calendar, CalendarSlots } from 'foldkit-mixins-ui'
245
+
246
+ const CalendarStyle = Style.forSlots(CalendarSlots)({
247
+ root: Style.whenInput<CalendarAttributes['_tag']>(mode => mode === 'Years', Style.class('years')),
248
+ })
249
+
250
+ const resolveCalendar = (attributes: CalendarAttributes, h: HtmlBuilder<Message>) =>
251
+ Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
252
+ ```
253
+
155
254
  ## What `resolve` does
156
255
 
157
256
  `resolve(attributes, mixins, { input, h })` receives the shaped value the
@@ -175,11 +274,21 @@ For richer components, non-slot values pass through untouched. Values such as
175
274
  data rather than becoming Mixins slots.
176
275
 
177
276
  `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`.
277
+ feature view that is often the Surface's projected Model; leave it out when no
278
+ attached Mixin reads one.
279
+
280
+ What `resolve` returns (and `draw` receives) has a name for each adapter:
281
+ `ResolvedButton<Message>`, `ResolvedInput<Message>`, `ResolvedDialog<Message>`,
282
+ `ResolvedRadioGroup<Value, Message>` and `ResolvedRadioOption<Value, Message>`,
283
+ `ResolvedTabs<Value, Message>`, `ResolvedCalendar<Message>`, and so on, so a
284
+ helper that draws part of a component can be typed without `ReturnType`.
285
+ `ResolvedTextarea`'s `textarea` bundle is typed for `h.textarea`, which refuses
286
+ `InnerHTML`; the resolver refuses an `InnerHTML` from any Mixin, so no cast is
287
+ needed.
288
+
289
+ Every adapter is available as both a component namespace (`Button.toView`,
290
+ `Button.resolve`, `Button.ButtonSlots`) and flat Slot exports such as
291
+ `ButtonSlots`.
183
292
 
184
293
  ## What the resolver protects
185
294
 
@@ -254,11 +363,164 @@ adapter.
254
363
  | Dialog | `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton` |
255
364
  | Popover | `button`, `panel`, `backdrop`, `arrow` |
256
365
  | Tooltip | `trigger`, `panel` |
366
+ | HoverIntent | `trigger`, `panel` (open and close delays with intent, for a hover card or a menu) |
257
367
  | Slider | `root`, `track`, `filledTrack`, `thumb`, `label`, `hiddenInput` |
258
368
  | Tabs | `tablist`, `tab`, `panel` |
259
369
  | RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
370
+ | Anchor | a Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id |
260
371
  | Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
261
372
 
373
+ ## Recipes
374
+
375
+ The adapters only name slots. `Recipes` gives those slots a look: one
376
+ `Style.recipeFor` per contract (`Button`, `Input`, `Textarea`, `Checkbox`,
377
+ `Switch`, `Dialog`, `Tabs`, `Segmented`), built on the tokens of `foldkit-mixins/theme`.
378
+ Select variants, hand the pieces to `Style.forSlots`, and attach the result
379
+ like any other Style:
380
+
381
+ ```ts
382
+ import { Layers, Style } from 'foldkit-mixins'
383
+ import { Theme } from 'foldkit-mixins/theme'
384
+ import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
385
+
386
+ const DeleteStyle = Style.forSlots(ButtonSlots)(
387
+ Recipes.Button({ tone: 'danger', variant: 'outline', size: 'sm' }),
388
+ )
389
+
390
+ const L = Layers.standard
391
+ const palette = Theme.oklch({ accent: { h: 280, c: 0.15, l: '60%' } })
392
+
393
+ export const sheet = Style.stylesheet(
394
+ L.declare,
395
+ L.in('tokens', Theme.root(Theme.tokens)),
396
+ L.in('theme', Theme.root(palette)),
397
+ DeleteStyle,
398
+ )
399
+ ```
400
+
401
+ `DeleteStyle.mixin` then goes to `Button.toView` as in the first example.
402
+
403
+ What a recipe assumes and does:
404
+
405
+ - **The page ships the tokens.** Every value is a `var(--fk-…)` reference to
406
+ `Theme.tokens` or a `Theme.oklch` palette, so a scoped theme or a knob
407
+ override restyles every recipe with no new CSS.
408
+ - **Bases sit in `components`, variants in `variants`** of `Layers.standard`,
409
+ so an application's `app` layer overrides both without specificity fights.
410
+ Every declaration is a layered rule and none is inline style, since inline
411
+ style beats every layer and could not be overridden this way:
412
+
413
+ ```ts
414
+ const Red = Style.forSlots(ButtonSlots)(
415
+ { button: Style.self({ background: 'red' }) },
416
+ { layer: L.layer('app') },
417
+ )
418
+ // Style.stylesheet(L.declare, …, DeleteStyle, Red): Red's background wins.
419
+ ```
420
+ - **State comes from the component's own attributes.** Checked, selected, and
421
+ disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
422
+ which `@foldkit/ui` already writes; no `whenInput` is needed.
423
+ - **Tone and variant are independent.** A tone sets a few private custom
424
+ properties that `solid`, `outline`, and `ghost` read — except `primary`,
425
+ which is ink by definition, and `icon`, which fixes its own square geometry
426
+ (combine it with `size: null`, since a density would un-square it).
427
+ - **On a colored band, unfilled buttons take the band's color.** `outline` and
428
+ `ghost` draw their text in the tone's ink, which reads on the page's surface
429
+ and not on a band of the accent. A band sets
430
+ `Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for its
431
+ headings, and their text is the band's.
432
+
433
+ Adjust a recipe with `extend` instead of forking it. Base pieces compose per
434
+ slot, a variant's pieces compose over the shipped ones, and compounds append:
435
+
436
+ ```ts
437
+ const BrandButton = Recipes.Button.extend({
438
+ base: { button: Style.class('brand-button') },
439
+ variants: { size: { lg: { button: Style.class('brand-button-lg') } } },
440
+ })
441
+ ```
442
+
443
+ `Recipes.Badge` is a function rather than a variant selection: one style serves
444
+ badges in every state, so every tone is present at once and there is no axis
445
+ to select. It takes the attribute carrying the value and the value-to-tone
446
+ map; values the map leaves out keep the base pill:
447
+
448
+ ```ts
449
+ const EntryStyle = Style.forSlots(EntrySlots)(
450
+ {
451
+ badge: Recipes.Badge({
452
+ attribute: 'data-state',
453
+ tones: { Published: 'success', Changed: 'warning' },
454
+ }).badge,
455
+ },
456
+ )
457
+ ```
458
+
459
+ Like the variant recipes it reads `Theme.tokens` and `Theme.oklch` tokens and
460
+ keeps the base in `components` with each tone in `variants`.
461
+
462
+ `Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
463
+ buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
464
+ The pressed option rises from the tray: that rule lives on the group, so icon
465
+ tiles take the group piece alone. `tray` is a muted tray or a plain row (which
466
+ sets no `display`: the Builder owns its narrow tabs' visibility); `size` is
467
+ text density:
468
+
469
+ ```ts
470
+ const SegmentedStyle = Style.forSlots(SegmentedSlots)(
471
+ {
472
+ group: Recipes.Segmented({ tray: 'plain', size: 'sm' }).group ?? Style.empty,
473
+ option: Recipes.Segmented({ tray: 'plain', size: 'sm' }).option ?? Style.empty,
474
+ },
475
+ { layer: L.layer('app') },
476
+ )
477
+ ```
478
+
479
+ ## Mechanisms
480
+
481
+ `Touch` and `Icons` are style mechanisms, not components: no slots, no views.
482
+ Compose them into your own slots. `Touch.target` floors one control at 44px
483
+ where the pointer is coarse; `Touch.targets` floors every boxed control a
484
+ region draws. `Icons.glyph(size)` draws the icon in `--icon` before the
485
+ element's words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from
486
+ an attribute's value, where `icons` maps each value to its resolved `url(…)`:
487
+
488
+ ```ts
489
+ const TileStyle = Style.forSlots(TileSlots)(
490
+ {
491
+ tile: Style.compose(
492
+ Touch.target,
493
+ Icons.glyph('1rem'),
494
+ Icons.byAttribute('data-block', { Hero: iconUrl('hero') }),
495
+ ),
496
+ },
497
+ { layer: L.layer('app') },
498
+ )
499
+ ```
500
+
501
+ ## Accessibility patterns
502
+
503
+ Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
504
+ slots a widget of that kind must publish and what each must expose. The
505
+ catalog lists them with a `tier` (`stateful` for a Submodel, `stateless` for
506
+ a decorated native control), the ARIA `roles` involved, and the platform
507
+ `floor`: what the widget relies on the browser for (`focus-trap`,
508
+ `escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here
509
+ reimplements it and a reader or an agent can ask.
510
+
511
+ ```ts
512
+ import { A11y } from 'foldkit-mixins'
513
+ import { Patterns } from 'foldkit-mixins-ui'
514
+
515
+ A11y.validate(Patterns.Tabs, MyTabsSlots) // [] when a custom tabs view publishes what tabs need
516
+ Patterns.catalog.find(entry => entry.name === 'dialog')?.floor // ['focus-trap', 'escape-dismiss', ...]
517
+ ```
518
+
519
+ A test iterates the catalog and validates each adapter's own Slots against
520
+ its pattern, so an adapter cannot drift from the contract it claims. The
521
+ patterns are written separately from the Slots, which is what makes the
522
+ check mean something.
523
+
262
524
  ## Why some components cannot be adapted
263
525
 
264
526
  The bridge needs a **consumer-visible attribute bundle**. If a component builds
@@ -270,7 +532,7 @@ They cannot be adapted here without a change to their upstream component API.
270
532
  That is a limitation of the exposed render seam, not of Slot resolution.
271
533
 
272
534
  Other `@foldkit/ui` modules—`Toast`, `FileDrop`, `VirtualList`, `DragAndDrop`,
273
- `Anchor`, `HoverIntent`, and `Animation`—simply do not have adapters here yet.
535
+ and `Animation`—simply do not have adapters here yet.
274
536
  `FileDrop` does expose a render seam, so it is an example that could be added
275
537
  without changing `@foldkit/ui`.
276
538