@dxos/react-ui 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/src/components/ScrollArea/ScrollArea.tsx

@@ -1,138 +1,105 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import {
-  Corner as ScrollAreaPrimitiveCorner,
-  type ScrollAreaCornerProps as ScrollAreaPrimitiveCornerProps,
-  Root as ScrollAreaPrimitiveRoot,
-  type ScrollAreaProps as ScrollAreaPrimitiveRootProps,
-  Scrollbar as ScrollAreaPrimitiveScrollbar,
-  type ScrollAreaScrollbarProps as ScrollAreaPrimitiveScrollbarProps,
-  Thumb as ScrollAreaPrimitiveThumb,
-  type ScrollAreaThumbProps as ScrollAreaPrimitiveThumbProps,
-  Viewport as ScrollAreaPrimitiveViewport,
-  type ScrollAreaViewportProps as ScrollAreaPrimitiveViewportProps,
-} from '@radix-ui/react-scroll-area';
-import React, { type PropsWithChildren, forwardRef } from 'react';
-
-import { mx } from '@dxos/ui-theme';
+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 { useThemeContext } from '../../hooks';
-import { type ThemedClassName } from '../../util';
+import { composableProps } from '@dxos/ui-theme';
+import { type AllowedAxis, type SlottableProps, type ThemedClassName } from '@dxos/ui-types';
 
-type ScrollAreaVariant = 'coarse' | 'fine';
+import { useThemeContext } from '../../hooks';
 
 //
-// Root
+// Context
 //
 
-type ScrollAreaRootProps = ThemedClassName<ScrollAreaPrimitiveRootProps>;
-
-const ScrollAreaRoot = forwardRef<HTMLDivElement, ScrollAreaRootProps>(({ classNames, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <ScrollAreaPrimitiveRoot
-      {...props}
-      className={tx('scrollArea.root', 'scroll-area', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
-});
-
-//
-// Viewport
-//
+const SCROLLAREA_NAME = 'ScrollArea';
 
-type ScrollAreaViewportProps = ThemedClassName<ScrollAreaPrimitiveViewportProps>;
+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 ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
-  ({ classNames, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
-    return (
-      <ScrollAreaPrimitiveViewport
-        {...props}
-        className={tx('scrollArea.viewport', 'scroll-area', {}, classNames)}
-        ref={forwardedRef}
-      />
-    );
-  },
-);
+const [ScrollAreaProvider, useScrollAreaContext] = createContext<ScrollAreaContextType>(SCROLLAREA_NAME);
 
 //
-// Scrollbar
+// Root
 //
 
-type ScrollAreaScrollbarProps = ThemedClassName<ScrollAreaPrimitiveScrollbarProps> & { variant?: ScrollAreaVariant };
+const SCROLLAREA_ROOT_NAME = 'ScrollArea.Root';
+
+type ScrollAreaRootProps = SlottableProps<HTMLDivElement, Partial<ScrollAreaContextType>>;
 
-const ScrollAreaScrollbar = forwardRef<HTMLDivElement, ScrollAreaScrollbarProps>(
-  ({ classNames, variant = 'fine', ...props }, forwardedRef) => {
+/**
+ * ScrollArea provides native scrollbars with custom styling.
+ */
+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 (
-      <ScrollAreaPrimitiveScrollbar
-        data-variant={variant}
-        {...props}
-        className={tx('scrollArea.scrollbar', 'scroll-area__scrollbar', {}, classNames)}
-        ref={forwardedRef}
-      />
+      <ScrollAreaProvider {...options}>
+        <Comp {...rest} className={tx('scrollArea.root', options, className)} ref={forwardedRef}>
+          {children}
+        </Comp>
+      </ScrollAreaProvider>
     );
   },
 );
 
-//
-// Thumb
-//
-
-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}
-    />
-  );
-});
+ScrollAreaRoot.displayName = SCROLLAREA_ROOT_NAME;
 
 //
-// Corner
+// Viewport
 //
 
-type ScrollAreaCornerProps = ThemedClassName<ScrollAreaPrimitiveCornerProps>;
+const SCROLLAREA_VIEWPORT_NAME = 'ScrollArea.Viewport';
 
