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

package/src/components/defs.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Edge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+
+import { type Size as DndSize } from '@dxos/react-ui-dnd';
+
+import { type Orientation, type Size } from './Stack';
+
+export type StackItemSize = DndSize;
+
+export type StackItemData = { id: string; type: 'column' | 'card' };
+
+export type StackItemRearrangeHandler<Data extends { id: string } = StackItemData> = (
+  source: Data,
+  target: Data,
+  closestEdge: Edge | null,
+) => void;
+
+export type StackContextValue = {
+  orientation: Orientation;
+  rail: boolean;
+  size: Size;
+  onRearrange?: StackItemRearrangeHandler;
+};

package/src/components/{LayoutControls.tsx → deprecated/LayoutControls.tsx}

@@ -4,17 +4,9 @@
 
 import React, { forwardRef } from 'react';
 
-import {
-  Button,
-  ButtonGroup,
-  type ButtonGroupProps,
-  type ButtonProps,
-  Icon,
-  Tooltip,
-  useTranslation,
-} from '@dxos/react-ui';
+import { ButtonGroup, type ButtonGroupProps, type ButtonProps, IconButton, useTranslation } from '@dxos/react-ui';
 
-import { translationKey } from '../translations';
+import { translationKey } from '../../translations';
 
 export type LayoutControlEvent = 'solo' | 'close' | `${'pin' | 'increment'}-${'start' | 'end'}`;
 export type LayoutControlHandler = (event: LayoutControlEvent) => void;
