ts-spatial-navigation 1.0.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Spatial Navigation Type Definitions
+ * Following Interface Segregation Principle (ISP)
+ */
+import type { EnterToValue, RestrictModeValue } from './constants';
+/**
+ * Navigation direction
+ */
+export type Direction = 'up' | 'down' | 'left' | 'right';
+/**
+ * Selector type - can be CSS selector string, NodeList, or HTMLElement
+ */
+export type Selector = string | NodeList | HTMLElement | HTMLElement[];
+/**
+ * Extended selector - includes @sectionId syntax
+ */
+export type ExtendedSelector = Selector | `@${string}`;
+/**
+ * Point in 2D space
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Rectangle with center point calculation
+ */
+export interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+    element: HTMLElement;
+    center: {
+        x: number;
+        y: number;
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    };
+}
+/**
+ * Distance calculation function
+ */
+export type DistanceFunction = (rect: Rect) => number;
+/**
+ * Collection of distance functions for navigation
+ */
+export interface DistanceFunctions {
+    nearPlumbLineIsBetter: DistanceFunction;
+    nearHorizonIsBetter: DistanceFunction;
+    nearTargetLeftIsBetter: DistanceFunction;
+    nearTargetTopIsBetter: DistanceFunction;
+    topIsBetter: DistanceFunction;
+    bottomIsBetter: DistanceFunction;
+    leftIsBetter: DistanceFunction;
+    rightIsBetter: DistanceFunction;
+}
+/**
+ * Priority group with distance functions for sorting
+ */
+export interface Priority {
+    group: Rect[];
+    distance: DistanceFunction[];
+}
+/**
+ * Array of priority groups
+ */
+export type Priorities = Priority[];
+/**
+ * Basic section identification
+ */
+export interface SectionIdentity {
+    /**
+     * Unique identifier for the section
+     */
+    id?: string;
+    /**
+     * CSS selector for navigable elements in this section
+     */
+    selector?: string;
+}
+/**
+ * Navigation behavior configuration
+ */
+export interface NavigationBehavior {
+    /**
+     * Only allow navigation in cardinal directions (no diagonal)
+     * @default false
+     */
+    straightOnly?: boolean;
+    /**
+     * Threshold for straight direction overlap (0 to 1)
+     * @default 0.5
+     */
+    straightOverlapThreshold?: number;
+    /**
+     * Remember previously focused element when navigating back
+     * @default false
+     */
+    rememberSource?: boolean;
+}
+/**
+ * Section transition configuration
+ */
+export interface SectionTransition {
+    /**
+     * Behavior when entering this section
+     * - 'last-focused': Focus the last focused element
+     * - 'default-element': Focus the default element
+     * - '': Natural focus behavior
+     * @default ''
+     */
+    enterTo?: EnterToValue | 'last-focused' | 'default-element' | '';
+    /**
+     * Configuration for leaving the section in specific directions
+     */
+    leaveFor?: Partial<LeaveFor>;
+    /**
+     * How to restrict navigation at section boundaries
+     * - 'self-first': Prefer staying in section
+     * - 'self-only': Never leave section via keyboard
+     * - 'none': No restriction
+     * @default 'self-first'
+     */
+    restrict?: RestrictModeValue | 'self-first' | 'self-only' | 'none';
+}
+/**
+ * LeaveFor configuration - what to focus when leaving in each direction
+ */
+export interface LeaveFor {
+    up?: string | HTMLElement;
+    down?: string | HTMLElement;
+    left?: string | HTMLElement;
+    right?: string | HTMLElement;
+}
+/**
+ * Filter configuration for navigable elements
+ */
+export interface FilterConfig {
+    /**
+     * Custom filter function for navigable elements
+     * Return false to exclude an element from navigation
+     */
+    navigableFilter?: NavigableFilter;
+    /**
+     * Elements matching this selector will not have tabindex modified
+     * @default 'a, input, select, textarea, button, iframe, [contentEditable=true]'
+     */
+    tabIndexIgnoreList?: string;
+    /**
+     * Whether to ignore hidden elements
+     * @default false
+     */
+    ignoreHidden?: boolean;
+}
+/**
+ * Navigable filter function signature
+ */
+export type NavigableFilter = (element: HTMLElement, sectionId: string) => boolean;
+/**
+ * Section state (internal)
+ */
+export interface SectionState {
+    /**
+     * Whether this section is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Default element to focus when entering section
+     */
+    defaultElement?: HTMLElement | string;
+    /**
+     * Last focused element in this section
+     */
+    lastFocusedElement?: HTMLElement;
+    /**
+     * Previous navigation state for rememberSource
+     */
+    previous?: PreviousFocus;
+}
+/**
+ * Previous focus state for rememberSource feature
+ */
+export interface PreviousFocus {
+    target: HTMLElement;
+    destination: HTMLElement;
+    reverse: Direction;
+}
+/**
+ * Full section configuration
+ * Combines all configuration interfaces
+ */
+export interface SectionConfig extends SectionIdentity, NavigationBehavior, SectionTransition, FilterConfig, SectionState {
+}
+/**
+ * Configuration for adding a new section
+ * All properties optional except selector
+ */
+export interface AddSectionConfig extends Partial<SectionConfig> {
+    selector: string;
+}
+/**
+ * Global configuration
+ */
+export interface GlobalConfig extends Omit<SectionConfig, 'id' | 'lastFocusedElement' | 'previous'> {
+    /**
+     * Prefix for auto-generated section IDs
+     * @default 'section-'
+     */
+    sectionPrefix?: string;
+    /**
+     * Prefix for custom events
+     * @default 'sn:'
+     */
+    eventPrefix?: string;
+}
+/**
+ * Legacy Config type for backwards compatibility
+ * @deprecated Use SectionConfig instead
+ */
+export type Config = SectionConfig;
+/**
+ * Detail object for spatial navigation events
+ */
+export interface SpatialEventDetail {
+    /**
+     * Direction of navigation
+     */
+    direction?: Direction;
+    /**
+     * Current section ID
+     */
+    id?: string;
+    /**
+     * Next section ID (for cross-section navigation)
+     */
+    nextId?: string;
+    /**
+     * Element that will receive focus
+     */
+    nextElement?: HTMLElement;
+    /**
+     * Element that had focus before
+     */
+    previousElement?: HTMLElement;
+    /**
+     * Whether triggered by native focus events
+     */
+    native?: boolean;
+    /**
+     * What caused this navigation
+     */
+    cause?: 'keydown' | 'api';
+}
+/**
+ * Spatial navigation custom event
+ */
+export interface SpatialEvent extends CustomEvent<SpatialEventDetail> {
+    type: `sn:${string}`;
+}
+/**
+ * Section store - Map of section ID to configuration
+ */
+export type SectionStore = Map<string, SectionConfig>;
+/**
+ * Navigation state
+ */
+export interface NavigationState {
+    ready: boolean;
+    paused: boolean;
+    duringFocusChange: boolean;
+    sections: SectionStore;
+    sectionCount: number;
+    defaultSectionId: string;
+    lastSectionId: string;
+    idPool: number;
+}
+/**
+ * Deep partial type
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Make specific properties required
+ */
+export type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+/**
+ * Extract non-undefined properties
+ */
+export type NonUndefined<T> = T extends undefined ? never : T;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Spatial Navigation Type Definitions
+ * Following Interface Segregation Principle (ISP)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "ts-spatial-navigation",
+  "version": "1.0.0-beta.1",
+  "description": "A TypeScript library for spatial navigation in Smart TV applications",
+  "author": "Rodrigo França <rodrigo@example.com>",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rodrigofranca/ts-spatial-navigation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rodrigofranca/ts-spatial-navigation/issues"
+  },
+  "homepage": "https://github.com/rodrigofranca/ts-spatial-navigation#readme",
+  "keywords": [
+    "spatial-navigation",
+    "smart-tv",
+    "tv",
+    "navigation",
+    "focus",
+    "keyboard-navigation",
+    "typescript",
+    "webos",
+    "tizen",
+    "android-tv",
+    "fire-tv",
+    "arrow-keys"
+  ],
+  "type": "module",
+  "main": "./dist/spatial-navigation.js",
+  "module": "./dist/spatial-navigation.js",
+  "types": "./dist/spatial-navigation.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/spatial-navigation.d.ts",
+      "import": "./dist/spatial-navigation.js",
+      "default": "./dist/spatial-navigation.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./geometry": {
+      "types": "./dist/geometry.d.ts",
+      "import": "./dist/geometry.js"
+    },
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "import": "./dist/constants.js"
+    },
+    "./strategies": {
+      "types": "./dist/strategies.d.ts",
+      "import": "./dist/strategies.js"
+    },
+    "./state": {
+      "types": "./dist/state.d.ts",
+      "import": "./dist/state.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "@vitest/ui": "^4.0.18",
+    "happy-dom": "^20.5.0",
+    "typescript": "^4.9.5",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "build:clean": "rm -rf dist && tsc --build --force",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit"
+  }
+}