@amazon-devices/vega-carousel 0.2.1 → 0.2.5

package/dist/CarouselScrollable/native/CarouselNativeLogic.d.ts

@@ -1,5 +1,5 @@
 import { HostComponent, StyleProp, ViewStyle } from 'react-native';
-import { ListOrientation, OnItemBindFunc, OnItemUnbindFunc, OnSelectionChangedCallback } from '../CarouselScrollableTypes';
+import { ListOrientation, ListSelectionStrategy, OnItemBindFunc, OnItemUnbindFunc, OnSelectionChangedCallback } from '../CarouselScrollableTypes';
 import { CarouselNativeHostComponentSelectionChangedEvent, CarouselNativeHostComponentProps } from './CarouselNativeHostComponent';
 import { CarouselDataAdapter, CarouselDataChange, CarouselResolvedDataValues, RenderItemFunc } from '../../CarouselData';
 import { AnyValue } from '../../utils';
@@ -112,6 +112,47 @@ export declare function callReset(hostComponent: HostComponent<CarouselNativeHos
  *         `baseStyle` and a _row_ or _column_ flex direction.
  */
 export declare function addFlexDirectionStyle(baseStyle: StyleProp<ViewStyle>, orientation: ListOrientation): StyleProp<ViewStyle>;
+/**
+ * Resolves how many items {@link getInitialData} should place **before** the
+ * `initialStartIndex` in the initial render window.
+ *
+ * For {@link ListSelectionStrategy.ANCHORED} and
+ * {@link ListSelectionStrategy.NATURAL}, the initial pool is a leading-margin
+ * window, so the back count is simply `numOffsetItems` (the historical
+ * behavior).
+ *
+ * For {@link ListSelectionStrategy.PINNED} the native layer redistributes the
+ * initial pool so the selected item rests at its pin proportion. If JS resolves
+ * a different window than native pins to, the leading pin-window frames native
+ * wants were never sent by JS, so native fires an async `bindTo` roundtrip to
+ * refill them — a visible pop-in on the leading side (VEGATV-116583). To stay
+ * in lockstep this MIRRORS native `computePinnedPoolStart`'s `itemsBefore`
+ * exactly:
+ *
+ *   pool        = min(renderedItemsCount, itemCount)   // native items_.size()
+ *   itemsBefore = clamp(floor(pool * pin), minBefore, maxBefore)
+ *     minBefore = (hasDataBefore && pool > 2) ? 1 : 0
+ *     maxBefore = (hasDataAfter  && pool > 2) ? pool - 2 : pool - 1
+ *
+ * A plain `min(floor(pool*pin), pool-1)` diverges from native at the extremes
+ * (e.g. pool 8 pin 0.9 → JS 7 vs native 6; pin 0.0 mid-list → JS 0 vs native 1),
+ * and that off-by-one frame is exactly the leading frame native would then have
+ * to bind async — the roundtrip this change removes. Center pins already match;
+ * mirroring the clamp closes the extremes.
+ *
+ * @param {ListSelectionStrategy} selectionStrategy The list's selection strategy.
+ * @param {number} renderedItemsCount The configured render window size.
+ * @param {number} numOffsetItems The leading-margin back count used for the
+ *        non-pinned strategies.
+ * @param {number} pinnedFocusOffset The resolved pin proportion (0.0 - 1.0);
+ *        only used when `selectionStrategy` is `PINNED`.
+ * @param {number} initialStartIndex The selected data index at mount (used to
+ *        detect whether data exists before/after, matching native).
+ * @param {number} itemCount Total number of items in the data set.
+ *
+ * @return {number} The number of items to resolve before `initialStartIndex`.
+ */
+export declare function resolveInitialBackCount(selectionStrategy: ListSelectionStrategy, renderedItemsCount: number, numOffsetItems: number, pinnedFocusOffset: number, initialStartIndex: number, itemCount: number): number;
 /**
  * This function is the core logic to retrieve items on the {@link CarouselScrollable}
  * initial render.

package/dist/CarouselScrollable/native/CarouselNativeLogic.js

@@ -5,7 +5,7 @@
  * PROPRIETARY/CONFIDENTIAL. USE IS SUBJECT TO LICENSE TERMS.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.triggerOnItemBindCallback = exports.triggerOnItemUnbindCallback = exports.triggerOnSelectionChangeCallback = exports.getInitialData = exports.addFlexDirectionStyle = exports.callReset = exports.callNativeNotifyDataChange = exports.callNativeSetOverflowItemsVisible = exports.callNativeSetSelectedItem = exports.callNativeEnableInputEvents = void 0;
+exports.triggerOnItemBindCallback = exports.triggerOnItemUnbindCallback = exports.triggerOnSelectionChangeCallback = exports.getInitialData = exports.resolveInitialBackCount = exports.addFlexDirectionStyle = exports.callReset = exports.callNativeNotifyDataChange = exports.callNativeSetOverflowItemsVisible = exports.callNativeSetSelectedItem = exports.callNativeEnableInputEvents = void 0;
 const react_native_1 = require("react-native");
 const CarouselScrollableTypes_1 = require("../CarouselScrollableTypes");
 const CarouselNativeHostComponent_1 = require("./CarouselNativeHostComponent");
@@ -154,6 +154,63 @@ function addFlexDirectionStyle(baseStyle, orientation) {
         : FlexDirectionColumn);
 }
 exports.addFlexDirectionStyle = addFlexDirectionStyle;
+/**
+ * Resolves how many items {@link getInitialData} should place **before** the
+ * `initialStartIndex` in the initial render window.
+ *
+ * For {@link ListSelectionStrategy.ANCHORED} and
+ * {@link ListSelectionStrategy.NATURAL}, the initial pool is a leading-margin
+ * window, so the back count is simply `numOffsetItems` (the historical
+ * behavior).
+ *
+ * For {@link ListSelectionStrategy.PINNED} the native layer redistributes the
+ * initial pool so the selected item rests at its pin proportion. If JS resolves
+ * a different window than native pins to, the leading pin-window frames native
+ * wants were never sent by JS, so native fires an async `bindTo` roundtrip to
+ * refill them — a visible pop-in on the leading side (VEGATV-116583). To stay
+ * in lockstep this MIRRORS native `computePinnedPoolStart`'s `itemsBefore`
+ * exactly:
+ *
+ *   pool        = min(renderedItemsCount, itemCount)   // native items_.size()
+ *   itemsBefore = clamp(floor(pool * pin), minBefore, maxBefore)
+ *     minBefore = (hasDataBefore && pool > 2) ? 1 : 0
+ *     maxBefore = (hasDataAfter  && pool > 2) ? pool - 2 : pool - 1
+ *
+ * A plain `min(floor(pool*pin), pool-1)` diverges from native at the extremes
+ * (e.g. pool 8 pin 0.9 → JS 7 vs native 6; pin 0.0 mid-list → JS 0 vs native 1),
+ * and that off-by-one frame is exactly the leading frame native would then have
+ * to bind async — the roundtrip this change removes. Center pins already match;
+ * mirroring the clamp closes the extremes.
+ *
+ * @param {ListSelectionStrategy} selectionStrategy The list's selection strategy.
+ * @param {number} renderedItemsCount The configured render window size.
+ * @param {number} numOffsetItems The leading-margin back count used for the
+ *        non-pinned strategies.
+ * @param {number} pinnedFocusOffset The resolved pin proportion (0.0 - 1.0);
+ *        only used when `selectionStrategy` is `PINNED`.
+ * @param {number} initialStartIndex The selected data index at mount (used to
+ *        detect whether data exists before/after, matching native).
+ * @param {number} itemCount Total number of items in the data set.
+ *
+ * @return {number} The number of items to resolve before `initialStartIndex`.
+ */
+function resolveInitialBackCount(selectionStrategy, renderedItemsCount, numOffsetItems, pinnedFocusOffset, initialStartIndex, itemCount) {
+    if (selectionStrategy !== CarouselScrollableTypes_1.ListSelectionStrategy.PINNED) {
+        return numOffsetItems;
+    }
+    // Pool = the number of frames native actually renders (native items_.size()).
+    const pool = Math.min(renderedItemsCount, itemCount);
+    const rawItemsBefore = Math.floor(pool * pinnedFocusOffset);
+    const hasDataBefore = initialStartIndex > 0;
+    const hasDataAfter = initialStartIndex < itemCount - 1;
+    // The pool > 2 guard matches native (prevents an inverted [minBefore, maxBefore] range for
+    // tiny pools, i.e. minBefore > maxBefore).
+    const minBefore = hasDataBefore && pool > 2 ? 1 : 0;
+    const maxBefore = hasDataAfter && pool > 2 ? pool - 2 : pool - 1;
+    // std::clamp(v, lo, hi) == min(max(v, lo), hi)
+    return Math.min(Math.max(rawItemsBefore, minBefore), maxBefore);
+}
+exports.resolveInitialBackCount = resolveInitialBackCount;
 /**
  * This function is the core logic to retrieve items on the {@link CarouselScrollable}
  * initial render.

package/dist/CarouselScrollable/native/CarouselNativeWrapper.js

@@ -51,10 +51,21 @@ function CarouselNativeInner(rawProps, ref) {
     const dataAdapter = (0, CarouselScrollableProps_1.getDataAdapter)(props);
     const hostRef = react_1.default.useRef(null);
     const [childrenStates] = react_1.default.useState(new Map());
-    const { style, uniqueId, initialStartIndex, orientation, renderedItemsCount, numOffsetItems, showSelectionBorder, selectionBorderStyle, selectionBorderStrategy, focusedItemScaleFactor, pressedItemScaleFactor, shiftItemsOnSelection, renderItem, onItemBind, onItemUnbind, onSelectionChanged, } = props;
+    const { style, uniqueId, initialStartIndex, orientation, renderedItemsCount, numOffsetItems, selectionStrategy, pinnedFocusOffset, showSelectionBorder, selectionBorderStyle, selectionBorderStrategy, focusedItemScaleFactor, pressedItemScaleFactor, shiftItemsOnSelection, renderItem, onItemBind, onItemUnbind, onSelectionChanged, } = props;
     const initialStartIndexInternal = react_1.default.useMemo(() => initialStartIndex < dataAdapter.getItemCount()
         ? initialStartIndex
         : Math.max(0, dataAdapter.getItemCount() - 1), [initialStartIndex, dataAdapter]);
+    // For PINNED, resolve the same pin-centered window native binds to on mount so
+    // the leading pin-window frames are already in initialData and native never has
+    // to fire an async bindTo roundtrip to refill them (VEGATV-116583).
+    const initialBackCount = react_1.default.useMemo(() => (0, CarouselNativeLogic_1.resolveInitialBackCount)(selectionStrategy, renderedItemsCount, numOffsetItems, pinnedFocusOffset, initialStartIndexInternal, dataAdapter.getItemCount()), [
+        selectionStrategy,
+        renderedItemsCount,
+        numOffsetItems,
+        pinnedFocusOffset,
+        initialStartIndexInternal,
+        dataAdapter,
+    ]);
     // Activation animations on the native layer assume pressedItemScaleFactor is based on the unselected dimensions of an item.
     // However, the prop for this wrapper is documented to be based on the selected dimensions to better align with specs given by BXT.
     // This means that if a partner passes an pressedItemScaleFactor of 0.94 and a focusedItemScaleFactor of 1.4, when an item is pressed it should
@@ -86,13 +97,13 @@ function CarouselNativeInner(rawProps, ref) {
     const styleWithFlexDirection = react_1.default.useMemo(() => (0, CarouselNativeLogic_1.addFlexDirectionStyle)(style, orientation), [style, orientation]);
     let initialData = lastInitialData.current && lastInitialData.current.length !== 0
         ? lastInitialData.current
-        : (0, CarouselNativeLogic_1.getInitialData)(dataAdapter, renderItem, initialStartIndexInternal, numOffsetItems, renderedFrames.current);
+        : (0, CarouselNativeLogic_1.getInitialData)(dataAdapter, renderItem, initialStartIndexInternal, initialBackCount, renderedFrames.current);
     if (!lastParentId.current || !lastInitialData.current) {
         lastParentId.current = uniqueId;
         lastInitialData.current = initialData;
     }
     if (lastParentId.current !== uniqueId) {
-        initialData = (0, CarouselNativeLogic_1.getInitialData)(dataAdapter, renderItem, initialStartIndexInternal, numOffsetItems, renderedFrames.current);
+        initialData = (0, CarouselNativeLogic_1.getInitialData)(dataAdapter, renderItem, initialStartIndexInternal, initialBackCount, renderedFrames.current);
         lastParentId.current = uniqueId;
         lastInitialData.current = initialData;
     }

package/package.json

@@ -1 +1 @@
-{"name": "@amazon-devices/vega-carousel", "version": "0.2.1", "main": "dist/index.js", "types": "dist/index.d.ts", "files": ["dist", "react-native.config.js", "THIRD_PARTY_NOTICES.txt"], "scripts": {"clean": "rm -rf build dist generated logs node_modules", "test:snapshot": "jest --colors --updateSnapshot", "start": "node node_modules/react-native/local-cli/cli.js start", "test": "jest --colors", "lint": "eslint src --ext .ts,.tsx", "lint:fix": "eslint src --ext .ts,.tsx --fix", "lint-staged": "lint-staged --allow-empty", "format": "clang-format -i --glob=\"native/**/*.{cpp,h}\"", "git-commit-template": "git-commit-template .git-commit-template", "compile": "tsc -p tsconfig-build.json", "build": "npm-run-all format compile"}, "dependencies": {"@amazon-devices/react-native-kepler": "^2.0.0", "ansi-colors": "^4.1.3", "react": "^18.2.0", "react-native": "^0.72.0", "recyclerlistview": "4.2.1"}, "devDependencies": {"@babel/core": "^7.20.0", "@babel/plugin-transform-private-methods": "^7.23.3", "@babel/runtime": "^7.20.0", "@bam.tech/jest-junit-reports-merger": "^1.1.0", "@react-native-community/eslint-config": "^3.2.0", "@testing-library/jest-native": "^5.4.3", "@testing-library/react-native": "^11.5.4", "@types/jest": "^28.0.0", "@types/react-test-renderer": "^18.0.0", "@typescript-eslint/eslint-plugin": "^5.18.0", "babel-jest": "^28.0.0", "clang-format": "^1.8.0", "eslint": "^8.19.0", "eslint-plugin-react-native": "^4.1.0", "git-commit-template": "^1.0.5", "lint-staged": "^12.3.7", "jest": "^28.0.0", "jest-junit": "^16.0.0", "metro-react-native-babel-preset": "^0.76.5", "npm-run-all": "^4.1.5", "prettier": "^3.0.0", "react": "^18.2.0", "react-native": "^0.72.0", "react-test-renderer": "18.2.0", "ts-jest": "^28.0.0", "typedoc": "^0.25.7", "typescript": "4.9.5", "@amazon-devices/kepler-cli-platform": "^0", "@react-native-community/cli": "^11.2.0"}, "resolutions": {"@types/react": "^18"}, "peerDependencies": {"react": "^18.2.0", "react-native": "^0.72.0"}, "kepler": {"projectType": "turbomodule", "toolchain": "clang", "targets": ["tv"], "os": ["vega"]}, "eslintConfig": {"extends": "@react-native-community", "parser": "@typescript-eslint/parser", "plugins": ["@typescript-eslint"], "root": true}, "prettier": {"arrowParens": "avoid", "bracketSameLine": true, "bracketSpacing": false, "singleQuote": true, "trailingComma": "all"}, "npm-pretty-much": {"allowUnsafeName": "reason for using a unsafe name"}, "license": "See license in LICENSE"}
+{"name": "@amazon-devices/vega-carousel", "version": "0.2.5", "main": "dist/index.js", "types": "dist/index.d.ts", "files": ["dist", "react-native.config.js", "THIRD_PARTY_NOTICES.txt"], "scripts": {"clean": "rm -rf build dist generated logs node_modules", "test:snapshot": "jest --colors --updateSnapshot", "start": "node node_modules/react-native/local-cli/cli.js start", "test": "jest --colors", "lint": "eslint src --ext .ts,.tsx", "lint:fix": "eslint src --ext .ts,.tsx --fix", "lint-staged": "lint-staged --allow-empty", "format": "clang-format -i --glob=\"native/**/*.{cpp,h}\"", "git-commit-template": "git-commit-template .git-commit-template", "compile": "tsc -p tsconfig-build.json", "build": "npm-run-all format compile"}, "dependencies": {"@amazon-devices/react-native-kepler": "^2.0.0", "ansi-colors": "^4.1.3", "react": "^18.2.0", "react-native": "^0.72.0", "recyclerlistview": "4.2.1"}, "devDependencies": {"@babel/core": "^7.20.0", "@babel/plugin-transform-private-methods": "^7.23.3", "@babel/runtime": "^7.20.0", "@bam.tech/jest-junit-reports-merger": "^1.1.0", "@react-native-community/eslint-config": "^3.2.0", "@testing-library/jest-native": "^5.4.3", "@testing-library/react-native": "^11.5.4", "@types/jest": "^28.0.0", "@types/react-test-renderer": "^18.0.0", "@typescript-eslint/eslint-plugin": "^5.18.0", "babel-jest": "^28.0.0", "clang-format": "^1.8.0", "eslint": "^8.19.0", "eslint-plugin-react-native": "^4.1.0", "git-commit-template": "^1.0.5", "lint-staged": "^12.3.7", "jest": "^28.0.0", "jest-junit": "^16.0.0", "metro-react-native-babel-preset": "^0.76.5", "npm-run-all": "^4.1.5", "prettier": "^3.0.0", "react": "^18.2.0", "react-native": "^0.72.0", "react-test-renderer": "18.2.0", "ts-jest": "^28.0.0", "typedoc": "^0.25.7", "typescript": "4.9.5", "@amazon-devices/kepler-cli-platform": "^0", "@react-native-community/cli": "^11.2.0"}, "resolutions": {"@types/react": "^18"}, "peerDependencies": {"react": "^18.2.0", "react-native": "^0.72.0"}, "kepler": {"projectType": "turbomodule", "toolchain": "clang", "targets": ["tv"], "os": ["vega"]}, "eslintConfig": {"extends": "@react-native-community", "parser": "@typescript-eslint/parser", "plugins": ["@typescript-eslint"], "root": true}, "prettier": {"arrowParens": "avoid", "bracketSameLine": true, "bracketSpacing": false, "singleQuote": true, "trailingComma": "all"}, "npm-pretty-much": {"allowUnsafeName": "reason for using a unsafe name"}, "license": "See license in LICENSE"}