<!-- Generated by tools/docs.php from docs/src/palette.html - edit the source, not this file. -->

# Command palette

One search for every place and action of an app, opened from anywhere by `⌘K` or `Ctrl K`: a dialog with the combobox's search and a list of links and buttons - Enter opens a page by its plain link or runs a button's command.

## Example

The button opens the dialog by the browser's command and names its keys in `aria-keyshortcuts`, which the library also takes as the shortcut. The options are links and buttons with `role="option"`, in groups; the search finds them by their words and by `data-keywords`.

```html
<button class="btn btn-subtle-secondary" type="button" commandfor="palette-demo-dialog" command="show-modal" aria-keyshortcuts="Meta+K Control+K"><i class="bi bi-search" aria-hidden="true"></i>Find or go to…<kbd>⌘K</kbd></button>
<dialog class="palette" id="palette-demo-dialog" closedby="any" aria-label="Find or go to">
	<input class="palette-search" type="search" role="combobox" aria-controls="palette-demo-list" aria-expanded="true" aria-autocomplete="list" aria-label="Find or go to" placeholder="Find or go to…" autocomplete="off" autofocus>
	<div class="palette-list" id="palette-demo-list" role="listbox" aria-label="Places and actions">
		<div role="group" aria-labelledby="palette-demo-go">
			<div class="menu-header" id="palette-demo-go" role="presentation">Go to</div>
			<a class="menu-item" role="option" id="palette-demo-pages" href="#palette-examples"><i class="bi bi-file-text" aria-hidden="true"></i>Pages</a>
			<a class="menu-item" role="option" id="palette-demo-excursions" href="#palette-examples"><i class="bi bi-compass" aria-hidden="true"></i>Excursions</a>
			<a class="menu-item" role="option" id="palette-demo-media" href="#palette-examples" data-keywords="images photos files"><i class="bi bi-images" aria-hidden="true"></i>Media library</a>
			<a class="menu-item" role="option" id="palette-demo-languages" href="#palette-examples" data-keywords="translations strings"><i class="bi bi-translate" aria-hidden="true"></i>Languages</a>
			<a class="menu-item" role="option" id="palette-demo-settings" href="#palette-examples" data-keywords="preferences options"><i class="bi bi-gear" aria-hidden="true"></i>Settings</a>
		</div>
		<div role="group" aria-labelledby="palette-demo-do">
			<div class="menu-header" id="palette-demo-do" role="presentation">Actions</div>
			<button class="menu-item" role="option" id="palette-demo-new" type="button" data-docs-run="toast-success"><i class="bi bi-plus-lg" aria-hidden="true"></i>New page</button>
			<button class="menu-item" role="option" id="palette-demo-cache" type="button" aria-disabled="true"><i class="bi bi-arrow-clockwise" aria-hidden="true"></i>Rebuild every page</button>
		</div>
	</div>
	<p class="combobox-no-results" hidden>Nothing found</p>
	<div class="palette-footer"><span><kbd>↑</kbd> <kbd>↓</kbd> to move</span><span><kbd>↵</kbd> to open</span><span><kbd>esc</kbd> to close</span></div>
</dialog>
```

## Shortcuts

A button or a link whose `aria-keyshortcuts` names a combination with `Control`, `Meta` or `Alt` is pressed by it: the page states the keys once, for screen readers and for the library. Where both `Meta+K` and `Control+K` are named, Apple's systems answer `⌘K` and the others `Ctrl K`, so `Control K` keeps its meaning in a Mac's text fields; Firefox's own `Ctrl K` gives way to the page's.

- A single key is never a shortcut here: WCAG 2.1.4 asks for a way to turn such keys off, and a combination needs none.
- A disabled or hidden button is left alone, and so is one outside an open modal dialog.
- The hint the button shows - `⌘K` or `Ctrl K` - is the page's to write.

## Keyboard and accessibility

| Key | In the palette |
| --- | --- |
| `⌘K`, `Ctrl K` | Opens it from anywhere, the focus in its search |
| `↓` / `↑` | The next / the previous option, round the ends |
| `Page Down` / `Page Up` | Ten options on / back |
| `Enter` | Opens the active link or presses the active button; the palette closes |
| `Esc` | Empties the search; on an empty search, closes the palette, the focus back where it was |

- The palette is a modal `<dialog>` with a name; a click on its backdrop closes it (`closedby="any"`). Opening it empties its search.
- Its search is the WAI-ARIA combobox with a listbox, as in [Combobox](combobox.md): the options are plain links and buttons with `role="option"`, so a link opens in a new tab with `⌘` or the middle button as any link does. The library keeps them out of the Tab order (`tabindex="-1"`): the arrow keys reach them, as in every listbox.
- Where the options come from - the app's menu, recent pages, a search on the server - is the page's: a server search answers `redz:search` as a combobox's does.

## Tokens

From [`css/components/palette.css`](https://github.com/redz-tech/REDZ.UI/blob/main/css/components/palette.css), which declares no custom property of its own.

It reads the theme's `--redz-border`, `--redz-radius-12`, `--redz-bg-raised`, `--redz-shadow-3`, `--redz-text`, `--redz-space-16`, `--redz-fs-16`, `--redz-text-muted`, `--redz-focus`, `--redz-space-4`, `--redz-space-8`, `--redz-bg-hover`, `--redz-fs-12`, `--redz-ease`.
