@dxos/react-ui 0.8.4-main.67995b8 → 0.8.4-main.6fa680abb7

package/src/components/ScrollArea/ScrollArea.tsx

@@ -1,111 +1,113 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import {
-  Root as ScrollAreaPrimitiveRoot,
-  type ScrollAreaProps as ScrollAreaPrimitiveRootProps,
-  Viewport as ScrollAreaPrimitiveViewport,
-  type ScrollAreaViewportProps as ScrollAreaPrimitiveViewportProps,
-  Scrollbar as ScrollAreaPrimitiveScrollbar,
-  type ScrollAreaScrollbarProps as ScrollAreaPrimitiveScrollbarProps,
-  Thumb as ScrollAreaPrimitiveThumb,
-  type ScrollAreaThumbProps as ScrollAreaPrimitiveThumbProps,
-  Corner as ScrollAreaPrimitiveCorner,
-  type ScrollAreaCornerProps as ScrollAreaPrimitiveCornerProps,
-} from '@radix-ui/react-scroll-area';
-import React, { forwardRef } from 'react';
+import { createContext } from '@radix-ui/react-context';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { type HTMLAttributes, forwardRef } from 'react';
+
+import { composableProps } from '@dxos/ui-theme';
+import { type AllowedAxis, type SlottableProps, type ThemedClassName } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
-import { type ThemedClassName } from '../../util';
 
-type ScrollAreaVariant = 'coarse' | 'fine';
+//
+// Context
+//
 
-type ScrollAreaRootProps = ThemedClassName<ScrollAreaPrimitiveRootProps>;
+const SCROLLAREA_NAME = 'ScrollArea';
+
+type ScrollAreaContextType = {
+  /** Orientation of scrollbars. */
+  orientation: AllowedAxis;
+  /** Hide scrollbars when not scrolling. */
+  autoHide: boolean;
+  /** Apply padding to opposite side of scrollbar. */
+  margin?: boolean;
+  /** Apply padding. */
+  padding: boolean;
+  /** Use thin scrollbars. */
+  thin: boolean;
+  /** Enable snap scrolling. */
+  snap: boolean;
+};
+
+const [ScrollAreaProvider, useScrollAreaContext] = createContext<ScrollAreaContextType>(SCROLLAREA_NAME);
+
+//
+// Root
+//
+
+const SCROLLAREA_ROOT_NAME = 'ScrollArea.Root';
+
+type ScrollAreaRootProps = SlottableProps<HTMLDivElement, Partial<ScrollAreaContextType>>;
 
 /**
- * @deprecated
+ * ScrollArea provides native scrollbars with custom styling.
  */
