@dxos/plugin-deck 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/{components → containers}/DeckLayout/Dialog.tsx

@@ -4,11 +4,11 @@
 
 import React, { useCallback } from 'react';
 
-import { Surface } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
 import { AlertDialog, Dialog as NaturalDialog } from '@dxos/react-ui';
 
-import { useDeckState } from '../../hooks';
-import { PlankContentError } from '../Plank';
+import { useDeckState } from '#hooks';
+import { PlankErrorFallback } from '../Plank';
 
 export const Dialog = () => {
   const { state, updateEphemeral } = useDeckState();
@@ -28,10 +28,16 @@ export const Dialog = () => {
     <Root modal={dialogBlockAlign !== 'end'} open={dialogOpen} onOpenChange={handleOpenChange}>
       {dialogBlockAlign === 'end' ? (
         // TODO(burdon): Placeholder creates a suspense boundary; replace with defaults.
-        <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} placeholder={<div />} />
+        <Surface.Surface
+          role='dialog'
+          data={dialogContent}
+          limit={1}
+          fallback={PlankErrorFallback}
+          placeholder={<div />}
+        />
       ) : (
         <Overlay blockAlign={dialogBlockAlign} classNames={dialogOverlayClasses} style={dialogOverlayStyle}>
-          <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} />
+          <Surface.Surface role='dialog' data={dialogContent} limit={1} fallback={PlankErrorFallback} />
         </Overlay>
       )}
     </Root>

package/src/containers/DeckLayout/Fallback.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+const Fallback = () => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <div role='none' className='min-h-screen w-full flex items-center justify-center p-8'>
+      <p
+        role='alert'
+        className='flex items-center justify-center p-8 font-normal text-lg text-error-text border border-rose-fill rounded-md'
+      >
+        {t('plugin-error.message')}
+      </p>
+    </div>
+  );
+};

package/src/{components → containers}/DeckLayout/Popover.tsx

@@ -3,16 +3,25 @@
 //
 
 import { createContext } from '@radix-ui/react-context';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
 import React, { type PropsWithChildren, useCallback, useEffect, useRef, useState } from 'react';
 
-import { Surface } from '@dxos/app-framework/react';
-import { Popover, type PopoverContentInteractOutsideEvent, toLocalizedString, useTranslation } from '@dxos/react-ui';
-import { Card } from '@dxos/react-ui-mosaic';
+import { Surface } from '@dxos/app-framework/ui';
+import { useObjectMenuItems } from '@dxos/app-toolkit/ui';
+import { Annotation, Obj } from '@dxos/echo';
+import {
+  Card,
+  Popover,
+  type PopoverContentInteractOutsideEvent,
+  toLocalizedString,
+  Toolbar,
+  useTranslation,
+} from '@dxos/react-ui';
+import { Menu } from '@dxos/react-ui-menu';
 
-import { useDeckState } from '../../hooks';
-import { meta } from '../../meta';
-
-export type DeckPopoverRootProps = PropsWithChildren<{}>;
+import { useDeckState } from '#hooks';
+import { meta } from '#meta';
 
 const DEBOUNCE_DELAY = 40;
 
