1.20.1 Procedures

Procedure: command-item label KEY: #:href #:hint #:keywords ¶

Create one command in a command palette.

A command is a link: choosing one is a navigation, and the palette is only a quicker way to find it. keywords are extra words the filter should match (a synonym, an abbreviation) and are kept out of the visible label.

label

The command’s visible text.

href

Where the command goes.

hint

An optional keyboard shortcut or category shown at the end of the row.

keywords

Optional extra text for the filter to match.

(command-item "Open settings" #:href "/settings" #:hint "G S")

Procedure: command-palette KEY: #:id #:label #:placeholder #:commands #:empty-text #:close-label #:classes ¶

Create a command palette, opened by a link and filtered as you type.

The palette is a dialog revealed by :target, like the drawer: an anchor to #commands opens it and an anchor to "#" closes it, so it works with scripting off and the URL states what is open. The input filters the list in the browser, and the script that ships with the framework adds arrow-key navigation and the common keyboard shortcut.

The list is a list of real links, which is what makes the palette useful in a server-rendered page: every row is something that can be followed, not a button whose meaning lives in a client-side handler.

id

The identifier the opening link targets.

label

The accessible name of the dialog and its list.

placeholder

The input’s placeholder. Defaults to "Type a command…".

commands

A list of command-item nodes.

empty-text

What the palette says when the filter matches nothing.

close-label

The accessible name of the backdrop’s close control.

classes

Extra classes for the panel.

(command-palette #:id "commands"
                 #:commands (list (command-item "Home" #:href "/")))

Procedure: drawer KEY: #:id #:title #:content #:footer #:side #:close-label #:label #:classes ¶

Create a drawer that slides in from an edge, opened by a link.

The drawer is a real dialog, revealed by the CSS :target pseudo-class: link to it with (a "Filters" #:href "#filters") and it appears, follow a link to "#" and it is gone. That means the whole overlay works with scripting off, and the URL says which overlay is open, which is the same contract the framework’s modal already uses.

The drawer is placed at the end of the page, so the link that opens it is never itself covered by it. A drawer that carries a form is the common case – filters, a cart, a settings panel – and the footer is where its actions go.

id

The identifier the opening link targets.

title

The dialog’s title, also its accessible name.

content

The drawer body.

footer

An optional list of actions.

side

'right (default), 'left or 'bottom.

close-label

The accessible name of the close control.

label

An optional accessible name overriding the title.

classes

Extra classes for the panel.

(drawer #:id "filters" #:title "Filters"
        #:content (list (checkbox #:label "In stock" #:name "stock")))

Procedure: dropdown-item label KEY: #:href #:on-click #:danger? #:disabled? #:classes ¶

Create one item of a dropdown menu.

The item is a link when it has an href, and a button otherwise, so a menu is a list of ordinary controls rather than a list of scripted rows. Items carry role="menuitem"; the menu itself is the native disclosure around them.

label

The item’s text.

href

The destination, for a navigation item.

on-click

A JavaScript handler, for an item that acts in place.

danger?

Whether the item is destructive.

disabled?

Whether the item is disabled.

classes

Extra classes for the item.

(dropdown-item "Duplicate" #:on-click "duplicate()")

Procedure: dropdown-menu KEY: #:label #:items #:position #:open? #:classes ¶

Create a dropdown menu that opens without JavaScript.

The menu is a native <details>: its summary is the trigger, its body is a list of menu items, and the browser does the opening and closing. The script that ships with the framework adds the keyboard behaviour a role="menu" promises – arrow keys, Home and End, Escape – and leaves the menu usable when it is not there.

label

The trigger’s visible text.

items

A list of dropdown-item nodes.

position

'bottom-start (default), 'bottom-end, 'top-start or 'top-end.

open?

Whether the menu starts open. Defaults to false; a menu on a page normally opens when its summary is clicked, but a demo or a menu that should draw attention can start expanded.

classes

Extra classes for the menu wrapper.

(dropdown-menu #:label "Actions"
               #:items (list (dropdown-item "Rename" #:href "/rename")
                             (dropdown-item "Delete" #:danger? #t)))

Procedure: hover-card KEY: #:trigger #:title #:content #:position #:label #:classes ¶

Show a small card of richer content when a trigger is hovered or focused.

A tooltip is a sentence; a hover card is a little more – a name, a role, a couple of links. It appears on hover and on keyboard focus, because :focus-within is part of the same rule, and its content is real markup inside the page, not generated content, so assistive technology can reach it.

The card is not a modal and does not trap focus: a reader can ignore it, tab past it, or follow what is inside it. That is the right shape for a preview; a surface that must be dealt with is a dialog.

trigger

The label or node the card is attached to.

title

An optional heading inside the card.

content

The card body.

position

'bottom-start (default), 'bottom, 'top-start or 'top.

label

The accessible name of the card.

classes

Extra classes for the card.

(hover-card #:trigger "@ada" #:title "Ada Lovelace"
            #:content (list (p "Wrote the first algorithm.")))

Procedure: popover KEY: #:id #:trigger #:content #:title #:position #:label #:classes ¶

Attach a native popover to a trigger.

The popover is the HTML Popover API: the control carries popovertarget, the panel carries the popover attribute, and the browser puts the panel in the top layer, dismisses it on Escape or an outside click, and does not let it be clipped by an ancestor. That is a lot of behaviour no script of ours has to implement.

Placement is CSS anchor positioning where the browser supports it: the trigger names an anchor, the panel points at it, and the stylesheet places the panel below or above it. Where anchor positioning is not available, the panel falls back to the browser’s own centred popover placement, which is usable even if less precise – and the position class is still there for a page that wants to nudge it.

id

The identifier the trigger’s popovertarget names.

trigger

The button’s label, or a node to put inside the button.

content

The popover body.

title

An optional heading inside the popover.

position

'bottom-start (default), 'bottom, 'top-start or 'top.

label

The accessible name of the panel, when there is no title.

classes

Extra classes for the panel.

(popover #:id "share" #:trigger "Share"
         #:title "Share this page"
         #:content (list (copy-button #:text "https://example.org")))

Procedure: sheet KEY: #:id #:title #:content #:footer #:close-label #:label #:classes ¶

Create a bottom sheet: a drawer anchored to the bottom edge.

This is drawer with #:side 'bottom, named for the surface it makes. On a phone it is the shape a picker or an action list usually takes, and it is still a plain anchor target, so it opens without a script.

id

The identifier the opening link targets.

title

The sheet’s title and accessible name.

content

The sheet body.

footer

An optional list of actions.

close-label

The accessible name of the close control.

label

An optional accessible name overriding the title.

classes

Extra classes for the panel.

(sheet #:id "actions" #:title "Actions" #:content (list (p "...")))