foldkit-mixins-ui 0.6.1 → 0.8.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 +124 -23
- package/dist/index.d.mts +3555 -97
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +4078 -193
- package/dist/index.mjs.map +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -297,7 +297,9 @@ attached Mixin reads one.
|
|
|
297
297
|
What `resolve` returns (and `draw` receives) has a name for each adapter:
|
|
298
298
|
`ResolvedButton<Message>`, `ResolvedInput<Message>`, `ResolvedDialog<Message>`,
|
|
299
299
|
`ResolvedRadioGroup<Value, Message>` and `ResolvedRadioOption<Value, Message>`,
|
|
300
|
-
`ResolvedTabs<Value, Message>`, `ResolvedCalendar<Message>`,
|
|
300
|
+
`ResolvedTabs<Value, Message>`, `ResolvedCalendar<Message>`,
|
|
301
|
+
`ResolvedMenu<Message>` (with `ResolvedMenuGroup`/`ResolvedMenuItem` per
|
|
302
|
+
entry), and so on, so a
|
|
301
303
|
helper that draws part of a component can be typed without `ReturnType`.
|
|
302
304
|
`ResolvedTextarea`'s `textarea` bundle is typed for `h.textarea`, which refuses
|
|
303
305
|
`InnerHTML`; the resolver refuses an `InnerHTML` from any Mixin, so no cast is
|
|
@@ -347,7 +349,7 @@ ChildAttribute
|
|
|
347
349
|
component Submodel dispatcher
|
|
348
350
|
```
|
|
349
351
|
|
|
350
|
-
Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, and
|
|
352
|
+
Dialog, Popover, Tooltip, Slider, Tabs, RadioGroup, Calendar, and Menu all rely on this
|
|
351
353
|
behavior.
|
|
352
354
|
|
|
353
355
|
Per-item components can also return structured groups rather than one flat Slot
|
|
@@ -357,6 +359,10 @@ array. The adapter preserves that shape. For example:
|
|
|
357
359
|
Tabs -> { tablist, tabs, activeIndex }
|
|
358
360
|
RadioGroup -> { group, options, selectedValue, hiddenInput }
|
|
359
361
|
Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
|
|
362
|
+
Menu -> { wrapper, button, backdrop, items, scroll, groups, isVisible }
|
|
363
|
+
Toast -> { container, entries }
|
|
364
|
+
Listbox -> { wrapper, button, backdrop, items, scroll, groups, hiddenInputs, isVisible }
|
|
365
|
+
Combobox -> { wrapper, inputWrapper, input, toggleButton, backdrop, items, scroll, groups, hiddenInputs, isVisible }
|
|
360
366
|
```
|
|
361
367
|
|
|
362
368
|
One Slot contribution can apply to each repeated item while every item's base
|
|
@@ -386,12 +392,64 @@ adapter.
|
|
|
386
392
|
| RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
|
|
387
393
|
| Anchor | a Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id |
|
|
388
394
|
| Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
|
|
395
|
+
| Menu | `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator` (over the `MenuView` fork; see below) |
|
|
396
|
+
| FileDrop | `root`, `input` |
|
|
397
|
+
| Toast | `container`, `entry` (over the `ToastView` fork; the dismiss control stays inside the consumer's `entryToView`) |
|
|
398
|
+
| Listbox | `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator` (over the `ListboxView` fork; single and multi share one transcription) |
|
|
399
|
+
| Combobox | `wrapper`, `inputWrapper`, `input`, `toggleButton`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator` (over the `ComboboxView` fork; single and multi share one transcription) |
|
|
400
|
+
| DatePicker | `trigger`, `panel`, `backdrop` (over the `DatePickerView` fork, which keeps upstream's Popover+Calendar composition and seams only the popover assembly) |
|
|
401
|
+
|
|
402
|
+
## Stateless vocabulary
|
|
403
|
+
|
|
404
|
+
These views own no Model, no Message, and no bundle. Call `X.view(options, h)`.
|
|
405
|
+
Every one takes an optional `style` of its slots and `mixins` beside it. Style
|
|
406
|
+
the slots with the matching recipe. Hide text with `U.srOnly` from
|
|
407
|
+
`foldkit-mixins/utilities`. Name a control with `FieldAssociation`;
|
|
408
|
+
`Label.view` takes the id that derived.
|
|
409
|
+
|
|
410
|
+
```ts
|
|
411
|
+
import { Style } from 'foldkit-mixins'
|
|
412
|
+
import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
|
|
413
|
+
|
|
414
|
+
const Frame = Style.forSlots(AspectRatioSlots)(Recipes.AspectRatio({ ratio: 'video' }))
|
|
415
|
+
const Mark = Style.forSlots(IconSlots)(Recipes.Icon({ size: 'sm' }))
|
|
416
|
+
|
|
417
|
+
// `h` is the view's builder. `content` is `Html`.
|
|
418
|
+
AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
|
|
419
|
+
Icon.view({ content: h.span([], ['!']), label: 'Warning', style: Mark }, h)
|
|
420
|
+
Icon.view({ content: h.span([], ['!']), style: Mark }, h)
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
424
|
+
`Icons.glyph` is the other tool: a mask on an element that already exists.
|
|
425
|
+
|
|
426
|
+
| View | Call | Recipe |
|
|
427
|
+
| --- | --- | --- |
|
|
428
|
+
| `Alert` | `{ title, description?, icon?, assertive? }`. `assertive` is `role="alert"`; otherwise `role="status"`. | `tone`: `info` (default), `success`, `warning`, `error`. Slots `root`, `icon`, `title`, `description`. |
|
|
429
|
+
| `AspectRatio` | `{ content? }`. Slot `frame`. | `ratio`: `square` (default), `video` (16/9), `portrait` (3/4). The corner reads `radius`. |
|
|
430
|
+
| `Avatar` | `{ name, src }`. Initials show until the image covers them. | `size`: `sm`, `md` (default), `lg`. Slots `root`, `fallback`, `image`. |
|
|
431
|
+
| `Badge` | `{ text, tone? }` writes `data-tone`. | `Recipes.Badge({ attribute, tones })` maps that attribute; values outside the map keep the base. Slot `badge`. |
|
|
432
|
+
| `Breadcrumb` | `{ steps: { label, href?, current? }[] }`. `current` is text with `aria-current="page"`; the others are links. | No axis. Slots `root`, `list`, `item`, `link`, `current`. |
|
|
433
|
+
| `ButtonGroup` | `{ label, items }`. `role="group"`. The buttons stay the caller's. `Segmented` is the control that selects. | No axis. Slot `root`. |
|
|
434
|
+
| `Card` | `{ content, title?, description?, footer?, action? }`. | `padding`: `comfortable` (default), `roomy`, `flush`. Slots `root`, `header`, `title`, `description`, `content`, `footer`, `action`. |
|
|
435
|
+
| `Empty` | `{ title, description?, icon?, action? }`. | No axis. Slots `root`, `icon`, `title`, `description`, `action`. |
|
|
436
|
+
| `Icon` | `{ content, label? }`. A `label` is `role="img"`; without one the glyph is `aria-hidden`. | `size`: `sm`, `md` (default), `lg`. Slot `glyph`. |
|
|
437
|
+
| `Item` | `{ content, media?, title?, description?, actions? }`. | `density`: `comfortable` (default), `compact`. Slots `root`, `media`, `content`, `title`, `description`, `actions`. |
|
|
438
|
+
| `Kbd` | `{ key }`. Names the key. | No axis. Slot `key`. |
|
|
439
|
+
| `Label` | `{ for, text }`. `for` is the control's id. | No axis. Slot `label`. |
|
|
440
|
+
| `Pagination` | `{ page, pageCount, onPage, label? }`. Fewer than two pages draws nothing. `Pagination.itemsOf(page, pageCount)` is the stops. | No axis. The current stop reads `aria-current`. Slots `root`, `prev`, `next`, `page`, `ellipsis`. |
|
|
441
|
+
| `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin. The viewport is tabbable. | `orientation`: `vertical` (default), `horizontal`, `both`. Slot `viewport`. |
|
|
442
|
+
| `Separator` | `{ orientation? }`, horizontal by default. A vertical rule needs its container to set the cross size. | `orientation`: `horizontal` (default), `vertical`. Slot `rule`. |
|
|
443
|
+
| `Skeleton` | `{ label? }`. `role="status"`. Stack one bar per line. | `shape`: `bar` (default), `circle`. Slot `bar`. |
|
|
444
|
+
| `Spinner` | `{ label? }`. `role="status"`. | `size`: `sm`, `md` (default). Slot `wheel`. |
|
|
445
|
+
| `Table` | `{ columns: { header, value, numeric? }[], rows, caption? }`. Sorting and selection stay with `foldkit-data-grid`. | No axis. Slots `root`, `caption`, `head`, `headerRow`, `headerCell`, `body`, `row`, `cell`. |
|
|
446
|
+
| `Typography` | `{ level, text }`. The level chooses the element (`h1`–`h4`, `lead`, `body`, `small`, `muted`, `quote`, `code`). | `level`, same set. Defaults to `body`. Slot `text`. |
|
|
389
447
|
|
|
390
448
|
## Recipes
|
|
391
449
|
|
|
392
|
-
The adapters only name slots. `Recipes` gives those slots
|
|
393
|
-
`Style.recipeFor` per contract
|
|
394
|
-
`
|
|
450
|
+
The adapters only name slots. `Recipes` gives those slots, and the vocabulary
|
|
451
|
+
above, a look: one `Style.recipeFor` per contract, built on the tokens of
|
|
452
|
+
`foldkit-mixins/theme`.
|
|
395
453
|
Select variants, hand the pieces to `Style.forSlots`, and attach the result
|
|
396
454
|
like any other Style:
|
|
397
455
|
|
|
@@ -440,7 +498,11 @@ What a recipe assumes and does:
|
|
|
440
498
|
- **Tone and variant are independent.** A tone sets a few private custom
|
|
441
499
|
properties that `solid`, `outline`, and `ghost` read — except `primary`,
|
|
442
500
|
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).
|
|
501
|
+
(combine it with `size: null`, since a density would un-square it). A tone
|
|
502
|
+
also carries the line an `outline` draws: the fill, or for `neutral`, whose
|
|
503
|
+
fill is a quiet grey, the page's default line. A neutral Checkbox or Switch
|
|
504
|
+
that is on is in the page's ink, not the neutral grey, so it stands out
|
|
505
|
+
without a color.
|
|
444
506
|
- **On a colored band, unfilled buttons take the band's color.** `outline` and
|
|
445
507
|
`ghost` draw their text in the tone's ink, which reads on the page's surface
|
|
446
508
|
and not on a band of the accent. A band sets
|
|
@@ -474,12 +536,37 @@ const EntryStyle = Style.forSlots(EntrySlots)(
|
|
|
474
536
|
```
|
|
475
537
|
|
|
476
538
|
Like the variant recipes it reads `Theme.tokens` and `Theme.oklch` tokens and
|
|
477
|
-
keeps the base in `components` with each tone in `variants`.
|
|
539
|
+
keeps the base in `components` with each tone in `variants`. A toned pill is
|
|
540
|
+
grounded on its tone's `subtle`, which keeps the tone's hue over a tinted page.
|
|
541
|
+
|
|
542
|
+
`Recipes.InputGroup` draws a text field with a prefix or suffix, such as an
|
|
543
|
+
address's `/`, as one box: `group` carries the border, its hover and the
|
|
544
|
+
focus ring (while the control inside has focus), `affix` sits inside it,
|
|
545
|
+
muted, and `control` makes the input inside borderless. They are pieces for
|
|
546
|
+
your own group, affix and control slots, as `foldkit-mixins-form`'s field
|
|
547
|
+
publishes them:
|
|
548
|
+
|
|
549
|
+
```ts
|
|
550
|
+
const AddressStyle = Style.forSlots(FieldSlots)({
|
|
551
|
+
group: Recipes.InputGroup.group,
|
|
552
|
+
affix: Recipes.InputGroup.affix,
|
|
553
|
+
text: Style.compose(Recipes.Input({}).input ?? Style.empty, Recipes.InputGroup.control),
|
|
554
|
+
})
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
`control` is in `variants`, so it wins over a `components` look on the same
|
|
558
|
+
slot; over a look of your own in a later layer, say the same in that layer.
|
|
559
|
+
|
|
560
|
+
`Recipes.Tabs({ variant: 'pill' })`'s chosen tab is the accent's tint and ink,
|
|
561
|
+
as a pressed Segmented option is. To look at every recipe in every variant and
|
|
562
|
+
state at once, in both schemes, write the specimen page:
|
|
563
|
+
`pnpm --filter foldkit-mixins-ui specimen <out.html> [hue]`.
|
|
478
564
|
|
|
479
565
|
`Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
|
|
480
566
|
buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
|
|
481
|
-
The pressed option
|
|
482
|
-
tiles take the group piece alone
|
|
567
|
+
The pressed option takes the accent's tint, flat: that rule lives on the
|
|
568
|
+
group, in `variants`, so icon tiles take the group piece alone, and an icon
|
|
569
|
+
button's own background, a variant too, does not hide it. `tray` is a muted tray or a plain row (which
|
|
483
570
|
sets no `display`: the Builder owns its narrow tabs' visibility); `size` is
|
|
484
571
|
text density:
|
|
485
572
|
|
|
@@ -538,20 +625,34 @@ its pattern, so an adapter cannot drift from the contract it claims. The
|
|
|
538
625
|
patterns are written separately from the Slots, which is what makes the
|
|
539
626
|
check mean something.
|
|
540
627
|
|
|
541
|
-
## Why some components
|
|
542
|
-
|
|
543
|
-
The bridge needs a **consumer-visible attribute bundle**.
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
628
|
+
## Why some components needed a fork
|
|
629
|
+
|
|
630
|
+
The bridge needs a **consumer-visible attribute bundle**. `Menu`,
|
|
631
|
+
`Listbox`, `ComboBox`, `DatePicker`, and `Toast` build (parts of) their
|
|
632
|
+
element tree internally and expose no `toView`-style seam, so there is
|
|
633
|
+
nothing for Mixins to attach to — a limitation of the exposed render seam,
|
|
634
|
+
not of Slot resolution. Each is transcribed from the pinned `@foldkit/ui`
|
|
635
|
+
source (attributed in its module) with the missing `toView` added, as
|
|
636
|
+
described above; state, Messages, update, Commands, and Mounts stay
|
|
637
|
+
upstream in every case. If upstream gains seams, the forks go away.
|
|
638
|
+
|
|
639
|
+
`Menu` is the exception that proves the seam rule: its state machine stays
|
|
640
|
+
upstream, but its markup assembly is transcribed into `MenuView` (from the
|
|
641
|
+
pinned `@foldkit/ui` source, attributed there) with the missing `toView`
|
|
642
|
+
added, and `Menu` adapts that fork. `Menu.create` pairs the forked view with
|
|
643
|
+
upstream's `update`, and a parity battery draws both views over the same
|
|
644
|
+
models. If upstream gains a seam, the fork goes away. `Toast` follows the
|
|
645
|
+
same shape: `ToastView.make` binds upstream's `Toast.make` for the payload
|
|
646
|
+
and swaps in the transcribed view; the dismiss control stays inside the
|
|
647
|
+
consumer's `entryToView`, so it is content, not a slot. `Listbox` forks both
|
|
648
|
+
variants over one shared transcription (`ListboxView.create` and
|
|
649
|
+
`ListboxView.Multi.create` bind the upstream bundles; the single and multi
|
|
650
|
+
Models are structurally identical, so the single adaptor maps
|
|
651
|
+
`maybeSelectedValue` to `selectedValues` exactly as upstream's does).
|
|
652
|
+
`Combobox` follows the same shape over its own shared transcription
|
|
653
|
+
(`ComboboxView.create` / `ComboboxView.Multi.create`).
|
|
654
|
+
|
|
655
|
+
`VirtualList`, `DragAndDrop`, and `Animation` do not have adapters here yet.
|
|
555
656
|
|
|
556
657
|
## Status
|
|
557
658
|
|