@dxos/react-ui 0.8.4-main.5ad4a44 → 0.8.4-main.66e292d

package/src/components/ScrollContainer/ScrollContainer.tsx

@@ -0,0 +1,231 @@
+//
+// 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;
+  }>
+>;
+
+/**
+ * Scroll container that automatically scrolls to the bottom when new content is added.
+ */
+const Root = forwardRef<ScrollController, RootProps>(({ children, classNames, pin, fade }, 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 = 'instant') => {
+    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;
+    }
+
+    // Setup resize observer to detect content changes.
+    const resizeObserver = new ResizeObserver(() => scrollToBottom());
+    scrollToBottom('instant');
+
+    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>
@@ -108,7 +108,7 @@ const SelectScrollDownButton = forwardRef<HTMLDivElement, SelectScrollDownButton
 type SelectViewportProps = ThemedClassName<SelectPrimitive.SelectViewportProps>;
 
 const SelectViewport = forwardRef<HTMLDivElement, SelectViewportProps>(
-  ({ classNames, asChild, children, ...props }, forwardedRef) => {
+  ({ classNames, children, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
     return (
       <SelectPrimitive.SelectViewport
@@ -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/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';
 
@@ -63,9 +63,7 @@ const DefaultStory = (props: StorybookToolbarProps) => {
       </Toolbar.Button>
       <Toolbar.Separator />
       <Toolbar.Button>Test</Toolbar.Button>
-      <Toolbar.Button>
-        <Icon icon='ph--arrow-clockwise--regular' />
-      </Toolbar.Button>
+      <Toolbar.IconButton icon='ph--arrow-clockwise--regular' label='Refresh' iconOnly />
     </Toolbar.Root>
   );
 };

package/src/components/Toolbar/Toolbar.tsx

@@ -4,7 +4,7 @@
 
 import type { ToggleGroupItemProps as ToggleGroupItemPrimitiveProps } from '@radix-ui/react-toggle-group';
 import * as ToolbarPrimitive from '@radix-ui/react-toolbar';
-import React, { forwardRef } from 'react';
+import React, { Fragment, forwardRef } from 'react';
 
 import { useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
@@ -18,23 +18,34 @@ import {
   Toggle,
   type ToggleGroupItemProps,
   type ToggleProps,
-} from '../Buttons';
+} from '../Button';
 import { Link, type LinkProps } from '../Link';
 import { Separator, type SeparatorProps } from '../Separator';
 
-type ToolbarRootProps = ThemedClassName<ToolbarPrimitive.ToolbarProps> & { layoutManaged?: boolean };
+type ToolbarRootProps = ThemedClassName<
+  ToolbarPrimitive.ToolbarProps & {
+    textBlockWidth?: boolean;
+    layoutManaged?: boolean;
+    disabled?: boolean;
+  }
+>;
 
 const ToolbarRoot = forwardRef<HTMLDivElement, ToolbarRootProps>(
-  ({ classNames, children, layoutManaged, ...props }, forwardedRef) => {
+  ({ classNames, children, layoutManaged, textBlockWidth: textBlockWidthParam, disabled, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
+    const InnerRoot = textBlockWidthParam ? 'div' : Fragment;
+    const innerRootProps = textBlockWidthParam
+      ? { role: 'none', className: tx('toolbar.inner', 'toolbar', { layoutManaged }, classNames) }
+      : {};
+
     return (
       <ToolbarPrimitive.Root
         {...props}
         data-arrow-keys={props.orientation === 'vertical' ? 'up down' : 'left right'}
-        className={tx('toolbar.root', 'toolbar', { layoutManaged }, classNames)}
+        className={tx('toolbar.root', 'toolbar', { layoutManaged, disabled }, classNames)}
         ref={forwardedRef}
       >
-        {children}
+        <InnerRoot {...innerRootProps}>{children}</InnerRoot>
       </ToolbarPrimitive.Root>
     );
   },

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -8,7 +8,7 @@ import React from 'react';
 import { faker } from '@dxos/random';
 
 import { withTheme } from '../../testing';
-import { Button } from '../Buttons';
+import { Button } from '../Button';
 
 import { Tooltip } from './Tooltip';
 

package/src/components/index.ts

@@ -5,19 +5,20 @@
 export * from './AnchoredOverflow';
 export * from './Avatars';
 export * from './Breadcrumb';
-export * from './Buttons';
+export * from './Button';
 export * from './Clipboard';
-export * from './Dialogs';
+export * from './Dialog';
 export * from './Icon';
 export * from './Input';
 export * from './Link';
-export * from './Lists';
+export * from './List';
 export * from './Main';
 export * from './Menus';
 export * from './Message';
 export * from './Popover';
 export * from './Status';
 export * from './ScrollArea';
+export * from './ScrollContainer';
 export * from './Select';
 export * from './Separator';
 export * from './Tag';

package/src/hooks/useSafeArea.ts

@@ -4,7 +4,7 @@
 
 import { useCallback, useState } from 'react';
 
-import { useResize } from '@dxos/react-hooks';
+import { useViewportResize } from '@dxos/react-hooks';
 
 export type SafeAreaPadding = Record<'top' | 'right' | 'bottom' | 'left', number>;
 
@@ -21,6 +21,6 @@ export const useSafeArea = (): SafeAreaPadding => {
     });
   }, []);
 
-  useResize(handleResize);
+  useViewportResize(handleResize);
   return padding;
 };

package/src/hooks/useVisualViewport.ts

@@ -4,9 +4,9 @@
 
 import { useCallback, useState } from 'react';
 
-import { useResize } from '@dxos/react-hooks';
+import { useViewportResize } from '@dxos/react-hooks';
 
-export const useVisualViewport = (deps?: Parameters<typeof useResize>[1]) => {
+export const useVisualViewport = (deps?: Parameters<typeof useViewportResize>[1]) => {
   const [width, setWidth] = useState<number | null>(null);
   const [height, setHeight] = useState<number | null>(null);
 
@@ -17,7 +17,7 @@ export const useVisualViewport = (deps?: Parameters<typeof useResize>[1]) => {
     }
   }, []);
 
-  useResize(handleResize, deps);
+  useViewportResize(handleResize, deps);
 
   return { width, height };
 };

package/src/playground/Controls.stories.tsx

@@ -7,7 +7,7 @@ import React, { useState } from 'react';
 
 import { Icon, Input, Select, Toggle, Toolbar } from '../components';
 import { withTheme } from '../testing';
-import { withSurfaceVariantsLayout } from '../testing';
+import { withLayoutVariants } from '../testing';
 
 const DefaultStory = () => {
   const [checked, setChecked] = useState<boolean>(false);
@@ -84,7 +84,7 @@ const DefaultStory = () => {
 const meta = {
   title: 'ui/react-ui-core/Playground/Controls',
   render: DefaultStory,
-  decorators: [withTheme, withSurfaceVariantsLayout()],
+  decorators: [withTheme, withLayoutVariants()],
 } satisfies Meta<typeof Icon>;
 
 export default meta;

package/src/playground/Custom.stories.tsx

@@ -30,7 +30,7 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
               iconOnly
               size={7}
               density='coarse'
-              classNames='px-1.5'
+              classNames='pli-1.5'
             />
           </div>
         </div>
@@ -43,7 +43,7 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             </Button>
           </div>
           <div className='flex justify-center'>
-            <IconButton {...args} label='Test' icon='ph--atom--regular' size={5} density='fine' classNames='px-2' />
+            <IconButton {...args} label='Test' icon='ph--atom--regular' density='fine' classNames='pli-2' />
           </div>
           <div className='flex justify-center'>
             <IconButton
@@ -51,9 +51,8 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
               label='Test'
               icon='ph--atom--regular'
               iconOnly
-              size={5}
               density='fine'
-              classNames='py-1 px-1.5'
+              classNames='plb-1 pli-1.5'
             />
           </div>
         </div>
@@ -61,7 +60,7 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
         {/* Small */}
         <div className='grid grid-cols-3 gap-4'>
           <div className='flex justify-center'>
-            <Button {...args} density='fine' classNames={'!h-[24px] !text-[14px] p-0 px-1.5 min-bs-0'}>
+            <Button {...args} density='fine' classNames={'!h-[24px] !text-[14px] p-0 pli-1.5 min-bs-0'}>
               {children}
             </Button>
           </div>
@@ -90,18 +89,17 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
 
         {/* TODO(burdon): Full variant with max width. */}
         <div className='flex justify-center'>
-          <Button classNames='w-full max-w-[15rem] rounded' variant='default'>
+          <Button classNames='is-full max-is-[15rem] rounded' variant='default'>
             Test
           </Button>
         </div>
         <div className='flex justify-center'>
           {/* TODO(burdon): Option to have button on RHS. Default size for icon should be 5 for this (medium) density. */}
           <IconButton
-            classNames='w-full max-w-[15rem] rounded'
+            classNames='is-full max-is-[15rem] rounded'
             variant='primary'
             icon='ph--arrows-clockwise--regular'
             label='Test'
-            size={5}
           />
         </div>
       </div>

package/src/testing/decorators/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './withLayout';
+export * from './withLayoutVariants';
 export * from './withTheme';
-export * from './withSurfaceVariantsLayout';

package/src/testing/decorators/withLayout.tsx

@@ -0,0 +1,56 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Decorator } from '@storybook/react';
+import React, { type FC, type PropsWithChildren } from 'react';
+
+import { type ClassNameValue, type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+export type ContainerProps = ThemedClassName<PropsWithChildren>;
+
+export type ContainerType = 'default' | 'column';
+
+export type WithLayoutProps =
+  | FC<ContainerProps>
+  | { classNames?: ClassNameValue; container?: ContainerType; scroll?: boolean };
+
+/**
+ * Adds layout container.
+ */
+export const withLayout =
+  (props: WithLayoutProps): Decorator =>
+  (Story) => {
+    if (typeof props === 'function') {
+      const Container = props;
+      return (
+        <Container>
+          <Story />
+        </Container>
+      );
+    }
+
+    const Container = layouts[(props as any).container as ContainerType] ?? layouts.default;
+    return (
+      <Container classNames={mx(props.classNames, props.scroll ? 'overflow-y-auto' : 'overflow-hidden')}>
+        <Story />
+      </Container>
+    );
+  };
+
+const layouts: Record<ContainerType, FC<ContainerProps>> = {
+  default: ({ children, classNames }: ContainerProps) => (
+    <div role='none' className={mx(classNames)}>
+      {children}
+    </div>
+  ),
+
+  column: ({ children, classNames }: ContainerProps) => (
+    <div role='none' className='fixed inset-0 flex justify-center overflow-hidden bg-deckSurface'>
+      <div role='none' className={mx('flex flex-col is-[40rem] bg-baseSurface', classNames)}>
+        {children}
+      </div>
+    </div>
+  ),
+};

package/src/testing/decorators/{withSurfaceVariantsLayout.tsx → withLayoutVariants.tsx}

@@ -23,7 +23,7 @@ const Panel = ({
   densities,
   className,
 }: { Story: ComponentType } & Config & { className?: string }) => (
-  <div className={mx('flex flex-col h-full p-4 gap-4', className)}>
+  <div className={mx('flex flex-col bs-full p-4 gap-4', className)}>
     {elevations?.map(({ elevation, surface }) =>
       densities?.map((density) => (
         <Container key={`${elevation}--${density}`} surface={surface} elevation={elevation}>
@@ -34,7 +34,7 @@ const Panel = ({
   </div>
 );
 
-export const withSurfaceVariantsLayout = ({
+export const withLayoutVariants = ({
   elevations = [
     { elevation: 'base', surface: 'bg-baseSurface' },
     { elevation: 'positioned', surface: 'bg-cardSurface' },

package/src/util/domino.ts

@@ -29,12 +29,14 @@ export class Domino<T extends HTMLElement> {
     this._el.dataset[key] = value;
     return this;
   }
-  style(styles: Partial<CSSStyleDeclaration>): this {
-    Object.assign(this._el.style, styles);
+  attributes(attr: Record<string, string | undefined>): this {
+    Object.entries(attr)
+      .filter(([_, value]) => value !== undefined)
+      .map(([key, value]) => this._el.setAttribute(key, value!));
     return this;
   }
-  attr<K extends keyof T>(key: K, value: T[K]): this {
-    (this._el as any)[key] = value;
+  style(styles: Partial<CSSStyleDeclaration>): this {
+    Object.assign(this._el.style, styles);
     return this;
   }
   children<C extends HTMLElement>(...children: Domino<C>[]): this {