/**
 * ScrollHeader — a screen header that hands over to a compact bar as the page
 * scrolls.
 *
 * A screen with a title has two states and every app draws both: the title
 * large, at rest, with room around it, and the title small, pinned, once you
 * are reading. Hand-rolling the change between them is where screens stop
 * matching each other — one snaps, one crossfades at a different point, one
 * forgets the bar is over a safe area — so the two states and the transit
 * between them are one component here.
 *
 * ```tsx
 * <ScrollHeader className="flex-1">
 *   <ScrollHeader.Bar>
 *     <ScrollHeader.Title>Library</ScrollHeader.Title>
 *     <ScrollHeader.Actions>
 *       <Button variant="ghost" size="icon"><SearchIcon size={18} /></Button>
 *     </ScrollHeader.Actions>
 *   </ScrollHeader.Bar>
 *   <ScrollHeader.Large>
 *     <ScrollHeader.Title>Library</ScrollHeader.Title>
 *     <ScrollHeader.Description>128 components</ScrollHeader.Description>
 *   </ScrollHeader.Large>
 *   <ScrollView>{rows}</ScrollView>
 * </ScrollHeader>
 * ```
 *
 * ## The band collapses; nothing inside it is animated up
 *
 * The header is one absolutely positioned band over the scroller, and the only
 * thing driven by the scroll is its height: `bar + max(0, large - offset)`.
 * The bar is anchored to its top and the large block to its bottom, so the
 * band shrinking is what carries the large block up and behind the bar, and
 * `overflow-hidden` is what cuts it off there.
 *
 * Driving the height rather than a `translateY` is what makes the rest fall
 * out for free. Over-scrolling makes `large - offset` larger than `large`, so
 * the band grows and a cover filling it stretches by being laid out bigger —
 * no scale transform, so a photograph stretches without going soft. And the
 * band's height is the inset the content needs, so there is one number rather
 * than two that have to agree.
 *
 * ## The two titles cross-fade; neither one morphs
 *
 * The large title and the bar title are separate elements that fade past each
 * other. A single title scaled and translated between the two positions tracks
 * beautifully until the text is long enough to truncate, at which point it is
 * animating between two different strings.
 *
 * Both are therefore in the tree at once, which is a problem for a screen
 * reader — one of them is invisible and would still be read. So the crossing
 * point is also published to React as `collapsed`, and whichever title is not
 * being shown is hidden from accessibility. That is one re-render per crossing
 * and no more: everything that runs per frame stays in shared values.
 *
 * ## The bar's surface is a fill, or a frost
 *
 * `surface` says what the bar is drawn on once it has taken over: a token
 * fill, nothing at all over a cover, or `blur` — a real material, so the rows
 * passing under the bar stay legible as shape and colour while losing the
 * detail that would compete with the title on top.
 *
 * The frost needs a native view, and there are two ways it cannot be drawn:
 * `expo-blur` is optional and may not be installed, and Reduce Transparency is
 * a preference that outranks the design. Both fall back to the plain
 * background token rather than to nothing, because a bar you cannot read is a
 * worse answer than a bar that is not frosted.
 *
 * ## What it needs
 *
 * A height to fill, and exactly one scrollable child. The child is cloned with
 * the scroll handler and the content inset composed onto it, the same way
 * `ScrollFade` wraps one, so a `ScrollView`, a `FlatList` or a `SectionList`
 * all work unchanged.
 */
