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 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,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 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`.
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 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`.
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