@@ -35,19 +27,7 @@ export type LayoutControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
 };
 
 const LayoutControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> & { label: string; icon: string }) => {
-  return (
-    <Tooltip.Root>
-      <Tooltip.Trigger asChild>
-        <Button variant='ghost' {...props}>
-          <span className='sr-only'>{label}</span>
-          <Icon icon={icon} />
-        </Button>
-      </Tooltip.Trigger>
-      <Tooltip.Portal>
-        <Tooltip.Content side='bottom'>{label}</Tooltip.Content>
-      </Tooltip.Portal>
-    </Tooltip.Root>
-  );
+  return <IconButton iconOnly icon={icon} label={label} tooltipSide='bottom' variant='ghost' {...props} />;
 };
 
 export const LayoutControls = forwardRef<HTMLDivElement, LayoutControlsProps>(

package/src/components/index.ts

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

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

@@ -0,0 +1,135 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// import '@dxos-theme';
+//
+// import React from 'react';
+//
+// import { faker } from '@dxos/random';
+// import { Input, ScrollArea } from '@dxos/react-ui';
+// import { modalSurface, mx } from '@dxos/react-ui-theme';
+// import { withTheme } from '@dxos/storybook-utils';
+//
+// import { Card } from './Card';
+//
+// faker.seed(1);
+//
+// // https://unsplash.com
+// // TODO(burdon): Use https://picsum.photos
+// const testImages = [
+//   'https://images.unsplash.com/photo-1616394158624-a2ba9cfe2994',
+//   'https://images.unsplash.com/photo-1507941097613-9f2157b69235',
+//   'https://images.unsplash.com/photo-1431274172761-fca41d930114',
+//   'https://images.unsplash.com/photo-1513635269975-59663e0ac1ad',
+//   'https://images.unsplash.com/photo-1564221710304-0b37c8b9d729',
+//   'https://images.unsplash.com/photo-1605425183435-25b7e99104a4',
+// ];
+//
+// const ReadonlyCardStory = () => {
+//   return (
+//     <div className='flex flex-col overflow-y-scroll'>
+//       <div className='flex flex-col gap-4'>
+//         <Card.Root item={{ id: 'readonly card story 1' }} data-flags='square noPadding'>
+//           <Card.Heading data-flags='floating'>
+//             <Card.DragHandle data-flags='positionLeft' />
+//             <Card.Menu data-flags='positionRight' />
+//           </Card.Heading>
+//           <Card.Media src={testImages[1]} />
+//         </Card.Root>
+//
+//         <Card.Root item={{ id: 'readonly card story 2' }}>
+//           <Card.Heading>
+//             <Card.HeadingLabel title={faker.lorem.sentence(3)} />
+//           </Card.Heading>
+//         </Card.Root>
+//
+//         <Card.Root item={{ id: 'readonly card story 3' }}>
+//           <Card.Content classNames={'text-sm font-thin h-[100px]'}>
+//             <ScrollArea.Root>
+//               <ScrollArea.Viewport>{faker.lorem.sentences(16)}</ScrollArea.Viewport>
+//               <ScrollArea.Scrollbar orientation='vertical'>
+//                 <ScrollArea.Thumb />
+//               </ScrollArea.Scrollbar>
+//             </ScrollArea.Root>
+//           </Card.Content>
+//         </Card.Root>
+//
+//         <Card.Root item={{ id: 'readonly card story 4' }}>
+//           <Card.Heading>
+//             <Card.HeadingLabel data-flags='center' title={faker.lorem.sentence(3)} />
+//           </Card.Heading>
+//           <Card.Content classNames={'text-sm font-thin'}>{faker.lorem.sentences(3)}</Card.Content>
+//         </Card.Root>
+//
+//         <Card.Root item={{ id: 'readonly card story 5' }}>
+//           <Card.Heading>
+//             <Card.DragHandle />
+//             <Card.HeadingLabel title={faker.lorem.sentence(8)} />
+//             {/* TODO(burdon): Menu util. */}
+//             <Card.Menu />
+//           </Card.Heading>
+//           <Card.Content data-flags='gutter' classNames={'gap-2 text-sm font-thin'}>
+//             <p>Content with gutter</p>
+//             <p className='line-clamp-3'>{faker.lorem.sentences(3)}</p>
+//           </Card.Content>
+//         </Card.Root>
+//
+//         <Card.Root item={{ id: 'readonly card story 6' }}>
+//           <Card.Heading>
+//             <Card.DragHandle />
+//             <Card.HeadingLabel title={faker.lorem.sentence(3)} />
+//             <Card.Menu />
+//           </Card.Heading>
+//           <Card.Content data-flags='gutter' classNames={'text-sm gap-2 font-thin'}>
+//             <p className='line-clamp-3'>{faker.lorem.sentences(1)}</p>
+//           </Card.Content>
+//           <Card.Media className={'h-[200px] grayscale'} src={testImages[0]} />
+//           <Card.Content data-flags='gutter' classNames={'text-sm gap-2 font-thin'}>
+//             <p className='line-clamp-3'>{faker.lorem.sentences(3)}</p>
+//           </Card.Content>
+//         </Card.Root>
+//       </div>
+//     </div>
+//   );
+// };
+//
+// const EditableCardStory = () => {
+//   return (
+//     <div className='flex flex-col h-full justify-center'>
+//       <Card.Root item={{ id: 'editable card story 1' }}>
+//         <Card.Heading>
+//           <Card.DragHandle />
+//           <Input.Root>
+//             <Input.TextInput classNames={'-mx-2 px-2'} variant='subdued' placeholder={'Title'} />
+//           </Input.Root>
+//           <Card.Menu />
+//         </Card.Heading>
+//         <Card.Content data-flags='gutter' classNames={'gap-2 text-sm font-thin'}>
+//           {faker.lorem.sentences()}
+//         </Card.Content>
+//       </Card.Root>
+//     </div>
+//   );
+// };
+//
+// export default {
+//   title: 'ui/react-ui-card/Card',
+//   component: Card,
+//   decorators: [
+//     withTheme,
+//     (Story: any) => (
+//       <div className={mx('flex h-screen w-full justify-center overflow-hidden', modalSurface)}>
+//         <div className='flex flex-col w-[360px] overflow-hidden'>
+//           <Story />
+//         </div>
+//       </div>
+//     ),
+//   ],
+//   parameters: {
+//     layout: 'fullscreen',
+//   },
+// };
+//
+// export const ReadOnly = () => <ReadonlyCardStory />;
+// export const Editable = () => <EditableCardStory />;

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 };