Materials, motion, focus, and portals

• Let the component that owns interaction also own the material state transition. For interactable components, Container owns it through InteractableBase.
• Supply configuration from component code instead of running another state machine beside the material.
• Animate scale, material color, stroke, and glow from the same transition so their feedback stays synchronized.
• Programmatic focus must produce the same visual state as keyboard or directional-pad focus. This consistency is an accessibility invariant.
• Paint the intended resting or focused state on the first frame. Avoid an initial animation from an unscaled state because it makes page entry appear unstable.

import { useMemo, type ReactNode } from 'react';
import { Container, MaterialLibrary } from '@wearables-ui-toolkit/mrbd';

function UnboundedContainer({ children }: { children: ReactNode }) {
  const material = useMemo(() => MaterialLibrary.unbounded(), []);
  return <Container material={material}>{children}</Container>;
}

• A material instance carries mutable visual state and per-layer caches, so exactly one mounted host can own it at a time. Mounting the same instance in two containers concurrently throws.
• Memoize each factory call for its host. Avoid calling a factory inline during render because each new instance restarts the transition.
• Reuse the owner’s instance across renders to keep transitions continuous.
• withInset() returns a derived material with material-owned insets, and withoutInnerShadow() returns one with the inner-shadow layer removed. Both create independent layer instances. A stateful custom layer must therefore implement clone() so derived materials do not share mutable state.
• Prefer immutable or intentionally shared values in callbacks passed to createLayer. Use a layer class when the layer owns mutable state.

• Pointer press enters PRESSED on mouse down and leaves it on mouse up, mouse leave, blur, or a global pointer release.
• Enter and Space are handled on key down and key up. The default action is suppressed, the element runs the same press-in/press-out visuals, and key up dispatches a single activation.
• onActivate fires exactly once per activation and receives the originating mouse or keyboard event (InteractableActivationEvent). onClick still receives the genuine DOM click.
• A press that is released faster than the minimum feedback window is held at PRESSED for the full window before returning, so a quick tap is never invisible.
• Activation with no preceding pointer press — a programmatic or assistive click — emits a brief visual press pulse so feedback is still shown.
• onLongPress fires while the control is still pressed after the long-press timeout, and the click that would follow is suppressed.
• Repeated fast activation cannot strand the control in an impossible state: the pending release is recomputed when it runs, and it is cancelled on unmount.

• Press-in and press-out states are transient. Activation returns to FOCUSED while focus remains on the control.
• A control must not remain visually pressed after activation; stale feedback would misrepresent its current state.
• Application logic may debounce a duplicate semantic action, but it must not suppress press feedback because every activation needs a visible response.

1. Searches for the nearest eligible target in that direction, first within the focus sections that contain the current element and then across the whole container. Candidates are scored so distance along the movement axis dominates perpendicular offset, and a candidate directly in line with the current element wins over a closer but off-axis one.
2. Skips anything hidden, inert, aria-hidden, zero-sized, or clipped out of view by an ancestor that cannot scroll on that axis.
3. If no target exists, asks the nearest scroll container to scroll in that direction.
4. If neither focus nor scroll can move, signals an invalid direction to the focused element, which surfaces as onInvalidFocusDirection and the rubber-band effect.

• Exactly one component is focused at a time. The coordinator clears the previous owner before the new one claims focus.
• Keep the toolkit component as the interaction target instead of adding a second focusable wrapper. One target gives assistive technology and directional navigation a consistent owner.
• Use initialFocusEligible={false} to exclude a control from automatic initial focus while preserving its place in the tab order.

• Before the enter animation starts, the host waits for the incoming page’s images to load and decode, bounded by a short timeout, so the page does not animate in half-painted.
• The exiting page is marked aria-hidden and inert, so it never takes focus or input during the transition.
• With preservePageState, scroll positions are restored instantly before the page becomes visible and focus is restored to the element that had it, with retries so a lazily loaded page still lands focus once its content mounts.
• Page content updates during an in-flight transition are applied to the entering page only; the exiting page keeps its snapshot.

• They inherit the same theme custom properties.
• They use the application’s coordinate space, which keeps anchors correct when the app does not fill the browser viewport.
• They use the application’s compositing context, which keeps blend modes and additive-light display rendering consistent on the device.

• Anchor popup coordinates to the component that owns the popup.
• Treat popup direction as a preference. Custom popup content such as a menu flips when space is tight, while a built-in text tooltip keeps the requested side and clamps within the bounds.
• Clamp overlays to the application’s content area rather than the browser window.

• CSS transforms and opacity.
• CSS custom properties written at transition boundaries.
• Stable SVG elements with animated transforms.
• useSpringAnimation when you need a physical curve, writing to the DOM from onChange.

• Per-frame React state for visual animation.
• Remounting animated layers on focus change.
• Rewriting SVG geometry attributes every frame when a transform would do.
• Separately timed child animations that should be one synchronized transition.