@tvuikit/navigation-react 0.1.0

package/dist/react/useCustomFocusable.d.ts

@@ -0,0 +1,76 @@
+import type { NodeId, Rect, NavigationStore } from "@tvuikit/navigation";
+export type UseCustomFocusableOptions = {
+    /**
+     * The navigation store instance.
+     * Required - pass the store directly to avoid cross-reconciler context issues.
+     */
+    store: NavigationStore;
+    /**
+     * Source name for this focusable (e.g., "pixi", "three").
+     * Default: "custom"
+     */
+    source?: string;
+    /**
+     * Unique identifier for this focusable node (local ID, without source prefix).
+     * Will be namespaced as "source:id" internally.
+     */
+    id: NodeId;
+    /**
+     * Bounding rectangle in viewport coordinates.
+     * Must be in the same coordinate space as DOM elements (client coordinates).
+     * For canvas/WebGL elements, add the canvas offset to local coordinates.
+     */
+    rect: Rect;
+    /**
+     * Optional focus group id for this node.
+     * If not provided, attempts to inherit from the nearest FocusGroup context.
+     */
+    groupId?: string | null;
+    /**
+     * If true, element cannot receive focus.
+     */
+    disabled?: boolean;
+    /**
+     * Called when this element gains focus.
+     */
+    onFocus?: () => void;
+    /**
+     * Called when this element loses focus.
+     */
+    onBlur?: () => void;
+};
+/**
+ * Hook to register a custom (non-DOM) element as focusable and track its focus state.
+ *
+ * Use this for elements rendered via WebGL, Canvas, or other non-DOM technologies.
+ * Unlike `useFocusable`, you must provide the bounding rect manually and pass
+ * the store directly (to avoid cross-reconciler context issues).
+ *
+ * Uses `useSyncExternalStore` for tear-free focus state updates,
+ * compatible with React concurrent features.
+ *
+ * @example
+ * ```tsx
+ * function PixiTile({ store, id, x, y, canvasOffset }: Props) {
+ *   const rect = useMemo(() => ({
+ *     x: canvasOffset.x + x,
+ *     y: canvasOffset.y + y,
+ *     w: 200,
+ *     h: 150,
+ *   }), [canvasOffset.x, canvasOffset.y, x, y]);
+ *
+ *   const { focused } = useCustomFocusable({
+ *     store,
+ *     source: "pixi",
+ *     id,
+ *     rect,
+ *   });
+ *
+ *   return <Graphics draw={(g) => drawTile(g, focused)} />;
+ * }
+ * ```
+ */
+export declare function useCustomFocusable(opts: UseCustomFocusableOptions): {
+    focused: boolean;
+};
+//# sourceMappingURL=useCustomFocusable.d.ts.map

package/dist/react/useCustomFocusable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCustomFocusable.d.ts","sourceRoot":"","sources":["../../src/react/useCustomFocusable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGzE,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,KAAK,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CA+DxF"}

package/dist/react/useFocusEvents.d.ts

@@ -0,0 +1,39 @@
+import type { NavigationEventMap, NavigationStore } from "@tvuikit/navigation";
+type EventType = keyof NavigationEventMap;
+/**
+ * Handler map for subscribing to multiple events at once.
+ */
+export type FocusEventHandlers = {
+    [K in EventType]?: (detail: NavigationEventMap[K]["detail"]) => void;
+};
+type UseFocusEventsOptions = {
+    store?: NavigationStore;
+};
+/**
+ * Subscribe to a single navigation event.
+ *
+ * @example
+ * ```tsx
+ * useFocusEvents("focus", ({ nodeId }) => {
+ *   console.log("Focused:", nodeId);
+ * });
+ * ```
+ */
+export declare function useFocusEvents<T extends EventType>(type: T, handler: (detail: NavigationEventMap[T]["detail"]) => void, options?: UseFocusEventsOptions): void;
+/**
+ * Subscribe to multiple navigation events at once.
+ *
+ * @example
+ * ```tsx
+ * useFocusEvents({
+ *   focus: ({ nodeId }) => console.log("Focused:", nodeId),
+ *   move: ({ from, to, direction }) => console.log("Moved:", direction),
+ *   reject: ({ reason }) => {
+ *     if (reason === "boundary-blocked") playBoundarySound();
+ *   },
+ * });
+ * ```
+ */
+export declare function useFocusEvents(handlers: FocusEventHandlers, options?: UseFocusEventsOptions): void;
+export {};
+//# sourceMappingURL=useFocusEvents.d.ts.map

package/dist/react/useFocusEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusEvents.d.ts","sourceRoot":"","sources":["../../src/react/useFocusEvents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG/E,KAAK,SAAS,GAAG,MAAM,kBAAkB,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;KAC9B,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI;CACrE,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,EAChD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI,EAC1D,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAAC;AAER;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAAC"}

package/dist/react/useFocusable.d.ts

@@ -0,0 +1,44 @@
+import type { NodeId } from "@tvuikit/navigation";
+export type UseFocusableOptions = {
+    id: NodeId;
+    /**
+     * Optional focus group id for this node.
+     * If not provided, inherits from the nearest FocusGroup context.
+     */
+    groupId?: string | null;
+    /**
+     * If true, element cannot receive focus.
+     */
+    disabled?: boolean;
+    /**
+     * Called when this element gains focus.
+     */
+    onFocus?: () => void;
+    /**
+     * Called when this element loses focus.
+     */
+    onBlur?: () => void;
+};
+/**
+ * Hook to register a DOM element as focusable and track its focus state.
+ *
+ * Uses `useSyncExternalStore` for tear-free focus state updates,
+ * compatible with React concurrent features.
+ *
+ * @example
+ * ```tsx
+ * function Button({ id }: { id: string }) {
+ *   const { ref, focused } = useFocusable({ id });
+ *   return (
+ *     <button ref={ref} className={focused ? "focused" : ""}>
+ *       Click me
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFocusable(opts: UseFocusableOptions): {
+    ref: (el: HTMLElement | null) => void;
+    focused: boolean;
+};
+//# sourceMappingURL=useFocusable.d.ts.map

package/dist/react/useFocusable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusable.d.ts","sourceRoot":"","sources":["../../src/react/useFocusable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAIlD,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB;cAgD7C,WAAW,GAAG,IAAI;;EAsB1B"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tvuikit/navigation-react",
+  "version": "0.1.0",
+  "description": "React integration for TVKit Navigation. Hooks, components, and providers for spatial navigation.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "TVKit Team",
+  "homepage": "https://github.com/tvkit/navigation#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tvkit/navigation.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/tvkit/navigation/issues"
+  },
+  "keywords": [
+    "tv",
+    "navigation",
+    "react",
+    "hooks",
+    "focus",
+    "spatial",
+    "tvkit",
+    "smart-tv"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@tvuikit/navigation": "^0.1.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tvuikit/navigation": "file:../core"
+  },
+  "scripts": {
+    "build": "vite build && npm run build:types",
+    "build:types": "tsc -p tsconfig.types.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}
+
+