foldkit-mixins-ui 0.7.0 → 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 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>`, and so on, so a
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 Calendar all rely on this
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 a look: one
393
- `Style.recipeFor` per contract (`Button`, `Input`, `Textarea`, `Checkbox`,
394
- `Switch`, `Dialog`, `Tabs`, `Segmented`), built on the tokens of `foldkit-mixins/theme`.
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
@@ -495,6 +557,11 @@ const AddressStyle = Style.forSlots(FieldSlots)({
495
557
  `control` is in `variants`, so it wins over a `components` look on the same
496
558
  slot; over a look of your own in a later layer, say the same in that layer.
497
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]`.
564
+
498
565
  `Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
499
566
  buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
500
567
  The pressed option takes the accent's tint, flat: that rule lives on the
@@ -558,20 +625,34 @@ its pattern, so an adapter cannot drift from the contract it claims. The
558
625
  patterns are written separately from the Slots, which is what makes the
559
626
  check mean something.
560
627
 
561
- ## Why some components cannot be adapted
562
-
563
- The bridge needs a **consumer-visible attribute bundle**. If a component builds
564
- its entire element tree internally and exposes no `toView`-style seam, there is
565
- nothing for Mixins to attach to.
566
-
567
- Currently `Menu`, `Listbox`, `ComboBox`, and `DatePicker` fall into that category.
568
- They cannot be adapted here without a change to their upstream component API.
569
- That is a limitation of the exposed render seam, not of Slot resolution.
570
-
571
- Other `@foldkit/ui` modules—`Toast`, `FileDrop`, `VirtualList`, `DragAndDrop`,
572
- and `Animation`—simply do not have adapters here yet.
573
- `FileDrop` does expose a render seam, so it is an example that could be added
574
- without changing `@foldkit/ui`.
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.
575
656
 
576
657
  ## Status
577
658