@dxos/react-ui-stack 0.8.4-main.e098934 → 0.8.4-main.e8ec1fe

package/src/components/StackItem/StackItem.stories.tsx

@@ -2,19 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { DropdownMenu, Icon } from '@dxos/react-ui';
-import { withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
 import { StackItem, type StackItemRootProps } from './StackItem';
 
 const DefaultStory = (props: StackItemRootProps) => {
   return (
-    <StackItem.Root role='section' {...props} classNames='w-[20rem] border border-separator'>
+    <StackItem.Root role='section' {...props} classNames='is-[20rem] border border-separator'>
       <StackItem.Heading>
         <span className='sr-only'>Title</span>
         <div role='none' className='sticky -block-start-px bg-[--sticky-bg] p-1 is-full'>
@@ -27,7 +25,7 @@ const DefaultStory = (props: StackItemRootProps) => {
           </DropdownMenu.Root>
         </div>
       </StackItem.Heading>
-      <StackItem.Content classNames='p-2'>Content</StackItem.Content>
+      <StackItem.Content>Content</StackItem.Content>
     </StackItem.Root>
   );
 };

package/src/components/StackItem/StackItem.tsx

@@ -63,7 +63,7 @@ type StackItemRootProps = ThemedClassName<ComponentPropsWithRef<'div'>> & {
   onSizeChange?: (nextSize: StackItemSize) => void;
   role?: 'article' | 'section';
   disableRearrange?: boolean;
-  focusIndicatorVariant?: 'over-all' | 'group';
+  focusIndicatorVariant?: 'over-all' | 'group' | 'over-all-always' | 'group-always';
 };
 
 const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
@@ -232,15 +232,22 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
             'group/stack-item grid relative',
             focusIndicatorVariant === 'over-all'
               ? 'dx-focus-ring-inset-over-all'
-              : orientation === 'horizontal'
-                ? 'dx-focus-ring-group-x'
-                : 'dx-focus-ring-group-y',
+              : focusIndicatorVariant === 'over-all-always'
+                ? 'dx-focus-ring-inset-over-all-always'
+                : orientation === 'horizontal'
+                  ? focusIndicatorVariant === 'group-always'
+                    ? 'dx-focus-ring-group-x-always'
+                    : 'dx-focus-ring-group-x'
+                  : focusIndicatorVariant === 'group-always'
+                    ? 'dx-focus-ring-group-y-always'
+                    : 'dx-focus-ring-group-y',
             orientation === 'horizontal' ? 'grid-rows-subgrid' : 'grid-cols-subgrid',
             rail && (orientation === 'horizontal' ? 'row-span-2' : 'col-span-2'),
             role === 'section' && orientation !== 'horizontal' && 'border-be border-subduedSeparator',
             classNames,
           )}
           data-dx-stack-item={stackId}
