Why Q

Almost nothing binds it. Browsers and operating systems leave a bare Q alone, and it sits under your left hand, next to the number row. You can change the key.

q is written in TypeScript, has no dependencies and needs no framework. Its styles are one plain CSS file.

Install

npm install @ziran-project/q

Mount a wheel

import { createQ } from '@ziran-project/q';
import '@ziran-project/q/styles.css';

const q = createQ({
  items: [
    { id: 'home', label: 'Home', href: '/' },
    {
      id: 'projects',
      label: 'Projects',
      description: 'Everything in motion.',
      children: [
        { id: 'atlas', label: 'Atlas', href: '/projects/atlas' },
        { id: 'orbit', label: 'Orbit', href: '/projects/orbit' },
      ],
    },
  ],
});

That is a working wheel. Hold Q and it opens; choose a slot and q follows its href.

Use your router

Pass onNavigate and q calls it instead of following the link.

createQ({
  items,
  onNavigate: ({ item, path }) => router.push(item.href),
});

Clean up

Importing the package is safe on the server. Call createQ in the browser, once per document, and call destroy when the page or component goes away.

q.destroy();

Details that matter

Slots without a key of their own take the next free one from 1 2 3 4 5 W E R A S D F Z X C V, all within reach of the hand holding Q.

Slots that appear under a resting pointer do nothing until the pointer moves. One long hover cannot fall through several levels.

When a slot has the focus, after the arrow keys or Tab, Space and Enter press it, as they do on any button.

q ignores its keys while you type in a field or in editable content, and while Ctrl, Alt or the Command key is held.

Between three and eight slots per level read well. The trigger key and the back key cannot be used as a hotkey.

Treat the tree as immutable. To change it, call setItems with a new one.

You can feel the three delays before choosing them: Timing has a dial for each.

Content from renderItem should not be interactive. The slot is already a button.

State

interface QState {
  isOpen: boolean;
  path: string[];          // IDs of the open groups
  parent: QItem | null;    // the group being explored
  items: QItem[];          // the slots of the current level
  activeId: string | null; // the highlighted slot
  canGoBack: boolean;
}

import { createQController } from '@ziran-project/q/headless';

const navigation = createQController({ items, onNavigate });
const stop = navigation.subscribe((state) => render(state));

navigation.open();
navigation.select('projects'); // opens the group
navigation.select('atlas');    // calls onNavigate and closes

stop();

It has the same methods as the instance, except element and destroy. It runs in Node.

Keys, hold and tap, resting the pointer and the corner button belong to createQ. With the controller, they are yours to build.

Support

q needs <dialog> and Pointer Events, which every current browser has. The closing animation needs @starting-style; without it the wheel closes instantly.

Accessibility

The wheel is a modal dialog. While it is open, the page behind it is inert and the focus stays inside. When it closes, the focus returns to where it was.

Every slot is a button with a name and its key. Arrow keys and Tab reach all of them, Back included. The center announces the highlighted slot.

Animations are off for anyone who asks their system for reduced motion.

What is yours to check

Contrast, if you change the colors. Labels, if you replace the content of a slot. And after navigating, move the focus to the new page, as this site does.

.q-root,
.q-trigger {
  --q-surface: #ffffff;   /* center and corner button */
  --q-slot: #ffffff;
  --q-text: #16182a;
  --q-muted: #565a75;     /* descriptions */
  --q-accent: #ffd23f;    /* highlight and progress */
  --q-on-accent: #16182a; /* text over the accent */
  --q-backdrop: rgb(16 27 110 / 70%);
  --q-font: 'Bricolage Grotesque', sans-serif;
  --q-size: min(620px, calc(100vw - 16px), calc(100dvh - 16px));
}

Those are the values of Cobalt. To see them, hold Q and press W 1 2.

State

Each .q-slot says what is happening to it:

data-active

Highlighted by the pointer or the keyboard.

data-dwelling

The pointer is resting on it and it is about to open.

data-selected

Just chosen, while the wheel closes.

data-group

It has children.

More than one theme

Pass className to createQ and scope the variables to it, or scope them to an attribute on the page, as this site does.