@dxos/react-ui 0.8.4-main.548089c → 0.8.4-main.59c2e9b

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

@@ -6,9 +6,9 @@ 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 { activeSurface, surfaceShadow } from '@dxos/ui-theme';
 
-import { withTheme } from '../../testing';
+import { withLayout, withTheme } from '../../testing';
 
 import { ScrollArea } from './ScrollArea';
 
@@ -34,10 +34,13 @@ const DefaultStory = ({ children }: PropsWithChildren<{}>) => {
 };
 
 const meta = {
-  title: 'ui/react-ui-core/Scroll area',
+  title: 'ui/react-ui-core/ScrollArea',
   component: ScrollArea as any,
   render: DefaultStory,
-  decorators: [withTheme],
+  decorators: [withTheme, withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
 } satisfies Meta<typeof DefaultStory>;
 
 export default meta;
@@ -49,3 +52,50 @@ export const Default: Story = {
     children: faker.lorem.paragraphs(5),
   },
 };
+
+export const NestedScrollAreas: Story = {
+  render: () => {
+    const columns = Array.from({ length: 3 }).map((_, index) => ({
+      id: String(index),
+      itemCount: 20,
+    }));
+
+    return (
+      <div className='p-4 bs-full is-full overflow-hidden'>
+        <div className='flex bs-full is-full overflow-hidden border border-sky-500'>
+          <ScrollArea.Root>
+            <ScrollArea.Viewport>
+              <div className='flex gap-4 p-3 bs-full overflow-hidden'>
+                {columns.map((column) => (
+                  <div key={column.id} className='flex flex-col gap-1 bs-full overflow-hidden is-[300px]'>
+                    <div className='flex shrink-0 p-2 border border-separator'>Column {column.id}</div>
+                    <ScrollArea.Expander classNames='border border-rose-500'>
+                      <ScrollArea.Root>
+                        <ScrollArea.Viewport>
+                          <div className='flex flex-col p-3 space-y-2'>
+                            {Array.from({ length: column.itemCount }, (_, i) => (
+                              <div key={i} className={`p-3 border border-separator rounded-sm`}>
+                                Item {i + 1}
+                              </div>
+                            ))}
+                          </div>
+                        </ScrollArea.Viewport>
+                        <ScrollArea.Scrollbar orientation='vertical'>
+                          <ScrollArea.Thumb />
+                        </ScrollArea.Scrollbar>
+                      </ScrollArea.Root>
+                    </ScrollArea.Expander>
+                    <div className={`p-2 border border-separator`}>Footer</div>
+                  </div>
+                ))}
+              </div>
+            </ScrollArea.Viewport>
+            <ScrollArea.Scrollbar orientation='horizontal'>
+              <ScrollArea.Thumb />
+            </ScrollArea.Scrollbar>
+          </ScrollArea.Root>
+        </div>
+      </div>
+    );
+  },
+};

package/src/components/ScrollArea/ScrollArea.tsx

@@ -14,18 +14,21 @@ import {
   Viewport as ScrollAreaPrimitiveViewport,
   type ScrollAreaViewportProps as ScrollAreaPrimitiveViewportProps,
 } from '@radix-ui/react-scroll-area';
