foldkit-mixins-ui 0.16.0 → 0.18.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 +34 -8
- package/dist/index.d.mts +279 -53
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +613 -170
- package/dist/index.mjs.map +1 -1
- package/package.json +7 -5
package/README.md
CHANGED
|
@@ -214,6 +214,14 @@ alike. The Message type comes from `h`, and a Submodel's value type (a
|
|
|
214
214
|
RadioGroup's or Tabs' `Value`) from where the `toView` goes, so neither needs
|
|
215
215
|
writing out.
|
|
216
216
|
|
|
217
|
+
Every view takes the view's `h` last, as Foldkit's own views do. At runtime it
|
|
218
|
+
is the same builder everywhere; its type is the point: it carries the Message
|
|
219
|
+
the part of the app being drawn can route (the root's, or a Submodel's own), so
|
|
220
|
+
a handler built for another part's Message is a compile error where it is
|
|
221
|
+
written. Pass it down as a parameter and never keep it, as Foldkit asks: a
|
|
222
|
+
builder kept and used in another frame builds handlers that frame cannot
|
|
223
|
+
deliver.
|
|
224
|
+
|
|
217
225
|
A button drawn as a button needs no `draw` at all. `Button.view` takes the
|
|
218
226
|
label, a style, and `@foldkit/ui`'s own config:
|
|
219
227
|
|
|
@@ -475,6 +483,7 @@ the slots with the matching recipe. Hide text with `U.srOnly` from
|
|
|
475
483
|
`Label.view` takes the id that derived.
|
|
476
484
|
|
|
477
485
|
```ts
|
|
486
|
+
import { parse } from 'foldkit-media/icons'
|
|
478
487
|
import { Style } from 'foldkit-mixins'
|
|
479
488
|
import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
|
|
480
489
|
|
|
@@ -483,11 +492,17 @@ const Mark = Style.forSlots(IconSlots)(Recipes.Icon({ size: 'sm' }))
|
|
|
483
492
|
|
|
484
493
|
// `h` is the view's builder. `content` is `Html`.
|
|
485
494
|
AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
|
|
486
|
-
|
|
487
|
-
|
|
495
|
+
|
|
496
|
+
// An icon as data: an import from `virtual:foldkit-icons/…`, or parsed by a script.
|
|
497
|
+
const check = parse('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>', 'check')
|
|
498
|
+
Icon.view({ icon: check, label: 'Done', style: Mark }, h)
|
|
499
|
+
Icon.view({ icon: check, style: Mark }, h)
|
|
488
500
|
```
|
|
489
501
|
|
|
490
502
|
A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
503
|
+
`Icon.view` draws the `IconData` as inline SVG with `foldkit-media`'s
|
|
504
|
+
`Icon.draw` (ids of its own; `key` parts two copies of one icon) and fills its
|
|
505
|
+
glyph with it, so the recipe's size is the drawing's.
|
|
491
506
|
`Icons.glyph` is the other tool: a mask on an element that already exists.
|
|
492
507
|
|
|
493
508
|
| View | Call | Recipe |
|
|
@@ -496,25 +511,27 @@ A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
|
496
511
|
| `Alert` | `{ layout, title, description?, icon?, actions?, onDismiss?, dismissLabel? }`, and by `layout`: `'inline'` takes `assertive?` and is a live region inside the content, of something that just happened (`role="alert"` when assertive, `role="status"` otherwise); `'banner'` takes `label` and is a full-width strip across a page or a section, there on load, so a `section` landmark named by `label` rather than a live region, which would say nothing on load. Each action is `{ label, href }` (a link) or `{ label, onClick }` (a button); `onDismiss` draws a close button named `Dismiss <title>` inline, `Dismiss <label>` as a banner. The icon is `aria-hidden`. Whether it shows is the application's. The root writes `data-layout` and `data-dismissible`. | `tone`: `info` (default), `success`, `warning`, `error`; `emphasis`: `subtle` (default, the family's tint) or `bold` (its fill). Slots `root`, `icon`, `title`, `description`, `actions`, `action`, `dismiss`. |
|
|
497
512
|
| `AngleSlider` | After Zag's: a dial in degrees, 0 at the top and clockwise. `AngleSlider.init({ id, value? })` is the angle and the drag, folded with `AngleSlider.update(layout)`, where `layout` (`step`, `largeStep`, `marks`, `restrictToMarks`) is the object the view spreads in too: `AngleSlider.view({ ...layout, model, onMessage, label, name?, format?, valueText?, showValue?, disabled?, readOnly?, invalid?, style? }, h)`. A press or drag on the dial sends `Pointed` and `Released`; the APG's slider keys reach `update` as what was pressed, and go round past 0. A `name` draws a hidden input for a form. | `tone`, `track` (`ring`, `plain`, `disc`), `value` (`inside`, `below`), `size`. Slots `root`, `label`, `control`, `needle`, `thumb`, `markers`, `marker`, `markerLabel`, `value`, `input`. |
|
|
498
513
|
| `AspectRatio` | `{ content? }`. Slot `frame`. | `ratio`: `square` (default), `video` (16/9), `portrait` (3/4). The corner reads `radius`. |
|
|
499
|
-
| `Avatar` | `{ name, src?, initials?, status?, statusLabel? }`. The root is one `role="img"` named by the person (and the status, "Ada Lovelace, Online"); initials show until the picture covers them, the picture's alt empty. `status` (`online`, `away`, `busy`, `offline`) is a dot on the lower end corner. `Avatar.group({ people, max?, label?, moreLabel?, style?, avatarStyle? })` overlaps them, each ringed in the page, and counts the rest as one more avatar. An avatar beside a name and a line is an `Item` with the avatar as its media. | `size`: `xs`, `sm`, `md` (default), `lg`, `xl`; `shape`: `circle` (default), `rounded`, `square`; `color`: `neutral` (default) or `name` (initials in a hue from the name); `ring`: `none`, `page`, `accent`. Slots `root`, `fallback`, `image`, `status`. `Recipes.AvatarGroup({ overlap: 'tight' \| 'loose' \| 'none' })` over `AvatarGroupSlots` (`root`). |
|
|
514
|
+
| `Avatar` | `{ name, src?, initials?, status?, statusLabel? }`. The root is one `role="img"` named by the person (and the status, "Ada Lovelace, Online"); initials show until the picture covers them, the picture's alt empty. `status` (`online`, `away`, `busy`, `offline`) is a dot on the lower end corner. `src` may be an `AvatarPicture` (`{ asset, provider, width }` from `foldkit-media`): the picture is drawn with its 1x and 2x candidates at `width` CSS pixels, and a provider with no URL for it leaves the initials. `Avatar.widthOf(size)` is a size's width in CSS pixels, for that `width`. `Avatar.group({ people, max?, label?, moreLabel?, style?, avatarStyle? })` overlaps them, each ringed in the page, and counts the rest as one more avatar. An avatar beside a name and a line is an `Item` with the avatar as its media. | `size`: `xs`, `sm`, `md` (default), `lg`, `xl`; `shape`: `circle` (default), `rounded`, `square`; `color`: `neutral` (default) or `name` (initials in a hue from the name); `ring`: `none`, `page`, `accent`. Slots `root`, `fallback`, `image`, `status`. `Recipes.AvatarGroup({ overlap: 'tight' \| 'loose' \| 'none' })` over `AvatarGroupSlots` (`root`). |
|
|
515
|
+
| `Figure` | `{ content, caption? }`: a `figure` holding its content (an `Image.view`, a chart, a code block), then its caption in a `figcaption`, which names the figure for assistive technology by itself; no caption, no `figcaption`. | `align`: `start` (default) or `center`. The caption is the `caption` role, muted. Slots `root`, `caption`. |
|
|
516
|
+
| `Image` | `{ asset, provider, layout, alt, priority?, sizes? }` from `foldkit-media`: a `picture` with a `source` per format the provider offers and an `img` with its candidates, `sizes`, `width` and `height` (the box is held before the file arrives), lazy unless `priority` (then `fetchpriority="high"`). `alt` is what the image shows in words (a string, or `Image.described(text)`) or `Image.decorative` (`alt=""`, `role="presentation"`), never omitted. `Provider.hosted` takes only a `HashedAsset`, so facts without a content hash are a type error there. The `img` carries `--fk-image-ratio`, `--fk-image-placeholder` (none behind a transparent image) and `data-layout` (`fixed`, `constrained`, `full`); a provider with no URL for the image leaves an empty frame marked `data-unavailable`. An unavailable image keeps its box and is `role="img"` named by its alt text (hidden when decorative). `--fk-image-focus` places a crop at the asset's focal point. `placeholder: 'detail' | 'average'` chooses how much of a ThumbHash to paint; by default the picture for `priority`, the color otherwise. `Image.watchLoad`, beside the style, marks the `img`'s `data-state` (`loading`, `loaded`, `failed`); the recipe hides a failed image, keeping its box. `Image.audit`, beside the style in a development build, warns in the console of an image drawn wider than its file (blurry) or far narrower (wasted bytes), and of more than one image drawn with `priority`. `Image.preloadsIn` is a `foldkit-ssr` `Head`: the `<link rel="preload">` of each image the rendered page drew with `priority`. | `fit`: `cover` (default) or `contain`; `edge`: `none` (default) or `line` (the faint inset line); `ratio`: `auto` (default), `square`, `video` (16:9), `portrait` (3:4), cropped at the asset's focal point (an unavailable image holds the cropped box); `radius`: `none` (default), `sm`, `md`, `lg`, `full`. The placeholder paints the `img`'s background. Slots `frame`, `source`, `image`. |
|
|
500
517
|
| `Badge` | `{ text, tone? }` writes `data-tone`. | `Recipes.Badge({ attribute, tones, appearance? })` maps that attribute; values outside the map keep the base. `appearance`: `tinted` (default), `dot`, `outline`, `solid`. Slot `badge`. |
|
|
501
518
|
| `Breadcrumb` | `{ steps: { label, href?, current?, icon? }[], separator?, collapse? }`. `current` is text with `aria-current="page"`; the others are links. An `icon` draws before its label, hidden from assistive technology. `separator` is drawn between steps in place of the recipe's; `collapse: { max, onExpand, label? }` folds the middle of a long trail into an ellipsis (`Breadcrumb.collapsedOf(steps, max)` is the split). `collapse: { max, menu: { model, onMessage, mixins } }` makes the ellipsis open a Menu of the hidden steps instead: the Menu's Model is the application's, built from `Breadcrumb.menuRows(steps, max)`, and `Breadcrumb.chosen(steps, max, value)` is the step a row leads to. | `separator`: `slash` (default), `chevron` or `dot`, drawn where the view is given no `separator` of its own. Slots `root`, `list`, `item`, `link`, `current`, `icon`, `separator`, `ellipsis`, `dots`. |
|
|
502
519
|
| `ButtonGroup` | `{ label, items, orientation?, separated? }`. `role="group"`, joining its items: borders overlap by one and only the outer corners stay round. An item is the caller's button, field or Menu (a wrapper passes the corners to the face it holds), or a string, drawn in the `text` box (a count, a field's prefix). `orientation: 'vertical'` stacks them; `separated` draws a rule on every seam, for solid buttons whose fills meet. A hovered or focused item rises over its neighbour. `Segmented` is the control that selects. | `size`: `sm`, `md`, `lg`, for every item with no size of its own; `width: 'fill'` spans the container, a field taking what the buttons leave. Slots `root`, `separator`, `text`. |
|
|
503
520
|
| `Calendar` | One date system, inline: `Calendar.Selection` is `Single`, `Range` or `Multiple`, owned by the application (`Calendar.empty(mode)`, fold each `SelectedDate` through `Calendar.picked`, `Calendar.isComplete` says when a picker may close). Spread `Calendar.inputs(selection, mixins, { h })` into upstream `Calendar.view`'s inputs: its `toView` (`Calendar.toView(selection, mixins, { h })`) marks each chosen day `aria-selected`, a range's ends `data-selected` with `data-range-start`/`data-range-end` and every day between `data-in-range`, and its `maybeSelectedDate` (`Calendar.selectedDate(selection)`, a Single selection's day) agrees with it. The grid of a Range or Multiple selection is `aria-multiselectable`. A selection in a popover is the DatePicker's. Options, the fourth argument of `toView`, `inputs` and `resolve` (`CalendarOptions`): `weekNumbers`, `caption: 'label'` or `dropdowns: { model, onShow }` (month and year selects; answer `onShow` with `Calendar.show`), `paging` with `Calendar.alongside(model, other, offset)` for two months side by side, `preview: { date, onPreview }` for a range under the pointer, and `detail: date => Option<string>` for a line under a day's number (a price, "2 events") that describes its button; `ResolvedDayCell.detail` holds it. `ResolvedDays`' paging buttons are `Option`s and its heading is a `caption` (`Grid`, `Label`, `Dropdowns`). Presets: `Calendar.lastDays`, `nextDays`, `monthOf`, `day`, drawn by `Calendar.presetsView`. `Calendar.localeOf('de-DE')` reads upstream's `locale` from Intl. | `size` (the Calendar's); `outside`: `shown` (default), `hidden`; `detail`: `text` (a taller rounded day holding the line), `dot` (the line as a dot, its words left to a screen reader), unset by default. Slots `CalendarSlots`. |
|
|
504
|
-
| `Card` | `{ title?, description?, content?, image?, media?, action?, footer?, press?, label?, selected?, disabled?, dismiss? }`. `press` is `{ onClick }` or `{ href, external? }`: one button or link stretched over the card, named by `label` or the title (a pressable card with neither throws); `action`, `footer` and the dismiss button stay pressable above it. `selected` is `aria-pressed` on the button, `aria-current` on the link. `dismiss: { onDismiss, label?, always? }` is revealed on hover and focus unless `always`, and always on a touch screen. The root carries `data-selected`, `data-disabled`, `data-pressable`, `data-dismissible` (the header then keeps clear of the button). | `orientation`: `stacked` (default), `inline` (image or media leading, footer trailing). `surface`: `outlined` (default), `elevated`, `filled`, `plain`. `padding`: `compact`, `comfortable` (default), `roomy`, `flush`. `elevation`: `0` to `3`, a step of the surface ladder (lighter in a dark scheme; a contact and an ambient shadow in a light one). `lift`: `none` (default) or `hover`, a lift under the pointer that `travel` stills. `Card.overlay` is the stretched press control, shared with Item. Slots `root`, `image`, `media`, `header`, `title`, `description`, `action`, `content`, `footer`, `overlay`, `dismiss`. |
|
|
505
|
-
| `Card.group` | `{ cards: (CardView & { key })[], columns?, fluidHover?, label?, cardStyle? }`. A keyed list of cards in up to `columns` (default 1), which wraps to fewer where a column would be narrower than the recipe's `minColumn`; the root carries `--fk-card-columns` and `data-card-fluid`. With `fluidHover` (default) one highlight follows the pointer to the nearest card through `FluidHover` from `foldkit-primitives/dom`, reading both directions when there is more than one column, and a press in a gap presses the highlighted card. `cardStyle` styles every card that names no style of its own. | `Recipes.CardGroup`: `layout`: `divided` (default, hairlines between cards, wherever the row wraps), `separated` (apart,
|
|
521
|
+
| `Card` | `{ title?, description?, content?, image?, media?, action?, footer?, press?, label?, selected?, disabled?, dismiss? }`. `press` is `{ onClick }` or `{ href, external? }`: one button or link stretched over the card, named by `label` or the title (a pressable card with neither throws); `action`, `footer` and the dismiss button stay pressable above it. `selected` is `aria-pressed` on the button, `aria-current` on the link. `dismiss: { onDismiss, label?, always? }` is revealed on hover and focus unless `always`, and always on a touch screen. The root carries `data-selected`, `data-disabled`, `data-pressable`, `data-dismissible` (the header then keeps clear of the button). | `orientation`: `stacked` (default), `inline` (image or media leading, footer trailing). An `image` bleeds to the card's edges (16:9 when stacked); `media` puts a bare icon (`svg`, `img`) in a tile and lets anything else, an Avatar say, lead at its own size. `surface`: `outlined` (default), `elevated`, `filled`, `plain`. `padding`: `compact`, `comfortable` (default), `roomy`, `flush`. `elevation`: `0` to `3`, a step of the surface ladder (lighter in a dark scheme; a contact and an ambient shadow in a light one). `lift`: `none` (default) or `hover`, a lift under the pointer that `travel` stills (not in a `Card.group` with a highlight, which is the hover there). `Card.overlay` is the stretched press control, shared with Item. Slots `root`, `image`, `media`, `header`, `title`, `description`, `action`, `content`, `footer`, `overlay`, `dismiss`. |
|
|
522
|
+
| `Card.group` | `{ cards: (CardView & { key })[], columns?, fluidHover?, label?, cardStyle? }`. A keyed list of cards in up to `columns` (default 1), which wraps to fewer where a column would be narrower than the recipe's `minColumn`; the root carries `--fk-card-columns` and `data-card-fluid`. With `fluidHover` (default) one highlight follows the pointer to the nearest card through `FluidHover` from `foldkit-primitives/dom`, reading both directions when there is more than one column, and a press in a gap presses the highlighted card. `cardStyle` styles every card that names no style of its own. | `Recipes.CardGroup`: `layout`: `divided` (default, hairlines between cards, wherever the row wraps), `separated` (apart, for cards with a surface). `minColumn`: `none`, `sm`, `md` (default), `lg`, the narrowest a column may be (10, 14, 18rem); `none` keeps every column at any width. `border`: `none` (default), `outlined`. The highlight is a film over the card the pointer is on, and is that card's hover: a card in a group with one draws no hover of its own, whatever its `surface`. Divided cards are usually `surface: 'plain'`. Slots `root`, `list`, `item`, `highlight`. |
|
|
506
523
|
| `Carousel` | The APG carousel: `Carousel.init({ id, slide?, autoplay?, delay? })`, folded with `Carousel.update({ count, perView?, loop? })`, drawn with `Carousel.view({ label, model, slides, onMessage, loop?, perView?, picker?, thumbnails?, slideLabel?, previousLabel?, nextLabel?, pickerLabel?, rotationLabels?, style? }, h)`. A group with `aria-roledescription="carousel"`, each slide a group named "2 of 5"; previous and next (`aria-disabled` at the ends unless `loop`), a dot per place the track can rest (or `thumbnails` in their place), and a polite status naming the slide shown. The track is a CSS scroll-snap scroller, so swipes move it natively, and `ScrollSettle` reports where a swipe rests, so the dots follow the finger. Every press, swipe and timer reaches `update`, which returns the `Carousel.ShowSlide` Command that scrolls the track: do not keep the slide yourself. With `autoplay` it moves on every `delay` (4s), the current dot filling as it waits; it pauses under the pointer, stops when focus arrives by the keys, quiets its status while it rotates, and draws the APG's rotation button first. | `peek`: `none` (default) or `edge`. Slots `root`, `track`, `slide`, `controls`, `rotation`, `previous`, `next`, `picker`, `dot`, `thumbnail`, `status`. |
|
|
507
524
|
| `CascadeSelect` | After Zag's: one value chosen as a path of ids through nested options. `CascadeSelect.init({ id })` holds the chosen path and the one the keys are on while open, folded with `CascadeSelect.update(config)` (`config` is `{ nodes, parents?, closeOnSelect?, loop? }`, the same object the view takes): `CascadeSelect.view({ model, config, onMessage, label, placeholder?, levels?, layout?, expandOn?, clearable?, separator?, name?, disabled?, invalid?, direction?, style? }, h)`. The trigger is a combobox opening a top-layer APG tree, a column per level or one level at a time (`layout: 'drill'`; the columns also drill in on their own when they would not fit the window, measured as the popup opens); the arrows move within and between levels (swapped right to left), Home, End and a letter jump, Enter and Space choose, and only an option without children is chosen unless `parents` allows any. | `size`, `trigger` (`outline`, `filled`, `ghost`), `width` (`trigger`, `auto`). Slots `root`, `trigger`, `valueText`, `chevron`, `clear`, `input`, `layer`, `backdrop`, `panel`, `column`, `heading`, `back`, `item`, `itemText`, `branch`. |
|
|
508
525
|
| `Chart` | After shadcn's Chart: `Chart.view({ id, label, kind: 'bar' \| 'line' \| 'area', categories, series: [{ name, values, color? }], model, onMessage, description?, format?, legend?, table?, categoryLabel?, style? }, h)`, or `kind: 'donut'` with `slices: [{ name, value, color? }]` and `totalLabel?`. The value axis's ticks are round and reach both ends, zero included; the plot is drawn in percentages, so it fills its container's width with nothing measured and renders the same on a server. `Chart.Model` (`Chart.init()`, folded with `Chart.update`) holds the lit point: the pointer lights a category's band and its tooltip, and the plot is a tab stop whose arrows, Home and End step through the points while a polite status says each. The drawing is hidden from assistive technology, which reads a data table, visually hidden unless `table: 'shown'`. Series take `chart-1` to `chart-5` in order, or the `color` they name; a sixth series throws. | `height` (`sm`, `md`, `lg`), `grid` (`lines`, `zero`), `indicator` (`dot`, `line`). Slots `root`, `title`, `description`, `legend`, `legendItem`, `swatch`, `body`, `yAxis`, `xAxis`, `yTick`, `xTick`, `plot`, `canvas`, `paths`, `grid`, `cursor`, `bar`, `line`, `area`, `dot`, `slice`, `band`, `center`, `centerValue`, `centerLabel`, `tooltip` and its parts, `status`, `table` and its parts. |
|
|
509
526
|
| `ChatMessage` | One message of a chat: `ChatMessage.view({ from, content, author?, avatar?, time?, status?, onRetry?, actions?, pinActions?, streaming?, style? }, h)`, `from` being `user`, `assistant` or `system`. The user's sits at the end in a bubble, an answer as text at the start. `status` is `sending`, `sent` or `failed`, which draws a retry; `actions` are named buttons (`{ key, label, onClick, icon?, pressed?, disabled? }`) shown on hover and focus unless pinned. A streamed answer is the same message drawn again with more `content` and `streaming: true` (`aria-busy`); its body wraps with `text-wrap: wrap`, so no earlier word moves line. `ChatMessage.group({ items, continues?, style?, messageStyle? }, h)` draws a run, a sender's following messages continued. Markdown is the application's to render (`foldkit-richtext-markdown`'s `parse`, `foldkit-richtext-dom/view`'s `renderDocument`). | `layout` (`chat`, `thread`), `bubble` (`muted`, `accent`), `content` (`text`, `markdown`). `Recipes.ChatMessageGroup` for the group. Slots `root`, `avatar`, `main`, `header`, `author`, `time`, `bubble`, `body`, `footer`, `status`, `retry`, `actions`, `action`. |
|
|
510
527
|
| `CheckboxGroup` | `{ id, legend, options: { value, label, description?, disabled? }[], checked, onToggle, error?, selectAll? }`; `toggled(checked, value)` is one option's transition, `coverage(options, checked)` is `none` \| `some` \| `all` (a disabled option counts for neither), and `setEnabled(options, checked, on)` is every enabled option or none, a disabled one keeping the state `checked` gives it. `selectAll: { label, onSet }` draws a first row whose checkbox is checked, `mixed` or unchecked by `coverage` and controls every option; a press sends `onSet` with `setEnabled`'s values, on unless all already are. A `fieldset` named by its `legend`, each option the APG's checkbox (`role="checkbox"`) named by a `label` for it, so a press on the words toggles it. `error` is shown under the options and the group is `aria-invalid`, described by it. | `variant`: `plain` (default), `list` (checked rows fill, and merge where they stand together; a vertical list has no gap, or the block would split). `orientation`: `vertical` (default), `horizontal` (a wrapping row). The checkbox sits on the label's row, so a description does not pull it down. Slots `root`, `legend`, `options`, `option`, `checkbox`, `label`, `description`, `error`. |
|
|
511
528
|
| `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`. |
|
|
512
|
-
| `ColorPicker` | After ReUI's: a saturation and brightness area, hue and alpha Sliders, an eyedropper where the browser has one (`ColorPicker.Eyedrop`, `canEyedrop`), text in hex, rgb, hsl or oklch, and `presets` as a radio group of swatches. The color, its format and a draft being typed are `ColorPicker.Model` (`init({ id, color?, format? })`), folded with `ColorPicker.update`: keys and drags reach `update` as what was pressed, so fast keys each step from the last color. Drawn with `ColorPicker.view({ model, onMessage, label, presets?, alpha?, eyedropper?, labels?, disabled?, style?, slider? }, h)`; `ColorPicker.popover(options, h)`
|
|
529
|
+
| `ColorPicker` | After ReUI's: a saturation and brightness area, hue and alpha Sliders, an eyedropper where the browser has one (`ColorPicker.Eyedrop`, `canEyedrop`), text in hex, rgb, hsl or oklch, and `presets` as a radio group of swatches. The color, its format and a draft being typed are `ColorPicker.Model` (`init({ id, color?, format? })`), folded with `ColorPicker.update`: keys and drags reach `update` as what was pressed, so fast keys each step from the last color. Drawn with `ColorPicker.view({ model, onMessage, label, presets?, alpha?, eyedropper?, labels?, disabled?, style?, slider? }, h)`; `ColorPicker.popover({ ...options, popover, onPopover, anchor?, popoverMixins? }, h)` draws it behind a swatch in a Popover made with `contentFocus: true` (it throws for one without): the panel opens on the area's thumb, a press or a drag inside never closes it, whatever opened it, and focus leaving it closes one the keys or a finger opened (a mouse's stays open, as upstream's Popover does). `ColorPicker.color('#3b82f6')` reads a literal in code (it throws on a typo); `format`, `parse` (an `Option`) and `toOklch` are pure. | `size`. Its Sliders take `Recipes.Slider({ track: 'paint', label: 'hidden' })`. Slots `root`, `label`, `area`, `areaThumb`, `controls`, `eyedropper`, `channels`, `channel`, `swatch`, `fields`, `format`, `input`, `presets`, `preset`, `picker`, `trigger`, `value`. |
|
|
513
530
|
| `Command` | `{ id, label, placeholder?, groups: { heading?, items: { value, label, description?, keywords?, shortcut?, icon?, opensPage?, disabled? }[] }[], query, onQuery, active, onActive, onRun, empty?, loading?, page?, hints?, kbd? }`, a `shortcut` being a tuple of keys (`['⌘', 'K']`) drawn as Kbd with `kbd`. `page: { trail, onBack }` draws the pages stepped into as crumbs before the field, and Backspace in an empty field sends `onBack`; a row with `opensPage` has a chevron. `loading` says it and marks the list `aria-busy`, its rows still shown; `hints` are a footer of keys. `Command.hotkey(message)` is ⌘K or Ctrl+K anywhere, for an application to lift with `Subscription.persistentEntry` and open its Dialog on; `Command.filtered(groups, query)` is what a query leaves. shadcn's Command and Fluid's CommandMenu: the field points at the highlighted row through `aria-activedescendant`, ↑ and ↓ wrap through enabled rows, Enter runs the highlighted one; rows never re-sort, and a filtered-away highlight moves to the first enabled row. The list stands in a `frame` beside its bar, which `Command.overlayBars` drives (see [Overlay scroll bars](#overlay-scroll-bars)). A shortcut reads left to right on a right-to-left page. | `frame`: `card` (default) or `bare`, for inside a dialog. Slots `root`, `search`, `crumbs`, `crumb`, `input`, `list`, `group`, `heading`, `item`, `icon`, `text`, `label`, `description`, `shortcut`, `chevron`, `status`, `empty`, `loading`, `frame`, `bar`, `thumb`, `footer`, `hint`. |
|
|
514
531
|
| `Empty` | `{ title, description?, icon?, action? }`. The title takes the `subtitle` role; the icon is `aria-hidden`. | `media`: `icon` (default), `illustration`; `frame`: `none` (default), `dashed`, `filled`; `tone`: `neutral` (default), `danger`; `size`: `compact`, `comfortable` (default). Slots `root`, `icon`, `title`, `description`, `action`. |
|
|
515
532
|
| `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`. |
|
|
516
533
|
| `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`. |
|
|
517
|
-
| `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`. |
|
|
534
|
+
| `Icon` | `{ content, label? }`. A `label` is `role="img"`; without one the glyph is `aria-hidden`. `foldkit-media`'s `Icon.draw(icon, h)` is an `IconData`'s inline SVG for `content`, which the glyph fills. | `size`: `sm`, `md`, `lg` on the type scale; none (the default) stands on the size ladder, 16px or 14px compact. Slot `glyph`. |
|
|
518
535
|
| `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`. |
|
|
519
536
|
| `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`. |
|
|
520
537
|
| `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`). |
|
|
@@ -542,7 +559,7 @@ A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
|
|
|
542
559
|
| `Sidebar` | shadcn's sidebar with Fluid's collapse, keeping a Model: `Sidebar.init({ id, rows, open?, collapsed?, side?, width? })` (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?, action?, rows }`, a row a `SidebarLink` (`{ id, label, href, current?, icon?, badge?, action? }`) or a `SidebarBranch` of nested links (`items`). An `action` (`SidebarAction`: `{ label, icon, message }`) is a button at a titled group's heading or beside a link, where it takes the badge's place under the pointer (both show on a touch screen). 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`. `Sidebar.init({ width: { size?, min?, max? } })` makes the column resizable, its width in the Model: a `resize` handle on its edge drags it, the arrows step it, Enter or a double-click collapses it, and dragged below half `min` it collapses, coming back at the width the drag began at. | `variant`: `sidebar` (flush with the page's edge, the default), `floating` (a card lifted off it), `inset` (no edge, on the surface it stands on, for a page drawn as a card beside it); on a phone with a Sheet the column is its opener alone. Slots `root`, `header`, `footer`, `opener`, `title`, `toggle`, `nav`, `section`, `heading`, `trigger`, `chevron`, `links`, `item`, `branch`, `link`, `icon`, `mark`, `detail`, `label`, `badge`, `action`, `tip`, `indicator`, `highlight`, `resize`. |
|
|
543
560
|
| `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`. |
|
|
544
561
|
| `Skeleton` | `{ label? }`, `role="status"`, a bar a film of the text. `Skeleton.lines({ lines, label? })`, `avatarRow`, `card` and `tableRow({ columns })` draw the shapes content takes, in a `group`. | `shape`: `bar` (default), `circle`; `animation`: `pulse` (default), `shimmer`, `none`. Slots `bar`, `group`. |
|
|
545
|
-
| `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, those at either end flush with its ends rather than hanging past them. | `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`. |
|
|
562
|
+
| `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, those at either end flush with its ends rather than hanging past them. | `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`. A Slider is at least 12rem wide; a holder that lays it narrower sets `--fk-slider-min-length`, as the ColorPicker's channels do. Slots `root`, `label`, `control`, `track`, `fill`, `mark`, `value`, `thumb`. |
|
|
546
563
|
| `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`. |
|
|
547
564
|
| `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`. A horizontal row narrower than 32rem shows only the current step's words, wrapping inside an even share so the markers stay evenly spaced (a word longer than 40% of the row is cut), and narrower than 17rem draws them on a line of their own under the markers. Slots `root`, `item`, `step`, `trigger`, `marker`, `number` (the figure in a marker with no icon, trimmed to its digits so it centers in any face), `text`, `title`, `description`, `content`, `connector`. |
|
|
548
565
|
| `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`. |
|
|
@@ -955,6 +972,15 @@ const TileStyle = Style.forSlots(TileSlots)(
|
|
|
955
972
|
)
|
|
956
973
|
```
|
|
957
974
|
|
|
975
|
+
The icons the components draw themselves (a search field's magnifier, a
|
|
976
|
+
toast's mark, a locked cell's padlock) are the theme's `icon` tokens, Lucide's
|
|
977
|
+
by default. An application's own pack replaces them as its own tokens:
|
|
978
|
+
`AppStyle.make({ theme, tokens: Icons.tokens(pack, { width?, corners? }) })`,
|
|
979
|
+
where `pack` holds an `IconData` for each name the components draw
|
|
980
|
+
(`ChromeIcon` from `foldkit-mixins/theme`; one missing is a type error), and
|
|
981
|
+
the stroke is redrawn into each mask, which CSS cannot reach once it is a
|
|
982
|
+
`url()`.
|
|
983
|
+
|
|
958
984
|
## Accessibility patterns
|
|
959
985
|
|
|
960
986
|
Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
|