Mixins / foldkit-mixins-ui
Buttons, actions and commands
| Widget | What it does | State |
|---|---|---|
Button | Action button, toggle button (pressed), or link (href) | Application / Adapter |
ButtonGroup | Joins buttons, fields, or menus with shared seams | Application |
Toolbar | Single-tab-stop toolbar with arrow-key navigation | Small Model / Bundle |
Command | Searchable command palette with grouped, filterable rows | Application |
Kbd | Keyboard key or shortcut (Kbd.combo) badge | Stateless |
A button drawn as a button needs no draw callback. Button.view takes a label, a recipe style, and @foldkit/ui button options:
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.
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.