@tvuikit/scroll-react 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { useScroller } from "./useScroller.js";
+export { useScrollState, type ScrollState } from "./useScrollState.js";
+export { useVirtualRange } from "./useVirtualRange.js";
+export { useScrollNavigation, type UseScrollNavigationOptions } from "./useScrollNavigation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,51 @@
+import { useMemo as i, useEffect as r, useCallback as o, useSyncExternalStore as a, useRef as c } from "react";
+import { createScroller as d, createVirtualizer as g, connectScrollToNavigation as z } from "@tvuikit/scroll";
+function v(e) {
+  const t = i(() => d(e), []);
+  return r(() => () => {
+    t.dispose();
+  }, [t]), t;
+}
+function R(e) {
+  const t = o(
+    (s) => e.subscribe(s),
+    [e]
+  ), n = o(() => e.getSnapshot(), [e]), u = o(() => 0, []);
+  return a(t, n, u), {
+    scrollOffset: e.scrollOffset,
+    focusedIndex: e.focusedIndex,
+    isAnimating: e.isAnimating
+  };
+}
+function p(e, t) {
+  const n = i(
+    () => g(0, e.offsets, e.sizes, e.itemCount, {
+      overscan: t ?? 2
+    }),
+    [e]
+    // intentionally minimal — scroller internals accessed via ref
+  ), u = o(
+    (S) => e.subscribe(S),
+    [e]
+  ), s = o(() => e.getSnapshot(), [e]), f = o(() => 0, []);
+  return a(u, s, f), n.setLayout(e.offsets, e.sizes, e.itemCount), n.setViewportSize(e.viewportSize), n.update(e.scrollOffset);
+}
+function x(e) {
+  const t = c(e.nodeToIndex), n = c(e.onFocusResize);
+  t.current = e.nodeToIndex, n.current = e.onFocusResize, r(() => z(
+    e.scroller,
+    e.navStore,
+    (s) => t.current(s),
+    {
+      onFocusResize: (s) => n.current?.(s) ?? null,
+      scrollToOptions: e.scrollToOptions
+    }
+  ), [e.scroller, e.navStore, e.scrollToOptions]);
+}
+export {
+  x as useScrollNavigation,
+  R as useScrollState,
+  v as useScroller,
+  p as useVirtualRange
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/useScroller.ts","../src/useScrollState.ts","../src/useVirtualRange.ts","../src/useScrollNavigation.ts"],"sourcesContent":["import { useMemo, useEffect } from \"react\";\nimport type { Scroller, ScrollerOptions } from \"@tvuikit/scroll\";\nimport { createScroller } from \"@tvuikit/scroll\";\n\n/**\n * Create and lifecycle-manage a Scroller instance.\n *\n * The scroller is created once on mount and disposed on unmount.\n * Returns a stable reference across renders.\n *\n * @example\n * ```tsx\n * const scroller = useScroller({\n *   axis: \"horizontal\",\n *   viewportSize: 1920,\n *   itemCount: 50,\n *   itemSize: 300,\n *   animation: { tweenTo: gsap.to.bind(gsap) },\n * });\n * ```\n */\nexport function useScroller(options: ScrollerOptions): Scroller {\n  // Create scroller once — options are captured at mount time.\n  // Consumers should use scroller mutation methods for runtime changes.\n  const scroller = useMemo(() => createScroller(options), []); // intentionally empty — options captured at mount\n\n  useEffect(() => {\n    return () => {\n      scroller.dispose();\n    };\n  }, [scroller]);\n\n  return scroller;\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\nimport type { Scroller } from \"@tvuikit/scroll\";\n\nexport type ScrollState = {\n  scrollOffset: number;\n  focusedIndex: number;\n  isAnimating: boolean;\n};\n\n/**\n * Reactively read scroll state from a Scroller using useSyncExternalStore.\n *\n * Re-renders the component when the scroller's version counter changes\n * (on every scroll position update, size change, etc.).\n *\n * @example\n * ```tsx\n * const { scrollOffset, focusedIndex, isAnimating } = useScrollState(scroller);\n * ```\n */\nexport function useScrollState(scroller: Scroller): ScrollState {\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => scroller.subscribe(onStoreChange),\n    [scroller]\n  );\n\n  const getSnapshot = useCallback(() => scroller.getSnapshot(), [scroller]);\n\n  const getServerSnapshot = useCallback(() => 0, []);\n\n  // useSyncExternalStore triggers re-render when version changes\n  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n\n  // Read current values directly from the scroller (guaranteed fresh after version bump)\n  return {\n    scrollOffset: scroller.scrollOffset,\n    focusedIndex: scroller.focusedIndex,\n    isAnimating: scroller.isAnimating,\n  };\n}\n","import { useCallback, useMemo, useSyncExternalStore } from \"react\";\nimport type { Scroller, VirtualRange } from \"@tvuikit/scroll\";\nimport { createVirtualizer } from \"@tvuikit/scroll\";\n\n/**\n * Reactively compute the visible item range from a Scroller.\n *\n * Creates an internal Virtualizer and updates it whenever the scroller's\n * state changes. Returns a VirtualRange with start/end indices and overscan.\n *\n * @example\n * ```tsx\n * const range = useVirtualRange(scroller, 3);\n * for (let i = range.overscanStart; i < range.overscanEnd; i++) {\n *   renderItem(i);\n * }\n * ```\n */\nexport function useVirtualRange(scroller: Scroller, overscan?: number): VirtualRange {\n  const virtualizer = useMemo(\n    () =>\n      createVirtualizer(0, scroller.offsets, scroller.sizes, scroller.itemCount, {\n        overscan: overscan ?? 2,\n      }),\n    [scroller] // intentionally minimal — scroller internals accessed via ref\n  );\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => scroller.subscribe(onStoreChange),\n    [scroller]\n  );\n\n  const getSnapshot = useCallback(() => scroller.getSnapshot(), [scroller]);\n  const getServerSnapshot = useCallback(() => 0, []);\n\n  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n\n  // Sync virtualizer layout with scroller state\n  virtualizer.setLayout(scroller.offsets, scroller.sizes, scroller.itemCount);\n  virtualizer.setViewportSize(scroller.viewportSize);\n\n  // Compute and return visible range\n  return virtualizer.update(scroller.scrollOffset);\n}\n","import { useEffect, useRef } from \"react\";\nimport type { Scroller, ScrollToOptions } from \"@tvuikit/scroll\";\nimport { connectScrollToNavigation } from \"@tvuikit/scroll\";\n\n/**\n * Structural type for the NavigationStore's event interface.\n * Avoids hard dependency on @tvuikit/navigation in this package.\n */\ntype NavigationStoreLike = {\n  addEventListener(\n    type: string,\n    listener: (event: Event) => void,\n    options?: AddEventListenerOptions\n  ): void;\n  removeEventListener(\n    type: string,\n    listener: (event: Event) => void,\n    options?: EventListenerOptions\n  ): void;\n};\n\nexport type UseScrollNavigationOptions = {\n  /** The scroller to drive. */\n  scroller: Scroller;\n  /** The navigation store to listen to. */\n  navStore: NavigationStoreLike;\n  /** Maps a navigation node ID to a scroller item index. Return null for unrelated nodes. */\n  nodeToIndex: (nodeId: string) => number | null;\n  /** Called when an item receives focus. Return new size for resize-on-focus, or null. */\n  onFocusResize?: (index: number) => { size: number } | null;\n  /** Override scroll animation options for focus-driven scrolls. */\n  scrollToOptions?: ScrollToOptions;\n};\n\n/**\n * Connect navigation focus events to a scroller.\n *\n * When the navigation system focuses a node that maps to a scroller item,\n * the scroller automatically scrolls to that item.\n *\n * @example\n * ```tsx\n * useScrollNavigation({\n *   scroller,\n *   navStore: store,\n *   nodeToIndex: (id) => {\n *     if (!id.startsWith(\"pixi:tile-\")) return null;\n *     return parseInt(id.slice(\"pixi:tile-\".length), 10);\n *   },\n * });\n * ```\n */\nexport function useScrollNavigation(options: UseScrollNavigationOptions): void {\n  // Use refs for callbacks to avoid reconnecting on every render\n  const nodeToIndexRef = useRef(options.nodeToIndex);\n  const onFocusResizeRef = useRef(options.onFocusResize);\n  nodeToIndexRef.current = options.nodeToIndex;\n  onFocusResizeRef.current = options.onFocusResize;\n\n  useEffect(() => {\n    const disconnect = connectScrollToNavigation(\n      options.scroller,\n      options.navStore,\n      (nodeId) => nodeToIndexRef.current(nodeId),\n      {\n        onFocusResize: (index) => onFocusResizeRef.current?.(index) ?? null,\n        scrollToOptions: options.scrollToOptions,\n      }\n    );\n\n    return disconnect;\n  }, [options.scroller, options.navStore, options.scrollToOptions]);\n}\n"],"names":["useScroller","options","scroller","useMemo","createScroller","useEffect","useScrollState","subscribe","useCallback","onStoreChange","getSnapshot","getServerSnapshot","useSyncExternalStore","useVirtualRange","overscan","virtualizer","createVirtualizer","useScrollNavigation","nodeToIndexRef","useRef","onFocusResizeRef","connectScrollToNavigation","nodeId","index"],"mappings":";;AAqBO,SAASA,EAAYC,GAAoC;AAG9D,QAAMC,IAAWC,EAAQ,MAAMC,EAAeH,CAAO,GAAG,CAAA,CAAE;AAE1D,SAAAI,EAAU,MACD,MAAM;AACX,IAAAH,EAAS,QAAA;AAAA,EACX,GACC,CAACA,CAAQ,CAAC,GAENA;AACT;ACbO,SAASI,EAAeJ,GAAiC;AAC9D,QAAMK,IAAYC;AAAA,IAChB,CAACC,MAA8BP,EAAS,UAAUO,CAAa;AAAA,IAC/D,CAACP,CAAQ;AAAA,EAAA,GAGLQ,IAAcF,EAAY,MAAMN,EAAS,eAAe,CAACA,CAAQ,CAAC,GAElES,IAAoBH,EAAY,MAAM,GAAG,CAAA,CAAE;AAGjD,SAAAI,EAAqBL,GAAWG,GAAaC,CAAiB,GAGvD;AAAA,IACL,cAAcT,EAAS;AAAA,IACvB,cAAcA,EAAS;AAAA,IACvB,aAAaA,EAAS;AAAA,EAAA;AAE1B;ACrBO,SAASW,EAAgBX,GAAoBY,GAAiC;AACnF,QAAMC,IAAcZ;AAAA,IAClB,MACEa,EAAkB,GAAGd,EAAS,SAASA,EAAS,OAAOA,EAAS,WAAW;AAAA,MACzE,UAAUY,KAAY;AAAA,IAAA,CACvB;AAAA,IACH,CAACZ,CAAQ;AAAA;AAAA,EAAA,GAGLK,IAAYC;AAAA,IAChB,CAACC,MAA8BP,EAAS,UAAUO,CAAa;AAAA,IAC/D,CAACP,CAAQ;AAAA,EAAA,GAGLQ,IAAcF,EAAY,MAAMN,EAAS,eAAe,CAACA,CAAQ,CAAC,GAClES,IAAoBH,EAAY,MAAM,GAAG,CAAA,CAAE;AAEjD,SAAAI,EAAqBL,GAAWG,GAAaC,CAAiB,GAG9DI,EAAY,UAAUb,EAAS,SAASA,EAAS,OAAOA,EAAS,SAAS,GAC1Ea,EAAY,gBAAgBb,EAAS,YAAY,GAG1Ca,EAAY,OAAOb,EAAS,YAAY;AACjD;ACSO,SAASe,EAAoBhB,GAA2C;AAE7E,QAAMiB,IAAiBC,EAAOlB,EAAQ,WAAW,GAC3CmB,IAAmBD,EAAOlB,EAAQ,aAAa;AACrD,EAAAiB,EAAe,UAAUjB,EAAQ,aACjCmB,EAAiB,UAAUnB,EAAQ,eAEnCI,EAAU,MACWgB;AAAA,IACjBpB,EAAQ;AAAA,IACRA,EAAQ;AAAA,IACR,CAACqB,MAAWJ,EAAe,QAAQI,CAAM;AAAA,IACzC;AAAA,MACE,eAAe,CAACC,MAAUH,EAAiB,UAAUG,CAAK,KAAK;AAAA,MAC/D,iBAAiBtB,EAAQ;AAAA,IAAA;AAAA,EAC3B,GAID,CAACA,EAAQ,UAAUA,EAAQ,UAAUA,EAAQ,eAAe,CAAC;AAClE;"}

