Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Keyboard-activation helpers: making a non-`<button>` element that carries an
* `onClick` keyboard-operable, plus the shared predicates for "is this keystroke
* an activation?" that global key handlers consult before claiming a key.
*
* A `<div onClick>` / `<span onClick>` is invisible to keyboard and
* screen-reader users: it isn't focusable and Enter/Space do nothing. Native
* `<button>` is always preferable, but when a clickable element can't be a
* button (it wraps block content, participates in drag-and-drop, or would lose
* its layout styling), these helpers restore the missing semantics without a
* visual change:
*
* - `role="button"` so assistive tech announces it as activatable,
* - `tabIndex={0}` so it enters the keyboard tab order,
* - an `onKeyDown` that fires the handler on Enter and Space (and
* `preventDefault`s Space so the page doesn't scroll).
*
* Usage — keep the existing `onClick` and spread the a11y props:
*
* <div onClick={select} {...clickableProps(select)}>…</div>
*
* For a disabled clickable, pass `{ disabled: true }` — it drops `tabIndex`
* and the key handler and sets `aria-disabled` so the element is announced as
* unavailable but stays out of the tab order.
*/
/**
* Build an `onKeyDown` handler that invokes `handler` when the user presses
* Enter or Space on a focused element. Space is `preventDefault`ed so the
* page doesn't scroll. Returns `undefined` when `handler` isn't a function so
* it can be spread safely.
*
* @param {(event: KeyboardEvent) => void} handler
* @returns {((event: KeyboardEvent) => void) | undefined}
*/
export function onActivateKeyDown(handler) {
if (typeof handler !== 'function') return undefined;
return (event) => {
// Only activate when the key event ORIGINATED on the element this handler
// is attached to — not when it bubbled up from a focusable descendant.
// A clickable container often wraps its own action buttons (a row with a
// Delete/Stop/Remove button, an expandable card with a caret toggle);
// without this guard, pressing Enter/Space while focused on the inner
// button would bubble here, fire the container's handler, AND
// `preventDefault` the button's native activation — so "Delete" would
// select the row instead of deleting. Only focusable descendants can be a
// distinct key-event target (a non-focusable <span>/<div> never receives
// the keydown), so this precisely excludes the controls we must not hijack.
// `currentTarget` is only null outside a live dispatch (synthetic test
// events) — there the guard is a no-op and activation proceeds.
if (event.currentTarget != null && event.target !== event.currentTarget) return;
// `' '` is the modern key value; `'Spacebar'` covers legacy engines.
if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
event.preventDefault();
handler(event);
}
};
}
/**
* Return the ARIA + keyboard props that make a non-`<button>` clickable
* element keyboard-accessible. Spread alongside the element's existing
* `onClick` handler.
*
* @param {(event: Event) => void} handler - The same activation handler wired to `onClick`.
* @param {object} [options]
* @param {string} [options.role='button'] - ARIA role to advertise.
* @param {boolean} [options.disabled=false] - When true, marks the element `aria-disabled` and keeps it out of the tab order.
* @returns {{ role: string, tabIndex?: number, onKeyDown?: Function, 'aria-disabled'?: boolean }}
*/
export function clickableProps(handler, { role = 'button', disabled = false } = {}) {
if (disabled) {
return { role, 'aria-disabled': true };
}
return {
role,
tabIndex: 0,
onKeyDown: onActivateKeyDown(handler),
};
}
/**
* True when a keystroke is a Space press on a focused button-like element or
* native disclosure summary, where the browser will activate the control.
*
* App-global single-key handlers bound to Space (the voice widget's
* push-to-talk hotkey, page-level shortcut maps) must stand down for these:
* `preventDefault`ing here would swallow every keyboard button press in the app
* and run the global action instead. Scoped to Space and to button-like targets
* only — anchors do NOT activate on Space (Enter only), so exempting them would
* just make Space dead on a focused link.
*
* @param {KeyboardEvent} event
* @returns {boolean}
*/
export function isButtonActivation(event) {
const isSpace = event?.key === ' ' || event?.key === 'Spacebar' || event?.code === 'Space';
if (!isSpace) return false;
const target = event.target;
if (typeof target?.closest !== 'function') return false;
return target.closest('button, [role="button"], details > summary:first-of-type') != null;
}
/**
* True for the keys that count as "press this control": Enter or Space. Matches
* on `code` as well as `key`, so a surface reading raw `KeyboardEvent.code`
* (game/drill input) and one reading `key` agree on what a press is.
*
* @param {KeyboardEvent} event
* @returns {boolean}
*/
export function isPressKey(event) {
return event?.key === 'Enter'
|| event?.key === ' '
|| event?.key === 'Spacebar'
|| event?.code === 'Space';
}
/**
* True when an event came from a field the user is typing into, so a single-key
* shortcut (a/d/g/j/k), a bare arrow, or a Space-claiming surface never steals a
* keystroke or caret move. The standard form fields plus any contentEditable
* surface count.
*
* @param {EventTarget | null} el
* @returns {boolean}
*/
export function isEditableTarget(el) {
if (!el || typeof el.tagName !== 'string') return false;
if (el.isContentEditable) return true;
return el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT';
}
/**
* The one predicate every app-global key handler consults before acting on a
* window keystroke: "is this event off-limits to me?". `useKeyboardShortcuts`
* (bubble-phase shortcut maps) and `useKeyCapture` (capture-phase key claiming)
* both route through it, so a guard added here lands for both instead of having
* to be re-remembered at each hook — the drift that let `useKeyCapture` swallow
* native button activation while the other two Space paths stood down (#4748).
*
* Always ignored, with no opt-out:
* - **Editable targets** — typing into an input/textarea/select/contentEditable.
* - **Native button activation** (`isButtonActivation`) — Space on a focused
* button-like element, where the browser is about to click it. Claiming that
* press swallows every keyboard button activation on the surface and runs the
* global action instead.
*
* Ignored by default, opt out per handler:
* - **⌘/Ctrl/Alt chords** (`allowChords`) — so app/browser shortcuts still win.
* A handler that reads a raw physical key (a keyer, a game control) passes
* `allowChords: true`, because dropping a chorded keydown strands it with no
* matching keyup.
* - **OS auto-repeat** (`ignoreRepeat`) — a held key fires once, not once per
* repeat tick. A handler that tracks press/release itself passes
* `ignoreRepeat: false` and filters `e.repeat` on its own terms.
* - **An open `aria-modal` dialog** (`enabledInDialog`) — the dialog owns the top
* surface, so a key aimed at it must not reach a handler still mounted behind
* it. A surface that itself lives INSIDE the dialog opts back in.
*
* @param {KeyboardEvent} event
* @param {object} [options]
* @param {boolean} [options.enabledInDialog=false] act even while a dialog is open
* @param {boolean} [options.ignoreRepeat=true] drop OS auto-repeat keydowns
* @param {boolean} [options.allowChords=false] act on ⌘/Ctrl/Alt chords too
* @returns {boolean} true when the handler must stand down
*/
export function shouldIgnoreGlobalKey(event, { enabledInDialog = false, ignoreRepeat = true, allowChords = false } = {}) {
// Cheapest guards first: plain flags, then a property read, then an ancestor
// walk, and only then the full-document query — this runs on every keystroke
// of every mounted consumer.
if (!allowChords && (event.metaKey || event.ctrlKey || event.altKey)) return true;
if (ignoreRepeat && event.repeat) return true;
if (isEditableTarget(event.target)) return true;
if (isButtonActivation(event)) return true;
if (!enabledInDialog && document.querySelector('[aria-modal="true"]')) return true;
return false;
}
/**
* True when a keystroke is the focus-escape gesture — a backtab (Shift+Tab),
* the conventional "leave this widget" move — that a key-capturing widget must
* release to the browser instead of consuming.
*
* The consumer is a widget whose input surface claims nearly every keystroke —
* the Shell page's xterm terminal, whose helper textarea sits in the tab order
* but whose `_keyDown` `preventDefault`s Tab, Shift+Tab and Escape alike
* (WCAG 2.1.2 keyboard trap). Installed as
* `term.attachCustomKeyEventHandler((e) => !isFocusEscapeKey(e))`, the `false`
* return makes xterm bail before it cancels the event, so the browser performs
* the backtab and focus lands on the previous tabbable element — and nothing
* is sent to the PTY. Plain Tab stays claimed: it is shell completion, and
* forward-leaving is what the controls laid out before the terminal are for.
*
* Chorded variants are deliberately not excluded — a Ctrl/Alt+Shift+Tab the
* browser or OS owns (previous browser tab, window switching) must pass
* through rather than be eaten by the widget too.
*
* @param {KeyboardEvent} event
* @returns {boolean}
*/
export function isFocusEscapeKey(event) {
return event?.key === 'Tab' && event?.shiftKey === true;
}
/**
* Props for the ROOT of a surface that owns a key globally — a drill scored on
* Space, the Morse keyer, RapidReader, the OpenWorld rig.
*
* On such a surface a button that keeps focus after a mouse click silently takes
* the key over: `shouldIgnoreGlobalKey` correctly stands the global handler down
* for native button activation, so the next Space presses the lingering button
* instead of driving the surface. `preventDefault` on `mousedown` is what
* suppresses that focus — it leaves the click itself, and every keyboard path,
* untouched, so a user who TABS to the button still focuses and activates it.
*
* This sits on the surface root rather than on each button deliberately. The
* per-button form has to be remembered for every control on the surface and for
* every control added later — the same "re-remember it at each site" drift that
* made #4748 a bug in the first place — and these surfaces render their buttons
* across several child components. One capture-phase handler at the root covers
* all of them, including ones that don't exist yet.
*/
// The control whose pointer focus was last suppressed. A button that opens a
// dialog never becomes `document.activeElement`, so `useFocusTrap` would capture
// `<body>` as the element to restore focus to on close (WCAG 2.4.3) — this is
// what it falls back to instead. No staleness guard is needed beyond
// `isConnected`: the fallback is only ever consulted when nothing else holds
// focus, and anything else taking focus is exactly what makes that untrue.
let pointerFocusSuppressed = null;
export const noPointerFocusSurfaceProps = {
onMouseDownCapture: (event) => {
const control = event.target?.closest?.('button, [role="button"]');
if (!control) return;
event.preventDefault();
pointerFocusSuppressed = control;
},
};
/**
* The control `noPointerFocusSurfaceProps` last kept focus off, if it is still
* in the document. Focus restoration consults this when it finds nothing
* focused; everything else should read `document.activeElement`.
*
* @returns {Element | null}
*/
export function pointerFocusSuppressedElement() {
return pointerFocusSuppressed?.isConnected ? pointerFocusSuppressed : null;
}