@dxos/react-ui-stack 0.8.3-staging.0fa589b → 0.8.4-main.1da679c

package/src/components/StackItem/StackItem.tsx

@@ -7,46 +7,47 @@ import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-d
 import { preserveOffsetOnSource } from '@atlaskit/pragmatic-drag-and-drop/element/preserve-offset-on-source';
 import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
 import {
+  type Edge,
   attachClosestEdge,
   extractClosestEdge,
-  type Edge,
 } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
 import { useFocusableGroup } from '@fluentui/react-tabster';
 import { composeRefs } from '@radix-ui/react-compose-refs';
 import React, {
-  forwardRef,
-  useLayoutEffect,
-  useState,
   type ComponentPropsWithRef,
-  useCallback,
   type ReactNode,
+  forwardRef,
+  useCallback,
+  useLayoutEffect,
   useMemo,
+  useState,
 } from 'react';
 import { createPortal } from 'react-dom';
 
-import { type ThemedClassName, ListItem } from '@dxos/react-ui';
+import { ListItem, type ThemedClassName } from '@dxos/react-ui';
 import { resizeAttributes, sizeStyle } from '@dxos/react-ui-dnd';
 import { mx } from '@dxos/react-ui-theme';
 
+import { type StackItemData, type StackItemSize } from '../defs';
+import { type ItemDragState, StackItemContext, idle, useStack, useStackItem } from '../StackContext';
+
 import { StackItemContent, type StackItemContentProps } from './StackItemContent';
 import { StackItemDragHandle, type StackItemDragHandleProps } from './StackItemDragHandle';
 import {
   StackItemHeading,
   StackItemHeadingLabel,
-  type StackItemHeadingProps,
   type StackItemHeadingLabelProps,
+  type StackItemHeadingProps,
   StackItemHeadingStickyContent,
 } from './StackItemHeading';
 import { StackItemResizeHandle, type StackItemResizeHandleProps } from './StackItemResizeHandle';
 import {
   StackItemSigil,
-  type StackItemSigilProps,
   type StackItemSigilAction,
-  type StackItemSigilButtonProps,
   StackItemSigilButton,
+  type StackItemSigilButtonProps,
+  type StackItemSigilProps,
 } from './StackItemSigil';
-import { useStack, StackItemContext, idle, type ItemDragState, useStackItem } from '../StackContext';
-import { type StackItemSize, type StackItemData } from '../defs';
 
 // NOTE: 48rem fills the screen on a MacbookPro with the sidebars closed.
 export const DEFAULT_HORIZONTAL_SIZE = 48 satisfies StackItemSize;
@@ -89,7 +90,7 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
     const [closestEdge, setEdge] = useState<Edge | null>(null);
     const [sourceId, setSourceId] = useState<string | null>(null);
     const [dragState, setDragState] = useState<ItemDragState>(idle);
-    const { orientation, rail, onRearrange } = useStack();
+    const { orientation, rail, onRearrange, size: stackSize, stackId } = useStack();
     const [size = orientation === 'horizontal' ? DEFAULT_HORIZONTAL_SIZE : DEFAULT_VERTICAL_SIZE, setInternalSize] =
       useState(propsSize);
 
@@ -239,10 +240,10 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
             role === 'section' && orientation !== 'horizontal' && 'border-be border-subduedSeparator',
             classNames,
           )}
