Mixins / foldkit-mixins-ui

Buttons, actions and commands

WidgetWhat it doesState
ButtonAction button, toggle button (pressed), or link (href)Application / Adapter
ButtonGroupJoins buttons, fields, or menus with shared seamsApplication
ToolbarSingle-tab-stop toolbar with arrow-key navigationSmall Model / Bundle
CommandSearchable command palette with grouped, filterable rowsApplication
KbdKeyboard key or shortcut (Kbd.combo) badgeStateless

A button drawn as a button needs no draw callback. Button.view takes a label, a recipe style, and @foldkit/ui button options:

ts
import { Button, Recipes } from 'foldkit-mixins-ui'

const SaveButtonStyle = Recipes.Button.style({})

const saveButton = (disabled: boolean, h: HtmlBuilder<Message>) =>
  Button.view(
    {
      label: 'Save',
      style: SaveButtonStyle,
      type: 'submit',
      disabled,
      onClick: Message.Saved(),
    },
    h,
  )

disabled writes aria-disabled, not disabled, as upstream does, so the button keeps its focus. A type: 'submit' one therefore still submits its form, on Enter or a press: refuse the submit in update while it should not go.

attributes: { button?, icon? } adds what another component hands a slot, before the mixins resolve, as PasswordInput.view's do: a Dialog's initialFocus, so the dialog opens on that button (attributes: { button: dialog.initialFocus }). A class among them joins the style's, and an event or attribute a mixin owns is a conflict. Recipes.Button({ variant: 'icon' }) shows the icon alone, the label still the button's name; shape: 'square' draws any other variant as that square (an outlined icon button in a toolbar). A toggle button, shadcn's Toggle, is a Button with pressed, and each variant has its on look.

trailing draws after the label (a chevron, a count, a Kbd.combo); it is read as drawn, so a decorative one carries its own aria-hidden. description is a second line under the label, and both name the button. mark is a Badge or a dot on the button's corner, on the end side whatever the writing direction. invalid writes data-invalid and turns the button's colours to the danger tone: not aria-invalid, which a button's role does not take, so the reason is text the application draws. busy writes aria-busy and data-busy, and a press does nothing while it is on (a type: 'submit' button stops submitting too); it stays focusable. There is no loading option that draws a spinner, since that would put Spinner in every page that draws a button: compose icon: Spinner.view(...). href draws an anchor with the button's look; external opens a new tab and says so (words.external, default 'Opens in a new tab'), and a disabled link has no href. Recipes.Button({ variant: 'link' }) is the look of a link in running text; size: 'xs' is a step below sm.

ButtonGroup renders a named role="group" that joins its items (buttons, fields, menus, or plain strings in text boxes) so borders overlap cleanly and only outer corners remain rounded. Use orientation: 'vertical' to stack items, separated: true to draw rules between solid buttons, and Recipes.ButtonGroup (size, width: 'fill') to match item heights or span the container. Reach for Segmented when the group chooses a value.

Kbd draws a key badge ({ key }) with text or a key glyph, and Kbd.combo({ keys, joiner? }, h) joins multiple keys in one <kbd>.

Toolbar

A Toolbar is one tab stop over a row of controls you draw. It owns the keys (the arrows along its orientation, Home and End) and hands each control the attributes of its stop; you own which control holds the stop, so Tab comes back to the control focused last, and you draw the controls. Toolbar.view draws the toolbar and does no I/O; focus moves in the browser, and onFocus reports where it went.

items are, in order, controls { id, disabled?, draw }, where draw receives { attributes, disabled } and puts attributes (the id, the tabindex and a focus report) on the one focusable element and draws it off when disabled; groups { label, controls, disabled? }, a named role="group"; and the word 'separator', a rule between sets. roving is a placed RovingTabindex's slice ({ current }) and onFocus(id) is answered with its Focused. A disabled control (its own, its group's, or the toolbar's) is skipped by the arrows and never holds the tab stop; Toolbar.controlId(toolbarId, id) is the id a control draws, for a Command that focuses it. A focused text field, textarea, select or range keeps the keys it uses, so the arrows leave a text field only from the edge they point at: place a field last, or leave it with Tab. A key pressed in something the toolbar did not draw, such as a menu's rows, is left to it.

ts
import { Toolbar, ToolbarSlots } from 'foldkit-mixins-ui'

const BarModel = Schema.Struct({ stop: Schema.NullOr(Schema.String), bold: Schema.Boolean })
const BarMessage = defineMessageUnion({ Focused: { id: Schema.String }, ToggledBold: {} })
type BarMessage = typeof BarMessage.Type

const BarStyle = Recipes.Toolbar.style()
const ToolStyle = Recipes.Button.style({ tone: 'neutral', variant: 'outline' })

const barView = (model: typeof BarModel.Type, h: HtmlBuilder<BarMessage>) =>
  Toolbar.view(
    {
      id: 'format',
      label: 'Formatting',
      roving: { current: model.stop },
      onFocus: id => BarMessage.Focused({ id }),
      items: [
        {
          id: 'bold',
          draw: control =>
            Button.view(
              {
                label: 'Bold',
                pressed: model.bold,
                onClick: BarMessage.ToggledBold(),
                attributes: { button: control.attributes },
                style: ToolStyle,
              },
              h,
            ),
        },
        'separator',
        {
          id: 'link',
          disabled: true,
          draw: control =>
            Button.view(
              {
                label: 'Link',
                disabled: control.disabled,
                attributes: { button: control.attributes },
                style: ToolStyle,
              },
              h,
            ),
        },
      ],
      style: BarStyle,
    },
    h,
  )

roving is the { current } slice of a RovingTabindex: kept by hand here, or placed as Bundles.Toolbar (Bundle.withChild('bar', Bundles.Toolbar, { args: { current? } })), whose Model is passed as roving and whose Message Toolbar.focused(wrap) builds for onFocus: onFocus: Toolbar.focused(message => GotBar({ message })). Otherwise onFocus(id) is answered by setting it. Toolbar.configure({ base, presets }) returns a view with orientation, direction, loop and the look given once, as every configure does. control.attributes goes on the one focusable element, and control.disabled says to draw it off: the arrows skip it. routes are application key routes whose input is undefined.

Command

The field points at the highlighted row through aria-activedescendant; ↑ and ↓ wrap through enabled rows, PageUp and PageDown move the highlight ten rows and stop at the ends, Enter runs the highlighted one, and Home and End stay the field's caret keys. Rows never re-sort, and a filtered-away highlight moves to the first enabled row. A row is { value, label, description?, keywords?, shortcut?, icon?, opensPage?, disabled? }; a shortcut is a tuple of keys (['⌘', 'K']) drawn as Kbd with kbd and reads left to right on a right-to-left page. page: { trail, onBack } draws the pages stepped into as crumbs before the field, and Backspace in an empty field sends onBack; a row with opensPage has a chevron. loading: true says words.loading and marks the list aria-busy, its rows still shown, and a list nothing matches says words.empty (Command.words are the defaults, Loading… and No results.); hints are a footer of keys.

Command.hotkey(message) is ⌘K or Ctrl+K anywhere, for an application to lift with Subscription.persistentEntry and open its Dialog on; Command.filtered(groups, query) is what a query leaves. Command.keepActiveInView beside the style scrolls the highlighted row into view as the keys move it; like the other Mounts that send no Message it is a mixin, off by default. The list stands in a frame beside its bar, which Command.overlayBars drives (see Overlay scroll bars). routes are application key routes whose handle reads a CommandKeyInput of the query, the highlighted row and the rows the keys step through.