@dxos/react-ui-stack 0.8.4-main.dedc0f3 → 0.8.4-main.ead640a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-stack",
-  "version": "0.8.4-main.dedc0f3",
+  "version": "0.8.4-main.ead640a",
   "description": "A stack component.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -54,36 +54,36 @@
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
     "react-resize-detector": "^11.0.1",
-    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
-    "@dxos/keyboard": "0.8.4-main.dedc0f3",
-    "@dxos/live-object": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui-dnd": "0.8.4-main.dedc0f3",
-    "@dxos/storybook-utils": "0.8.4-main.dedc0f3",
-    "@dxos/util": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui-attention": "0.8.4-main.dedc0f3"
+    "@dxos/echo": "0.8.4-main.ead640a",
+    "@dxos/keyboard": "0.8.4-main.ead640a",
+    "@dxos/react-ui-attention": "0.8.4-main.ead640a",
+    "@dxos/react-ui-dnd": "0.8.4-main.ead640a",
+    "@dxos/storybook-utils": "0.8.4-main.ead640a",
+    "@dxos/live-object": "0.8.4-main.ead640a",
+    "@dxos/util": "0.8.4-main.ead640a"
   },
   "devDependencies": {
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "vite": "7.1.1",
-    "@dxos/app-graph": "0.8.4-main.dedc0f3",
-    "@dxos/random": "0.8.4-main.dedc0f3",
-    "@dxos/client": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui": "0.8.4-main.dedc0f3",
-    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui-theme": "0.8.4-main.dedc0f3",
-    "@dxos/storybook-utils": "0.8.4-main.dedc0f3",
-    "@dxos/test-utils": "0.8.4-main.dedc0f3"
+    "@types/react": "~19.2.2",
+    "@types/react-dom": "~19.2.1",
+    "react": "~19.2.0",
+    "react-dom": "~19.2.0",
+    "vite": "7.1.9",
+    "@dxos/app-graph": "0.8.4-main.ead640a",
+    "@dxos/client": "0.8.4-main.ead640a",
+    "@dxos/echo": "0.8.4-main.ead640a",
+    "@dxos/react-ui": "0.8.4-main.ead640a",
+    "@dxos/random": "0.8.4-main.ead640a",
+    "@dxos/react-ui-theme": "0.8.4-main.ead640a",
+    "@dxos/storybook-utils": "0.8.4-main.ead640a",
+    "@dxos/test-utils": "0.8.4-main.ead640a"
   },
   "peerDependencies": {
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "@dxos/client": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui": "0.8.4-main.dedc0f3",
-    "@dxos/random": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui-theme": "0.8.4-main.dedc0f3"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@dxos/client": "0.8.4-main.ead640a",
+    "@dxos/random": "0.8.4-main.ead640a",
+    "@dxos/react-ui-theme": "0.8.4-main.ead640a",
+    "@dxos/react-ui": "0.8.4-main.ead640a"
   },
   "publishConfig": {
     "access": "public"

package/src/components/Image/Image.stories.tsx

@@ -2,17 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React from 'react';
+import React, { useMemo } from 'react';
 
 import { faker } from '@dxos/random';
-import { withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
 import { Image } from './Image';
 
-faker.seed(1);
+const seed = Math.random();
+
+faker.seed(seed);
 
 const meta = {
   title: 'ui/react-ui-stack/Image',
@@ -24,7 +24,7 @@ const meta = {
   ),
   decorators: [withTheme],
   parameters: {
-    layout: 'fullscreen',
+    layout: 'centered',
   },
 } satisfies Meta<typeof Image>;
 
@@ -56,3 +56,23 @@ export const SVG: Story = {
     classNames: 'w-[20rem]',
   },
 };
+
+export const Many: Story = {
+  args: {
+    src: 'https://dxos.network/bg-kube.svg',
+  },
+  render: () => {
+    const images = useMemo(
+      () => Array.from({ length: 9 }, (_, i) => `https://picsum.photos/seed/${seed + i}/500/500`),
+      [],
+    );
+    console.log(images);
+    return (
+      <div className='is-[60rem] grid grid-cols-3 grid-rows-3 gap-8'>
+        {images.map((src, i) => (
+          <Image key={i} src={src} classNames='is-[18rem] bs-[12rem]' />
+        ))}
+      </div>
+    );
+  },
+};

package/src/components/Image/Image.tsx

@@ -7,13 +7,13 @@ import React, { type SyntheticEvent, useRef, useState } from 'react';
 import { type ThemedClassName } from '@dxos/react-ui';
 import { mx } from '@dxos/react-ui-theme';
 
-export type ImageProps = ThemedClassName<{
-  src: string;
-  alt?: string;
-  crossOrigin?: 'anonymous' | 'use-credentials' | '';
-  sampleSize?: number;
-  contrast?: number;
-}>;
+export type ImageProps = ThemedClassName<
+  {
+    src: string;
+    alt?: string;
+    crossOrigin?: 'anonymous' | 'use-credentials' | '';
+  } & ColorOptions
+>;
 
 export const Image = ({
   classNames,
@@ -28,74 +28,26 @@ export const Image = ({
   const [imageLoaded, setImageLoaded] = useState<boolean>(false);
   const canvasRef = useRef<HTMLCanvasElement>(null);
 
-  // TODO(burdon): Cache?
-  const extractDominantColor = (img: HTMLImageElement): void => {
-    const canvas = canvasRef.current;
-    const ctx = canvas?.getContext('2d');
-    if (!canvas || !ctx) {
+  // CORS not supported by server.
+  const handleImageError = (): void => {
+    setCrossOriginState(undefined);
+  };
+
+  const handleImageLoad = ({ target }: SyntheticEvent<HTMLImageElement>): void => {
+    const img = target as HTMLImageElement;
+    if (!canvasRef.current) {
       return;
     }
 
-    // Draw the image scaled down.
-    canvas.width = sampleSize;
-    canvas.height = sampleSize;
-    ctx.drawImage(img, 0, 0, sampleSize, sampleSize);
-
     try {
-      // Get image data.
-      const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize);
-      const pixels = imageData.data;
-
-      // Calculate average color with more weight to vibrant colors.
-      let r = 0;
-      let g = 0;
-      let b = 0;
-      let totalWeight = 0;
-      for (let i = 0; i < pixels.length; i += 4) {
-        const red = pixels[i];
-        const green = pixels[i + 1];
-        const blue = pixels[i + 2];
-        const alpha = pixels[i + 3];
-
-        // Skip transparent pixels.
-        if (alpha === 0) continue;
-
-        // Calculate saturation to weight vibrant colors more.
-        const max = Math.max(red, green, blue);
-        const min = Math.min(red, green, blue);
-        const saturation = max === 0 ? 0 : (max - min) / max;
-        const weight = 1 + saturation * 2; // Give more weight to saturated colors.
-
-        r += red * weight;
-        g += green * weight;
-        b += blue * weight;
-        totalWeight += weight;
-      }
-
-      if (totalWeight > 0) {
-        r = Math.round(r / totalWeight);
-        g = Math.round(g / totalWeight);
-        b = Math.round(b / totalWeight);
-
-        // Slightly darken the color for better contrast.
-        r = Math.round(r * contrast);
-        g = Math.round(g * contrast);
-        b = Math.round(b * contrast);
-        setDominantColor(`rgb(${r}, ${g}, ${b})`);
+      const color = extractDominantColor(canvasRef.current, img, { sampleSize, contrast });
+      if (color) {
+        setDominantColor(`rgb(${color[0]}, ${color[1]}, ${color[2]})`);
       }
     } catch {
       setCrossOriginState(undefined);
     }
-  };
 
-  // CORS not supported by server.
-  const handleImageError = (): void => {
-    setCrossOriginState(undefined);
-  };
-
-  const handleImageLoad = (ev: SyntheticEvent<HTMLImageElement>): void => {
-    const img = ev.target as HTMLImageElement;
-    extractDominantColor(img);
     setImageLoaded(true);
   };
 
@@ -135,3 +87,106 @@ export const Image = ({
     </div>
   );
 };
+
+type ColorOptions = {
+  sampleSize?: number;
+  contrast?: number;
+};
+
+// TODO(burdon): Cache?
+const extractDominantColor = (
+  canvas: HTMLCanvasElement,
+  img: HTMLImageElement,
+  { sampleSize = 64, contrast = 0.95 }: ColorOptions,
+): [number, number, number] | null => {
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    return null;
+  }
+
+  // Draw the image scaled down.
+  canvas.width = sampleSize;
+  canvas.height = sampleSize;
+  ctx.drawImage(img, 0, 0, sampleSize, sampleSize);
+
+  // Get image data.
+  const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize);
+  const pixels = imageData.data;
+
+  // Check for transparent background.
+  if (isTransparent(pixels, sampleSize)) {
+    return null;
+  }
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let totalWeight = 0;
+
+  // Calculate average color with more weight to vibrant colors.
+  for (let i = 0; i < pixels.length; i += 4) {
+    const red = pixels[i];
+    const green = pixels[i + 1];
+    const blue = pixels[i + 2];
+    const alpha = pixels[i + 3];
+
+    // Skip transparent pixels.
+    if (alpha === 0) continue;
+
+    // Calculate saturation to weight vibrant colors more.
+    const max = Math.max(red, green, blue);
+    const min = Math.min(red, green, blue);
+    // Give more weight to saturated colors.
+    const saturation = max === 0 ? 0 : (max - min) / max;
+    const weight = 1 + saturation * 2;
+
+    r += red * weight;
+    g += green * weight;
+    b += blue * weight;
+    totalWeight += weight;
+  }
+
+  if (totalWeight > 0) {
+    // Slightly darken the color for better contrast.
+    r = Math.round(Math.round(r / totalWeight) * contrast);
+    g = Math.round(Math.round(g / totalWeight) * contrast);
+    b = Math.round(Math.round(b / totalWeight) * contrast);
+    return [r, g, b];
+  }
+
+  return null;
+};
+
+/**
+ * Detects if an image has a transparent background by examining edge pixels.
+ * @param pixels - Image pixel data from canvas
+ * @param sampleSize - Size of the sampled image
+ * @param threshold - Percentage threshold for considering background transparent (default: 0.5)
+ * @returns True if the image has a transparent background
+ */
+const isTransparent = (pixels: Uint8ClampedArray, sampleSize: number, threshold: number = 0.5): boolean => {
+  let edgeTransparentPixels = 0;
+  const edgePixels = sampleSize * 4 - 4; // Perimeter minus corners counted twice.
+
+  for (let x = 0; x < sampleSize; x++) {
+    // Top edge.
+    const topIndex = x * 4;
+    if (pixels[topIndex + 3] === 0) edgeTransparentPixels++;
+
+    // Bottom edge.
+    const bottomIndex = ((sampleSize - 1) * sampleSize + x) * 4;
+    if (pixels[bottomIndex + 3] === 0) edgeTransparentPixels++;
+  }
+
+  for (let y = 1; y < sampleSize - 1; y++) {
+    // Left edge.
+    const leftIndex = y * sampleSize * 4;
+    if (pixels[leftIndex + 3] === 0) edgeTransparentPixels++;
+
+    // Right edge.
+    const rightIndex = (y * sampleSize + sampleSize - 1) * 4;
+    if (pixels[rightIndex + 3] === 0) edgeTransparentPixels++;
+  }
+
+  return edgeTransparentPixels / edgePixels > threshold;
+};

package/src/components/Stack/Stack.stories.tsx

@@ -2,14 +2,12 @@
 // Copyright 2024 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 { withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
 import { type StackItemData } from '../defs';
 import { StackItem } from '../StackItem';
@@ -133,8 +131,8 @@ const DefaultStory = () => {
 const meta = {
   title: 'ui/react-ui-stack/Stack',
   component: DefaultStory,
-  decorators: [withTheme],
   argTypes: { orientation: { control: 'radio', options: ['horizontal', 'vertical'] } },
+  decorators: [withTheme],
 } satisfies Meta<typeof DefaultStory>;
 
 export default meta;

package/src/components/Stack/Stack.tsx

@@ -37,6 +37,7 @@ export type StackProps = Omit<ThemedClassName<ComponentPropsWithRef<'div'>>, 'ar
     itemsCount?: number;
     getDropElement?: (stackElement: HTMLDivElement) => HTMLDivElement;
     separatorOnScroll?: number;
+    circularFocus?: boolean;
   };
 
 export const railGridHorizontal = 'grid-rows-[[rail-start]_var(--rail-size)_[content-start]_1fr_[content-end]]';
@@ -73,12 +74,14 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
       itemsCount = Children.count(children),
       getDropElement,
       separatorOnScroll,
+      circularFocus,
       ...props
     },
     forwardedRef,
   ) => {
     const stackId = useId('stack', props.id);
     const [stackElement, stackRef] = useState<HTMLDivElement | null>(null);
+    const [lastFocusedItem, setLastFocusedItem] = useState<string>();
     const composedItemRef = composeRefs<HTMLDivElement>(stackRef, forwardedRef);
 
     const styles: CSSProperties = {
@@ -114,6 +117,23 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
       }
     }, [stackElement, separatorOnScroll, orientation]);
 
+    /**
+     * Handles blur events to track the last focused item within this stack.
+     */
+    const handleBlur = useCallback(
+      (event: React.FocusEvent<HTMLDivElement>) => {
+        if (event.target) {
+          const target = event.target as HTMLElement;
+          const closestStackItem = target.closest(`[data-dx-item-id]`) as HTMLElement | null;
+          if (closestStackItem?.closest(`[data-dx-stack="${stackId}"]`)) {
+            setLastFocusedItem(closestStackItem?.getAttribute('data-dx-item-id') ?? undefined);
+          }
+        }
+        props.onBlur?.(event);
+      },
+      [stackId, props.onBlur],
+    );
+
     /**
      * Handles moving focus using the arrow keys. Focus is only handled by the nearest stack; if the arrow key matches the
      * orientation, focus cycles between items, otherwise focus is passed to an adjacent stack item; or, if there is no
@@ -152,10 +172,22 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
                 ? 1
                 : 0;
             if (parallelDelta !== 0) {
-              const adjacentItem = closestStackItems[
-                (closestStackItems.indexOf(closestOwnedItem) + parallelDelta + closestStackItems.length) %
-                  closestStackItems.length
-              ] as HTMLElement | undefined;
+              const currentIndex = closestStackItems.indexOf(closestOwnedItem);
+              const nextIndex = currentIndex + parallelDelta;
+              let adjacentItem: HTMLElement | undefined;
+
+              if (circularFocus) {
+                // Circular navigation: wrap around using modulo.
+                adjacentItem = closestStackItems[(nextIndex + closestStackItems.length) % closestStackItems.length] as
+                  | HTMLElement
+                  | undefined;
+              } else {
+                // Non-circular navigation: only move if within bounds.
+                if (nextIndex >= 0 && nextIndex < closestStackItems.length) {
+                  adjacentItem = closestStackItems[nextIndex] as HTMLElement | undefined;
+                }
+              }
+
               if (adjacentItem) {
                 event.preventDefault();
                 scrollIntoViewAndFocus(adjacentItem, closestStackOrientation);
@@ -168,10 +200,21 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
                     `[data-dx-stack-item="${ancestorStack.getAttribute('data-dx-stack')}"] [data-dx-stack]`,
                   ),
                 ) as HTMLElement[];
-                const adjacentStack = siblingStacks[
-                  (siblingStacks.indexOf(closestStack) + perpendicularDelta + siblingStacks.length) %
-                    siblingStacks.length
-                ] as HTMLElement | undefined;
+                const currentStackIndex = siblingStacks.indexOf(closestStack);
+                const nextStackIndex = currentStackIndex + perpendicularDelta;
+                let adjacentStack: HTMLElement | undefined;
+
+                if (ancestorStack.getAttribute('data-dx-stack-circular-focus') === 'true') {
+                  // Circular navigation: wrap around using modulo.
+                  adjacentStack = siblingStacks[(nextStackIndex + siblingStacks.length) % siblingStacks.length] as
+                    | HTMLElement
+                    | undefined;
+                } else {
+                  // Non-circular navigation: only move if within bounds.
+                  if (nextStackIndex >= 0 && nextStackIndex < siblingStacks.length) {
+                    adjacentStack = siblingStacks[nextStackIndex] as HTMLElement | undefined;
+                  }
+                }
                 const adjacentStackSelfItem = adjacentStack?.closest(
                   `[data-dx-stack-item=${ancestorStack.getAttribute('data-dx-stack')}]`,
                 ) as HTMLElement | undefined;
@@ -182,26 +225,35 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
                       ),
                     ) as HTMLElement[])
                   : [];
-                if (adjacentStackItems.length > 0) {
-                  // Find the closest item by position
-                  const ownedItemRect = closestOwnedItem.getBoundingClientRect();
-                  const targetPosition =
-                    closestStackOrientation === 'vertical' ? ownedItemRect.top : ownedItemRect.left;
-
+                if (adjacentStack && adjacentStackItems.length > 0) {
+                  // Check if the adjacent stack has a last focused item recorded, otherwise find the closest item by position.
                   let closestItem = adjacentStackItems[0];
-                  let closestDistance = Infinity;
+                  // Try to find an item with matching data-dx-stack-item value.
+                  const lastFocusedItem = adjacentStack.querySelector(
+                    `[data-dx-item-id="${adjacentStack.getAttribute('data-dx-last-focused-item') ?? 'never'}"]`,
+                  );
+                  if (lastFocusedItem) {
+                    closestItem = lastFocusedItem as HTMLElement;
+                  } else {
+                    // Fall back to positional calculation
+                    const ownedItemRect = closestOwnedItem.getBoundingClientRect();
+                    const targetPosition =
+                      closestStackOrientation === 'vertical' ? ownedItemRect.top : ownedItemRect.left;
 
-                  for (const item of adjacentStackItems) {
-                    const itemRect = item.getBoundingClientRect();
-                    const itemPosition = closestStackOrientation === 'vertical' ? itemRect.top : itemRect.left;
-                    const distance = Math.abs(itemPosition - targetPosition);
+                    let closestDistance = Infinity;
 
-                    if (distance < closestDistance) {
-                      closestDistance = distance;
-                      closestItem = item;
-                    }
-                    if (closestDistance <= PERPENDICULAR_FOCUS_THRESHHOLD) {
-                      break;
+                    for (const item of adjacentStackItems) {
+                      const itemRect = item.getBoundingClientRect();
+                      const itemPosition = closestStackOrientation === 'vertical' ? itemRect.top : itemRect.left;
+                      const distance = Math.abs(itemPosition - targetPosition);
+
+                      if (distance < closestDistance) {
+                        closestDistance = distance;
+                        closestItem = item;
+                      }
+                      if (closestDistance <= PERPENDICULAR_FOCUS_THRESHHOLD) {
+                        break;
+                      }
                     }
                   }
 
@@ -235,7 +287,7 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
         }
         props.onKeyDown?.(event);
       },
-      [props.onKeyDown, stackId],
+      [props.onKeyDown, stackId, circularFocus],
     );
 
     const gridClasses = useMemo(() => {
@@ -279,7 +331,10 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
             classNames,
           )}
           onKeyDown={handleKeyDown}
+          onBlur={handleBlur}
           data-dx-stack={stackId}
+          data-dx-stack-circular-focus={circularFocus}
+          data-dx-last-focused-item={lastFocusedItem}
           data-rail={rail}
           aria-orientation={orientation}
           style={styles}

package/src/components/StackItem/StackItem.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 { 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';
 
@@ -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}