@oxy.so/bloom 7.4.0 → 7.6.0

package/src/index.web.ts

@@ -174,13 +174,17 @@ export {
   useClaimTopEdge,
   useTopEdgeInset,
   ScrollOffsetProvider,
+  ScrollMetricsProvider,
+  useScrollMetricsBinding,
+  useAnimatedScrollMetricsBinding,
+  ScrollArea,
   useScrollOffset,
   ScreenScope,
   HeaderDockProvider,
   useHeaderDockInset,
   StickySection,
 } from './layout';
-export type { StickySectionProps } from './layout';
+export type { StickySectionProps, ScrollMetricsBindingOptions, AnimatedScrollMetricsBindingOptions, ScrollAreaProps } from './layout';
 export { Fab } from './fab/index.web';
 export type { FabProps, FabSize } from './fab/index.web';
 export { FrostedIconButton } from './frosted-icon-button/index.web';

package/src/layout/ScrollArea.tsx

@@ -0,0 +1,25 @@
+import React, { forwardRef, type ComponentType, type Ref } from 'react';
+import { ScrollView, type ScrollViewProps } from 'react-native';
+import { styled } from 'react-native-css';
+import { useScrollMetricsBinding } from './use-scroll-metrics-binding';
+
+export interface ScrollAreaProps extends ScrollViewProps {
+  /** Utilities for the scrolling viewport, resolved by Bloom's own interop. */
+  className?: string;
+  /** Utilities for the inner content container. */
+  contentContainerClassName?: string;
+}
+
+// Narrow only the styled mapping input to avoid ScrollViewProps' recursive
+// dot-path union. The public component retains the complete ScrollView contract.
+const ScrollAreaBase: ComponentType<Pick<ScrollViewProps, 'style' | 'contentContainerStyle'>> = ScrollView;
+const StyledScrollView: ComponentType<ScrollAreaProps & { ref?: Ref<ScrollView> }> = styled(ScrollAreaBase, {
+  className: 'style',
+  contentContainerClassName: 'contentContainerStyle',
+});
+
+/** A ScrollView that publishes its measurements to surrounding page chrome. */
+export const ScrollArea = forwardRef<ScrollView, ScrollAreaProps>(function ScrollArea({ onScroll, onLayout, onContentSizeChange, scrollEventThrottle, ...props }, ref) {
+  const binding = useScrollMetricsBinding({ onScroll, onLayout, onContentSizeChange });
+  return <StyledScrollView {...props} {...binding} scrollEventThrottle={scrollEventThrottle ?? binding.scrollEventThrottle} ref={ref} />;
+});

package/src/layout/index.ts

@@ -18,3 +18,11 @@ export { ScreenScope } from './screen-scope';
 export { HeaderDockProvider, useHeaderDockInset } from './header-dock';
 export { StickySection } from './StickySection';
 export type { StickySectionProps } from './StickySection';
+
+export { ScrollMetricsProvider } from './scroll-metrics';
+export { useScrollMetricsBinding } from './use-scroll-metrics-binding';
+export type { ScrollMetricsBindingOptions } from './use-scroll-metrics-binding';
+export { ScrollArea } from './ScrollArea';
+export type { ScrollAreaProps } from './ScrollArea';
+export { useAnimatedScrollMetricsBinding } from './use-animated-scroll-metrics-binding';
+export type { AnimatedScrollMetricsBindingOptions } from './use-animated-scroll-metrics-binding';

package/src/layout/screen-scope.tsx

@@ -39,6 +39,7 @@ import { ScreenContext, ScreenNavigationContext } from '../screen/context';
 import type { PropsWithChildren } from 'react';
 
 import { BottomEdgeProvider } from './bottom-edge';
+import { ScrollMetricsContext } from './scroll-metrics';
 import { ScrollOffsetProvider } from './scroll-offset';
 import { TopEdgeProvider } from './top-edge';
 
