@dxos/react-ui-stack 0.8.4-main.f5c0578 → 0.8.4-main.fcc0d83b33

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

@@ -2,45 +2,49 @@
 // 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 } from './StackItem';
+import { StackItem, type StackItemRootProps } from './StackItem';
 
-const meta: Meta<typeof StackItem.Root> = {
-  title: 'ui/react-ui-stack/StackItem',
-  component: StackItem.Root,
-  render: (args) => (
-    <StackItem.Root role='section' {...args} classNames='w-[20rem] border border-separator'>
-      <StackItem.Heading>
+const DefaultStory = (props: StackItemRootProps) => {
+  return (
+    <StackItem.Root role='section' {...props} classNames='w-[20rem] border border-separator'>
+      <StackItem.Heading classNames='w-full border-b border-separator'>
         <span className='sr-only'>Title</span>
-        <div role='none' className='sticky -block-start-px bg-[--sticky-bg] p-1 is-full'>
+        <div role='none' className='sticky -top-px bg-(--sticky-bg) p-1 w-full'>
           <DropdownMenu.Root>
             <DropdownMenu.Trigger asChild>
               <StackItem.SigilButton>
-                <Icon icon='ph--dots-three--regular' size={5} />
+                <Icon icon='ph--dots-three--regular' />
               </StackItem.SigilButton>
             </DropdownMenu.Trigger>
           </DropdownMenu.Root>
         </div>
       </StackItem.Heading>
-      <StackItem.Content classNames='p-2'>Content</StackItem.Content>
+      <StackItem.Content>
+        <div className='p-4 text-center'>Content</div>
+      </StackItem.Content>
     </StackItem.Root>
-  ),
-  decorators: [withTheme],
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-stack/StackItem',
+  component: StackItem.Root as any,
+  render: DefaultStory,
+  decorators: [withTheme()],
   parameters: {
     layout: 'centered',
   },
-};
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-type Story = StoryObj<typeof StackItem.Root>;
+type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {

package/src/components/StackItem/StackItem.tsx

@@ -2,15 +2,15 @@
 // Copyright 2024 DXOS.org
 //
 
-import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
-import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
-import { preserveOffsetOnSource } from '@atlaskit/pragmatic-drag-and-drop/element/preserve-offset-on-source';
-import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
 import {
   type Edge,
   attachClosestEdge,
   extractClosestEdge,
 } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { preserveOffsetOnSource } from '@atlaskit/pragmatic-drag-and-drop/element/preserve-offset-on-source';
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
 import { useFocusableGroup } from '@fluentui/react-tabster';
 import { composeRefs } from '@radix-ui/react-compose-refs';
 import React, {
@@ -26,11 +26,10 @@ import { createPortal } from 'react-dom';
 
 import { ListItem, type ThemedClassName } from '@dxos/react-ui';
 import { resizeAttributes, sizeStyle } from '@dxos/react-ui-dnd';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
-import { type StackItemData, type StackItemSize } from '../defs';
 import { type ItemDragState, StackItemContext, idle, useStack, useStackItem } from '../StackContext';
-
+import { type StackItemData, type StackItemSize } from '../types';
 import { StackItemContent, type StackItemContentProps } from './StackItemContent';
 import { StackItemDragHandle, type StackItemDragHandleProps } from './StackItemDragHandle';
 import {
@@ -49,36 +48,39 @@ import {
   type StackItemSigilProps,
 } from './StackItemSigil';
 
-// NOTE: 48rem fills the screen on a MacbookPro with the sidebars closed.
-export const DEFAULT_HORIZONTAL_SIZE = 48 satisfies StackItemSize;
 export const DEFAULT_VERTICAL_SIZE = 'min-content' satisfies StackItemSize;
+export const DEFAULT_HORIZONTAL_SIZE = 50 satisfies StackItemSize;
 export const DEFAULT_EXTRINSIC_SIZE = DEFAULT_HORIZONTAL_SIZE satisfies StackItemSize;
 
+//
+// StackItemRoot
+//
+
 type StackItemRootProps = ThemedClassName<ComponentPropsWithRef<'div'>> & {
+  role?: 'article' | 'section';
   item: Omit<StackItemData, 'type'>;
   order?: number;
   prevSiblingId?: string;
   nextSiblingId?: string;
   size?: StackItemSize;
   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>(
   (
     {
-      item,
-      children,
       classNames,
-      size: propsSize,
-      onSizeChange,
+      children,
+      style,
       role,
+      item,
       order,
       prevSiblingId,
       nextSiblingId,
-      style,
+      size: sizeProp,
+      onSizeChange,
       disableRearrange,
       focusIndicatorVariant = 'over-all',
       ...props
@@ -86,18 +88,17 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
     forwardedRef,
   ) => {
     const [itemElement, itemRef] = useState<HTMLDivElement | null>(null);
+    const composedItemRef = composeRefs<HTMLDivElement>(itemRef, forwardedRef);
     const [selfDragHandleElement, selfDragHandleRef] = useState<HTMLDivElement | null>(null);
     const [closestEdge, setEdge] = useState<Edge | null>(null);
     const [sourceId, setSourceId] = useState<string | null>(null);
     const [dragState, setDragState] = useState<ItemDragState>(idle);
-    const { orientation, rail, onRearrange } = useStack();
+    const { orientation, rail, onRearrange, size: stackSize, stackId } = useStack();
     const [size = orientation === 'horizontal' ? DEFAULT_HORIZONTAL_SIZE : DEFAULT_VERTICAL_SIZE, setInternalSize] =
-      useState(propsSize);
+      useState(sizeProp);
 
     const Root = role ?? 'div';
 
-    const composedItemRef = composeRefs<HTMLDivElement>(itemRef, forwardedRef);
-
     const setSize = useCallback(
       (nextSize: StackItemSize, commit?: boolean) => {
         setInternalSize(nextSize);
@@ -110,6 +111,7 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
 
     const type = orientation === 'horizontal' ? 'column' : 'card';
 
+    // TODO(burdon): Factor out?
     useLayoutEffect(() => {
       if (!itemElement || !onRearrange || disableRearrange) {
         return;
@@ -183,18 +185,18 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
 
     const focusableGroupAttrs = useFocusableGroup({ tabBehavior: 'limited' });
 
-    // Determine if the drop would result in any changes
+    // Determine if the drop would result in any changes.
     const shouldShowDropIndicator = () => {
       if (!closestEdge || !sourceId) {
         return false;
       }
 
-      // Don't show indicator when dragged item is over itself
+      // Don't show indicator when dragged item is over itself.
       if (sourceId === item.id) {
         return false;
       }
 
-      // Don't show indicator when dragged item is over the trailing edge of its previous sibling
+      // Don't show indicator when dragged item is over the trailing edge of its previous sibling.
       const isTrailingEdgeOfPrevSibling =
         prevSiblingId !== undefined &&
         sourceId === prevSiblingId &&
@@ -232,18 +234,25 @@ 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',
+            role === 'section' && orientation !== 'horizontal' && 'border-b border-subdued-separator',
             classNames,
           )}
-          data-dx-stack-item
+          data-dx-stack-item={stackId}
+          data-dx-item-id={item.id}
           {...resizeAttributes}
           style={{
-            ...sizeStyle(size, orientation),
+            ...(stackSize !== 'split' && sizeStyle(size, orientation)),
             ...(Number.isFinite(order) && {
               [orientation === 'horizontal' ? 'gridColumn' : 'gridRow']: `${order}`,
             }),
@@ -261,37 +270,45 @@ const StackItemRoot = forwardRef<HTMLDivElement, StackItemRootProps>(
   },
 );
 
+//
+// StackItemDragPreview
+//
+
 type StackItemDragPreviewProps = {
   children: ({ item }: { item: any }) => ReactNode;
 };
 
-export const StackItemDragPreview = ({ children }: StackItemDragPreviewProps) => {
+const StackItemDragPreview = ({ children }: StackItemDragPreviewProps) => {
   const { state } = useStackItem();
   return state?.type === 'preview' ? createPortal(children({ item: state.item }), state.container) : null;
 };
 
+//
+// StackItem
+//
+
 export const StackItem = {
   Root: StackItemRoot,
   Content: StackItemContent,
+  DragHandle: StackItemDragHandle,
+  DragPreview: StackItemDragPreview,
   Heading: StackItemHeading,
   HeadingLabel: StackItemHeadingLabel,
   HeadingStickyContent: StackItemHeadingStickyContent,
   ResizeHandle: StackItemResizeHandle,
-  DragHandle: StackItemDragHandle,
   Sigil: StackItemSigil,
   SigilButton: StackItemSigilButton,
-  DragPreview: StackItemDragPreview,
 };
 
 export type {
   StackItemRootProps,
   StackItemContentProps,
+  StackItemDragHandleProps,
+  StackItemDragPreviewProps,
   StackItemHeadingProps,
   StackItemHeadingLabelProps,
   StackItemResizeHandleProps,
-  StackItemDragHandleProps,
   StackItemSigilProps,
   StackItemSigilButtonProps,
   StackItemSigilAction,
-  StackItemDragPreviewProps,
 };

package/src/components/StackItem/StackItemContent.tsx

@@ -5,71 +5,49 @@
 import React, { type ComponentPropsWithoutRef, forwardRef, useMemo } from 'react';
 
 import { type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 import { useStack, useStackItem } from '../StackContext';
 
-export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRef<'div'>, 'role'>> & {
-  /**
-   * 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.
-   */
+export type StackItemContentProps = ThemedClassName<Omit<ComponentPropsWithoutRef<'div'>, 'role' | 'scrollable'>> & {
   toolbar?: boolean;
-
-  /**
-   * Whether to provide for the layout of a statusbar after the content.
-   */
   statusbar?: boolean;
-
-  /**
-   * Whether the consumer intends to do something custom and typical affordances should not apply
-   */
-  layoutManaged?: 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.
-   */
-  size?: 'intrinsic' | 'video' | 'square';
 };
 
 /**
- * This component should be used by plugins for rendering content within a stack item, a.k.a. a “plank” or “section”.
- * The `toolbar` flag must be provided since this component provides for the layout of content with the toolbar.
+ * This component should be used by plugins for rendering content within a stack item (i.e., a “plank” or “section”).
  */
 export const StackItemContent = forwardRef<HTMLDivElement, StackItemContentProps>(
-  ({ children, toolbar, statusbar, layoutManaged, classNames, size = 'intrinsic', ...props }, forwardedRef) => {
+  ({ classNames, children, toolbar, statusbar, ...props }, forwardedRef) => {
     const { size: stackItemSize } = useStack();
     const { role } = useStackItem();
     const style = useMemo(
-      () =>
-        layoutManaged
-          ? {}
-          : {
-              gridTemplateRows: [
-                ...(toolbar ? [role === 'section' ? 'calc(var(--toolbar-size) - 1px)' : 'var(--toolbar-size)'] : []),
-                '1fr',
-                ...(statusbar ? ['var(--statusbar-size)'] : []),
-              ].join(' '),
-            },
-      [toolbar, statusbar, layoutManaged],
+      () => ({
+        gridTemplateRows: [
+          toolbar && role === 'section' ? 'calc(var(--dx-toolbar-size) - 1px)' : 'var(--dx-toolbar-size)',
+          '1fr',
+          statusbar && 'var(--dx-statusbar-size)',
+        ]
+          .filter(Boolean)
+          .join(' '),
+      }),
+      [toolbar, statusbar],
     );
 
     return (
       <div
-        role='none'
         {...props}
+        role='none'
+        style={style}
         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',
-          role === 'section' &&
-            toolbar &&
-            '[&_.dx-toolbar]:sticky [&_.dx-toolbar]:z-[1] [&_.dx-toolbar]:block-start-0 [&_.dx-toolbar]:-mbe-px [&_.dx-toolbar]:min-is-0',
+          'group grid grid-cols-[100%] dx-density-coarse',
+          stackItemSize === 'contain' && 'min-h-0 overflow-hidden',
+          toolbar &&
+            role === 'section' &&
+            '[&_.dx-toolbar]:sticky [&_.dx-toolbar]:z-[1] [&_.dx-toolbar]:top-0 [&_.dx-toolbar]:-mb-px [&_.dx-toolbar]:min-w-0',
+          toolbar && '[&>.dx-toolbar]:relative [&>.dx-toolbar]:border-b [&>.dx-toolbar]:border-subdued-separator',
           classNames,
         )}
-        style={style}
         data-popover-collision-boundary={true}
         ref={forwardedRef}
       >
@@ -78,3 +56,5 @@ export const StackItemContent = forwardRef<HTMLDivElement, StackItemContentProps
     );
   },
 );
+
+StackItemContent.displayName = 'StackItemContent';

package/src/components/StackItem/StackItemDragHandle.tsx

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
 import React, { type ComponentPropsWithoutRef } from 'react';
 
@@ -12,11 +13,11 @@ export type StackItemDragHandleProps = ComponentPropsWithoutRef<'button'> & { as
 export const StackItemDragHandle = ({ asChild, children }: StackItemDragHandleProps) => {
   const { selfDragHandleRef } = useStackItem();
 
-  const Root = asChild ? Slot : 'div';
+  const Comp = asChild ? Slot : Primitive.div;
 
   return (
-    <Root ref={selfDragHandleRef} role='button'>
+    <Comp ref={selfDragHandleRef} role='button'>
       {children}
-    </Root>
+    </Comp>
   );
 };

package/src/components/StackItem/StackItemHeading.tsx

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { useFocusableGroup } from '@fluentui/react-tabster';
+import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
 import React, {
   type ComponentPropsWithRef,
@@ -13,7 +13,7 @@ import React, {
 
 import { type ThemedClassName } from '@dxos/react-ui';
 import { type AttendableId, type Related, useAttention } from '@dxos/react-ui-attention';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 import { useStack } from '../StackContext';
 
@@ -27,37 +27,34 @@ export const StackItemHeading = ({
   classNames,
   asChild,
   separateOnScroll,
+  role,
   ...props
 }: StackItemHeadingProps) => {
   const { orientation } = useStack();
-  const focusableGroupAttrs = useFocusableGroup({ tabBehavior: 'limited' });
-
-  const Root = asChild ? Slot : 'div';
+  const Comp = asChild ? Slot : Primitive.div;
 
   return (
-    <Root
-      role='heading'
+    <Comp
       {...props}
-      tabIndex={0}
-      {...focusableGroupAttrs}
+      role={role ?? 'heading'}
       className={mx(
-        'flex items-center dx-focus-ring-inset-over-all relative !border-is-0 bg-headerSurface',
+        'flex items-center border-x-0! bg-header-surface',
         separateOnScroll
-          ? 'border-transparent [[data-scroll-separator="true"]_&]:border-subduedSeparator'
-          : 'border-subduedSeparator',
-        orientation === 'horizontal' ? 'bs-[--rail-size]' : 'is-[--rail-size] flex-col',
-        orientation === 'horizontal' ? 'border-be' : 'border-ie',
+          ? 'border-transparent [[data-scroll-separator="true"]_&]:border-subdued-separator'
+          : 'border-subdued-separator',
+        orientation === 'horizontal' ? 'h-(--dx-rail-size)' : 'w-(--dx-rail-size) flex-col',
+        orientation === 'horizontal' ? 'border-b' : 'border-e',
         classNames,
       )}
     >
       {children}
-    </Root>
+    </Comp>
   );
 };
 
 export const StackItemHeadingStickyContent = ({ children }: PropsWithChildren<{}>) => {
   return (
-    <div role='none' className='sticky block-start-0 bg-[--sticky-bg] p-1 is-full'>
+    <div role='none' className='sticky top-0 bg-(--sticky-bg) p-1 w-full'>
       {children}
     </div>
   );
@@ -74,7 +71,7 @@ export const StackItemHeadingLabel = forwardRef<HTMLHeadingElement, StackItemHea
         {...props}
         data-attention={((related && isRelated) || hasAttention || isAncestor).toString()}
         className={mx(
-          'pli-1 min-is-0 is-0 grow truncate font-medium text-baseText data-[attention=true]:text-accentText self-center',
+          'px-1 min-w-0 w-0 grow truncate font-medium text-base-surface-text data-[attention=true]:text-accent-text self-center',
           classNames,
         )}
         ref={forwardedRef}

package/src/components/StackItem/StackItemResizeHandle.tsx

@@ -7,7 +7,6 @@ import React from 'react';
 import { ResizeHandle } from '@dxos/react-ui-dnd';
 
 import { useStack, useStackItem } from '../StackContext';
-
 import { DEFAULT_EXTRINSIC_SIZE } from './StackItem';
 
 const MIN_WIDTH = 20;
@@ -15,7 +14,7 @@ const MIN_HEIGHT = 3;
 
 export type StackItemResizeHandleProps = {};
 
-export const StackItemResizeHandle = () => {
+export const StackItemResizeHandle = (_: StackItemResizeHandleProps) => {
   const { orientation } = useStack();
   const { setSize, size } = useStackItem();
 

package/src/components/StackItem/StackItemSigil.tsx

@@ -4,14 +4,14 @@
 
 import React, { Fragment, type PropsWithChildren, forwardRef, useState } from 'react';
 
-import { type ActionLike } from '@dxos/app-graph';
+import { type Node } from '@dxos/app-graph';
 import { keySymbols } from '@dxos/keyboard';
 import { Button, type ButtonProps, DropdownMenu, Icon, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { type AttendableId, type Related, useAttention } from '@dxos/react-ui-attention';
-import { descriptionText, mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 import { getHostPlatform } from '@dxos/util';
 
-import { translationKey } from '../../translations';
+import { translationKey } from '#translations';
 
 import { MenuSignifierHorizontal } from './MenuSignifier';
 
@@ -23,7 +23,7 @@ export type KeyBinding = {
   unknown?: string;
 };
 
-export type StackItemSigilAction = Pick<ActionLike, 'id' | 'properties' | 'data'>;
+export type StackItemSigilAction = Pick<Node.ActionLike, 'id' | 'properties' | 'data'>;
 
 export type StackItemSigilButtonProps = Omit<ButtonProps, 'variant'> &
   AttendableId &
@@ -40,7 +40,10 @@ export const StackItemSigilButton = forwardRef<HTMLButtonElement, StackItemSigil
       <Button
         {...props}
         variant={variant}
-        classNames={['shrink-0 pli-0 min-bs-0 is-[--rail-action] bs-[--rail-action] relative app-no-drag', classNames]}
+        classNames={[
+          'shrink-0 px-0 min-h-0 w-(--dx-rail-action) h-(--dx-rail-action) relative dx-app-no-drag',
+          classNames,
+        ]}
         ref={forwardedRef}
       >
         {isMenu && <MenuSignifierHorizontal />}
@@ -78,7 +81,7 @@ export const StackItemSigil = forwardRef<HTMLButtonElement, StackItemSigilProps>
         classNames={!hasActions && 'cursor-default'}
       >
         <span className='sr-only'>{triggerLabel}</span>
-        <Icon icon={icon} size={5} />
+        <Icon icon={icon} />
       </StackItemSigilButton>
     );
 
@@ -133,7 +136,7 @@ export const StackItemSigil = forwardRef<HTMLButtonElement, StackItemSigilProps>
                             </DropdownMenu.ItemIndicator>
                           )}
                           {shortcut && (
-                            <span className={mx('shrink-0', descriptionText)}>{keySymbols(shortcut).join('')}</span>
+                            <span className={mx('shrink-0', 'text-description')}>{keySymbols(shortcut).join('')}</span>
                           )}
                         </Root>
                       );

package/src/components/index.ts

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