foldkit-mixins-ui 0.7.0 → 0.9.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 +102 -20
- package/dist/index.d.mts +3632 -97
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +4290 -276
- 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,65 @@ 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
|
+
| `CodeBlock` | `{ code, tokens?, language?, title?, lineNumbers?, copy? }`. `tokens` are `{ from, to, kind }`, as `foldkit-richtext-code` and `foldkit-richtext-code-shiki` tokenizers return them; each is drawn with `data-kind`, and a token out of order or outside the code throws. The block's text is the code exactly. `copy: { onCopy?, copied? }`: `onCopy` gets the code, so run `copyText` from `foldkit-primitives`; without it the button has no handler, for a page whose script copies. `CodeBlock.linesOf` is the cut. | No axis. Colors each kind from the theme's `syntax` group; `data-line-numbers` numbers lines, `data-copied` marks a copy done. Slots `root`, `header`, `title`, `copy`, `body`, `code`, `line`, `token`. |
|
|
436
|
+
| `Empty` | `{ title, description?, icon?, action? }`. | No axis. Slots `root`, `icon`, `title`, `description`, `action`. |
|
|
437
|
+
| `Icon` | `{ content, label? }`. A `label` is `role="img"`; without one the glyph is `aria-hidden`. | `size`: `sm`, `md` (default), `lg`. Slot `glyph`. |
|
|
438
|
+
| `Item` | `{ content, media?, title?, description?, actions? }`. | `density`: `comfortable` (default), `compact`. Slots `root`, `media`, `content`, `title`, `description`, `actions`. |
|
|
439
|
+
| `Kbd` | `{ key }`. Names the key. | No axis. Slot `key`. |
|
|
440
|
+
| `Label` | `{ for, text }`. `for` is the control's id. | No axis. Slot `label`. |
|
|
441
|
+
| `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`. |
|
|
442
|
+
| `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin. The viewport is tabbable. | `orientation`: `vertical` (default), `horizontal`, `both`. Slot `viewport`. |
|
|
443
|
+
| `Separator` | `{ orientation? }`, horizontal by default. A vertical rule needs its container to set the cross size. | `orientation`: `horizontal` (default), `vertical`. Slot `rule`. |
|
|
444
|
+
| `Skeleton` | `{ label? }`. `role="status"`. Stack one bar per line. | `shape`: `bar` (default), `circle`. Slot `bar`. |
|
|
445
|
+
| `Spinner` | `{ label? }`. `role="status"`. | `size`: `sm`, `md` (default). Slot `wheel`. |
|
|
446
|
+
| `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`. |
|
|
447
|
+
| `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
448
|
|
|
390
449
|
## Recipes
|
|
391
450
|
|
|
392
|
-
The adapters only name slots. `Recipes` gives those slots
|
|
393
|
-
`Style.recipeFor` per contract
|
|
394
|
-
`
|
|
451
|
+
The adapters only name slots. `Recipes` gives those slots, and the vocabulary
|
|
452
|
+
above, a look: one `Style.recipeFor` per contract, built on the tokens of
|
|
453
|
+
`foldkit-mixins/theme`.
|
|
395
454
|
Select variants, hand the pieces to `Style.forSlots`, and attach the result
|
|
396
455
|
like any other Style:
|
|
397
456
|
|
|
@@ -440,7 +499,11 @@ What a recipe assumes and does:
|
|
|
440
499
|
- **Tone and variant are independent.** A tone sets a few private custom
|
|
441
500
|
properties that `solid`, `outline`, and `ghost` read — except `primary`,
|
|
442
501
|
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).
|
|
502
|
+
(combine it with `size: null`, since a density would un-square it). A tone
|
|
503
|
+
also carries the line an `outline` draws: the fill, or for `neutral`, whose
|
|
504
|
+
fill is a quiet grey, the page's default line. A neutral Checkbox or Switch
|
|
505
|
+
that is on is in the page's ink, not the neutral grey, so it stands out
|
|
506
|
+
without a color.
|
|
444
507
|
- **On a colored band, unfilled buttons take the band's color.** `outline` and
|
|
445
508
|
`ghost` draw their text in the tone's ink, which reads on the page's surface
|
|
446
509
|
and not on a band of the accent. A band sets
|
|
@@ -495,6 +558,11 @@ const AddressStyle = Style.forSlots(FieldSlots)({
|
|
|
495
558
|
`control` is in `variants`, so it wins over a `components` look on the same
|
|
496
559
|
slot; over a look of your own in a later layer, say the same in that layer.
|
|
497
560
|
|
|
561
|
+
`Recipes.Tabs({ variant: 'pill' })`'s chosen tab is the accent's tint and ink,
|
|
562
|
+
as a pressed Segmented option is. To look at every recipe in every variant and
|
|
563
|
+
state at once, in both schemes, write the specimen page:
|
|
564
|
+
`pnpm --filter foldkit-mixins-ui specimen <out.html> [hue]`.
|
|
565
|
+
|
|
498
566
|
`Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
|
|
499
567
|
buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
|
|
500
568
|
The pressed option takes the accent's tint, flat: that rule lives on the
|
|
@@ -558,20 +626,34 @@ its pattern, so an adapter cannot drift from the contract it claims. The
|
|
|
558
626
|
patterns are written separately from the Slots, which is what makes the
|
|
559
627
|
check mean something.
|
|
560
628
|
|
|
561
|
-
## Why some components
|
|
562
|
-
|
|
563
|
-
The bridge needs a **consumer-visible attribute bundle**.
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
629
|
+
## Why some components needed a fork
|
|
630
|
+
|
|
631
|
+
The bridge needs a **consumer-visible attribute bundle**. `Menu`,
|
|
632
|
+
`Listbox`, `ComboBox`, `DatePicker`, and `Toast` build (parts of) their
|
|
633
|
+
element tree internally and expose no `toView`-style seam, so there is
|
|
634
|
+
nothing for Mixins to attach to — a limitation of the exposed render seam,
|
|
635
|
+
not of Slot resolution. Each is transcribed from the pinned `@foldkit/ui`
|
|
636
|
+
source (attributed in its module) with the missing `toView` added, as
|
|
637
|
+
described above; state, Messages, update, Commands, and Mounts stay
|
|
638
|
+
upstream in every case. If upstream gains seams, the forks go away.
|
|
639
|
+
|
|
640
|
+
`Menu` is the exception that proves the seam rule: its state machine stays
|
|
641
|
+
upstream, but its markup assembly is transcribed into `MenuView` (from the
|
|
642
|
+
pinned `@foldkit/ui` source, attributed there) with the missing `toView`
|
|
643
|
+
added, and `Menu` adapts that fork. `Menu.create` pairs the forked view with
|
|
644
|
+
upstream's `update`, and a parity battery draws both views over the same
|
|
645
|
+
models. If upstream gains a seam, the fork goes away. `Toast` follows the
|
|
646
|
+
same shape: `ToastView.make` binds upstream's `Toast.make` for the payload
|
|
647
|
+
and swaps in the transcribed view; the dismiss control stays inside the
|
|
648
|
+
consumer's `entryToView`, so it is content, not a slot. `Listbox` forks both
|
|
649
|
+
variants over one shared transcription (`ListboxView.create` and
|
|
650
|
+
`ListboxView.Multi.create` bind the upstream bundles; the single and multi
|
|
651
|
+
Models are structurally identical, so the single adaptor maps
|
|
652
|
+
`maybeSelectedValue` to `selectedValues` exactly as upstream's does).
|
|
653
|
+
`Combobox` follows the same shape over its own shared transcription
|
|
654
|
+
(`ComboboxView.create` / `ComboboxView.Multi.create`).
|
|
655
|
+
|
|
656
|
+
`VirtualList`, `DragAndDrop`, and `Animation` do not have adapters here yet.
|
|
575
657
|
|
|
576
658
|
## Status
|
|
577
659
|
|