@dxos/react-ui-stack 0.8.4-main.d05673bc65 → 0.8.4-main.dfabb4ec29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-stack",
-  "version": "0.8.4-main.d05673bc65",
+  "version": "0.8.4-main.dfabb4ec29",
   "description": "A stack component.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -12,6 +12,9 @@
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
+  "imports": {
+    "#translations": "./src/translations.ts"
+  },
   "exports": {
     ".": {
       "types": "./dist/types/src/index.d.ts",
@@ -22,19 +25,15 @@
       "types": "./dist/types/src/playwright/index.d.ts",
       "browser": "./dist/lib/browser/playwright/index.mjs",
       "node": "./dist/lib/node-esm/playwright/index.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "browser": "./dist/lib/browser/translations.mjs",
+      "node": "./dist/lib/node-esm/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "playwright": [
-        "dist/types/src/playwright/index.d.ts"
-      ],
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
@@ -53,40 +52,40 @@
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
     "react-resize-detector": "^11.0.1",
-    "@dxos/keyboard": "0.8.4-main.d05673bc65",
-    "@dxos/react-ui-attention": "0.8.4-main.d05673bc65",
-    "@dxos/react-ui-mosaic": "0.8.4-main.d05673bc65",
-    "@dxos/react-ui-dnd": "0.8.4-main.d05673bc65",
-    "@dxos/util": "0.8.4-main.d05673bc65",
-    "@dxos/echo": "0.8.4-main.d05673bc65"
+    "@dxos/echo": "0.8.4-main.dfabb4ec29",
+    "@dxos/keyboard": "0.8.4-main.dfabb4ec29",
+    "@dxos/react-ui-attention": "0.8.4-main.dfabb4ec29",
+    "@dxos/react-ui-mosaic": "0.8.4-main.dfabb4ec29",
+    "@dxos/util": "0.8.4-main.dfabb4ec29",
+    "@dxos/react-ui-dnd": "0.8.4-main.dfabb4ec29"
   },
   "devDependencies": {
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "vite": "^7.1.11",
-    "@dxos/app-framework": "0.8.4-main.d05673bc65",
-    "@dxos/client": "0.8.4-main.d05673bc65",
-    "@dxos/app-graph": "0.8.4-main.d05673bc65",
-    "@dxos/random": "0.8.4-main.d05673bc65",
-    "@dxos/echo-db": "0.8.4-main.d05673bc65",
-    "@dxos/echo": "0.8.4-main.d05673bc65",
-    "@dxos/react-client": "0.8.4-main.d05673bc65",
-    "@dxos/schema": "0.8.4-main.d05673bc65",
-    "@dxos/test-utils": "0.8.4-main.d05673bc65",
-    "@dxos/types": "0.8.4-main.d05673bc65",
-    "@dxos/ui-theme": "0.8.4-main.d05673bc65",
-    "@dxos/react-ui": "0.8.4-main.d05673bc65",
-    "@dxos/storybook-utils": "0.8.4-main.d05673bc65"
+    "vite": "^8.0.10",
+    "@dxos/app-framework": "0.8.4-main.dfabb4ec29",
+    "@dxos/app-graph": "0.8.4-main.dfabb4ec29",
+    "@dxos/client": "0.8.4-main.dfabb4ec29",
+    "@dxos/echo": "0.8.4-main.dfabb4ec29",
+    "@dxos/echo-db": "0.8.4-main.dfabb4ec29",
+    "@dxos/random": "0.8.4-main.dfabb4ec29",
+    "@dxos/react-client": "0.8.4-main.dfabb4ec29",
+    "@dxos/schema": "0.8.4-main.dfabb4ec29",
+    "@dxos/storybook-utils": "0.8.4-main.dfabb4ec29",
+    "@dxos/react-ui": "0.8.4-main.dfabb4ec29",
+    "@dxos/types": "0.8.4-main.dfabb4ec29",
+    "@dxos/test-utils": "0.8.4-main.dfabb4ec29",
+    "@dxos/ui-theme": "0.8.4-main.dfabb4ec29"
   },
   "peerDependencies": {
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/client": "0.8.4-main.d05673bc65",
-    "@dxos/react-ui": "0.8.4-main.d05673bc65",
-    "@dxos/random": "0.8.4-main.d05673bc65",
-    "@dxos/ui-theme": "0.8.4-main.d05673bc65"
+    "@dxos/client": "0.8.4-main.dfabb4ec29",
+    "@dxos/react-ui": "0.8.4-main.dfabb4ec29",
+    "@dxos/ui-theme": "0.8.4-main.dfabb4ec29",
+    "@dxos/random": "0.8.4-main.dfabb4ec29"
   },
   "publishConfig": {
     "access": "public"

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

@@ -6,12 +6,11 @@ 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 { random } from '@dxos/random';
 import { withTheme } from '@dxos/react-ui/testing';
 
 import { StackItem } from '../StackItem';
 import { type StackItemData } from '../types';
-
 import { Stack } from './Stack';
 
 type StoryStackItem = {
@@ -30,16 +29,16 @@ const KanbanBlock = ({ item }: { item: StoryStackItem }) => {
 
 const DefaultStory = () => {
   const [columns, setColumns] = useState<StoryStackItem[]>(
-    faker.helpers.multiple(
+    random.helpers.multiple(
       () =>
         ({
-          id: faker.string.uuid(),
-          title: faker.lorem.paragraph(),
-          items: faker.helpers.multiple(
+          id: random.string.uuid(),
+          title: random.lorem.paragraph(),
+          items: random.helpers.multiple(
             () =>
               ({
-                id: faker.string.uuid(),
-                title: faker.lorem.paragraph(),
+                id: random.string.uuid(),
+                title: random.lorem.paragraph(),
               }) satisfies StoryStackItem,
             { count: { min: 32, max: 64 } },
           ),
@@ -77,7 +76,6 @@ const DefaultStory = () => {
             targetColumn.items
           ) {
             const [movedCard] = sourceColumn.items.splice(sourceCardIndex, 1);
-
             let insertIndex;
             if (sourceColumn === targetColumn && sourceCardIndex < targetCardIndex) {
               insertIndex = closestEdge === 'bottom' ? targetCardIndex : targetCardIndex - 1;

package/src/components/Stack/Stack.tsx

@@ -4,7 +4,6 @@
 
 import { composeRefs } from '@radix-ui/react-compose-refs';
 import React, {
-  type CSSProperties,
   Children,
   type ComponentPropsWithRef,
   type FocusEvent,
@@ -12,7 +11,6 @@ import React, {
   forwardRef,
   useCallback,
   useEffect,
-  useMemo,
   useState,
 } from 'react';
 
@@ -37,14 +35,6 @@ export type Size = 'intrinsic' | 'contain' | 'split';
 export const railGridHorizontal = 'grid-rows-[[rail-start]_var(--dx-rail-size)_[content-start]_1fr_[content-end]]';
 export const railGridVertical = 'grid-cols-[[rail-start]_var(--dx-rail-size)_[content-start]_1fr_[content-end]]';
 
-// TODO(ZaymonFC): Magic 2px to stop overflow.
-export const railGridHorizontalContainFitContent =
-  'grid-rows-[[rail-start]_var(--dx-rail-size)_[content-start]_fit-content(calc(100%-var(--dx-rail-size)*2+2px))_[content-end]]';
-export const railGridVerticalContainFitContent =
-  'grid-cols-[[rail-start]_var(--dx-rail-size)_[content-start]_fit-content(calc(100%-var(--dx-rail-size)*2+2px))_[content-end]]';
-
-export const autoScrollRootAttributes = { 'data-drag-autoscroll': 'idle' };
-
 const PERPENDICULAR_FOCUS_THRESHHOLD = 128;
 
 const scrollIntoViewAndFocus = (el: HTMLElement, orientation: StackProps['orientation']) => {
@@ -58,9 +48,9 @@ const scrollIntoViewAndFocus = (el: HTMLElement, orientation: StackProps['orient
 export type StackProps = Omit<ThemedClassName<ComponentPropsWithRef<'div'>>, 'aria-orientation'> &
   Partial<StackContextValue> & {
     itemsCount?: number;
-    getDropElement?: (stackElement: HTMLDivElement) => HTMLDivElement;
-    separatorOnScroll?: number;
     circularFocus?: boolean;
+    separatorOnScroll?: number;
+    getDropElement?: (stackElement: HTMLDivElement) => HTMLDivElement;
   };
 
 export const Stack = forwardRef<HTMLDivElement, StackProps>(
@@ -68,34 +58,30 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
     {
       children,
       classNames,
+      id,
       style,
       orientation = 'vertical',
-      rail = true, // TODO(burdon): Change default to false.
+      rail = true,
       size = 'intrinsic',
-      onRearrange,
       itemsCount = Children.count(children),
-      getDropElement,
-      separatorOnScroll,
       circularFocus,
+      separatorOnScroll,
+      getDropElement,
+      onBlur,
+      onKeyDown,
+      onRearrange,
       ...props
     },
     forwardedRef,
   ) => {
-    const stackId = useId('stack', props.id);
+    const stackId = useId('stack', id);
     const [stackElement, stackRef] = useState<HTMLDivElement | null>(null);
     const [lastFocusedItem, setLastFocusedItem] = useState<string>();
     const composedItemRef = composeRefs<HTMLDivElement>(stackRef, forwardedRef);
 
-    const styles: CSSProperties = {
-      [orientation === 'horizontal' ? 'gridTemplateColumns' : 'gridTemplateRows']:
-        size === 'split' ? `repeat(${itemsCount}, 1fr)` : `repeat(${itemsCount}, min-content) [tabster-dummies] 0`,
-      ...style,
-    };
-
-    const selfDroppable = !!(itemsCount < 1 && onRearrange && props.id);
-
+    const selfDroppable = !!(itemsCount < 1 && onRearrange && id);
     const { dropping } = useStackDropForElements({
-      id: props.id,
+      id,
       element: getDropElement && stackElement ? getDropElement(stackElement) : stackElement,
       scrollElement: stackElement,
       selfDroppable,
@@ -103,6 +89,7 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
       onRearrange,
     });
 
+    /** Updates scroll separator data attributes based on current scroll position. */
     const handleScroll = useCallback(() => {
       if (stackElement && Number.isFinite(separatorOnScroll)) {
         const scrollPosition = orientation === 'horizontal' ? stackElement.scrollLeft : stackElement.scrollTop;
@@ -119,9 +106,7 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
       }
     }, [stackElement, separatorOnScroll, orientation]);
 
-    /**
-     * Handles blur events to track the last focused item within this stack.
-     */
+    /** Handles blur events to track the last focused item within this stack. */
     const handleBlur = useCallback(
       (event: FocusEvent<HTMLDivElement>) => {
         if (event.target) {
@@ -131,178 +116,15 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
             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 such stack item, focus is passed to the adjacent empty stack if one can be found.
-     */
-    const handleKeyDown = useCallback(
-      (event: KeyboardEvent<HTMLDivElement>) => {
-        const target = event.target as HTMLElement;
-        if (
-          event.key.startsWith('Arrow') &&
-          !target.closest(
-            `input, textarea, [role="textbox"], [data-tabster*="mover"], [data-arrow-keys="all"], [data-arrow-keys~="${event.key.toLowerCase().slice(5)}"]`,
-          )
-        ) {
-          const closestOwnedItem = target.closest(`[data-dx-stack-item="${stackId}"]`);
-          const closestStack = target.closest('[data-dx-stack]') as HTMLElement | null;
-          const closestStackItems = Array.from(
-            closestStack?.querySelectorAll(`[data-dx-stack-item="${stackId}"]`) ?? [],
-          );
-          const closestStackOrientation = closestStack?.getAttribute('aria-orientation') as Orientation;
-          const ancestorStack = closestStack?.parentElement?.closest('[data-dx-stack]') as HTMLElement | null;
-          if (closestOwnedItem && closestStack) {
-            const ancestorOrientation = ancestorStack?.getAttribute('aria-orientation') as Orientation | undefined;
-            const parallelDelta = (
-              closestStackOrientation === 'vertical' ? event.key === 'ArrowUp' : event.key === 'ArrowLeft'
-            )
-              ? -1
-              : (closestStackOrientation === 'vertical' ? event.key === 'ArrowDown' : event.key === 'ArrowRight')
-                ? 1
-                : 0;
-            const perpendicularDelta = (
-              closestStackOrientation === 'vertical' ? event.key === 'ArrowLeft' : event.key === 'ArrowUp'
-            )
-              ? -1
-              : (closestStackOrientation === 'vertical' ? event.key === 'ArrowRight' : event.key === 'ArrowDown')
-                ? 1
-                : 0;
-            if (parallelDelta !== 0) {
-              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);
-              }
-            }
-
-            if (perpendicularDelta !== 0) {
-              if (ancestorStack && ancestorOrientation !== closestStackOrientation) {
-                const siblingStacks = Array.from(
-                  ancestorStack.querySelectorAll(
-                    `[data-dx-stack-item="${ancestorStack.getAttribute('data-dx-stack')}"] [data-dx-stack]`,
-                  ),
-                ) as HTMLElement[];
-                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;
-                const adjacentStackItems = adjacentStack
-                  ? (Array.from(
-                      adjacentStack.querySelectorAll(
-                        `[data-dx-stack-item="${adjacentStack.getAttribute('data-dx-stack')}"]`,
-                      ),
-                    ) as HTMLElement[])
-                  : [];
-                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];
-                  // 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;
-
-                    let closestDistance = Infinity;
-                    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;
-                      }
-                    }
-                  }
-
-                  event.preventDefault();
-                  scrollIntoViewAndFocus(closestItem, closestStackOrientation);
-                } else if (adjacentStackSelfItem) {
-                  event.preventDefault();
-                  scrollIntoViewAndFocus(adjacentStackSelfItem, ancestorOrientation);
-                }
-              } else if (closestOwnedItem) {
-                const closestOwnedItemStack = closestOwnedItem.querySelector('[data-dx-stack]');
-                const closestOwnedItemStackItems = closestOwnedItemStack
-                  ? (Array.from(
-                      closestOwnedItemStack.querySelectorAll(
-                        `[data-dx-stack-item="${closestOwnedItemStack.getAttribute('data-dx-stack')}"]`,
-                      ),
-                    ) as HTMLElement[])
-                  : [];
-                if (closestOwnedItemStackItems.length > 0) {
-                  event.preventDefault();
-                  scrollIntoViewAndFocus(
-                    closestOwnedItemStackItems[
-                      ['ArrowUp', 'ArrowLeft'].includes(event.key) ? closestOwnedItemStackItems.length - 1 : 0
-                    ],
-                    closestOwnedItemStack?.getAttribute('aria-orientation') as Orientation,
-                  );
-                }
-              }
-            }
-          }
-        }
-        props.onKeyDown?.(event);
+        onBlur?.(event);
       },
-      [props.onKeyDown, stackId, circularFocus],
+      [stackId, onBlur],
     );
 
-    const gridClasses = useMemo(() => {
-      if (!rail) {
-        return orientation === 'horizontal' ? 'grid-rows-1 px-(--stack-gap)' : 'grid-cols-1 py-(--stack-gap)';
-      }
-
-      if (orientation === 'horizontal') {
-        return railGridHorizontal;
-      } else {
-        return railGridVertical;
-      }
-    }, [rail, orientation, size]);
+    /** Handles keyboard navigation within the stack. */
+    const handleKeyDown = useKeyDown(stackId, circularFocus, onKeyDown);
 
+    /** Observes DOM mutations to keep scroll separator state in sync. */
     useEffect(() => {
       if (!(stackElement && Number.isFinite(separatorOnScroll))) {
         return;
@@ -313,35 +135,46 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
       });
 
       observer.observe(stackElement, { childList: true, subtree: true });
-
       return () => {
         observer.disconnect();
       };
     }, [stackElement, handleScroll]);
 
     return (
-      <StackContext.Provider value={{ orientation, rail, size, onRearrange, stackId }}>
+      <StackContext.Provider value={{ stackId, orientation, rail, size, onRearrange }}>
         <div
           {...props}
+          {...(Number.isFinite(separatorOnScroll) && { onScroll: handleScroll })}
           className={mx(
-            'grid relative [--stack-gap:var(--spacing-trim-xs)]',
-            gridClasses,
+            'relative grid [--stack-gap:var(--spacing-trim-xs)]',
             size === 'contain' &&
               (orientation === 'horizontal'
                 ? 'overflow-x-auto overscroll-x-contain min-h-0 max-h-full h-full'
                 : 'overflow-y-auto min-w-0 max-w-full w-full'),
+            rail
+              ? orientation === 'horizontal'
+                ? railGridHorizontal
+                : railGridVertical
+              : orientation === 'horizontal'
+                ? 'grid-rows-1 px-(--stack-gap)'
+                : 'grid-cols-1 py-(--stack-gap)',
             classNames,
           )}
-          onKeyDown={handleKeyDown}
-          onBlur={handleBlur}
+          style={{
+            [orientation === 'horizontal' ? 'gridTemplateColumns' : 'gridTemplateRows']:
+              size === 'split'
+                ? `repeat(${itemsCount}, 1fr)`
+                : `repeat(${itemsCount}, min-content) [tabster-dummies] 0`,
+            ...style,
+          }}
+          aria-orientation={orientation}
           data-dx-stack={stackId}
           data-dx-stack-circular-focus={circularFocus}
           data-dx-last-focused-item={lastFocusedItem}
           data-rail={rail}
-          aria-orientation={orientation}
-          style={styles}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
           ref={composedItemRef}
-          {...(Number.isFinite(separatorOnScroll) && { onScroll: handleScroll })}
         >
           {children}
           {selfDroppable && dropping && (
@@ -361,3 +194,157 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(
 export { StackContext };
 
 export type { StackContextValue };
+
+/**
+ * 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 such stack item, focus is passed to the adjacent empty stack if one can be found.
+ */
+// TODO(burdon): Replace with Mosaic.Stack which handles this automatically.
+const useKeyDown = (stackId: string, circularFocus?: boolean, onKeyDown?: StackProps['onKeyDown']) =>
+  useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      const target = event.target as HTMLElement;
+      if (
+        event.key.startsWith('Arrow') &&
+        !target.closest(
+          `input, textarea, [role="textbox"], [data-tabster*="mover"], [data-arrow-keys="all"], [data-arrow-keys~="${event.key.toLowerCase().slice(5)}"]`,
+        )
+      ) {
+        const closestOwnedItem = target.closest(`[data-dx-stack-item="${stackId}"]`);
+        const closestStack = target.closest('[data-dx-stack]') as HTMLElement | null;
+        const closestStackItems = Array.from(closestStack?.querySelectorAll(`[data-dx-stack-item="${stackId}"]`) ?? []);
+        const closestStackOrientation = closestStack?.getAttribute('aria-orientation') as Orientation;
+        const ancestorStack = closestStack?.parentElement?.closest('[data-dx-stack]') as HTMLElement | null;
+        if (closestOwnedItem && closestStack) {
+          const ancestorOrientation = ancestorStack?.getAttribute('aria-orientation') as Orientation | undefined;
+          const parallelDelta = (
+            closestStackOrientation === 'vertical' ? event.key === 'ArrowUp' : event.key === 'ArrowLeft'
+          )
+            ? -1
+            : (closestStackOrientation === 'vertical' ? event.key === 'ArrowDown' : event.key === 'ArrowRight')
+              ? 1
+              : 0;
+          const perpendicularDelta = (
+            closestStackOrientation === 'vertical' ? event.key === 'ArrowLeft' : event.key === 'ArrowUp'
+          )
+            ? -1
+            : (closestStackOrientation === 'vertical' ? event.key === 'ArrowRight' : event.key === 'ArrowDown')
+              ? 1
+              : 0;
+          if (parallelDelta !== 0) {
+            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);
+            }
+          }
+
+          if (perpendicularDelta !== 0) {
+            if (ancestorStack && ancestorOrientation !== closestStackOrientation) {
+              const siblingStacks = Array.from(
+                ancestorStack.querySelectorAll(
+                  `[data-dx-stack-item="${ancestorStack.getAttribute('data-dx-stack')}"] [data-dx-stack]`,
+                ),
+              ) as HTMLElement[];
+              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;
+              const adjacentStackItems = adjacentStack
+                ? (Array.from(
+                    adjacentStack.querySelectorAll(
+                      `[data-dx-stack-item="${adjacentStack.getAttribute('data-dx-stack')}"]`,
+                    ),
+                  ) as HTMLElement[])
+                : [];
+              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];
+                // 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;
+
+                  let closestDistance = Infinity;
+                  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;
+                    }
+                  }
+                }
+
+                event.preventDefault();
+                scrollIntoViewAndFocus(closestItem, closestStackOrientation);
+              } else if (adjacentStackSelfItem) {
+                event.preventDefault();
+                scrollIntoViewAndFocus(adjacentStackSelfItem, ancestorOrientation);
+              }
+            } else if (closestOwnedItem) {
+              const closestOwnedItemStack = closestOwnedItem.querySelector('[data-dx-stack]');
+              const closestOwnedItemStackItems = closestOwnedItemStack
+                ? (Array.from(
+                    closestOwnedItemStack.querySelectorAll(
+                      `[data-dx-stack-item="${closestOwnedItemStack.getAttribute('data-dx-stack')}"]`,
+                    ),
+                  ) as HTMLElement[])
+                : [];
+              if (closestOwnedItemStackItems.length > 0) {
+                event.preventDefault();
+                scrollIntoViewAndFocus(
+                  closestOwnedItemStackItems[
+                    ['ArrowUp', 'ArrowLeft'].includes(event.key) ? closestOwnedItemStackItems.length - 1 : 0
+                  ],
+                  closestOwnedItemStack?.getAttribute('aria-orientation') as Orientation,
+                );
+              }
+            }
+          }
+        }
+      }
+      onKeyDown?.(event);
+    },
+    [onKeyDown, stackId, circularFocus],
+  );

package/src/components/StackContext.tsx

@@ -33,7 +33,7 @@ export type ItemDragState =
       item: any;
     }
   | {
-      type: 'w-dragging';
+      type: 'is-dragging';
       item: any;
     };