@fire-spark/rn-ui 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -4,5 +4,5 @@ import { Category, CategoryContent, CategoryDescription, CategoryEmpty, Category
 import { Checkout, CheckoutAside, CheckoutBack, CheckoutBanner, CheckoutColumn, CheckoutDescription, CheckoutFeeInfo, CheckoutFeeLabel, CheckoutFeeList, CheckoutFeeRow, CheckoutFeeValue, CheckoutFooter, CheckoutFulfillment, CheckoutFulfillmentOption, CheckoutHeader, CheckoutMain, CheckoutNav, CheckoutNavBrand, CheckoutOption, CheckoutOptionControl, CheckoutOptionLabel, CheckoutPayment, CheckoutPaymentOption, CheckoutPaymentPanel, CheckoutPaymentPanelHeader, CheckoutPromo, CheckoutPromoChevron, CheckoutPromoIcon, CheckoutPromoLabel, CheckoutRow, CheckoutRowAside, CheckoutRowChevron, CheckoutRowContent, CheckoutRowDescription, CheckoutRowMedia, CheckoutRowTitle, CheckoutSection, CheckoutSectionAction, CheckoutSectionHeader, CheckoutSectionTitle, CheckoutStore, CheckoutStoreContent, CheckoutStoreDescription, CheckoutStoreImage, CheckoutStoreMedia, CheckoutStoreTitle, CheckoutSubmit, CheckoutTip, CheckoutTipCustom, CheckoutTipList, CheckoutTipOption, CheckoutTitle } from "./checkout.js";
 import { Menu, MenuEmpty, MenuEmptyContent, MenuEmptyDescription, MenuEmptyHeader, MenuEmptyMedia, MenuEmptyTitle } from "./menu.js";
 import { ProductCard, ProductCardAddButton, ProductCardAnchorPrice, ProductCardBadge, ProductCardContent, ProductCardDescription, ProductCardDiscount, ProductCardFooter, ProductCardHeader, ProductCardImage, ProductCardImageSlot, ProductCardMedia, ProductCardMeta, ProductCardPrice, ProductCardRating, ProductCardTitle } from "./product-card.js";
-import { UseActiveCategoryOptions, useActiveCategory } from "./use-active-category.js";
-export { Cart, CartAction, CartBanner, CartBody, CartDescription, CartEmpty, CartEmptyDescription, CartEmptyTitle, CartFooter, CartHeader, CartItem, CartItemAction, CartItemActions, CartItemAnchorPrice, CartItemAside, CartItemContent, CartItemDescription, CartItemHeader, CartItemImage, CartItemImageSlot, CartItemMedia, CartItemMeta, CartItemPrice, CartItemTitle, CartList, CartOption, CartOptionControl, CartOptionLabel, CartQuantity, CartQuantityButton, CartQuantityValue, CartScroller, CartSection, CartSectionHeader, CartSectionTitle, CartStore, CartStoreContent, CartStoreDescription, CartStoreImage, CartStoreMedia, CartStoreTitle, CartSubmit, CartSummary, CartSummaryLabel, CartSummaryRow, CartSummaryValue, CartTitle, Category, CategoryContent, CategoryDescription, CategoryEmpty, CategoryEmptyContent, CategoryEmptyDescription, CategoryEmptyHeader, CategoryEmptyMedia, CategoryEmptyTitle, CategoryGrid, CategoryGridItem, CategoryHeader, CategoryList, CategoryListItem, CategoryNav, CategoryNavExtra, CategoryNavItem, CategoryNavLink, CategoryNavList, CategoryNavOrientation, CategoryTitle, Checkout, CheckoutAside, CheckoutBack, CheckoutBanner, CheckoutColumn, CheckoutDescription, CheckoutFeeInfo, CheckoutFeeLabel, CheckoutFeeList, CheckoutFeeRow, CheckoutFeeValue, CheckoutFooter, CheckoutFulfillment, CheckoutFulfillmentOption, CheckoutHeader, CheckoutMain, CheckoutNav, CheckoutNavBrand, CheckoutOption, CheckoutOptionControl, CheckoutOptionLabel, CheckoutPayment, CheckoutPaymentOption, CheckoutPaymentPanel, CheckoutPaymentPanelHeader, CheckoutPromo, CheckoutPromoChevron, CheckoutPromoIcon, CheckoutPromoLabel, CheckoutRow, CheckoutRowAside, CheckoutRowChevron, CheckoutRowContent, CheckoutRowDescription, CheckoutRowMedia, CheckoutRowTitle, CheckoutSection, CheckoutSectionAction, CheckoutSectionHeader, CheckoutSectionTitle, CheckoutStore, CheckoutStoreContent, CheckoutStoreDescription, CheckoutStoreImage, CheckoutStoreMedia, CheckoutStoreTitle, CheckoutSubmit, CheckoutTip, CheckoutTipCustom, CheckoutTipList, CheckoutTipOption, CheckoutTitle, Menu, MenuEmpty, MenuEmptyContent, MenuEmptyDescription, MenuEmptyHeader, MenuEmptyMedia, MenuEmptyTitle, ProductCard, ProductCardAddButton, ProductCardAnchorPrice, ProductCardBadge, ProductCardContent, ProductCardDescription, ProductCardDiscount, ProductCardFooter, ProductCardHeader, ProductCardImage, ProductCardImageSlot, ProductCardMedia, ProductCardMeta, ProductCardPrice, ProductCardRating, ProductCardTitle, UseActiveCategoryOptions, useActiveCategory };
+import { ActiveCategoryViewToken, ActiveCategoryViewableInfo, ScrollableList, UseActiveCategoryIndexOptions, UseActiveCategoryOffsetOptions, UseActiveCategoryOptions, useActiveCategory } from "./use-active-category.js";
+export { ActiveCategoryViewToken, ActiveCategoryViewableInfo, Cart, CartAction, CartBanner, CartBody, CartDescription, CartEmpty, CartEmptyDescription, CartEmptyTitle, CartFooter, CartHeader, CartItem, CartItemAction, CartItemActions, CartItemAnchorPrice, CartItemAside, CartItemContent, CartItemDescription, CartItemHeader, CartItemImage, CartItemImageSlot, CartItemMedia, CartItemMeta, CartItemPrice, CartItemTitle, CartList, CartOption, CartOptionControl, CartOptionLabel, CartQuantity, CartQuantityButton, CartQuantityValue, CartScroller, CartSection, CartSectionHeader, CartSectionTitle, CartStore, CartStoreContent, CartStoreDescription, CartStoreImage, CartStoreMedia, CartStoreTitle, CartSubmit, CartSummary, CartSummaryLabel, CartSummaryRow, CartSummaryValue, CartTitle, Category, CategoryContent, CategoryDescription, CategoryEmpty, CategoryEmptyContent, CategoryEmptyDescription, CategoryEmptyHeader, CategoryEmptyMedia, CategoryEmptyTitle, CategoryGrid, CategoryGridItem, CategoryHeader, CategoryList, CategoryListItem, CategoryNav, CategoryNavExtra, CategoryNavItem, CategoryNavLink, CategoryNavList, CategoryNavOrientation, CategoryTitle, Checkout, CheckoutAside, CheckoutBack, CheckoutBanner, CheckoutColumn, CheckoutDescription, CheckoutFeeInfo, CheckoutFeeLabel, CheckoutFeeList, CheckoutFeeRow, CheckoutFeeValue, CheckoutFooter, CheckoutFulfillment, CheckoutFulfillmentOption, CheckoutHeader, CheckoutMain, CheckoutNav, CheckoutNavBrand, CheckoutOption, CheckoutOptionControl, CheckoutOptionLabel, CheckoutPayment, CheckoutPaymentOption, CheckoutPaymentPanel, CheckoutPaymentPanelHeader, CheckoutPromo, CheckoutPromoChevron, CheckoutPromoIcon, CheckoutPromoLabel, CheckoutRow, CheckoutRowAside, CheckoutRowChevron, CheckoutRowContent, CheckoutRowDescription, CheckoutRowMedia, CheckoutRowTitle, CheckoutSection, CheckoutSectionAction, CheckoutSectionHeader, CheckoutSectionTitle, CheckoutStore, CheckoutStoreContent, CheckoutStoreDescription, CheckoutStoreImage, CheckoutStoreMedia, CheckoutStoreTitle, CheckoutSubmit, CheckoutTip, CheckoutTipCustom, CheckoutTipList, CheckoutTipOption, CheckoutTitle, Menu, MenuEmpty, MenuEmptyContent, MenuEmptyDescription, MenuEmptyHeader, MenuEmptyMedia, MenuEmptyTitle, ProductCard, ProductCardAddButton, ProductCardAnchorPrice, ProductCardBadge, ProductCardContent, ProductCardDescription, ProductCardDiscount, ProductCardFooter, ProductCardHeader, ProductCardImage, ProductCardImageSlot, ProductCardMedia, ProductCardMeta, ProductCardPrice, ProductCardRating, ProductCardTitle, ScrollableList, UseActiveCategoryIndexOptions, UseActiveCategoryOffsetOptions, UseActiveCategoryOptions, useActiveCategory };

package/dist/use-active-category.d.ts

@@ -1,29 +1,59 @@
 import { LayoutChangeEvent } from "react-native";
 import { RefObject } from "react";
 //#region src/use-active-category.d.ts
-type Scrollable = {
+type OffsetScrollable = {
   scrollTo: (opts: {
     y: number;
     animated?: boolean;
   }) => void;
 };
-type UseActiveCategoryOptions = {
+/** List ref shared by FlashList, FlatList, and LegendList. No list package. */
+type ScrollableList = {
+  scrollToIndex: (params: {
+    index: number;
+    animated?: boolean;
+    viewOffset?: number;
+  }) => unknown;
+  getFirstVisibleIndex?: () => number;
+};
+type ActiveCategoryViewToken = {
+  index: number | null;
+  isViewable?: boolean;
+};
+type ActiveCategoryViewableInfo = {
+  viewableItems: readonly ActiveCategoryViewToken[];
+};
+type ScrollOffsetEvent = {
+  nativeEvent: {
+    contentOffset: {
+      y: number;
+    };
+  };
+};
+type UseActiveCategoryOffsetOptions = {
   categoryIds: readonly string[];
   offset?: number;
-  scrollRef?: RefObject<Scrollable | null>;
+  scrollRef?: RefObject<OffsetScrollable | null>;
 };
+type UseActiveCategoryIndexOptions = {
+  /** Section id for every list row (row i belongs to rowSectionIds[i]). */
+  rowSectionIds: readonly string[];
+  /** Section id → index of its header row. */
+  headerIndex: ReadonlyMap<string, number>;
+  listRef: RefObject<ScrollableList | null>;
+  /** Pixels kept above the header after a jump (sticky chrome). */
+  offset?: number;
+  /** Section shown as active before the first scroll (deep links). */
+  initialCategoryId?: string;
+};
+type UseActiveCategoryOptions = UseActiveCategoryOffsetOptions | UseActiveCategoryIndexOptions;
 declare const useActiveCategory: (opts: UseActiveCategoryOptions) => {
+  onViewableItemsChanged: (info: ActiveCategoryViewableInfo) => void;
+  selectCategory: (categoryId: string) => void;
+  onScroll: (event?: ScrollOffsetEvent) => void;
+  registerCategory: (categoryId: string) => (_event: LayoutChangeEvent) => void;
   activeCategoryId: string;
   setActiveCategoryId: import("react").Dispatch<import("react").SetStateAction<string>>;
-  selectCategory: (categoryId: string) => void;
-  onScroll: (event: {
-    nativeEvent: {
-      contentOffset: {
-        y: number;
-      };
-    };
-  }) => void;
-  registerCategory: (categoryId: string) => (event: LayoutChangeEvent) => void;
 };
 //#endregion
-export { UseActiveCategoryOptions, useActiveCategory };
+export { ActiveCategoryViewToken, ActiveCategoryViewableInfo, ScrollableList, UseActiveCategoryIndexOptions, UseActiveCategoryOffsetOptions, UseActiveCategoryOptions, useActiveCategory };

package/dist/use-active-category.js

@@ -4,24 +4,56 @@ import { useEffect, useRef, useState } from "react";
 const SCROLL_SETTLE_MS = 140;
 /** Fallback if scroll never starts; scroll handler re-arms while moving. */
 const SCROLL_LOCK_FALLBACK_MS = 1e3;
+const EMPTY_IDS = [];
+const EMPTY_HEADERS = /* @__PURE__ */ new Map();
+const EMPTY_LIST_REF = { current: null };
+const isIndexMode = (opts) => {
+	return "rowSectionIds" in opts;
+};
+const firstSectionId = (headerIndex, rowSectionIds) => {
+	let bestId = "";
+	let bestAt = Number.POSITIVE_INFINITY;
+	for (const [id, index] of headerIndex) {
+		if (index >= bestAt) continue;
+		bestAt = index;
+		bestId = id;
+	}
+	if (bestId) return bestId;
+	return rowSectionIds[0] ?? "";
+};
+const ignoreLayout = (_event) => {};
+const ignoreViewable = (_info) => {};
 const useActiveCategory = (opts) => {
-	const { categoryIds, offset = 0, scrollRef } = opts;
-	const [activeCategoryId, setActiveCategoryId] = useState(() => {
+	const indexMode = isIndexMode(opts);
+	const offset = opts.offset ?? 0;
+	const categoryIds = indexMode ? EMPTY_IDS : opts.categoryIds;
+	const rowSectionIds = indexMode ? opts.rowSectionIds : EMPTY_IDS;
+	const headerIndex = indexMode ? opts.headerIndex : EMPTY_HEADERS;
+	const listRef = indexMode ? opts.listRef : EMPTY_LIST_REF;
+	const scrollRef = indexMode ? void 0 : opts.scrollRef;
+	const initialCategoryId = indexMode ? opts.initialCategoryId : void 0;
+	const [storedId, setStoredId] = useState(() => {
+		if (indexMode) return initialCategoryId ?? "";
 		return categoryIds[0] ?? "";
 	});
 	const offsetsRef = useRef(/* @__PURE__ */ new Map());
 	const lockedIdRef = useRef(null);
 	const settleTimerRef = useRef(null);
 	useEffect(() => {
+		if (indexMode) return;
 		if (categoryIds.length === 0) {
-			setActiveCategoryId("");
+			setStoredId("");
 			return;
 		}
-		setActiveCategoryId((current) => {
+		setStoredId((current) => {
 			if (categoryIds.includes(current)) return current;
 			return categoryIds[0] ?? "";
 		});
-	}, [categoryIds, categoryIds.join("\0")]);
+	}, [
+		indexMode,
+		categoryIds,
+		categoryIds.join("\0")
+	]);
 	useEffect(() => {
 		return () => {
 			if (settleTimerRef.current) clearTimeout(settleTimerRef.current);
@@ -33,13 +65,34 @@ const useActiveCategory = (opts) => {
 			lockedIdRef.current = null;
 		}, SCROLL_SETTLE_MS);
 	};
+	let activeCategoryId = storedId;
+	if (indexMode && !headerIndex.has(storedId)) activeCategoryId = firstSectionId(headerIndex, rowSectionIds);
 	const registerCategory = (categoryId) => {
+		if (indexMode) return ignoreLayout;
 		return (event) => {
 			const y = event.nativeEvent.layout.y;
 			offsetsRef.current.set(categoryId, y);
 		};
 	};
+	const applyVisibleIndex = (index) => {
+		if (typeof index !== "number" || index < 0) return;
+		const sectionId = rowSectionIds[index];
+		if (!sectionId) return;
+		setStoredId((previous) => {
+			if (previous === sectionId) return previous;
+			return sectionId;
+		});
+	};
 	const onScroll = (event) => {
+		if (indexMode) {
+			if (lockedIdRef.current) {
+				armSettleUnlock();
+				return;
+			}
+			applyVisibleIndex(listRef.current?.getFirstVisibleIndex?.());
+			return;
+		}
+		if (!event) return;
 		const scrollY = event.nativeEvent.contentOffset.y;
 		if (lockedIdRef.current) {
 			armSettleUnlock();
@@ -51,31 +104,75 @@ const useActiveCategory = (opts) => {
 			const top = offsetsRef.current.get(id);
 			if (top !== void 0 && top <= threshold) current = id;
 		}
-		setActiveCategoryId((previous) => {
+		setStoredId((previous) => {
 			return previous === current ? previous : current;
 		});
 	};
+	const onViewableItemsChanged = (info) => {
+		if (!indexMode) return;
+		if (lockedIdRef.current) {
+			armSettleUnlock();
+			return;
+		}
+		let lowest = null;
+		for (const token of info.viewableItems) {
+			if (token.isViewable === false) continue;
+			const tokenIndex = token.index;
+			if (tokenIndex == null || tokenIndex < 0) continue;
+			if (lowest == null || tokenIndex < lowest) lowest = tokenIndex;
+		}
+		if (lowest == null) return;
+		applyVisibleIndex(lowest);
+	};
+	const onViewableRef = useRef(onViewableItemsChanged);
+	onViewableRef.current = onViewableItemsChanged;
+	const stableViewable = useRef((info) => {
+		onViewableRef.current(info);
+	}).current;
 	const selectCategory = (categoryId) => {
 		lockedIdRef.current = categoryId;
-		setActiveCategoryId(categoryId);
-		const top = offsetsRef.current.get(categoryId) ?? 0;
-		const y = Math.max(0, top - offset);
-		scrollRef?.current?.scrollTo({
-			y,
-			animated: true
-		});
+		setStoredId(categoryId);
+		if (indexMode) {
+			const index = headerIndex.get(categoryId);
+			const list = listRef.current;
+			if (index !== void 0 && list) {
+				const jump = {
+					index,
+					animated: true,
+					viewOffset: offset
+				};
+				const pending = list.scrollToIndex(jump);
+				Promise.resolve(pending).catch(() => void 0);
+			}
+		} else {
+			const top = offsetsRef.current.get(categoryId) ?? 0;
+			const y = Math.max(0, top - offset);
+			scrollRef?.current?.scrollTo({
+				y,
+				animated: true
+			});
+		}
 		if (settleTimerRef.current) clearTimeout(settleTimerRef.current);
 		settleTimerRef.current = setTimeout(() => {
 			lockedIdRef.current = null;
 		}, SCROLL_LOCK_FALLBACK_MS);
 	};
-	return {
+	const viewable = indexMode ? stableViewable : ignoreViewable;
+	const b1 = {
 		activeCategoryId,
-		setActiveCategoryId,
+		setActiveCategoryId: setStoredId
+	};
+	const b2 = {
 		selectCategory,
 		onScroll,
 		registerCategory
 	};
+	const b3 = { onViewableItemsChanged: viewable };
+	return {
+		...b1,
+		...b2,
+		...b3
+	};
 };
 //#endregion
 export { useActiveCategory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/rn-ui",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Fire Spark React Native UI components",
   "type": "module",
   "sideEffects": false,
@@ -121,6 +121,7 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "check-types": "tsc --noEmit",
+    "test:utils": "vitest run",
     "lint": "oxlint ./src --max-warnings=0",
     "format": "oxfmt ./src",
     "check-format": "oxfmt --check ./src"