Mixins / foldkit-mixins-ui
Long lists and scrolling
| Widget | What it does | State |
|---|---|---|
ScrollArea | Scrollable container with fade edges and overlay bars | Stateless |
Resizable | Split panes with keyboard and pointer drag handle | Small Model / Bundle |
VirtualList | Boxed virtualized list rendering visible rows only | Adapter / Bundle |
WindowList | Document-scrolled virtual list keeping focus on held rows | Small Model / Bundle |
- ScrollArea. Put a height on
viewportorrootand optional width onroot; passScrollArea.overlayBars(imported separately) to overlay scrollbars (Overlay scroll bars). - VirtualList. Wraps
@foldkit/ui/virtualList(Bundles.VirtualListemitsNearEndfor pagination and supportsVirtualList.overlayBars); unmounts off-screen rows including focused ones—useWindowListwhen document scroll or held focus matters.
Resizable
The handle is a separator with its value, stepped by the arrows and sent to the
bounds by Home and End (a collapsible panel collapses when the key reaches its
side, as the APG asks, and a collapsed one leaves the key alone); with an id the
handle's aria-controls names the first panel; a drag follows the Move Mount from
where it began over the group the Resize Mount measured. Under direction: 'rtl'
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; the bounds init was given are read by both update and the view. A split fills its
panel, so splits nest either way.
WindowList
It draws the rows in view of the document's viewport between spacers as tall as the
rest, so the page keeps its own scrolling: the browser restores its offset, a sticky
header above the list sticks, and Space and End move it. Use VirtualList for a list
in a box of its own.
- Measuring. Its one Mount on
root,WindowList.Track, reads where the viewport lies over the list on every scroll, resize and resize of the page (WindowViewport), so content above it, or growing above it, counts, and measures each drawn row's border box (MeasureRows; space rows with padding: a row isflow-root). The rows already drawn when it starts are read at once, so no row leaves before its height is known. A row not yet measured countsestimatedHeight, or withunmeasured: 'mean'the mean of the rows measured above 0: for rows whose height the window's width decides, whichinitcannot know. A row still drawn is measured again only when it resizes, so keep the keys of the rows drawn:WindowList.windowOf(model, keys)is which rows are drawn, for loading what is in view, andWindowList.keep(model, keys)drops the heights of rows that left. A Scene test of a page drawing the list resolves it withScene.Mount.resolveAll(WindowList.resolveTrack(onMessage, WindowList.Message.Placed({ top, height }))), the reading going through the view's ownonMessage. - Held row. A row holding focus stays drawn beside the window while it is scrolled
out (
Message.Focusedreports it asModel.held,WindowList.heldRow(model, keys)is its index, andkeepretains its height), so the reader keeps their place in the tab order;VirtualListkeeps neither. - Reveal.
WindowList.reveal(model, index, align?)is theRevealCommand that scrolls the page until rowindexis drawn and shown, however far outside the window (align:nearestby default,start,centerorend); return it from anupdate, and it answersMessage.CompletedReveal. - Find in page.
findable: (item, index) => textlets the browser's find in page match rows that are not drawn: each row outside the window is ahidden="until-found"stand-in holding that text in the spacers, which keep their height, and a match (Message.Found) reveals its row. It costs a node and a text node per row, so it is for lists of thousands; it is drawn once the runtime has placed the list and only whereWindowList.supportsFindable()says the browser finds hidden text. - Server pages. A server's page opens the list at a row with
from(a page's?from=): the window starts at that row, with no overscan above it, and the rows above take no room untilTrackplaces the list, which gives them their room and scrolls the window by what that moved the first row drawn, so a reader sees the same rows before and after the runtime takes the page over. The firstPlacedsetsfromback to 0, and the list follows the window. For a page without scripts,WindowList.pageOf(model, keys)is{ start, end, previous, next }: the rows drawn and, asOptions, the rows the pages either side open at (previousthe first whose window reaches this one's start), for links that set?from=.