-          data-dx-stack-item
+          data-dx-stack-item={stackId}
           {...resizeAttributes}
           style={{
-            ...sizeStyle(size, orientation),
+            ...(stackSize !== 'split' && sizeStyle(size, orientation)),
             ...(Number.isFinite(order) && {
               [orientation === 'horizontal' ? 'gridColumn' : 'gridRow']: `${order}`,
             }),

package/src/components/StackItem/StackItemContent.tsx

@@ -9,7 +9,7 @@ import { mx } from '@dxos/react-ui-theme';
 
 import { useStack, useStackItem } from '../StackContext';
 
-export type StackItemContentProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & {
+export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRef<'div'>, 'role'>> & {
   /**
    * This flag is required in order to clarify a developer experience that seemed like it needed extra boilerplate
    * (`row-span-2`) or was buggy. See the description of the StackItem.Content component itself for more information.
@@ -54,15 +54,16 @@ export const StackItemContent = forwardRef<HTMLDivElement, StackItemContentProps
             },
       [toolbar, statusbar, layoutManaged],
     );
+
     return (
       <div
         role='none'
         {...props}
         className={mx(
-          'group grid grid-cols-[100%]',
+          'group grid grid-cols-[100%] density-coarse',
           stackItemSize === 'contain' && 'min-bs-0 overflow-hidden',
           size === 'video' ? 'aspect-video' : size === 'square' && 'aspect-square',
-          toolbar && '[&_.dx-toolbar]:relative [&_.dx-toolbar]:border-be [&_.dx-toolbar]:border-subduedSeparator',
+          toolbar && '[&>.dx-toolbar]:relative [&>.dx-toolbar]:border-be [&>.dx-toolbar]:border-subduedSeparator',
           role === 'section' &&
             toolbar &&
             '[&_.dx-toolbar]:sticky [&_.dx-toolbar]:z-[1] [&_.dx-toolbar]:block-start-0 [&_.dx-toolbar]:-mbe-px [&_.dx-toolbar]:min-is-0',

package/src/components/StackItem/StackItemHeading.tsx

@@ -5,14 +5,14 @@
 import { useFocusableGroup } from '@fluentui/react-tabster';
 import { Slot } from '@radix-ui/react-slot';
 import React, {
-  type ComponentPropsWithoutRef,
   type ComponentPropsWithRef,
-  forwardRef,
+  type ComponentPropsWithoutRef,
   type PropsWithChildren,
+  forwardRef,
 } from 'react';
 
 import { type ThemedClassName } from '@dxos/react-ui';
-import { useAttention, type AttendableId, type Related } from '@dxos/react-ui-attention';
+import { type AttendableId, type Related, useAttention } from '@dxos/react-ui-attention';
 import { mx } from '@dxos/react-ui-theme';
 
 import { useStack } from '../StackContext';

package/src/components/StackItem/StackItemResizeHandle.tsx

@@ -6,9 +6,10 @@ import React from 'react';
 
 import { ResizeHandle } from '@dxos/react-ui-dnd';
 
-import { DEFAULT_EXTRINSIC_SIZE } from './StackItem';
 import { useStack, useStackItem } from '../StackContext';
 
+import { DEFAULT_EXTRINSIC_SIZE } from './StackItem';
+
 const MIN_WIDTH = 20;
 const MIN_HEIGHT = 3;
 

package/src/components/StackItem/StackItemSigil.tsx

@@ -11,9 +11,10 @@ import { type AttendableId, type Related, useAttention } from '@dxos/react-ui-at
 import { descriptionText, mx } from '@dxos/react-ui-theme';
 import { getHostPlatform } from '@dxos/util';
 
-import { MenuSignifierHorizontal } from './MenuSignifier';
 import { translationKey } from '../../translations';
 
+import { MenuSignifierHorizontal } from './MenuSignifier';
+
 export type KeyBinding = {
   windows?: string;
   macos?: string;

package/src/components/index.ts

@@ -2,7 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './defs';
+export type * from './defs';
 
+export * from './Image';
 export * from './Stack';
 export * from './StackItem';

package/src/exemplars/Card/Card.stories.tsx

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { faker } from '@dxos/random';
+import { withTheme } from '@dxos/storybook-utils';
+
+import { Card } from './Card';
+
+faker.seed(0);
+
+type CardStoryProps = {
+  title: string;
+  description: string;
+  image: string;
+  showImage: boolean;
+  showIcon: boolean;
+};
+
+const DefaultStory = ({ title, description, image, showImage, showIcon }: CardStoryProps) => {
+  return (
+    <div className='max-is-md'>
+      <Card.StaticRoot>
+        <Card.Toolbar>
+          <Card.DragHandle toolbarItem />
+          <Card.ToolbarSeparator variant='gap' />
+          <Card.ToolbarIconButton iconOnly variant='ghost' icon='ph--x--regular' label={'remove card label'} />
+        </Card.Toolbar>
+        {showImage && <Card.Poster alt={title} image={image} />}
+        {!showImage && showIcon && <Card.Poster alt={title} icon='ph--building-office--regular' />}
+        <Card.Heading>{title}</Card.Heading>
+        {description && <Card.Text classNames='line-clamp-2'>{description}</Card.Text>}
+      </Card.StaticRoot>
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-stack/Card',
+  render: DefaultStory,
+  decorators: [withTheme],
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    title: {
+      control: 'text',
+      description: 'Card title',
+    },
+    description: {
+      control: 'text',
+      description: 'Card description',
+    },
+    image: {
+      control: 'text',
+      description: 'URL for the poster image',
+    },
+    showImage: {
+      control: 'boolean',
+      description: 'Whether to show the image',
+    },
+    showIcon: {
+      control: 'boolean',
+      description: 'Whether to show an icon (when image is not shown)',
+    },
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const image = faker.image.url();
+
+export const Default: Story = {
+  args: {
+    title: faker.commerce.productName(),
+    description: faker.lorem.paragraph(),
+    image,
+    showImage: true,
+    showIcon: true,
+  },
+};

package/src/exemplars/Card/Card.tsx

@@ -5,40 +5,27 @@
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
 import React, {
-  type ComponentPropsWithoutRef,
   type ComponentPropsWithRef,
+  type ComponentPropsWithoutRef,
   type FC,
-  forwardRef,
   type PropsWithChildren,
+  forwardRef,
 } from 'react';
 
 import { Icon, IconButton, type ThemedClassName, Toolbar, type ToolbarRootProps, useTranslation } from '@dxos/react-ui';
 import { hoverableControls, mx } from '@dxos/react-ui-theme';
 
-import { cardChrome, cardContent, cardHeading, cardRoot, cardText, cardSpacing } from './fragments';
-import { StackItem } from '../../components';
+import { Image, StackItem } from '../../components';
 import { translationKey } from '../../translations';
 
-type SharedCardProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & { asChild?: boolean };
+import { cardChrome, cardHeading, cardRoot, cardSpacing, cardText } from './fragments';
 
-const CardRoot = forwardRef<HTMLDivElement, SharedCardProps>(
-  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
-    const Root = asChild ? Slot : 'div';
-    const rootProps = asChild ? { classNames: [cardRoot, classNames] } : { className: mx(cardRoot, classNames), role };
-    return (
-      <Root {...props} {...rootProps} ref={forwardedRef}>
-        {children}
-      </Root>
-    );
-  },
-);
+type SharedCardProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & { asChild?: boolean };
 
-const CardContent = forwardRef<HTMLDivElement, SharedCardProps>(
+const CardStaticRoot = forwardRef<HTMLDivElement, SharedCardProps>(
   ({ children, classNames, asChild, role = 'group', ...props }, forwardedRef) => {
     const Root = asChild ? Slot : 'div';
-    const rootProps = asChild
-      ? { classNames: [cardContent, classNames] }
-      : { className: mx(cardContent, classNames), role };
+    const rootProps = asChild ? { classNames: [cardRoot, classNames] } : { className: mx(cardRoot, classNames), role };
     return (
       <Root {...props} {...rootProps} ref={forwardedRef}>
         {children}
@@ -49,21 +36,40 @@ const CardContent = forwardRef<HTMLDivElement, SharedCardProps>(
 
 /**
  * This should be used by Surface fulfillments in cases where the content may or may not already be encapsulated (e.g.
- * in a Popover) and knows this based on the `role` it receives. This will render a `Card.Content` by default, otherwise
+ * in a Popover) and knows this based on the `role` it receives. This will render a `Card.StaticRoot` by default, otherwise
  * it will render a `div` primitive with the appropriate styling for specific handled situations.
  */
-const CardConditionalContent = ({ role, children }: PropsWithChildren<{ role?: string }>) => {
-  if (['popover', 'card--kanban'].includes(role ?? 'never')) {
+const CardSurfaceRoot = ({
+  role = 'never',
+  children,
+  classNames,
+}: ThemedClassName<PropsWithChildren<{ role?: string }>>) => {
+  if (['card--popover', 'card--intrinsic', 'card--extrinsic'].includes(role)) {
     return (
-      <div className={role === 'popover' ? 'popover-card-width' : role === 'card--kanban' ? 'contents' : ''}>
+      <div
+        className={mx(
+          role === 'card--popover'
+            ? 'popover-card-width'
+            : ['card--intrinsic', 'card--extrinsic'].includes(role)
+              ? 'contents'
+              : '',
+          classNames,
+        )}
+      >
         {children}
       </div>
     );
   } else {
     return (
-      <CardContent {...(role === 'card--document' && { classNames: ['mlb-[1em]', hoverableControls] })}>
+      <CardStaticRoot
+        classNames={[
+          role === 'card--transclusion' && 'mlb-1',
+          role === 'card--transclusion' && hoverableControls,
+          classNames,
+        ]}
+      >
         {children}
-      </CardContent>
+      </CardStaticRoot>
     );
   }
 };
@@ -84,7 +90,7 @@ const CardHeading = forwardRef<HTMLDivElement, SharedCardProps>(
 
 const CardToolbar = forwardRef<HTMLDivElement, ToolbarRootProps>(({ children, classNames, ...props }, forwardedRef) => {
   return (
-    <Toolbar.Root {...props} classNames={['bg-transparent', classNames]} ref={forwardedRef}>
+    <Toolbar.Root {...props} classNames={['bg-transparent density-coarse', classNames]} ref={forwardedRef}>
       {children}
     </Toolbar.Root>
   );
@@ -101,7 +107,7 @@ const CardDragHandle = forwardRef<HTMLButtonElement, { toolbarItem?: boolean }>(
       iconOnly
       icon='ph--dots-six-vertical--regular'
       variant='ghost'
-      label={t('card drag handle label')}
+      label={t('drag handle label')}
       classNames='pli-2'
       ref={forwardedRef}
     />
@@ -120,15 +126,14 @@ type CardPosterProps = {
 const CardPoster = (props: CardPosterProps) => {
   const aspect = props.aspect === 'auto' ? 'aspect-auto' : 'aspect-video';
   if (props.image) {
-    return (
-      <img className={`dx-card__poster ${aspect} object-cover is-full bs-auto`} src={props.image} alt={props.alt} />
-    );
+    return <Image classNames={[`dx-card__poster is-full __bs-auto`, aspect]} src={props.image} alt={props.alt} />;
   }
+
   if (props.icon) {
     return (
       <div
         role='image'
-        className={`dx-card__poster grid ${aspect} place-items-center bg-inputSurface text-subdued`}
+        className={mx(`dx-card__poster grid place-items-center bg-inputSurface text-subdued`, aspect)}
         aria-label={props.alt}
       >
         <Icon icon={props.icon} size={10} />
@@ -151,9 +156,9 @@ const CardChrome = forwardRef<HTMLDivElement, SharedCardProps>(
   },
 );
 
-const CardText = forwardRef<HTMLParagraphElement, SharedCardProps>(
+const CardText = forwardRef<HTMLDivElement, SharedCardProps>(
   ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
-    const Root = asChild ? Slot : 'p';
+    const Root = asChild ? Slot : 'div';
     const rootProps = asChild ? { classNames: [cardText, classNames] } : { className: mx(cardText, classNames), role };
     return (
       <Root {...props} {...rootProps} ref={forwardedRef}>
@@ -164,9 +169,8 @@ const CardText = forwardRef<HTMLParagraphElement, SharedCardProps>(
 );
 
 export const Card = {
-  Root: CardRoot,
-  Content: CardContent,
-  Container: CardConditionalContent,
+  StaticRoot: CardStaticRoot,
+  SurfaceRoot: CardSurfaceRoot,
   Heading: CardHeading,
   Toolbar: CardToolbar,
   ToolbarIconButton: CardToolbarIconButton,
@@ -179,4 +183,4 @@ export const Card = {
   Text: CardText,
 };
 
-export { cardRoot, cardContent, cardHeading, cardText, cardChrome, cardSpacing };
+export { cardRoot, cardHeading, cardText, cardChrome, cardSpacing };

package/src/exemplars/Card/CardDragPreview.tsx

@@ -6,14 +6,14 @@ import React, { type PropsWithChildren } from 'react';
 
 import { mx } from '@dxos/react-ui-theme';
 
-import { cardContent } from './fragments';
+import { cardRoot } from './fragments';
 
 const CardDragPreviewRoot = ({ children }: PropsWithChildren<{}>) => {
   return <div className='p-2'>{children}</div>;
 };
 
 const CardDragPreviewContent = ({ children }: PropsWithChildren<{}>) => {
-  return <div className={mx(cardContent, 'ring-focusLine ring-neutralFocusIndicator')}>{children}</div>;
+  return <div className={mx(cardRoot, 'ring-focusLine ring-neutralFocusIndicator')}>{children}</div>;
 };
 
 export const CardDragPreview = {

package/src/exemplars/Card/fragments.ts

@@ -2,12 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-export const cardRoot = 'contain-layout pli-2 plb-1 first-of-type:pbs-0 last-of-type:pbe-0';
-
-export const cardContent =
+export const cardRoot =
   'rounded overflow-hidden bg-cardSurface border border-separator dark:border-subduedSeparator dx-focus-ring-group-y-indicator relative min-bs-[--rail-item] group/card';
 
 export const cardSpacing = 'pli-cardSpacingInline mlb-cardSpacingBlock';
+export const cardNoSpacing = 'pli-0 mlb-0';
 export const labelSpacing = 'mbs-inputSpacingBlock mbe-labelSpacingBlock';
 
 export const cardDialogContent = 'p-0 bs-content min-bs-[8rem] max-bs-full md:max-is-[32rem] overflow-hidden';
@@ -19,7 +18,7 @@ export const cardDialogSearchListRoot =
 
 export const cardText = cardSpacing;
 
-export const cardHeading = 'text-lg font-medium line-clamp-2';
+export const cardHeading = 'text-lg font-medium line-clamp-2 grow';
 
 export const cardChrome =
-  'pli-[--dx-cardSpacingChrome] mlb-[--dx-cardSpacingChrome] [&_.dx-button]:text-start [&_.dx-button]:is-full';
+  'pli-[--dx-cardSpacingChrome] mlb-[--dx-cardSpacingChrome] [&_.dx-button]:text-start [&_.dx-button]:is-full [&_.dx-button]:pis-[calc(var(--dx-cardSpacingInline)-var(--dx-cardSpacingChrome))]';

package/src/exemplars/CardStack/CardStack.stories.tsx

@@ -0,0 +1,172 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Edge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useState } from 'react';
+
+import { faker } from '@dxos/random';
+import { IconButton } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/storybook-utils';
+
+import { StackItem } from '../../components';
+import { Card, CardDragPreview } from '../Card';
+
+import { CardStack } from './CardStack';
+
+faker.seed(0);
+
+type CardItem = {
+  id: string;
+  title: string;
+  description: string;
+  image: string;
+};
+
+type StackItemData = {
+  id: string;
+  type?: 'column' | 'card';
+};
+
+const CardStackStory = () => {
+  const [column, setColumn] = useState<CardItem[]>(
+    faker.helpers.multiple(
+      () => ({
+        id: faker.string.uuid(),
+        title: faker.commerce.productName(),
+        description: faker.lorem.paragraph(),
+        image: faker.image.url(),
+      }),
+      { count: 12 },
+    ),
+  );
+
+  const handleRearrange = useCallback((source: StackItemData, target: StackItemData, closestEdge: Edge | null) => {
+    setColumn((prevColumn) => {
+      const newColumns = [...prevColumn];
+      // Reordering cards within a column
+      const sourceCardIndex = prevColumn.findIndex((card) => card.id === source.id);
+      const targetCardIndex = prevColumn.findIndex((card) => card.id === target.id);
+
+      if (typeof sourceCardIndex === 'number' && typeof targetCardIndex === 'number') {
+        const [movedCard] = newColumns.splice(sourceCardIndex, 1);
+
+        let insertIndex;
+        if (sourceCardIndex < targetCardIndex) {
+          insertIndex = closestEdge === 'bottom' ? targetCardIndex : targetCardIndex - 1;
+        } else {
+          insertIndex = closestEdge === 'bottom' ? targetCardIndex + 1 : targetCardIndex;
+        }
+        newColumns.splice(insertIndex, 0, movedCard);
+      }
+      return newColumns;
+    });
+  }, []);
+
+  const handleAddCard = useCallback(() => {
+    setColumn((prevColumn) => {
+      const newColumn = [...prevColumn];
+      const newCard = {
+        id: faker.string.uuid(),
+        title: faker.commerce.productName(),
+        description: faker.lorem.paragraph(),
+        image: faker.image.url(),
+      } satisfies CardItem;
+      newColumn.push(newCard);
+      console.log('[add card]', prevColumn.length, newColumn.length);
+      return newColumn;
+    });
+  }, []);
+
+  const handleRemoveCard = useCallback((cardId: string) => {
+    setColumn((prevColumn) => {
+      const newColumn = [...prevColumn];
+
+      const cardIndex = prevColumn.findIndex((card) => card.id === cardId);
+      if (cardIndex !== -1) {
+        newColumn.splice(cardIndex, 1);
+      }
+
+      return newColumn;
+    });
+  }, []);
+
+  return (
+    <CardStack.Root classNames='is-96'>
+      <CardStack.Content>
+        <CardStack.Stack id='story column' onRearrange={handleRearrange} itemsCount={column.length}>
+          {column.map((card, cardIndex, cardsArray) => {
+            const cardItem = { id: card.id, type: 'card' as const };
+            const prevCardId = cardIndex > 0 ? cardsArray[cardIndex - 1].id : undefined;
+            const nextCardId = cardIndex < cardsArray.length - 1 ? cardsArray[cardIndex + 1].id : undefined;
+
+            return (
+              <CardStack.Item asChild key={card.id}>
+                <StackItem.Root
+                  item={cardItem}
+                  focusIndicatorVariant='group'
+                  prevSiblingId={prevCardId}
+                  nextSiblingId={nextCardId}
+                >
+                  <Card.StaticRoot>
+                    <Card.Toolbar>
+                      <StackItem.DragHandle asChild>
+                        <Card.DragHandle toolbarItem />
+                      </StackItem.DragHandle>
+                      <Card.ToolbarSeparator variant='gap' />
+                      <Card.ToolbarIconButton
+                        iconOnly
+                        variant='ghost'
+                        icon='ph--x--regular'
+                        label='Remove card'
+                        onClick={() => handleRemoveCard(card.id)}
+                      />
+                    </Card.Toolbar>
+                    <Card.Poster alt={card.title} image={card.image} />
+                    <Card.Heading>{card.title}</Card.Heading>
+                    <Card.Text classNames='line-clamp-2'>{card.description}</Card.Text>
+                  </Card.StaticRoot>
+                  <StackItem.DragPreview>
+                    {() => (
+                      <CardDragPreview.Root>
+                        <CardDragPreview.Content>
+                          <Card.Toolbar>
+                            <Card.DragHandle toolbarItem />
+                          </Card.Toolbar>
+                          <Card.Poster alt={card.title} image={card.image} />
+                          <Card.Heading>{card.title}</Card.Heading>
+                          <Card.Text classNames='line-clamp-2'>{card.description}</Card.Text>
+                        </CardDragPreview.Content>
+                      </CardDragPreview.Root>
+                    )}
+                  </StackItem.DragPreview>
+                </StackItem.Root>
+              </CardStack.Item>
+            );
+          })}
+        </CardStack.Stack>
+
+        <CardStack.Footer>
+          <IconButton icon='ph--plus--regular' label='Add card' onClick={handleAddCard} classNames='is-full' />
+        </CardStack.Footer>
+
+        <CardStack.Heading>{faker.company.name()}</CardStack.Heading>
+      </CardStack.Content>
+    </CardStack.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-stack/CardStack',
+  component: CardStackStory,
+  decorators: [withTheme, withLayout({ fullscreen: true })],
+} satisfies Meta<typeof CardStackStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof CardStackStory>;
+
+export const Default: Story = {};

package/src/exemplars/CardStack/CardStack.tsx

@@ -8,7 +8,7 @@ import React, { type ComponentPropsWithoutRef, forwardRef } from 'react';
 import type { ThemedClassName } from '@dxos/react-ui';
 import { mx } from '@dxos/react-ui-theme';
 
-import { railGridHorizontalContainFitContent, Stack, type StackProps } from '../../components';
+import { Stack, type StackProps, railGridHorizontalContainFitContent } from '../../components';
 import { Card } from '../Card';
 
 type SharedCardStackProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & { asChild?: boolean };
@@ -107,6 +107,22 @@ const CardStackRoot = forwardRef<HTMLDivElement, SharedCardStackProps>(
   },
 );
 
+const cardStackItem = 'contain-layout pli-2 plb-1 first-of-type:pbs-0 last-of-type:pbe-0';
+
+const CardStackItem = forwardRef<HTMLDivElement, SharedCardStackProps>(
+  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'div';
+    const rootProps = asChild
+      ? { classNames: [cardStackItem, classNames] }
+      : { className: mx(cardStackItem, classNames), role };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
 export const CardStack = {
   Root: CardStackRoot,
   Content: CardStackContent,
@@ -114,6 +130,7 @@ export const CardStack = {
   Heading: CardStackHeading,
   Footer: CardStackFooter,
   DragHandle: CardStackDragHandle,
+  Item: CardStackItem,
 };
 
-export { cardStackRoot, cardStackFooter, cardStackHeading, cardStackContent };
+export { cardStackRoot, cardStackFooter, cardStackHeading, cardStackContent, cardStackItem };