+          data-dx-item-id={item.id}
           {...resizeAttributes}
           style={{
             ...(stackSize !== 'split' && sizeStyle(size, orientation)),

package/src/components/StackItem/StackItemContent.tsx

@@ -9,7 +9,8 @@ import { mx } from '@dxos/react-ui-theme';
 
 import { useStack, useStackItem } from '../StackContext';
 
-export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRef<'div'>, 'role'>> & {
+// TODO(burdon): Add prop for container-max-width?
+export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRef<'div'>, 'role' | 'scrollable'>> & {
   /**
    * 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.
@@ -22,15 +23,21 @@ export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRe
   statusbar?: boolean;
 
   /**
-   * Whether the consumer intends to do something custom and typical affordances should not apply
+   * Whether to support y-axis scrolling.
    */
-  layoutManaged?: boolean;
+  scrollable?: boolean;
 
   /**
-   * Whether to set a certain aspect ratio on the content, including the toolbar and statusbar. This is provided for
-   * convenience and consistency; it can instead be specified by the `classNames` or `style` props as needed.
+   * Whether to set a certain aspect ratio on the content, including the toolbar and statusbar.
+   * This is provided for convenience and consistency; it can instead be specified by the `classNames` or `style` props as needed.
    */
   size?: 'intrinsic' | 'video' | 'square';
+
+  /**
+   * Whether the consumer intends to do something custom and typical affordances should not apply.
+   * @deprecated Replace with override for gridTempateRows.
+   */
+  layoutManaged?: boolean;
 };
 
 /**
@@ -38,7 +45,10 @@ export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRe
  * The `toolbar` flag must be provided since this component provides for the layout of content with the toolbar.
  */
 export const StackItemContent = forwardRef<HTMLDivElement, StackItemContentProps>(
-  ({ children, toolbar, statusbar, layoutManaged, classNames, size = 'intrinsic', ...props }, forwardedRef) => {
+  (
+    { children, toolbar, statusbar, layoutManaged, classNames, size = 'intrinsic', scrollable, ...props },
+    forwardedRef,
+  ) => {
     const { size: stackItemSize } = useStack();
     const { role } = useStackItem();
     const style = useMemo(
@@ -61,12 +71,13 @@ export const StackItemContent = forwardRef<HTMLDivElement, StackItemContentProps
         {...props}
         className={mx(
           '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',
+          stackItemSize === 'contain' && 'min-bs-0 overflow-hidden',
+          scrollable ? 'min-bs-0 overflow-y-auto scrollbar-thin contain-layout' : 'overflow-hidden',
           role === 'section' &&
             toolbar &&
             '[&_.dx-toolbar]:sticky [&_.dx-toolbar]:z-[1] [&_.dx-toolbar]:block-start-0 [&_.dx-toolbar]:-mbe-px [&_.dx-toolbar]:min-is-0',
+          toolbar && '[&>.dx-toolbar]:relative [&>.dx-toolbar]:border-be [&>.dx-toolbar]:border-subduedSeparator',
           classNames,
         )}
         style={style}

package/src/components/StackItem/StackItemHeading.tsx

@@ -2,7 +2,6 @@
 // Copyright 2024 DXOS.org
 //
 
-import { useFocusableGroup } from '@fluentui/react-tabster';
 import { Slot } from '@radix-ui/react-slot';
 import React, {
   type ComponentPropsWithRef,
@@ -30,7 +29,6 @@ export const StackItemHeading = ({
   ...props
 }: StackItemHeadingProps) => {
   const { orientation } = useStack();
-  const focusableGroupAttrs = useFocusableGroup({ tabBehavior: 'limited' });
 
   const Root = asChild ? Slot : 'div';
 
@@ -38,10 +36,8 @@ export const StackItemHeading = ({
     <Root
       role='heading'
       {...props}
-      tabIndex={0}
-      {...focusableGroupAttrs}
       className={mx(
-        'flex items-center dx-focus-ring-inset-over-all relative !border-is-0 bg-headerSurface',
+        'flex items-center !border-is-0 bg-headerSurface',
         separateOnScroll
           ? 'border-transparent [[data-scroll-separator="true"]_&]:border-subduedSeparator'
           : 'border-subduedSeparator',

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

@@ -2,13 +2,11 @@
 // 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';
 
@@ -47,28 +45,6 @@ const meta = {
   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;

package/src/exemplars/Card/Card.tsx

@@ -13,21 +13,31 @@ import React, {
 } 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 { 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>
     );
@@ -35,18 +45,19 @@ 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 = ({
+  id,
   role = 'never',
   children,
   classNames,
-}: ThemedClassName<PropsWithChildren<{ role?: string }>>) => {
+}: ThemedClassName<PropsWithChildren<{ id?: string; role?: string }>>) => {
   if (['card--popover', 'card--intrinsic', 'card--extrinsic'].includes(role)) {
     return (
       <div
+        {...(id && { 'data-object-id': id })}
         className={mx(
           role === 'card--popover'
             ? 'popover-card-width'
@@ -62,6 +73,7 @@ const CardSurfaceRoot = ({
   } else {
     return (
       <CardStaticRoot
+        id={id}
         classNames={[
           role === 'card--transclusion' && 'mlb-1',
           role === 'card--transclusion' && hoverableControls,
@@ -118,22 +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 <Image classNames={[`dx-card__poster is-full __bs-auto`, aspect]} src={props.image} alt={props.alt} />;
+    return (
+      <Image classNames={[`dx-card__poster is-full`, aspect, props.classNames]} src={props.image} alt={props.alt} />
+    );
   }
 
   if (props.icon) {
     return (
       <div
         role='image'
-        className={mx(`dx-card__poster grid place-items-center bg-inputSurface text-subdued`, aspect)}
+        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} />
@@ -183,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

@@ -21,4 +21,4 @@ export const cardText = cardSpacing;
 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,15 +2,13 @@
 // 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 { withTheme } from '@dxos/react-ui/testing';
 
 import { StackItem } from '../../components';
 import { Card, CardDragPreview } from '../Card';
@@ -162,7 +160,10 @@ const 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

@@ -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

@@ -10,6 +10,8 @@ import { useLayoutEffect, useState } from 'react';
 
 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]);