-const ScrollAreaCorner = forwardRef<HTMLDivElement, ScrollAreaCornerProps>(({ classNames, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <ScrollAreaPrimitiveCorner
-      {...props}
-      className={tx('scrollArea.corner', 'scroll-area__corner', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
-});
+type ScrollAreaViewportProps = ThemedClassName<HTMLAttributes<HTMLDivElement>>;
 
-//
-// Expander
-//
-
-type ScrollAreaExpanderProps = ThemedClassName<PropsWithChildren>;
+const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(
+  ({ classNames, children, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const options = useScrollAreaContext(SCROLLAREA_VIEWPORT_NAME);
 
-/**
- * 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'>
+    return (
+      <div {...props} className={tx('scrollArea.viewport', options, classNames)} ref={forwardedRef}>
         {children}
       </div>
-    </div>
-  );
-};
+    );
+  },
+);
+
+ScrollAreaViewport.displayName = SCROLLAREA_VIEWPORT_NAME;
 
 //
 // ScrollArea
@@ -141,17 +108,6 @@ const ScrollAreaExpander = ({ classNames, children }: ScrollAreaExpanderProps) =
 export const ScrollArea = {
   Root: ScrollAreaRoot,
   Viewport: ScrollAreaViewport,
-  Scrollbar: ScrollAreaScrollbar,
-  Thumb: ScrollAreaThumb,
-  Corner: ScrollAreaCorner,
-  Expander: ScrollAreaExpander,
 };
 
-export type {
-  ScrollAreaRootProps,
-  ScrollAreaViewportProps,
-  ScrollAreaScrollbarProps,
-  ScrollAreaThumbProps,
-  ScrollAreaCornerProps,
-  ScrollAreaExpanderProps,
-};
+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

@@ -7,16 +7,22 @@ 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';
 
-const DefaultStory = (props: ScrollContainerRootProps) => {
+type StoryProps = ScrollContainerRootProps & { running?: boolean; initialLines?: number };
+
+const DefaultStory = ({ initialLines = 0, running: runningProp, ...props }: StoryProps) => {
   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 }, () => faker.lorem.paragraph()));
+  }, [initialLines]);
   useEffect(() => {
     if (!running) {
       return;
@@ -30,32 +36,36 @@ const DefaultStory = (props: ScrollContainerRootProps) => {
   }, [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-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/ScrollContainer',
+  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;
@@ -66,5 +76,14 @@ 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

@@ -15,7 +15,6 @@ import React, {
   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';
@@ -23,6 +22,7 @@ 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);
@@ -68,7 +68,7 @@ const Root = forwardRef<ScrollController, RootProps>(
     const timeoutRef = useRef<NodeJS.Timeout>(undefined);
     const scrollToBottom = useCallback((behavior: ScrollBehavior = behaviorProp) => {
       if (scrollerRef.current) {
-        // Temporarily hide scrollbar to prevent flicker.
+        // Temporarily hide scrollbar to prevent flickering.
         autoScrollRef.current = true;
         scrollerRef.current.classList.add('scrollbar-none');
         scrollerRef.current.scrollTo({
@@ -83,6 +83,7 @@ const Root = forwardRef<ScrollController, RootProps>(
             autoScrollRef.current = false;
           }, 500);
         }
+
         setPinned(true);
       }
     }, []);
@@ -125,22 +126,22 @@ const Root = forwardRef<ScrollController, RootProps>(
 
     return (
       <ScrollContainerProvider pinned={pinned} controller={controller} scrollToBottom={scrollToBottom}>
-        <div className='relative grid flex-1 min-bs-0 overflow-hidden'>
+        <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 block-start-0 inset-inline-0 bs-24 is-full',
+                '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',
+                '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>
+          <ScrollArea.Root classNames={mx('min-h-0', classNames)} thin>
+            <ScrollArea.Viewport ref={scrollerRef}>{children}</ScrollArea.Viewport>
+          </ScrollArea.Root>
         </div>
       </ScrollContainerProvider>
     );
@@ -153,11 +154,13 @@ 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.displayName!);
+  const { pinned, scrollToBottom } = useScrollContainerContext(VIEWPORT_NAME);
 
   useEffect(() => {
     if (!pinned || !contentRef.current) {
@@ -174,22 +177,24 @@ const Viewport = forwardRef<HTMLDivElement, ViewportProps>(({ classNames, childr
   }, [pinned, scrollToBottom]);
 
   return (
-    <div className={mx('is-full', classNames)} {...props} ref={contentRef}>
+    <div className={mx('w-full', classNames)} {...props} ref={contentRef}>
       {children}
     </div>
   );
 });
 
-Viewport.displayName = 'ScrollContainer.Viewport';
+Viewport.displayName = VIEWPORT_NAME;
 
 //
 // ScrollDownButton
 //
 
+const SCROLL_DOWN_BUTTON_NAME = 'ScrollContainer.ScrollDownButton';
+
 type ScrollDownButtonProps = ThemedClassName;
 
 const ScrollDownButton = ({ classNames }: ScrollDownButtonProps) => {
-  const { pinned, scrollToBottom } = useScrollContainerContext(ScrollDownButton.displayName!);
+  const { pinned, scrollToBottom } = useScrollContainerContext(SCROLL_DOWN_BUTTON_NAME);
 
   return (
     <div
@@ -212,7 +217,7 @@ const ScrollDownButton = ({ classNames }: ScrollDownButtonProps) => {
   );
 };
 
-ScrollDownButton.displayName = 'ScrollContainer.ScrollDownButton';
+ScrollDownButton.displayName = SCROLL_DOWN_BUTTON_NAME;
 
 //
 // ScrollContainer

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

@@ -42,9 +42,9 @@ const DefaultStory = ({ items = [] }: StoryProps) => {
 };
 
 const meta = {
-  title: 'ui/react-ui-core/Select',
+  title: 'ui/react-ui-core/components/Select',
   render: DefaultStory,
-  decorators: [withTheme, withLayoutVariants()],
+  decorators: [withTheme(), withLayoutVariants()],
 } satisfies Meta<typeof DefaultStory>;
 
 export default meta;

package/src/components/Select/Select.tsx

@@ -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='is-1 flex-1' />
+          <span className='w-1 flex-1' />
           <SelectPrimitive.Icon asChild>
             <Icon size={3} icon='ph--caret-down--bold' />
           </SelectPrimitive.Icon>
@@ -61,7 +61,7 @@ const SelectContent = forwardRef<HTMLDivElement, SelectContentProps>(
         {...props}
         data-arrow-keys='up down'
         collisionPadding={safeCollisionPadding}
-        className={tx('select.content', 'select__content', { elevation }, classNames)}
+        className={tx('select.content', { elevation }, classNames)}
         position='popper'
         ref={forwardedRef}
       >
@@ -79,7 +79,7 @@ const SelectScrollUpButton = forwardRef<HTMLDivElement, SelectScrollUpButtonProp
     return (
       <SelectPrimitive.SelectScrollUpButton
         {...props}
-        className={tx('select.scrollButton', 'select__scroll-button--up', {}, classNames)}
+        className={tx('select.scrollButton', {}, classNames)}
         ref={forwardedRef}
       >
         {children ?? <Icon size={3} icon='ph--caret-up--bold' />}
@@ -96,7 +96,7 @@ const SelectScrollDownButton = forwardRef<HTMLDivElement, SelectScrollDownButton
     return (
       <SelectPrimitive.SelectScrollDownButton
         {...props}
-        className={tx('select.scrollButton', 'select__scroll-button--down', {}, classNames)}
+        className={tx('select.scrollButton', {}, classNames)}
         ref={forwardedRef}
       >
         {children ?? <Icon size={3} icon='ph--caret-down--bold' />}
@@ -111,11 +111,7 @@ const SelectViewport = forwardRef<HTMLDivElement, SelectViewportProps>(
   ({ classNames, children, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
     return (
-      <SelectPrimitive.SelectViewport
-        {...props}
-        className={tx('select.viewport', 'select__viewport', {}, classNames)}
-        ref={forwardedRef}
-      >
+      <SelectPrimitive.SelectViewport {...props} className={tx('select.viewport', {}, classNames)} ref={forwardedRef}>
         {children}
       </SelectPrimitive.SelectViewport>
     );
@@ -126,7 +122,7 @@ type SelectItemProps = ThemedClassName<SelectPrimitive.SelectItemProps>;
 
 const SelectItem = forwardRef<HTMLDivElement, SelectItemProps>(({ classNames, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
-  return <SelectPrimitive.Item {...props} className={tx('select.item', 'option', {}, classNames)} ref={forwardedRef} />;
+  return <SelectPrimitive.Item {...props} className={tx('select.item', {}, classNames)} ref={forwardedRef} />;
 });
 
 type SelectItemTextProps = SelectPrimitive.SelectItemTextProps;
@@ -141,7 +137,7 @@ const SelectItemIndicator = forwardRef<HTMLDivElement, SelectItemIndicatorProps>
     return (
       <SelectPrimitive.ItemIndicator
         {...props}
-        className={tx('select.itemIndicator', 'option__indicator', {}, classNames)}
+        className={tx('select.itemIndicator', {}, classNames)}
         ref={forwardedRef}
       >
         {children}
@@ -156,9 +152,9 @@ type SelectOptionProps = SelectItemProps;
 const SelectOption = forwardRef<HTMLDivElement, SelectItemProps>(({ children, classNames, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
   return (
-    <SelectPrimitive.Item {...props} className={tx('select.item', 'option', {}, classNames)} ref={forwardedRef}>
+    <SelectPrimitive.Item {...props} className={tx('select.item', {}, classNames)} ref={forwardedRef}>
       <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
-      <span className='grow is-1' />
+      <span className='grow w-1' />
       {/* <SelectPrimitive.ItemIndicator className={tx('select.itemIndicator', 'option__indicator', {})}> */}
       <Icon icon='ph--check--regular' />
       {/* </SelectPrimitive.ItemIndicator> */}
@@ -178,26 +174,14 @@ type SelectSeparatorProps = ThemedClassName<SelectPrimitive.SelectSeparatorProps
 
 const SelectSeparator = forwardRef<HTMLDivElement, SelectSeparatorProps>(({ classNames, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
-  return (
-    <SelectPrimitive.Separator
-      {...props}
-      className={tx('select.separator', 'select__separator', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
+  return <SelectPrimitive.Separator {...props} className={tx('select.separator', {}, classNames)} ref={forwardedRef} />;
 });
 
 type SelectArrowProps = ThemedClassName<SelectPrimitive.SelectArrowProps>;
 
 const SelectArrow = forwardRef<SVGSVGElement, SelectArrowProps>(({ classNames, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
-  return (
-    <SelectPrimitive.Arrow
-      {...props}
-      className={tx('select.arrow', 'select__arrow', {}, classNames)}
-      ref={forwardedRef}
-    />
-  );
+  return <SelectPrimitive.Arrow {...props} className={tx('select.arrow', {}, classNames)} ref={forwardedRef} />;
 });
 
 export const Select = {

package/src/components/Separator/Separator.tsx

@@ -19,7 +19,7 @@ const Separator = forwardRef<HTMLDivElement, SeparatorProps>(
       <SeparatorPrimitive
         orientation={orientation}
         {...props}
-        className={tx('separator.root', 'separator', { orientation, subdued }, classNames)}
+        className={tx('separator.root', { orientation, subdued }, classNames)}
         ref={forwardedRef}
       />
     );

package/src/components/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { withTheme } from '../../testing';
+
+import { Skeleton } from './Skeleton';
+
+export default {
+  title: 'ui/react-ui-core/components/Skeleton',
+  component: Skeleton,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+};
+
+export const Default = {
+  render: () => (
+    <div className='flex flex-col gap-4 p-4 border border-separator rounded-xs'>
+      <div className='flex w-fit items-center gap-4'>
+        <Skeleton classNames='size-10 shrink-0 rounded-full' />
+        <div className='grid gap-2'>
+          <Skeleton classNames='h-4 w-[150px]' />
+          <Skeleton classNames='h-4 w-[100px]' />
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const Card = {
+  render: () => (
+    <div className='flex flex-col gap-3 w-96 p-4 border border-separator rounded-xs'>
+      <div className='flex items-center gap-3'>
+        <Skeleton variant='circle' classNames='h-12 w-12 rounded-full' />
+        <div className='flex flex-col gap-2 flex-1'>
+          <Skeleton classNames='h-4 w-24' />
+          <Skeleton classNames='h-3 w-32' />
+        </div>
+      </div>
+      <Skeleton classNames='h-32 w-full rounded-sm' />
+      <div className='flex flex-col gap-2'>
+        <Skeleton classNames='h-3 w-full' />
+        <Skeleton classNames='h-3 w-5/6' />
+        <Skeleton classNames='h-3 w-4/6' />
+      </div>
+    </div>
+  ),
+};

package/src/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { type ComponentPropsWithRef, forwardRef } from 'react';
+
+import { useThemeContext } from '../../hooks';
+import { type ThemedClassName } from '../../util';
+
+type SkeletonProps = ThemedClassName<ComponentPropsWithRef<'div'>> & {
+  variant?: 'default' | 'circle' | 'text';
+};
+
+/**
+ * A skeleton loading component that displays a placeholder while content is loading.
+ */
+const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(
+  ({ classNames, variant = 'default', ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    return <div {...props} className={tx('skeleton.root', { variant }, classNames)} ref={forwardedRef} />;
+  },
+);
+
+export { Skeleton };
+
+export type { SkeletonProps };

package/src/components/Skeleton/index.ts

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