import {
  Children,
  createContext,
  forwardRef,
  isValidElement,
  useCallback,
  useContext,
  useMemo,
  useState,
  type ComponentType,
  type ReactNode,
  type Ref,
} from 'react';
import {
  Image,
  Platform,
  StyleSheet,
  View,
  type ImageSourcePropType,
  type LayoutChangeEvent,
  type NativeScrollEvent,
  type NativeSyntheticEvent,
  type StyleProp,
  type Text as RNText,
  type ViewProps,
  type ViewStyle,
} from 'react-native';
import { LinearGradient } from 'expo-linear-gradient';
import Animated, {
  interpolate,
  runOnJS,
  scrollTo,
  useAnimatedReaction,
  useAnimatedRef,
  useAnimatedScrollHandler,
  useAnimatedStyle,
  useComposedEventHandler,
  useDerivedValue,
  useReducedMotion,
  useSharedValue,
  withTiming,
  type AnimatedScrollViewProps,
  type SharedValue,
} from 'react-native-reanimated';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import { tv, type VariantProps } from 'tailwind-variants';
import { useCSSVariable } from 'uniwind';
import { hasBlur, useReduceTransparency } from '../../primitives/scrim';
import { Text, textChildren, type TextProps } from '../../primitives/text';
import { useThemeMode } from '../../theme/use-theme';
import { cn } from '../../utils/cn';
import {
  BAR_TITLE_ARRIVE,
  HANDOVER_DURATION,
  LARGE_EXIT,
  SURFACE_ARRIVE,
  bandHeight,
  collapseProgress,
  contentInset,
  hasSpan,
  isCrossing,
  snapTarget,
} from './scroll-header-math';

/**
 * Height of the pinned bar, in points, before the device's top inset is added.
 * The platform navigation bars are 44 and 56; 48 is the target-size floor the
 * rest of the library holds compact controls to, and it sits between them.
 */
const BAR_HEIGHT = 48;

/**
 * The scrollables Reanimated already animates. Its animated components are
 * ordinary function components carrying the *inner* component's name, so there
 * is nothing on one to test — but these two are module-level constants, and
 * identity is exact.
 */
/** Which way the frost tints. `default` follows the app's theme. */
export type ScrollHeaderMaterial = 'light' | 'dark' | 'default';

/**
 * `expo-blur`'s BlurView, or null when it is not installed. Resolved once at
 * module load — the require is cheap and caching it avoids a try/catch on
 * every render.
 */
const BlurView: ComponentType<{
  intensity?: number;
  tint?: ScrollHeaderMaterial;
  style?: unknown;
}> | null = (() => {
  try {
    // eslint-disable-next-line @typescript-eslint/no-require-imports
    const mod = require('expo-blur');
    return (mod?.BlurView as ComponentType<{ intensity?: number }>) ?? null;
  } catch {
    return null;
  }
})();

/**
 * Depth of the frost. Heavier than a scrim's, because a scrim covers a whole
 * screen and this is a thin band read against content that is moving under it.
 */
const DEFAULT_BLUR_INTENSITY = 40;

const ANIMATED_SCROLLABLES = new Set<unknown>([Animated.ScrollView, Animated.FlatList]);

const scrollHeaderVariants = tv({
  slots: {
    root: 'flex-1',
    band: 'absolute inset-x-0 top-0 overflow-hidden',
    cover: 'absolute inset-0',
    bar: 'absolute inset-x-0 top-0 flex-row items-center gap-3 px-4',
    barSurface: 'absolute inset-0',
    large: 'absolute inset-x-0 bottom-0 gap-1 px-4 pb-3',
    actions: 'ml-auto flex-row items-center gap-1',
  },
  variants: {
    /** What the bar is drawn on once it has taken over. */
    surface: {
      plain: { barSurface: 'bg-background' },
      muted: { barSurface: 'bg-card' },
      none: { barSurface: 'bg-transparent' },
      // No fill of its own: an opaque colour behind the material is part of
      // what the material samples, so a frost over one is a flat bar that has
      // paid for a native view.
      blur: { barSurface: 'bg-transparent' },
    },
    divider: {
      true: { barSurface: 'border-b border-border' },
      false: {},
    },
  },
  defaultVariants: {
    surface: 'plain',
    divider: true,
  },
});

type ScrollHeaderVariantProps = VariantProps<typeof scrollHeaderVariants>;

/** What the bar is drawn on once the large block has gone. */
export type ScrollHeaderSurface = NonNullable<ScrollHeaderVariantProps['surface']>;

/** Which half of the header a part is standing in. */
export type ScrollHeaderSlot = 'bar' | 'large';

