GrKbd

<GrKbd>
Esc
</GrKbd>

<GrKbd keys="mod+K" />

<GrKbd :keys="['mod', 'shift', 'P']" />

The slot remains usable for a single key. The keys prop accepts both a string ("mod+shift+K") and an array of tokens — assembling ⌘ + K from two GrKbd and a <span>+</span> is no longer necessary.

A combination is marked up with nested <kbd> — a device from the HTML specification: that way it stays keyboard input as a whole rather than a set of neighbouring elements. Only which of them carries the border depends on the variant.

<GrKbd keys="mod+K" />                      <!-- ⌘K -->

<GrKbd keys="mod+K" variant="split" />      <!-- ⌘ K -->

<GrKbd :keys="['G', 'I']" variant="sequence" />

The separator is computed by itself

separator is not set by default — that is auto:

• in merged the separator is put only after a word: ⌘K and ⌘⇧K on macOS, Ctrl+K and Ctrl+Shift+K on the rest. Within one platform the set is uniform (macOS gives symbols, the rest give words), so the rule “a symbol on the left — glue them” means “write it the way the system does”;
• in split it is +, in sequence a word from the locale (gr.kbd.then).

An explicit separator is stronger than the auto one: separator="" will glue anything, separator="+" will put a plus even between symbols. The separator is decorative (aria-hidden).

A space divides keys into steps, a plus — the keys within a step:

<GrKbd keys="g i" />        <!-- G then I -->

<GrKbd keys="mod+k p" />    <!-- ⌘K then P -->

That way the hint and the binding are described with one string: the same 'g i' is understood by v-hotkey (keyboard.md). Before that the string 'g+i' meant a chord for the directive and a chain for the hint, and what told them apart was variant, which the directive does not see.

The boundary of a step is stronger than variant: “then” appears between steps regardless of it. variant="sequence" remains working for a string without spaces — the old notation keys="g+i" variant="sequence" gives the previous result.

The array form of keys remains a flat chord: which is a step and which is a key, an array does not distinguish.

hotkey takes a combination by id from the registry of the application (granularityHotkeysPlugin) — then the hint cannot diverge from the binding:

<GrKbd hotkey="search.open" />

The prop is stronger than keys: when both are set, the registry wins, otherwise two sources would argue silently. An unknown id in a dev build gives a warning rather than an empty hint.

Tokens set more than the modifiers:

The case does not matter, and a glyph is accepted as a token too (↑, ⌘). Writing an arrow as a literal in the markup is neither necessary nor advisable: a token brings a readable name with it, while a bare glyph is pronounced by a screen reader as a sign.

The catalogue is not a table in the docs but data: GR_KBD_TOKENS is exported by the package, the showcase page is built from it, and it feeds the formatter as well. A copy of the list would diverge from the behaviour at the very first new key.

import { GR_KBD_TOKENS, findKbdToken } from '@feugene/granularity'

const navigation = GR_KBD_TOKENS.filter(spec => spec.group === 'navigation')
const command = findKbdToken('⌘') // the same token as `meta`

The mod token is Cmd on macOS and Ctrl on the other platforms; ctrl, alt and shift are shown as symbols on Apple too (⌃, ⌥, ⇧) and as words on the rest.

<GrKbd keys="mod+K" />                    <!-- detected automatically -->

<GrKbd keys="mod+K" platform="apple" />   <!-- always ⌘ -->

<GrKbd keys="mod+K" platform="other" />   <!-- always Ctrl -->

platform="auto" refines the platform after mounting: navigator in the first render would diverge from the server HTML and break the hydration. The non-Apple variant therefore always comes from the server, and the ⌘ appears on the client. If the audience is known in advance, platform removes even that repaint.

The same mod token is understood by the v-hotkey directive, so the hint and the binding are written the same way and do not diverge:

<div v-hotkey="{ 'mod+K': openSearch }">
  <GrKbd keys="mod+K" />
</div>

The parsing and the normalisation live in components/shared/hotkey.ts — the same module GrCommandPalette uses to match its own opening combination. A shared module rather than an import from the directory of the palette: otherwise a GrKbd → GrCommandPalette edge would appear in the build, and granular doctor would count it as an undeclared dependency.

Symbol keys get a readable name beside the symbol:

<kbd><span aria-hidden="true">⌘</span><span class="sr-only">Command</span></kbd>

Without that a screen reader pronounces ⌘ as “place of interest sign”. Words (Ctrl, Shift, Enter) are read on their own — no name is added to them, otherwise it would come out as “Ctrl Control”. The texts of the names are the gr.kbd.* keys.

The full scale of the package: xs, sm, md (the default), lg — the height, the minimum width, the padding, the type size and the gap between the keys change. size is read from GrConfigProvider.

min-w keeps a single symbol square: without it “K” would be narrower than “Esc”, and a row of shortcuts would jump.