@@ -22,7 +31,9 @@ type DeckPopoverContextValue = {
 
 const [DeckPopoverProvider, useDeckPopoverContext] = createContext<DeckPopoverContextValue>('DeckPopover');
 
-export const PopoverRoot = ({ children }: DeckPopoverRootProps) => {
+export type PopoverRootProps = PropsWithChildren;
+
+export const PopoverRoot = ({ children }: PopoverRootProps) => {
   const { state } = useDeckState();
   const virtualRef = useRef<HTMLButtonElement | null>(null);
   const [virtualIter, setVirtualIter] = useState(0);
@@ -59,6 +70,19 @@ export const PopoverContent = () => {
   const { t } = useTranslation(meta.id);
   const { state, updateEphemeral } = useDeckState();
   const { setOpen } = useDeckPopoverContext('PopoverContent');
+  const popoverSubject = state.popoverContent?.subject;
+  const isObjectPopover = Obj.isObject(popoverSubject);
+  const objectMenuItems = useObjectMenuItems(popoverSubject);
+  const title = state.popoverTitle ? toLocalizedString(state.popoverTitle, t) : 'Unknown';
+  const icon = isObjectPopover
+    ? Function.pipe(
+        Obj.getSchema(popoverSubject),
+        Option.fromNullable,
+        Option.flatMap(Annotation.IconAnnotation.get),
+        Option.map(({ icon }) => icon),
+        Option.getOrElse(() => 'ph--placeholder--regular'),
+      )
+    : undefined;
 
   const handleClose = useCallback(() => {
     setOpen(false);
@@ -96,18 +120,34 @@ export const PopoverContent = () => {
         onEscapeKeyDown={handleInteractOutside}
       >
         <Popover.Viewport>
+          {/* Base popover */}
+          {state.popoverKind === 'base' && <Surface.Surface role='popover' data={state.popoverContent} limit={1} />}
+
+          {/* Card popover */}
           {state.popoverKind === 'card' && (
-            <Card.Root>
-              <Card.Toolbar>
-                {/* TODO(wittjosiah): Cleaner way to handle no drag handle in toolbar? */}
-                <span />
-                {state.popoverTitle ? <Card.Title>{toLocalizedString(state.popoverTitle, t)}</Card.Title> : <span />}
-                <Card.Close onClick={handleClose} />
-              </Card.Toolbar>
-              <Surface role='card--content' data={state.popoverContent} limit={1} />
-            </Card.Root>
+            <Menu.Root>
+              <Card.Root border={false} classNames='dx-card-popover'>
+                <Card.Toolbar>
+                  <Card.IconBlock padding>{icon && <Card.Icon icon={icon} />}</Card.IconBlock>
+                  <Card.Title>{title}</Card.Title>
+                  {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
+                  <Card.IconBlock padding>
+                    <Menu.Trigger asChild disabled={!objectMenuItems.length}>
+                      <Toolbar.IconButton
+                        variant='ghost'
+                        icon='ph--dots-three-vertical--regular'
+                        iconOnly
+                        label='Actions'
+                      />
+                    </Menu.Trigger>
+                    <Menu.Content items={objectMenuItems} />
+                  </Card.IconBlock>
+                </Card.Toolbar>
+
+                <Surface.Surface role='card--content' data={state.popoverContent} limit={1} />
+              </Card.Root>
+            </Menu.Root>
           )}
-          {state.popoverKind === 'base' && <Surface role='popover' data={state.popoverContent} limit={1} />}
         </Popover.Viewport>
         <Popover.Arrow />
       </Popover.Content>

package/src/{components → containers}/DeckLayout/Toast.tsx

@@ -4,7 +4,7 @@
 
 import React from 'react';
 
-import { type Common } from '@dxos/app-framework';
+import { type LayoutOperation } from '@dxos/app-toolkit';
 import {
   Button,
   Icon,
@@ -14,7 +14,7 @@ import {
   useTranslation,
 } from '@dxos/react-ui';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
 
 // TODO(wittjosiah): Render remaining duration as a progress bar within the toast.
 export const Toast = ({
@@ -28,7 +28,7 @@ export const Toast = ({
   closeLabel,
   onAction,
   onOpenChange,
-}: Common.LayoutOperation.Toast & Pick<ToastRootProps, 'onOpenChange'>) => {
+}: LayoutOperation.Toast & Pick<ToastRootProps, 'onOpenChange'>) => {
   const { t } = useTranslation(meta.id);
 
   return (
@@ -61,7 +61,7 @@ export const Toast = ({
 };
 
 export type ToasterProps = {
-  toasts?: Common.LayoutOperation.Toast[];
+  toasts?: LayoutOperation.Toast[];
   onDismissToast?: (id: string) => void;
 };
 

package/src/{components → containers}/DeckLayout/constants.ts

@@ -3,4 +3,5 @@
 //
 
 export const NAV_ID = 'NavTree';
+
 export const SURFACE_PREFIX = 'surface:';

package/src/{components → containers}/DeckLayout/index.ts

@@ -2,7 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
+import { DeckLayout } from './DeckLayout';
+
 export { NAV_ID } from './constants';
 
-export * from './Banner';
-export * from './DeckLayout';
+export default DeckLayout;

package/src/containers/Plank/Plank.stories.tsx

@@ -0,0 +1,105 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { corePlugins } from '@dxos/plugin-testing';
+import { faker } from '@dxos/random';
+import { Main } from '@dxos/react-ui';
+import { Json } from '@dxos/react-ui-syntax-highlighter';
+import { Loading } from '@dxos/react-ui/testing';
+import { StackContext } from '@dxos/react-ui-stack';
+import { Organization } from '@dxos/types';
+
+import { meta as pluginMeta } from '#meta';
+
+import { translations } from '../../translations';
+
+import { Plank } from './Plank';
+
+import { DeckSettings, DeckState } from '#capabilities';
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    activatesOn: AppActivationEvents.SetupSettings,
+    activate: DeckSettings,
+  }),
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  Plugin.make,
+);
+
+faker.seed(101);
+
+const storySurfaceExtension = Capability.contributes(
+  Capabilities.ReactSurface,
+  Surface.create({
+    id: 'story-article',
+    role: 'article',
+    component: ({ data }) => {
+      const subject = (data as any)?.subject;
+      if (!subject) {
+        return <Loading />;
+      }
+
+      return (
+        <Json.Root data={subject}>
+          <Json.Content />
+        </Json.Root>
+      );
+    },
+  }),
+);
+
+const DefaultStory = () => {
+  const { graph } = useAppGraph();
+  const item = useMemo(() => Organization.make({ name: faker.company.name() }), []);
+  const node = useMemo(() => ({ id: item.id, data: item, type: 'test', properties: { label: item.name } }), [item]);
+
+  return (
+    <Main.Root>
+      <Main.Content bounce handlesFocus classNames='grid' style={{ '--main-spacing': '0' } as any}>
+        <div role='none' className='relative overflow-hidden bg-deck-surface'>
+          <StackContext.Provider value={{ orientation: 'horizontal', size: 'contain', rail: true }}>
+            <Plank.Root graph={graph} part='solo' layoutMode='solo'>
+              <Plank.Content solo companion={false} encapsulate={false}>
+                <Plank.Component id={item.id} part='solo-primary' node={node as any} />
+              </Plank.Content>
+            </Plank.Root>
+          </StackContext.Provider>
+        </div>
+      </Main.Content>
+    </Main.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-deck/containers/Plank',
+  component: DefaultStory,
+  decorators: [
+    withPluginManager({
+      plugins: [...corePlugins(), TestPlugin()],
+      capabilities: [storySurfaceExtension],
+      setupEvents: [AppActivationEvents.SetupSettings],
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/Plank/Plank.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { PlankRoot, PlankRootProps } from './PlankRoot';
+import { PlankComponent, PlankComponentProps } from './PlankComponent';
+import { PlankContent, PlankContentProps } from './PlankContent';
+import { PlankHeading } from './PlankHeading';
+import { PlankControls } from './PlankControls';
+
+/**
+ * Radix-style composite Plank component.
+ */
+export const Plank = {
+  Root: PlankRoot,
+  Content: PlankContent,
+  Component: PlankComponent,
+  Heading: PlankHeading,
+  Controls: PlankControls,
+};
+
+export type { PlankRootProps, PlankComponentProps, PlankContentProps };

package/src/containers/Plank/PlankComponent.tsx

@@ -0,0 +1,179 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useFocusFinders } from '@fluentui/react-tabster';
+import React, { type KeyboardEvent, memo, useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { debounce } from '@dxos/async';
+import { type Node } from '@dxos/plugin-graph';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { StackItem, railGridHorizontal } from '@dxos/react-ui-stack';
+import { mainIntrinsicSize, mx } from '@dxos/ui-theme';
+
+import { useMainSize } from '#hooks';
+import { PLANK_COMPANION_TYPE } from '#types';
+
+import { PlankRootProps, usePlankContext } from './PlankRoot';
+import { PlankError, PlankErrorFallback } from './PlankError';
+import { PlankHeading } from './PlankHeading';
+import { PlankLoading } from './PlankLoading';
+
+export type PlankComponentProps = Pick<PlankRootProps, 'part'> & {
+  id: string;
+  path?: string[];
+  order?: number;
+  active?: string[];
+  node?: Node.Node;
+  primary?: Node.Node;
+  companions?: Node.Node[];
+  companioned?: 'primary' | 'companion';
+};
+
+export const PlankComponent = memo(
+  ({ part, id, path, order, active, node, primary, companions, companioned }: PlankComponentProps) => {
+    const { layoutMode, settings, popoverAnchorId, scrollIntoView, plankSizing, onResize, onScrollIntoView } =
+      usePlankContext('PlankComponent');
+
+    const canResize = layoutMode === 'multi';
+    const { findFirstFocusable } = useFocusFinders();
+    const attentionAttrs = useAttentionAttributes(primary?.id ?? id);
+    const orderId = companioned === 'companion' ? primary?.id : id;
+    const index = orderId && active ? active.findIndex((entryId) => entryId === orderId) : -1;
+    const length = active?.length ?? 1;
+    const isOrdered = !!active && index >= 0;
+    const canIncrementStart = isOrdered && index > 0;
+    const canIncrementEnd = isOrdered && index < length - 1;
+
+    const rootElement = useRef<HTMLDivElement | null>(null);
+
+    const variant = node?.type === PLANK_COMPANION_TYPE ? getLinkedVariant(id) : undefined;
+    const sizeKey = id.split('+')[0];
+    const size = plankSizing?.[sizeKey] as number | undefined;
+
+    const handleSizeChange = useCallback(
+      debounce((nextSize: number) => {
+        onResize?.(sizeKey, nextSize);
+      }, 200),
+      [onResize, sizeKey],
+    );
+
+    // TODO(thure): Tabster's focus group should handle moving focus to Main, but something is blocking it.
+    const handleKeyDown = useCallback((event: KeyboardEvent) => {
+      if (event.target === event.currentTarget) {
+        switch (event.key) {
+          case 'Escape':
+            rootElement.current?.closest('main')?.focus();
+            break;
+          case 'Enter':
+            rootElement.current && findFirstFocusable(rootElement.current)?.focus();
+            break;
+        }
+      }
+    }, []);
+
+    useLayoutEffect(() => {
+      if (scrollIntoView === id) {
+        layoutMode === 'multi' && rootElement.current?.scrollIntoView({ behavior: 'smooth', inline: 'center' });
+        onScrollIntoView?.(undefined);
+      }
+    }, [id, scrollIntoView, layoutMode, onScrollIntoView]);
+
+    const isSolo = layoutMode.startsWith('solo') && part === 'solo';
+    const isAttendable =
+      (layoutMode.startsWith('solo') && part.startsWith('solo')) || (layoutMode === 'multi' && part === 'multi');
+    const sizeAttrs = useMainSize();
+
+    const data = useMemo(
+      () =>
+        node && {
+          attendableId: id,
+          subject: node.data,
+          companionTo: primary?.data,
+          properties: node.properties,
+          variant,
+          path,
+          popoverAnchorId,
+        },
+      [node, node?.data, node?.properties, path, popoverAnchorId, primary?.data, variant],
+    );
+
+    // TODO(wittjosiah): Change prop to accept a component.
+    const placeholder = useMemo(() => <PlankLoading />, []);
+
+    const fullscreen = layoutMode === 'solo--fullscreen';
+    const className = mx(
+      'dx-attention-surface relative dx-focus-ring-inset-over-all dx-density-coarse',
+      isSolo && 'absolute inset-0',
+      isSolo && mainIntrinsicSize,
+      railGridHorizontal,
+      part.startsWith('solo') && 'grid',
+      part.startsWith('solo-') && 'grid-rows-subgrid row-span-2 min-w-0',
+      fullscreen && 'grid-rows-1',
+      part === 'multi' && (companioned === 'companion' ? 'border-separator! border-e' : 'border-separator! border-x'),
+      part === 'solo-companion' && 'border-separator! border-s',
+      settings?.encapsulatedPlanks &&
+        !part.startsWith('solo') &&
+        'mx-(--main-spacing) border-separator! border rounded-sm overflow-hidden',
+    );
+
+    const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
+
+    return (
+      <Root
+        ref={rootElement}
+        data-testid='deck.plank'
+        data-popover-collision-boundary={true}
+        tabIndex={0}
+        {...(part.startsWith('solo')
+          ? ({
+              className,
+              ...sizeAttrs,
+            } as any)
+          : {
+              role: 'article',
+              classNames: className,
+              order,
+              size,
+              item: { id },
+              onSizeChange: handleSizeChange,
+            })}
+        {...(isAttendable ? attentionAttrs : {})}
+        onKeyDown={handleKeyDown}
+      >
+        {node ? (
+          <>
+            {!fullscreen && (
+              <PlankHeading
+                id={id}
+                part={part.startsWith('solo-') ? 'solo' : part}
+                node={node}
+                layoutMode={layoutMode}
+                deckEnabled={settings?.enableDeck}
+                canIncrementStart={canIncrementStart}
+                canIncrementEnd={canIncrementEnd}
+                popoverAnchorId={popoverAnchorId}
+                primaryId={primary?.id}
+                companioned={companioned}
+                companions={companions}
+              />
+            )}
+            <Surface.Surface
+              key={node.id}
+              role='article'
+              data={data}
+              limit={1}
+              fallback={PlankErrorFallback}
+              placeholder={placeholder}
+            />
+          </>
+        ) : (
+          <PlankError id={id} part={part} />
+        )}
+        {canResize && <StackItem.ResizeHandle />}
+      </Root>
+    );
+  },
+);

package/src/containers/Plank/PlankContent.tsx

@@ -0,0 +1,45 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { railGridHorizontal } from '@dxos/react-ui-stack';
+import { composable, composableProps, mainIntrinsicSize } from '@dxos/ui-theme';
+
+import { useMainSize } from '#hooks';
+
+export type PlankContentProps = PropsWithChildren<{
+  solo: boolean;
+  companion: boolean;
+  encapsulate: boolean;
+}>;
+
+export const PlankContent = composable<HTMLDivElement, PlankContentProps>(
+  ({ children, solo, companion, encapsulate, ...props }, forwardedRef) => {
+    const sizeAttrs = useMainSize();
+    if (!solo) {
+      return children;
+    }
+
+    return (
+      <div
+        {...sizeAttrs}
+        {...composableProps(props, {
+          role: 'none',
+          classNames: [
+            'absolute inset-(--main-spacing) grid',
+            railGridHorizontal,
+            mainIntrinsicSize,
+            companion && 'grid-cols-[6fr_4fr]', // Ration of primary to companion.
+            encapsulate && 'border border-separator rounded-sm overflow-hidden',
+          ],
+        })}
+        data-popover-collision-boundary={true}
+        ref={forwardedRef}
+      >
+        {children}
+      </div>
+    );
+  },
+);