interface ScrollHeaderContextValue {
  /** 0 while the large block is whole, 1 once the bar has taken over. */
  progress: SharedValue<number>;
  /** Distance scrolled, in points. Negative while the finger pulls down. */
  offset: SharedValue<number>;
  /** Measured height of the large block. */
  largeHeight: SharedValue<number>;
  /** The crossing point, published to React for accessibility. */
  collapsed: boolean;
  /** Whether there is a large block at all. A bar-only header has no crossing. */
  hasLarge: boolean;
  measureLarge: (event: LayoutChangeEvent) => void;
}

const ScrollHeaderContext = createContext<ScrollHeaderContextValue | undefined>(undefined);

function useScrollHeader(component: string): ScrollHeaderContextValue {
  const context = useContext(ScrollHeaderContext);
  if (!context) throw new Error(`${component} must be used within a <ScrollHeader>`);
  return context;
}

/**
 * Which half a part is in. `Title` reads it to know which size to be and which
 * way to fade, so the same element can be written in both places.
 */
const ScrollHeaderSlotContext = createContext<ScrollHeaderSlot>('large');

interface ScrollableProps {
  onScroll?: AnimatedScrollViewProps['onScroll'];
  contentContainerStyle?: StyleProp<ViewStyle>;
  scrollIndicatorInsets?: { top?: number; bottom?: number; left?: number; right?: number };
  scrollEventThrottle?: number;
  contentInsetAdjustmentBehavior?: AnimatedScrollViewProps['contentInsetAdjustmentBehavior'];
  ref?: Ref<unknown>;
}

export interface ScrollHeaderProps extends ViewProps {
  className?: string;
  /**
   * Height of the pinned bar in points, before the device's top inset. The
   * inset is added on top of this rather than taken out of it, so the bar's
   * contents keep this much room on every device.
   */
  barHeight?: number;
  /**
   * How much of the large block has to leave before the bar has fully taken
   * over, as a fraction of its height. Below 1 the crossing happens early,
   * which suits a tall block whose last few points are not worth waiting for.
   */
  threshold?: number;
  /**
   * Settle a part-scrolled band open or closed when the finger lifts, rather
   * than leaving the header half-collapsed.
   */
  snap?: boolean;
  /**
   * Let the band grow past its resting height when the scroller is pulled
   * down. A cover fills the band, so this is what stretches it. Off under
   * Reduce Motion.
   */
  stretch?: boolean;
  /** Add the device's top inset above the bar. Off inside a screen that already has one. */
  inset?: boolean;
  /**
   * Called as the bar takes over, and again when the large block comes back.
   * Fires on the crossing, not on every frame.
   */
  onCollapsedChange?: (collapsed: boolean) => void;
  /**
   * A shared value to mirror the collapse into, 0 to 1, for animating
   * something outside the header against the same transition.
   */
  progress?: SharedValue<number>;
  /** The parts, and exactly one scrollable. */
  children?: ReactNode;
}

/**
 * The band, and the scroller it sits over. Everything that is not a part is
 * treated as the scrollable child.
 */
