react-native-collapsible-sticky-header 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santhosh James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,570 @@
-# Temporary Holding Version
+# react-native-collapsible-sticky-header
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/react-native-collapsible-sticky-header.svg)](https://www.npmjs.com/package/react-native-collapsible-sticky-header)
+[![CI](https://github.com/santhoshjamesc/react-native-collapsible-sticky-header/actions/workflows/ci.yml/badge.svg)](https://github.com/santhoshjamesc/react-native-collapsible-sticky-header/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/react-native-collapsible-sticky-header.svg)](LICENSE)
+![platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android-blue)
+
+A fully configurable collapsing hero header with a sticky compact bar for **React Native (iOS & Android)**. Works in Expo and bare React Native.
+
+- Hero image, plain color, or nothing at all, with an optional fade and rounded bottom corners
+- Built-in layout: logo, greeting, title, subtitle, avatar and up to **3** icon actions with badges
+- Swap in your own expanded nav, collapsible block or sticky bar with render props
+- Scroll handling runs on the UI thread through Reanimated. React re-renders only when the sticky state changes
+- `FlatList`, `ScrollView`, `SectionList`, or any Animated scrollable (such as FlashList)
+- Accessible: the hidden sticky bar is skipped by screen readers, and reduced motion is respected
+- Fully typed and themeable, with no bundled icons, images or brand colors
+
+<p align="center">
+  <img src="docs/demo.gif" alt="Demo: the hero header collapses and the sticky bar fades in" width="320" />
+  <br />
+  <em>The example app: hero header expanded, with the sticky bar ready to fade in on scroll.</em>
+</p>
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Props](#props)
+- [Actions (icon buttons)](#actions-icon-buttons)
+- [Theming](#theming)
+- [Recipes](#recipes) (including [customizing the collapsed header](#customize-the-collapsed-header))
+- [Building blocks](#building-blocks)
+- [Accessibility & performance](#accessibility--performance)
+- [Example app](#example-app)
+
+## Installation
+
+```sh
+npm install react-native-collapsible-sticky-header
+```
+
+### Expo
+
+```sh
+npx expo install react-native-reanimated react-native-worklets react-native-safe-area-context expo-linear-gradient
+```
+
+`babel-preset-expo` adds the Reanimated / Worklets Babel plugin for you. `expo-linear-gradient` is **optional** and only used for the fade at the bottom of the hero.
+
+### Bare React Native
+
+```sh
+npm install react-native-reanimated react-native-worklets react-native-safe-area-context
+# optional, for the gradient fade:
+npx install-expo-modules@latest && npm install expo-linear-gradient
+cd ios && pod install
+```
+
+Add the Babel plugin. It **must be listed last**:
+
+```js
+// babel.config.js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: [
+    // Reanimated 4.x:
+    'react-native-worklets/plugin',
+    // Reanimated 3.x uses 'react-native-reanimated/plugin' instead
+  ],
+};
+```
+
+Then wrap your app in `SafeAreaProvider`:
+
+```tsx
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+
+export default function App() {
+  return <SafeAreaProvider>{/* ... */}</SafeAreaProvider>;
+}
+```
+
+| Peer dependency                  | Version                                             |
+| -------------------------------- | --------------------------------------------------- |
+| `react`                          | ≥ 18                                                |
+| `react-native`                   | ≥ 0.76                                              |
+| `react-native-reanimated`        | ≥ 3 (tested on 4.x; 4.x needs the New Architecture) |
+| `react-native-safe-area-context` | ≥ 4                                                 |
+| `expo-linear-gradient`           | optional                                            |
+
+> **No gradient library?** Pass `renderBackgroundFade` to draw the fade with any gradient component, such as `react-native-linear-gradient`. With neither installed, no fade is drawn. The package loads `expo-linear-gradient` through a `require` inside `try/catch`, which Metro treats as an optional dependency.
+
+## Quick start
+
+```tsx
+import Ionicons from '@expo/vector-icons/Ionicons';
+import { CollapsibleStickyHeaderScreen } from 'react-native-collapsible-sticky-header';
+
+export function HomeScreen() {
+  return (
+    <CollapsibleStickyHeaderScreen
+      backgroundImage={require('./hero.jpg')}
+      logo={require('./logo.png')}
+      greeting="Welcome back"
+      title="Ava Thompson"
+      actions={[
+        {
+          key: 'cart',
+          accessibilityLabel: 'Cart',
+          badgeCount: 3,
+          icon: ({ color, size }) => (
+            <Ionicons name="bag-outline" color={color} size={size} />
+          ),
+          onPress: openCart,
+        },
+      ]}
+      scrollProps={{
+        data: products,
+        keyExtractor: (p) => p.id,
+        renderItem: ({ item }) => <ProductRow product={item} />,
+      }}
+    />
+  );
+}
+```
+
+## How it works
+
+```
+┌──────────────────────────────┐  ← sticky compact bar (absolute, zIndex 20)
+│ [logo]          (🔔) (👜³)   │     opacity 0→1 over [threshold-40, threshold]
+└──────────────────────────────┘     touchable once y ≥ threshold-20
+┌──────────────────────────────┐  ← list header
+│  hero image / color / custom │
+│ [LOGO]          (🔔) (👜³)   │  ← expanded nav bar, measured with onLayout
+│ Welcome back                 │  ← collapsible block: opacity 1→0,
+│ Ava Thompson          (👤)   │     translateY 0→-12 over [0, threshold]
+│░░░░░░░ fade ░░░░░░░░░░░░░░░░░│  ← background overhangs by 60px and fades out
+└──────────────────────────────┘
+  list items…
+```
+
+`threshold = safeAreaTop + navBarHeight + thresholdOffset`. Until the nav bar has been measured, the threshold is `0` and the sticky bar stays hidden.
+
+## Props
+
+All props are optional except `scrollProps` for list types.
+
+### Scroll container
+
+| Prop              | Type                                                       | Default                 | Description                                                                                                                                                          |
+| ----------------- | ---------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `as`              | `'FlatList' \| 'ScrollView' \| 'SectionList' \| Component` | `'FlatList'`            | Scroll container. A custom component must be Animated (`Animated.createAnimatedComponent`).                                                                          |
+| `scrollProps`     | props of the container                                     |                         | Passed through. `onScroll` is merged (it runs on the JS thread). `refreshControl` and `contentContainerStyle` work as usual. `scrollEventThrottle` defaults to `16`. |
+| `listRef`         | `Ref`                                                      |                         | Forwarded to the scrollable, for example to call `scrollToOffset`.                                                                                                   |
+| `headerPlacement` | `'ListHeaderComponent' \| 'children'`                      | `'ListHeaderComponent'` | Custom scrollables only.                                                                                                                                             |
+
+### Background
+
+| Prop                   | Type                                       | Default                                          | Description                                                                  |
+| ---------------------- | ------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `backgroundImage`      | `ImageSourcePropType`                      |                                                  | Optional hero image.                                                         |
+| `backgroundColor`      | `string`                                   | `theme.colors.headerBg` (`'transparent'`)        | Shown with no image, or behind it.                                           |
+| `backgroundStyle`      | `ViewStyle`                                |                                                  | Background container.                                                        |
+| `backgroundImageStyle` | `ImageStyle`                               |                                                  | The image (`opacity`, `resizeMode`…).                                        |
+| `renderBackground`     | `(ctx) => ReactNode`                       |                                                  | Replaces the image entirely. Receives `{ theme, insets, collapseProgress }`. |
+| `backgroundOverhang`   | `number`                                   | `60` (`0` when rounded)                          | How far the background extends below the header.                             |
+| `headerBottomRadius`   | `number`                                   | `theme.radius.headerBottom` (`0`)                | Rounds the bottom corners and clips the header.                              |
+| `showFade`             | `boolean`                                  | `true`, or `false` when `headerBottomRadius > 0` | Gradient fade at the bottom of the background.                               |
+| `fadeColors`           | `[string, string]`                         | `['transparent', '#ffffff']`                     |                                                                              |
+| `fadeHeight`           | `number`                                   | `60`                                             |                                                                              |
+| `renderBackgroundFade` | `({ colors, height, style }) => ReactNode` |                                                  | Draws the fade with any gradient component.                                  |
+
+### Header content
+
+| Prop                                             | Type                                             | Default                          | Description                                                                    |
+| ------------------------------------------------ | ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------ |
+| `logo`                                           | `ImageSourcePropType \| ReactNode`               |                                  | Expanded-bar logo.                                                             |
+| `stickyLogo`                                     | `ImageSourcePropType \| ReactNode \| false`      | `logo`                           | Compact-bar logo. `false` hides it in the sticky bar only.                     |
+| `logoSize`                                       | `{ expanded?, compact? }`                        | `100×75` / `64×48`               |                                                                                |
+| `logoStyle`                                      | `ImageStyle \| ViewStyle`                        |                                  |                                                                                |
+| `logoAccessibilityLabel`                         | `string`                                         |                                  |                                                                                |
+| `onLogoPress`                                    | `(variant) => void`                              |                                  | Makes the logo a button, for example to scroll to the top from the sticky bar. |
+| `greeting` / `title` / `subtitle`                | `ReactNode`                                      |                                  | Strings are rendered as styled `Text`.                                         |
+| `greetingStyle` / `titleStyle` / `subtitleStyle` | `TextStyle`                                      |                                  |                                                                                |
+| `avatar`                                         | `ImageSourcePropType \| ReactNode`               |                                  | Profile picture or any element.                                                |
+| `avatarPosition`                                 | `'left' \| 'right'`                              | `'right'`                        |                                                                                |
+| `avatarSize`                                     | `number`                                         | `theme.avatarSize` (`44`)        |                                                                                |
+| `avatarStyle`                                    | `ImageStyle \| ViewStyle`                        |                                  |                                                                                |
+| `onAvatarPress`                                  | `() => void`                                     |                                  | Makes the avatar a button.                                                     |
+| `avatarAccessibilityLabel`                       | `string`                                         | `'Profile'`                      |                                                                                |
+| `stickyTitle`                                    | `ReactNode`                                      |                                  | Text in the compact bar, next to or instead of the logo.                       |
+| `stickyTitleStyle`                               | `TextStyle`                                      |                                  |                                                                                |
+| `stickyContent`                                  | `('logo' \| 'title' \| 'avatar' \| 'actions')[]` | `['logo', 'title', 'actions']`   | What the sticky (collapsed) bar shows. Leading items follow this order.        |
+| `stickyAvatarSize`                               | `number`                                         | `theme.avatarSizeCompact` (`32`) | Avatar size in the sticky bar (when `stickyContent` includes `'avatar'`).      |
+| `stickyAvatarStyle`                              | `ImageStyle \| ViewStyle`                        |                                  |                                                                                |
+| `actions`                                        | `HeaderAction[]`                                 | `[]`                             | Icon buttons, **max 3**. See [Actions](#actions-icon-buttons).                 |
+
+### Slots
+
+Each render prop receives `{ progress, isSticky, variant, theme, insets, actions }`. `progress` is a `SharedValue<number>` from 0 to 1. It holds collapse progress for the expanded slots and sticky-reveal progress for the sticky slot.
+
+| Prop                     | Default                                                                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `renderExpandedNav`      | `<HeaderNavBar variant="overlay" logo actions />`. It is measured and defines the threshold.                                                    |
+| `renderCollapsible`      | `<HeaderGreeting greeting title subtitle avatar />`                                                                                             |
+| `renderStickyNav`        | `<HeaderNavBar variant="solid" logo={stickyLogo} title={stickyTitle} show={stickyContent} actions />`                                           |
+| `renderStickyBackground` | None. Draws a gradient, image or blur behind the sticky bar's content. The bar's color becomes transparent unless `stickyBarBackground` is set. |
+| `children`               | Extra content **inside** the header, on the background.                                                                                         |
+| `ListHeaderExtra`        | Extra content **after** the header, on the page background.                                                                                     |
+
+### Behavior
+
+| Prop                  | Type                                       | Default                               | Description                                                                       |
+| --------------------- | ------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------------------- |
+| `thresholdOffset`     | `number`                                   | `0`                                   | Added to the measured threshold.                                                  |
+| `stickyFadeDistance`  | `number`                                   | `40`                                  | Distance over which the sticky bar fades in.                                      |
+| `stickyPointerOffset` | `number`                                   | `20`                                  | The sticky bar becomes touchable at `threshold - offset`.                         |
+| `collapseTranslateY`  | `number`                                   | `-12`                                 |                                                                                   |
+| `collapseAnimation`   | `(progress) => style` (worklet)            |                                       | Replaces the collapsible block's animation.                                       |
+| `stickyAnimation`     | `(progress) => style` (worklet)            | fade                                  | Replaces the sticky bar's animation.                                              |
+| `respectSafeArea`     | `boolean`                                  | `true`                                | Pads the header and sticky bar by the top inset and includes it in the threshold. |
+| `enteringAnimations`  | `boolean \| { duration, stagger, easing }` | `650 / 70 / Easing.out(Easing.cubic)` | Mount animation (`FadeInUp`). Pass `false` to disable it.                         |
+| `onStickyChange`      | `(isSticky) => void`                       |                                       | Fires once per transition.                                                        |
+
+### Styling
+
+| Prop                  | Type                             | Default                                                      |
+| --------------------- | -------------------------------- | ------------------------------------------------------------ |
+| `theme`               | `DeepPartial<StickyHeaderTheme>` | see [Theming](#theming)                                      |
+| `stickyBarStyle`      | `ViewStyle`                      |                                                              |
+| `stickyBarBackground` | `string`                         | `theme.colors.stickyBg` (`'#ffffff'`)                        |
+| `stickyShadow`        | `boolean \| ShadowStyle`         | `true` (opacity 0.08, radius 6, offset `{0,2}`, elevation 4) |
+| `containerStyle`      | `ViewStyle`                      |                                                              |
+| `headerStyle`         | `ViewStyle`                      |                                                              |
+
+## Actions (icon buttons)
+
+```ts
+type HeaderAction = {
+  key: string;
+  icon:
+    | ReactNode
+    | ((p: {
+        color: string;
+        size: number;
+        variant: 'overlay' | 'solid';
+      }) => ReactNode);
+  onPress: () => void;
+  accessibilityLabel: string; // required
+  accessibilityHint?: string;
+  badgeCount?: number;
+  color?: string; // per-icon override of the theme color
+  size?: number; // per-icon override of theme.iconSize
+  style?: StyleProp<ViewStyle>; // the 36×36 round hit area
+  hidden?: boolean;
+  showInSticky?: boolean; // default true
+  testID?: string;
+};
+```
+
+- **0 to 3 actions** are valid (`MAX_HEADER_ACTIONS = 3`). Only the first 3 visible actions render. Passing more logs a `__DEV__` warning.
+- No icon library is bundled. Use `@expo/vector-icons`, `react-native-vector-icons`, SVG, or an `Image`.
+- The function form receives the variant's color and size, so one icon definition works in both bars.
+- A badge shows `9+` when the count is above 9.
+
+## Theming
+
+Pass a partial theme. It is deep-merged over the defaults, and props take priority over the theme.
+
+```ts
+const theme: StickyHeaderThemeOverrides = {
+  colors: {
+    stickyBg: '#ffffff', // compact bar
+    headerBg: 'transparent', // header background when there is no image
+    iconOverlay: '#ffffff', // icons on the hero
+    iconSolid: '#1f2937', // icons on the compact bar
+    actionBgOverlay: 'transparent',
+    actionBgSolid: 'transparent',
+    badge: '#ef4444',
+    badgeText: '#ffffff',
+    badgeBorder: '#ffffff',
+    greeting: '#ffffff',
+    title: '#ffffff',
+    subtitle: 'rgba(255,255,255,0.85)',
+    stickyTitle: '#111827',
+    fade: ['transparent', '#ffffff'],
+    shadow: '#000000',
+  },
+  spacing: {
+    horizontal: 16,
+    actionGap: 8,
+    avatarGap: 12,
+    leadingGap: 8, // logo / avatar / title gap in the nav bar
+    navBar: {
+      overlay: { paddingHorizontal: 16, paddingVertical: 8 },
+      solid: { paddingHorizontal: 16, paddingVertical: 4 },
+    },
+  },
+  radius: { headerBottom: 0 },
+  pressedOpacity: 0.6,
+  iconSize: 22,
+  actionSize: 36,
+  avatarSize: 44,
+  badgeSize: 18,
+  logoSize: {
+    expanded: { width: 100, height: 75 },
+    compact: { width: 64, height: 48 },
+  },
+  typography: {
+    greetingSize: 14,
+    titleSize: 24,
+    subtitleSize: 14,
+    stickyTitleSize: 17,
+  },
+};
+```
+
+`createTheme(...partials)` returns a fully resolved theme. Example brand theme (amber and white):
+
+```ts
+const beanBrewTheme = {
+  colors: { iconSolid: '#d97706', badge: '#f59e0b', greeting: '#fde7c7' },
+};
+```
+
+## Recipes
+
+### Customize the collapsed header
+
+The collapsed header is the compact bar that appears once the expanded header scrolls away.
+
+**Color:**
+
+```tsx
+<CollapsibleStickyHeaderScreen
+  stickyBarBackground="#4f46e5"            // or theme.colors.stickyBg
+  theme={{
+    colors: {
+      iconSolid: '#ffffff',                // icons in the collapsed bar
+      actionBgSolid: 'rgba(255,255,255,0.16)',
+      stickyTitle: '#ffffff',              // stickyTitle text
+    },
+  }}
+  stickyBarStyle={{ borderBottomWidth: 1, borderBottomColor: '#3730a3' }}
+  stickyShadow={false}
+  …
+/>
+```
+
+**Content:** choose the items and their order. Actions always sit on the right.
+
+```tsx
+<CollapsibleStickyHeaderScreen
+  avatar={{ uri: user.photoUrl }}
+  stickyTitle="Ava's tasks"
+  stickyContent={['avatar', 'title', 'actions']}   // no logo in the collapsed bar
+  stickyAvatarSize={32}
+  actions={[
+    search,
+    { ...settings, showInSticky: false },          // expanded bar only
+  ]}
+  …
+/>
+```
+
+To keep the same layout but drop the logo, use `stickyLogo={false}`. To show a smaller or different mark, pass `stickyLogo={require('./mark.png')}`.
+
+**Gradient, image or blur background:**
+
+```tsx
+<CollapsibleStickyHeaderScreen
+  renderStickyBackground={() => (
+    <LinearGradient colors={['#4f46e5', '#7c3aed']} style={StyleSheet.absoluteFill} />
+  )}
+  …
+/>
+```
+
+**Animated color**, for example transparent → solid while the bar appears:
+
+```tsx
+import { interpolateColor } from 'react-native-reanimated';
+
+const colorIn = (p: number) => {
+  'worklet';
+  return {
+    opacity: p,
+    backgroundColor: interpolateColor(p, [0, 1], ['rgba(79,70,229,0)', '#4f46e5']),
+  };
+};
+
+<CollapsibleStickyHeaderScreen stickyAnimation={colorIn} … />
+```
+
+**Anything else:** `renderStickyNav={({ isSticky, theme }) => <MyBar />}` replaces the bar's content entirely. The bar container, safe-area padding, animation and accessibility handling stay in place.
+
+### "Fade" vs "slide" sticky bar
+
+The default sticky bar fades in. To slide it down from the top instead:
+
+```tsx
+import { slideStickyAnimation } from 'react-native-collapsible-sticky-header';
+
+<CollapsibleStickyHeaderScreen stickyAnimation={slideStickyAnimation(110)} … />
+```
+
+Or write your own. **It must be a worklet**:
+
+```tsx
+const scaleIn = (p: number) => {
+  'worklet';
+  return { opacity: p, transform: [{ scale: 0.95 + p * 0.05 }] };
+};
+```
+
+### No background image
+
+```tsx
+<CollapsibleStickyHeaderScreen backgroundColor="#0f766e" title="Orders" … />
+// or no background at all (transparent): omit both
+```
+
+### Rounded header bottom
+
+```tsx
+<CollapsibleStickyHeaderScreen
+  backgroundColor="#4f46e5"
+  headerBottomRadius={24}   // also disables the fade and the overhang by default
+  headerStyle={{ paddingBottom: 20 }}
+  …
+/>
+```
+
+### Avatar + welcome text
+
+```tsx
+<CollapsibleStickyHeaderScreen
+  greeting="Welcome back,"
+  title="Ava Thompson"
+  subtitle="You have 6 tasks today"
+  avatar={{ uri: user.photoUrl }}   // or <Initials name="Ava" />
+  avatarPosition="left"
+  avatarSize={52}
+  onAvatarPress={openProfile}
+  …
+/>
+```
+
+### Custom icons (up to 3)
+
+```tsx
+actions={[
+  { key: 'search', accessibilityLabel: 'Search', onPress: search,
+    icon: ({ color, size }) => <SearchIcon color={color} width={size} height={size} /> },
+  { key: 'inbox', accessibilityLabel: 'Inbox', badgeCount: unread, onPress: openInbox,
+    icon: ({ color, size, variant }) =>
+      <Ionicons name={variant === 'overlay' ? 'mail' : 'mail-outline'} color={color} size={size} /> },
+  { key: 'settings', accessibilityLabel: 'Settings', onPress: openSettings, showInSticky: false,
+    icon: <Image source={require('./gear.png')} style={{ width: 22, height: 22 }} /> },
+]}
+```
+
+### Custom collapsible content
+
+```tsx
+import Animated, { useAnimatedStyle } from 'react-native-reanimated';
+
+function Stats({ progress }: { progress: SharedValue<number> }) {
+  const style = useAnimatedStyle(() => ({ transform: [{ scale: 1 - progress.value * 0.1 }] }));
+  return <Animated.View style={style}>{/* … */}</Animated.View>;
+}
+
+<CollapsibleStickyHeaderScreen renderCollapsible={({ progress }) => <Stats progress={progress} />} … />
+```
+
+### Custom scrollable (FlashList)
+
+```tsx
+const AnimatedFlashList = Animated.createAnimatedComponent(FlashList);
+
+<CollapsibleStickyHeaderScreen as={AnimatedFlashList} scrollProps={{ data, renderItem, estimatedItemSize: 72 }} … />
+```
+
+## Building blocks
+
+To build your own screen, use these pieces directly:
+
+```tsx
+import {
+  useStickyHeader,
+  HeaderNavBar,
+  HeaderGreeting,
+  Badge,
+} from 'react-native-collapsible-sticky-header';
+
+function MyScreen() {
+  const { scrollHandler, onNavLayout, collapseStyle, stickyStyle, isSticky } =
+    useStickyHeader({
+      thresholdOffset: 0,
+      stickyFadeDistance: 40,
+      stickyPointerOffset: 20,
+      onStickyChange: (s) => console.log(s),
+    });
+  return (
+    <View style={{ flex: 1 }}>
+      <Animated.ScrollView onScroll={scrollHandler} scrollEventThrottle={16}>
+        <View onLayout={onNavLayout}>
+          <HeaderNavBar variant="overlay" logo={logo} />
+        </View>
+        <Animated.View style={collapseStyle}>
+          <HeaderGreeting title="Hi" />
+        </Animated.View>
+        {/* … */}
+      </Animated.ScrollView>
+      <Animated.View
+        pointerEvents={isSticky ? 'auto' : 'none'}
+        style={[styles.bar, stickyStyle]}
+      >
+        <HeaderNavBar variant="solid" logo={logo} />
+      </Animated.View>
+    </View>
+  );
+}
+```
+
+`useStickyHeader` returns `{ scrollHandler, scrollY, threshold, navBarHeight, collapseProgress, stickyProgress, collapseStyle, stickyStyle, isSticky, onNavLayout, updateScrollY, topInset, reducedMotion }`. `updateScrollY(y)` is a worklet that feeds offsets from a scrollable you drive yourself.
+
+Also exported: `Badge` (`count`, `max = 9`, `color`, `borderColor`, `textColor`, `size`, `showZero`), `createTheme`, `defaultTheme`, `MAX_HEADER_ACTIONS`, the pure worklets `computeThreshold`, `getCollapseProgress`, `getStickyProgress` and `isStickyAt`, and the animation presets `fadeStickyAnimation` and `slideStickyAnimation`.
+
+## Accessibility & performance
+
+- Every action is a `Pressable` with `accessibilityRole="button"` and a **required** `accessibilityLabel`. A badge count is announced through `accessibilityValue`.
+- While hidden, the sticky bar has `pointerEvents="none"`, `importantForAccessibility="no-hide-descendants"` (Android) and `accessibilityElementsHidden` (iOS).
+- When reduced motion is enabled (`useReducedMotion()`), entering animations are skipped, the sticky bar appears instantly and the collapsible block only fades.
+- Scroll is handled by `useAnimatedScrollHandler` on the UI thread. The component crosses to JS (`runOnJS`) only when the sticky state flips, so scrolling causes **no React re-renders**.
+- Slots are memoized. If you pass inline `theme` objects or `actions` arrays, wrap them in `useMemo` to avoid needless header re-renders when the parent re-renders.
+- Passing `scrollProps.onScroll` makes every scroll frame call into JS. Prefer `onStickyChange` or `useStickyHeader().scrollY`.
+
+## Example app
+
+`example/` is an Expo app with three screens:
+
+1. **Bean Brew**: hero image, greeting, logo, bell and bag icons with a cart badge, and pull-to-refresh. Tap the compact logo to scroll to the top.
+2. **Slide**: a `ScrollView` with a slide-down sticky bar.
+3. **Rounded**: no image, a solid color, `headerBottomRadius={24}`, an avatar with welcome text, and 3 custom actions.
+
+```sh
+npm install
+cd example && npm install
+npx expo start          # press i for iOS, a for Android
+# or a native build:
+npx expo run:ios
+npx expo run:android
+```
+
+The example resolves the library from `../src` through `metro.config.js`, so edits show up immediately.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Machine-readable summary
+
+AI assistants and tools can read [`llms.txt`](llms.txt) for a compact API summary.
+
+## License
+
+MIT

package/lib/commonjs/Badge.js

@@ -0,0 +1,65 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Badge = void 0;
+var _react = require("react");
+var _reactNative = require("react-native");
+var _theme = require("./theme.js");
+var _utils = require("./utils.js");
+var _jsxRuntime = require("react/jsx-runtime");
+const Badge = exports.Badge = /*#__PURE__*/(0, _react.memo)(function Badge({
+  count,
+  max = _utils.DEFAULT_BADGE_MAX,
+  color = _theme.defaultTheme.colors.badge,
+  textColor = _theme.defaultTheme.colors.badgeText,
+  borderColor = _theme.defaultTheme.colors.badgeBorder,
+  borderWidth = 1.5,
+  size = _theme.defaultTheme.badgeSize,
+  showZero = false,
+  style,
+  textStyle,
+  testID = 'sticky-header-badge'
+}) {
+  const whole = Math.floor(count);
+  if (!Number.isFinite(whole) || whole < 0 || whole === 0 && !showZero) {
+    return null;
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    testID: testID,
+    pointerEvents: "none",
+    importantForAccessibility: "no-hide-descendants",
+    accessibilityElementsHidden: true,
+    style: [styles.badge, {
+      backgroundColor: color,
+      borderColor,
+      borderWidth,
+      minWidth: size,
+      height: size,
+      borderRadius: size / 2
+    }, style],
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+      numberOfLines: 1,
+      allowFontScaling: false,
+      style: [styles.text, {
+        color: textColor,
+        fontSize: Math.round(size * 0.55)
+      }, textStyle],
+      children: (0, _utils.formatBadgeCount)(whole, max)
+    })
+  });
+});
+const styles = _reactNative.StyleSheet.create({
+  badge: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 4
+  },
+  text: {
+    fontWeight: '700',
+    includeFontPadding: false,
+    textAlign: 'center'
+  }
+});
+//# sourceMappingURL=Badge.js.map

package/lib/commonjs/Badge.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_reactNative","_theme","_utils","_jsxRuntime","Badge","exports","memo","count","max","DEFAULT_BADGE_MAX","color","defaultTheme","colors","badge","textColor","badgeText","borderColor","badgeBorder","borderWidth","size","badgeSize","showZero","style","textStyle","testID","whole","Math","floor","Number","isFinite","jsx","View","pointerEvents","importantForAccessibility","accessibilityElementsHidden","styles","backgroundColor","minWidth","height","borderRadius","children","Text","numberOfLines","allowFontScaling","text","fontSize","round","formatBadgeCount","StyleSheet","create","alignItems","justifyContent","paddingHorizontal","fontWeight","includeFontPadding","textAlign"],"sourceRoot":"../../src","sources":["Badge.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AAQA,IAAAE,MAAA,GAAAF,OAAA;AACA,IAAAG,MAAA,GAAAH,OAAA;AAA8D,IAAAI,WAAA,GAAAJ,OAAA;AAoBvD,MAAMK,KAAK,GAAAC,OAAA,CAAAD,KAAA,gBAAG,IAAAE,WAAI,EAAC,SAASF,KAAKA,CAAC;EACvCG,KAAK;EACLC,GAAG,GAAGC,wBAAiB;EACvBC,KAAK,GAAGC,mBAAY,CAACC,MAAM,CAACC,KAAK;EACjCC,SAAS,GAAGH,mBAAY,CAACC,MAAM,CAACG,SAAS;EACzCC,WAAW,GAAGL,mBAAY,CAACC,MAAM,CAACK,WAAW;EAC7CC,WAAW,GAAG,GAAG;EACjBC,IAAI,GAAGR,mBAAY,CAACS,SAAS;EAC7BC,QAAQ,GAAG,KAAK;EAChBC,KAAK;EACLC,SAAS;EACTC,MAAM,GAAG;AACC,CAAC,EAAE;EACb,MAAMC,KAAK,GAAGC,IAAI,CAACC,KAAK,CAACpB,KAAK,CAAC;EAC/B,IAAI,CAACqB,MAAM,CAACC,QAAQ,CAACJ,KAAK,CAAC,IAAIA,KAAK,GAAG,CAAC,IAAKA,KAAK,KAAK,CAAC,IAAI,CAACJ,QAAS,EAAE;IACtE,OAAO,IAAI;EACb;EACA,oBACE,IAAAlB,WAAA,CAAA2B,GAAA,EAAC9B,YAAA,CAAA+B,IAAI;IACHP,MAAM,EAAEA,MAAO;IACfQ,aAAa,EAAC,MAAM;IACpBC,yBAAyB,EAAC,qBAAqB;IAC/CC,2BAA2B;IAC3BZ,KAAK,EAAE,CACLa,MAAM,CAACtB,KAAK,EACZ;MACEuB,eAAe,EAAE1B,KAAK;MACtBM,WAAW;MACXE,WAAW;MACXmB,QAAQ,EAAElB,IAAI;MACdmB,MAAM,EAAEnB,IAAI;MACZoB,YAAY,EAAEpB,IAAI,GAAG;IACvB,CAAC,EACDG,KAAK,CACL;IAAAkB,QAAA,eAEF,IAAArC,WAAA,CAAA2B,GAAA,EAAC9B,YAAA,CAAAyC,IAAI;MACHC,aAAa,EAAE,CAAE;MACjBC,gBAAgB,EAAE,KAAM;MACxBrB,KAAK,EAAE,CACLa,MAAM,CAACS,IAAI,EACX;QAAElC,KAAK,EAAEI,SAAS;QAAE+B,QAAQ,EAAEnB,IAAI,CAACoB,KAAK,CAAC3B,IAAI,GAAG,IAAI;MAAE,CAAC,EACvDI,SAAS,CACT;MAAAiB,QAAA,EAED,IAAAO,uBAAgB,EAACtB,KAAK,EAAEjB,GAAG;IAAC,CACzB;EAAC,CACH,CAAC;AAEX,CAAC,CAAC;AAEF,MAAM2B,MAAM,GAAGa,uBAAU,CAACC,MAAM,CAAC;EAC/BpC,KAAK,EAAE;IACLqC,UAAU,EAAE,QAAQ;IACpBC,cAAc,EAAE,QAAQ;IACxBC,iBAAiB,EAAE;EACrB,CAAC;EACDR,IAAI,EAAE;IACJS,UAAU,EAAE,KAAK;IACjBC,kBAAkB,EAAE,KAAK;IACzBC,SAAS,EAAE;EACb;AACF,CAAC,CAAC","ignoreList":[]}