@furystack/shades 13.0.0 → 13.1.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [13.1.0] - 2026-03-10
+
+### ✨ Features
+
+### Spatial Navigation Service
+
+Added `SpatialNavigationService` for D-pad / arrow-key spatial navigation across interactive elements. The service intercepts arrow key events and moves focus spatially based on element geometry, supporting section boundaries via `data-nav-section` attributes and optional cross-section navigation.
+
+**Key capabilities:**
+
+- Arrow key focus movement based on Euclidean distance between element centers
+- Section-scoped navigation with `data-nav-section` DOM attributes
+- Cross-section navigation with focus memory (restores last-focused element per section)
+- Input passthrough — arrow keys work normally inside text inputs, textareas, selects, and contenteditable elements
+- Configurable `Backspace` → `history.back()` and `Escape` → parent section behaviors
+- Runtime enable/disable via `enabled` observable
+- `configureSpatialNavigation()` helper to set options before the singleton is first resolved
+
+**Usage:**
+
+```typescript
+import { SpatialNavigationService, configureSpatialNavigation } from '@furystack/shades'
+
+// Configure before first use
+configureSpatialNavigation(injector, {
+  initiallyEnabled: true,
+  crossSectionNavigation: true,
+})
+
+// Or resolve directly with defaults
+const spatialNav = injector.getInstance(SpatialNavigationService)
+
+// Toggle at runtime
+spatialNav.enabled.setValue(false)
+```
+
+### `useDisposable` deps parameter
+
+Added optional `deps` parameter to `useDisposable` — when provided, the resource is re-created (and the old one disposed) whenever the serialized deps value changes.
+
+```typescript
+useDisposable('my-resource', () => createResource(value), [value])
+```
+
+### 🧪 Tests
+
+- Added tests for `SpatialNavigationService` covering directional movement, section boundaries, cross-section navigation, input passthrough, focus memory, and disposal
+
+### ⬆️ Dependencies
+
+- Updated `@furystack/core` dependency to the new major version
+
 ## [13.0.0] - 2026-03-07
 
 ### ⬆️ Dependencies

package/esm/models/render-options.d.ts

@@ -77,12 +77,15 @@ export type RenderOptions<TProps, TElementBase extends HTMLElement = HTMLElement
      */
     useRef: <T extends Element = HTMLElement>(key: string) => RefObject<T>;
     /**
-     * Creates and disposes a resource after the component has been detached from the DOM
+     * Creates and disposes a resource after the component has been detached from the DOM.
+     * When `deps` is provided, the resource is re-created (and the old one disposed) whenever
+     * the serialized deps value changes.
      * @param key The key for caching the disposable resource
      * @param factory A factory method for creating the disposable resource
+     * @param deps Optional dependency array — when deps change, the old resource is disposed and a new one is created
      * @returns The Disposable instance
      */
