@dxos/react-ui-stack 0.8.2 → 0.8.3-main.672df60

package/src/exemplars/Card/Card.tsx

@@ -0,0 +1,178 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, {
+  type ComponentPropsWithoutRef,
+  type ComponentPropsWithRef,
+  type FC,
+  forwardRef,
+  type PropsWithChildren,
+} from 'react';
+
+import { Icon, IconButton, type ThemedClassName, Toolbar, type ToolbarRootProps, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import { cardChrome, cardContent, cardHeading, cardRoot, cardText } from './fragments';
+import { StackItem } from '../../components';
+import { translationKey } from '../../translations';
+
+type SharedCardProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & { asChild?: boolean };
+
+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>
+    );
+  },
+);
+
+const CardContent = 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 };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+/**
+ * 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
+ * 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')) {
+    return (
+      <div className={role === 'popover' ? 'popover-card-width' : role === 'card--kanban' ? 'contents' : ''}>
+        {children}
+      </div>
+    );
+  } else {
+    return <CardContent>{children}</CardContent>;
+  }
+};
+
+const CardHeading = forwardRef<HTMLDivElement, SharedCardProps>(
+  ({ children, classNames, asChild, role = 'heading', ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'div';
+    const rootProps = asChild
+      ? { classNames: [cardHeading, cardText, classNames] }
+      : { className: mx(cardHeading, cardText, classNames), role };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+const CardToolbar = forwardRef<HTMLDivElement, ToolbarRootProps>(({ children, ...props }, forwardedRef) => {
+  return (
+    <Toolbar.Root {...props} ref={forwardedRef}>
+      {children}
+    </Toolbar.Root>
+  );
+});
+
+const CardToolbarIconButton = Toolbar.IconButton;
+const CardToolbarSeparator = Toolbar.Separator;
+
+const CardDragHandle = forwardRef<HTMLButtonElement, { toolbarItem?: boolean }>(({ toolbarItem }, forwardedRef) => {
+  const { t } = useTranslation(translationKey);
+  const Root = toolbarItem ? Toolbar.IconButton : IconButton;
+  return (
+    <Root
+      iconOnly
+      icon='ph--dots-six-vertical--regular'
+      variant='ghost'
+      label={t('card drag handle label')}
+      classNames='pli-2'
+      ref={forwardedRef}
+    />
+  );
+});
+
+const CardDragPreview = StackItem.DragPreview;
+
+const CardMenu = Primitive.div as FC<ComponentPropsWithRef<'div'>>;
+
+type CardPosterProps = {
+  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} />
+    );
+  }
+  if (props.icon) {
+    return (
+      <div
+        role='image'
+        className={`dx-card__poster grid ${aspect} place-items-center bg-inputSurface text-subdued`}
+        aria-label={props.alt}
+      >
+        <Icon icon={props.icon} size={10} />
+      </div>
+    );
+  }
+};
+
+const CardChrome = forwardRef<HTMLDivElement, SharedCardProps>(
+  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'div';
+    const rootProps = asChild
+      ? { classNames: [cardChrome, classNames] }
+      : { className: mx(cardChrome, classNames), role };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+const CardText = forwardRef<HTMLParagraphElement, SharedCardProps>(
+  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'p';
+    const rootProps = asChild ? { classNames: [cardText, classNames] } : { className: mx(cardText, classNames), role };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+export const Card = {
+  Root: CardRoot,
+  Content: CardContent,
+  Container: CardConditionalContent,
+  Heading: CardHeading,
+  Toolbar: CardToolbar,
+  ToolbarIconButton: CardToolbarIconButton,
+  ToolbarSeparator: CardToolbarSeparator,
+  DragHandle: CardDragHandle,
+  DragPreview: CardDragPreview,
+  Menu: CardMenu,
+  Poster: CardPoster,
+  Chrome: CardChrome,
+  Text: CardText,
+};
+
+export { cardRoot, cardContent, cardHeading, cardText, cardChrome };

package/src/exemplars/Card/CardDragPreview.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { mx } from '@dxos/react-ui-theme';
+
+import { cardContent } 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>;
+};
+
+export const CardDragPreview = {
+  Root: CardDragPreviewRoot,
+  Content: CardDragPreviewContent,
+};

package/src/exemplars/Card/fragments.ts

@@ -0,0 +1,14 @@
+//
+// 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 =
+  '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 cardText = 'pli-3 mlb-3';
+
+export const cardHeading = 'text-lg font-medium line-clamp-2';
+
+export const cardChrome = 'pli-1.5 mlb-1.5 [&_.dx-button]:pli-1.5 [&_.dx-button]:text-start [&_.dx-button]:is-full';

package/src/exemplars/Card/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './Card';
+export * from './CardDragPreview';

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

@@ -0,0 +1,80 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// type CardData = {
+//   id: string;
+//   title: string;
+//   body: string;
+//   image?: string;
+// };
+
+// const DraggableCard: FC<{ data: CardData; onDelete: (id: string) => void }> = ({ data, onDelete }) => {
+//   const { id, title, body, image } = data;
+//   const { attributes, listeners, setNodeRef, transform } = useSortable({ id });
+//   const t = transform ? Object.assign(transform, { scaleY: 1 }) : null;
+//
+//   return (
+//     <Card.Root ref={setNodeRef} item={data} style={{ transform: CSS.Transform.toString(t) }}>
+//       <Card.Heading>
+//         <Card.DragHandle {...listeners} {...attributes} />
+//         <Card.Title title={title} />
+//         <DropdownMenu.Root>
+//           <DropdownMenu.Trigger asChild>
+//             <Card.Menu />
+//           </DropdownMenu.Trigger>
+//           <DropdownMenu.Content>
+//             <DropdownMenu.Viewport>
+//               <DropdownMenu.Item onClick={() => onDelete(id)}>Delete</DropdownMenu.Item>
+//             </DropdownMenu.Viewport>
+//           </DropdownMenu.Content>
+//         </DropdownMenu.Root>
+//       </Card.Heading>
+//       <Card.Content classNames={'text-sm'} gutter>
+//         <p>{body}</p>
+//       </Card.Content>
+//       {image && <Card.Media src={image} classNames={'h-[160px]'} />}
+//     </Card.Root>
+//   );
+// };
+//
+// const DraggableStory: FC<PropsWithChildren> = ({ children }) => {
+//   const [cards, setCards] = useState<CardData[]>(
+//     Array.from({ length: 7 }).map(() => ({
+//       id: faker.string.uuid(),
+//       title: faker.lorem.sentence(3),
+//       body: faker.lorem.sentences(),
+//       image: faker.datatype.boolean() ? faker.helpers.arrayElement(testImages) : undefined,
+//     })),
+//   );
+//
+//   const handleDelete = (id: string) => {
+//     setCards((cards) => cards.filter((card) => card.id !== id));
+//   };
+//
+//   const handleDragEnd = (event: DragEndEvent) => {
+//     const { active, over } = event;
+//     if (active.id !== over?.id) {
+//       setCards((cards) => {
+//         const oldIndex = cards.findIndex((card) => card.id === active.id);
+//         const newIndex = cards.findIndex((card) => card.id === over?.id);
+//         return arrayMove(cards, oldIndex, newIndex);
+//       });
+//     }
+//   };
+//
+//   return (
+//     <DndContext onDragEnd={handleDragEnd}>
+//       <SortableContext items={cards.map(({ id }) => id)} strategy={verticalListSortingStrategy}>
+//         <div className='flex flex-col overflow-y-scroll'>
+//           <div className='flex flex-col gap-4'>
+//             {cards.map((card) => (
+//               <DraggableCard key={card.id} data={card} onDelete={handleDelete} />
+//             ))}
+//           </div>
+//         </div>
+//       </SortableContext>
+//     </DndContext>
+//   );
+// };
+// export const Draggable = () => <DraggableStory />;

package/src/exemplars/CardStack/CardStack.tsx

@@ -0,0 +1,118 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Slot } from '@radix-ui/react-slot';
+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 { Card } from '../Card';
+
+type SharedCardStackProps = ThemedClassName<ComponentPropsWithoutRef<'div'>> & { asChild?: boolean };
+
+const CardStackStack = forwardRef<
+  HTMLDivElement,
+  Omit<StackProps, 'orientation' | 'size' | 'rail' | 'separatorOnScroll'>
+>(({ children, classNames, itemsCount = 0, ...props }, forwardedRef) => {
+  return (
+    <Stack
+      orientation='vertical'
+      size='contain'
+      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]
+      }
+      itemsCount={itemsCount}
+      separatorOnScroll={9}
+      {...props}
+      ref={forwardedRef}
+    >
+      {children}
+    </Stack>
+  );
+});
+
+const CardStackDragHandle = Card.DragHandle;
+
+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: [cardStackHeading, classNames] }
+      : { className: mx(cardStackHeading, classNames), role };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+const cardStackFooter =
+  'plb-2 mli-2 border-bs border-transparent [[data-scroll-separator-end="true"]_&]:border-subduedSeparator';
+
+const CardStackFooter = forwardRef<HTMLDivElement, SharedCardStackProps>(
+  ({ children, classNames, asChild, role = 'none', ...props }, forwardedRef) => {
+    const Root = asChild ? Slot : 'div';
+    const rootProps = asChild
+      ? { classNames: [cardStackFooter, classNames] }
+      : { className: mx(cardStackFooter, classNames), role };
+    return (
+      <Root {...props} {...rootProps} ref={forwardedRef}>
+        {children}
+      </Root>
+    );
+  },
+);
+
+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>
+    );
+  },
+);
+
+const cardStackRoot = 'flex flex-col pli-2 plb-2';
+
+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>
+    );
+  },
+);
+
+export const CardStack = {
+  Root: CardStackRoot,
+  Content: CardStackContent,
+  Stack: CardStackStack,
+  Heading: CardStackHeading,
+  Footer: CardStackFooter,
+  DragHandle: CardStackDragHandle,
+};
+
+export { cardStackRoot, cardStackFooter, cardStackHeading, cardStackContent };

package/src/exemplars/CardStack/CardStackDragPreview.tsx

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { IconButton, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import { type StackProps } from '../../components';
+import { translationKey } from '../../translations';
+
+const CardStackDragPreviewRoot = ({ children }: PropsWithChildren<{}>) => {
+  return (
+    <div className='p-2'>
+      <div className='rounded-md max-bs-[calc(100dvh-1rem)] overflow-hidden bg-baseSurface border border-separator ring-focusLine ring-neutralFocusIndicator flex flex-col'>
+        {children}
+      </div>
+    </div>
+  );
+};
+
+const CardStackDragPreviewHeading = ({ children }: PropsWithChildren<{}>) => {
+  const { t } = useTranslation(translationKey);
+  return (
+    <div className='flex items-center p-2'>
+      <IconButton
+        iconOnly
+        icon='ph--dots-six-vertical--regular'
+        variant='ghost'
+        label={t('column drag handle label')}
+        classNames='pli-2'
+      />
+      {children}
+    </div>
+  );
+};
+
+const CardStackDragPreviewContent = ({
+  children,
+  itemsCount = 0,
+}: PropsWithChildren<Pick<StackProps, 'itemsCount'>>) => {
+  return (
+    <div
+      className={mx('overflow-y-auto flex-1 pli-2 flex flex-col gap-2', 'plb-1', itemsCount > 0 ? 'plb-2' : 'plb-1')}
+    >
+      {children}
+    </div>
+  );
+};
+
+const CardStackDragPreviewFooter = ({ children }: PropsWithChildren<{}>) => {
+  return <div className='p-2 border-t border-separator'>{children}</div>;
+};
+
+export const CardStackDragPreview = {
+  Root: CardStackDragPreviewRoot,
+  Heading: CardStackDragPreviewHeading,
+  Content: CardStackDragPreviewContent,
+  Footer: CardStackDragPreviewFooter,
+};

package/src/exemplars/CardStack/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './CardStack';
+export * from './CardStackDragPreview';

package/src/exemplars/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './Card';
+export * from './CardStack';

package/src/hooks/useStackDropForElements.ts

@@ -16,12 +16,14 @@ import { type StackItemRearrangeHandler, type StackItemData, type Orientation }
 export const useStackDropForElements = ({
   id,
   element,
+  scrollElement = element,
   selfDroppable,
   orientation,
   onRearrange,
 }: {
   id?: string;
   element: HTMLDivElement | null;
+  scrollElement?: HTMLDivElement | null;
   selfDroppable: boolean;
   orientation: Orientation;
   onRearrange?: StackItemRearrangeHandler;
@@ -64,9 +66,9 @@ export const useStackDropForElements = ({
           }
         },
       }),
-      autoScrollForElements({ element, getAllowedAxis: () => orientation }),
+      autoScrollForElements({ element: scrollElement as Element, getAllowedAxis: () => orientation }),
     );
-  }, [element, selfDroppable, orientation, id, onRearrange]);
+  }, [element, scrollElement, selfDroppable, orientation, id, onRearrange]);
 
   return { dropping };
 };

package/src/index.ts

@@ -3,4 +3,8 @@
 //
 
 export * from './components';
+
+// TODO(thure): Consider exporting exemplars from separate endpoints.
+export * from './exemplars';
+
 export { default as translations } from './translations';

package/src/translations.ts

@@ -9,6 +9,7 @@ export default [
     'en-US': {
       [translationKey]: {
         'resize label': 'Drag to resize',
+        'drag handle label': 'Drag to rearrange',
         'pin start label': 'Pin to the left sidebar',
         'pin end label': 'Pin to the right sidebar',
         'increment start label': 'Move to the left',