foldkit-mixins-ui 0.11.0 → 0.13.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 +16 -10
- package/dist/index.d.mts +388 -214
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +1246 -689
- package/dist/index.mjs.map +1 -1
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -31,7 +31,7 @@ Three kinds of thing live here:
|
|
|
31
31
|
- **Stateless views** draw a vocabulary from what the application passes and
|
|
32
32
|
keep nothing: Card, Badge, Item, Avatar, Command, Slider, PasswordInput.
|
|
33
33
|
- **Components with a small Model of their own**: Menu, Menubar, Toast,
|
|
34
|
-
Sheet, TagsInput, TreeView, Carousel, Resizable, ColorPicker, InputCopy,
|
|
34
|
+
Sheet, Drawer, TagsInput, TreeView, Carousel, Resizable, ColorPicker, InputCopy,
|
|
35
35
|
MessageScroller, Questionnaire, AngleSlider, Timer, Marquee, ImageCropper,
|
|
36
36
|
SignaturePad, Chart, CascadeSelect, FloatingPanel and Tour.
|
|
37
37
|
The Model holds interaction state only (what is open, a drag, a countdown,
|
|
@@ -405,7 +405,7 @@ adapter.
|
|
|
405
405
|
| Switch | `button`, `label`, `description`, `hiddenInput` |
|
|
406
406
|
| Fieldset | `fieldset`, `legend`, `description` |
|
|
407
407
|
| Disclosure | `button`, `panel` |
|
|
408
|
-
| Dialog | `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton`, and this package's `handle` (the Sheet's grabber, `aria-hidden`), `body`, `scroll`, `scrollBar`, `scrollThumb` and `footer`: draw `scroll` and its bar inside `body` and the answers in `footer`, and a body taller than the screen scrolls under the title while the footer stays (`Dialog.overlayBars` beside the style draws the overlay bar). An alert dialog is this one with `role: 'alertdialog'` in its context (`Dialog.toView(mixins, { h, role: 'alertdialog' }, draw)`), which puts `role="alertdialog"` on the `dialog` bundle; draw no close button, and drop the Messages `Dialog.isDismissal` names (Escape, the backdrop, the close button) in `update`, so only its own buttons, closing with `@foldkit/ui`'s `close`, answer it. `covered: true` in the context marks the panel `data-covered`, for a dialog another was opened from (draw the second inside the first's `dialog`, beside its panel), and the recipe steps it back; `attributes` adds to a bundle before the mixins resolve. Recipe `size`: `sm`, `md` (default), `lg`, `xl`, `full` |
|
|
408
|
+
| Dialog | `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton`, and this package's `handle` (the Sheet's grabber, `aria-hidden`), `body`, `scroll`, `scrollBar`, `scrollThumb` and `footer`: draw `scroll` and its bar inside `body` and the answers in `footer`, and a body taller than the screen scrolls under the title while the footer stays (`Dialog.overlayBars` beside the style draws the overlay bar). `Dialog.keyboard` among the mixins of a dialog or sheet that holds a field measures the on-screen keyboard on the panel, and the recipes keep the panel above it (a Dialog shrinks, a bottom Sheet stands on it): iOS Safari and Chrome on Android otherwise leave it under the keys. An alert dialog is this one with `role: 'alertdialog'` in its context (`Dialog.toView(mixins, { h, role: 'alertdialog' }, draw)`), which puts `role="alertdialog"` on the `dialog` bundle; draw no close button, and drop the Messages `Dialog.isDismissal` names (Escape, the backdrop, the close button) in `update`, so only its own buttons, closing with `@foldkit/ui`'s `close`, answer it. `covered: true` in the context marks the panel `data-covered`, for a dialog another was opened from (draw the second inside the first's `dialog`, beside its panel), and the recipe steps it back; `attributes` adds to a bundle before the mixins resolve. Recipe `size`: `sm`, `md` (default), `lg`, `xl`, `full` |
|
|
409
409
|
| Popover | `button`, `panel`, `backdrop`, `arrow`, and this package's `layer`, drawn around the panel to show it in the top layer (see [The top layer](#the-top-layer)); `Popover.anchor(config?)` is the placement. Recipe `arrow`: `shown` (default), `none` |
|
|
410
410
|
| Tooltip | `trigger`, `panel`, `arrow`, and this package's `layer`. `Tooltip.toView(mixins, { h, id }, draw)` takes the Tooltip's id (`model.id`), whose trigger the arrow points at; `Tooltip.anchor(config?)` is the placement, above by default. Recipe `arrow`: `shown` (default), `none` |
|
|
411
411
|
| HoverIntent | `trigger`, `panel`, `arrow` (open and close delays with intent, for a hover card or a menu). `anchored: { id, anchor? }` in the context anchors the panel to the trigger in the top layer (`HoverIntent.anchor()` unless given), the trigger taking `HoverIntent.triggerId(id)` |
|
|
@@ -424,7 +424,7 @@ adapter.
|
|
|
424
424
|
|
|
425
425
|
These views take no `@foldkit/ui` bundle. Call `X.view(options, h)`. Most own no
|
|
426
426
|
Model and no Message; the components among them that keep a small Model
|
|
427
|
-
(Menu, Menubar, Toast, Sheet, TagsInput, TreeView, Carousel, Resizable,
|
|
427
|
+
(Menu, Menubar, Toast, Sheet, Drawer, TagsInput, TreeView, Carousel, Resizable,
|
|
428
428
|
ColorPicker, InputCopy, MessageScroller, Questionnaire, AngleSlider, Timer,
|
|
429
429
|
Marquee, ImageCropper, SignaturePad, Chart, CascadeSelect, FloatingPanel,
|
|
430
430
|
Tour) say so, with its `init` and `update`.
|
|
@@ -474,13 +474,13 @@ A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
|
474
474
|
| `FloatingPanel` | After Zag's: a non-modal window. `FloatingPanel.init({ id, rect, open? })` holds its rect, stage and a drag, folded with `FloatingPanel.update(limits)` (`min`, `max`, `grid`, `overflow`); `FloatingPanel.open(model, { opener })` focuses it and `close` gives focus back. `FloatingPanel.view({ model, onMessage, title, content, order?, draggable?, resizable?, closeOnEscape?, step?, direction?, labels?, style? }, h)`: the drag trigger moves it and eight edges resize it, kept within the viewport; the arrows move it from the drag trigger and resize it from the bottom-end corner; minimize, maximize, restore and close. A press or focus inside returns the `Raised` OutMessage, which the application folds into the `order` its panels stack by with `FloatingPanel.raise(order, id)`. | `header`. Slots `root`, `boundary`, `panel`, `header`, `dragTrigger`, `title`, `controls`, `minimize`, `maximize`, `restore`, `close`, `body`, `handle`. |
|
|
475
475
|
| `HoverCard` (recipe) | Styles `@foldkit/ui`'s HoverIntent (`HoverIntentSlots`): a trigger read as a link, a raised panel fading in on the fast tier as it is drawn. Place the panel with `HoverIntent.toView`'s `anchored`, which shows it in the top layer with an `arrow`; the open and close delays are HoverIntent's (200ms and 300ms by default). | No axis. Slots `trigger`, `panel`, `arrow`. |
|
|
476
476
|
| `Icon` | `{ content, label? }`. A `label` is `role="img"`; without one the glyph is `aria-hidden`. | `size`: `sm`, `md`, `lg` on the type scale; none (the default) stands on the size ladder, 16px or 14px compact. Slot `glyph`. |
|
|
477
|
-
| `ImageCropper` | After Zag's: the image fitted in a viewport, a selection that a drag moves (`Move`) and eight handles resize, zoom by a Slider, the wheel and `+`/`-` with the selection kept where it is on screen, a pan of the zoomed image, quarter turns, an aspect lock and a round crop. `ImageCropper.init({ id, aspect?, shape?, crop?, min?, maxZoom? })` holds the crop, in the turned image's pixels, folded with `ImageCropper.update`; keys (arrows, Shift ×10, Alt to resize) step by screen pixels. Drawn with `ImageCropper.view({ model, onMessage, label, src, crossOrigin?, controls?, labels?, disabled?, style?, slider? }, h)`. `ImageCropper.crop(model)` is the crop in whole pixels (an `Option`); `RequestedExport({ type, quality })` returns the `Export` Command, answered by `Exported({ url, width, height })` or `FailedExport`. | `guides`, `handles` (`all`, `corners`), `viewport` (`landscape`, `wide`, `square`). Its zoom takes `Recipes.Slider({ label: 'hidden' })`. Slots `root`, `label`, `viewport`, `stage`, `pan`, `image`, `selection`, `guides`, `handle`, `controls`, `zoom`, `rotate`, `reset`. |
|
|
477
|
+
| `ImageCropper` | After Zag's: the image fitted in a viewport, a selection that a drag moves (`Move`) and eight handles resize, zoom by a Slider, the wheel, two fingers spread or pinched, and `+`/`-` with the selection kept where it is on screen, a pan of the zoomed image, quarter turns, an aspect lock and a round crop. `ImageCropper.init({ id, aspect?, shape?, crop?, min?, maxZoom? })` holds the crop, in the turned image's pixels, folded with `ImageCropper.update`; keys (arrows, Shift ×10, Alt to resize) step by screen pixels. Drawn with `ImageCropper.view({ model, onMessage, label, src, crossOrigin?, controls?, labels?, disabled?, style?, slider? }, h)`. `ImageCropper.crop(model)` is the crop in whole pixels (an `Option`); `RequestedExport({ type, quality })` returns the `Export` Command, answered by `Exported({ url, width, height })` or `FailedExport`. | `guides`, `handles` (`all`, `corners`), `viewport` (`landscape`, `wide`, `square`). Its zoom takes `Recipes.Slider({ label: 'hidden' })`. Slots `root`, `label`, `viewport`, `stage`, `pan`, `image`, `selection`, `guides`, `handle`, `controls`, `zoom`, `rotate`, `reset`. |
|
|
478
478
|
| `InputCopy` | A read-only value with a copy button, Zag's clipboard: `InputCopy.view({ id, label, value, copied, onCopy, copyLabel?, copiedLabel?, style? }, h)`. The view is stateless: answer `onCopy` with the `InputCopy.Copy({ text })` Command, which yields `foldkit-primitives/dom`'s `ClipboardMessage` (`Copied` or `CopyFailed`, never a throw); `copied` is the application's, and `InputCopy.Model` keeps it: `InputCopy.init({ resetAfter? })` (default 2000ms), folded with `InputCopy.update`, where `Copied` on `ClipboardMessage.Copied` shows it copied and starts the `Reset` Command that sets it back unless a later copy came first; pass `model.copied`. The button is named `Copy <label>`; copied, it reads `Copied` and a polite status region says so. | No axis. Slots `root`, `label`, `group`, `input`, `button`, `status`. |
|
|
479
479
|
| `Item` | The row primitive: `{ content?, media?, title?, description?, actions?, press?, label?, selected?, disabled? }`; `content` follows the title and description. `press` is `{ onClick }` or `{ href }`, one control stretched over the row (`overlay`, as a Card's) and named by `label` or the title, `actions` staying pressable above it; `selected` is `aria-pressed` or `aria-current`. `Item.group({ items: (ItemView & { key })[], label?, style?, itemStyle? })` is a list of them. Field is for form controls. | `variant`: `plain` (default), `outline`, `muted`; `density`: `comfortable` (default), `compact`; `media`: `plain` (default), `icon`, `image`. Slots `root`, `media`, `content`, `title`, `description`, `actions`, `overlay`. `Recipes.ItemGroup({ layout: 'divided' \| 'separated' })` over `ItemGroupSlots` (`root`, `row`). |
|
|
480
480
|
| `Kbd` | `{ key }`. Names the key. `Kbd.combo({ keys, joiner? }, h)` draws several in one `kbd`, with an optional joiner between them. | No axis. Slots `key`, `combo`, `joiner`. |
|
|
481
481
|
| `Label` | `{ for, text }`. `for` is the control's id. | No axis. Slot `label`. |
|
|
482
482
|
| `Marquee` | After Zag's: content that scrolls on without a seam. `Marquee.init({ id })` holds what it measured and whether it is paused, folded with `Marquee.update`; `Marquee.view({ model, onMessage, label, items, side?, speed?, autoFill?, repeat?, delay?, loopCount?, style? }, h)` measures its content (`Resize`) and draws copies to fill the viewport, `inert` after the first. A pointer, focus or its pause press (WCAG 2.2.2) holds it; `Marquee.Message.Paused()` holds it from outside. Its motion is CSS, and under reduced motion the viewport scrolls instead. | `spacing`, `edges` (`fade`, `none`). Slots `root`, `viewport`, `content`, `item`, `pause`. |
|
|
483
|
-
| `Menu` | One menu, opened three ways: `Menu.init(id, rows, { isAnimated?, isModal? })` (a row with `items` hosts a submenu, one level deep; `isAnimated` gives the menu's and its submenus' panels upstream's transition marks, for the recipe's fade, and `isModal` makes the rest of the page inert while the menu is open), folded with `Menu.update`, drawn with `Menu.view({ model, rows, buttonContent, onMessage, opensAt?, direction?, isRowDisabled?, mixins, submenuMixins? }, h)`, the style being one of the `mixins` (`[MenuStyle.mixin]`). By a button (`opensAt` unset); at a point (`opensAt: 'point'`, with `Menu.target(onMessage, h)` on the area: a right press records its point and the `contextmenu` after it opens the menu there). A row is an `ItemRow` (`{ label }`), a `CheckRow` (`check: 'checkbox' \| 'radio'`, `checked`: `menuitemcheckbox` or `menuitemradio` with `aria-checked`; choosing it sends `Selected` and leaves the menu open, the application keeping `checked`, a radio row's group being the rows of its `group`), or a `SubmenuRow` (`items`). Any row may name a `group` (rows next to each other with one group stand under its heading, a separator between groups), a `shortcut` (keys drawn at the row's end as Kbd with the view's `kbd`, named in `aria-keyshortcuts`; the menu binds nothing) and `tone: 'destructive'` (`data-tone`). A submenu's row is a `menuitem` with `aria-haspopup="menu"` and `aria-expanded`; ArrowRight, Enter or Space opens it on its first row, ArrowLeft or Escape closes it back to the row (under `direction: 'rtl'`, drawn as the root's `dir`, the submenu opens on the left, its chevron points there, and the arrows swap), a pointer resting 150ms opens it, and choosing a leaf closes everything. `Selected` names the value and the submenu it came from. Pass `Menu.fluid` beside the style (in `submenuMixins`, not `mixins`, where rows open submenus). Its panels, submenus included, draw in the top layer. A `@foldkit/ui` Menu the application folds itself, for typed items or groups, is drawn through the panel adapter instead, and opens at a point with `Menu.drawAtPoint` and `Menu.pointTarget` (see [Why some components needed a fork](#why-some-components-needed-a-fork)). | No axis. Slots `MenuSlots`. |
|
|
483
|
+
| `Menu` | One menu, opened three ways: `Menu.init(id, rows, { isAnimated?, isModal? })` (a row with `items` hosts a submenu, one level deep; `isAnimated` gives the menu's and its submenus' panels upstream's transition marks, for the recipe's fade, and `isModal` makes the rest of the page inert while the menu is open), folded with `Menu.update`, drawn with `Menu.view({ model, rows, buttonContent, onMessage, opensAt?, direction?, isRowDisabled?, mixins, submenuMixins? }, h)`, the style being one of the `mixins` (`[MenuStyle.mixin]`). By a button (`opensAt` unset); at a point (`opensAt: 'point'`, with `Menu.target(onMessage, h)` on the area: a right press records its point and the `contextmenu` after it opens the menu there; a finger or a pen held there `Menu.HOLD_MS`, 500ms, opens it too, as iOS fires no `contextmenu`, while one that moves 10px is a scroll; give the area `-webkit-touch-callout: none` and `user-select: none`, or iOS shows its own callout over it). A row is an `ItemRow` (`{ label }`), a `CheckRow` (`check: 'checkbox' \| 'radio'`, `checked`: `menuitemcheckbox` or `menuitemradio` with `aria-checked`; choosing it sends `Selected` and leaves the menu open, the application keeping `checked`, a radio row's group being the rows of its `group`), or a `SubmenuRow` (`items`). Any row may name a `group` (rows next to each other with one group stand under its heading, a separator between groups), a `shortcut` (keys drawn at the row's end as Kbd with the view's `kbd`, named in `aria-keyshortcuts`; the menu binds nothing) and `tone: 'destructive'` (`data-tone`). A submenu's row is a `menuitem` with `aria-haspopup="menu"` and `aria-expanded`; ArrowRight, Enter or Space opens it on its first row, ArrowLeft or Escape closes it back to the row (under `direction: 'rtl'`, drawn as the root's `dir`, the submenu opens on the left, its chevron points there, and the arrows swap), a pointer resting 150ms opens it, and choosing a leaf closes everything. `Selected` names the value and the submenu it came from. Pass `Menu.fluid` beside the style (in `submenuMixins`, not `mixins`, where rows open submenus). Its panels, submenus included, draw in the top layer. A `@foldkit/ui` Menu the application folds itself, for typed items or groups, is drawn through the panel adapter instead, and opens at a point with `Menu.drawAtPoint` and `Menu.pointTarget` (see [Why some components needed a fork](#why-some-components-needed-a-fork)). | No axis. Slots `MenuSlots`. |
|
|
484
484
|
| `Menubar` | A row of `@foldkit/ui` Menus, shadcn's and the APG's menubar: `Menubar.view({ label, model, menus, onMessage, direction?, style?, menuMixins }, h)`, each menu's `{ label, rows, isRowDisabled? }` taking a Menu's rows (none opening a submenu), its Model (`Menubar.init(ids, { isAnimated?, isModal? })`) folded with `Menubar.update`, whose `Selected` OutMessage names the menu and the row. One trigger is the tab stop; ArrowLeft/ArrowRight (Home/End while all are shut) move it, swapped under `direction: 'rtl'` (drawn as the bar's `dir`), and with a menu open they open the next on its first row. While one is open, pointing at another opens it, and opening any shuts the rest. `Recipes.MenubarMenu` is the Menu recipe with a bar's flat triggers. | No axis. Slots `bar`, `menu`; each menu's are `MenuSlots`. |
|
|
485
485
|
| `MessageScroller` | A conversation's log that follows the newest message while the reader is at the end and stops when they scroll up. `MessageScroller.init({ id })` holds only whether it follows and how many arrived unseen; the scroll position is the browser's, read by its `FollowEnd` Mount. Fold `MessageScroller.update`, and send `Message.Appended({ count })` when your update appends messages (not when it loads older ones, which it holds in place). `MessageScroller.view({ model, label, content, onMessage, jumpLabel?, unseenLabel?, style?, areaStyle?, areaMixins? }, h)` draws a named `role="log"` in a ScrollArea, with a jump button counting what arrived while away; give its parent a height. | No axis. Slots `root`, `log`, `jump`, `count`. |
|
|
486
486
|
| `Meter` | `@foldkit/ui`'s Meter: `Meter.view({ id, label, value, min?, max?, low?, high?, optimum?, valueText?, style? }, h)` draws a `meter` named by its label. The root says how good the value is as `data-level` (`good`, `fair`, `poor`), as the HTML meter judges it; `Meter.levelOf` is that judgment. A measurement, where `Progress` is work. | No axis; the fill takes success, warning or error by level. Slots `root`, `label`, `track`, `fill`. |
|
|
@@ -496,6 +496,7 @@ A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
|
496
496
|
| `Resizable` | `Resizable.Model` (`init(share)`), its `Message` and `update(model, message, bounds)`, which the application keeps and folds; `Resizable.view({ model, onMessage, label, first, second, orientation?, direction?, min?, max?, step? })`. shadcn's Resizable and the APG's window splitter: the handle is a `separator` with its value, stepped by the arrows and sent to the bounds by Home and End; a drag follows the `Move` Mount from where it began over the group the `Resize` Mount measured. Under `direction: 'rtl'`, drawn as the root's `dir`, the first panel is on the right, so ArrowLeft and a drag to the left grow it. `collapsible: 'first' | 'second'` (with `collapsedTo`) collapses that panel on Enter or a double-click and puts it back where it was, easing there while a drag follows the pointer at once; pass the same bounds to `update` and the view. A split fills its panel, so splits nest either way. | `handle`: `line` (default; a thicker accent line under the pointer) or `grip` (a pill of dots); `data-orientation` lays it out. Slots `root`, `first`, `handle`, `second`. |
|
|
497
497
|
| `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin, on `viewport` or `root`; a width goes on `root`, which the viewport fills and the bars lie over. The viewport is tabbable. A bar per axis is drawn beside the viewport, and `ScrollArea.overlayBars` beside the style lays them over its edge, driven by `ScrollBars` from `foldkit-primitives/dom`: a thumb that rests 4px wide, widens to 6px under the pointer, and fades once scrolling and the pointer rest; a coarse pointer keeps the browser's bar. See [Overlay scroll bars](#overlay-scroll-bars). | `orientation`: `vertical` (default), `horizontal`, `both`; `vertical` and `horizontal` fade the content toward an edge with more past it and draw a hairline there. Slots `root`, `viewport`, `bar`, `thumb`. |
|
|
498
498
|
| `Separator` | `{ orientation?, label?, decorative? }`, horizontal by default. A `label` sits between two drawn rules and is read as text; `decorative` is `role="none"`. A vertical rule needs its container to set the cross size. | `orientation`: `horizontal` (default), `vertical`; `line`: `solid`, `dashed`, `dotted`; `thickness`: `thin`, `thick`; `spacing`: `none`, `sm`, `md`, `lg`; `inset`: `none`, `sm`, `md`. The line is a border in `outline.default`, which a dark page shows. Slots `rule`, `root`, `label`. |
|
|
499
|
+
| `Drawer` | A panel docked to the bottom of the screen that peeks or opens beside the page, not over it: no focus trap, backdrop or scroll lock, so the page under it stays live (a modal one is the `Sheet`). `Drawer.init({ id, open? })` (down by default), folded with `Drawer.update`, opened with `Drawer.open` and `Drawer.close`, drawn with `Drawer.view({ model, onMessage, labels: { open, closed }, style?, mixins?, draw }, h)`, `draw` laying out `panel`, `handle` and `body` (the body may sit below what else peeks with the handle). A drag of the handle follows the finger and lets go open or down by its speed, then by whether it came a quarter of the panel; a click or Enter toggles it, and the click a browser sends after a drag does not. The panel's inline style is the drag's: set `--fk-drawer-peek` (default 5rem) and `--fk-drawer-height` (default 70dvh) on an ancestor or in a style. | `Recipes.Drawer`: `dock`: `always` (default), `below-lg` or `below-xl`, above which the panel is the column it sits in, with no handle. The handle's bar bends into a chevron going down, with the finger while dragged. Slots `panel`, `handle`, `body`. |
|
|
499
500
|
| `Sheet` | A Dialog its handle drags, vaul's Drawer: `Sheet.init({ id, side?, points?, opensAt?, dismissible?, isAnimated? })`, folded with `Sheet.update` and opened with `Sheet.open` and `Sheet.close` (each also reporting the Dialog's `Opened` or `Closed`), drawn with `Sheet.view({ model, onMessage, mixins, hasDescription?, covered?, scalesPage?, draw }, h)`, `draw` laying out `DialogSlots`' bundles with `h.div(sheet.handle)` in the panel. The panel stands on `side`'s edge (`data-side`); a drag of the handle follows the pointer and settles at the nearest of `points` (the share of the panel shown, ascending), or, flicked or dragged far enough past the first, closes it, unless `dismissible: false`. The Dialog keeps focus, Escape and scroll lock. `scalesPage` with `Recipes.sheetPage` on the page beside the sheet, never around it, steps the page back while it is open. | `Recipes.Sheet`: `size`: `sm`, `md` (default), `lg`, `full`; `handle`: `bar` (default) or `none`. Slots are `DialogSlots`. |
|
|
500
501
|
| `Sidebar` | shadcn's sidebar with Fluid's collapse, keeping a Model: `Sidebar.init({ id, rows, open?, collapsed?, side? })` (a Tooltip per row id, and the phone's Sheet), folded with `Sidebar.update`, drawn with `Sidebar.view({ model, onMessage, label, groups, header?, footer?, direction?, collapse?, style?, mixins?, tooltip?, sheet? }, h)`. `groups` are `{ id, title?, collapsible?, rows }`, a row a `SidebarLink` (`{ id, label, href, current?, icon?, badge? }`) or a `SidebarBranch` of nested links (`items`). Groups and branches open like an accordion's, several at once; the current page is `aria-current` and `Sidebar.fluid` glides a marker to it. `collapse: 'offcanvas'` (default) takes the whole column off the page; `'icons'` leaves a rail of icons named in Tooltips (`tooltip`, a Tooltip style). With `sheet` (a Sheet style), an opener shows it in a Sheet on a phone. Shut groups and a collapsed column stay drawn and `inert`. A resizable width is a Resizable whose `first` is the sidebar with `width: 'fill'`. | `width: 'fill'`. Slots `root`, `header`, `footer`, `opener`, `title`, `toggle`, `nav`, `section`, `heading`, `trigger`, `chevron`, `links`, `item`, `branch`, `link`, `icon`, `label`, `badge`, `tip`, `indicator`, `highlight`. |
|
|
501
502
|
| `SignaturePad` | After Zag's: strokes drawn by one pointer over a dashed line and "Sign here", undo, clear, and a typed name instead. `SignaturePad.init({ id, pen? })` holds the strokes (points with pressure, in the pad's coordinates), folded with `SignaturePad.update`. Drawn with `SignaturePad.view({ model, onMessage, label, fallback?, labels?, disabled?, style? }, h)`. `pathOf(stroke, pen)` and `toSvg(model, { color?, font? })` are pure; `RequestedPng({ scale, background })` returns `ExportPng`, answered by `ExportedPng({ url, width, height })` or `FailedExport`. | `surface` (`plain`, `muted`, `dashed`), `size`. Slots `root`, `label`, `control`, `segments`, `stroke`, `guide`, `placeholder`, `typedName`, `controls`, `undo`, `clear`, `fallback`, `fallbackLabel`, `input`. |
|
|
@@ -503,7 +504,7 @@ A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
|
503
504
|
| `Slider` | `Slider.view({ id, label, value, onChange, min?, max?, step?, format?, marks?, showValue?, name?, disabled?, style? }, h)`, where `value` is a number or a `{ low, high }` range and `onChange` is handed the same kind. Native `input type="range"` thumbs, so drag, keys, right to left and the form value are the browser's. One number is one thumb across the track, named by the label; a press anywhere on the track moves it. A range is a `group` named by its label holding two thumbs named by `thumbLabels` (default `Minimum` and `Maximum`), each bounded by the other (the low one's `max` is the high value), so the browser stops a drag or a key at the other thumb; `Slider.moved(range, 'low' \| 'high', value, bounds)` snaps, bounds and orders a range, and returns the same range when nothing changed. `marks` are values dotted on the track (`data-filled` where the fill covers them) and `showValue` draws each value, both hidden from assistive technology, which hears `aria-valuetext`. `@foldkit/ui`'s Slider is not adapted: draw its Submodel with Slots of your own. `orientation: 'vertical'` stands it upright; `ticks` dots every step; a mark may be `{ value, label }` (`SliderMark`), its words under the track. | `tone`: `accent` (default) or `neutral`; `size`: `sm`, `md` (default), `lg`, the thumb's edge; `track`: `thick` (default; the fill reaches each thumb's far edge, Fluid's look), `thin` or `paint` (a track a holder paints, as the color picker's); `value`: `above` (default), `inside` (widens the thumb into a pill; best at `md` or `lg`) or `end` (at the end of the label's row); `label`: `shown` (default) or `hidden`. Slots `root`, `label`, `control`, `track`, `fill`, `mark`, `value`, `thumb`. |
|
|
504
505
|
| `Spinner` | `{ label?, showLabel? }`. `role="status"`; `showLabel` draws the label beside the wheel. A turn is about 720ms times `travel`. | `kind`: `ring` (default), `dots`, `bars`, `pulse`, `orbit`; `size`: `sm`, `md` (default), `lg`; `tone`: `accent` (default), `neutral`, `current`. Slots `wheel`, `part`, `root`, `text`. |
|
|
505
506
|
| `Steps` | `Steps.view({ label, steps: { title, description?, icon?, content? }[], current, onSelect?, style? }, h)`: a stepper, an ordered list named by `label`. The step at `current` is `aria-current="step"`, those before it `data-state="complete"` (a check replaces the number), those after `upcoming`. An `icon` stands in the marker for its number; `content` follows the step, beside the line in a vertical stepper. With `onSelect(index)`, completed steps are buttons for going back; steps ahead never are. The application owns `current`. `progress` (0 to 1) fills the connector after the current step when the recipe's connector is a progress bar. | `orientation`: `horizontal` (default) or `vertical`; `size`: `xs`, `sm`, `md`, `lg` (the Avatar's sizes; unset, 1.75rem); `marker`: `number` or `dot`; `connector`: `line` or `progress`. Slots `root`, `item`, `step`, `trigger`, `marker`, `text`, `title`, `description`, `content`, `connector`. |
|
|
506
|
-
| `Table` | The presentational table: `{ columns: { header, value, numeric?, sortKey? }[], rows, rowKey?, caption?, fluid?, sort?, selection?, expansion?, empty? }`. A column with a `sortKey` heads with a button that sends `sort.onSort(column)`, and the sorted column carries `aria-sort`; `Table.nextSort(sort, column)` cycles ascending, descending and none. `selection` puts a checkbox on every row and one in the heading, mixed while only some are chosen; `expansion` opens a row's detail in a row below it (`aria-expanded`, `aria-controls`); `empty` stands across the table while there are no rows (an `Empty.view`). The sort, the chosen and the open rows are the application's. With `fluid`, one highlight behind the body rows follows the pointer, skipping detail and empty rows. Filtering, column reorder and resize, and virtualized rows stay with `foldkit-data-grid`. | `rows`: `lined`, `striped`, `plain`; `density`: `compact`, `regular`, `comfortable` (none set follows the region); `header`: `static`, `sticky`. Slots `frame`, `highlight` (with `fluid`), `root`, `caption`, `head`, `headerRow`, `headerCell`, `sortButton`, `sortIcon`, `body`, `row`, `cell`, `controlCell`, `checkboxLabel`, `expandButton`, `expandIcon`, `detailRow`, `detailCell`, `emptyRow`, `emptyCell`. |
|
|
507
|
+
| `Table` | The presentational table: `{ columns: { header, value, numeric?, sortKey? }[], rows, rowKey?, caption?, fluid?, sort?, selection?, expansion?, empty? }`. A column with a `sortKey` heads with a button that sends `sort.onSort(column)`, and the sorted column carries `aria-sort`; `Table.nextSort(sort, column)` cycles ascending, descending and none. `selection` puts a checkbox on every row and one in the heading, mixed while only some are chosen; `expansion` opens a row's detail in a row below it (`aria-expanded`, `aria-controls`); `empty` stands across the table while there are no rows (an `Empty.view`). The sort, the chosen and the open rows are the application's. It stands in a `frame`, which scrolls sideways when the table is wider than the screen (under a `static` header; a `sticky` one sticks to the application's scroller, which scrolls it). With `fluid`, one highlight behind the body rows follows the pointer, skipping detail and empty rows. Filtering, column reorder and resize, and virtualized rows stay with `foldkit-data-grid`. | `rows`: `lined`, `striped`, `plain`; `density`: `compact`, `regular`, `comfortable` (none set follows the region); `header`: `static`, `sticky`. Slots `frame`, `highlight` (with `fluid`), `root`, `caption`, `head`, `headerRow`, `headerCell`, `sortButton`, `sortIcon`, `body`, `row`, `cell`, `controlCell`, `checkboxLabel`, `expandButton`, `expandIcon`, `detailRow`, `detailCell`, `emptyRow`, `emptyCell`. |
|
|
507
508
|
| `TagsInput` | Zag's tags input, a small Model of its own: `TagsInput.init({ id, tags?, delimiter?, max? })`, folded with `TagsInput.update` (which returns a focus Command), drawn with `TagsInput.view({ model, onMessage, label, placeholder?, disabled? }, h)`. The tags are a list of chips named by the label, each with a `Remove <tag>` button, then a text input. Enter or the delimiter (default `,`) adds the draft split at the delimiter and trimmed, refusing empty and repeated parts, and parts past `max`: a refusal (`TagsInput.Refusal`: `Repeat`, `Empty`, `Full`) is said in a polite `message` (worded by `refusalText`) and shakes the field once, the shake travel-aware; Backspace on an empty draft removes the last tag; a removal returns focus to the input. Keys reach `update`, which decides from its own draft. | No axis; `data-disabled` on `control`. Slots `root`, `label`, `control`, `list`, `tag`, `remove`, `input`, `message`. |
|
|
508
509
|
| `ThinkingIndicator` | An assistant at work: `ThinkingIndicator.view({ label?, detail?, active?, icon?, style? }, h)` draws dots, a pulse or the view's icon beside words a band of light sweeps, and a detail line, in a polite status. Keep it drawn with `active: false` before work starts, so what it says when it starts is announced. Every movement holds under reduced motion. | `mark` (`dots`, `pulse`, `none`), `label` (`shimmer`, `plain`, `hidden`), `tone` (`muted`, `accent`). Slots `root`, `mark`, `dot`, `icon`, `label`, `detail`. |
|
|
509
510
|
| `ThinkingSteps` | The trace of what an assistant did: `ThinkingSteps.view({ id, steps, open, onToggle, duration?, summary?, openSteps?, onToggleStep?, stateWords?, style? }, h)`. Each step is `{ id, title, state, duration?, detail?, icon?, steps? }`, `state` being `pending`, `running`, `done` or `failed`, said in words too. The button says the running step's title, or "Thought for 4s". Its openness is yours, an `Option<boolean>`: none opens it while a step runs and shuts it once all are done, and the press sends the state the reader asked for. `openSteps` and `onToggleStep` make each step's detail collapsible (`Accordion.toggled`). | `variant` (`plain`, `card`), `connector` (`line`, `none`). Slots `root`, `trigger`, `summary`, `chevron`, `panel`, `list`, `step`, `head`, `marker`, `title`, `state`, `duration`, `body`, `detail`. |
|
|
@@ -892,9 +893,12 @@ direction explicitly:
|
|
|
892
893
|
## Mechanisms
|
|
893
894
|
|
|
894
895
|
`Touch` and `Icons` are style mechanisms, not components: no slots, no views.
|
|
895
|
-
Compose them into your own slots.
|
|
896
|
-
where the pointer is coarse
|
|
897
|
-
|
|
896
|
+
Compose them into your own slots. The recipes' own controls already stand
|
|
897
|
+
44px tall where the pointer is coarse: `Defaults.reset` sets
|
|
898
|
+
`--fk-touch-floor` there, and a control's height on the size ladder is at
|
|
899
|
+
least that (a region that must stay dense sets it to `0px`). For your own
|
|
900
|
+
slots, `Touch.target` floors one control at 44px where the pointer is coarse;
|
|
901
|
+
`Touch.targets` floors every boxed control a region draws. `Icons.glyph(size)` draws the icon in `--icon` before the
|
|
898
902
|
element's words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from
|
|
899
903
|
an attribute's value, where `icons` maps each value to its resolved `url(…)`:
|
|
900
904
|
|
|
@@ -976,7 +980,9 @@ h)` as `toView`'s `draw` (its button becomes a mark of no size at `point`, an
|
|
|
976
980
|
sends `onPress` with its point, which the application keeps, and the
|
|
977
981
|
`contextmenu` after it (or Shift+F10, or the ContextMenu key) sends `onOpen`,
|
|
978
982
|
which the application answers with the Menu's own `Opened` Message, the
|
|
979
|
-
browser's menu kept shut.
|
|
983
|
+
browser's menu kept shut. A finger's press sends `onPress` too, so Android's
|
|
984
|
+
`contextmenu` for a held finger opens under it; iOS fires none, which the
|
|
985
|
+
component's `Menu.target` answers by opening on the hold itself. The component (`Menu.init/update/view`, in the table above) is
|
|
980
986
|
this package's own, drawn through the adapter, as the Slider is; its
|
|
981
987
|
`Menu.target` is `pointTarget` wired to its own Messages.
|
|
982
988
|
|