@furystack/shades/esm/services/spatial-navigation-service.d.ts

A lightweight UI framework for FuryStack with JSX support

import type { Injector, Token } from '@furystack/inject';
import { ObservableValue } from '@furystack/utils';
/**
 * Direction for spatial navigation movement.
 */
export type SpatialDirection = 'up' | 'down' | 'left' | 'right';
/**
 * Configuration options for the SpatialNavigationService.
 */
export type SpatialNavigationOptions = {
    /** Whether spatial navigation is enabled on startup. Default: true */
    initiallyEnabled?: boolean;
    /** Whether to allow cross-section navigation. Default: true */
    crossSectionNavigation?: boolean;
    /** Custom focusable selector override */
    focusableSelector?: string;
    /** Whether Backspace triggers history.back(). Default: false */
    backspaceGoesBack?: boolean;
    /** Whether Escape moves focus to parent section. Default: false */
    escapeGoesToParentSection?: boolean;
};
/**
 * Configuration token for {@link SpatialNavigationService}. Override via
 * {@link configureSpatialNavigation} before the service is first resolved.
 */
export declare const SpatialNavigationSettings: Token<SpatialNavigationOptions, 'singleton'>;
/**
 * Service for D-pad / arrow-key spatial navigation across interactive elements.
 *
 * Intercepts arrow key events and moves focus spatially based on element geometry.
 * Supports section boundaries via `data-nav-section` attributes and optional
 * cross-section navigation.
 *
 * @example
 * ```typescript
 * // Opt in to spatial navigation
 * const spatialNav = injector.get(SpatialNavigationService)
 *
 * // Disable during video playback
 * spatialNav.enabled.setValue(false)
 * ```
 */
export interface SpatialNavigationService {
    readonly enabled: ObservableValue<boolean>;
    readonly activeSection: ObservableValue<string | null>;
    /** Push a focus trap onto the stack. Nesting is supported — only the topmost trap is enforced. */
    pushFocusTrap(sectionName: string): void;
    /** Remove a focus trap from the stack. */
    popFocusTrap(sectionName: string, previousSection?: string | null): void;
    /** Programmatically move focus in a direction */
    moveFocus(direction: SpatialDirection): void;
    /** Programmatically activate (click) the currently focused element */
    activateFocused(): void;
}
export declare const SpatialNavigationService: Token<SpatialNavigationService, 'singleton'>;
/**
 * Configures spatial navigation options before the service is first instantiated.
 * Rebinds {@link SpatialNavigationSettings} and invalidates the cached
 * {@link SpatialNavigationService}. Must be called **before** the service is
 * first resolved — calling afterwards drops the cached instance without
 * disposing it (listeners leak until the injector is disposed).
 * @param injector The root injector.
 * @param options Configuration options for spatial navigation.
 */
export declare const configureSpatialNavigation: (injector: Injector, options: SpatialNavigationOptions) => void;
//# sourceMappingURL=spatial-navigation-service.d.ts.map