Mixins / foldkit-mixins-ui
Showing content
Stateless views render directly from the values you pass. Hide visual-only text with U.srOnly from foldkit-mixins/utilities.
| Widget | What it does | State |
|---|---|---|
Table | Sortable, selectable, expandable data table | Application |
Card | Content card with media, actions, and optional press | Application |
Card.group | Responsive card grid with optional Card.fluid hover | Application |
Item | Flexible list row primitive (Item.group) | Application |
Avatar | User image or initials with status, badges, and groups | Stateless |
Badge | Status pill, optional link or dismiss button | Stateless |
Typography | Semantic text levels (h1–h4, body, code, display) | Stateless |
Separator | Horizontal or vertical divider with optional label | Stateless |
Empty | Empty-state placeholder with icon, title, and action | Stateless |
Skeleton | Loading bars (lines, avatarRow, card, tableRow) | Stateless |
Carousel | Scroll-snap carousel with autoplay and dots | Small Model / Bundle |
Marquee | Seamless scrolling strip that pauses on hover/focus | Small Model / Bundle |
- Avatar. Renders
role="img"named by the person (and status) with initials underneath until the image loads; accepts a URLsrcorAvatar.picture(...)(foldkit-media) for responsive1x/2ximages.Avatar.groupstacks overlapping avatars and summarizes extras (+N). - Badge, Typography, Separator, Empty, Skeleton.
Badgestyles tones viadata-tone(Recipes.badgeTonesmaps custom attributes) and takes eitheronDismissorhref.Typographyrenders the semantic element for eachleveland setsdata-level.Separatoradapts to horizontal or flex/grid vertical orientation automatically.Skeletonsetsrole="status"when given alabelandaria-hidden="true"otherwise. - Marquee. Measures content with
Resizeand fills the viewport withinertclones without duplicateids, pausing on hover, focus, or its pause button (and scrolling natively under reduced motion).
Images, icons and codes
| Widget | What it does | State |
|---|---|---|
Image | Responsive <picture> with layout and aspect ratio | Stateless |
Figure | <figure> with <figcaption> placed in DOM reading order | Stateless |
Frame | Grouped tray of panels with header, action, and footer | Stateless |
AspectRatio | Fixed aspect-ratio frame (square, video, portrait) | Stateless |
Icon | Inline IconData SVG or custom glyph with optional badge | Stateless |
CodeBlock | Syntax-tokenized code with line marks, copy, and collapse | Application |
QrCode | Vector SVG QR code with overlay support and PNG/SVG export | Stateless |
Chart | Bars, line, area, or donut chart with data table fallback | Small Model |
ImageCropper | Pan, zoom, rotate, and crop viewport with Export Command | Small Model / Bundle |
SignaturePad | Pointer signature canvas with undo/redo and SVG/PNG export | Small Model / Bundle |
- CodeBlock. Renders syntax tokens (
{ from, to, kind }) fromfoldkit-richtext-code, line numbers fromstartLine, whole-linemarks(added,removed,error, etc.), optionalcollapsedtoggle (working statically viadata-collapsedeven withoutonToggle),onLineSelect,lineAction, andcopywith polite status announcements. PassCodeBlock.followinmixinsto keep streaming output scrolled to the end. - QrCode, ImageCropper, SignaturePad.
QrCode.encodeandpathOfare pure, andQrCode.Downloadsaves PNG or SVG.ImageCroppersupports mouse/touch/wheel/keyboard resizing, optionalImageCropper.zoomSlider, andRequestedExport.SignaturePadsupports pointer filtering (pointers: ['pen']ignores palm touches),fallbacktyped name, formnamesubmission as SVG, andRequestedPng.
import { parse } from 'foldkit-media/icons'
import { Style } from 'foldkit-mixins'
import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
const Frame = Recipes.AspectRatio.style({ ratio: 'video' })
const Mark = Recipes.Icon.style({ size: 'sm' })
// `h` is the view's builder. `content` is `Html`.
AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
// An icon as data: an import from `virtual:foldkit-icons/…`, or parsed by a script.
const check = parse('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>', 'check')
Icon.view({ icon: check, label: 'Done', style: Mark }, h)
Icon.view({ icon: check, style: Mark }, h)Icons.glyph is the other tool: a mask on an element that already exists.
Table
A column with rowHeader draws its cells as th scope="row", so a screen reader
names a row by it. 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. A column's
sortKey keeps the literal it is written as, so onSort receives 'name' | 'price'
and not a string: a Message field of Schema.Literals(['name', 'price']) needs no guard
in update. Columns written in the call infer it; columns hoisted into a constant go
through Table.defineColumns<Row>()([...]) (or as const), and a call that names its
type arguments (Table.view<Row, Message>) gets string. 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; its buttons' column is headed Details for a screen reader,
words.details renames it); 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. The
table 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: Table.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. A selection draws its boxes through control: Table.checkboxes(style?), which is where Checkbox is imported, and one of your own is an object with a draw. A column's footer draws a totals row after the body, its control columns left blank; a header that is markup holds an icon beside the words; the recipe's header: 'hidden' keeps the headings for a screen reader (a table read down its first column), borders: 'cells' boxes the cells and layout: 'fixed' gives each column an equal share.
A keyed row that a re-sort moves is taken out of the tree and put back, which
blurs the control focused inside it. FocusRecovery.behavior(TableSlots)({ owner: 'frame',
parts: { expandButton: ['same'], sortButton: ['same'], control: ['same'] } }), given
in mixins, finds the control again at its new place. A control you draw in a cell is
a part when you mark it: h.DataAttribute(FOCUS_MARK.part, 'control') and
h.DataAttribute(FOCUS_MARK.key, rowKey) (FOCUS_MARK is from foldkit-primitives/dom).
import { Option } from 'effect'
import { Table, TableSlots } from 'foldkit-mixins-ui'
interface Product {
readonly name: string
readonly price: string
}
const Sort = defineMessageUnion({ Sorted: { column: Schema.Literal('name') } })
type Sort = typeof Sort.Type
const ProductsStyle = Recipes.Table.style()
const productsTable = (
rows: ReadonlyArray<Product>,
sorted: Option.Option<Table.TableSort<'name'>>,
h: HtmlBuilder<Sort>,
) =>
Table.view(
{
columns: [
{ header: 'Product', sortKey: 'name', rowHeader: true, value: row => row.name },
{ header: 'Price', numeric: true, value: row => row.price },
],
rows,
rowKey: row => row.name,
sort: { by: sorted, onSort: column => Sort.Sorted({ column }) },
style: ProductsStyle,
},
h,
)
// in update, on Sorted: modifyFields(model, { sorted: () => Table.nextSort(model.sorted, column) })Card and Item
press is { onClick } or { href, external? }: one button or link stretched over
the card (overlay, from press.ts, shared with Item; its type is Press), 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="page" on the
link. headingLevel (2 to 6, default 3) is the level of the title's heading. A
disabled card's overlay is aria-disabled and sends nothing, so it stays focusable
(a link loses its href). dismiss: { onDismiss, always? } is revealed on
hover and focus unless always, and always on a touch screen; its name and mark are
words.dismiss and words.dismissMark. recoveryPart marks
the dismiss button as a FocusRecovery part (see Focus after
removal). The root carries data-selected, data-disabled,
data-pressable and data-dismissible (the header then keeps clear of the button).
In the recipe 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. elevation is a step of the surface ladder (lighter in a dark
scheme; a contact and an ambient shadow in a light one). lift: 'hover' lifts under
the pointer, which travel stills (not in a Card.group given fluid: Card.fluid, whose
highlight is the hover there). In a group, a card draws no hover of its own, whatever its
surface; divided cards are usually surface: 'plain'.
An Item's press is the same stretched control, named by label or the title, with
actions staying pressable above it; selected is aria-pressed or aria-current.
An avatar beside a name and a line is an Item with the avatar as its media. header and
footer are bands across the row above the overlay, for a heading or a note that holds
controls of its own. An Item page does not ship Card or FluidHover: both read
press.ts.
Carousel
Previous and next are aria-disabled at the ends unless loop; a dot per place the
track can rest (or thumbnails in their place) and a polite status name the slide
shown. Each slide is a group named "2 of 5". 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.
reducedMotion in init (the application's reading of prefers-reduced-motion,
from its flags or a MediaQuery; init stays pure so a server's Model equals the
client's) starts an autoplaying carousel stopped, with the rotation button to start
it. A slide out of view is inert, so its content takes no focus, which would scroll
the track.
Image
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, which 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.
Chart
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. 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. kind is a value you import, so a page ships the kinds it draws: Chart.bars (stack: true puts one series on another), Chart.line and Chart.area (curve: 'step' runs level to the next category before it rises; markers: 'always' puts a dot on every point; an area takes stack), and Chart.donut (hole: 0 is a pie, with no total in it). A kind of your own is a ChartKind: its entries, points and head say what the legend, the status line and the data table read, and its draw is given a ChartFrame (the lit point, the legend, the plot's attributes and a pointer(at) attribute) and returns the plot, so the title, the legend placement, the status and the table stay the chart's.