Mixins / foldkit-mixins-ui
Navigation and structure
| Widget | What it does | State |
|---|---|---|
Tabs | Tablist and active panel with optional close buttons | Small Model / Bundle |
Nav | Stateless nav adapter or multi-panel menu | Application / Small Model |
Breadcrumb | Page trail with collapsible middle ellipsis or menu | Application |
Pagination | Page buttons, range summary, and page-size select | Application |
Steps | Ordered step indicator with optional progress line | Application |
Sidebar | Collapsible, resizable navigation column and mobile sheet | Small Model / Bundle |
AppShell | Page frame with skip link, header, sidebars, and footer | Stateless |
Accordion | Collapsible heading/panel list (Accordion.toggled) | Application / Bundle |
Disclosure | Single toggle button and animated panel | Application / Bundle |
TreeView | Hierarchical tree with keyboard navigation and checks | Small Model / Bundle |
- Breadcrumb. Renders links for prior steps and
aria-current="page"for the current step, placing separators between items so wrapped lines never start with one. Passcollapse: { max, onExpand }to show an ellipsis button, orBreadcrumbMenu.make(...)(imported from its own module) to open hidden steps in aMenu. - AppShell. Draws a skip link to
#main, sticky header (banner), optionalsidecolumn,mainregion, optionalasidelandmark, andfooter. On narrow screens (< md), the side column moves into the header row andasidemoves belowmain. - Accordion. Keeps closed panels rendered with
inertand matches open/close timing via--fk-collapse-durationand--fk-collapse-close-durationso switching sections animates smoothly.Accordion.toggledandBundles.Accordionmanagemultipleandcollapsiblerules.
Tabs
Tabs.view is the usual drawing (rows with a mark, words, a trailing Html and a panel; orientation: 'vertical' lays the panel beside the tabs; close and routes as below); it takes mixins: [...Tabs.fluid] as a value, so a page that never passes it never loads what glides the indicator. Its root slot holds the tablist and the panel. Tabs.toView stays the lower rung for a drawing of your own.
TabsContext.close: { onClose } gives each tab a close button (no tab stop, hidden
from assistive technology) and Delete, named in aria-keyshortcuts; answer with
Tabs.closing(tabs, chosen, closed), which gives the tabs left, the tab chosen
and the index to focus with FocusTab. TabsContext.routes takes keys the
application answers on a tab, such as F2 renaming it, beside Delete: the input is
the tab's TabInfo, and a tab with no key to answer draws no keydown at all.
overflow: 'scroll' is one line with its edges fading; 'wrap' is a grid of equal
columns that fills the row and falls to fewer columns, no tab cut off (a column is
no narrower than three control heights; .extend the tablist's --_fk-tab-min to
change it). selection: 'tint' is the accent's tint and ink instead of the raised
pill, as a pressed Segmented option is; upstream's orientation: 'Vertical' stands
the rule at the tabs' inline end. Tabs.fluid glides the indicator (see Fluid
highlights).
Nav
The navigation menu shows its panels in the top layer, with the APG's
disclosure-navigation keys (Escape, ArrowDown into a panel, the arrows, Home and End
along the row; a press outside and focus leaving close it). A trigger names its
panel in aria-controls only while the panel is drawn, and links are keyed by place
as well as address, so two links to one address do not collide. A panel's groups
are { label, href, description?, current? } columns. routes takes
application key routes on the top-level links and
triggers, beside the row's own: the input is the entry and item.index its place;
panelRoutes takes keys on a panel's links, where the input is the link and
item.index its place among the panel's links. Nav.fluid glides a line to the
current link and a faint pill to the one the pointer nears.
Pagination
Fewer than two pages draws no stops; with a range it still draws the summary and
the page-size select. range.choose: { sizes, onPerPage } adds a select of
rows per page (labelled words.perPage, Rows per page) that sends onPerPage with the
size; the application sets perPage and a page that keeps its rows in view.
numbered: false leaves previous and next alone; ends draws first and last.
icons: { first?, previous?, next?, last? } draws an Html in place of a stop's word, which stays the button's accessible name.
Pagination.configure({ base, presets }) fixes the style, words, windows, ends, numbered and icons once.
words: { label, first, previous, next, last, stop, ellipsis, ofCount, perPage, summary } (Pagination.words, merged word by word) is every word it says, as text with blanks: stop is "{word} page" (each stop's name), ofCount / {count}, summary "{from}–{to} of {total}", for another
language. A stop at an end is aria-disabled, not disabled, so it keeps focus and
sends nothing. The current stop reads aria-current and holds / 12 in a
pageCount span hidden from assistive technology; compact shows only that stop and
no ellipses.
Steps
The marker is hidden from assistive technology, so words: { complete?, current?,
upcoming? } (defaults Steps.words: Completed, an empty word that says nothing,
Upcoming; the current step's aria-current="step" already says it) say each step's state in text after its
title, in the state slot. progress (0 to 1) fills the connector after the
current step when the recipe's connector is a progress bar. 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.
A step may state its own state (complete, current, upcoming, loading or error) over the one
current gives it: a later step already complete, the one being taken loading, a step that
errored. aria-current still follows current, and each state has a word (loading: In progress,
error: Failed). A step's trailing Html (a time, a badge) ends its row in the trailing slot, and
the recipe's labels: 'current' keeps only the current step's words beside its marker, 'hidden' none,
the rest left to a screen reader. Steps.configure({ base, presets }) fixes the style and words once.
Sidebar
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; a rail that draws a row init's rows did not list throws, since a Tooltip
is state only init can make). 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, Home
collapses it (a collapsed one leaves the key alone) and End goes to the widest, Enter
or a double-click collapses it, and dragged below half min it collapses, coming
back at the width the drag began at.
A row and a nested link take RowContent's parts: content drawn in place of the
label's text (the label still names it), and trailing Html at its end in a
trailing Slot (a key, a status dot), which gives way to the row's action under the
pointer as the badge does. words (Sidebar.words: show, hide, open,
resize, each with {label}) name the toggle, the phone's opener and the resize
handle. A group shuts over the time it opens in. Sidebar.fluid and the Slots are
files of their own, so a sidebar without the glide keeps no FluidHover.
TreeView
One tab stop; Up/Down move through the rows showing, stepping over shut and disabled
ones; Right opens or steps in, Left shuts or steps out (swapped under direction:
'rtl'); Home/End; letters typed within 500ms of each other find the next showing row
whose label starts with all of them (TreeView.Model.typeahead, cleared by the
QueryExpired Message, which an application that wraps the Messages passes through to
update); * opens every row beside the current one that holds rows; Enter, Space or
a click chooses a row and opens or shuts a branch. Keys reach update, which decides
from its own Model and sends a focus Command. A shut group stays drawn and inert.
checkable (on the view and update) gives each row a box: the Model's checked
holds the leaves, a branch reads checked, mixed or not from them
(TreeView.checksOf), and Space checks the current row in update. The Model's
checked is the one owner: the checked rows that hold no rows. An application that
stores or sends another shape converts at the edge, with two pure functions over the
same nodes, TreeView.checkedAs(nodes, checked, 'leaf' | 'branch' | 'trunk') and
TreeView.leavesOf(nodes, value):
import { TreeView, type TreeNode } from 'foldkit-mixins-ui'
const nodes: ReadonlyArray<TreeNode> = [
{
id: 'src',
label: 'src',
children: [
{ id: 'button', label: 'button.ts' },
{ id: 'tree', label: 'tree.ts' },
],
},
{ id: 'readme', label: 'README.md' },
]
TreeView.checkedAs(nodes, ['button', 'tree', 'readme'], 'branch') // ['src', 'button', 'tree', 'readme']
TreeView.checkedAs(nodes, ['button', 'tree', 'readme'], 'trunk') // ['src', 'readme']
const seeded = TreeView.init({ id: 'files', checked: TreeView.leavesOf(nodes, ['src']) })
// seeded.checked is ['button', 'tree']A row holding rows is listed once every row it holds that holds none is checked, a disabled one included. Ids the tree does not hold are left out of both. Independent checks that do not cascade, and branches whose rows are not loaded yet, are not modelled.
Disclosure
Disclosure.view draws the button and the panel from options (see its row above);
the adapter below is the rung for a layout of your own. The recipe draws the button
and the panel's box, and animatePanel keeps the shut panel inert and moves its
height.
import { Disclosure as UiDisclosure } from '@foldkit/ui'
import { Style } from 'foldkit-mixins'
import { Disclosure, DisclosureSlots, Recipes } from 'foldkit-mixins-ui'
const DetailsStyle = Recipes.Disclosure.style({ variant: 'bordered' })
const details = (isOpen: boolean, h: HtmlBuilder<Message>) =>
UiDisclosure.view(
{
id: 'details',
isOpen,
onToggle: isOpen => ToggledDetails({ isOpen }),
toView: attributes => {
const disclosure = Disclosure.resolve(attributes, [DetailsStyle.mixin], {
input: undefined,
h,
})
return h.div(
[],
[
h.button(disclosure.button, ['Shipping details']),
disclosure.animatePanel(h.div(disclosure.panel, ['Shipped in two days.'])),
],
)
},
},
h,
)