@dxos/plugin-deck 0.8.4-main.c1de068 → 0.8.4-main.c351d160a8

package/src/components/Plank/Plank.tsx

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { useFocusFinders } from '@fluentui/react-tabster';
 import React, {
   type KeyboardEvent,
   type PropsWithChildren,
@@ -12,33 +13,37 @@ import React, {
   useRef,
 } from 'react';
 
-import {
-  LayoutAction,
-  Surface,
-  createIntent,
-  useCapability,
-  useAppGraph,
-  useIntentDispatcher,
-} from '@dxos/app-framework';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation, getCompanionVariant } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { debounce } from '@dxos/async';
-import { useNode, type Node } from '@dxos/plugin-graph';
-import { ATTENDABLE_PATH_SEPARATOR, useAttentionAttributes } from '@dxos/react-ui-attention';
+import { type Node, useNode } from '@dxos/plugin-graph';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
 import { StackItem, railGridHorizontal } from '@dxos/react-ui-stack';
-import { mainIntrinsicSize, mx } from '@dxos/react-ui-theme';
+import { mainIntrinsicSize, mx } from '@dxos/ui-theme';
+
+import { useCompanions, useDeckState, useMainSize, useSelectedCompanion } from '../../hooks';
+import {
+  DeckOperation,
+  type DeckSettingsProps,
+  type LayoutMode,
+  PLANK_COMPANION_TYPE,
+  type ResolvedPart,
+} from '../../types';
 
-import { PlankContentError, PlankError } from './PlankError';
+import { PlankError, PlankErrorFallback } from './PlankError';
 import { PlankHeading } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
-import { DeckCapabilities } from '../../capabilities';
-import { useMainSize, useCompanions } from '../../hooks';
-import { parseEntryId } from '../../layout';
-import { DeckAction, type LayoutMode, type ResolvedPart, type DeckSettingsProps } from '../../types';
 
 const UNKNOWN_ID = 'unknown_id';
 
+//
+// Plank
+//
+
 export type PlankProps = Pick<PlankComponentProps, 'layoutMode' | 'part' | 'path' | 'order' | 'active' | 'settings'> & {
   id?: string;
-  companionId?: string;
+  companionVariant?: string;
 };
 
 // TODO(burdon): Factor out conditional rendering.
@@ -49,25 +54,31 @@ export type PlankProps = Pick<PlankComponentProps, 'layoutMode' | 'part' | 'path
 //  benefits. I think where we anticipate users will definitely want to quickly switch between showing and hiding entire
 //  articles, over the (again probably large) performance benefit that unmounting them would confer, we can mount and
 //  hide them, but I think that scenario in its most unambiguous form is probably rare. You could extrapolate
-//  the scenario to include all “potential” planks such as companions, which we could keep mounted and hidden, but I
-//  don’t think the resulting performance would be acceptable. I think the real issue is “perceived performance” which
+//  the scenario to include all "potential" planks such as companions, which we could keep mounted and hidden, but I
+//  don't think the resulting performance would be acceptable. I think the real issue is "perceived performance" which
 //  has mitigations that are in between mounting and un-mounting since both of those have tradeoffs; we may need one or more
-//  “partially-mounted” experiences, like loading skeletons at the simple end, or screenshots of “sleeping” planks at
+//  "partially-mounted" experiences, like loading skeletons at the simple end, or screenshots of "sleeping" planks at
 //  the advanced end.
 
 /**
  * A Plank is the main container for surfaces within a Deck.
  * It may be paired with a companion plank that enables the user to select one of multiple companion surfaces.
  */
