@dxos/react-ui 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/components/ScrollContainer/ScrollContainer.tsx

@@ -4,8 +4,8 @@
 
 import { createContext } from '@radix-ui/react-context';
 import React, {
-  type HTMLAttributes,
   type PropsWithChildren,
+  type RefObject,
   forwardRef,
   useCallback,
   useEffect,
@@ -17,12 +17,14 @@ import React, {
 
 import { addEventListener, combine } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
-import { useForwardedRef } from '@dxos/react-hooks';
+import { useMergeRefs } from '@dxos/react-hooks';
+import { composable, composableProps, slottable } from '@dxos/ui-theme';
 import { mx } from '@dxos/ui-theme';
+import { type SlottableProps } from '@dxos/ui-types';
 
 import { type ThemedClassName } from '../../util';
 import { IconButton } from '../Button';
-import { ScrollArea } from '../ScrollArea';
+import { ScrollArea, type ScrollAreaRootProps } from '../ScrollArea';
 
 const isBottom = (el: HTMLElement | null) => {
   return !!(el && el.scrollHeight - el.scrollTop === el.clientHeight);
@@ -35,9 +37,15 @@ export interface ScrollController {
 }
 
 type ScrollContainerContextValue = {
-  scrollToBottom: (behavior?: ScrollBehavior) => void;
   controller?: ScrollController;
   pinned?: boolean;
+  overflow?: boolean;
+  /** Called by Viewport to register/unregister the scroll element. */
+  setViewport: (el: HTMLDivElement | null) => void;
+  /** Called by Viewport on wheel events to update pinned state. */
+  setPinned: (value: boolean) => void;
+  /** Called by Viewport on scroll events to update overflow state. */
+  setOverflow: (value: boolean) => void;
 };
 
 const [ScrollContainerProvider, useScrollContainerContext] =
@@ -47,102 +55,85 @@ const [ScrollContainerProvider, useScrollContainerContext] =
 // Root
 //
 
-type RootProps = ThemedClassName<
-  PropsWithChildren<{
-    pin?: boolean;
-    fade?: boolean;
-    behavior?: ScrollBehavior;
-  }>
->;
+type RootProps = PropsWithChildren<{
+  pin?: boolean;
+  behavior?: ScrollBehavior;
+}>;
 
 /**
- * Scroll container that automatically scrolls to the bottom when new content is added.
+ * Headless scroll container that provides context for scroll state.
+ * Render ScrollContainer.Content and ScrollContainer.Viewport as children.
  */
 const Root = forwardRef<ScrollController, RootProps>(
-  ({ children, classNames, pin, fade, behavior: behaviorProp = 'smooth' }, forwardedRef) => {
-    const scrollerRef = useRef<HTMLDivElement>(null);
+  ({ children, pin, behavior: behaviorProp = 'smooth' }, forwardedRef) => {
+    const scrollerRef = useRef<HTMLDivElement | null>(null);
     const autoScrollRef = useRef(false);
-    const [overflow, setOverflow] = useState(false);
     const [pinned, setPinned] = useState(pin);
+    const [overflow, setOverflow] = useState(false);
 
     const timeoutRef = useRef<NodeJS.Timeout>(undefined);
-    const scrollToBottom = useCallback((behavior: ScrollBehavior = behaviorProp) => {
-      if (scrollerRef.current) {
-        // Temporarily hide scrollbar to prevent flickering.
-        autoScrollRef.current = true;
-        scrollerRef.current.classList.add('scrollbar-none');
-        scrollerRef.current.scrollTo({
-          top: scrollerRef.current.scrollHeight,
-          behavior,
-        });
-
-        clearTimeout(timeoutRef.current);
-        if (behavior !== 'instant') {
-          timeoutRef.current = setTimeout(() => {
-            scrollerRef.current?.classList.remove('scrollbar-none');
-            autoScrollRef.current = false;
-          }, 500);
+    const scrollToBottom = useCallback(
+      (behavior: ScrollBehavior = behaviorProp) => {
+        if (scrollerRef.current) {
+          if (behavior !== 'instant') {
+            // Temporarily hide scrollbar to prevent flickering during smooth scroll.
+            // For instant scrolling we skip this — there's no animation to hide,
+            // and adding the class changes element size which re-fires the ResizeObserver.
+            autoScrollRef.current = true;
+            scrollerRef.current.classList.add('scrollbar-none');
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = setTimeout(() => {
+              scrollerRef.current?.classList.remove('scrollbar-none');
+              autoScrollRef.current = false;
+            }, 500);
+          }
+
+          scrollerRef.current.scrollTo({
+            top: scrollerRef.current.scrollHeight,
+            behavior,
+          });
+
+          setPinned(true);
         }
+      },
+      [behaviorProp],
+    );
 
-        setPinned(true);
-      }
-    }, []);
-
-    const controller = useMemo(
+    const controller = useMemo<ScrollController>(
       () => ({
-        viewport: scrollerRef.current,
+        get viewport() {
+          return scrollerRef.current;
+        },
         scrollToTop: () => {
           invariant(scrollerRef.current);
           scrollerRef.current.scrollTo({ top: 0, behavior: 'smooth' });
           setPinned(false);
         },
-        scrollToBottom: () => {
-          scrollToBottom('smooth');
+        scrollToBottom: (behavior = 'smooth' as ScrollBehavior) => {
+          scrollToBottom(behavior);
         },
       }),
-      [scrollToBottom, scrollerRef.current],
+      [scrollToBottom],
     );
 
     // Scroll controller imperative ref.
     useImperativeHandle(forwardedRef, () => controller, [controller]);
 
-    // Listen for scroll events.
-    useEffect(() => {
-      if (!scrollerRef.current) {
-        return;
-      }
-
-      return combine(
-        // Check if user scrolls.
-        addEventListener(scrollerRef.current, 'wheel', () => {
-          setPinned(isBottom(scrollerRef.current));
-        }),
-        // Check if scrolls.
-        addEventListener(scrollerRef.current, 'scroll', () => {
-          setOverflow((scrollerRef.current?.scrollTop ?? 0) > 0);
-        }),
-      );
+    // Called by Viewport when the scroll element mounts/unmounts.
+    const setViewport = useCallback((el: HTMLDivElement | null) => {
+      scrollerRef.current = el;
     }, []);
 
     return (
-      <ScrollContainerProvider pinned={pinned} controller={controller} scrollToBottom={scrollToBottom}>
-        <div className='relative grid dx-container overflow-hidden'>
-          {fade && (
-            <div
-              role='none'
-              data-visible={overflow}
-              className={mx(
-                // NOTE: Gradients may not be visible with dark reader extensions.
-                'z-10 absolute top-0 inset-x-0 h-24 w-full',
-                'opacity-0 duration-200 transition-opacity data-[visible="true"]:opacity-100',
-                'bg-gradient-to-b from-(--surface-bg) to-transparent pointer-events-none',
-              )}
-            />
-          )}
-          <ScrollArea.Root classNames={mx('min-h-0', classNames)} thin>
-            <ScrollArea.Viewport ref={scrollerRef}>{children}</ScrollArea.Viewport>
-          </ScrollArea.Root>
-        </div>
+      <ScrollContainerProvider
+        pinned={pinned}
+        overflow={overflow}
+        controller={controller}
+        setViewport={setViewport}
+        setPinned={setPinned}
+        setOverflow={setOverflow}
+      >
+        {children}
       </ScrollContainerProvider>
     );
   },
@@ -150,41 +141,154 @@ const Root = forwardRef<ScrollController, RootProps>(
 
 Root.displayName = 'ScrollContainer.Root';
 
+//
+// Content
+//
+
+type ContentProps = Pick<ScrollAreaRootProps, 'thin' | 'padding' | 'centered'>;
+
+/**
+ * Composable wrapper around ScrollArea.Root.
+ * Provides the DOM structure for the scroll container.
+ */
+const Content = composable<HTMLDivElement, ContentProps>(
+  ({ children, thin, padding, centered, ...props }, forwardedRef) => {
+    return (
+      <ScrollArea.Root
+        {...composableProps(props, { classNames: 'relative' })}
+        thin={thin}
+        padding={padding}
+        centered={centered}
+        ref={forwardedRef}
+      >
+        {children}
+      </ScrollArea.Root>
+    );
+  },
+);
+
+Content.displayName = 'ScrollContainer.Content';
+
 //
 // Viewport
 //
 
 const VIEWPORT_NAME = 'ScrollContainer.Viewport';
 
-type ViewportProps = ThemedClassName<PropsWithChildren<Omit<HTMLAttributes<HTMLDivElement>, 'className'>>>;
+type ViewportProps = SlottableProps;
 
-const Viewport = forwardRef<HTMLDivElement, ViewportProps>(({ classNames, children, ...props }, forwardedRef) => {
-  const contentRef = useForwardedRef(forwardedRef);
-  const { pinned, scrollToBottom } = useScrollContainerContext(VIEWPORT_NAME);
+const Viewport = slottable<HTMLDivElement, ViewportProps>(({ children, asChild, ...props }, forwardedRef) => {
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const mergedRef = useMergeRefs([forwardedRef, scrollerRef]);
+  const { setViewport, setPinned, setOverflow } = useScrollContainerContext(VIEWPORT_NAME);
 
+  // Register the scroll element with Root and set up wheel/scroll listeners.
   useEffect(() => {
-    if (!pinned || !contentRef.current) {
+    const el = scrollerRef.current;
+    if (!el) {
       return;
     }
 
-    // Scroll instantly otherwise it might move while we're scrolling.
-    scrollToBottom();
+    setViewport(el);
 
-    // Setup resize observer to detect content changes.
-    const resizeObserver = new ResizeObserver(() => scrollToBottom());
-    resizeObserver.observe(contentRef.current);
-    return () => resizeObserver.disconnect();
-  }, [pinned, scrollToBottom]);
+    return combine(
+      addEventListener(el, 'wheel', () => setPinned(isBottom(el))),
+      addEventListener(el, 'scroll', () => setOverflow((el.scrollTop ?? 0) > 0)),
+      () => setViewport(null),
+    );
+  }, [setViewport, setPinned, setOverflow]);
 
   return (
-    <div className={mx('w-full', classNames)} {...props} ref={contentRef}>
-      {children}
-    </div>
+    <>
+      <ScrollArea.Viewport asChild={asChild} {...composableProps(props)} ref={mergedRef}>
+        {children}
+      </ScrollArea.Viewport>
+      <PinEffect scrollerRef={scrollerRef} />
+    </>
   );
 });
 
 Viewport.displayName = VIEWPORT_NAME;
 
+/**
+ * Isolated component that consumes pinned/controller from context.
+ * Kept separate so that Viewport does not re-render when pinned changes.
+ */
+const PIN_EFFECT_NAME = 'ScrollContainer.PinEffect';
+
+const PinEffect = ({ scrollerRef }: { scrollerRef: RefObject<HTMLDivElement | null> }) => {
+  const { pinned, controller } = useScrollContainerContext(PIN_EFFECT_NAME);
+
+  // Pin scroll to bottom when content changes.
+  useEffect(() => {
+    const viewport = scrollerRef.current;
+    if (!pinned || !viewport) {
+      return;
+    }
+
+    // Scroll instantly so we don't visually jump while content is being added.
+    controller?.scrollToBottom('instant');
+
+    // Setup resize observer on content children to detect size changes (e.g. streaming).
+    // We observe children rather than the viewport itself, because the viewport's size
+    // stays fixed — only its content grows.
+    // Use instant scroll in the callback — smooth scrolling adds/removes the
+    // scrollbar-none class, which changes the element size and re-fires the
+    // observer, creating an infinite loop.
+    const resizeObserver = new ResizeObserver(() => controller?.scrollToBottom('smooth'));
+    Array.from(viewport.children).forEach((child) => {
+      resizeObserver.observe(child);
+    });
+
+    // Watch for added/removed children.
+    const mutationObserver = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (node instanceof Element) {
+            resizeObserver.observe(node);
+          }
+        });
+      });
+
+      controller?.scrollToBottom('smooth');
+    });
+    mutationObserver.observe(viewport, { childList: true });
+
+    return () => {
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+    };
+  }, [pinned, controller, scrollerRef]);
+
+  return null;
+};
+
+//
+// Fade
+//
+
+const FADE_NAME = 'ScrollContainer.Fade';
+
+type FadeProps = {};
+
+const Fade = () => {
+  const { overflow } = useScrollContainerContext(FADE_NAME);
+
+  return (
+    <div
+      data-visible={overflow}
+      className={mx(
+        // NOTE: Gradients may not be visible with dark reader extensions.
+        'z-10 absolute top-0 inset-x-0 h-24 w-full',
+        'opacity-0 duration-200 transition-opacity data-[visible="true"]:opacity-100',
+        'bg-gradient-to-b from-(--color-base-surface) to-transparent pointer-events-none',
+      )}
+    />
+  );
+};
+
+Fade.displayName = FADE_NAME;
+
 //
 // ScrollDownButton
 //
@@ -194,11 +298,10 @@ const SCROLL_DOWN_BUTTON_NAME = 'ScrollContainer.ScrollDownButton';
 type ScrollDownButtonProps = ThemedClassName;
 
 const ScrollDownButton = ({ classNames }: ScrollDownButtonProps) => {
-  const { pinned, scrollToBottom } = useScrollContainerContext(SCROLL_DOWN_BUTTON_NAME);
+  const { pinned, controller } = useScrollContainerContext(SCROLL_DOWN_BUTTON_NAME);
 
   return (
     <div
-      role='none'
       className={mx(
         'absolute bottom-2 right-4 opacity-100 transition-opacity duration-300',
         pinned && 'opacity-0',
@@ -211,7 +314,7 @@ const ScrollDownButton = ({ classNames }: ScrollDownButtonProps) => {
         iconOnly
         size={4}
         label='Scroll down'
-        onClick={() => scrollToBottom()}
+        onClick={() => controller?.scrollToBottom()}
       />
     </div>
   );
@@ -227,12 +330,16 @@ export { useScrollContainerContext };
 
 export const ScrollContainer = {
   Root,
+  Content,
   Viewport,
+  Fade,
   ScrollDownButton,
 };
 
 export type {
   RootProps as ScrollContainerRootProps,
+  ContentProps as ScrollContainerContentProps,
   ViewportProps as ScrollContainerViewportProps,
+  FadeProps as ScrollContainerFadeProps,
   ScrollDownButtonProps as ScrollContainerScrollDownButtonProps,
 };

package/src/components/Select/Select.stories.tsx

@@ -5,20 +5,19 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 
 import { withTheme } from '../../testing';
 import { withLayoutVariants } from '../../testing';
-
 import { Select } from './Select';
 
-faker.seed(1234);
+random.seed(1234);
 
 type ItemProps = { id: string; text: string };
 
-type StoryProps = { items: ItemProps[] };
+type DefaultStoryProps = { items: ItemProps[] };
 
-const DefaultStory = ({ items = [] }: StoryProps) => {
+const DefaultStory = ({ items = [] }: DefaultStoryProps) => {
   const [value, setValue] = useState<string>();
   return (
     <Select.Root value={value} onValueChange={setValue}>
@@ -53,6 +52,6 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    items: Array.from({ length: 16 }).map((_, i) => ({ id: `item-${i}`, text: faker.lorem.word() })),
+    items: Array.from({ length: 16 }).map((_, i) => ({ id: `item-${i}`, text: random.lorem.word() })),
   },
 };

package/src/components/Separator/Separator.tsx

@@ -1,24 +1,21 @@
 //
 // Copyright 2023 DXOS.org
 //
-import {
-  Separator as SeparatorPrimitive,
-  type SeparatorProps as SeparatorPrimitiveProps,
-} from '@radix-ui/react-separator';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
 import React, { forwardRef } from 'react';
 
 import { useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
 
-type SeparatorProps = ThemedClassName<SeparatorPrimitiveProps> & { subdued?: boolean };
+type SeparatorProps = ThemedClassName<SeparatorPrimitive.SeparatorProps> & { subdued?: boolean };
 
 const Separator = forwardRef<HTMLDivElement, SeparatorProps>(
   ({ classNames, orientation = 'horizontal', subdued, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
     return (
-      <SeparatorPrimitive
-        orientation={orientation}
+      <SeparatorPrimitive.Root
         {...props}
+        orientation={orientation}
         className={tx('separator.root', { orientation, subdued }, classNames)}
         ref={forwardedRef}
       />

package/src/components/Skeleton/Skeleton.stories.tsx

@@ -5,7 +5,6 @@
 import React from 'react';
 
 import { withTheme } from '../../testing';
-
 import { Skeleton } from './Skeleton';
 
 export default {

package/src/components/Splitter/Splitter.stories.tsx

@@ -9,50 +9,50 @@ import { Panel } from '../../primitives';
 import { withLayout, withTheme } from '../../testing';
 import { ScrollArea } from '../ScrollArea';
 import { Toolbar } from '../Toolbar';
-
 import { Splitter, type SplitterRootProps } from './Splitter';
 
 const PanelContent = forwardRef<HTMLDivElement, ComponentPropsWithoutRef<'div'> & { label: string }>(
-  ({ label, ...props }, ref) => (
-    <div ref={ref} {...props}>
-      <Panel.Root>
-        <Panel.Toolbar asChild>
-          <Toolbar.Root>{label}</Toolbar.Root>
-        </Panel.Toolbar>
-        <Panel.Content asChild>
-          <ScrollArea.Root orientation='vertical'>
-            <ScrollArea.Viewport>
-              {Array.from({ length: 100 }).map((_, i) => (
-                <div key={i} className='p-1'>
-                  {label}-{i}
-                </div>
-              ))}
-            </ScrollArea.Viewport>
-          </ScrollArea.Root>
-        </Panel.Content>
-      </Panel.Root>
-    </div>
+  ({ label, ...props }, forwardedRef) => (
+    <Panel.Root {...props} ref={forwardedRef}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>{label}</Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content asChild>
+        <ScrollArea.Root orientation='vertical'>
+          <ScrollArea.Viewport>
+            {Array.from({ length: 100 }).map((_, i) => (
+              <div key={i} className='p-1'>
+                {label}-{i}
+              </div>
+            ))}
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Panel.Content>
+    </Panel.Root>
   ),
 );
 
 const DefaultStory = (props: SplitterRootProps) => {
-  const [mode, setMode] = useState(props.mode ?? 'both');
+  const [mode, setMode] = useState(props.mode ?? 'split');
+  const [ratio, setRatio] = useState(props.ratio ?? 0.5);
 
   return (
     <Panel.Root>
       <Panel.Toolbar asChild>
         <Toolbar.Root>
-          <Toolbar.Button onClick={() => setMode('upper')}>A</Toolbar.Button>
-          <Toolbar.Button onClick={() => setMode('both')}>A + B</Toolbar.Button>
-          <Toolbar.Button onClick={() => setMode('lower')}>B</Toolbar.Button>
+          <Toolbar.Button onClick={() => setMode('top')}>A</Toolbar.Button>
+          <Toolbar.Button onClick={() => setMode('split')}>A+B</Toolbar.Button>
+          <Toolbar.Button onClick={() => setMode('bottom')}>B</Toolbar.Button>
+          <Toolbar.Separator />
+          <Toolbar.Button onClick={() => setRatio((r) => 1 - r)}>Toggle</Toolbar.Button>
         </Toolbar.Root>
       </Panel.Toolbar>
       <Panel.Content asChild>
-        <Splitter.Root mode={mode} ratio={props.ratio}>
-          <Splitter.Panel asChild position='upper'>
+        <Splitter.Root mode={mode} ratio={ratio}>
+          <Splitter.Panel asChild position='top'>
             <PanelContent label='A' />
           </Splitter.Panel>
-          <Splitter.Panel asChild position='lower'>
+          <Splitter.Panel asChild position='bottom'>
             <PanelContent label='B' />
           </Splitter.Panel>
         </Splitter.Root>
@@ -77,7 +77,7 @@ type Story = StoryObj<SplitterRootProps>;
 
 export const Default: Story = {
   args: {
-    mode: 'both',
-    ratio: 0.5,
+    mode: 'split',
+    ratio: 0.4,
   },
 };