@rific/scroll-view 0.1.0

package/README.md

@@ -0,0 +1,319 @@
+# @rific/scroll-view
+
+Blur-chrome scroll system for React Native. Drop-in replacements for `ScrollView`, `FlatList`, and `SectionList` with floating headers and footers, pull-to-search, keyboard awareness, horizontal paging, and frosted-glass chrome.
+
+## Installation
+
+```sh
+npm install @rific/scroll-view
+```
+
+### Peer dependencies
+
+```sh
+npm install @rific/auto-paper react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-paper react-native-keyboard-controller
+```
+
+## Quick start
+
+Wrap your screen in `ScrollViewProvider`, add a `ScrollViewHeader`, then drop in one of the scroll components.
+
+```tsx
+import { ScrollViewProvider, ScrollViewHeader, FlatList } from '@rific/scroll-view'
+
+export default function MyScreen() {
+  return (
+    <ScrollViewProvider>
+      <ScrollViewHeader title="My Screen" backAction={() => router.back()} />
+      <FlatList data={items} renderItem={({ item }) => <Row item={item} />} keyExtractor={(item) => item.id} />
+    </ScrollViewProvider>
+  )
+}
+```
+
+For app-wide defaults, wrap your root layout with `ScrollViewSettingsProvider`.
+
+```tsx
+import { ScrollViewSettingsProvider } from '@rific/scroll-view'
+
+export default function RootLayout({ children }) {
+  return (
+    <ScrollViewSettingsProvider value={{ snapBack: true }}>
+      {children}
+    </ScrollViewSettingsProvider>
+  )
+}
+```
+
+---
+
+## Components
+
+### `ScrollViewProvider`
+
+Screen-level provider that owns header/footer state and scroll position. Must wrap `ScrollViewHeader`, `ScrollViewFooter`, and the scroll component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `blur` | `boolean` | system | Enable frosted-glass backdrop on header/footer |
+| `fixed` | `boolean` | `false` | Pin both header and footer (overrides `headerFixed`/`footerFixed`) |
+| `headerFixed` | `boolean` | `false` | Pin header; overrides settings default |
+| `footerFixed` | `boolean` | `false` | Pin footer; overrides settings default |
+| `snapBack` | `boolean` | `false` | Snap header and footer back when scrolling up |
+| `snapBackHeader` | `boolean` | — | Override `snapBack` for header only |
+| `snapBackFooter` | `boolean` | — | Override `snapBack` for footer only |
+| `tabBarHeight` | `number` | `60` | Used to compute safe scroll height |
+
+---
+
+### `ScrollViewHeader`
+
+Floating header with blur backdrop, title, back action, trailing action, and built-in progress bar. Place it as a direct child of `ScrollViewProvider`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Center title text |
+| `caption` | `string` | — | Subtitle below title |
+| `centerContent` | `ReactNode` | — | Replaces title/caption with custom content |
+| `children` | `ReactNode` | — | Left-side content (icon buttons, etc.) |
+| `backAction` | `() => void` | — | Renders a back button and calls this on press |
+| `backActionFixed` | `boolean` | settings | Keep back button visible as header scrolls away |
+| `trailingAction` | `ReactNode` | — | Right-side floating action |
+| `trailingActionFixed` | `boolean` | `true` | Keep trailing action visible as header scrolls away |
+| `actionSize` | `number` | `48` | Size of floating action buttons |
+| `iconSize` | `number` | `actionSize/2` | Icon size inside action buttons |
+| `actionStyle` | `ViewStyle` | — | Style applied to action button backgrounds |
+| `style` | `ViewStyle` | — | Style applied to the header content area |
+| `topInset` | `boolean` | `true` | Pad for safe area top inset |
+
+---
+
+### `ScrollViewFooter`
+
+Floating footer with blur backdrop. Place it as a direct child of `ScrollViewProvider`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Footer content |
+| `style` | `ViewStyle` | Style applied to the inner row |
+
+---
+
+### `ScrollView`
+
+Drop-in for React Native's `ScrollView`. Accepts all `ScrollViewProps` plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `footerFixed` | `boolean` | Pin footer for this scroll view; overrides provider |
+| `headerFixed` | `boolean` | Pin header for this scroll view; overrides provider |
+| `gesture` | `GestureType` | Compose with an external RNGH gesture |
+| `keyboardAware` | `boolean` | Add keyboard height to bottom content inset |
+| `onRefresh` | `() => void` | Enables pull-to-refresh |
+| `refreshing` | `boolean` | Controlled refreshing state |
+| `pullSearchHeight` | `number` | Reserve space above content for `PullSearch` |
+| `ref` | `RefObject<RNScrollView>` | Forward ref to the underlying scroll view |
+
+---
+
+### `FlatList`
+
+Drop-in for React Native's `FlatList`. Accepts all `FlatListProps<T>` plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderFilters` | `ReactNode` | Rendered below `ListHeaderComponent`, above list items |
+| `footerFixed` | `boolean` | Pin footer for this list; overrides provider |
+| `headerFixed` | `boolean` | Pin header for this list; overrides provider |
+| `gesture` | `GestureType` | Compose with an external RNGH gesture |
+| `keyboardAware` | `boolean` | Add keyboard height to bottom content inset |
+| `onRefresh` | `() => Promise<void> \| void` | Enables pull-to-refresh |
+| `pullSearchHeight` | `number` | Reserve space above content for `PullSearch` |
+| `ref` | `RefObject<RNFlatList>` | Forward ref to the underlying list |
+
+Performance props are user-overridable with sensible defaults:
+
+| Prop | Default |
+|------|---------|
+| `initialNumToRender` | `20` |
+| `maxToRenderPerBatch` | `50` |
+| `windowSize` | `100` |
+| `removeClippedSubviews` | `false` |
+| `showsHorizontalScrollIndicator` | `horizontal` |
+| `showsVerticalScrollIndicator` | `!horizontal` |
+
+When `horizontal` and `pagingEnabled` are both true and `data` has more than one item, horizontal dot indicators render automatically.
+
+---
+
+### `SectionList`
+
+Drop-in for React Native's `SectionList`. Accepts all `SectionListProps<ItemT, SectionT>` (except `horizontal`) plus the same set of library props as `FlatList`. Custom sticky section headers are supported — pass `renderSectionHeader` and `stickySectionHeadersEnabled` and the library renders them via an animated overlay so they properly account for the floating header offset.
+
+---
+
+### `CustomList`
+
+Wraps any list component that follows the FlatList scroll API (e.g. FlashList). Pass the component via the `component` prop; all other props are forwarded.
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+import { CustomList } from '@rific/scroll-view'
+
+<CustomList component={FlashList} data={items} renderItem={renderItem} estimatedItemSize={80} />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `component` | `ComponentType<P>` | The list component to render |
+| `renderFilters` | `ReactNode` | Rendered below `ListHeaderComponent`, above list items |
+| `footerFixed` | `boolean` | Pin footer; overrides provider |
+| `headerFixed` | `boolean` | Pin header; overrides provider |
+| `gesture` | `GestureType` | Compose with an external RNGH gesture |
+| `keyboardAware` | `boolean` | Add keyboard height to bottom content inset |
+| `onRefresh` | `() => Promise<void> \| void` | Enables pull-to-refresh |
+| `pullSearchHeight` | `number` | Reserve space above content for `PullSearch` |
+| `scrollRef` | `RefObject<{ scrollToOffset }>` | Forward ref to the underlying list |
+
+The underlying component receives `contentInset`, `contentOffset`, `onScroll`, `refreshControl`, and `scrollEventThrottle` — props it must support for the library to function.
+
+---
+
+### `PullSearch`
+
+A search bar that lives above the list content and is revealed by pulling down. Use alongside `pullSearchHeight` on the scroll component.
+
+```tsx
+import { useRef, useState } from 'react'
+import { FlatList, PullSearch, type PullSearchHandle } from '@rific/scroll-view'
+
+export default function SearchScreen() {
+  const searchRef = useRef<PullSearchHandle>(null)
+  const [query, setQuery] = useState('')
+  const [searchHeight, setSearchHeight] = useState(0)
+
+  return (
+    <ScrollViewProvider>
+      <ScrollViewHeader title="Search" />
+      <FlatList
+        data={filteredItems}
+        renderItem={renderItem}
+        keyExtractor={(item) => item.id}
+        pullSearchHeight={searchHeight}
+        ListHeaderComponent={
+          <PullSearch
+            ref={searchRef}
+            value={query}
+            onChangeText={setQuery}
+            onHeightChange={setSearchHeight}
+            placeholder="Search…"
+            debounce
+          />
+        }
+      />
+    </ScrollViewProvider>
+  )
+}
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onChangeText` | `(text: string) => void` | Called with trimmed search text |
+| `onHeightChange` | `(height: number) => void` | Required — pass the height back as `pullSearchHeight` |
+| `value` | `string` | Controlled value |
+| `placeholder` | `string` | Placeholder text |
+| `debounce` | `boolean` | Debounce `onChangeText` by 500ms |
+
+**Ref methods**: `focus()`, `blur()`
+
+---
+
+## Hooks
+
+### `useScrollView`
+
+Access scroll state and progress control from anywhere inside a `ScrollViewProvider`.
+
+```tsx
+const { scrollPosition, scrollHeight, progressing, progress, setProgress, setProgressing } = useScrollView()
+```
+
+| Return | Type | Description |
+|--------|------|-------------|
+| `scrollPosition` | `SharedValue<number>` | Live scroll offset (Reanimated worklet-safe) |
+| `scrollHeight` | `number` | Visible scroll area height (window minus header/footer) |
+| `progressing` | `boolean` | Whether the header progress bar is visible |
+| `progress` | `number \| null` | Progress bar value (0–1), or `null` for indeterminate |
+| `setProgress` | `(p: number \| null) => void` | Set progress; pass `null` for indeterminate |
+| `setProgressing` | `(b: boolean) => void` | Show/hide the progress bar |
+
+```tsx
+// Show an indeterminate progress bar while loading
+useEffect(() => {
+  setProgressing(true)
+  fetchData().finally(() => setProgressing(false))
+}, [])
+```
+
+---
+
+### `useScrollViewSettings`
+
+Read and update scroll settings at runtime from anywhere inside `ScrollViewSettingsProvider`.
+
+```tsx
+const { settings, set } = useScrollViewSettings()
+
+// Toggle snap-back on the fly
+set({ snapBack: true })
+```
+
+---
+
+### `useKeyboardInset`
+
+Returns the current keyboard height, updating as the keyboard animates in and out. Useful when you need the keyboard height outside of a scroll component.
+
+```tsx
+const keyboardHeight = useKeyboardInset()
+```
+
+---
+
+## Redux integration
+
+If your app uses Redux, you can drive scroll settings from the store instead of (or in addition to) `ScrollViewSettingsProvider`.
+
+```ts
+// store.ts
+import { scrollViewReducer } from '@rific/scroll-view'
+
+export const store = configureStore({
+  reducer: {
+    scrollView: scrollViewReducer,
+    // ...
+  }
+})
+```
+
+```ts
+// Dispatch initial settings (e.g. from a remote config)
+store.dispatch(scrollViewActions.initialize({ snapBack: true, headerFixed: false, footerFixed: false, backActionFixed: true }))
+```
+
+---
+
+## Settings reference
+
+`ScrollViewSettings` defaults:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `headerFixed` | `false` | Pin header globally |
+| `footerFixed` | `false` | Pin footer globally |
+| `snapBack` | `false` | Snap header and footer back when scrolling up |
+| `snapBackHeader` | — | Override `snapBack` for header only |
+| `snapBackFooter` | — | Override `snapBack` for footer only |
+| `backActionFixed` | `true` | Keep back button visible as header scrolls away |
+
+Settings cascade: `ScrollViewSettingsProvider` → `ScrollViewProvider` → individual scroll component props. More specific values always win.