const ScrollHeaderRoot = forwardRef<View, ScrollHeaderProps>(
  (
    {
      className,
      barHeight = BAR_HEIGHT,
      threshold = 1,
      snap = true,
      stretch = true,
      inset = true,
      onCollapsedChange,
      progress: externalProgress,
      children,
      ...props
    },
    ref
  ) => {
    const insets = useSafeAreaInsets();
    const reducedMotion = useReducedMotion();
    const insetTop = inset ? insets.top : 0;
    const barBand = insetTop + barHeight;

    const offset = useSharedValue(0);
    const largeHeight = useSharedValue(0);
    const [largeSize, setLargeSize] = useState(0);
    const [collapsed, setCollapsed] = useState(false);

    const scrollRef = useAnimatedRef<Animated.ScrollView>();

    // Measured into both a shared value, for the band's height, and React
    // state, for the content inset — the inset is a resting number that only
    // changes when the block is re-laid-out, so paying a render for it costs
    // nothing per frame and keeps the scroller's props stable.
    const measureLarge = useCallback((event: LayoutChangeEvent) => {
      const { height } = event.nativeEvent.layout;
      largeHeight.value = height;
      setLargeSize((previous) => (Math.abs(previous - height) < 0.5 ? previous : height));
    }, [largeHeight]);

    const progress = useDerivedValue(() => {
      const next = collapseProgress(offset.value, largeHeight.value, threshold);
      // A header with a block hands over across that block's height, and the
      // finger sets the pace. One without has no distance to interpolate over,
      // so the step is timed rather than instant — the alternative is a bar
      // whose surface appears between one frame and the next.
      const value = hasSpan(largeHeight.value)
        ? next
        : withTiming(next, { duration: HANDOVER_DURATION });
      if (externalProgress) externalProgress.value = value;
      return value;
    }, [threshold, externalProgress]);

    // The one thing the transition tells React about. `collapsed` gates the
    // accessibility of the two titles and is what `onCollapsedChange` reports;
    // the reaction fires on the crossing, not on the frames either side of it.
    const cross = useCallback(
      (next: boolean) => {
        setCollapsed(next);
        onCollapsedChange?.(next);
      },
      [onCollapsedChange]
    );

    useAnimatedReaction(
      () => progress.value >= 1,
      (isCollapsed, was) => {
        if (!isCrossing(isCollapsed, was)) return;
        runOnJS(cross)(isCollapsed);
      },
      [cross]
    );

    const settle = useCallback(
      (velocity: number) => {
        'worklet';
        if (!snap) return;
        const target = snapTarget(offset.value, largeHeight.value, velocity);
        if (target === null) return;
        scrollTo(scrollRef, 0, target, true);
      },
      [snap, largeHeight, offset, scrollRef]
    );

    const { parts, scrollable } = useMemo(() => splitChildren(children), [children]);

    const childType = isValidElement(scrollable)
      ? (scrollable.type as ComponentType<ScrollableProps>)
      : null;
    // Keyed on the element type rather than the element: rebuilding the
    // wrapper would remount the list and lose its scroll position. A child
    // that is animated already is used as it stands — wrapping one twice is
    // unsupported, and there is no marker on them to test for, so the two
    // that exist are recognised by identity.
    const AnimatedScrollable = useMemo(() => {
      if (!childType) return null;
      if (ANIMATED_SCROLLABLES.has(childType)) return childType;
      return Animated.createAnimatedComponent(childType);
    }, [childType]);

    const childProps = (isValidElement(scrollable) ? scrollable.props : {}) as ScrollableProps;
    const childOnScroll = childProps.onScroll;

    /*
     * A consumer's own `onScroll` is kept, whichever of the two kinds it is,
     * because silently dropping one looks like a bug in the scrolling rather
     * than in the call site.
     *
     * `useEvent` returns an object wearing a function's type, so the two are
     * told apart by what they actually are: an object is a Reanimated handler
     * and composes onto ours, staying on the UI thread. A plain function
     * cannot — `useComposedEventHandler` keeps only worklet handlers and drops
     * anything else without a word — so it is called across the bridge
     * instead, once per scroll event the child delivers. How often that is, is
     * `scrollEventThrottle`'s answer rather than this component's: every frame
     * at the default of 16, and as rare as the caller asks for above it.
     */
    const workletOnScroll = typeof childOnScroll === 'function' ? null : childOnScroll ?? null;
    const plainOnScroll = typeof childOnScroll === 'function' ? childOnScroll : null;

    // Rebuilt only when the callback itself changes, so the worklet below is
    // not rebuilt on every render of the child.
    const forwardScroll = useCallback(
      (native: NativeScrollEvent) => {
        // The `nativeEvent` crosses whole; the synthetic wrapper around it does
        // not, because the rest of one is a live object with methods on it.
        plainOnScroll?.({ nativeEvent: native } as NativeSyntheticEvent<NativeScrollEvent>);
      },
      [plainOnScroll]
    );
    const forwards = plainOnScroll !== null;

    const scrollHandler = useAnimatedScrollHandler(
      {
        onScroll: (event) => {
          offset.value = event.contentOffset.y;
          if (forwards) {
            // Every field React Native puts on a scroll event, so a callback
            // reading `velocity` for a direction, or `targetContentOffset` for
            // where a fling is going, finds what it would have without the
            // header. Listed rather than spread: the event carries Reanimated's
            // own `eventName` too, and that is not part of the contract.
            runOnJS(forwardScroll)({
              contentInset: event.contentInset,
              contentOffset: event.contentOffset,
              contentSize: event.contentSize,
              layoutMeasurement: event.layoutMeasurement,
              velocity: event.velocity,
              zoomScale: event.zoomScale,
              targetContentOffset: event.targetContentOffset,
            } as NativeScrollEvent);
          }
        },
        onEndDrag: (event) => {
          settle(event.velocity?.y ?? 0);
        },
        onMomentumEnd: () => {
          settle(0);
        },
      },
      [settle, forwards, forwardScroll]
    );

    const onScroll = useComposedEventHandler([
      scrollHandler,
      (workletOnScroll as typeof scrollHandler | null) ?? null,
    ]);

    /*
     * The band's resting height, plus whatever top padding the child asked
     * for. A style array overrides rather than adds, so composing ours after
     * theirs would drop their padding and composing theirs after ours would
     * drop the inset — and they cannot write the sum themselves, because the
     * band's height is measured. Reading it and adding is the only
     * arrangement where both survive.
     */
    const childContentStyle = StyleSheet.flatten(childProps.contentContainerStyle) ?? {};
    const headerHeight = contentInset(
      barBand + largeSize,
      childContentStyle.paddingTop ??
        childContentStyle.paddingVertical ??
        childContentStyle.padding
    );

    const bandStyle = useAnimatedStyle(
      () => ({
        height: bandHeight(barBand, largeHeight.value, offset.value, stretch && !reducedMotion),
      }),
      [barBand, stretch, reducedMotion]
    );

    const metrics = useMemo<BandMetrics>(
      () => ({ barBand, insetTop }),
      [barBand, insetTop]
    );

    const hasLarge = largeSize >= 1;

    const context = useMemo<ScrollHeaderContextValue>(
      () => ({ progress, offset, largeHeight, collapsed, hasLarge, measureLarge }),
      [progress, offset, largeHeight, collapsed, hasLarge, measureLarge]
    );

    const { root, band } = scrollHeaderVariants();

    return (
      <ScrollHeaderContext.Provider value={context}>
        <View {...props} ref={ref} className={root({ className })}>
          {AnimatedScrollable && isValidElement(scrollable) ? (
            <AnimatedScrollable
              {...childProps}
              ref={composeRefs(scrollRef, childProps.ref)}
              onScroll={onScroll}
              scrollEventThrottle={childProps.scrollEventThrottle ?? 16}
              // The band is the inset. iOS would otherwise add one of its own
              // on top of it, for a header it cannot see.
              contentInsetAdjustmentBehavior={
                childProps.contentInsetAdjustmentBehavior ?? 'never'
              }
              contentContainerStyle={[
                childProps.contentContainerStyle,
                { paddingTop: headerHeight },
              ]}
              scrollIndicatorInsets={{ top: barBand, ...childProps.scrollIndicatorInsets }}
            />
          ) : (
            scrollable
          )}

          <Animated.View
            pointerEvents="box-none"
            style={[bandStyle, Platform.OS === 'android' ? styles.lift : null]}
            className={band()}
          >
            <BandMetricsContext.Provider value={metrics}>
              {/* Draw order, not writing order: the cover is behind the block,
                  and the bar is over both so it covers the block on its way
                  past rather than being crossed by it. */}
              {parts.cover}
              {parts.large}
              {parts.bar}
            </BandMetricsContext.Provider>
          </Animated.View>
        </View>
      </ScrollHeaderContext.Provider>
    );
  }
);
ScrollHeaderRoot.displayName = 'ScrollHeader';