package/dist/useScrollNavigation.d.ts

@@ -0,0 +1,44 @@
+import type { Scroller, ScrollToOptions } from "@tvuikit/scroll";
+/**
+ * Structural type for the NavigationStore's event interface.
+ * Avoids hard dependency on @tvuikit/navigation in this package.
+ */
+type NavigationStoreLike = {
+    addEventListener(type: string, listener: (event: Event) => void, options?: AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: (event: Event) => void, options?: EventListenerOptions): void;
+};
+export type UseScrollNavigationOptions = {
+    /** The scroller to drive. */
+    scroller: Scroller;
+    /** The navigation store to listen to. */
+    navStore: NavigationStoreLike;
+    /** Maps a navigation node ID to a scroller item index. Return null for unrelated nodes. */
+    nodeToIndex: (nodeId: string) => number | null;
+    /** Called when an item receives focus. Return new size for resize-on-focus, or null. */
+    onFocusResize?: (index: number) => {
+        size: number;
+    } | null;
+    /** Override scroll animation options for focus-driven scrolls. */
+    scrollToOptions?: ScrollToOptions;
+};
+/**
+ * Connect navigation focus events to a scroller.
+ *
+ * When the navigation system focuses a node that maps to a scroller item,
+ * the scroller automatically scrolls to that item.
+ *
+ * @example
+ * ```tsx
+ * useScrollNavigation({
+ *   scroller,
+ *   navStore: store,
+ *   nodeToIndex: (id) => {
+ *     if (!id.startsWith("pixi:tile-")) return null;
+ *     return parseInt(id.slice("pixi:tile-".length), 10);
+ *   },
+ * });
+ * ```
+ */
+export declare function useScrollNavigation(options: UseScrollNavigationOptions): void;
+export {};
+//# sourceMappingURL=useScrollNavigation.d.ts.map