package/dist/index.d.mts

@@ -0,0 +1,210 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, RefObject } from 'react';
+import { NativeSyntheticEvent, NativeScrollEvent, StyleProp, ViewStyle, FlatListProps as FlatListProps$1, FlatList as FlatList$1, ScrollViewProps as ScrollViewProps$1, ScrollView as ScrollView$1, SectionListProps as SectionListProps$1, SectionList as SectionList$1 } from 'react-native';
+import { GestureType } from 'react-native-gesture-handler';
+import * as redux from 'redux';
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import { PayloadAction } from '@reduxjs/toolkit';
+import * as react_native_reanimated from 'react-native-reanimated';
+import { SharedValue } from 'react-native-reanimated';
+
+type ScrollToOffsetRef = {
+    scrollToOffset: (params: {
+        animated?: boolean;
+        offset: number;
+    }) => void;
+};
+type CustomListProps<P extends object> = Omit<P, 'contentInset' | 'contentOffset' | 'onScroll' | 'refreshControl' | 'scrollEventThrottle'> & {
+    component: ComponentType<P>;
+    renderFilters?: ReactNode;
+    footerFixed?: boolean;
+    gesture?: GestureType;
+    headerFixed?: boolean;
+    keyboardAware?: boolean;
+    onMomentumScrollEnd?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onRefresh?: () => Promise<void> | void;
+    onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onScrollEndDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    pullSearchHeight?: number;
+    scrollRef?: RefObject<ScrollToOffsetRef | null>;
+    style?: StyleProp<ViewStyle>;
+};
+declare const CustomListInner: <P extends object>({ component: List, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, keyboardAware, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, scrollRef, style, ...props }: CustomListProps<P>) => react.JSX.Element;
+declare const CustomList: typeof CustomListInner;
+
+type FlatListProps<T> = Omit<FlatListProps$1<T>, 'onRefresh' | 'refreshing'> & {
+    renderFilters?: ReactNode;
+    footerFixed?: boolean;
+    gesture?: GestureType;
+    headerFixed?: boolean;
+    keyboardAware?: boolean;
+    onMomentumScrollEnd?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onRefresh?: () => Promise<void> | void;
+    onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onScrollEndDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    pullSearchHeight?: number;
+    ref?: RefObject<FlatList$1 | null>;
+};
+declare const FlatListInner: <T>({ contentContainerStyle: externalContentContainerStyle, data, initialNumToRender, maxToRenderPerBatch, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pagingEnabled, pullSearchHeight, removeClippedSubviews, showsHorizontalScrollIndicator, showsVerticalScrollIndicator, style, onContentSizeChange, ref: externalRef, windowSize, ...props }: FlatListProps<T>) => react.JSX.Element;
+declare const FlatList: typeof FlatListInner;
+
+type PullSearchHandle = {
+    blur: () => void;
+    focus: () => void;
+};
+type PullSearchProps = {
+    debounce?: boolean;
+    onChangeText: (text: string) => void;
+    onHeightChange: (height: number) => void;
+    placeholder?: string;
+    value?: string;
+};
+declare const PullSearch: react.ForwardRefExoticComponent<PullSearchProps & react.RefAttributes<PullSearchHandle>>;
+
+type ScrollViewSettings = {
+    backActionFixed: boolean;
+    footerFixed: boolean;
+    headerFixed: boolean;
+    snapBack: boolean;
+    snapBackFooter?: boolean;
+    snapBackHeader?: boolean;
+};
+declare const defaultScrollViewSettings: ScrollViewSettings;
+type ScrollViewSettingsContextType = {
+    settings: ScrollViewSettings;
+    set: (patch: Partial<ScrollViewSettings>) => void;
+};
+declare const ScrollViewSettingsContext: react.Context<ScrollViewSettingsContextType>;
+
+declare const scrollViewActions: _reduxjs_toolkit.CaseReducerActions<{
+    initialize: (_state: {
+        backActionFixed: boolean;
+        footerFixed: boolean;
+        headerFixed: boolean;
+        snapBack: boolean;
+        snapBackFooter?: boolean | undefined;
+        snapBackHeader?: boolean | undefined;
+    }, action: PayloadAction<ScrollViewSettings>) => ScrollViewSettings;
+}, "scrollView">;
+declare const scrollViewReducer: redux.Reducer<ScrollViewSettings>;
+
+type ScrollViewProps = ScrollViewProps$1 & {
+    footerFixed?: boolean;
+    gesture?: GestureType;
+    headerFixed?: boolean;
+    keyboardAware?: boolean;
+    onRefresh?: () => void;
+    onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onScrollEndDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    pullSearchHeight?: number;
+    ref?: RefObject<ScrollView$1 | null>;
+    refreshing?: boolean;
+};
+declare const ScrollViewInner: ({ children, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, refreshing, style, ...props }: ScrollViewProps) => react.JSX.Element;
+declare const ScrollView: typeof ScrollViewInner;
+
+type ScrollViewContextType = {
+    blur: boolean;
+    footerHeight: number;
+    footerHeightShared: SharedValue<number>;
+    footerFixed: boolean;
+    footerOffset: SharedValue<number>;
+    headerHeight: number;
+    headerHeightShared: SharedValue<number>;
+    headerFixed: boolean;
+    headerOffset: SharedValue<number>;
+    progress: number | null;
+    pullSearchHeightShared: SharedValue<number>;
+    snapBackFooterShared: SharedValue<boolean>;
+    snapBackHeaderShared: SharedValue<boolean>;
+    progressing: boolean;
+    scrollHeight: number;
+    scrollPosition: SharedValue<number>;
+    setFooterHeight: (h: number) => void;
+    setHeaderHeight: (h: number) => void;
+    setProgress: (p: number | null) => void;
+    setProgressing: (b: boolean) => void;
+    tabBarHeight: number;
+};
+declare const ScrollViewContext: react.Context<ScrollViewContextType>;
+
+type ScrollViewFooterProps = {
+    children?: ReactNode | ReactNode[];
+    style?: ViewStyle;
+};
+declare const ScrollViewFooter: ({ children, style }: ScrollViewFooterProps) => react.JSX.Element;
+
+type ScrollViewHeaderProps = {
+    actionSize?: number;
+    actionStyle?: ViewStyle;
+    backAction?: () => void;
+    backActionFixed?: boolean;
+    caption?: string;
+    centerContent?: ReactNode;
+    children?: ReactNode | ReactNode[];
+    iconSize?: number;
+    style?: ViewStyle;
+    title?: string;
+    topInset?: boolean;
+    trailingAction?: ReactNode;
+    trailingActionFixed?: boolean;
+};
+declare const ScrollViewHeader: ({ actionSize, actionStyle, backAction, backActionFixed, caption, centerContent, children, iconSize, style, title, topInset, trailingAction, trailingActionFixed }: ScrollViewHeaderProps) => react.JSX.Element;
+
+type ScrollViewProviderProps = {
+    blur?: boolean;
+    children: ReactNode;
+    fixed?: boolean;
+    footerFixed?: boolean;
+    headerFixed?: boolean;
+    snapBack?: boolean;
+    snapBackFooter?: boolean;
+    snapBackHeader?: boolean;
+    tabBarHeight?: number;
+};
+declare const ScrollViewProvider: ({ blur, children, fixed, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight }: ScrollViewProviderProps) => react.JSX.Element;
+
+type ScrollViewSettingsProviderProps = {
+    children: ReactNode;
+    onChange?: (settings: ScrollViewSettings) => void;
+    value?: Partial<ScrollViewSettings>;
+};
+declare const ScrollViewSettingsProvider: ({ children, onChange, value }: ScrollViewSettingsProviderProps) => react.JSX.Element;
+
+type SectionListProps<ItemT, SectionT extends {
+    data: ReadonlyArray<ItemT>;
+} = {
+    data: ReadonlyArray<ItemT>;
+}> = Omit<SectionListProps$1<ItemT, SectionT>, 'horizontal'> & {
+    renderFilters?: ReactNode;
+    footerFixed?: boolean;
+    gesture?: GestureType;
+    headerFixed?: boolean;
+    keyboardAware?: boolean;
+    onMomentumScrollEnd?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onScrollEndDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    pullSearchHeight?: number;
+    ref?: RefObject<SectionList$1<ItemT, SectionT> | null>;
+};
+declare const SectionListInner: <ItemT, SectionT extends {
+    data: ReadonlyArray<ItemT>;
+} = {
+    data: ReadonlyArray<ItemT>;
+}>({ contentContainerStyle: externalContentContainerStyle, initialNumToRender, maxToRenderPerBatch, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onContentSizeChange, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, refreshing, removeClippedSubviews, sections, showsVerticalScrollIndicator, style, ref: externalRef, windowSize, ...props }: SectionListProps<ItemT, SectionT>) => react.JSX.Element;
+declare const SectionList: typeof SectionListInner;
+
+declare const useKeyboardInset: () => number;
+
+declare const useScrollView: () => {
+    progress: number | null;
+    progressing: boolean;
+    scrollHeight: number;
+    scrollPosition: react_native_reanimated.SharedValue<number>;
+    setProgress: (p: number | null) => void;
+    setProgressing: (b: boolean) => void;
+};
+
+declare const useScrollViewSettings: () => ScrollViewSettingsContextType;
+
+export { CustomList, type CustomListProps, FlatList, type FlatListProps, PullSearch, type PullSearchHandle, type PullSearchProps, ScrollView, ScrollViewContext, type ScrollViewContextType, ScrollViewFooter, type ScrollViewFooterProps, ScrollViewHeader, type ScrollViewHeaderProps, type ScrollViewProps, ScrollViewProvider, type ScrollViewProviderProps, type ScrollViewSettings, ScrollViewSettingsContext, type ScrollViewSettingsContextType, ScrollViewSettingsProvider, type ScrollViewSettingsProviderProps, SectionList, type SectionListProps, defaultScrollViewSettings, scrollViewActions, scrollViewReducer, useKeyboardInset, useScrollView, useScrollViewSettings };