interface BandMetrics {
  /** Height of the pinned band, inset included. */
  barBand: number;
  /** How much of it is safe area. */
  insetTop: number;
}

const BandMetricsContext = createContext<BandMetrics>({ barBand: BAR_HEIGHT, insetTop: 0 });

export interface ScrollHeaderBarProps extends ViewProps {
  className?: string;
  /**
   * What the bar is drawn on once it has taken over. `none` leaves it clear,
   * for a bar over a cover that should stay visible. `blur` frosts it, so the
   * content passing under the bar stays legible as shape and colour.
   *
   * `blur` needs `expo-blur`, which is optional, and it is replaced by an
   * opaque bar under Reduce Transparency. Both fall back to `plain` — a bar
   * whose title cannot be read is a worse answer than one that is not frosted.
   */
  surface?: ScrollHeaderSurface;
  /** A hairline under the bar, drawn with its surface. */
  divider?: boolean;
  /**
   * Depth of the frost, on `expo-blur`'s 0–100 scale. Defaults to 40 — heavier
   * than a scrim's, because a scrim covers a whole screen and this is a thin
   * band read against content moving under it. Ignored unless `surface` is
   * `blur`.
   */
  intensity?: number;
  /**
   * Which way the frost tints. Defaults to the app's theme rather than the
   * device's, so an app running light inside a dark OS frosts light. Ignored
   * unless `surface` is `blur`.
   */
  material?: ScrollHeaderMaterial;
  children?: ReactNode;
}