@@ -49,7 +50,7 @@ export function ScreenScope({ children }: PropsWithChildren) {
         <TopEdgeProvider>
           <BottomEdgeProvider>
             {/* null means no scroller has claimed this scope yet. */}
-            <ScrollOffsetProvider value={null}>{children}</ScrollOffsetProvider>
+            <ScrollMetricsContext.Provider value={null}><ScrollOffsetProvider value={null}>{children}</ScrollOffsetProvider></ScrollMetricsContext.Provider>
           </BottomEdgeProvider>
         </TopEdgeProvider>
       </ScreenNavigationContext.Provider>

package/src/layout/scroll-metrics-events.ts

@@ -0,0 +1,14 @@
+import type { NativeScrollEvent } from 'react-native';
+import type { ScrollMetrics } from './scroll-metrics';
+
+/** Shared by ordinary RN events and UI-thread animated events. */
+export function recordScrollMetrics(metrics: ScrollMetrics | null, event: NativeScrollEvent): void {
+  'worklet';
+  if (!metrics) return;
+  const contentHeight = Number.isFinite(event.contentSize.height) ? Math.max(0, event.contentSize.height) : metrics.contentHeight.value;
+  const viewportHeight = Number.isFinite(event.layoutMeasurement.height) ? Math.max(0, event.layoutMeasurement.height) : metrics.viewportHeight.value;
+  metrics.contentHeight.value = contentHeight;
+  metrics.viewportHeight.value = viewportHeight;
+  const max = Math.max(0, contentHeight - viewportHeight);
+  if (Number.isFinite(event.contentOffset.y)) metrics.scrollY.value = Math.min(max, Math.max(0, event.contentOffset.y));
+}

package/src/layout/scroll-metrics.tsx

@@ -0,0 +1,35 @@
+import React, { createContext, useContext, useMemo, type PropsWithChildren } from 'react';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+import { ScrollOffsetProvider } from './scroll-offset';
+
+export interface ScrollMetrics {
+  scrollY: SharedValue<number>;
+  contentHeight: SharedValue<number>;
+  viewportHeight: SharedValue<number>;
+}
+
+/** Internal scope boundary; overlay screens must not follow the page beneath them. */
+export const ScrollMetricsContext = createContext<ScrollMetrics | null>(null);
+
+/** Pair one scroller with its surrounding header/footer without adding a layout box. */
+export function ScrollMetricsProvider({ children }: PropsWithChildren) {
+  const scrollY = useSharedValue(0);
+  const contentHeight = useSharedValue(-1);
+  const viewportHeight = useSharedValue(0);
+  const value = useMemo(() => ({ scrollY, contentHeight, viewportHeight }), [scrollY, contentHeight, viewportHeight]);
+  return <ScrollMetricsContext.Provider value={value}>
+    <ScrollOffsetProvider value={scrollY}>{children}</ScrollOffsetProvider>
+  </ScrollMetricsContext.Provider>;
+}
+
+export function useScrollMetricsValue(): ScrollMetrics | null {
+  return useContext(ScrollMetricsContext);
+}
+
+/** Unmeasured and non-scrollable content has no hidden bottom edge. */
+export function remainingScrollDistance(metrics: ScrollMetrics | null): number {
+  'worklet';
+  if (!metrics || metrics.viewportHeight.value <= 0 || metrics.contentHeight.value < 0) return 0;
+  const max = Math.max(0, metrics.contentHeight.value - metrics.viewportHeight.value);
+  return Math.max(0, max - Math.max(0, metrics.scrollY.value));
+}

package/src/layout/scroll-offset.ts

@@ -8,7 +8,11 @@
  * one scroll container has moved. The container is the screen's, and the chrome
  * is usually not inside it, so the number has to travel.
  *
- * Until now it travelled as a prop, and the default when the prop was omitted
+ * Prefer ScrollMetricsProvider with ScrollArea when the footer also needs to
+ * know the remaining content. This lower-level offset-only provider remains
+ * useful for an existing animated scroll owner.
+ *
+ * Originally it travelled as a prop, and the default when the prop was omitted
  * was `window.scrollY` on web and "nothing moves" on native. That default is
  * right for exactly one layout — a web page whose document IS the scroller —
  * and silently wrong for the two that a Bloom app usually has: a desktop panel

package/src/layout/use-animated-scroll-metrics-binding.ts

@@ -0,0 +1,42 @@
+import { useCallback } from 'react';
+import type { NativeScrollEvent, NativeSyntheticEvent, ScrollViewProps } from 'react-native';
+import { runOnJS, useAnimatedScrollHandler, useComposedEventHandler, type ScrollHandlerProcessed } from 'react-native-reanimated';
+import { useScrollMetricsValue } from './scroll-metrics';
+import { recordScrollMetrics } from './scroll-metrics-events';
+import { useScrollMetricsBinding } from './use-scroll-metrics-binding';
+
+export interface AnimatedScrollMetricsBindingOptions<Context extends Record<string, unknown> = Record<string, unknown>>
+  extends Pick<ScrollViewProps, 'onLayout' | 'onContentSizeChange'> {
+  /** Optional ordinary RN observer, bridged to JS only when supplied (e.g. restoration.onScroll). */
+  onScroll?: ScrollViewProps['onScroll'];
+  /** Existing Reanimated handler, including tab-bar minimize or other animated scroll handlers. */
+  handler?: ScrollHandlerProcessed<Context> | null;
+}
+
+/**
+ * Bind an Animated ScrollView / virtualized list with metrics updated on the UI
+ * thread. Composition preserves consumer drag and momentum subscriptions.
+ */
+export function useAnimatedScrollMetricsBinding<Context extends Record<string, unknown> = Record<string, unknown>>({
+  handler = null, onScroll: observeScroll, onLayout, onContentSizeChange,
+}: AnimatedScrollMetricsBindingOptions<Context> = {}) {
+  const metrics = useScrollMetricsValue();
+  if (observeScroll != null && typeof observeScroll !== 'function') {
+    throw new Error('Bloom useAnimatedScrollMetricsBinding onScroll expects a plain RN callback; pass a Reanimated handler through the handler option.');
+  }
+  // The optional ordinary RN observer (for example scroll restoration) runs on
+  // JS. Metrics and composed animated consumers remain on the UI thread.
+  const reportScroll = useCallback((event: NativeScrollEvent) => {
+    observeScroll?.({ nativeEvent: event } as NativeSyntheticEvent<NativeScrollEvent>);
+  }, [observeScroll]);
+  const reportsScroll = observeScroll != null;
+  const measurements = useScrollMetricsBinding({ onLayout, onContentSizeChange });
+  const ownHandler = useAnimatedScrollHandler<Context>({
+    onScroll: event => {
+      recordScrollMetrics(metrics, event);
+      if (reportsScroll) runOnJS(reportScroll)(event);
+    },
+  }, [metrics, reportsScroll, reportScroll]);
+  const onScroll = useComposedEventHandler([ownHandler, handler]);
+  return { ...measurements, onScroll };
+}

package/src/layout/use-scroll-metrics-binding.ts

@@ -0,0 +1,37 @@
+import { useCallback } from 'react';
+import type { ScrollViewProps } from 'react-native';
+import { recordScrollMetrics } from './scroll-metrics-events';
+import { useScrollMetricsValue } from './scroll-metrics';
+
+/** Events accepted by ordinary RN ScrollView, FlatList and SectionList. */
+export type ScrollMetricsBindingOptions = Pick<ScrollViewProps, 'onScroll' | 'onLayout' | 'onContentSizeChange'>;
+
+/** Bind one scrolling owner to the nearest ScrollMetricsProvider. No React updates per frame. */
+export function useScrollMetricsBinding({ onScroll, onLayout, onContentSizeChange }: ScrollMetricsBindingOptions = {}) {
+  const metrics = useScrollMetricsValue();
+  // Reanimated types its processed handler as a function, but returns an object.
+  // Reject that mismatch before an event instead of attempting to call it on JS.
+  if (onScroll != null && typeof onScroll !== 'function') {
+    throw new Error('Bloom useScrollMetricsBinding expects a plain RN onScroll callback. Use useAnimatedScrollMetricsBinding({ handler }) for Reanimated handlers.');
+  }
+  const handleScroll = useCallback<NonNullable<ScrollViewProps['onScroll']>>(event => {
+    recordScrollMetrics(metrics, event.nativeEvent);
+    onScroll?.(event);
+  }, [metrics, onScroll]);
+  const handleLayout = useCallback<NonNullable<ScrollViewProps['onLayout']>>(event => {
+    const height = event.nativeEvent.layout.height;
+    if (metrics && Number.isFinite(height)) {
+      metrics.viewportHeight.value = Math.max(0, height);
+      if (metrics.contentHeight.value >= 0) metrics.scrollY.value = Math.min(metrics.scrollY.value, Math.max(0, metrics.contentHeight.value - height));
+    }
+    onLayout?.(event);
+  }, [metrics, onLayout]);
+  const handleContentSizeChange = useCallback<NonNullable<ScrollViewProps['onContentSizeChange']>>((width, height) => {
+    if (metrics && Number.isFinite(height)) {
+      metrics.contentHeight.value = Math.max(0, height);
+      metrics.scrollY.value = Math.min(metrics.scrollY.value, Math.max(0, height - metrics.viewportHeight.value));
+    }
+    onContentSizeChange?.(width, height);
+  }, [metrics, onContentSizeChange]);
+  return { onScroll: handleScroll, onLayout: handleLayout, onContentSizeChange: handleContentSizeChange, scrollEventThrottle: 16 };
+}

package/src/page-footer/PageFooter.tsx

@@ -1,6 +1,8 @@
 import React, { memo, useContext, useEffect, useId, useState } from 'react';
 import { Platform, StyleSheet, View, useWindowDimensions, type LayoutChangeEvent } from 'react-native';
 import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
+import Animated, { useAnimatedStyle } from 'react-native-reanimated';
+import { remainingScrollDistance, useScrollMetricsValue } from '../layout/scroll-metrics';
 import { BloomScope } from '../appearance';
 import { useBottomEdgeInset } from '../layout/bottom-edge';
 import { EdgeScrim, SCRIM_TAIL_RATIO } from '../page-header/EdgeScrim';
@@ -15,9 +17,14 @@ const BAR_HEIGHT = 56;
 
 /** Page-local controls floating over a bounded scroller, above app navigation. */
 function PageFooterComponent({
-  children, actions, bottomInset, safeArea, scrim = 'always', scrimColor, style, testID,
+  children, actions, bottomInset, safeArea, scrim = 'always', scrimColor, scrollThreshold = 20, style, testID,
 }: PageFooterProps) {
   const theme = useTheme();
+  const metrics = useScrollMetricsValue();
+  const threshold = Math.max(1, Number.isFinite(scrollThreshold) ? scrollThreshold : 20);
+  const scrimStyle = useAnimatedStyle(() => ({
+    opacity: scrim === 'auto' ? Math.min(1, remainingScrollDistance(metrics) / threshold) : 1,
+  }), [metrics, scrim, threshold]);
   const fill = useSurfaceFill() ?? theme.colors.background;
   const occupied = useBottomEdgeInset();
   const rawBottom = bottomInset ?? occupied;
@@ -51,13 +58,13 @@ function PageFooterComponent({
       style={[styles.container, { bottom, paddingBottom: padBottom }, style]}
     >
       {scrim !== 'none' ? (
-        <View
+        <Animated.View
           pointerEvents="none"
-          style={[styles.scrim, { height: height * (1 + SCRIM_TAIL_RATIO) }]}
+          style={[styles.scrim, { height: height * (1 + SCRIM_TAIL_RATIO) }, scrimStyle]}
           testID={testID ? `${testID}-scrim` : undefined}
         >
           <EdgeScrim edge="bottom" color={scrimColor ?? fill} testID={testID ? `${testID}-scrim-gradient` : undefined} />
-        </View>
+        </Animated.View>
       ) : null}
       <View
         onLayout={onLayout}

package/src/page-footer/types.ts

@@ -17,8 +17,14 @@ export interface PageFooterProps {
    * true on native, false on web. Disable when the containing shell owns it.
    */
   safeArea?: boolean;
-  /** The PageHeader gradient, mirrored upward. Default always. */
-  scrim?: 'always' | 'none';
+  /**
+   * Mirrored PageHeader gradient. Default always preserves existing behavior.
+   * auto follows ScrollMetricsProvider: hidden at the bottom or for short /
+   * unmeasured content, fading in over scrollThreshold of remaining content.
+   */
+  scrim?: 'auto' | 'always' | 'none';
+  /** Distance from the bottom over which the automatic scrim fades. Default 20. */
+  scrollThreshold?: number;
   /** Opaque gradient color; defaults to the containing surface's fill. */
   scrimColor?: string;
   style?: StyleProp<ViewStyle>;

package/src/page-header/PageHeader.tsx

@@ -24,6 +24,7 @@ import { BUTTON_SHADOW } from '../button/shared';
 import { BloomScope } from "../appearance";
 import { GlassIsland } from '../glass';
 import { RiArrowLeftLine } from '../icons/remix/RiArrowLeftLine';
+import { useScrollMetricsValue } from '../layout/scroll-metrics';
 import { useClaimTopEdge, useScrollOffset } from '../layout';
 import { BREAKPOINTS } from '../styles/breakpoints';
 import { WEB_POSITION_STICKY, WEB_SURFACE_STICKY_TOP, type WebCssStyle } from '../styles/web-view-style';
@@ -186,14 +187,15 @@ function PageHeaderComponent({
 
   // ── The scroll owner ──────────────────────────────────────────────────────
   //
-  // Prop, then Screen, then the nearest ScrollOffsetProvider, then the document on web.
+  // Explicit offset, dock, local metrics, Screen, legacy offset, then the web document.
   // The context step is the one that matters for a Bloom composition: without
   // it a header inside a scrolling panel followed `window.scrollY`, which on a
   // desktop shell never moves, so the header looked deliberately inert.
   const screen = useScreenContext();
   const contextScrollY = useScrollOffset();
+  const metrics = useScrollMetricsValue();
   const internalScrollY = useSharedValue(0);
-  const scrollY = externalScrollY ?? dock?.scrollY ?? screen?.scrollY ?? contextScrollY ?? internalScrollY;
+  const scrollY = externalScrollY ?? dock?.scrollY ?? metrics?.scrollY ?? screen?.scrollY ?? contextScrollY ?? internalScrollY;
   const followsWindow = !externalScrollY && !dock && !screen && !contextScrollY;
 
   useEffect(() => {

package/src/page-header/types.ts

@@ -142,10 +142,9 @@ export interface PageHeaderProps {
   /**
    * The scroll offset driving the scrim, the separator and the shadow.
    *
-   * Resolution order: this prop, then the enclosing `Screen` offset, then the nearest `ScrollOffsetProvider`
-   * (`@oxy.so/bloom/layout`) — which is how a header inside a Bloom scroll
-   * composition gets it with no wiring — then, on web only, `window.scrollY`.
-   * On native with none of the three, the header stays at rest.
+   * Resolution order: this prop, HeaderDockProvider, ScrollMetricsProvider,
+   * the enclosing Screen, then ScrollOffsetProvider. On web with no local
+   * owner it follows window.scrollY; on native it stays at rest.
    */
   scrollY?: SharedValue<number>;
   /** The offset (px) over which the scrim, separator and shadow fade in. Default 20. */