-const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(({ classNames, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <ScrollAreaPrimitiveRoot
-      {...props}
-      className={tx('scrollArea.root', 'scroll-area', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
-});
-
-type ScrollAreaViewportProps = ThemedClassName<ScrollAreaPrimitiveViewportProps>;
-
-const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
-  ({ classNames, ...props }, forwardedRef) => {
+const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(
+  (
+    {
+      children,
+      asChild,
+      orientation = 'vertical',
+      autoHide = true,
+      margin = false,
+      padding = false,
+      thin = false,
+      snap = false,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { className, ...rest } = composableProps(props);
+    const Comp = asChild ? Slot : Primitive.div;
     const { tx } = useThemeContext();
+    const options = { orientation, autoHide, margin, padding, thin, snap };
+
     return (
-      <ScrollAreaPrimitiveViewport
-        {...props}
-        className={tx('scrollArea.viewport', 'scroll-area', {}, classNames)}
-        ref={forwardedRef}
-      />
+      <ScrollAreaProvider {...options}>
+        <Comp {...rest} className={tx('scrollArea.root', options, className)} ref={forwardedRef}>
+          {children}
+        </Comp>
+      </ScrollAreaProvider>
     );
   },
 );
 
-type ScrollAreaScrollbarProps = ThemedClassName<ScrollAreaPrimitiveScrollbarProps> & { variant?: ScrollAreaVariant };
+ScrollAreaRoot.displayName = SCROLLAREA_ROOT_NAME;
+
+//
+// Viewport
+//
+
+const SCROLLAREA_VIEWPORT_NAME = 'ScrollArea.Viewport';
+
+type ScrollAreaViewportProps = ThemedClassName<HTMLAttributes<HTMLDivElement>>;
 
-const ScrollAreaScrollbar = forwardRef<HTMLDivElement, ScrollAreaScrollbarProps>(
-  ({ classNames, variant = 'fine', ...props }, forwardedRef) => {
+const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
+  ({ classNames, children, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
+    const options = useScrollAreaContext(SCROLLAREA_VIEWPORT_NAME);
+
     return (
-      <ScrollAreaPrimitiveScrollbar
-        data-variant={variant}
-        {...props}
-        className={tx('scrollArea.scrollbar', 'scroll-area__scrollbar', {}, classNames)}
-        ref={forwardedRef}
-      />
+      <div {...props} className={tx('scrollArea.viewport', options, classNames)} ref={forwardedRef}>
+        {children}
+      </div>
     );
   },
 );
 
-type ScrollAreaThumbProps = ThemedClassName<ScrollAreaPrimitiveThumbProps>;
-
-const ScrollAreaThumb = forwardRef<HTMLDivElement, ScrollAreaThumbProps>(({ classNames, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <ScrollAreaPrimitiveThumb
-      {...props}
-      className={tx('scrollArea.thumb', 'scroll-area__thumb', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
-});
-
-type ScrollAreaCornerProps = ThemedClassName<ScrollAreaPrimitiveCornerProps>;
-
-const ScrollAreaCorner = forwardRef<HTMLDivElement, ScrollAreaCornerProps>(({ classNames, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <ScrollAreaPrimitiveCorner
-      {...props}
-      className={tx('scrollArea.corner', 'scroll-area__corner', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
-});
+ScrollAreaViewport.displayName = SCROLLAREA_VIEWPORT_NAME;
+
+//
+// ScrollArea
+//
 
 export const ScrollArea = {
   Root: ScrollAreaRoot,
   Viewport: ScrollAreaViewport,
-  Scrollbar: ScrollAreaScrollbar,
-  Thumb: ScrollAreaThumb,
-  Corner: ScrollAreaCorner,
 };
 
-export type {
-  ScrollAreaRootProps,
-  ScrollAreaViewportProps,
-  ScrollAreaScrollbarProps,
-  ScrollAreaThumbProps,
-  ScrollAreaCornerProps,
-};
+export type { ScrollAreaRootProps, ScrollAreaViewportProps };

package/src/components/ScrollArea/index.ts

@@ -1,5 +1,5 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
 export * from './ScrollArea';

package/src/components/ScrollContainer/ScrollContainer.stories.tsx

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useRef, useState } from 'react';
+
+import { faker } from '@dxos/random';
+
+import { Panel } from '../../primitives';
+import { withLayout, withTheme } from '../../testing';
+import { Button } from '../Button';
+import { Toolbar } from '../Toolbar';
+
+import { ScrollContainer, type ScrollContainerRootProps, type ScrollController } from './ScrollContainer';
+
+type StoryProps = ScrollContainerRootProps & { running?: boolean; initialLines?: number };
+
+const DefaultStory = ({ initialLines = 0, running: runningProp, ...props }: StoryProps) => {
+  const [lines, setLines] = useState<string[]>([]);
+  const [running, setRunning] = useState(runningProp);
+  const scroller = useRef<ScrollController>(null);
+  useEffect(() => {
+    setLines(Array.from({ length: initialLines }, () => faker.lorem.paragraph()));
+  }, [initialLines]);
+  useEffect(() => {
+    if (!running) {
+      return;
+    }
+
+    const i = setInterval(() => {
+      setLines((lines) => [...lines, faker.lorem.paragraph()]);
+    }, 500);
+
+    return () => clearInterval(i);
+  }, [running]);
+
+  return (
+    <Panel.Root className='dx-article'>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>
+          <Button onClick={() => setRunning((running) => !running)}>{running ? 'Stop' : 'Start'}</Button>
+          <Button onClick={() => scroller.current?.scrollToBottom()}>Scroll to bottom</Button>
+          <Toolbar.Separator />
+          <div className='px-1'>{lines.length}</div>
+        </Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content asChild>
+        <ScrollContainer.Root {...props} ref={scroller}>
+          <ScrollContainer.Viewport>
+            {lines.map((line, index) => (
+              <div key={index} className='p-2 text-description'>
+                {line}
+              </div>
+            ))}
+          </ScrollContainer.Viewport>
+          <ScrollContainer.ScrollDownButton />
+        </ScrollContainer.Root>
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-core/components/ScrollContainer',
+  component: ScrollContainer.Root,
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-[30rem]' })],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    pin: true,
+    fade: true,
+    running: true,
+  },
+};
+
+export const Large: Story = {
+  args: {
+    pin: true,
+    fade: true,
+    initialLines: 100,
+  },
+};

package/src/components/ScrollContainer/ScrollContainer.tsx

@@ -0,0 +1,238 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, {
+  type HTMLAttributes,
+  type PropsWithChildren,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { addEventListener, combine } from '@dxos/async';
+import { invariant } from '@dxos/invariant';
+import { useForwardedRef } from '@dxos/react-hooks';
+import { mx } from '@dxos/ui-theme';
+
+import { type ThemedClassName } from '../../util';
+import { IconButton } from '../Button';
+import { ScrollArea } from '../ScrollArea';
+
+const isBottom = (el: HTMLElement | null) => {
+  return !!(el && el.scrollHeight - el.scrollTop === el.clientHeight);
+};
+
+export interface ScrollController {
+  viewport: HTMLDivElement | null;
+  scrollToTop: (behavior?: ScrollBehavior) => void;
+  scrollToBottom: (behavior?: ScrollBehavior) => void;
+}
+
+type ScrollContainerContextValue = {
+  scrollToBottom: (behavior?: ScrollBehavior) => void;
+  controller?: ScrollController;
+  pinned?: boolean;
+};
+
+const [ScrollContainerProvider, useScrollContainerContext] =
+  createContext<ScrollContainerContextValue>('ScrollContainer');
+
+//
+// Root
+//
+
+type RootProps = ThemedClassName<
+  PropsWithChildren<{
+    pin?: boolean;
+    fade?: boolean;
+    behavior?: ScrollBehavior;
+  }>
+>;
+
+/**
+ * Scroll container that automatically scrolls to the bottom when new content is added.
+ */
+const Root = forwardRef<ScrollController, RootProps>(
+  ({ children, classNames, pin, fade, behavior: behaviorProp = 'smooth' }, forwardedRef) => {
+    const scrollerRef = useRef<HTMLDivElement>(null);
+    const autoScrollRef = useRef(false);
+    const [overflow, setOverflow] = useState(false);
+    const [pinned, setPinned] = useState(pin);
+
+    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);
+        }
+
+        setPinned(true);
+      }
+    }, []);
+
+    const controller = useMemo(
+      () => ({
+        viewport: scrollerRef.current,
+        scrollToTop: () => {
+          invariant(scrollerRef.current);
+          scrollerRef.current.scrollTo({ top: 0, behavior: 'smooth' });
+          setPinned(false);
+        },
+        scrollToBottom: () => {
+          scrollToBottom('smooth');
+        },
+      }),
+      [scrollToBottom, scrollerRef.current],
+    );
+
+    // 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);
+        }),
+      );
+    }, []);
+
+    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>
+    );
+  },
+);
+
+Root.displayName = 'ScrollContainer.Root';
+
+//
+// Viewport
+//
+
+const VIEWPORT_NAME = 'ScrollContainer.Viewport';
+
+type ViewportProps = ThemedClassName<PropsWithChildren<Omit<HTMLAttributes<HTMLDivElement>, 'className'>>>;
+
+const Viewport = forwardRef<HTMLDivElement, ViewportProps>(({ classNames, children, ...props }, forwardedRef) => {
+  const contentRef = useForwardedRef(forwardedRef);
+  const { pinned, scrollToBottom } = useScrollContainerContext(VIEWPORT_NAME);
+
+  useEffect(() => {
+    if (!pinned || !contentRef.current) {
+      return;
+    }
+
+    // Scroll instantly otherwise it might move while we're scrolling.
+    scrollToBottom();
+
+    // Setup resize observer to detect content changes.
+    const resizeObserver = new ResizeObserver(() => scrollToBottom());
+    resizeObserver.observe(contentRef.current);
+    return () => resizeObserver.disconnect();
+  }, [pinned, scrollToBottom]);
+
+  return (
+    <div className={mx('w-full', classNames)} {...props} ref={contentRef}>
+      {children}
+    </div>
+  );
+});
+
+Viewport.displayName = VIEWPORT_NAME;
+
+//
+// ScrollDownButton
+//
+
+const SCROLL_DOWN_BUTTON_NAME = 'ScrollContainer.ScrollDownButton';
+
+type ScrollDownButtonProps = ThemedClassName;
+
+const ScrollDownButton = ({ classNames }: ScrollDownButtonProps) => {
+  const { pinned, scrollToBottom } = 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',
+        classNames,
+      )}
+    >
+      <IconButton
+        variant='primary'
+        icon='ph--arrow-down--regular'
+        iconOnly
+        size={4}
+        label='Scroll down'
+        onClick={() => scrollToBottom()}
+      />
+    </div>
+  );
+};
+
+ScrollDownButton.displayName = SCROLL_DOWN_BUTTON_NAME;
+
+//
+// ScrollContainer
+//
+
+export { useScrollContainerContext };
+
+export const ScrollContainer = {
+  Root,
+  Viewport,
+  ScrollDownButton,
+};
+
+export type {
+  RootProps as ScrollContainerRootProps,
+  ViewportProps as ScrollContainerViewportProps,
+  ScrollDownButtonProps as ScrollContainerScrollDownButtonProps,
+};

package/src/components/ScrollContainer/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ScrollContainer';

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

@@ -2,15 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
-import { type StoryObj } from '@storybook/react-vite';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
 import { faker } from '@dxos/random';
 
+import { withTheme } from '../../testing';
+import { withLayoutVariants } from '../../testing';
+
 import { Select } from './Select';
-import { withSurfaceVariantsLayout, withTheme } from '../../testing';
 
 faker.seed(1234);
 
@@ -41,15 +41,18 @@ const DefaultStory = ({ items = [] }: StoryProps) => {
   );
 };
 
-export const Default: StoryObj<StoryProps> = {
+const meta = {
+  title: 'ui/react-ui-core/components/Select',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayoutVariants()],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
   args: {
     items: Array.from({ length: 16 }).map((_, i) => ({ id: `item-${i}`, text: faker.lorem.word() })),
   },
 };
-
-export default {
-  title: 'ui/react-ui-core/Select',
-  render: DefaultStory,
-  decorators: [withSurfaceVariantsLayout(), withTheme],
-  parameters: { chromatic: { disableSnapshot: false } },
-};