/**
 * The pinned bar. Its contents never move; its surface fades in as the large
 * block leaves, which is what makes the change read as one crossfade rather
 * than two things happening at once.
 */
const ScrollHeaderBar = forwardRef<View, ScrollHeaderBarProps>(
  (
    {
      className,
      surface = 'plain',
      divider = true,
      intensity = DEFAULT_BLUR_INTENSITY,
      material = 'default',
      children,
      ...props
    },
    ref
  ) => {
    const { progress } = useScrollHeader('ScrollHeader.Bar');
    const { barBand, insetTop } = useContext(BandMetricsContext);
    const { mode } = useThemeMode();
    const reduceTransparency = useReduceTransparency();

    // Three gates, and a preference that has not been answered yet counts as
    // switched on: the case worth being careful about is the one where it is.
    const blurring =
      surface === 'blur' && hasBlur && BlurView !== null && reduceTransparency === false;
    const fill = surface === 'blur' && !blurring ? 'plain' : surface;
    const { bar, barSurface } = scrollHeaderVariants({ surface: fill, divider });

    // Closed by the time the block has gone, so the block is never seen through
    // it — and never on top of whatever else the bar is carrying.
    const surfaceStyle = useAnimatedStyle(() => ({
      opacity: interpolate(progress.value, SURFACE_ARRIVE, [0, 1], 'clamp'),
    }));

    return (
      <View
        {...props}
        ref={ref}
        // The bar owns only its own band. `box-none` above it lets a pull
        // land on the scroller rather than on the header covering it.
        style={{ height: barBand, paddingTop: insetTop }}
        className={bar({ className })}
      >
        {/*
          The material is a child of the surface rather than a sibling of it,
          so there is one opacity driving both and the frost cannot arrive on a
          different curve from the fill it replaces. It sits inside the
          divider's border box, so the hairline stays on top of it.
        */}
        <Animated.View
          pointerEvents="none"
          style={surfaceStyle}
          className={barSurface()}
        >
          {blurring && BlurView ? (
            <BlurView
              intensity={intensity}
              tint={material === 'default' ? mode : material}
              style={StyleSheet.absoluteFill}
            />
          ) : null}
        </Animated.View>
        <ScrollHeaderSlotContext.Provider value="bar">
          {textChildren(children)}
        </ScrollHeaderSlotContext.Provider>
      </View>
    );
  }
);
ScrollHeaderBar.displayName = 'ScrollHeader.Bar';

export interface ScrollHeaderLargeProps extends ViewProps {
  className?: string;
  children?: ReactNode;
}

