@dxos/plugin-deck 0.8.4-main.4a85c3132b → 0.8.4-main.4f23b4e393

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,108 @@
+//
+// 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 { random } from '@dxos/random';
+import { Main } from '@dxos/react-ui';
+import { StackContext } from '@dxos/react-ui-stack';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { Loading } from '@dxos/react-ui/testing';
+import { Organization } from '@dxos/types';
+
+import { DeckSettings, DeckState } from '#capabilities';
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+
+import { Plank } from './Plank';
+
+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,
+);
+
+random.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 (
+        <Syntax.Root data={subject}>
+          <Syntax.Content>
+            <Syntax.Viewport>
+              <Syntax.Code />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
+      );
+    },
+  }),
+);
+
+const DefaultStory = () => {
+  const { graph } = useAppGraph();
+  const item = useMemo(() => Organization.make({ name: random.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 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: {
+    layout: 'fullscreen',
+    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 { PlankComponent, PlankComponentProps } from './PlankComponent';
+import { PlankContent, PlankContentProps } from './PlankContent';
+import { PlankControls } from './PlankControls';
+import { PlankHeading } from './PlankHeading';
+import { PlankRoot, PlankRootProps } from './PlankRoot';
+
+/**
+ * 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,217 @@
+//
+// 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 { AppSurface } from '@dxos/app-toolkit/ui';
+import { debounce } from '@dxos/async';
+import { type Node } from '@dxos/plugin-graph';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { StackItem, type StackItemSize, railGridHorizontal } from '@dxos/react-ui-stack';
+import { mainIntrinsicSize, mx } from '@dxos/ui-theme';
+
+import { useMainSize } from '#hooks';
+import { PLANK_COMPANION_TYPE } from '#types';
+
+import { PlankError, PlankErrorFallback } from './PlankError';
+import { PlankHeading } from './PlankHeading';
+import { PlankLoading } from './PlankLoading';
+import { PlankRootProps, usePlankContext } from './PlankRoot';
+
+/**
+ * JS-based smooth scroll that won't be interrupted by MutationObserver or layout changes.
+ */
+const smoothScrollTo = (element: HTMLElement, target: number, duration: number) => {
+  const start = element.scrollLeft;
+  const distance = target - start;
+  const startTime = performance.now();
+
+  const step = (currentTime: number) => {
+    const elapsed = currentTime - startTime;
+    const progress = Math.min(elapsed / duration, 1);
+    // Ease-out cubic.
+    const eased = 1 - Math.pow(1 - progress, 3);
+    element.scrollLeft = start + distance * eased;
+    if (progress < 1) {
+      requestAnimationFrame(step);
+    }
+  };
+
+  requestAnimationFrame(step);
+};
+
+// NOTE: Calibrated to show PLANK + COMPANION on MBP 16" screen.
+export const DEFAULT_SIZE = 48 satisfies StackItemSize;
+export const DEFAULT_COMPANION_SIZE = 35 satisfies StackItemSize;
+
+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 isCompanion = companioned === 'companion';
+    const attentionAttrs = useAttentionAttributes(primary?.id ?? id);
+    const orderId = isCompanion ? 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;
+
+    // Sizing.
+    const sizeAttrs = useMainSize();
+    const sizeKey = id.split('+')[0];
+    const size = isCompanion
+      ? DEFAULT_COMPANION_SIZE
+      : ((plankSizing?.[sizeKey] as number | undefined) ?? DEFAULT_SIZE);
+    const handleSizeChange = useCallback(
+      debounce((nextSize: number) => {
+        const size = Math.round(nextSize);
+        onResize?.(sizeKey, size);
+      }, 200),
+      [sizeKey, onResize],
+    );
+
+    // 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) {
+        const element = rootElement.current;
+        const scrollParent = element.closest('[style*="overflow"], .overflow-x-auto') as HTMLElement | null;
+        if (scrollParent) {
+          const elementRect = element.getBoundingClientRect();
+          const parentRect = scrollParent.getBoundingClientRect();
+          const targetScrollLeft = scrollParent.scrollLeft + (elementRect.left - parentRect.left);
+
+          smoothScrollTo(scrollParent, targetScrollLeft, 300);
+        }
+
+        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 data = useMemo<AppSurface.ArticleData | undefined>(
+      () =>
+        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 Root = part.startsWith('solo') ? 'article' : StackItem.Root;
+    const fullscreen = layoutMode === 'solo--fullscreen';
+    const classNames = [
+      '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' && (isCompanion ? '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',
+    ];
+
+    return (
+      <Root
+        ref={rootElement}
+        data-testid='deck.plank'
+        data-popover-collision-boundary={true}
+        tabIndex={0}
+        {...(part.startsWith('solo')
+          ? ({
+              className: mx(classNames),
+              ...sizeAttrs,
+            } as any)
+          : {
+              role: 'article',
+              item: { id },
+              classNames,
+              order,
+              size,
+              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}
+              type={AppSurface.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>
+    );
+  },
+);

package/src/{components → containers}/Plank/PlankControls.tsx

@@ -5,10 +5,11 @@
 import React, { forwardRef, useCallback } from 'react';
 
 import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
 import { ButtonGroup, type ButtonGroupProps, type ButtonProps, IconButton, useTranslation } from '@dxos/react-ui';
 
-import { meta } from '../../meta';
-import { type DeckAction, DeckOperation, type LayoutMode } from '../../types';
+import { meta } from '#meta';
+import { type DeckAction, type LayoutMode } from '#types';
 
 export type PlankControlHandler = (event: DeckAction.PartAdjustment) => void;
 
@@ -21,36 +22,27 @@ export type PlankCapabilities = {
   companion?: boolean;
 };
 
-export type PlankControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
-  onClick?: PlankControlHandler;
-  variant?: 'hide-disabled' | 'default';
-  close?: boolean | 'minify-start' | 'minify-end';
-  capabilities: PlankCapabilities;
-  layoutMode?: LayoutMode;
-  pin?: 'start' | 'end' | 'both';
-};
-
-const PlankControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> & { label: string; icon: string }) => {
-  return <IconButton label={label} icon={icon} iconOnly variant='ghost' tooltipSide='bottom' {...props} />;
-};
+//
+// Controls
+//
 
 const plankControlSpacing = 'px-2';
 
-type PlankComplimentControlsProps = {
+export type PlankCompanionControlsProps = {
   primary?: string;
 };
 
-export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankComplimentControlsProps>(
+export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankCompanionControlsProps>(
   ({ primary }, forwardedRef) => {
     const { t } = useTranslation(meta.id);
     const { invokePromise } = useOperationInvoker();
     const handleCloseCompanion = useCallback(() => {
-      return invokePromise(DeckOperation.ChangeCompanion, { companion: null });
+      return invokePromise(LayoutOperation.UpdateCompanion, { subject: null });
     }, [invokePromise]);
     return (
       <div ref={forwardedRef} className='contents dx-app-no-drag'>
         <PlankControl
-          label={t('close companion label')}
+          label={t('close-companion.label')}
           variant='ghost'
           icon='ph--x--regular'
           onClick={handleCloseCompanion}
@@ -61,6 +53,23 @@ export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankCompliment
   },
 );
 
+const PlankControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> & { label: string; icon: string }) => {
+  return <IconButton label={label} icon={icon} iconOnly variant='ghost' tooltipSide='bottom' {...props} />;
+};
+
+//
+// PlankControls
+//
+
+export type PlankControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
+  onClick?: PlankControlHandler;
+  variant?: 'hide-disabled' | 'default';
+  close?: boolean | 'minify-start' | 'minify-end';
+  capabilities: PlankCapabilities;
+  layoutMode?: LayoutMode;
+  pin?: 'start' | 'end' | 'both';
+};
+
 // TODO(wittjosiah): Duplicate of stack LayoutControls?
 //   Translations were to be duplicated between packages.
 // NOTE(thure): Pinning & unpinning are disabled indefinitely.
@@ -83,7 +92,7 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
               <>
                 {layoutMode === 'solo' && (
                   <PlankControl
-                    label={t('show fullscreen plank label')}
+                    label={t('show-fullscreen-plank.label')}
                     classNames={buttonClassNames}
                     icon='ph--corners-out--regular'
                     onClick={() => onClick?.('solo--fullscreen')}
@@ -92,10 +101,10 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
                 <PlankControl
                   label={t(
                     layoutMode === 'solo--fullscreen'
-                      ? 'exit fullscreen label'
+                      ? 'exit-fullscreen.label'
                       : layoutIsAnySolo
-                        ? 'show deck plank label'
-                        : 'show solo plank label',
+                        ? 'show-deck-plank.label'
+                        : 'show-solo-plank.label',
                   )}
                   classNames={buttonClassNames}
                   icon={
@@ -110,17 +119,17 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
               </>
             )}
 
-            {!layoutIsAnySolo && (
+            {!layoutIsAnySolo && layoutMode !== 'multi' && (
               <>
                 <PlankControl
-                  label={t('increment start label')}
+                  label={t('increment-start.label')}
                   disabled={!capabilities.incrementStart}
                   classNames={buttonClassNames}
                   icon='ph--caret-left--regular'
                   onClick={() => onClick?.('increment-start')}
                 />
                 <PlankControl
-                  label={t('increment end label')}
+                  label={t('increment-end.label')}
                   disabled={!capabilities.incrementEnd}
                   classNames={buttonClassNames}
                   icon='ph--caret-right--regular'
@@ -132,7 +141,7 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
         ) : (
           capabilities.fullscreen && (
             <PlankControl
-              label={t(layoutMode === 'solo--fullscreen' ? 'exit fullscreen label' : 'show fullscreen plank label')}
+              label={t(layoutMode === 'solo--fullscreen' ? 'exit-fullscreen.label' : 'show-fullscreen-plank.label')}
               classNames={buttonClassNames}
               icon={layoutMode === 'solo--fullscreen' ? 'ph--corners-in--regular' : 'ph--corners-out--regular'}
               onClick={() => onClick?.('solo--fullscreen')}
@@ -142,7 +151,7 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
 
         {close && !layoutIsAnySolo && (
           <PlankControl
-            label={t(`${typeof close === 'string' ? 'minify' : 'close'} label`)}
+            label={t(`${typeof close === 'string' ? 'minify' : 'close'}.label`)}
             classNames={buttonClassNames}
             data-testid='plankHeading.close'
             icon={
@@ -158,7 +167,7 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
 
         {capabilities.companion && (
           <PlankControl
-            label={t('open companion label')}
+            label={t('open-companion.label')}
             classNames={buttonClassNames}
             data-testid='plankHeading.companion'
             icon='ph--square-split-horizontal--regular'

package/src/{components → containers}/Plank/PlankError.tsx

@@ -2,13 +2,15 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useMemo, useState } from 'react';
 
+import { TimeoutError } from '@dxos/errors';
+import { log } from '@dxos/log';
 import { type Node } from '@dxos/plugin-graph';
 import { ErrorFallback, type ErrorFallbackProps, useTranslation } from '@dxos/react-ui';
 import { descriptionMessage, mx } from '@dxos/ui-theme';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
 
 import { PlankHeading, type PlankHeadingProps } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
@@ -17,7 +19,7 @@ export const PlankError = ({
   id,
   part,
   node,
-  error,
+  error: errorProp,
 }: {
   id: string;
   part: PlankHeadingProps['part'];
@@ -30,6 +32,14 @@ export const PlankError = ({
     return () => clearTimeout(timer);
   }, []);
 
+  const error = useMemo(() => {
+    if (timedOut) {
+      return new TimeoutError({ message: 'Timeout loading content' });
+    }
+
+    return errorProp;
+  }, [timedOut, errorProp]);
+
   return (
     <>
       <PlankHeading id={id} part={part} node={node} pending={!timedOut} />
@@ -44,6 +54,12 @@ export const PlankError = ({
 export const PlankErrorFallback = ({ error }: ErrorFallbackProps) => {
   const { t } = useTranslation(meta.id);
 
+  useEffect(() => {
+    if (error) {
+      log.error('plank error', { error });
+    }
+  }, [error]);
+
   if (process.env.NODE_ENV === 'development') {
     return <ErrorFallback title='Plank Error' error={error} />;
   } else {
@@ -55,7 +71,7 @@ export const PlankErrorFallback = ({ error }: ErrorFallbackProps) => {
         className='dx-attention-surface overflow-y-auto p-8 grid place-items-center'
       >
         <p className={mx(descriptionMessage, 'break-all rounded-md p-4')}>
-          {error ? errorString : t('error fallback message')}
+          {error ? errorString : t('error-fallback.message')}
         </p>
       </div>
     );