Interaction Modality

Headless Interaction Modality; covers React Aria useFocusVisible, WICG focus-visible.

API

createInteractionModalityTracker

Create an SSR-safe, document-scoped interaction-modality observer. Trackers in one document share native capture listeners and state. Separate documents, including iframes, remain isolated. Call InteractionModalityTracker.dispose when using this factory outside a Vue effect scope.

function createInteractionModalityTracker( options: InteractionModalityOptions = {}, ): InteractionModalityTracker

useInteractionModality

Create a tracker owned by the current Vue effect scope. The tracker is disposed automatically when its component or effect scope is destroyed, preventing document-listener leaks.

function useInteractionModality( options: InteractionModalityOptions = {}, ): InteractionModalityTracker

isElementFocusVisible

Determine whether a focused element should expose its focus indicator. Native :focus-visible semantics take precedence. The modality fallback is used only when the selector is unsupported, preserving text-input and platform heuristics implemented by the browser.

function isElementFocusVisible( element: Element | null | undefined, modality: InteractionModality | null, ): boolean

classifyKeyboardEvent

Classify keyboard intent while excluding composition and modified shortcuts.

function classifyKeyboardEvent(event: KeyboardEvent): InteractionModalityEvent | null

classifyPointerEvent

Map pointer hardware into the stable public modality vocabulary.

function classifyPointerEvent(event: PointerEvent): InteractionModalityEvent

classifyVirtualClick

Classify coordinate-free clicks used by keyboards and assistive technology.

function classifyVirtualClick( event: MouseEvent, current: InteractionModality | null, ): InteractionModalityEvent | null

subscribeToDocumentModality

Subscribe to shared document state and return an idempotent release callback.

function subscribeToDocumentModality( document: Document, initialModality: InteractionModality | null, subscriber: (update: DocumentModalityUpdate) => void, ): { readonly current: InteractionModality | null; readonly release: () => void }

publishDocumentModality

Synchronize an explicit consumer update with every peer in a document.

function publishDocumentModality( document: Document, update: DocumentModalityUpdate, ): boolean

Behavior

Normative state × input → outcome table for @vizejs/ui/interaction-modality. Every row is exercised by src/families/accessibility/interaction-modality/interaction-modality*.test.ts; compile-only API assertions live in src/families/accessibility/interaction-modality/interaction-modality.types.test-d.ts.

Accessibility decisions

• Native :focus-visible is authoritative when available. This preserves browser heuristics for editable controls, platform conventions, and assistive technology instead of replacing them with a narrower JavaScript guess.
• keyboard and virtual are the only globally focus-visible modalities. Components should use isElementFocusVisible for the final per-element decision and must still provide an actual visible style.
• Pointer Events reserve pointerId: -1 for input not produced by pointing hardware. An empty-type pointer with that ID is classified as virtual.
• Modified shortcuts and composition do not change visual modality. Shift+Tab remains keyboard intent because it directly changes focus.

SSR, hydration, and document ownership

• Importing this entry performs no DOM read, listener installation, style injection, timer scheduling, or mutation of request-scoped state.
• With no global document, the default tracker is inert and deterministic.
• Trackers share listeners only when keyed by the same live Document. Weak ownership and reference counting release the hub when its final subscriber disposes; iframes and independently hydrated documents cannot leak state.
• Pass a reactive document getter when an island, iframe, or portal owner is not known until mount. Passing null explicitly is the SSR/deferred escape hatch.

Styling contract

This primitive emits no CSS and sets no attributes. Consumers may map isFocusVisible or isElementFocusVisible to classes, data attributes, CSS variables, utility frameworks, or fully custom styles. Never remove the browser outline unless an equivalent visible indicator is supplied.

Normative references

• WCAG 2.2 — Focus Visible (2.4.7)
• Selectors Level 4 — :focus-visible
• Pointer Events — pointer types and non-pointing input