/**
 * The expanded block. Its measured height is the distance the header
 * collapses over, so whatever is put in it — a title, a search field, a row of
 * chips — sets the scroll distance rather than a prop having to agree with it.
 */
const ScrollHeaderLarge = forwardRef<View, ScrollHeaderLargeProps>(
  ({ className, onLayout, children, ...props }, ref) => {
    const { progress, measureLarge, collapsed } = useScrollHeader('ScrollHeader.Large');
    const { large } = scrollHeaderVariants();

    const style = useAnimatedStyle(() => ({
      opacity: interpolate(progress.value, LARGE_EXIT, [1, 0], 'clamp'),
    }));

    // The measurement is this block's whole job, so it is taken first and a
    // consumer's own `onLayout` runs after it rather than instead of it.
    const measure = useCallback(
      (event: LayoutChangeEvent) => {
        measureLarge(event);
        onLayout?.(event);
      },
      [measureLarge, onLayout]
    );

    return (
      <Animated.View
        {...props}
        ref={ref}
        onLayout={measure}
        // Behind the bar and faded out by the time it gets there, so it must
        // not keep taking touches that belong to the content underneath.
        pointerEvents={collapsed ? 'none' : 'box-none'}
        accessibilityElementsHidden={collapsed}
        importantForAccessibility={collapsed ? 'no-hide-descendants' : 'auto'}
        style={style}
        className={large({ className })}
      >
        <ScrollHeaderSlotContext.Provider value="large">
          {textChildren(children)}
        </ScrollHeaderSlotContext.Provider>
      </Animated.View>
    );
  }
);
ScrollHeaderLarge.displayName = 'ScrollHeader.Large';

/**
 * The screen's title. Written in both halves and styled from whichever it is
 * in: large and at rest in the block, compact and fading in on the bar.
 */
const ScrollHeaderTitle = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => {
  const { progress, largeHeight, collapsed, hasLarge } = useScrollHeader('ScrollHeader.Title');
  const slot = useContext(ScrollHeaderSlotContext);

  // A bar with no block above it is not handing over from anything: it is the
  // only title the screen has, and it is wanted from the first frame. Fading it
  // in with the collapse would leave that screen untitled until somebody
  // scrolled it.
  const style = useAnimatedStyle(() => ({
    opacity: hasSpan(largeHeight.value)
      ? interpolate(progress.value, BAR_TITLE_ARRIVE, [0, 1], 'clamp')
      : 1,
  }));

  if (slot === 'large') {
    return (
      <Text
        {...props}
        ref={ref}
        size="3xl"
        weight="bold"
        accessibilityRole="header"
        className={cn('text-foreground', className)}
      />
    );
  }

  return (
    <Animated.View
      style={style}
      // The large title is the one being read until the bar has taken over.
      // Both are in the tree the whole time, and only one of them should be —
      // unless there is no large title, in which case this one always is.
      accessibilityElementsHidden={hasLarge ? !collapsed : false}
      importantForAccessibility={!hasLarge || collapsed ? 'auto' : 'no-hide-descendants'}
      className="flex-1"
    >
      <Text
        {...props}
        ref={ref}
        size="base"
        weight="semibold"
        numberOfLines={props.numberOfLines ?? 1}
        accessibilityRole="header"
        className={cn('text-foreground', className)}
      />
    </Animated.View>
  );
});
ScrollHeaderTitle.displayName = 'ScrollHeader.Title';

/** The quiet line under the title — a count, a byline, a date. */
const ScrollHeaderDescription = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => (
  <Text {...props} ref={ref} size="sm" muted className={className} />
));
ScrollHeaderDescription.displayName = 'ScrollHeader.Description';

export interface ScrollHeaderActionsProps extends ViewProps {
  className?: string;
  children?: ReactNode;
}

/**
 * The controls at the trailing end of the bar. They stay put and stay
 * reachable — only the bar's surface and title are part of the transition.
 */