-export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProps) => {
+export const Plank = memo(({ id = UNKNOWN_ID, companionVariant, ...props }: PlankProps) => {
   const { graph } = useAppGraph();
   const node = useNode(graph, id);
   const companions = useCompanions(id);
-  const currentCompanion = companions.find(({ id }) => id === companionId);
-  const hasCompanion = !!(companionId && currentCompanion);
+  const { companionId } = useSelectedCompanion(companions, companionVariant);
+  const resolvedCompanionId = companionVariant ? companionId : undefined;
+  const currentCompanion = companions.find(({ id }) => id === resolvedCompanionId);
+  const hasCompanion = !!(resolvedCompanionId && currentCompanion);
 
   return (
-    <PlankContainer solo={props.part === 'solo'} companion={hasCompanion}>
+    <PlankContainer
+      solo={props.part === 'solo'}
+      companion={hasCompanion}
+      encapsulate={!!props.settings?.encapsulatedPlanks}
+    >
       <PlankComponent
         id={id}
         node={node}
@@ -78,7 +89,7 @@ export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProp
       />
       {hasCompanion && (
         <PlankComponent
-          id={companionId}
+          id={resolvedCompanionId}
           node={currentCompanion}
           primary={node}
           companions={companions}
@@ -91,7 +102,13 @@ export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProp
   );
 });
 
-const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo: boolean; companion: boolean }>) => {
+//
+// PlankContainer
+//
+
+type PlankContainerProps = PropsWithChildren<{ solo: boolean; companion: boolean; encapsulate: boolean }>;
+
+const PlankContainer = ({ children, solo, companion, encapsulate }: PlankContainerProps) => {
   const sizeAttrs = useMainSize();
   if (!solo) {
     return children;
@@ -101,7 +118,14 @@ const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo:
   return (
     <div
       role='none'
-      className={mx('absolute inset-0 grid', companion && 'grid-cols-[1fr_1fr]', railGridHorizontal, mainIntrinsicSize)}
+      data-popover-collision-boundary={true}
+      className={mx(
+        'absolute inset-(--main-spacing) grid',
+        encapsulate && 'border border-separator rounded-sm overflow-hidden',
+        companion && 'grid-cols-[6fr_4fr]', // TODO(burdon): Resize.
+        railGridHorizontal,
+        mainIntrinsicSize,
+      )}
       {...sizeAttrs}
     >
       {children}
@@ -109,6 +133,10 @@ const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo:
   );
 };
 
+//
+// PlankComponent
+//
+
 type PlankComponentProps = {
   layoutMode: LayoutMode;
   id: string;
@@ -116,11 +144,10 @@ type PlankComponentProps = {
   path?: string[];
   order?: number;
   active?: string[];
-  // TODO(burdon): Change to role?
   companioned?: 'primary' | 'companion';
-  node?: Node;
-  primary?: Node;
-  companions?: Node[];
+  node?: Node.Node;
+  primary?: Node.Node;
+  companions?: Node.Node[];
   settings?: DeckSettingsProps;
 };
 
@@ -138,8 +165,10 @@ const PlankComponent = memo(
     companions,
     settings,
   }: PlankComponentProps) => {
-    const { dispatchPromise: dispatch } = useIntentDispatcher();
-    const { deck, popoverAnchorId, scrollIntoView } = useCapability(DeckCapabilities.DeckState);
+    const { invokePromise } = useOperationInvoker();
+    const { state, deck } = useDeckState();
+    const { popoverAnchorId, scrollIntoView } = state;
+    const { findFirstFocusable } = useFocusFinders();
     const canResize = layoutMode === 'deck';
 
     const attentionAttrs = useAttentionAttributes(primary?.id ?? id);
@@ -150,35 +179,38 @@ const PlankComponent = memo(
 
     const rootElement = useRef<HTMLDivElement | null>(null);
 
-    const { variant } = parseEntryId(id);
-    const sizeKey = `${id.split('+')[0]}${variant ? `${ATTENDABLE_PATH_SEPARATOR}${variant}` : ''}`;
+    const variant = node?.type === PLANK_COMPANION_TYPE ? getCompanionVariant(id) : undefined;
+    const sizeKey = id.split('+')[0];
     const size = deck.plankSizing[sizeKey] as number | undefined;
 
     const handleSizeChange = useCallback(
       debounce((nextSize: number) => {
-        return dispatch(createIntent(DeckAction.UpdatePlankSize, { id: sizeKey, size: nextSize }));
+        return invokePromise(DeckOperation.UpdatePlankSize, { id: sizeKey, size: nextSize });
       }, 200),
-      [dispatch, sizeKey],
+      [invokePromise, sizeKey],
     );
 
-    // TODO(thure): Tabster’s focus group should handle moving focus to Main, but something is blocking it.
+    // 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 && event.key === 'Escape') {
-        rootElement.current?.closest('main')?.focus();
+      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) {
-        // TODO(wittjosiah): When focused on page load, the focus is always visible.
-        //   Forcing focus to something smaller than the plank prevents large focus ring in the interim.
-        const focusable = rootElement.current?.querySelector('button') || rootElement.current;
-        focusable?.focus({ preventScroll: true });
-        layoutMode === 'deck' && focusable?.scrollIntoView({ behavior: 'smooth', inline: 'center' });
+        layoutMode === 'deck' && rootElement.current?.scrollIntoView({ behavior: 'smooth', inline: 'center' });
         // Clear the scroll into view state once it has been actioned.
-        void dispatch(createIntent(LayoutAction.ScrollIntoView, { part: 'current', subject: undefined }));
+        void invokePromise(LayoutOperation.ScrollIntoView, { subject: undefined });
       }
-    }, [id, scrollIntoView, layoutMode]);
+    }, [id, scrollIntoView, layoutMode, invokePromise]);
 
     const isSolo = layoutMode.startsWith('solo') && part === 'solo';
     const isAttendable =
