@dxos/plugin-deck 0.8.1-main.ba2dec9 → 0.8.1-staging.5be625a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-deck",
-  "version": "0.8.1-main.ba2dec9",
+  "version": "0.8.1-staging.5be625a",
   "description": "DXOS Surface plugin for the main application layout.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -31,33 +31,33 @@
     "src"
   ],
   "dependencies": {
-    "@fluentui/react-tabster": "9.23.3",
+    "@fluentui/react-tabster": "^9.24.2",
     "@preact/signals-core": "^1.6.0",
     "effect": "3.13.3",
     "immer": "^10.1.1",
-    "@dxos/app-framework": "0.8.1-main.ba2dec9",
-    "@dxos/debug": "0.8.1-main.ba2dec9",
-    "@dxos/async": "0.8.1-main.ba2dec9",
-    "@dxos/echo-schema": "0.8.1-main.ba2dec9",
-    "@dxos/echo-signals": "0.8.1-main.ba2dec9",
-    "@dxos/artifact": "0.8.1-main.ba2dec9",
-    "@dxos/invariant": "0.8.1-main.ba2dec9",
-    "@dxos/live-object": "0.8.1-main.ba2dec9",
-    "@dxos/log": "0.8.1-main.ba2dec9",
-    "@dxos/keyboard": "0.8.1-main.ba2dec9",
-    "@dxos/local-storage": "0.8.1-main.ba2dec9",
-    "@dxos/plugin-attention": "0.8.1-main.ba2dec9",
-    "@dxos/plugin-client": "0.8.1-main.ba2dec9",
-    "@dxos/plugin-graph": "0.8.1-main.ba2dec9",
-    "@dxos/plugin-observability": "0.8.1-main.ba2dec9",
-    "@dxos/plugin-theme": "0.8.1-main.ba2dec9",
-    "@dxos/react-client": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui-attention": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui-form": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui-tabs": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui-stack": "0.8.1-main.ba2dec9",
-    "@dxos/util": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui-text-tooltip": "0.8.1-main.ba2dec9"
+    "@dxos/app-framework": "0.8.1-staging.5be625a",
+    "@dxos/artifact": "0.8.1-staging.5be625a",
+    "@dxos/debug": "0.8.1-staging.5be625a",
+    "@dxos/async": "0.8.1-staging.5be625a",
+    "@dxos/echo-signals": "0.8.1-staging.5be625a",
+    "@dxos/invariant": "0.8.1-staging.5be625a",
+    "@dxos/echo-schema": "0.8.1-staging.5be625a",
+    "@dxos/keyboard": "0.8.1-staging.5be625a",
+    "@dxos/live-object": "0.8.1-staging.5be625a",
+    "@dxos/local-storage": "0.8.1-staging.5be625a",
+    "@dxos/log": "0.8.1-staging.5be625a",
+    "@dxos/plugin-attention": "0.8.1-staging.5be625a",
+    "@dxos/plugin-client": "0.8.1-staging.5be625a",
+    "@dxos/plugin-graph": "0.8.1-staging.5be625a",
+    "@dxos/plugin-observability": "0.8.1-staging.5be625a",
+    "@dxos/plugin-theme": "0.8.1-staging.5be625a",
+    "@dxos/react-client": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-attention": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-form": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-text-tooltip": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-tabs": "0.8.1-staging.5be625a",
+    "@dxos/util": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-stack": "0.8.1-staging.5be625a"
   },
   "devDependencies": {
     "@phosphor-icons/react": "^2.1.5",
@@ -66,16 +66,16 @@
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
     "vite": "5.4.7",
-    "@dxos/react-ui": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui-theme": "0.8.1-main.ba2dec9",
-    "@dxos/storybook-utils": "0.8.1-main.ba2dec9"
+    "@dxos/react-ui": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-theme": "0.8.1-staging.5be625a",
+    "@dxos/storybook-utils": "0.8.1-staging.5be625a"
   },
   "peerDependencies": {
     "@phosphor-icons/react": "^2.0.5",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "@dxos/react-ui-theme": "0.8.1-main.ba2dec9",
-    "@dxos/react-ui": "0.8.1-main.ba2dec9"
+    "@dxos/react-ui": "0.8.1-staging.5be625a",
+    "@dxos/react-ui-theme": "0.8.1-staging.5be625a"
   },
   "publishConfig": {
     "access": "public"

package/src/capabilities/intent-resolver.ts

@@ -16,6 +16,7 @@ import {
   chain,
 } from '@dxos/app-framework';
 import { getTypename, S } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
 import { isReactiveObject } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { AttentionCapabilities } from '@dxos/plugin-attention';
@@ -25,7 +26,7 @@ import { isNonNullable } from '@dxos/util';
 import { DeckCapabilities } from './capabilities';
 import { closeEntry, incrementPlank, openEntry } from '../layout';
 import { DECK_PLUGIN } from '../meta';
-import { DeckAction, type LayoutMode, type DeckSettingsProps, isLayoutMode, getMode } from '../types';
+import { DeckAction, type LayoutMode, type DeckSettingsProps, isLayoutMode, getMode, defaultDeck } from '../types';
 import { setActive } from '../util';
 
 export default (context: PluginsContext) =>
@@ -201,7 +202,7 @@ export default (context: PluginsContext) =>
           }
           state.activeDeck = subject;
           if (!state.decks[subject]) {
-            state.decks[subject] = { initialized: false, active: [], inactive: [], fullscreen: false, plankSizing: {} };
+            state.decks[subject] = { ...defaultDeck };
           }
         });
 