package/dist/useScrollNavigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollNavigation.d.ts","sourceRoot":"","sources":["../src/useScrollNavigation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGjE;;;GAGG;AACH,KAAK,mBAAmB,GAAG;IACzB,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAChC,OAAO,CAAC,EAAE,uBAAuB,GAChC,IAAI,CAAC;IACR,mBAAmB,CACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAChC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,6BAA6B;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,yCAAyC;IACzC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,2FAA2F;IAC3F,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC/C,wFAAwF;IACxF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3D,kEAAkE;IAClE,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,IAAI,CAoB7E"}

package/dist/useScrollState.d.ts

@@ -0,0 +1,19 @@
+import type { Scroller } from "@tvuikit/scroll";
+export type ScrollState = {
+    scrollOffset: number;
+    focusedIndex: number;
+    isAnimating: boolean;
+};
+/**
+ * Reactively read scroll state from a Scroller using useSyncExternalStore.
+ *
+ * Re-renders the component when the scroller's version counter changes
+ * (on every scroll position update, size change, etc.).
+ *
+ * @example
+ * ```tsx
+ * const { scrollOffset, focusedIndex, isAnimating } = useScrollState(scroller);
+ * ```
+ */
+export declare function useScrollState(scroller: Scroller): ScrollState;
+//# sourceMappingURL=useScrollState.d.ts.map