@@ -189,34 +221,42 @@ const PlankComponent = memo(
     const data = useMemo(
       () =>
         node && {
+          attendableId: id,
           subject: node.data,
           companionTo: primary?.data,
+          properties: node.properties,
           variant,
           path,
           popoverAnchorId,
         },
-      [node, node?.data, path, popoverAnchorId, primary?.data, variant],
+      [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 className = mx(
-      'attention-surface relative dx-focus-ring-inset-over-all density-coarse',
-      isSolo && mainIntrinsicSize,
-      isSolo && railGridHorizontal,
+      '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 === 'deck' && (companioned === 'companion' ? '!border-separator border-ie' : '!border-separator border-li'),
-      part.startsWith('solo-') && 'row-span-2 grid-rows-subgrid min-is-0',
-      part === 'solo-companion' && '!border-separator border-is',
+      part.startsWith('solo-') && 'grid-rows-subgrid row-span-2 min-w-0',
+      fullscreen && 'grid-rows-1',
+      part === 'deck' && (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',
     );
 
     return (
       <Root
         ref={rootElement}
         data-testid='deck.plank'
+        data-popover-collision-boundary={true}
         tabIndex={0}
         {...(part.startsWith('solo')
           ? ({ ...sizeAttrs, className } as any)
@@ -233,32 +273,33 @@ const PlankComponent = memo(
       >
         {node ? (
           <>
-            <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
+            {!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={PlankContentError}
+              fallback={PlankErrorFallback}
               placeholder={placeholder}
             />
           </>
         ) : (
           <PlankError id={id} part={part} />
         )}
-
         {canResize && <StackItem.ResizeHandle />}
       </Root>
     );

package/src/components/Plank/PlankControls.tsx

@@ -4,12 +4,11 @@
 
 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, DeckOperation, type LayoutMode } from '../../types';
 
 export type PlankControlHandler = (event: DeckAction.PartAdjustment) => void;
 
@@ -32,10 +31,10 @@ export type PlankControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
 };
 
 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} />;
+  return <IconButton label={label} icon={icon} iconOnly variant='ghost' tooltipSide='bottom' {...props} />;
 };
 
-const plankControlSpacing = 'pli-2';
+const plankControlSpacing = 'px-2';
 
 type PlankComplimentControlsProps = {
   primary?: string;
@@ -43,14 +42,13 @@ type PlankComplimentControlsProps = {
 
 export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankComplimentControlsProps>(
   ({ 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')}
           variant='ghost'
@@ -71,14 +69,14 @@ 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 && (

package/src/components/Plank/PlankError.tsx

@@ -5,24 +5,13 @@
 import React, { useEffect, useState } from 'react';
 
 import { type Node } from '@dxos/plugin-graph';
-import { useTranslation } from '@dxos/react-ui';
-import { descriptionMessage, mx } from '@dxos/react-ui-theme';
+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';
-import { DECK_PLUGIN } from '../../meta';
-
-export const PlankContentError = ({ error }: { error?: Error }) => {
-  const { t } = useTranslation(DECK_PLUGIN);
-  const errorString = error?.toString() ?? '';
-  return (
-    <div role='none' className='overflow-y-auto p-8 attention-surface grid place-items-center'>
-      <p role='alert' className={mx(descriptionMessage, 'break-all rounded-md p-4')}>
-        {error ? errorString : t('error fallback message')}
-      </p>
-    </div>
-  );
-};
 
 export const PlankError = ({
   id,
@@ -32,17 +21,43 @@ export const PlankError = ({
 }: {
   id: string;
   part: PlankHeadingProps['part'];
-  node?: Node;
+  node?: Node.Node;
   error?: Error;
 }) => {
   const [timedOut, setTimedOut] = useState(false);
   useEffect(() => {
-    setTimeout(() => setTimedOut(true), 5e3);
+    const timer = setTimeout(() => setTimedOut(true), 5_000);
+    return () => clearTimeout(timer);
   }, []);
+
   return (
     <>
       <PlankHeading id={id} part={part} node={node} pending={!timedOut} />
-      {timedOut ? <PlankContentError error={error} /> : <PlankLoading />}
+      {timedOut ? <PlankErrorFallback error={error} /> : <PlankLoading />}
     </>
   );
 };
+
+/**
+ * User facing error fallback.
+ */
+export const PlankErrorFallback = ({ error }: ErrorFallbackProps) => {
+  const { t } = useTranslation(meta.id);
+
+  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>
+    );
+  }
+};