@dxos/react-ui-stack 0.8.4-main.f9ba587 → 0.8.4-main.fffef41

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

@@ -2,17 +2,14 @@
 // 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 { withTheme } from '@dxos/react-ui/testing';
 
 import { Card } from './Card';
 
-// Set a seed for reproducible random values
 faker.seed(0);
 
 type CardStoryProps = {
@@ -23,44 +20,8 @@ type CardStoryProps = {
   showIcon: boolean;
 };
 
-const meta: Meta<CardStoryProps> = {
-  title: 'ui/react-ui-stack/Card',
-  decorators: [withTheme],
-  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)',
-    },
-  },
-  args: {
-    title: faker.commerce.productName(),
-    description: faker.lorem.paragraph(),
-    image: faker.image.url(),
-    showImage: true,
-    showIcon: true,
-  },
-};
-
-export default meta;
-
-export const Default: StoryObj<CardStoryProps> = {
-  render: ({ title, description, image, showImage, showIcon }: CardStoryProps) => (
+const DefaultStory = ({ title, description, image, showImage, showIcon }: CardStoryProps) => {
+  return (
     <div className='max-is-md'>
       <Card.StaticRoot>
         <Card.Toolbar>
@@ -74,5 +35,30 @@ export const Default: StoryObj<CardStoryProps> = {
         {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',
+  },
+} 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,28 +5,39 @@
 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 { cardMinInlineSize, hoverableControls, mx } from '@dxos/react-ui-theme';
 
-import { cardChrome, cardRoot, cardHeading, cardText, cardSpacing } from './fragments';
-import { StackItem } from '../../components';
+import { Image, StackItem } from '../../components';
 import { translationKey } from '../../translations';
 
+import { cardChrome, cardHeading, cardRoot, cardSpacing, cardText } from './fragments';
+
+/**
+ * The default width of cards. It should be no larger than 320px per WCAG 2.1 SC 1.4.10.
+ */
+const cardDefaultInlineSize = cardMinInlineSize;
+
+/**
+ * This is `cardDefaultInlineSize` plus 2 times the sum of the inner and outer spacing applied by CardStack on the inline axis.
+ */
+const cardStackDefaultInlineSizeRem = cardDefaultInlineSize + 2.125;
+
 type SharedCardProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & { asChild?: boolean };
 
-const CardStaticRoot = forwardRef<HTMLDivElement, SharedCardProps>(
-  ({ children, classNames, asChild, role = 'group', ...props }, forwardedRef) => {
+const CardStaticRoot = forwardRef<HTMLDivElement, SharedCardProps & { id?: string }>(
+  ({ children, classNames, id, asChild, role = 'group', ...props }, forwardedRef) => {
     const Root = asChild ? Slot : 'div';
     const rootProps = asChild ? { classNames: [cardRoot, classNames] } : { className: mx(cardRoot, classNames), role };
     return (
-      <Root {...props} {...rootProps} ref={forwardedRef}>
+      <Root {...(id && { 'data-object-id': id })} {...props} {...rootProps} ref={forwardedRef}>
         {children}
       </Root>
     );
@@ -34,20 +45,41 @@ const CardStaticRoot = 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.StaticRoot` by default, otherwise
- * it will render a `div` primitive with the appropriate styling for specific handled situations.
+ * 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.StaticRoot` by default, otherwise it will render a `div` primitive with the appropriate styling for specific handled situations.
  */
-const CardSurfaceRoot = ({ role = 'never', children }: PropsWithChildren<{ role?: string }>) => {
-  if (['popover', 'card--kanban'].includes(role)) {
+const CardSurfaceRoot = ({
+  id,
+  role = 'never',
+  children,
+  classNames,
+}: ThemedClassName<PropsWithChildren<{ id?: string; role?: string }>>) => {
+  if (['card--popover', 'card--intrinsic', 'card--extrinsic'].includes(role)) {
     return (
-      <div className={role === 'popover' ? 'popover-card-width' : role === 'card--kanban' ? 'contents' : ''}>
+      <div
+        {...(id && { 'data-object-id': id })}
+        className={mx(
+          role === 'card--popover'
+            ? 'popover-card-width'
+            : ['card--intrinsic', 'card--extrinsic'].includes(role)
+              ? 'contents'
+              : '',
+          classNames,
+        )}
+      >
         {children}
       </div>
     );
   } else {
     return (
-      <CardStaticRoot {...(role === 'card--document' && { classNames: ['mlb-[1em]', hoverableControls] })}>
+      <CardStaticRoot
+        id={id}
+        classNames={[
+          role === 'card--transclusion' && 'mlb-1',
+          role === 'card--transclusion' && hoverableControls,
+          classNames,
+        ]}
+      >
         {children}
       </CardStaticRoot>
     );
@@ -98,23 +130,26 @@ const CardDragPreview = StackItem.DragPreview;
 
 const CardMenu = Primitive.div as FC<ComponentPropsWithRef<'div'>>;
 
-type CardPosterProps = {
-  alt: string;
-  aspect?: 'video' | 'auto';
-} & Partial<{ image: string; icon: string }>;
+type CardPosterProps = ThemedClassName<
+  {
+    alt: string;
+    aspect?: 'video' | 'auto';
+  } & Partial<{ image: string; icon: string }>
+>;
 
 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} />
+      <Image classNames={[`dx-card__poster is-full`, aspect, props.classNames]} 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, props.classNames)}
         aria-label={props.alt}
       >
         <Icon icon={props.icon} size={10} />
@@ -137,9 +172,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,4 +199,12 @@ export const Card = {
   Text: CardText,
 };
 
-export { cardRoot, cardHeading, cardText, cardChrome, cardSpacing };
+export {
+  cardRoot,
+  cardHeading,
+  cardText,
+  cardChrome,
+  cardSpacing,
+  cardStackDefaultInlineSizeRem,
+  cardDefaultInlineSize,
+};

package/src/exemplars/Card/fragments.ts

@@ -6,6 +6,7 @@ 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';
@@ -17,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

@@ -2,21 +2,19 @@
 // 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, { useState, useCallback } from 'react';
+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 { withTheme } from '@dxos/react-ui/testing';
 
-import { CardStack } from './CardStack';
 import { StackItem } from '../../components';
 import { Card, CardDragPreview } from '../Card';
 
-// Set a seed for reproducible random values
+import { CardStack } from './CardStack';
+
 faker.seed(0);
 
 type CardItem = {
@@ -130,7 +128,7 @@ const CardStackStory = () => {
                     <Card.Text classNames='line-clamp-2'>{card.description}</Card.Text>
                   </Card.StaticRoot>
                   <StackItem.DragPreview>
-                    {({ item }) => (
+                    {() => (
                       <CardDragPreview.Root>
                         <CardDragPreview.Content>
                           <Card.Toolbar>
@@ -159,11 +157,14 @@ const CardStackStory = () => {
   );
 };
 
-const meta: Meta<typeof CardStackStory> = {
+const meta = {
   title: 'ui/react-ui-stack/CardStack',
   component: CardStackStory,
-  decorators: [withTheme, withLayout({ fullscreen: true })],
-};
+  decorators: [withTheme],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof CardStackStory>;
 
 export default meta;
 

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 };
@@ -72,17 +72,20 @@ const CardStackFooter = forwardRef<HTMLDivElement, SharedCardStackProps>(
   },
 );
 
-const cardStackContent = [
-  'shrink min-bs-0 bg-baseSurface border border-separator rounded-md grid dx-focus-ring-group-x-indicator kanban-drop',
-  railGridHorizontalContainFitContent,
-];
+const cardStackContent =
+  'shrink min-bs-0 bg-baseSurface border border-separator rounded-md grid dx-focus-ring-group-x-indicator kanban-drop';
 
-const CardStackContent = forwardRef<HTMLDivElement, SharedCardStackProps>(
-  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+type CardStackContentProps = SharedCardStackProps & {
+  footer?: boolean;
+};
+
+const CardStackContent = forwardRef<HTMLDivElement, CardStackContentProps>(
+  ({ children, classNames, asChild, role = 'none', footer = true, ...props }, forwardedRef) => {
     const Root = asChild ? Slot : 'div';
+    const baseClassNames = footer ? [cardStackContent, railGridHorizontalContainFitContent] : [cardStackContent];
     const rootProps = asChild
-      ? { classNames: [...cardStackContent, classNames] }
-      : { className: mx(...cardStackContent, classNames), role };
+      ? { classNames: [...baseClassNames, classNames] }
+      : { className: mx(...baseClassNames, classNames), role };
     return (
       <Root {...props} {...rootProps} data-scroll-separator='false' ref={forwardedRef}>
         {children}

package/src/hooks/useStackDropForElements.ts

@@ -8,7 +8,9 @@ import { autoScrollForElements } from '@atlaskit/pragmatic-drag-and-drop-auto-sc
 import { attachClosestEdge, extractClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
 import { useLayoutEffect, useState } from 'react';
 
-import { type StackItemRearrangeHandler, type StackItemData, type Orientation } from '../components';
+import { type Orientation, type StackItemData, type StackItemRearrangeHandler } from '../components';
+
+const noop = () => {};
 
 /**
  * Hook to handle drag and drop functionality for Stack components.
@@ -17,59 +19,64 @@ export const useStackDropForElements = ({
   id,
   element,
   scrollElement = element,
-  selfDroppable,
   orientation,
+  selfDroppable,
   onRearrange,
 }: {
   id?: string;
   element: HTMLDivElement | null;
   scrollElement?: HTMLDivElement | null;
-  selfDroppable: boolean;
   orientation: Orientation;
+  selfDroppable: boolean;
   onRearrange?: StackItemRearrangeHandler;
 }) => {
   const [dropping, setDropping] = useState(false);
 
   useLayoutEffect(() => {
-    if (!element || !selfDroppable) {
+    if (!element) {
       return;
     }
 
     const acceptSourceType = orientation === 'horizontal' ? 'column' : 'card';
 
     return combine(
-      dropTargetForElements({
-        element,
-        getData: ({ input, element }) => {
-          return attachClosestEdge(
-            { id, type: orientation === 'horizontal' ? 'card' : 'column' },
-            { input, element, allowedEdges: [orientation === 'horizontal' ? 'left' : 'top'] },
-          );
-        },
-        onDragEnter: ({ source }) => {
-          if (source.data.type === acceptSourceType) {
-            setDropping(true);
-          }
-        },
-        onDrag: ({ source }) => {
-          if (source.data.type === acceptSourceType) {
-            setDropping(true);
-          }
-        },
-        onDragLeave: () => {
-          return setDropping(false);
-        },
-        onDrop: ({ self, source }) => {
-          setDropping(false);
-          if (source.data.type === acceptSourceType && selfDroppable && onRearrange) {
-            onRearrange(source.data as StackItemData, self.data as StackItemData, extractClosestEdge(self.data));
-          }
-        },
-      }),
-      autoScrollForElements({
-        element: scrollElement as Element,
-        getAllowedAxis: () => orientation,
-      }),
+      selfDroppable
+        ? dropTargetForElements({
+            element,
+            getData: ({ input, element }) => {
+              return attachClosestEdge(
+                { id, type: orientation === 'horizontal' ? 'card' : 'column' },
+                { input, element, allowedEdges: [orientation === 'horizontal' ? 'left' : 'top'] },
+              );
+            },
+            onDragEnter: ({ source }) => {
+              if (source.data.type === acceptSourceType) {
+                setDropping(true);
+              }
+            },
+            onDrag: ({ source }) => {
+              if (source.data.type === acceptSourceType) {
+                setDropping(true);
+              }
+            },
+            onDragLeave: () => {
+              return setDropping(false);
+            },
+            onDrop: ({ self, source }) => {
+              setDropping(false);
+              if (source.data.type === acceptSourceType && selfDroppable && onRearrange) {
+                onRearrange(source.data as StackItemData, self.data as StackItemData, extractClosestEdge(self.data));
+              }
+            },
+          })
+        : noop,
+
+      scrollElement
+        ? autoScrollForElements({
+            element: scrollElement,
+            getAllowedAxis: () => orientation,
+          })
+        : noop,
     );
   }, [element, scrollElement, selfDroppable, orientation, id, onRearrange]);
 

package/src/playwright/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './stack-manager';

package/src/playwright/smoke.spec.ts

@@ -6,7 +6,7 @@ import { expect, test } from '@playwright/test';
 
 import { setupPage, storybookUrl } from '@dxos/test-utils/playwright';
 
-import { StackManager } from '../testing';
+import { StackManager } from './stack-manager';
 
 const PORT = 9003;
 

package/src/testing/CardContainer.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { ExtrinsicCardContainer, IntrinsicCardContainer, PopoverCardContainer } from '@dxos/storybook-utils';
+
+import { Card } from '../exemplars';
+
+export const CardContainer = ({
+  children,
+  icon = 'ph--placeholder--regular',
+  role,
+}: PropsWithChildren<{ icon?: string; role?: string }>) => {
+  switch (role) {
+    case 'card--popover':
+      return <PopoverCardContainer icon={icon}>{children}</PopoverCardContainer>;
+
+    case 'card--extrinsic':
+      return (
+        <ExtrinsicCardContainer>
+          <Card.StaticRoot>{children}</Card.StaticRoot>
+        </ExtrinsicCardContainer>
+      );
+
+    case 'card--intrinsic':
+      return (
+        <IntrinsicCardContainer>
+          <Card.StaticRoot>{children}</Card.StaticRoot>
+        </IntrinsicCardContainer>
+      );
+
+    default:
+      return <Card.StaticRoot>{children}</Card.StaticRoot>;
+  }
+};

package/src/testing/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './stack-manager';
+export * from './CardContainer';

package/dist/types/src/testing/stack-manager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"stack-manager.d.ts","sourceRoot":"","sources":["../../../../src/testing/stack-manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,kBAAkB,CAAC;AAEtD,qBAAa,YAAY;IAGX,QAAQ,CAAC,OAAO,EAAE,OAAO;IAFrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;gBAER,OAAO,EAAE,OAAO;IAIrC,QAAQ,IAAI,OAAO;IAInB,KAAK;IAIL,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;CAGvC;AAED,qBAAa,cAAc;IAGb,QAAQ,CAAC,OAAO,EAAE,OAAO;IAFrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;gBAER,OAAO,EAAE,OAAO;IAI/B,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI5B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAKvB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,GAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CAehG"}