@mwillbanks/tuil-focus

Overview

Deterministic focus scopes, traversal, and restoration for terminal interfaces.

@mwillbanks/tuil-focus is independently installable and also participates in the umbrella @mwillbanks/tuil runtime where applicable.

Installation

npm install @mwillbanks/tuil-focus

How it operates

Focus scopes register semantic targets, order traversal deterministically, support directional movement, suspend or restore nested scopes, and expose an observable snapshot.

Documentation flow diagram. register scope; register node; activate; move; suspend/restore; dispose; S0 leads to S1; S1 leads to S2 — **Documentation flow diagram.** register scope; register node; activate; move; suspend/restore; dispose; S0 leads to S1; S1 leads to S2

API

API	Signature	Description
`FocusChange`	`interface FocusChange`	Public interface FocusChange.
`FocusDirection`	`type FocusDirection`	Public type FocusDirection.
`FocusManager`	`class FocusManager`	Public class FocusManager.
`FocusNode`	`interface FocusNode`	Public interface FocusNode.
`FocusNodeInput`	`type FocusNodeInput`	Public type FocusNodeInput.
`FocusProvider`	`function FocusProvider`	Public function FocusProvider.
`FocusScope`	`function FocusScope`	Public function FocusScope.
`FocusScopeDefinition`	`interface FocusScopeDefinition`	Public interface FocusScopeDefinition.
`FocusTrap`	`function FocusTrap`	Public function FocusTrap.
`useFocusable`	`function useFocusable`	Public function useFocusable.
`useFocusManager`	`function useFocusManager`	Public function useFocusManager.
`useFocusScopeId`	`function useFocusScopeId`	Public function useFocusScopeId.

Events and lifecycle

Focus changes are exposed through subscriptions; components use them with useSyncExternalStore rather than a separate event name.

All subscriptions and registrations return a disposer or belong to an owning runtime that disposes them in reverse order.

Example

import { FocusManager } from "@mwillbanks/tuil-focus";

const focus = new FocusManager();
focus.register({ id: "save", scopeId: "dialog" });
focus.focus("save");