Mixins / foldkit-mixins-ui

Navigation and structure

WidgetWhat it doesState
TabsTablist and active panel with optional close buttonsSmall Model / Bundle
NavStateless nav adapter or multi-panel menuApplication / Small Model
BreadcrumbPage trail with collapsible middle ellipsis or menuApplication
PaginationPage buttons, range summary, and page-size selectApplication
StepsOrdered step indicator with optional progress lineApplication
SidebarCollapsible, resizable navigation column and mobile sheetSmall Model / Bundle
AppShellPage frame with skip link, header, sidebars, and footerStateless
AccordionCollapsible heading/panel list (Accordion.toggled)Application / Bundle
DisclosureSingle toggle button and animated panelApplication / Bundle
TreeViewHierarchical tree with keyboard navigation and checksSmall 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. Pass collapse: { max, onExpand } to show an ellipsis button, or BreadcrumbMenu.make(...) (imported from its own module) to open hidden steps in a Menu.
  • AppShell. Draws a skip link to #main, sticky header (banner), optional side column, main region, optional aside landmark, and footer. On narrow screens (< md), the side column moves into the header row and aside moves below main.
  • Accordion. Keeps closed panels rendered with inert and matches open/close timing via --fk-collapse-duration and --fk-collapse-close-duration so switching sections animates smoothly. Accordion.toggled and Bundles.Accordion manage multiple and collapsible rules.

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

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.

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):

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

ts
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,
  )