@dxos/plugin-deck 0.8.4-main.1f223c7 → 0.8.4-main.2244d791bb

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,24 +13,18 @@ import React, {
   useRef,
 } from 'react';
 
-import {
-  LayoutAction,
-  Surface,
-  createIntent,
-  useAppGraph,
-  useCapability,
-  useIntentDispatcher,
-} from '@dxos/app-framework';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { debounce } from '@dxos/async';
 import { type Node, useNode } from '@dxos/plugin-graph';
 import { ATTENDABLE_PATH_SEPARATOR, 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 { DeckCapabilities } from '../../capabilities';
-import { useCompanions, useMainSize } from '../../hooks';
+import { useCompanions, useDeckState, useMainSize } from '../../hooks';
 import { parseEntryId } from '../../layout';
-import { DeckAction, type DeckSettingsProps, type LayoutMode, type ResolvedPart } from '../../types';
+import { DeckOperation, type DeckSettingsProps, type LayoutMode, type ResolvedPart } from '../../types';
 
 import { PlankContentError, PlankError } from './PlankError';
 import { PlankHeading } from './PlankHeading';
@@ -37,6 +32,10 @@ import { PlankLoading } from './PlankLoading';
 
 const UNKNOWN_ID = 'unknown_id';
 
+//
+// Plank
+//
+
 export type PlankProps = Pick<PlankComponentProps, 'layoutMode' | 'part' | 'path' | 'order' | 'active' | 'settings'> & {
   id?: string;
   companionId?: string;
@@ -50,10 +49,10 @@ 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.
 
 /**
@@ -68,7 +67,11 @@ export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProp
   const hasCompanion = !!(companionId && 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}
@@ -92,7 +95,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;
@@ -102,7 +111,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 overflow-hidden',
+        companion && 'grid-cols-[6fr_4fr]', // TODO(burdon): Resize.
+        railGridHorizontal,
+        mainIntrinsicSize,
+      )}
       {...sizeAttrs}
     >
       {children}
@@ -110,6 +126,10 @@ const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo:
   );
 };
 
+//
+// PlankComponent
+//
+
 type PlankComponentProps = {
   layoutMode: LayoutMode;
   id: string;
@@ -117,11 +137,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;
 };
 
@@ -139,8 +158,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);
@@ -157,29 +178,32 @@ const PlankComponent = memo(
 
     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 =
@@ -190,34 +214,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,
       isSolo && 'absolute inset-0',
+      isSolo && mainIntrinsicSize,
+      railGridHorizontal,
       part.startsWith('solo') && 'grid',
+      part.startsWith('solo-') && 'grid-rows-subgrid row-span-2 min-is-0',
+      fullscreen && 'grid-rows-1',
       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',
+      settings?.encapsulatedPlanks &&
+        !part.startsWith('solo') &&
+        'mli-[--main-spacing] !border-separator border rounded overflow-hidden',
     );
 
     return (
       <Root
         ref={rootElement}
         data-testid='deck.plank'
+        data-popover-collision-boundary={true}
         tabIndex={0}
         {...(part.startsWith('solo')
           ? ({ ...sizeAttrs, className } as any)
@@ -234,20 +266,22 @@ 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}
@@ -259,7 +293,6 @@ const PlankComponent = memo(
         ) : (
           <PlankError id={id} part={part} />
         )}
-
         {canResize && <StackItem.ResizeHandle />}
       </Root>
     );

package/src/components/Plank/PlankControls.tsx

@@ -4,12 +4,12 @@
 
 import React, { forwardRef, useCallback } from 'react';
 
-import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+import { useOperationInvoker } from '@dxos/app-framework/ui';
 import { invariant } from '@dxos/invariant';
 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,7 +32,7 @@ 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';
@@ -43,12 +43,12 @@ 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, { primary, companion: null });
+    }, [invokePromise, primary]);
     return (
       <div ref={forwardedRef} className='contents app-no-drag'>
         <PlankControl
@@ -71,7 +71,7 @@ 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;
 

package/src/components/Plank/PlankError.tsx

@@ -6,15 +6,15 @@ 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 { descriptionMessage, mx } from '@dxos/ui-theme';
 
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 
 import { PlankHeading, type PlankHeadingProps } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
 
 export const PlankContentError = ({ error }: { error?: Error }) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
   const errorString = error?.toString() ?? '';
   return (
     <div role='none' className='overflow-y-auto p-8 attention-surface grid place-items-center'>
@@ -33,7 +33,7 @@ export const PlankError = ({
 }: {
   id: string;
   part: PlankHeadingProps['part'];
-  node?: Node;
+  node?: Node.Node;
   error?: Error;
 }) => {
   const [timedOut, setTimedOut] = useState(false);

package/src/components/Plank/PlankHeading.tsx

@@ -4,17 +4,19 @@
 
 import React, { Fragment, type MouseEvent, memo, useCallback, useEffect, useMemo } from 'react';
 
-import { LayoutAction, Surface, createIntent, useAppGraph, useIntentDispatcher } from '@dxos/app-framework';
-import { type Node } from '@dxos/plugin-graph';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Graph, type Node, useActionRunner } from '@dxos/plugin-graph';
 import { Icon, IconButton, Popover, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { StackItem, type StackItemSigilAction } from '@dxos/react-ui-stack';
 import { TextTooltip } from '@dxos/react-ui-text-tooltip';
-import { hoverableControls, hoverableFocusedWithinControls } from '@dxos/react-ui-theme';
+import { hoverableControls, hoverableFocusedWithinControls } from '@dxos/ui-theme';
 
 import { useBreakpoints } from '../../hooks';
 import { parseEntryId } from '../../layout';
-import { DECK_PLUGIN } from '../../meta';
-import { DeckAction, type LayoutMode, PLANK_COMPANION_TYPE, type ResolvedPart } from '../../types';
+import { meta } from '../../meta';
+import { DeckOperation, type LayoutMode, PLANK_COMPANION_TYPE, type ResolvedPart } from '../../types';
 import { soloInlinePadding } from '../fragments';
 
 import { PlankCompanionControls, PlankControls } from './PlankControls';
@@ -25,7 +27,7 @@ export type PlankHeadingProps = {
   id: string;
   part: ResolvedPart;
   layoutMode?: LayoutMode;
-  node?: Node;
+  node?: Node.Node;
   deckEnabled?: boolean;
   canIncrementStart?: boolean;
   canIncrementEnd?: boolean;
@@ -33,7 +35,7 @@ export type PlankHeadingProps = {
   primaryId?: string;
   pending?: boolean;
   companioned?: 'primary' | 'companion';
-  companions?: Node[];
+  companions?: Node.Node[];
   actions?: StackItemSigilAction[];
 };
 
@@ -53,14 +55,15 @@ export const PlankHeading = memo(
     layoutMode,
     actions = [],
   }: PlankHeadingProps) => {
-    const { t } = useTranslation(DECK_PLUGIN);
-    const { dispatchPromise: dispatch } = useIntentDispatcher();
+    const { t } = useTranslation(meta.id);
+    const { invokePromise, invokeSync } = useOperationInvoker();
+    const runAction = useActionRunner();
     const { graph } = useAppGraph();
     const breakpoint = useBreakpoints();
     const icon = node?.properties?.icon ?? 'ph--placeholder--regular';
     const label = pending
       ? t('pending heading')
-      : toLocalizedString(node?.properties?.label ?? ['plank heading fallback label', { ns: DECK_PLUGIN }], t);
+      : toLocalizedString(node?.properties?.label ?? ['plank heading fallback label', { ns: meta.id }], t);
 
     const isCompanionNode = node?.type === PLANK_COMPANION_TYPE;
 
@@ -68,7 +71,7 @@ export const PlankHeading = memo(
       const frame = requestAnimationFrame(() => {
         // Load actions for the node.
         if (node) {
-          void graph.expand(node.id);
+          void Graph.expand(graph, node.id);
         }
       });
 
@@ -97,60 +100,53 @@ export const PlankHeading = memo(
       } else {
         return [
           actions,
-          graph
-            .getActions(node.id)
-            .filter((a) => ['list-item', 'list-item-primary', 'heading-list-item'].includes(a.properties.disposition)),
+          Graph.getActions(graph, node.id).filter((a) =>
+            ['list-item', 'list-item-primary', 'heading-list-item'].includes(a.properties.disposition),
+          ),
         ].filter((a) => a.length > 0);
       }
     }, [actions, node, variant, graph]);
 
     const handleAction = useCallback(
       (action: StackItemSigilAction) => {
-        typeof action.data === 'function' && void action.data?.({ parent: node, caller: DECK_PLUGIN });
+        if (typeof action.data === 'function') {
+          void runAction(action as Node.Action, { parent: node, caller: meta.id });
+        }
       },
-      [node],
+      [node, runAction],
     );
 
     const handlePlankAction = useCallback(
-      (eventType: DeckAction.PartAdjustment) => {
+      (eventType: DeckOperation.PartAdjustment) => {
         if (eventType.startsWith('solo')) {
-          return dispatch(createIntent(DeckAction.Adjust, { type: eventType, id }));
+          return invokePromise(DeckOperation.Adjust, { type: eventType, id });
         } else if (eventType === 'close') {
           if (part === 'complementary') {
-            return dispatch(
-              createIntent(LayoutAction.UpdateComplementary, {
-                part: 'complementary',
-                options: { state: 'collapsed' },
-              }),
-            );
+            return invokeSync(LayoutOperation.UpdateComplementary, { state: 'collapsed' });
           } else {
-            return dispatch(
-              createIntent(LayoutAction.Close, { part: 'main', subject: [id], options: { state: false } }),
-            );
+            return invokeSync(LayoutOperation.Close, { subject: [id] });
           }
         } else {
-          return dispatch(createIntent(DeckAction.Adjust, { type: eventType, id }));
+          return invokePromise(DeckOperation.Adjust, { type: eventType, id });
         }
       },
-      [dispatch, id, part],
+      [invokePromise, invokeSync, id, part],
     );
 
-    const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${DECK_PLUGIN}/${node.id}` ? Popover.Anchor : Fragment;
+    const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${meta.id}/${node.id}` ? Popover.Anchor : Fragment;
 
     const handleTabClick = useCallback(
       (event: MouseEvent) => {
         const target = (event.target as HTMLElement).closest('[data-id]') as HTMLElement | null;
         const tabId = target?.dataset?.id;
         if (primaryId && tabId) {
-          void dispatch(
-            createIntent(DeckAction.ChangeCompanion, {
-              primary: primaryId,
-              companion: tabId,
-            }),
-          );
+          void invokePromise(DeckOperation.ChangeCompanion, {
+            primary: primaryId,
+            companion: tabId,
+          });
         }
       },
-      [primaryId],
+      [primaryId, invokePromise],
     );
 
     return (
@@ -162,7 +158,8 @@ export const PlankHeading = memo(
             ? [
                 hoverableControls,
                 hoverableFocusedWithinControls,
-                '*:transition-opacity *:opacity-[--controls-opacity] bg-transparent border-transparent transition-[background-color,border-color] hover-hover:hover:bg-headerSurface focus-within:bg-headerSurface hover-hover:hover:border-subduedSeparator focus-within:border-subduedSeparator',
+                '*:transition-opacity *:opacity-[--controls-opacity] bg-transparent border-transparent transition-[background-color,border-color]',
+                'hover-hover:hover:bg-headerSurface focus-within:bg-headerSurface hover-hover:hover:border-subduedSeparator focus-within:border-subduedSeparator',
               ]
             : []),
         ]}
@@ -178,7 +175,6 @@ export const PlankHeading = memo(
                 icon={icon}
                 iconOnly={companions.length > MAX_COMPANIONS && node?.id !== id}
                 label={toLocalizedString(label, t)}
-                size={5}
                 variant={node?.id === id ? 'primary' : 'ghost'}
                 onClick={handleTabClick}
               />
@@ -196,12 +192,12 @@ export const PlankHeading = memo(
                   actions={sigilActions}
                   onAction={handleAction}
                 >
-                  <Surface role='menu-footer' data={{ subject: node.data }} />
+                  <Surface.Surface role='menu-footer' data={{ subject: node.data }} />
                 </StackItem.Sigil>
               ) : (
                 <StackItem.SigilButton>
                   <span className='sr-only'>{label}</span>
-                  <Icon icon={icon} size={5} />
+                  <Icon icon={icon} />
                 </StackItem.SigilButton>
               )}
             </ActionRoot>
@@ -216,7 +212,7 @@ export const PlankHeading = memo(
             </TextTooltip>
           </>
         )}
-        {node && part !== 'complementary' && <Surface role='navbar-end' data={{ subject: node.data }} />}
+        {node && part !== 'complementary' && <Surface.Surface role='navbar-end' data={{ subject: node.data }} />}
         {companioned === 'companion' ? (
           <PlankCompanionControls primary={primaryId} />
         ) : (