@@ -287,8 +288,16 @@ export default (context: PluginsContext) =>
         const active = state.deck.solo ? [state.deck.solo] : state.deck.active;
         const next = subject.reduce((acc, id) => closeEntry(acc, id), active);
         const toAttend = setActive({ next, state, attention });
+
+        const clearCompanionIntents = subject
+          .filter((id) => state.deck.activeCompanions && id in state.deck.activeCompanions)
+          .map((primary) => createIntent(DeckAction.ChangeCompanion, { primary, companion: null }));
+
         return {
-          intents: toAttend ? [createIntent(LayoutAction.ScrollIntoView, { part: 'current', subject: toAttend })] : [],
+          intents: [
+            ...clearCompanionIntents,
+            ...(toAttend ? [createIntent(LayoutAction.ScrollIntoView, { part: 'current', subject: toAttend })] : []),
+          ],
         };
       },
     }),
@@ -321,6 +330,23 @@ export default (context: PluginsContext) =>
         state.deck.plankSizing[data.id] = data.size;
       },
     }),
+    createResolver({
+      intent: DeckAction.ChangeCompanion,
+      resolve: (data) => {
+        const state = context.requestCapability(DeckCapabilities.MutableDeckState);
+        // TODO(thure): Reactivity only works when creating a lexically new `activeCompanions`… Are these not proxy objects?
+        if (data.companion === null) {
+          const { [data.primary]: _, ...nextActiveCompanions } = state.deck.activeCompanions ?? {};
+          state.deck.activeCompanions = nextActiveCompanions;
+        } else {
+          invariant(data.companion !== data.primary);
+          state.deck.activeCompanions = {
+            ...state.deck.activeCompanions,
+            [data.primary]: data.companion,
+          };
+        }
+      },
+    }),
     createResolver({
       intent: DeckAction.Adjust,
       resolve: (adjustment) => {

package/src/capabilities/state.ts

@@ -10,7 +10,7 @@ import { type SidebarState } from '@dxos/react-ui';
 
 import { DeckCapabilities } from './capabilities';
 import { DECK_PLUGIN } from '../meta';
-import { getMode, type Deck, type DeckState } from '../types';
+import { getMode, type Deck, type DeckState, defaultDeck } from '../types';
 
 const boolean = /true|false/;
 
@@ -48,14 +48,7 @@ export default () => {
     activeDeck: 'default',
     previousDeck: 'default',
     decks: {
-      default: {
-        initialized: false,
-        active: [],
-        inactive: [],
-        fullscreen: false,
-        solo: undefined,
-        plankSizing: {},
-      },
+      default: { ...defaultDeck },
     },
     get deck() {
       const deck = this.decks[this.activeDeck];

package/src/capabilities/tools.ts

@@ -14,12 +14,14 @@ import { S } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 
 import { meta } from '../meta';
+import { DeckAction } from '../types';
 
 // TODO(burdon): Factor out.
 declare global {
   interface ToolContextExtensions {
     dispatch?: PromiseIntentDispatcher;
     pivotId?: string;
+    part?: 'deck' | 'dialog';
   }
 }
 
@@ -27,10 +29,9 @@ export default () =>
   contributes(Capabilities.Tools, [
     defineTool(meta.id, {
       name: 'show',
-      // TODO(ZaymonFC): We should update the prompt to teach the LLM the difference between object ids and fully qualified ids.
       description: `
-        Show an item in the app. Use this tool to open an artifact. 
-        When supplying IDs to show, they must be fully qualified like space:object.
+        Show an item as a companion to an existing plank. This will make the item appear alongside the primary content.
+        When supplying IDs, they must be fully qualified like space:object.
       `,
       caption: 'Showing item...',
       // TODO(wittjosiah): Refactor Layout/Navigation/Deck actions so that they can be used directly.
@@ -38,29 +39,40 @@ export default () =>
         id: S.String.annotations({
           description: 'The ID of the item to show.',
         }),
-        pivotId: S.optional(
-          S.String.annotations({
-            description: 'The ID of the chat. If provided, the item will be added after the pivot item.',
-          }),
-        ),
       }),
       execute: async ({ id }, { extensions }) => {
+        invariant(extensions?.pivotId, 'No pivot ID');
         invariant(extensions?.dispatch, 'No intent dispatcher');
-        const { data, error } = await extensions.dispatch(
-          createIntent(LayoutAction.Open, {
-            subject: [id],
-            part: 'main',
-            options: {
-              pivotId: extensions.pivotId,
-              positioning: 'end',
-            },
-          }),
-        );
-        if (error) {
-          return ToolResult.Error(error.message);
-        }
 
-        return ToolResult.Success(data);
+        if (extensions.part === 'deck') {
+          const { data, error } = await extensions.dispatch(
+            createIntent(DeckAction.ChangeCompanion, {
+              primary: extensions.pivotId,
+              companion: id,
+            }),
+          );
+          if (error) {
+            return ToolResult.Error(error.message);
+          }
+
+          return ToolResult.Success(data);
+        } else {
+          const { data, error } = await extensions.dispatch(
+            createIntent(LayoutAction.Open, {
+              subject: [id],
+              part: 'main',
+              options: {
+                pivotId: extensions.pivotId,
+                positioning: 'end',
+              },
+            }),
+          );
+          if (error) {
+            return ToolResult.Error(error.message);
+          }
+
+          return ToolResult.Success(data);
+        }
       },
     }),
   ]);

package/src/capabilities/url-handler.ts

@@ -6,6 +6,7 @@ import { Capabilities, contributes, createIntent, LayoutAction, type PluginsCont
 import { scheduledEffect } from '@dxos/echo-signals/core';
 
 import { DeckCapabilities } from './capabilities';
+import { defaultDeck } from '../types';
 
 // TODO(wittjosiah): Cleanup the url handling. May justify introducing routing capabilities.
 export default async (context: PluginsContext) => {
@@ -17,14 +18,7 @@ export default async (context: PluginsContext) => {
     if (pathname === '/reset') {
       state.activeDeck = 'default';
       state.decks = {
-        default: {
-          initialized: false,
-          active: [],
-          inactive: [],
-          fullscreen: false,
-          solo: undefined,
-          plankSizing: {},
-        },
+        default: { ...defaultDeck },
       };
       window.location.pathname = '/';
       return;

package/src/components/DeckLayout/DeckLayout.tsx

@@ -19,9 +19,9 @@ import {
   Dialog as NaturalDialog,
   Main,
   Popover,
-  useOnTransition,
   type MainProps,
   useMediaQuery,
+  useOnTransition,
 } from '@dxos/react-ui';
 import { Stack, StackContext, DEFAULT_HORIZONTAL_SIZE } from '@dxos/react-ui-stack';
 import { mainPaddingTransitions } from '@dxos/react-ui-theme';
@@ -48,8 +48,8 @@ export type DeckLayoutProps = {
   onDismissToast: (id: string) => void;
 };
 
-const PlankSeparator = ({ index }: { index: number }) =>
-  index > 0 ? <span role='separator' className='row-span-2 bg-deck is-4' style={{ gridColumn: index * 2 }} /> : null;
+const PlankSeparator = ({ order }: { order: number }) =>
+  order > 0 ? <span role='separator' className='row-span-2 bg-deck is-4' style={{ gridColumn: order }} /> : null;
 
 export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayoutProps) => {
   const { dispatchPromise: dispatch } = useIntentDispatcher();
@@ -68,7 +68,7 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
     deck,
     toasts,
   } = context;
-  const { active, fullscreen, solo, plankSizing } = deck;
+  const { active, activeCompanions, fullscreen, solo, plankSizing } = deck;
   const breakpoint = useBreakpoints();
   const topbar = layoutAppliesTopbar(breakpoint);
   const hoistStatusbar = useHoistStatusbar(breakpoint);
@@ -187,6 +187,17 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
   );
   const handlePopoverClose = useCallback(() => handlePopoverOpenChange(false), [handlePopoverOpenChange]);
 
+  const { order, itemsCount }: { order: Record<string, number>; itemsCount: number } = useMemo(() => {
+    return active.reduce(
+      (acc: { order: Record<string, number>; itemsCount: number }, entryId) => {
+        acc.order[entryId] = acc.itemsCount + 1;
+        acc.itemsCount += activeCompanions?.[entryId] ? 3 : 2;
+        return acc;
+      },
+      { order: {}, itemsCount: 0 },
+    );
+  }, [active, activeCompanions]);
+
   return (
     <Popover.Root modal open={!!(popoverAnchorId && delayedPopoverVisibility)} onOpenChange={handlePopoverOpenChange}>
       <ActiveNode />
@@ -253,14 +264,21 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
                   size='contain'
                   classNames={['absolute inset-block-0 -inset-inline-px', mainPaddingTransitions]}
                   onScroll={handleScroll}
-                  itemsCount={2 * (active.length ?? 0) - 1}
+                  itemsCount={itemsCount - 1}
                   style={padding}
                   ref={deckRef}
                 >
-                  {active.map((entryId, index) => (
+                  {active.map((entryId) => (
                     <Fragment key={entryId}>
-                      <PlankSeparator index={index} />
-                      <Plank id={entryId} part='deck' order={index * 2 + 1} active={active} layoutMode={layoutMode} />
+                      <PlankSeparator order={order[entryId] - 1} />
+                      <Plank
+                        id={entryId}
+                        companionId={activeCompanions?.[entryId]}
+                        part='deck'
+                        order={order[entryId]}
+                        active={active}
+                        layoutMode={layoutMode}
+                      />
                     </Fragment>
                   ))}
                 </Stack>
@@ -273,7 +291,12 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
                 {!topbar && <ToggleSidebarButton classNames={fixedSidebarToggleStyles} />}
                 {!topbar && <ToggleComplementarySidebarButton classNames={fixedComplementarySidebarToggleStyles} />}
                 <StackContext.Provider value={{ size: 'contain', orientation: 'horizontal', rail: true }}>
-                  <Plank id={solo} part='solo' layoutMode={layoutMode} />
+                  <Plank
+                    id={solo}
+                    companionId={solo ? activeCompanions?.[solo] : undefined}
+                    part='solo'
+                    layoutMode={layoutMode}
+                  />
                 </StackContext.Provider>
               </div>
             </Main.Content>
@@ -304,7 +327,8 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
         onOpenChange={(nextOpen) => (context.dialogOpen = nextOpen)}
       >
         {dialogBlockAlign === 'end' ? (
-          <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} />
+          // TODO(burdon): Placeholder creates a suspense boundary; replace with defaults.
+          <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} placeholder={<div />} />
         ) : (
           <Dialog.Overlay blockAlign={dialogBlockAlign}>
             <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} />

package/src/components/DeckLayout/NodePlankHeading.tsx

@@ -10,21 +10,24 @@ import { Icon, 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 { PlankControls } from './PlankControls';
+import { PlankCompanionControls, PlankControls } from './PlankControls';
 import { DECK_PLUGIN } from '../../meta';
-import { DeckAction, SLUG_PATH_SEPARATOR } from '../../types';
+import { DeckAction, type ResolvedPart, SLUG_PATH_SEPARATOR } from '../../types';
 import { useBreakpoints } from '../../util';
 import { soloInlinePadding } from '../fragments';
 
 export type NodePlankHeadingProps = {
   id: string;
-  part: 'solo' | 'deck' | 'complementary';
+  part: ResolvedPart;
   node?: Node;
   canIncrementStart?: boolean;
   canIncrementEnd?: boolean;
   popoverAnchorId?: string;
   pending?: boolean;
   actions?: StackItemSigilAction[];
+  companioned?: 'primary' | 'companion';
+  primaryId?: string;
+  surfaceVariant?: string;
 };
 
 export const NodePlankHeading = memo(
@@ -37,6 +40,9 @@ export const NodePlankHeading = memo(
     popoverAnchorId,
     pending,
     actions = [],
+    companioned,
+    primaryId,
+    surfaceVariant,
   }: NodePlankHeadingProps) => {
     const { t } = useTranslation(DECK_PLUGIN);
     const { graph } = useAppGraph();
@@ -44,7 +50,14 @@ export const NodePlankHeading = memo(
     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(
+          (surfaceVariant
+            ? Array.isArray(node?.properties?.label)
+              ? [`${surfaceVariant} plank heading`, node.properties.label[1]]
+              : ['companion plank heading fallback label', { ns: DECK_PLUGIN }]
+            : node?.properties?.label) ?? ['plank heading fallback label', { ns: DECK_PLUGIN }],
+          t,
+        );
     const { dispatchPromise: dispatch } = useIntentDispatcher();
     const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${DECK_PLUGIN}/${node.id}` ? Popover.Anchor : Fragment;
 
@@ -105,27 +118,30 @@ export const NodePlankHeading = memo(
         classNames={[
           'plb-1 border-be border-separator items-stretch gap-1 sticky inline-start-12 app-drag',
           part === 'solo' ? soloInlinePadding : 'pli-1',
+          surfaceVariant && 'pis-3',
         ]}
       >
-        <ActionRoot>
-          {node && sigilActions ? (
-            <StackItem.Sigil
-              icon={icon}
-              related={part === 'complementary'}
-              attendableId={attendableId}
-              triggerLabel={t('actions menu label')}
-              actions={sigilActions}
-              onAction={handleAction}
-            >
-              <Surface role='menu-footer' data={{ subject: node.data }} />
-            </StackItem.Sigil>
-          ) : (
-            <StackItem.SigilButton>
-              <span className='sr-only'>{label}</span>
-              <Icon icon={icon} size={5} />
-            </StackItem.SigilButton>
-          )}
-        </ActionRoot>
+        {!surfaceVariant && (
+          <ActionRoot>
+            {node && sigilActions ? (
+              <StackItem.Sigil
+                icon={icon}
+                related={part === 'complementary'}
+                attendableId={attendableId}
+                triggerLabel={t('actions menu label')}
+                actions={sigilActions}
+                onAction={handleAction}
+              >
+                <Surface role='menu-footer' data={{ subject: node.data }} />
+              </StackItem.Sigil>
+            ) : (
+              <StackItem.SigilButton>
+                <span className='sr-only'>{label}</span>
+                <Icon icon={icon} size={5} />
+              </StackItem.SigilButton>
+            )}
+          </ActionRoot>
+        )}
         <TextTooltip text={label} onlyWhenTruncating>
           <StackItem.HeadingLabel
             attendableId={attendableId}
@@ -136,12 +152,16 @@ export const NodePlankHeading = memo(
           </StackItem.HeadingLabel>
         </TextTooltip>
         {node && part !== 'complementary' && <Surface role='navbar-end' data={{ subject: node.data }} />}
-        <PlankControls
-          capabilities={capabilities}
-          isSolo={part === 'solo'}
-          onClick={handlePlankAction}
-          close={part === 'complementary' ? 'minify-end' : true}
-        />
+        {companioned === 'companion' ? (
+          <PlankCompanionControls primary={surfaceVariant ? id : primaryId} />
+        ) : (
+          <PlankControls
+            capabilities={capabilities}
+            isSolo={part === 'solo'}
+            onClick={handlePlankAction}
+            close={part === 'complementary' ? 'minify-end' : true}
+          />
+        )}
       </StackItem.Heading>
     );
   },