@oxy.so/bloom 4.11.0 → 4.13.0

package/src/ai-chat/AiChatContainer.tsx

@@ -2,6 +2,7 @@ import React, {
   forwardRef,
   useCallback,
   useContext,
+  useEffect,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -30,12 +31,23 @@ import { parseRgba } from '../theme/color-utils';
 import { useIsomorphicLayoutEffect } from '../theme/use-isomorphic-layout-effect';
 import { GlyphAction } from './AiChatControls';
 import {
+  AiChatDocumentGutterContext,
   AiChatFloatingChromeContext,
+  useAiChatShell,
   type AiChatChromeInsets,
   type AiChatFloatingChrome,
   type AiChatScrollMetrics,
 } from './context';
-import { CONTAINER_RADIUS, dataHook, IS_WEB, useAiChatPalette, useAiChatWebCss } from './shared';
+import {
+  CONTAINER_RADIUS,
+  dataHook,
+  DOCUMENT_LAYER,
+  IS_WEB,
+  SHELL_GUTTER,
+  useAiChatPalette,
+  useAiChatWebCss,
+} from './shared';
+import { WEB_POSITION_STICKY, webViewportHeightMinus } from '../styles/web-view-style';
 import type { AiChatContainerProps, AiChatThreadHandle, AiChatThreadProps } from './types';
 
 const DEFAULT_LABELS = {
@@ -46,12 +58,8 @@ const DEFAULT_LABELS = {
 
 /** The thread's own top padding: the gap between the header and the first turn. */
 const THREAD_PAD_TOP = 16;
-/**
- * `floatingChrome`: the footer's fade strip, px — the footer's top padding, so
- * the last turn at rest ends where the fade begins, and the distance over which
- * the bottom fade ramps in as the transcript slides under it.
- */
-const FOOTER_FADE = 24;
+/** The footer's top padding: the gap between the last turn at rest and the composer. */
+const FOOTER_GAP = 12;
 /** Below this many px of overlap an edge counts as clear (sub-pixel scroll noise). */
 const EDGE_THRESHOLD = 1;
 
@@ -86,14 +94,19 @@ const HIDDEN_FROM_A11Y = {
  *             an edge scrim of the surface (opaque at the top, gone
  *             `SCRIM_TAIL_RATIO` below the block) fades in over the first 16px
  *             of transcript scrolled under it
- *   footer    absolute at the bottom, pt 24 instead of 12: the 24px strip is a
- *             scrim ramp and the rest is solid surface, faded in over the first
- *             24px of transcript below the fold
+ *   footer    absolute at the bottom, with no band of its own: the transcript
+ *             passes behind the composer and stays in sight around it
  *
  * Both blocks are `pointerEvents="box-none"`, so the transcript under their
  * empty space still scrolls and takes clicks. The measured heights reach an
  * `AiChatThread` child through context (its content padding) and any other
  * child through `useAiChatChromeInsets()`.
+ *
+ * Under a shell with `scroll="document"` the chrome always floats, since the
+ * document is what moves: the header and the footer are `sticky` in the flow,
+ * pinned to the screen's top and bottom gutter, the `background` slot and the
+ * card's frame are layers the size of the screen, and the card grows with the
+ * conversation. At rest nothing overlaps, so the insets are zero.
  */
 export function AiChatContainer({
   project,
@@ -118,6 +131,8 @@ export function AiChatContainer({
   useAiChatWebCss();
   const palette = useAiChatPalette();
   const l = useMemo(() => ({ ...DEFAULT_LABELS, ...labels }), [labels]);
+  const documentScroll = useAiChatShell()?.documentScroll ?? false;
+  const gutterColor = useContext(AiChatDocumentGutterContext);
 
   const hasCrumbRow = title != null || project != null || onShare || onMore || actions != null;
   const crumbRow = hasCrumbRow ? (
@@ -178,6 +193,41 @@ export function AiChatContainer({
     style,
   ];
 
+  if (documentScroll) {
+    return (
+      <FloatingChrome
+        documentScroll
+        testID={testID}
+        rootStyle={[
+          {
+            // Grows with the conversation, one screen at the least; nothing
+            // clips it, so the header and composer inside can stick.
+            minHeight: webViewportHeightMinus(SHELL_GUTTER * 2),
+            minWidth: 0,
+            flex: 1,
+            flexDirection: 'column',
+            borderRadius: CONTAINER_RADIUS,
+            backgroundColor: surface ? palette.secondary : 'transparent',
+          },
+          style,
+        ]}
+        backgroundLayer={
+          background ? (
+            <View pointerEvents="none" style={[DOCUMENT_LAYER, { overflow: 'hidden' }]}>
+              {background}
+            </View>
+          ) : null
+        }
+        header={header}
+        crumbRow={crumbRow}
+        footerBody={footerBody}
+        fadeColor={surface ? palette.secondary : null}
+        gutterColor={gutterColor}>
+        {children}
+      </FloatingChrome>
+    );
+  }
+
   if (floatingChrome) {
     return (
       <FloatingChrome
@@ -209,28 +259,36 @@ export function AiChatContainer({
 }
 
 interface FloatingChromeProps {
+  /** The page scrolls the document: the chrome is sticky in the flow, not absolute. */
+  documentScroll?: boolean;
   testID?: string;
   rootStyle: StyleProp<ViewStyle>;
   backgroundLayer: ReactNode;
   header: ReactNode;
   crumbRow: ReactNode;
   footerBody: ReactNode;
-  /** The opaque surface the edges fade to, or `null` for no fades. */
+  /** The opaque surface the header's edge fades to, or `null` for no fade. */
   fadeColor: string | null;
+  /** `documentScroll`: the gutter around the card, which its frame masks in. */
+  gutterColor?: string | null;
   children: ReactNode;
 }
 
+const NO_INSETS: AiChatChromeInsets = { top: 0, bottom: 0 };
+
 /**
- * `AiChatContainer floatingChrome`: the same parts, the chrome floated over the
- * transcript. Everything it measures lives here, so the stacked path above
- * carries none of the state.
+ * `AiChatContainer floatingChrome` (and every container under a document-
+ * scrolled shell): the same parts, the chrome floated over the transcript.
+ * Everything it measures lives here, so the stacked path above carries none of
+ * the state.
  *
- * The edge opacities are shared values written from the thread's scroll
- * reports, so a scroll frame re-renders nothing; the booleans only mount and
- * unmount the scrims, and change once per crossing. Same model as the
+ * The header's edge opacity is a shared value written from the thread's scroll
+ * reports, so a scroll frame re-renders nothing; the boolean only mounts and
+ * unmounts the scrim, and changes once per crossing. Same model as the
  * sidebar's `SidebarScrollArea`, whose scrim this reuses.
  */
 function FloatingChrome({
+  documentScroll = false,
   testID,
   rootStyle,
   backgroundLayer,
@@ -238,39 +296,44 @@ function FloatingChrome({
   crumbRow,
   footerBody,
   fadeColor,
+  gutterColor = null,
   children,
 }: FloatingChromeProps) {
-  const [insets, setInsets] = useState<AiChatChromeInsets>({ top: 0, bottom: 0 });
-  const [edges, setEdges] = useState({ top: false, bottom: false });
+  const [insets, setInsets] = useState<AiChatChromeInsets>(NO_INSETS);
+  const [headerHeight, setHeaderHeight] = useState(0);
+  const [scrolled, setScrolled] = useState(false);
   const topFade = useSharedValue(0);
-  const bottomFade = useSharedValue(0);
 
-  const onHeaderLayout = useCallback((event: LayoutChangeEvent) => {
-    const top = Math.round(event.nativeEvent.layout.height);
-    setInsets((previous) => (previous.top === top ? previous : { ...previous, top }));
-  }, []);
-  const onFooterLayout = useCallback((event: LayoutChangeEvent) => {
-    const bottom = Math.round(event.nativeEvent.layout.height);
-    setInsets((previous) => (previous.bottom === bottom ? previous : { ...previous, bottom }));
-  }, []);
+  const onHeaderLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const top = Math.round(event.nativeEvent.layout.height);
+      setHeaderHeight(top);
+      // In the flow the header covers nothing at rest: no inset to publish.
+      if (!documentScroll) setInsets((previous) => (previous.top === top ? previous : { ...previous, top }));
+    },
+    [documentScroll],
+  );
+  const onFooterLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      if (documentScroll) return;
+      const bottom = Math.round(event.nativeEvent.layout.height);
+      setInsets((previous) => (previous.bottom === bottom ? previous : { ...previous, bottom }));
+    },
+    [documentScroll],
+  );
 
   const reportScroll = useCallback(
     ({ offset, viewport, content }: AiChatScrollMetrics) => {
       const range = Math.max(0, content - viewport);
       const y = Math.max(0, Math.min(offset, range));
       const overflow = viewport > 0 && range > EDGE_THRESHOLD;
-      // The first turn rests THREAD_PAD_TOP below the header and the last one
-      // right on the footer's fade strip, so the overlap starts at the first px
-      // scrolled and each ramp spans the gap it is closing.
-      const top = overflow && y > EDGE_THRESHOLD;
-      const bottom = overflow && range - y > EDGE_THRESHOLD;
+      // The first turn rests THREAD_PAD_TOP below the header, so the overlap
+      // starts at the first px scrolled and the ramp spans the gap it closes.
       topFade.value = overflow ? Math.min(1, y / THREAD_PAD_TOP) : 0;
-      bottomFade.value = overflow ? Math.min(1, (range - y) / FOOTER_FADE) : 0;
-      setEdges((previous) =>
-        previous.top === top && previous.bottom === bottom ? previous : { top, bottom },
-      );
+      const next = overflow && y > EDGE_THRESHOLD;
+      setScrolled((previous) => (previous === next ? previous : next));
     },
-    [topFade, bottomFade],
+    [topFade],
   );
 
   const chrome = useMemo<AiChatFloatingChrome>(() => ({ insets, reportScroll }), [insets, reportScroll]);
@@ -280,66 +343,92 @@ function FloatingChrome({
   const solid = parsed ? `rgb(${parsed.r}, ${parsed.g}, ${parsed.b})` : fadeColor;
   const alpha = parsed?.a ?? 1;
   const topStyle = useAnimatedStyle(() => ({ opacity: topFade.value * alpha }), [topFade, alpha]);
-  const bottomStyle = useAnimatedStyle(() => ({ opacity: bottomFade.value * alpha }), [bottomFade, alpha]);
   const prefix = testID ?? 'ai-chat';
 
-  return (
-    <View testID={testID} style={[rootStyle, { position: 'relative' }]}>
-      {backgroundLayer}
-      <AiChatFloatingChromeContext.Provider value={chrome}>{children}</AiChatFloatingChromeContext.Provider>
+  // Absolute over a card of fixed height; sticky in the flow of a card that
+  // grows with the document, pinned to the screen's gutter.
+  const headerPosition: ViewStyle = documentScroll
+    ? { position: WEB_POSITION_STICKY, top: SHELL_GUTTER, zIndex: 2 }
+    : { position: 'absolute', top: 0, left: 0, right: 0 };
+  const footerPosition: ViewStyle = documentScroll
+    ? { position: WEB_POSITION_STICKY, bottom: SHELL_GUTTER, zIndex: 2 }
+    : { position: 'absolute', left: 0, right: 0, bottom: 0 };
+
+  const top = (
+    <View testID={`${prefix}-chrome-top`} pointerEvents="box-none" onLayout={onHeaderLayout} style={headerPosition}>
+      {solid && scrolled && headerHeight > 0 ? (
+        <Animated.View
+          testID={`${prefix}-fade-top`}
+          pointerEvents="none"
+          {...HIDDEN_FROM_A11Y}
+          style={[
+            {
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              right: 0,
+              // Past the block's own bottom: a ramp that ends where the layout
+              // does is a line across the transcript again.
+              height: Math.round(headerHeight * (1 + SCRIM_TAIL_RATIO)),
+              // The card's own corners, since nothing clips a document card.
+              borderTopLeftRadius: CONTAINER_RADIUS,
+              borderTopRightRadius: CONTAINER_RADIUS,
+              overflow: 'hidden',
+            },
+            topStyle,
+          ]}>
+          <EdgeScrim color={solid} />
+        </Animated.View>
+      ) : null}
+      {header}
+      {crumbRow}
+    </View>
+  );
 
+  const bottom = (
+    <View testID={`${prefix}-chrome-bottom`} pointerEvents="box-none" onLayout={onFooterLayout} style={footerPosition}>
       <View
-        testID={`${prefix}-chrome-top`}
         pointerEvents="box-none"
-        onLayout={onHeaderLayout}
-        style={{ position: 'absolute', top: 0, left: 0, right: 0 }}>
-        {solid && edges.top && insets.top > 0 ? (
-          <Animated.View
-            testID={`${prefix}-fade-top`}
-            pointerEvents="none"
-            {...HIDDEN_FROM_A11Y}
-            style={[
-              {
-                position: 'absolute',
-                top: 0,
-                left: 0,
-                right: 0,
-                // Past the block's own bottom: a ramp that ends where the layout
-                // does is a line across the transcript again.
-                height: Math.round(insets.top * (1 + SCRIM_TAIL_RATIO)),
-              },
-              topStyle,
-            ]}>
-            <EdgeScrim color={solid} />
-          </Animated.View>
-        ) : null}
-        {header}
-        {crumbRow}
+        style={{ width: '100%', flexDirection: 'column', gap: 10, paddingLeft: 10, paddingRight: 10, paddingTop: FOOTER_GAP, paddingBottom: 10 }}>
+        {footerBody}
       </View>
+    </View>
+  );
 
-      <View
-        testID={`${prefix}-chrome-bottom`}
-        pointerEvents="box-none"
-        onLayout={onFooterLayout}
-        style={{ position: 'absolute', left: 0, right: 0, bottom: 0 }}>
-        {solid && edges.bottom ? (
-          <Animated.View
-            testID={`${prefix}-fade-bottom`}
+  const thread = <AiChatFloatingChromeContext.Provider value={chrome}>{children}</AiChatFloatingChromeContext.Provider>;
+
+  if (documentScroll) {
+    return (
+      <View testID={testID} style={rootStyle}>
+        {backgroundLayer}
+        {gutterColor ? (
+          // The card's frame, pinned to the screen: a ring of the gutter's
+          // colour painted over whatever of the conversation scrolls past the
+          // card's visible edge, so the card keeps its rounded corners and its
+          // gutter at the top and the bottom of the screen. Clipped to the
+          // gutter sideways (the family sheet), so it never reaches the columns
+          // beside the card.
+          <View
+            testID={`${prefix}-frame`}
             pointerEvents="none"
             {...HIDDEN_FROM_A11Y}
-            style={[StyleSheet.absoluteFill, { flexDirection: 'column' }, bottomStyle]}>
-            <View style={{ height: FOOTER_FADE, transform: [{ rotate: '180deg' }] }}>
-              <EdgeScrim color={solid} />
-            </View>
-            <View style={{ flex: 1, backgroundColor: solid }} />
-          </Animated.View>
+            {...dataHook('bloomAiChatFrame')}
+            style={[DOCUMENT_LAYER, { zIndex: 1, boxShadow: `0 0 0 ${SHELL_GUTTER}px ${gutterColor}` }]}
+          />
         ) : null}
-        <View
-          pointerEvents="box-none"
-          style={{ width: '100%', flexDirection: 'column', gap: 10, paddingLeft: 10, paddingRight: 10, paddingTop: FOOTER_FADE, paddingBottom: 10 }}>
-          {footerBody}
-        </View>
+        {top}
+        {thread}
+        {bottom}
       </View>
+    );
+  }
+
+  return (
+    <View testID={testID} style={[rootStyle, { position: 'relative' }]}>
+      {backgroundLayer}
+      {thread}
+      {top}
+      {bottom}
     </View>
   );
 }
@@ -373,7 +462,13 @@ function FloatingChrome({
  * motion they pass under it. It also reports its position so the container
  * knows when to fade each edge. Anywhere else nothing of this exists.
  */
-export const AiChatThread = forwardRef<AiChatThreadHandle, AiChatThreadProps>(function AiChatThread(
+export const AiChatThread = forwardRef<AiChatThreadHandle, AiChatThreadProps>(function AiChatThread(props, ref) {
+  const documentScroll = useAiChatShell()?.documentScroll ?? false;
+  return documentScroll ? <DocumentThread ref={ref} {...props} /> : <ScrollThread ref={ref} {...props} />;
+});
+
+/** The thread inside a card of fixed height: a `ScrollView` of its own. */
+const ScrollThread = forwardRef<AiChatThreadHandle, AiChatThreadProps>(function ScrollThread(
   {
     children,
     autoFollow = true,
@@ -544,3 +639,181 @@ export const AiChatThread = forwardRef<AiChatThreadHandle, AiChatThreadProps>(fu
     </ScrollView>
   );
 });
+
+/** The window's scroll position and extent, px. */
+function readWindow() {
+  const page = document.scrollingElement ?? document.documentElement;
+  return { y: window.scrollY, viewport: window.innerHeight, end: page.scrollHeight };
+}
+
+function scrollWindowTo(top: number, animated: boolean) {
+  window.scrollTo({ top, behavior: animated ? 'smooth' : 'auto' });
+}
+
+/**
+ * The thread under a document-scrolled shell (web): no scroller of its own —
+ * the turns grow the page and the window scrolls them. Same props, same handle,
+ * same behaviour: it follows the newest turn, fires `onStartReached` near the
+ * top, holds the reader still while a page lands above, and reports its
+ * position to the container.
+ *
+ * Offsets keep the thread's own frame: `0` is the thread's top, so a row's
+ * `onLayout` y is still a `scrollToOffset` target, and `contentSize` runs to the
+ * END OF THE PAGE, so `contentSize − offset − viewport` is still the distance
+ * left to scroll. The browser's scroll anchoring is off inside the thread (the
+ * family sheet): it would move the page for growth the thread already accounts
+ * for, and only in some browsers.
+ */
+const DocumentThread = forwardRef<AiChatThreadHandle, AiChatThreadProps>(function DocumentThread(
+  {
+    children,
+    autoFollow = true,
+    followAnimated = true,
+    followThreshold,
+    onStartReached,
+    onStartReachedThreshold = 300,
+    maintainStartPosition = false,
+    onScroll,
+    style,
+    testID,
+  },
+  ref,
+) {
+  const chrome = useContext(AiChatFloatingChromeContext);
+  const nodeRef = useRef<View>(null);
+  const lastHeight = useRef(0);
+  /** An `onStartReached` is out and its page has not landed yet. */
+  const pageOut = useRef(false);
+  /** The reader has left the top zone, so the next approach may fire again. */
+  const startArmed = useRef(true);
+
+  /** The thread's top, px from the top of the page. */
+  const threadTop = useCallback(() => {
+    const node = nodeRef.current as unknown as HTMLElement | null;
+    return node ? node.getBoundingClientRect().top + window.scrollY : 0;
+  }, []);
+
+  useImperativeHandle(
+    ref,
+    (): AiChatThreadHandle => ({
+      scrollToEnd: (options) => scrollWindowTo(readWindow().end, options?.animated ?? true),
+      scrollToOffset: ({ offset: y, animated = false }) => scrollWindowTo(threadTop() + y, animated),
+      getScrollView: () => null,
+    }),
+    [threadTop],
+  );
+
+  // The latest handlers, read by one window listener that is never rebound.
+  const handlers = useRef({ chrome, onScroll, onStartReached, onStartReachedThreshold });
+  useIsomorphicLayoutEffect(() => {
+    handlers.current = { chrome, onScroll, onStartReached, onStartReachedThreshold };
+  });
+
+  const report = useCallback(() => {
+    const { chrome: frame, onScroll: listener, onStartReached: startReached, onStartReachedThreshold: zone } = handlers.current;
+    const { y, viewport, end } = readWindow();
+    frame?.reportScroll({ offset: y, viewport, content: end });
+    const top = threadTop();
+    const offset = y - top;
+    if (startReached) {
+      if (offset <= zone) {
+        if (startArmed.current) {
+          startArmed.current = false;
+          pageOut.current = true;
+          startReached();
+        }
+      } else {
+        startArmed.current = true;
+      }
+    }
+    listener?.({
+      nativeEvent: {
+        contentOffset: { x: 0, y: offset },
+        layoutMeasurement: { width: window.innerWidth, height: viewport },
+        contentSize: { width: window.innerWidth, height: end - top },
+        contentInset: { top: 0, left: 0, bottom: 0, right: 0 },
+        zoomScale: 1,
+      },
+    } as NativeSyntheticEvent<NativeScrollEvent>);
+  }, [threadTop]);
+
+  useEffect(() => {
+    let frame = 0;
+    const onWindowChange = () => {
+      if (frame !== 0) return;
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        report();
+      });
+    };
+    window.addEventListener('scroll', onWindowChange, { passive: true });
+    window.addEventListener('resize', onWindowChange);
+    report();
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', onWindowChange);
+      window.removeEventListener('resize', onWindowChange);
+    };
+  }, [report]);
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const height = event.nativeEvent.layout.height;
+      const previous = lastHeight.current;
+      lastHeight.current = height;
+      report();
+      // The page is shared with whatever was on it before — another route
+      // left it scrolled wherever it was — so a following thread opens at its
+      // newest turn rather than at that offset.
+      if (previous === 0) {
+        if (autoFollow) scrollWindowTo(readWindow().end, false);
+        return;
+      }
+      if (height <= previous + 0.5) return;
+      const growth = height - previous;
+
+      // A page landing above the reader: keep the turn they are on where it is.
+      if (maintainStartPosition && pageOut.current) {
+        pageOut.current = false;
+        window.scrollBy({ top: growth, behavior: 'auto' });
+        return;
+      }
+      pageOut.current = false;
+
+      if (!autoFollow) return;
+      if (followThreshold !== undefined) {
+        // Measured against the page BEFORE the growth: was the reader near the
+        // end when this arrived?
+        const { y, viewport, end } = readWindow();
+        if (end - growth - y - viewport > followThreshold) return;
+      }
+      scrollWindowTo(readWindow().end, followAnimated);
+    },
+    [autoFollow, followAnimated, followThreshold, maintainStartPosition, report],
+  );
+
+  return (
+    <View
+      ref={nodeRef}
+      testID={testID}
+      {...dataHook('bloomAiChatThread')}
+      onLayout={onLayout}
+      style={[
+        {
+          // Fills the card between the header and the composer, and anchors a
+          // short exchange just above the composer, as the scroller does.
+          width: '100%',
+          flexGrow: 1,
+          flexDirection: 'column',
+          justifyContent: 'flex-end',
+          gap: 12,
+          paddingLeft: 16,
+          paddingRight: 16,
+          paddingTop: THREAD_PAD_TOP,
+        },
+        style,
+      ]}>
+      {children}
+    </View>
+  );
+});