@dxos/react-ui-stack 0.8.4-main.3a94e84 → 0.8.4-main.3c1ae3b

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,42 @@
 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) => {
+/**
+ * Use this when ....
+ */
+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,44 +48,45 @@ 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,
-  classNames,
-}: ThemedClassName<PropsWithChildren<{ role?: string }>>) => {
-  if (['card--popover', 'card--intrinsic', 'card--extrinsic'].includes(role)) {
-    return (
-      <div
-        className={mx(
-          role === 'card--popover'
-            ? 'popover-card-width'
-            : ['card--intrinsic', 'card--extrinsic'].includes(role)
-              ? 'contents'
-              : '',
-          classNames,
-        )}
-      >
-        {children}
-      </div>
-    );
-  } else {
-    return (
-      <CardStaticRoot
-        classNames={[
-          role === 'card--transclusion' && 'mlb-[1em]',
-          role === 'card--transclusion' && hoverableControls,
-          classNames,
-        ]}
-      >
-        {children}
-      </CardStaticRoot>
-    );
-  }
-};
+const CardSurfaceRoot = forwardRef<HTMLDivElement, ThemedClassName<PropsWithChildren<{ id?: string; role?: string }>>>(
+  ({ id, role = 'never', children, classNames }, forwardedRef) => {
+    if (['card--popover', 'card--intrinsic', 'card--extrinsic'].includes(role)) {
+      return (
+        <div
+          {...(id && { 'data-object-id': id })}
+          className={mx(
+            role === 'card--popover'
+              ? 'popover-card-width'
+              : ['card--intrinsic', 'card--extrinsic'].includes(role)
+                ? 'contents'
+                : '',
+            classNames,
+          )}
+          ref={forwardedRef}
+        >
+          {children}
+        </div>
+      );
+    } else {
+      return (
+        <CardStaticRoot
+          id={id}
+          classNames={[
+            role === 'card--transclusion' && 'mlb-1',
+            role === 'card--transclusion' && hoverableControls,
+            classNames,
+          ]}
+          ref={forwardedRef}
+        >
+          {children}
+        </CardStaticRoot>
+      );
+    }
+  },
+);
 
 const CardHeading = forwardRef<HTMLDivElement, SharedCardProps>(
   ({ children, classNames, asChild, role = 'heading', ...props }, forwardedRef) => {
@@ -117,23 +132,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} />
@@ -156,9 +174,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}>
@@ -183,4 +201,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 = {
@@ -96,7 +94,7 @@ const CardStackStory = () => {
 
   return (
     <CardStack.Root classNames='is-96'>
-      <CardStack.Content>
+      <CardStack.Content footer>
         <CardStack.Stack id='story column' onRearrange={handleRearrange} itemsCount={column.length}>
           {column.map((card, cardIndex, cardsArray) => {
             const cardItem = { id: card.id, type: 'card' as const };
@@ -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,15 +8,72 @@ 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 };
+//
+// Root
+//
+
+const cardStackRoot = 'flex flex-col';
+
+// TODO(burdon): Root should be headless.
+const CardStackRoot = forwardRef<HTMLDivElement, SharedCardStackProps>(
+  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'div';
+    const rootProps = asChild
+      ? { classNames: [cardStackRoot, classNames] }
+      : { className: mx(cardStackRoot, classNames), role };
+
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+//
+// Content
+// TODO(burdon): Rename Viewport (should be the component that scrolls).
+//
+
+const cardStackContent = 'shrink min-bs-0 grid dx-focus-ring-group-x-indicator bg-baseSurface';
+
+type CardStackContentProps = SharedCardStackProps & {
+  footer?: boolean;
+};
+
+const CardStackContent = forwardRef<HTMLDivElement, CardStackContentProps>(
+  ({ children, classNames, asChild, role = 'none', footer, ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'div';
+    const baseClassNames = footer ? [cardStackContent, railGridHorizontalContainFitContent] : [cardStackContent];
+    const rootProps = asChild
+      ? { classNames: [...baseClassNames, classNames] }
+      : { className: mx(...baseClassNames, classNames), role };
+
+    return (
+      <Root {...props} {...rootProps} data-scroll-separator='false' ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+//
+// Stack
+// TODO(burdon): Rename Content.
+//
+
+type SharedCardStackProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & {
+  asChild?: boolean;
+};
 
 const CardStackStack = forwardRef<
   HTMLDivElement,
   Omit<StackProps, 'orientation' | 'size' | 'rail' | 'separatorOnScroll'>
 >(({ children, classNames, itemsCount = 0, ...props }, forwardedRef) => {
+  // NOTE: Should not have horizontal padding since separatorOnScroll should be full width.
   return (
     <Stack
       orientation='vertical'
@@ -24,7 +81,7 @@ const CardStackStack = forwardRef<
       rail={false}
       classNames={
         /* NOTE(thure): Do not let this element have zero intrinsic size, otherwise the drop indicator will not display. See #9035. */
-        ['plb-1', itemsCount > 0 && 'plb-2', classNames]
+        ['plb-2', classNames]
       }
       itemsCount={itemsCount}
       separatorOnScroll={9}
@@ -37,16 +94,19 @@ const CardStackStack = forwardRef<
   );
 });
 
-const CardStackDragHandle = Card.DragHandle;
+//
+// Item
+//
 
-const cardStackHeading = 'mli-2 order-first bg-transparent rounded-bs-md flex items-center';
+const cardStackItem = 'contain-layout pli-2 plb-1 first-of-type:pbs-0 last-of-type:pbe-0';
 
-const CardStackHeading = forwardRef<HTMLDivElement, SharedCardStackProps>(
-  ({ children, classNames, asChild, role = 'heading', ...props }, forwardedRef) => {
+const CardStackItem = forwardRef<HTMLDivElement, SharedCardStackProps>(
+  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
     const Root = asChild ? Slot : 'div';
     const rootProps = asChild
-      ? { classNames: [cardStackHeading, classNames] }
-      : { className: mx(cardStackHeading, classNames), role };
+      ? { classNames: [cardStackItem, classNames] }
+      : { className: mx(cardStackItem, classNames), role };
+
     return (
       <Root {...props} {...rootProps} ref={forwardedRef}>
         {children}
@@ -55,15 +115,19 @@ const CardStackHeading = forwardRef<HTMLDivElement, SharedCardStackProps>(
   },
 );
 
-const cardStackFooter =
-  'plb-2 mli-2 border-bs border-transparent [[data-scroll-separator-end="true"]_&]:border-subduedSeparator';
+//
+// Heading
+//
 
-const CardStackFooter = forwardRef<HTMLDivElement, SharedCardStackProps>(
-  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+const cardStackHeading = 'mli-2 order-first bg-transparent rounded-bs-md flex items-center';
+
+const CardStackHeading = forwardRef<HTMLDivElement, SharedCardStackProps>(
+  ({ children, classNames, asChild, role = 'heading', ...props }, forwardedRef) => {
     const Root = asChild ? Slot : 'div';
     const rootProps = asChild
-      ? { classNames: [cardStackFooter, classNames] }
-      : { className: mx(cardStackFooter, classNames), role };
+      ? { classNames: [cardStackHeading, classNames] }
+      : { className: mx(cardStackHeading, classNames), role };
+
     return (
       <Root {...props} {...rootProps} ref={forwardedRef}>
         {children}
@@ -72,33 +136,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 = forwardRef<HTMLDivElement, SharedCardStackProps>(
-  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
-    const Root = asChild ? Slot : 'div';
-    const rootProps = asChild
-      ? { classNames: [...cardStackContent, classNames] }
-      : { className: mx(...cardStackContent, classNames), role };
-    return (
-      <Root {...props} {...rootProps} data-scroll-separator='false' ref={forwardedRef}>
-        {children}
-      </Root>
-    );
-  },
-);
+//
+// Footer
+//
 
-const cardStackRoot = 'flex flex-col pli-2 plb-2';
+const cardStackFooter =
+  'plb-2 mli-2 border-bs border-transparent [[data-scroll-separator-end="true"]_&]:border-subduedSeparator';
 
-const CardStackRoot = forwardRef<HTMLDivElement, SharedCardStackProps>(
+const CardStackFooter = forwardRef<HTMLDivElement, SharedCardStackProps>(
   ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
     const Root = asChild ? Slot : 'div';
     const rootProps = asChild
-      ? { classNames: [cardStackRoot, classNames] }
-      : { className: mx(cardStackRoot, classNames), role };
+      ? { classNames: [cardStackFooter, classNames] }
+      : { className: mx(cardStackFooter, classNames), role };
+
     return (
       <Root {...props} {...rootProps} ref={forwardedRef}>
         {children}
@@ -107,21 +158,15 @@ const CardStackRoot = forwardRef<HTMLDivElement, SharedCardStackProps>(
   },
 );
 
-const cardStackItem = 'contain-layout pli-2 plb-1 first-of-type:pbs-0 last-of-type:pbe-0';
+//
+// DragHandle
+//
 
-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>
-    );
-  },
-);
+const CardStackDragHandle = Card.DragHandle;
+
+//
+// CardStack
+//
 
 export const CardStack = {
   Root: CardStackRoot,