-import React, { forwardRef } from 'react';
+import React, { type PropsWithChildren, forwardRef } from 'react';
+
+import { mx } from '@dxos/ui-theme';
 
 import { useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
 
 type ScrollAreaVariant = 'coarse' | 'fine';
 
+//
+// Root
+//
+
 type ScrollAreaRootProps = ThemedClassName<ScrollAreaPrimitiveRootProps>;
 
-/**
- * @deprecated
- */
 const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(({ classNames, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
   return (
@@ -37,6 +40,10 @@ const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(({ classN
   );
 });
 
+//
+// Viewport
+//
+
 type ScrollAreaViewportProps = ThemedClassName<ScrollAreaPrimitiveViewportProps>;
 
 const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
@@ -52,6 +59,10 @@ const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
   },
 );
 
+//
+// Scrollbar
+//
+
 type ScrollAreaScrollbarProps = ThemedClassName<ScrollAreaPrimitiveScrollbarProps> & { variant?: ScrollAreaVariant };
 
 const ScrollAreaScrollbar = forwardRef<HTMLDivElement, ScrollAreaScrollbarProps>(
@@ -68,6 +79,10 @@ const ScrollAreaScrollbar = forwardRef<HTMLDivElement, ScrollAreaScrollbarProps>
   },
 );
 
+//
+// Thumb
+//
+
 type ScrollAreaThumbProps = ThemedClassName<ScrollAreaPrimitiveThumbProps>;
 
 const ScrollAreaThumb = forwardRef<HTMLDivElement, ScrollAreaThumbProps>(({ classNames, ...props }, forwardedRef) => {
@@ -81,6 +96,10 @@ const ScrollAreaThumb = forwardRef<HTMLDivElement, ScrollAreaThumbProps>(({ clas
   );
 });
 
+//
+// Corner
+//
+
 type ScrollAreaCornerProps = ThemedClassName<ScrollAreaPrimitiveCornerProps>;
 
 const ScrollAreaCorner = forwardRef<HTMLDivElement, ScrollAreaCornerProps>(({ classNames, ...props }, forwardedRef) => {
@@ -94,12 +113,38 @@ const ScrollAreaCorner = forwardRef<HTMLDivElement, ScrollAreaCornerProps>(({ cl
   );
 });
 
+//
+// Expander
+//
+
+type ScrollAreaExpanderProps = ThemedClassName<PropsWithChildren>;
+
+/**
+ * Size-locking wrapper required for inner ScrollArea to function correctly.
+ * NOTE: Radix ScrollArea.Viewport applies `display: table` to its immediate child,
+ * causing the content to participate in table layout and escape the intended fixed-size viewport.
+ */
+const ScrollAreaExpander = ({ classNames, children }: ScrollAreaExpanderProps) => {
+  return (
+    <div role='none' className={mx('relative bs-full is-full overflow-hidden', classNames)}>
+      <div role='none' className='absolute inset-0 overflow-hidden'>
+        {children}
+      </div>
+    </div>
+  );
+};
+
+//
+// ScrollArea
+//
+
 export const ScrollArea = {
   Root: ScrollAreaRoot,
   Viewport: ScrollAreaViewport,
   Scrollbar: ScrollAreaScrollbar,
   Thumb: ScrollAreaThumb,
   Corner: ScrollAreaCorner,
+  Expander: ScrollAreaExpander,
 };
 
 export type {
@@ -108,4 +153,5 @@ export type {
   ScrollAreaScrollbarProps,
   ScrollAreaThumbProps,
   ScrollAreaCornerProps,
+  ScrollAreaExpanderProps,
 };

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({ layout: '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 { createContext } from '@radix-ui/react-context';
+import React, {
+  type HTMLAttributes,
+  type PropsWithChildren,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} 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/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

@@ -8,7 +8,7 @@ import React, { useState } from 'react';
 import { faker } from '@dxos/random';
 
 import { withTheme } from '../../testing';
-import { withSurfaceVariantsLayout } from '../../testing';
+import { withLayoutVariants } from '../../testing';
 
 import { Select } from './Select';
 
@@ -44,7 +44,7 @@ const DefaultStory = ({ items = [] }: StoryProps) => {
 const meta = {
   title: 'ui/react-ui-core/Select',
   render: DefaultStory,
-  decorators: [withTheme, withSurfaceVariantsLayout()],
+  decorators: [withTheme, withLayoutVariants()],
 } satisfies Meta<typeof DefaultStory>;
 
 export default meta;

package/src/components/Select/Select.tsx

@@ -8,7 +8,7 @@ import React, { forwardRef } from 'react';
 import { useElevationContext, useThemeContext } from '../../hooks';
 import { useSafeCollisionPadding } from '../../hooks/useSafeCollisionPadding';
 import { type ThemedClassName } from '../../util';
-import { Button, type ButtonProps } from '../Buttons';
+import { Button, type ButtonProps } from '../Button';
 import { Icon } from '../Icon';
 
 type SelectRootProps = SelectPrimitive.SelectProps;
@@ -39,7 +39,7 @@ const SelectTriggerButton = forwardRef<HTMLButtonElement, SelectTriggerButtonPro
       <SelectPrimitive.Trigger asChild ref={forwardedRef}>
         <Button {...props}>
           <SelectPrimitive.Value placeholder={placeholder}>{children}</SelectPrimitive.Value>
-          <span className='w-1 flex-1' />
+          <span className='is-1 flex-1' />
           <SelectPrimitive.Icon asChild>
             <Icon size={3} icon='ph--caret-down--bold' />
           </SelectPrimitive.Icon>
@@ -158,7 +158,7 @@ const SelectOption = forwardRef<HTMLDivElement, SelectItemProps>(({ children, cl
   return (
     <SelectPrimitive.Item {...props} className={tx('select.item', 'option', {}, classNames)} ref={forwardedRef}>
       <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
-      <span className='grow w-1' />
+      <span className='grow is-1' />
       {/* <SelectPrimitive.ItemIndicator className={tx('select.itemIndicator', 'option__indicator', {})}> */}
       <Icon icon='ph--check--regular' />
       {/* </SelectPrimitive.ItemIndicator> */}

package/src/components/Tag/Tag.stories.tsx

@@ -5,8 +5,8 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { hues } from '@dxos/react-ui-theme';
-import { type ChromaticPalette, type MessageValence } from '@dxos/react-ui-types';
+import { hues } from '@dxos/ui-theme';
+import { type ChromaticPalette, type MessageValence } from '@dxos/ui-types';
 
 import { withTheme } from '../../testing';
 

package/src/components/Tag/Tag.tsx

@@ -6,7 +6,7 @@ import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
 import React, { type ComponentPropsWithRef, forwardRef } from 'react';
 
-import { type ChromaticPalette, type MessageValence, type NeutralPalette } from '@dxos/react-ui-types';
+import { type ChromaticPalette, type MessageValence, type NeutralPalette } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';

package/src/components/ThemeProvider/ThemeProvider.tsx

@@ -5,7 +5,7 @@
 import { createKeyborg } from 'keyborg';
 import React, { type PropsWithChildren, createContext, useEffect, useMemo } from 'react';
 
-import { type Density, type Elevation, type ThemeFunction } from '@dxos/react-ui-types';
+import { type Density, type Elevation, type ThemeFunction, type ThemeMode } from '@dxos/ui-types';
 
 import { type SafeAreaPadding, useSafeArea } from '../../hooks';
 import { hasIosKeyboard } from '../../util';
@@ -14,8 +14,6 @@ import { ElevationProvider } from '../ElevationProvider';
 
 import { TranslationsProvider, type TranslationsProviderProps } from './TranslationsProvider';
 
-export type ThemeMode = 'dark' | 'light';
-
 export type ThemeContextValue = {
   tx: ThemeFunction<any>;
   themeMode: ThemeMode;

package/src/components/ThemeProvider/TranslationsProvider.tsx

@@ -3,7 +3,7 @@
 //
 
 import { type Locale, enUS as dtLocaleEnUs } from 'date-fns/locale';
-import i18Next, { type Resource, type TFunction } from 'i18next';
+import i18Next, { type Resource } from 'i18next';
 import React, { type ReactNode, Suspense, createContext, useContext, useEffect, useState } from 'react';
 import { initReactI18next, useTranslation as useI18NextTranslation } from 'react-i18next';
 
@@ -11,21 +11,6 @@ const initialLng = 'en-US';
 const initialNs = 'dxos-common';
 const initialDtLocale = dtLocaleEnUs;
 
-// TODO(thure): `Parameters<TFunction>` causes typechecking issues because `TFunction` has so many signatures.
-export type Label = string | [string, { ns: string; count?: number; defaultValue?: string }];
-
-export const isLabel = (o: any): o is Label =>
-  typeof o === 'string' ||
-  (Array.isArray(o) &&
-    o.length === 2 &&
-    typeof o[0] === 'string' &&
-    !!o[1] &&
-    typeof o[1] === 'object' &&
-    'ns' in o[1] &&
-    typeof o[1].ns === 'string');
-
-export const toLocalizedString = (label: Label, t: TFunction) => (Array.isArray(label) ? t(...label) : label);
-
 export const resources = {
   [initialLng]: {
     [initialNs]: {

package/src/components/ThemeProvider/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-export * from './ThemeProvider';
-export { type Label, isLabel, toLocalizedString, useTranslation } from './TranslationsProvider';
+export { type Label, isLabel, toLocalizedString } from '@dxos/ui-types';
 
-// TODO(burdon): Use `@internal` with barrel exports (rather than picking individual exports?)
+export * from './ThemeProvider';
+export { useTranslation } from './TranslationsProvider';

package/src/components/Toast/Toast.stories.tsx

@@ -6,7 +6,7 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { type ReactNode, useState } from 'react';
 
 import { withTheme } from '../../testing';
-import { Button } from '../Buttons';
+import { Button } from '../Button';
 
 import { Toast } from './Toast';
 

package/src/components/Toolbar/Toolbar.stories.tsx

@@ -6,7 +6,7 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { withTheme } from '../../testing';
-import { Toggle } from '../Buttons';
+import { Toggle } from '../Button';
 import { Icon } from '../Icon';
 import { Select } from '../Select';