const ScrollHeaderActions = forwardRef<View, ScrollHeaderActionsProps>(
  ({ className, children, ...props }, ref) => {
    const { actions } = scrollHeaderVariants();
    return (
      <View {...props} ref={ref} className={actions({ className })}>
        {textChildren(children)}
      </View>
    );
  }
);
ScrollHeaderActions.displayName = 'ScrollHeader.Actions';

export interface ScrollHeaderCoverProps extends ViewProps {
  className?: string;
  /** A picture behind the header. Laid out to fill the band, so it stretches with it. */
  source?: ImageSourcePropType;
  /**
   * The gradient drawn when there is no picture, or under one that has not
   * loaded. Defaults to two of the theme's series tokens, so an app that puts
   * its charts on brand puts this on brand with them.
   */
  colors?: [string, string, ...string[]];
  /** A wash over the cover, so a title stays legible on a bright picture. */
  scrim?: boolean;
  children?: ReactNode;
}

/**
 * A picture or a gradient filling the band. It has no height of its own — the
 * band's height is its height, which is why it stretches on an over-scroll by
 * being laid out larger rather than by being scaled up and going soft.
 */
const ScrollHeaderCover = forwardRef<View, ScrollHeaderCoverProps>(
  (
    {
      className,
      source,
      colors,
      scrim = true,
      children,
      ...props
    },
    ref
  ) => {
    const { cover } = scrollHeaderVariants();
    const seriesOne = useCSSVariable('--color-chart-1');
    const seriesTwo = useCSSVariable('--color-chart-2');

    const ramp: [string, string, ...string[]] = colors ?? [
      typeof seriesOne === 'string' ? seriesOne : '#6366f1',
      typeof seriesTwo === 'string' ? seriesTwo : '#8b5cf6',
    ];

    return (
      <View {...props} ref={ref} pointerEvents="none" className={cover({ className })}>
        <LinearGradient colors={ramp} start={{ x: 0, y: 0 }} end={{ x: 1, y: 1 }} style={StyleSheet.absoluteFill} />
        {source ? (
          <Image source={source} resizeMode="cover" style={StyleSheet.absoluteFill} />
        ) : null}
        {scrim ? <View className="absolute inset-0 bg-black/25" /> : null}
        {children}
      </View>
    );
  }
);
ScrollHeaderCover.displayName = 'ScrollHeader.Cover';

/**
 * Sort the children into the three band slots and the one scrollable. Sorting
 * by component rather than by order is what lets the example above read
 * top-down — bar, block, list — while the band still draws the cover first.
 */
function splitChildren(children: ReactNode): {
  parts: { cover: ReactNode; large: ReactNode; bar: ReactNode };
  scrollable: ReactNode;
} {
  let cover: ReactNode = null;
  let large: ReactNode = null;
  let bar: ReactNode = null;
  let scrollable: ReactNode = null;

  Children.forEach(children, (child) => {
    if (!isValidElement(child)) return;
    if (child.type === ScrollHeaderCover) cover = child;
    else if (child.type === ScrollHeaderLarge) large = child;
    else if (child.type === ScrollHeaderBar) bar = child;
    else if (!scrollable) scrollable = child;
  });

  return { parts: { cover, large, bar }, scrollable };
}

/** Point several refs at one node, skipping the ones that were not given. */
function composeRefs(...refs: (Ref<unknown> | undefined)[]) {
  return (node: unknown) => {
    for (const ref of refs) {
      if (typeof ref === 'function') ref(node);
      else if (ref && typeof ref === 'object') {
        (ref as { current: unknown }).current = node;
      }
    }
  };
}

const styles = StyleSheet.create({
  // Android draws by elevation before z-order, so a band with none of its own
  // ends up under the scroller's own background.
  lift: { elevation: 4 },
});

export const ScrollHeader = Object.assign(ScrollHeaderRoot, {
  Bar: ScrollHeaderBar,
  Large: ScrollHeaderLarge,
  Title: ScrollHeaderTitle,
  Description: ScrollHeaderDescription,
  Actions: ScrollHeaderActions,
  Cover: ScrollHeaderCover,
});