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.

WidgetWhat it doesState
TableSortable, selectable, expandable data tableApplication
CardContent card with media, actions, and optional pressApplication
Card.groupResponsive card grid with optional Card.fluid hoverApplication
ItemFlexible list row primitive (Item.group)Application
AvatarUser image or initials with status, badges, and groupsStateless
BadgeStatus pill, optional link or dismiss buttonStateless
TypographySemantic text levels (h1–h4, body, code, display)Stateless
SeparatorHorizontal or vertical divider with optional labelStateless
EmptyEmpty-state placeholder with icon, title, and actionStateless
SkeletonLoading bars (lines, avatarRow, card, tableRow)Stateless
CarouselScroll-snap carousel with autoplay and dotsSmall Model / Bundle
MarqueeSeamless scrolling strip that pauses on hover/focusSmall Model / Bundle
  • Avatar. Renders role="img" named by the person (and status) with initials underneath until the image loads; accepts a URL src or Avatar.picture(...) (foldkit-media) for responsive 1x/2x images. Avatar.group stacks overlapping avatars and summarizes extras (+N).
  • Badge, Typography, Separator, Empty, Skeleton. Badge styles tones via data-tone (Recipes.badgeTones maps custom attributes) and takes either onDismiss or href. Typography renders the semantic element for each level and sets data-level. Separator adapts to horizontal or flex/grid vertical orientation automatically. Skeleton sets role="status" when given a label and aria-hidden="true" otherwise.
  • Marquee. Measures content with Resize and fills the viewport with inert clones without duplicate ids, pausing on hover, focus, or its pause button (and scrolling natively under reduced motion).

Images, icons and codes

WidgetWhat it doesState
ImageResponsive <picture> with layout and aspect ratioStateless
Figure<figure> with <figcaption> placed in DOM reading orderStateless
FrameGrouped tray of panels with header, action, and footerStateless
AspectRatioFixed aspect-ratio frame (square, video, portrait)Stateless
IconInline IconData SVG or custom glyph with optional badgeStateless
CodeBlockSyntax-tokenized code with line marks, copy, and collapseApplication
QrCodeVector SVG QR code with overlay support and PNG/SVG exportStateless
ChartBars, line, area, or donut chart with data table fallbackSmall Model
ImageCropperPan, zoom, rotate, and crop viewport with Export CommandSmall Model / Bundle
SignaturePadPointer signature canvas with undo/redo and SVG/PNG exportSmall Model / Bundle
  • CodeBlock. Renders syntax tokens ({ from, to, kind }) from foldkit-richtext-code, line numbers from startLine, whole-line marks (added, removed, error, etc.), optional collapsed toggle (working statically via data-collapsed even without onToggle), onLineSelect, lineAction, and copy with polite status announcements. Pass CodeBlock.follow in mixins to keep streaming output scrolled to the end.
  • QrCode, ImageCropper, SignaturePad. QrCode.encode and pathOf are pure, and QrCode.Download saves PNG or SVG. ImageCropper supports mouse/touch/wheel/keyboard resizing, optional ImageCropper.zoomSlider, and RequestedExport. SignaturePad supports pointer filtering (pointers: ['pen'] ignores palm touches), fallback typed name, form name submission as SVG, and RequestedPng.
ts
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).

ts
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.

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.