@dxos/react-ui 0.8.4-main.2e9d522 → 0.8.4-main.3c1ae3b

package/src/components/Message/Message.stories.tsx

@@ -2,15 +2,15 @@
 // Copyright 2022 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { type MessageValence } from '@dxos/react-ui-types';
 
-import { Callout } from './Message';
 import { withTheme } from '../../testing';
 
+import { Callout } from './Message';
+
 type StoryProps = {
   valence: MessageValence;
   title: string;
@@ -24,9 +24,9 @@ const DefaultStory = ({ valence, title, body }: StoryProps) => (
   </Callout.Root>
 );
 
-export default {
+const meta = {
   title: 'ui/react-ui-core/Callout',
-  component: Callout,
+  component: Callout.Root as any,
   render: DefaultStory,
   decorators: [withTheme],
   parameters: { chromatic: { disableSnapshot: false } },
@@ -36,9 +36,13 @@ export default {
       options: ['success', 'info', 'warning', 'error', 'neutral'],
     },
   },
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {
+export const Default: Story = {
   args: {
     valence: 'neutral',
     title: 'Alert title',

package/src/components/Message/Message.tsx

@@ -8,7 +8,7 @@ import { Slot } from '@radix-ui/react-slot';
 import React, { type ComponentPropsWithRef, forwardRef } from 'react';
 
 import { useId } from '@dxos/react-hooks';
-import { type MessageValence, type Elevation } from '@dxos/react-ui-types';
+import { type Elevation, type MessageValence } from '@dxos/react-ui-types';
 
 import { useElevationContext, useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
@@ -53,6 +53,7 @@ const MessageRoot = forwardRef<HTMLDivElement, MessageRootProps>(
     const descriptionId = useId('message__description', propsDescriptionId);
     const elevation = useElevationContext(propsElevation);
     const Root = asChild ? Slot : Primitive.div;
+
     return (
       <MessageProvider {...{ titleId, descriptionId, valence }}>
         <Root
@@ -84,6 +85,7 @@ const MessageTitle = forwardRef<HTMLHeadingElement, MessageTitleProps>(
     const { tx } = useThemeContext();
     const { titleId, valence } = useMessageContext(MESSAGE_TITLE_NAME);
     const Root = asChild ? Slot : Primitive.h2;
+
     return (
       <Root
         {...props}

package/src/components/Popover/Popover.stories.tsx

@@ -2,15 +2,15 @@
 // Copyright 2022 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { type PropsWithChildren, type ReactNode, useRef, useState } from 'react';
 
 import { faker } from '@dxos/random';
 
-import { Popover } from './Popover';
 import { withTheme } from '../../testing';
-import { Button } from '../Buttons';
+import { Button } from '../Button';
+
+import { Popover } from './Popover';
 
 faker.seed(1234);
 
@@ -28,15 +28,18 @@ const DefaultStory = ({ openTrigger, children }: PropsWithChildren<{ openTrigger
   );
 };
 
-export default {
+const meta = {
   title: 'ui/react-ui-core/Popover',
-  component: Popover,
+  component: Popover.Root,
   render: DefaultStory,
   decorators: [withTheme],
-  parameters: { chromatic: { disableSnapshot: false } },
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {
+export const Default: Story = {
   args: {
     openTrigger: <Button>Open popover</Button>,
     children: faker.lorem.paragraphs(3),

package/src/components/Popover/Popover.tsx

@@ -22,17 +22,18 @@ import { useControllableState } from '@radix-ui/react-use-controllable-state';
 import { hideOthers } from 'aria-hidden';
 import React, {
   type ComponentPropsWithRef,
-  forwardRef,
+  type ComponentPropsWithoutRef,
   type ElementRef,
-  type RefObject,
+  type FC,
+  type MutableRefObject,
   type ReactNode,
-  useRef,
+  type RefObject,
+  forwardRef,
   useCallback,
-  type ComponentPropsWithoutRef,
-  type FC,
-  useState,
   useEffect,
-  type MutableRefObject,
+  useMemo,
+  useRef,
+  useState,
 } from 'react';
 import { RemoveScroll } from 'react-remove-scroll';
 
@@ -182,7 +183,7 @@ PopoverTrigger.displayName = TRIGGER_NAME;
 const VIRTUAL_TRIGGER_NAME = 'PopoverVirtualTrigger';
 
 interface PopoverVirtualTriggerProps {
-  virtualRef: RefObject<PopoverTriggerElement>;
+  virtualRef: RefObject<PopoverTriggerElement | null>;
 }
 
 const PopoverVirtualTrigger = (props: ScopedProps<PopoverVirtualTriggerProps>) => {
@@ -194,7 +195,7 @@ const PopoverVirtualTrigger = (props: ScopedProps<PopoverVirtualTriggerProps>) =
       context.triggerRef.current = virtualRef.current;
     }
   });
-  return <PopperPrimitive.Anchor {...popperScope} virtualRef={virtualRef} />;
+  return <PopperPrimitive.Anchor {...popperScope} virtualRef={virtualRef as RefObject<PopoverTriggerElement>} />;
 };
 
 PopoverVirtualTrigger.displayName = VIRTUAL_TRIGGER_NAME;
@@ -396,6 +397,7 @@ type PopoverContentImplElement = ElementRef<typeof PopperPrimitive.Content>;
 type FocusScopeProps = ComponentPropsWithoutRef<typeof FocusScope>;
 type DismissableLayerProps = ComponentPropsWithoutRef<typeof DismissableLayer>;
 type PopperContentProps = ThemedClassName<ComponentPropsWithoutRef<typeof PopperPrimitive.Content>>;
+
 interface PopoverContentImplProps
   extends Omit<PopperContentProps, 'onPlaced'>,
     Omit<DismissableLayerProps, 'onDismiss'> {
@@ -431,6 +433,7 @@ const PopoverContentImpl = forwardRef<PopoverContentImplElement, PopoverContentI
       onFocusOutside,
       onInteractOutside,
       collisionPadding = 8,
+      collisionBoundary,
       classNames,
       ...contentProps
     } = props;
@@ -440,10 +443,23 @@ const PopoverContentImpl = forwardRef<PopoverContentImplElement, PopoverContentI
     const elevation = useElevationContext();
     const safeCollisionPadding = useSafeCollisionPadding(collisionPadding);
 
-    // Make sure the whole tree has focus guards as our `Popover` may be
-    // the last element in the DOM (because of the `Portal`)
+    // Make sure the whole tree has focus guards as our `Popover` may be the last element in the DOM (because of the `Portal`)
     useFocusGuards();
 
+    // Check for the closest annotated collision boundary in the DOM tree.
+    const computedCollisionBoundary = useMemo(() => {
+      const closestBoundary = context.triggerRef.current?.closest(
+        '[data-popover-collision-boundary]',
+      ) as HTMLElement | null;
+      return closestBoundary
+        ? Array.isArray(collisionBoundary)
+          ? [closestBoundary, ...collisionBoundary]
+          : collisionBoundary
+            ? [closestBoundary, collisionBoundary]
+            : [closestBoundary]
+        : collisionBoundary;
+    }, [context.open, collisionBoundary, context.triggerRef.current]);
+
     return (
       <FocusScope
         asChild
@@ -468,11 +484,12 @@ const PopoverContentImpl = forwardRef<PopoverContentImplElement, PopoverContentI
             {...popperScope}
             {...contentProps}
             collisionPadding={safeCollisionPadding}
+            collisionBoundary={computedCollisionBoundary}
             className={tx('popover.content', 'popover', { elevation }, classNames)}
             ref={forwardedRef}
             style={{
               ...contentProps.style,
-              // re-namespace exposed content custom properties
+              // Re-namespace exposed content custom properties.
               ...{
                 '--radix-popover-content-transform-origin': 'var(--radix-popper-transform-origin)',
                 '--radix-popover-content-available-width': 'var(--radix-popper-available-width)',

package/src/components/ScrollArea/ScrollArea.stories.tsx

@@ -2,16 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { type PropsWithChildren } from 'react';
 
 import { faker } from '@dxos/random';
 import { activeSurface, surfaceShadow } from '@dxos/react-ui-theme';
 
-import { ScrollArea } from './ScrollArea';
 import { withTheme } from '../../testing';
 
+import { ScrollArea } from './ScrollArea';
+
 faker.seed(1234);
 
 const DefaultStory = ({ children }: PropsWithChildren<{}>) => {
@@ -33,15 +33,18 @@ const DefaultStory = ({ children }: PropsWithChildren<{}>) => {
   );
 };
 
-export default {
-  title: 'ui/react-ui-core/Scroll area',
-  component: ScrollArea,
+const meta = {
+  title: 'ui/react-ui-core/ScrollArea',
+  component: ScrollArea as any,
   render: DefaultStory,
   decorators: [withTheme],
-  parameters: { chromatic: { disableSnapshot: false } },
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {
+export const Default: Story = {
   args: {
     children: faker.lorem.paragraphs(5),
   },

package/src/components/ScrollArea/ScrollArea.tsx

@@ -3,16 +3,16 @@
 //
 
 import {
+  Corner as ScrollAreaPrimitiveCorner,
+  type ScrollAreaCornerProps as ScrollAreaPrimitiveCornerProps,
   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,
+  Viewport as ScrollAreaPrimitiveViewport,
+  type ScrollAreaViewportProps as ScrollAreaPrimitiveViewportProps,
 } from '@radix-ui/react-scroll-area';
 import React, { forwardRef } from 'react';
 

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

@@ -0,0 +1,70 @@
+//
+// 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 { withLayout, withTheme } from '../../testing';
+import { Button } from '../Button';
+import { Toolbar } from '../Toolbar';
+
+import { ScrollContainer, type ScrollContainerRootProps, type ScrollController } from './ScrollContainer';
+
+const DefaultStory = (props: ScrollContainerRootProps) => {
+  const [lines, setLines] = useState<string[]>([]);
+  const [running, setRunning] = useState(true);
+  const scroller = useRef<ScrollController>(null);
+  useEffect(() => {
+    if (!running) {
+      return;
+    }
+
+    const i = setInterval(() => {
+      setLines((lines) => [...lines, faker.lorem.paragraph()]);
+    }, 500);
+
+    return () => clearInterval(i);
+  }, [running]);
+
+  return (
+    <div className='flex flex-col bs-full overflow-hidden'>
+      <Toolbar.Root>
+        <Button onClick={() => setRunning((running) => !running)}>{running ? 'Stop' : 'Start'}</Button>
+        <Button onClick={() => scroller.current?.scrollToBottom()}>Scroll to bottom</Button>
+        <div className='flex-1' />
+        <div>{lines.length}</div>
+      </Toolbar.Root>
+      <ScrollContainer.Root {...props} ref={scroller}>
+        <ScrollContainer.Viewport>
+          {lines.map((line, index) => (
+            <div key={index} className='p-2'>
+              {line}
+            </div>
+          ))}
+        </ScrollContainer.Viewport>
+        <ScrollContainer.ScrollDownButton />
+      </ScrollContainer.Root>
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-core/ScrollContainer',
+  component: ScrollContainer.Root,
+  render: DefaultStory,
+  decorators: [withTheme, withLayout({ container: 'column', classNames: 'is-[30rem]' })],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    pin: true,
+    fade: true,
+  },
+};

package/src/components/ScrollContainer/ScrollContainer.tsx

@@ -0,0 +1,233 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useState } from '@preact-signals/safe-react/react';
+import { createContext } from '@radix-ui/react-context';
+import React, {
+  type HTMLAttributes,
+  type PropsWithChildren,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from 'react';
+
+// TODO(burdon): Move these deps to @dxos/dom-util.
+import { addEventListener, combine } from '@dxos/async';
+import { invariant } from '@dxos/invariant';
+import { useForwardedRef } from '@dxos/react-hooks';
+import { mx } from '@dxos/react-ui-theme';
+
+import { type ThemedClassName } from '../../util';
+import { IconButton } from '../Button';
+
+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 flicker.
+        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 flex-1 min-bs-0 overflow-hidden'>
+          {fade && (
+            <div
+              role='none'
+              data-visible={overflow}
+              className={mx(
+                // NOTE: Gradients may not be visible with dark reader extensions.
+                'z-10 absolute block-start-0 inset-inline-0 bs-24 is-full',
+                'opacity-0 duration-200 transition-opacity data-[visible="true"]:opacity-100',
+                'bg-gradient-to-b from-[--surface-bg] to-transparent pointer-events-none',
+              )}
+            />
+          )}
+          <div className={mx('flex flex-col min-bs-0 overflow-y-auto scrollbar-thin', classNames)} ref={scrollerRef}>
+            {children}
+          </div>
+        </div>
+      </ScrollContainerProvider>
+    );
+  },
+);
+
+Root.displayName = 'ScrollContainer.Root';
+
+//
+// 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.displayName!);
+
+  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('is-full', classNames)} {...props} ref={contentRef}>
+      {children}
+    </div>
+  );
+});
+
+Viewport.displayName = 'ScrollContainer.Viewport';
+
+//
+// ScrollDownButton
+//
+
+type ScrollDownButtonProps = ThemedClassName;
+
+const ScrollDownButton = ({ classNames }: ScrollDownButtonProps) => {
+  const { pinned, scrollToBottom } = useScrollContainerContext(ScrollDownButton.displayName!);
+
+  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 = 'ScrollContainer.ScrollDownButton';
+
+//
+// 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/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 } },
-};