package/dist/useScrollState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollState.d.ts","sourceRoot":"","sources":["../src/useScrollState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAmB9D"}

package/dist/useScroller.d.ts

@@ -0,0 +1,20 @@
+import type { Scroller, ScrollerOptions } from "@tvuikit/scroll";
+/**
+ * Create and lifecycle-manage a Scroller instance.
+ *
+ * The scroller is created once on mount and disposed on unmount.
+ * Returns a stable reference across renders.
+ *
+ * @example
+ * ```tsx
+ * const scroller = useScroller({
+ *   axis: "horizontal",
+ *   viewportSize: 1920,
+ *   itemCount: 50,
+ *   itemSize: 300,
+ *   animation: { tweenTo: gsap.to.bind(gsap) },
+ * });
+ * ```
+ */
+export declare function useScroller(options: ScrollerOptions): Scroller;
+//# sourceMappingURL=useScroller.d.ts.map

package/dist/useScroller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScroller.d.ts","sourceRoot":"","sources":["../src/useScroller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAY9D"}

package/dist/useVirtualRange.d.ts

@@ -0,0 +1,17 @@
+import type { Scroller, VirtualRange } from "@tvuikit/scroll";
+/**
+ * Reactively compute the visible item range from a Scroller.
+ *
+ * Creates an internal Virtualizer and updates it whenever the scroller's
+ * state changes. Returns a VirtualRange with start/end indices and overscan.
+ *
+ * @example
+ * ```tsx
+ * const range = useVirtualRange(scroller, 3);
+ * for (let i = range.overscanStart; i < range.overscanEnd; i++) {
+ *   renderItem(i);
+ * }
+ * ```
+ */
+export declare function useVirtualRange(scroller: Scroller, overscan?: number): VirtualRange;
+//# sourceMappingURL=useVirtualRange.d.ts.map

package/dist/useVirtualRange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualRange.d.ts","sourceRoot":"","sources":["../src/useVirtualRange.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG9D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAyBnF"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tvuikit/scroll-react",
+  "version": "0.2.0",
+  "description": "React hooks for @tvuikit/scroll. useSyncExternalStore-based, cross-reconciler compatible.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "TVKit Team",
+  "homepage": "https://tvkit.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dobreadi/tvkit.git",
+    "directory": "packages/scroll-react"
+  },
+  "bugs": {
+    "url": "https://github.com/dobreadi/tvkit/issues"
+  },
+  "keywords": [
+    "tv",
+    "scroll",
+    "react",
+    "hooks",
+    "tvkit"
+  ],
+  "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/scroll": "^0.1.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@tvuikit/scroll": "file:../scroll"
+  },
+  "scripts": {
+    "build": "vite build && npm run build:types",
+    "build:types": "tsc -p tsconfig.types.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}