Navigation and focus

1. It searches in the requested direction for the nearest eligible element, beginning in the innermost focus section that contains the current element and then widening outward. A candidate must be rendered, visible, not inert, not aria-hidden, and not clipped from view by an ancestor that cannot scroll to reveal it.
2. If no element qualifies, it asks the owning scroll container to move in that direction when distance remains.
3. If neither focus nor scrolling can move, it sends the focused element an invalid-direction signal, which produces boundary rubber-band feedback.

import { useFocusNavigation } from '@wearables-ui-toolkit/mrbd';

const { moveFocus, activateFocused, clearFocus, isActive } = useFocusNavigation();

• Place the route’s primary task first so composition selects the intended initial target. A route centered on navigation can begin with navigation.
• Toolkit interactables are eligible for initial focus by default. Set initialFocusEligible={false} on an element that must not become the entry point.
• Keep the initial target completely visible in the first settled frame. If a long static introduction pushes it out of view, condense that content, make an earlier element interactive, or move the action to the bottom dock.
• Animate only the initial target into its focused state on load, using the same transition used during navigation. This preserves a single, unambiguous focus owner.

• Focusing the first or last element places the scroller at its absolute start or end when that element can remain fully visible and clear of the active fading edge and header inset. ScrollView verifies this before aligning the boundary. If non-focusable content before or after the control would move it outside the safe area, focus reveal takes priority; continued outward arrow input scrolls the remaining content incrementally.
• When focus has no eligible destination but the scroller has distance left, the scroller advances by a computed step instead of a full viewport.
• Directional navigation continues while any part of the focused element remains in the physical viewport. Focus can therefore move to a partially visible neighbor, whose normal reveal then clears fading edges and the header. If incremental scrolling moves the current element completely outside the viewport, the opposite arrow first scrolls it back into view and then moves to a neighbor.
• Fading edges communicate remaining distance. Their strength follows how much content remains hidden on that side, and the fade disappears at the true boundary. Avoid leading or trailing spacer elements and permanent fade clearance; the scroller owns this presentation.
• Rubber-band feedback indicates that no distance remains. The scroller uses any remaining distance before showing that boundary response.
• A focused ScrollView also responds to PageUp, PageDown, Home, and End.

import { useBackNavigation } from '@wearables-ui-toolkit/mrbd';

useBackNavigation(() => {
  if (!canGoBack) {
    return false;
  }
  goBack();
});

import { useReactRouterNavigation } from '@wearables-ui-toolkit/mrbd/react-router';

const { navigateBack } = useReactRouterNavigation();

• Give the transition its own location snapshot and pass that snapshot to the route switch. This ensures Back renders the retained page rather than the first matching route. Application Structure shows the complete shell.
• Store return state such as a pager index or selection outside the route. A detail route’s local state disappears when that route unmounts.

import { useRef } from 'react';
import { preserveFocusedInteractableDuringNavigation } from '@wearables-ui-toolkit/mrbd';

const releaseRef = useRef<(() => void) | null>(null);

function startNavigation(nextPath: string) {
  releaseRef.current?.();
  releaseRef.current = preserveFocusedInteractableDuringNavigation();
  navigate(nextPath);
}

function handleTransitionEnd() {
  releaseRef.current?.();
  releaseRef.current = null;
}

• Selecting a tab while the tab bar owns focus changes the page and keeps focus on the bar, allowing consecutive tab changes without dropping into content.
• A page change initiated outside the tab bar focuses the incoming page as usual.
• ArrowDown from the tab bar focuses the first focusable element in the current page.
• A scrim fades in behind the focused tab bar to keep labels legible over page content.
• autoHide defaults to false. When enabled, it fades the bar after inactivity and restores it on focus.

• Give every control a useful neighbor in each direction a user is likely to press, supporting predictable directional navigation.
• Keep exactly one visible focus owner so the next action is unambiguous.
• Use component-provided focus, partial-focus, and handoff behavior to maintain consistent feedback.
• Return focus to the control that opened an overlay when the overlay closes.
• Test Back through the host’s routed Back path in both directions, and verify the restored frame before it is revealed.

• Avoid raw key-event interception for custom navigation; it bypasses the provider’s focus and scroll coordination.
• Do not add a focusable wrapper around a focusable component or place focusable children inside a focusable container. Nested focus owners create ambiguous navigation and accessibility semantics.
• Animate only the selected initial target into focus rather than animating every control on load.
• Avoid custom scale or opacity effects that imitate the toolkit focus, because they can conflict with component-owned state.
• Every interactive route must expose an eligible initial-focus target so directional input has a valid starting point.