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

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>
+    );
+  },
+);

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

@@ -4,12 +4,12 @@
 
 import React, { forwardRef, useCallback } from 'react';
 
-import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
-import { invariant } from '@dxos/invariant';
+import { useOperationInvoker } from '@dxos/app-framework/ui';
 import { ButtonGroup, type ButtonGroupProps, type ButtonProps, IconButton, useTranslation } from '@dxos/react-ui';
 
-import { DECK_PLUGIN } from '../../meta';
-import { DeckAction, type LayoutMode } from '../../types';
+import { meta } from '#meta';
+import { type DeckAction, type LayoutMode } from '#types';
+import { DeckOperation } from '#operations';
 
 export type PlankControlHandler = (event: DeckAction.PartAdjustment) => void;
 
@@ -22,37 +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 iconOnly label={label} icon={icon} size={5} variant='ghost' tooltipSide='bottom' {...props} />;
-};
+//
+// Controls
+//
 
-const plankControlSpacing = 'pli-2';
+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(DECK_PLUGIN);
-    const { dispatchPromise: dispatch } = useIntentDispatcher();
+    const { t } = useTranslation(meta.id);
+    const { invokePromise } = useOperationInvoker();
     const handleCloseCompanion = useCallback(() => {
-      invariant(primary);
-      return dispatch(createIntent(DeckAction.ChangeCompanion, { primary, companion: null }));
-    }, []);
+      return invokePromise(DeckOperation.ChangeCompanion, { companion: null });
+    }, [invokePromise]);
     return (
-      <div ref={forwardedRef} className='contents app-no-drag'>
+      <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}
@@ -63,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.
@@ -71,21 +78,21 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
     { children, classNames, variant = 'default', capabilities, layoutMode, pin, close = false, onClick, ...props },
     forwardedRef,
   ) => {
-    const { t } = useTranslation(DECK_PLUGIN);
+    const { t } = useTranslation(meta.id);
     const buttonClassNames =
       variant === 'hide-disabled' ? `disabled:hidden ${plankControlSpacing}` : plankControlSpacing;
 
     const layoutIsAnySolo = !!layoutMode?.startsWith('solo');
 
     return (
-      <ButtonGroup {...props} classNames={['app-no-drag !opacity-100', classNames]} ref={forwardedRef}>
+      <ButtonGroup {...props} classNames={['dx-app-no-drag opacity-100!', classNames]} ref={forwardedRef}>
         {capabilities.deck ? (
           <>
             {capabilities.solo && (
               <>
                 {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')}
@@ -94,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={
@@ -115,14 +122,14 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
             {!layoutIsAnySolo && (
               <>
                 <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'
@@ -134,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')}
@@ -144,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={
@@ -160,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/containers/Plank/PlankError.tsx

@@ -0,0 +1,79 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 { PlankHeading, type PlankHeadingProps } from './PlankHeading';
+import { PlankLoading } from './PlankLoading';
+
+export const PlankError = ({
+  id,
+  part,
+  node,
+  error: errorProp,
+}: {
+  id: string;
+  part: PlankHeadingProps['part'];
+  node?: Node.Node;
+  error?: Error;
+}) => {
+  const [timedOut, setTimedOut] = useState(false);
+  useEffect(() => {
+    const timer = setTimeout(() => setTimedOut(true), 5_000);
+    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} />
+      {timedOut ? <PlankErrorFallback error={error} /> : <PlankLoading />}
+    </>
+  );
+};
+
+/**
+ * User facing error fallback.
+ */
+export const PlankErrorFallback = ({ error }: ErrorFallbackProps) => {
+  const { t } = useTranslation(meta.id);
+
+  useEffect(() => {
+    if (error) {
+      log.error(error);
+    }
+  }, [error]);
+
+  if (process.env.NODE_ENV === 'development') {
+    return <ErrorFallback title='Plank Error' error={error} />;
+  } else {
+    const errorString = error?.toString() ?? '';
+    return (
+      <div
+        role='alert'
+        data-testid='plank-content-error'
+        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')}
+        </p>
+      </div>
+    );
+  }
+};