@dxos/react-ui 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

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

@@ -2,16 +2,18 @@
 // Copyright 2026 DXOS.org
 //
 
-import React, { useMemo } from 'react';
+import React, { PropsWithChildren, useMemo } from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { mx } from '@dxos/ui-theme';
+import { ThemedClassName } from '@dxos/ui-types';
 
 import { withLayout, withTheme } from '../../testing';
-
+import { Column } from '../Column';
+import { Input } from '../Input';
 import { ScrollArea } from './ScrollArea';
 
-faker.seed(123);
+random.seed(123);
 
 export default {
   title: 'ui/react-ui-core/components/ScrollArea',
@@ -22,22 +24,22 @@ export default {
   },
 };
 
-const Column = () => (
+const List = ({ items = 50 }: { items?: number }) => (
   <div>
-    {Array.from({ length: 50 }).map((_, index) => (
-      <div key={index} className='text-sm'>
+    {Array.from({ length: items }).map((_, index) => (
+      <div key={index} className='px-1 cursor-pointer hover:bg-hover-surface'>
         Item {index + 1}
       </div>
     ))}
   </div>
 );
 
-const Row = () => (
-  <div className='flex gap-2 is-max'>
-    {Array.from({ length: 50 }).map((_, index) => (
+const Row = ({ items = 50 }: { items?: number }) => (
+  <div className='flex gap-2 w-max'>
+    {Array.from({ length: items }).map((_, index) => (
       <div
         key={index}
-        className='shrink-0 bs-20 is-20 border border-separator rounded-md flex items-center justify-center text-sm'
+        className='shrink-0 h-20 w-20 cursor-pointer border border-separator rounded-md flex items-center justify-center hover:bg-hover-surface'
       >
         {index + 1}
       </div>
@@ -45,58 +47,91 @@ const Row = () => (
   </div>
 );
 
+const Container = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => {
+  return <div className={mx('border border-separator rounded-md overflow-hidden', classNames)}>{children}</div>;
+};
+
 export const Vertical = {
   render: () => (
-    <div className='bs-72 is-48 p-2 border border-separator rounded-md'>
+    <Container classNames='h-72 w-48'>
       <ScrollArea.Root orientation='vertical'>
         <ScrollArea.Viewport>
-          <Column />
+          <List />
         </ScrollArea.Viewport>
       </ScrollArea.Root>
-    </div>
+    </Container>
   ),
 };
 
 export const VerticalThin = {
   render: () => (
-    <div className='bs-72 is-48 p-2 border border-separator rounded-md'>
+    <Container classNames='h-72 w-48'>
       <ScrollArea.Root orientation='vertical' thin>
         <ScrollArea.Viewport>
-          <Column />
+          <List />
         </ScrollArea.Viewport>
       </ScrollArea.Root>
-    </div>
+    </Container>
+  ),
+};
+
+export const VerticalPadded = {
+  render: () => (
+    <Container classNames='h-72 w-48'>
+      <ScrollArea.Root orientation='vertical' centered padding thin>
+        <ScrollArea.Viewport>
+          <List />
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    </Container>
+  ),
+};
+
+export const VerticalColumn = {
+  render: () => (
+    <Container classNames='h-72 w-48'>
+      <Column.Root gutter='sm' classNames='h-full overflow-hidden'>
+        <ScrollArea.Root orientation='vertical' padding thin>
+          <ScrollArea.Viewport classNames='py-2'>
+            <Input.Root>
+              <Input.TextInput classNames='p-1' />
+            </Input.Root>
+            <List />
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Column.Root>
+    </Container>
   ),
 };
 
 export const Horizontal = {
   render: () => (
-    <div className='is-96 p-2 border border-separator rounded-md'>
+    <Container classNames='w-96'>
       <ScrollArea.Root orientation='horizontal'>
         <ScrollArea.Viewport>
           <Row />
         </ScrollArea.Viewport>
       </ScrollArea.Root>
-    </div>
+    </Container>
   ),
 };
 
 export const HorizontalThin = {
   render: () => (
-    <div className='is-96 p-2 border border-separator rounded-md'>
+    <Container classNames='w-96'>
       <ScrollArea.Root orientation='horizontal' thin>
         <ScrollArea.Viewport>
           <Row />
         </ScrollArea.Viewport>
       </ScrollArea.Root>
-    </div>
+    </Container>
   ),
 };
 
 export const Both = {
   render: () => (
-    <div className='bs-72 is-96 p-2 border border-separator rounded-md'>
-      <ScrollArea.Root thin orientation='all'>
+    <Container classNames='w-96 h-96'>
+      <ScrollArea.Root orientation='all'>
         <ScrollArea.Viewport>
           <div className='flex flex-col gap-2'>
             {Array.from({ length: 50 }).map((_, rowIndex) => (
@@ -104,7 +139,7 @@ export const Both = {
                 {Array.from({ length: 50 }).map((_, colIndex) => (
                   <div
                     key={colIndex}
-                    className='shrink-0 bs-20 is-20 flex items-center justify-center text-sm border border-separator font-mono'
+                    className='shrink-0 h-20 w-20 flex items-center justify-center text-sm border border-separator font-mono'
                   >
                     [{colIndex}:{rowIndex}]
                   </div>
@@ -114,7 +149,31 @@ export const Both = {
           </div>
         </ScrollArea.Viewport>
       </ScrollArea.Root>
-    </div>
+    </Container>
+  ),
+};
+
+export const Fullscreen = {
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  render: () => (
+    <ScrollArea.Root orientation='all' thin>
+      <ScrollArea.Viewport>
+        <div className='flex flex-col gap-2'>
+          {Array.from({ length: 50 }).map((_, rowIndex) => (
+            <div key={rowIndex} className='flex gap-2'>
+              {Array.from({ length: 50 }).map((_, colIndex) => (
+                <div
+                  key={colIndex}
+                  className='shrink-0 h-20 w-20 flex items-center justify-center text-sm border border-separator font-mono'
+                >
+                  [{colIndex}:{rowIndex}]
+                </div>
+              ))}
+            </div>
+          ))}
+        </div>
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
   ),
 };
 
@@ -125,30 +184,30 @@ export const NestedScrollAreas = {
       () =>
         Array.from({ length: 8 }).map((_, index) => ({
           id: String(index),
-          count: faker.number.int({ min: 5, max: 20 }),
+          count: random.number.int({ min: 5, max: 20 }),
         })),
       [],
     );
 
     return (
-      <ScrollArea.Root thin orientation='horizontal'>
+      <ScrollArea.Root orientation='horizontal' thin padding>
         <ScrollArea.Viewport classNames='gap-4'>
           {columns.map((column) => (
             <section
               key={column.id}
-              className='shrink-0 bs-full is-[16rem] grid grid-rows-[min-content_1fr_min-content] border border-separator'
+              className='shrink-0 h-full w-[16rem] grid grid-rows-[min-content_1fr_min-content] border border-separator'
             >
-              <header className='flex shrink-0 p-2 border-be border-separator'>Column {column.id}</header>
+              <header className='flex shrink-0 p-2 border-b border-separator'>Column {column.id}</header>
               <ScrollArea.Root thin orientation='vertical'>
-                <ScrollArea.Viewport classNames='plb-2 pli-2 gap-2'>
+                <ScrollArea.Viewport classNames='py-2 px-2 gap-2'>
                   {Array.from({ length: column.count }, (_, i) => (
-                    <div key={i} role='listitem' className={`shrink-0 p-2 text-sm border border-separator rounded-sm`}>
+                    <div key={i} role='listitem' className={`shrink-0 p-2 text-sm border border-separator rounded-xs`}>
                       Item {i + 1}
                     </div>
                   ))}
                 </ScrollArea.Viewport>
               </ScrollArea.Root>
-              <footer className={`p-2 text-subdued border-bs border-separator`}>{column.count}</footer>
+              <footer className={`p-2 text-subdued border-t border-separator`}>{column.count}</footer>
             </section>
           ))}
         </ScrollArea.Viewport>
@@ -159,18 +218,18 @@ export const NestedScrollAreas = {
 
 export const NativeScroll = {
   render: () => (
-    <div className='group bs-48 is-48 border border-separator'>
+    <div className='group h-48 w-48 border border-separator'>
       <div
         className={mx(
-          'group bs-full is-full overflow-y-scroll',
-          '[&::-webkit-scrollbar]:is-3',
+          'group h-full w-full overflow-y-scroll',
+          '[&::-webkit-scrollbar]:w-3',
           '[&::-webkit-scrollbar-thumb]:rounded-none',
-          '[&::-webkit-scrollbar-track]:bg-scrollbarTrack',
-          '[&::-webkit-scrollbar-thumb]:bg-scrollbarThumbSubdued',
-          'group-hover:[&::-webkit-scrollbar-thumb]:bg-scrollbarThumb',
+          '[&::-webkit-scrollbar-track]:bg-scrollbar-track',
+          '[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumbSubdued',
+          'group-hover:[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
         )}
       >
-        <Column />
+        <List />
       </div>
     </div>
   ),

package/src/components/ScrollArea/ScrollArea.theme.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { mx } from '@dxos/ui-theme';
+import { type AllowedAxis, type ComponentFunction, type Theme } from '@dxos/ui-types';
+
+import { withColumn } from '../Column/withColumn';
+
+export type ScrollAreaStyleProps = {
+  orientation?: AllowedAxis;
+  autoHide?: boolean;
+  /** Balance left/right, top/bottom offset with scrollbar. */
+  centered?: boolean;
+  /** Add default padding. */
+  /** TODO(burdon): Integrate with Column.Root padding. */
+  padding?: boolean;
+  /** Use thin scrollbars. */
+  /** TODO(burdon): Density fine/course. */
+  thin?: boolean;
+  /** Enable snap scrolling. */
+  snap?: boolean;
+};
+
+const root: ComponentFunction<ScrollAreaStyleProps> = ({ orientation }, ...etc) =>
+  mx(
+    // Expand
+    'dx-container',
+
+    orientation === 'vertical' && 'group/scroll-v flex flex-col',
+    orientation === 'horizontal' && 'group/scroll-h flex',
+    orientation === 'all' && 'group/scroll-all',
+
+    // Apply col-span-full only when inside a Column.Root grid (detected via dx-column-root marker).
+    '[.dx-column-root_&]:col-span-full',
+
+    ...etc,
+  );
+
+/**
+ * NOTE: The browser reserves space for scrollbars.
+ */
+const viewport: ComponentFunction<ScrollAreaStyleProps> = (
+  { orientation, centered, padding, snap, autoHide },
+  ...etc
+) => {
+  return mx(
+    'flex-1 min-h-0 w-full',
+
+    // Reset --dx-col so nested components don't try to grid-position themselves.
+    // ScrollArea has already consumed --gutter for padding.
+    withColumn.consumed(),
+
+    orientation === 'vertical' && 'overflow-y-scroll',
+    orientation === 'horizontal' && 'flex overflow-x-scroll overscroll-x-contain',
+    orientation === 'all' && 'overflow-scroll',
+
+    '[&::-webkit-scrollbar-corner]:bg-transparent',
+    '[&::-webkit-scrollbar-track]:bg-transparent',
+    '[&::-webkit-scrollbar-thumb]:rounded-none',
+
+    '[&::-webkit-scrollbar]:w-[var(--scroll-width)] [&::-webkit-scrollbar]:h-[var(--scroll-width)]',
+
+    // If contained within Column.Root grid the gutter is set by that component (--gutter CSS variable).
+    // If centered, left padding compensates for scrollbar width so content is visually centered.
+    (orientation === 'vertical' || orientation === 'all') &&
+      (padding
+        ? [
+            centered ? 'pl-[var(--gutter,calc(var(--scroll-width)+var(--scroll-padding)))]' : 'pl-[var(--gutter,0)]',
+            'pr-[calc(var(--gutter,calc(var(--scroll-width)+var(--scroll-padding)))-var(--scroll-width))]',
+          ]
+        : centered && 'pl-[var(--scroll-width)]'),
+
+    (orientation === 'horizontal' || orientation === 'all') &&
+      (padding
+        ? [centered && 'pt-[calc(var(--scroll-width)+var(--scroll-padding))]', 'pb-[var(--scroll-padding)]']
+        : centered && 'pt-[var(--scroll-width)]'),
+
+    snap && [
+      orientation === 'vertical' && 'snap-y snap-mandatory',
+      orientation === 'horizontal' && 'snap-x snap-mandatory',
+      orientation === 'all' && 'snap-both snap-mandatory',
+    ],
+
+    autoHide
+      ? [
+          orientation === 'vertical' && 'group-hover/scroll-v:[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
+          orientation === 'horizontal' && 'group-hover/scroll-h:[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
+          orientation === 'all' && 'group-hover/scroll-all:[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
+        ]
+      : [
+          orientation === 'vertical' && '[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
+          orientation === 'horizontal' && '[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
+          orientation === 'all' && '[&::-webkit-scrollbar-thumb]:bg-scrollbar-thumb',
+        ],
+
+    ...etc,
+  );
+};
+
+export const scrollAreaTheme: Theme<ScrollAreaStyleProps> = {
+  root,
+  viewport,
+};

package/src/components/ScrollArea/ScrollArea.tsx

@@ -3,11 +3,15 @@
 //
 
 import { createContext } from '@radix-ui/react-context';
-import React, { type HTMLAttributes, forwardRef } from 'react';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { CSSProperties, useMemo } from 'react';
 
-import { type AllowedAxis, type SlottableProps, type ThemedClassName } from '@dxos/ui-types';
+import { type AllowedAxis, type SlottableProps } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
+import { composableProps, slottable } from '../../util';
+import { scrollbar } from './scrollbar';
 
 //
 // Context
@@ -21,7 +25,7 @@ type ScrollAreaContextType = {
   /** Hide scrollbars when not scrolling. */
   autoHide: boolean;
   /** Apply padding to opposite side of scrollbar. */
-  margin?: boolean;
+  centered?: boolean;
   /** Apply padding. */
   padding: boolean;
   /** Use thin scrollbars. */
@@ -38,20 +42,19 @@ const [ScrollAreaProvider, useScrollAreaContext] = createContext<ScrollAreaConte
 
 const SCROLLAREA_ROOT_NAME = 'ScrollArea.Root';
 
-type ScrollAreaRootProps = SlottableProps<HTMLDivElement> & Partial<ScrollAreaContextType>;
+type ScrollAreaRootProps = Partial<ScrollAreaContextType>;
 
 /**
  * ScrollArea provides native scrollbars with custom styling.
  */
-const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(
+const ScrollAreaRoot = slottable<HTMLDivElement, ScrollAreaRootProps>(
   (
     {
-      className,
-      classNames,
       children,
+      asChild,
       orientation = 'vertical',
       autoHide = true,
-      margin = false,
+      centered = false,
       padding = false,
       thin = false,
       snap = false,
@@ -60,17 +63,18 @@ const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(
     forwardedRef,
   ) => {
     const { tx } = useThemeContext();
-    const options = { orientation, autoHide, margin, padding, thin, snap };
+    const { className, ...rest } = composableProps(props);
+    const Comp = asChild ? Slot : Primitive.div;
+    const options = useMemo(
+      () => ({ orientation, autoHide, centered, padding, thin, snap }),
+      [orientation, autoHide, centered, padding, thin, snap],
+    );
 
     return (
       <ScrollAreaProvider {...options}>
-        <div
-          {...props}
-          className={tx('scrollArea.root', 'scroll-area', options, [className, classNames])}
-          ref={forwardedRef}
-        >
+        <Comp {...rest} className={tx('scrollArea.root', options, className)} ref={forwardedRef}>
           {children}
-        </div>
+        </Comp>
       </ScrollAreaProvider>
     );
   },
@@ -84,24 +88,33 @@ ScrollAreaRoot.displayName = SCROLLAREA_ROOT_NAME;
 
 const SCROLLAREA_VIEWPORT_NAME = 'ScrollArea.Viewport';
 
-type ScrollAreaViewportProps = ThemedClassName<HTMLAttributes<HTMLDivElement>>;
-
-const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
-  ({ classNames, children, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
-    const options = useScrollAreaContext(SCROLLAREA_VIEWPORT_NAME);
-
-    return (
-      <div
-        {...props}
-        className={tx('scrollArea.viewport', 'scroll-area__viewport', options, classNames)}
-        ref={forwardedRef}
-      >
-        {children}
-      </div>
-    );
-  },
-);
+type ScrollAreaViewportProps = SlottableProps;
+
+const ScrollAreaViewport = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { tx } = useThemeContext();
+  const options = useScrollAreaContext(SCROLLAREA_VIEWPORT_NAME);
+  const density = options.thin ? scrollbar.md : scrollbar.lg;
+  const { className, ...rest } = composableProps(props);
+  const { style, ...restWithoutStyle } = rest as { style?: CSSProperties; [key: string]: any };
+  const Comp = asChild ? Slot : Primitive.div;
+
+  return (
+    <Comp
+      {...restWithoutStyle}
+      style={
+        {
+          '--scroll-width': `${density.size}px`,
+          '--scroll-padding': `${density.padding}px`,
+          ...style,
+        } as CSSProperties
+      }
+      className={tx('scrollArea.viewport', options, className)}
+      ref={forwardedRef}
+    >
+      {children}
+    </Comp>
+  );
+});
 
 ScrollAreaViewport.displayName = SCROLLAREA_VIEWPORT_NAME;
 

package/src/components/ScrollArea/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './ScrollArea';
+export * from './scrollbar';

package/src/components/ScrollArea/scrollbar.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Scrollbar sizing presets keyed by density tier.
+ */
+export const scrollbar = {
+  sm: {
+    size: 2,
+    padding: 2,
+  },
+  md: {
+    size: 4,
+    padding: 4,
+  },
+  lg: {
+    size: 8,
+    padding: 8,
+  },
+};

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

@@ -5,49 +5,61 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useEffect, useRef, useState } from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 
 import { withLayout, withTheme } from '../../testing';
 import { Button } from '../Button';
+import { Panel } from '../Panel';
 import { Toolbar } from '../Toolbar';
-
 import { ScrollContainer, type ScrollContainerRootProps, type ScrollController } from './ScrollContainer';
 
-const DefaultStory = (props: ScrollContainerRootProps) => {
+type DefaultStoryProps = ScrollContainerRootProps & { running?: boolean; initialLines?: number };
+
+const DefaultStory = ({ initialLines = 0, running: runningProp, ...props }: DefaultStoryProps) => {
   const [lines, setLines] = useState<string[]>([]);
-  const [running, setRunning] = useState(true);
+  const [running, setRunning] = useState(runningProp);
   const scroller = useRef<ScrollController>(null);
+  useEffect(() => {
+    setLines(Array.from({ length: initialLines }, () => random.lorem.paragraph()));
+  }, [initialLines]);
   useEffect(() => {
     if (!running) {
       return;
     }
 
     const i = setInterval(() => {
-      setLines((lines) => [...lines, faker.lorem.paragraph()]);
+      setLines((lines) => [...lines, random.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>
+    <Panel.Root className='dx-document'>
+      <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>
+        <ScrollContainer.Root {...props} ref={scroller}>
+          <ScrollContainer.Content>
+            <ScrollContainer.Viewport>
+              {lines.map((line, index) => (
+                <div key={index} className='p-2 text-description'>
+                  {line}
+                </div>
+              ))}
+            </ScrollContainer.Viewport>
+            <ScrollContainer.ScrollDownButton />
+            <ScrollContainer.Fade />
+          </ScrollContainer.Content>
+        </ScrollContainer.Root>
+      </Panel.Content>
+    </Panel.Root>
   );
 };
 
@@ -55,7 +67,7 @@ const meta = {
   title: 'ui/react-ui-core/components/ScrollContainer',
   component: ScrollContainer.Root,
   render: DefaultStory,
-  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'is-[30rem]' })],
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-[30rem]' })],
 } satisfies Meta<typeof DefaultStory>;
 
 export default meta;
@@ -65,6 +77,15 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     pin: true,
-    fade: true,
+
+    running: true,
+  },
+};
+
+export const Large: Story = {
+  args: {
+    pin: true,
+
+    initialLines: 100,
   },
 };