-    useDisposable: <T extends Disposable | AsyncDisposable>(key: string, factory: () => T) => T;
+    useDisposable: <T extends Disposable | AsyncDisposable>(key: string, factory: () => T, deps?: readonly unknown[]) => T;
     /**
      * Creates a state object from an existing observable value.
      *

package/esm/models/render-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-options.d.ts","sourceRoot":"","sources":["../../src/models/render-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,IAAI;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,EAAE,YAAY,SAAS,WAAW,GAAG,WAAW,IAAI;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,CAAA;IACrD,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAEtE;;;;;OAKG;IACH,aAAa,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,eAAe,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAE3F;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,aAAa,EAAE,CAAC,CAAC,EACf,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAA;KAAE,KACrE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAEhD;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAE1F;;;;;OAKG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAEhG;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,CAAC,EAChB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,WAAW,CAAC,EAAE,OAAO,KAClB,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;CACjD,CAAA"}
+{"version":3,"file":"render-options.d.ts","sourceRoot":"","sources":["../../src/models/render-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,IAAI;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,EAAE,YAAY,SAAS,WAAW,GAAG,WAAW,IAAI;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,CAAA;IACrD,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAEtE;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,eAAe,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,CAAC,CAAA;IAEtH;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,aAAa,EAAE,CAAC,CAAC,EACf,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAA;KAAE,KACrE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAEhD;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAE1F;;;;;OAKG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAEhG;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,CAAC,EAChB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,WAAW,CAAC,EAAE,OAAO,KAClB,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;CACjD,CAAA"}

package/esm/services/index.d.ts

@@ -2,4 +2,5 @@ export * from './location-service.js';
 export * from './route-match-service.js';
 export * from './route-meta-utils.js';
 export * from './screen-service.js';
+export * from './spatial-navigation-service.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iCAAiC,CAAA"}

package/esm/services/index.js

@@ -2,4 +2,5 @@ export * from './location-service.js';
 export * from './route-match-service.js';
 export * from './route-meta-utils.js';
 export * from './screen-service.js';
+export * from './spatial-navigation-service.js';
 //# sourceMappingURL=index.js.map

package/esm/services/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iCAAiC,CAAA"}

package/esm/services/spatial-navigation-service.d.ts

@@ -0,0 +1,88 @@
+import { type Injector } 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;
+};
+/**
+ * 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.getInstance(SpatialNavigationService)
+ *
+ * // Disable during video playback
+ * spatialNav.enabled.setValue(false)
+ *
+ * // Re-enable
+ * spatialNav.enabled.setValue(true)
+ * ```
+ */
+export declare class SpatialNavigationService implements Disposable {
+    /** Toggle spatial navigation on/off at runtime */
+    readonly enabled: ObservableValue<boolean>;
+    /** The currently active section name (from data-nav-section), or null if none */
+    readonly activeSection: ObservableValue<string | null>;
+    /** Remembered last-focused element per section for focus restoration */
+    private readonly focusMemory;
+    private readonly focusTrapStack;
+    private readonly focusableSelector;
+    private readonly crossSectionNavigation;
+    private readonly backspaceGoesBack;
+    private readonly escapeGoesToParentSection;
+    constructor(options?: SpatialNavigationOptions);
+    [Symbol.dispose](): void;
+    /**
+     * Push a focus trap onto the stack. While the trap is active, cross-section
+     * navigation is blocked and `activeSection` is locked to `sectionName`.
+     * Supports nesting — only the topmost trap is enforced.
+     */
+    pushFocusTrap(sectionName: string): void;
+    /**
+     * Remove a focus trap from the stack. If other traps remain, the topmost
+     * one becomes active. Otherwise `activeSection` reverts to `previousSection`.
+     */
+    popFocusTrap(sectionName: string, previousSection?: string | null): void;
+    private get activeTrap();
+    /** Programmatically move focus in a direction */
+    moveFocus(direction: SpatialDirection): void;
+    /** Programmatically activate (click) the currently focused element */
+    activateFocused(): void;
+    private handleKeyDown;
+    private focusFirstElement;
+    private findContainingSection;
+    private isVisibleInScrollContainers;
+    private getFocusableCandidates;
+    private findNearestInDirection;
+    private navigateCrossSection;
+    private storeFocusMemory;
+    private moveToParentSection;
+}
+/**
+ * Configures spatial navigation options before the service is first instantiated.
+ * Must be called **before** `SpatialNavigationService` is first resolved from the injector.
+ * @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

package/esm/services/spatial-navigation-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-navigation-service.d.ts","sourceRoot":"","sources":["../../src/services/spatial-navigation-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE/D;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,+DAA+D;IAC/D,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,mEAAmE;IACnE,yBAAyB,CAAC,EAAE,OAAO,CAAA;CACpC,CAAA;AAoND;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,wBAAyB,YAAW,UAAU;IACzD,kDAAkD;IAClD,SAAgB,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;IAEjD,iFAAiF;IACjF,SAAgB,aAAa,iCAA2C;IAExE,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAElE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAE9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAS;gBAEvC,OAAO,GAAE,wBAA6B;IAU3C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAQ/B;;;;OAIG;IACI,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK/C;;;OAGG;IACI,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAS/E,OAAO,KAAK,UAAU,GAErB;IAED,iDAAiD;IAC1C,SAAS,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAuCnD,sEAAsE;IAC/D,eAAe,IAAI,IAAI;IAO9B,OAAO,CAAC,aAAa,CAmDpB;IAED,OAAO,CAAC,iBAAiB;IA8BzB,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,2BAA2B;IAuBnC,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,sBAAsB;IAwB9B,OAAO,CAAC,oBAAoB;IA8C5B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,mBAAmB;CAgB5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,QAAQ,EAAE,SAAS,wBAAwB,KAAG,IAOlG,CAAA"}