@dxos/plugin-deck 0.8.1-main.303c73a → 0.8.1-main.81238a8

package/src/components/DeckLayout/Plank.tsx

@@ -2,7 +2,16 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { type KeyboardEvent, memo, useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+import React, {
+  Fragment,
+  type KeyboardEvent,
+  memo,
+  type PropsWithChildren,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
 
 import {
   createIntent,
@@ -17,133 +26,194 @@ import { useAttendableAttributes } from '@dxos/react-ui-attention';
 import { StackItem, railGridHorizontal } from '@dxos/react-ui-stack';
 import { mainIntrinsicSize, mx } from '@dxos/react-ui-theme';
 
-import { NodePlankHeading, type NodePlankHeadingProps } from './NodePlankHeading';
+import { NodePlankHeading } from './NodePlankHeading';
 import { PlankContentError, PlankError } from './PlankError';
 import { PlankLoading } from './PlankLoading';
 import { DeckCapabilities } from '../../capabilities';
 import { useNode, useMainSize } from '../../hooks';
-import { DeckAction, type LayoutMode } from '../../types';
+import { DeckAction, type LayoutMode, type Part, type ResolvedPart, surfaceVariantSeparator } from '../../types';
 
 const UNKNOWN_ID = 'unknown_id';
 
 export type PlankProps = {
   id?: string;
-  part: NodePlankHeadingProps['part'];
+  companionId?: string;
+  part: Part;
   path?: string[];
   order?: number;
   active?: string[];
   layoutMode: LayoutMode;
 };
 
-export const Plank = memo(({ id = UNKNOWN_ID, part, path, order, active, layoutMode }: PlankProps) => {
-  const { dispatchPromise: dispatch } = useIntentDispatcher();
-  const { deck, popoverAnchorId, scrollIntoView } = useCapability(DeckCapabilities.DeckState);
-  const { graph } = useAppGraph();
-  const node = useNode(graph, id);
-  const rootElement = useRef<HTMLDivElement | null>(null);
-  const canResize = layoutMode === 'deck';
-  const Root = part === 'solo' ? 'article' : StackItem.Root;
-
-  const attendableAttrs = useAttendableAttributes(id);
-  const index = active ? active.findIndex((entryId) => entryId === id) : 0;
-  const length = active?.length ?? 1;
-  const canIncrementStart = active && index !== undefined && index > 0 && length !== undefined && length > 1;
-  const canIncrementEnd = active && index !== undefined && index < length - 1 && length !== undefined;
-
-  const key = id.split('+')[0];
-  const size = deck.plankSizing[key] as number | undefined;
-  const setSize = useCallback(
-    debounce((nextSize: number) => {
-      return dispatch(createIntent(DeckAction.UpdatePlankSize, { id: key, size: nextSize }));
-    }, 200),
-    [dispatch, key],
-  );
-
-  // 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();
-    }
-  }, []);
-
-  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' });
-      // Clear the scroll into view state once it has been actioned.
-      void dispatch(createIntent(LayoutAction.ScrollIntoView, { part: 'current', subject: undefined }));
-    }
-  }, [id, scrollIntoView, layoutMode]);
-
-  const isSolo = layoutMode === 'solo' && part === 'solo';
-  const isAttendable = isSolo || (layoutMode === 'deck' && part === 'deck');
+type PlankImplProps = Omit<PlankProps, 'companionId' | 'part'> & {
+  part: ResolvedPart;
+  surfaceVariant?: string;
+  companioned?: 'primary' | 'companion';
+  primaryId?: string;
+};
 
+const PlankImpl = memo(
+  ({
+    id = UNKNOWN_ID,
+    part,
+    path,
+    order,
+    active,
+    layoutMode,
+    surfaceVariant,
+    companioned,
+    primaryId,
+  }: PlankImplProps) => {
+    const { dispatchPromise: dispatch } = useIntentDispatcher();
+    const { deck, popoverAnchorId, scrollIntoView } = useCapability(DeckCapabilities.DeckState);
+    const { graph } = useAppGraph();
+    const node = useNode(graph, id);
+    const rootElement = useRef<HTMLDivElement | null>(null);
+    const canResize = layoutMode === 'deck';
+    const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
+
+    const attendableAttrs = useAttendableAttributes(id);
+    const index = active ? active.findIndex((entryId) => entryId === id) : 0;
+    const length = active?.length ?? 1;
+    const canIncrementStart = active && index !== undefined && index > 0 && length !== undefined && length > 1;
+    const canIncrementEnd = active && index !== undefined && index < length - 1 && length !== undefined;
+
+    const sizeKey = `${id.split('+')[0]}${surfaceVariant ? `${surfaceVariantSeparator}${surfaceVariant}` : ''}`;
+    const size = deck.plankSizing[sizeKey] as number | undefined;
+    const setSize = useCallback(
+      debounce((nextSize: number) => {
+        return dispatch(createIntent(DeckAction.UpdatePlankSize, { id: sizeKey, size: nextSize }));
+      }, 200),
+      [dispatch, 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 && event.key === 'Escape') {
+        rootElement.current?.closest('main')?.focus();
+      }
+    }, []);
+
+    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' });
+        // Clear the scroll into view state once it has been actioned.
+        void dispatch(createIntent(LayoutAction.ScrollIntoView, { part: 'current', subject: undefined }));
+      }
+    }, [id, scrollIntoView, layoutMode]);
+
+    const isSolo = layoutMode === 'solo' && part === 'solo';
+    const isAttendable = isSolo || (layoutMode === 'deck' && part === 'deck');
+
+    const sizeAttrs = useMainSize();
+
+    const data = useMemo(
+      () =>
+        node && {
+          subject: node.data,
+          variant: surfaceVariant,
+          path,
+          popoverAnchorId,
+        },
+      [node, node?.data, path, popoverAnchorId, surfaceVariant],
+    );
+
+    // TODO(wittjosiah): Change prop to accept a component.
+    const placeholder = useMemo(() => <PlankLoading />, []);
+
+    const className = mx(
+      'attention-surface relative',
+      isSolo && mainIntrinsicSize,
+      isSolo && railGridHorizontal,
+      isSolo && 'grid absolute inset-0',
+      part === 'deck' && (companioned === 'companion' ? '!border-separator border-ie' : '!border-separator border-li'),
+      part.startsWith('solo-') && 'row-span-2 min-is-0',
+      part === 'solo-companion' && '!border-separator border-is',
+    );
+
+    return (
+      <Root
+        ref={rootElement}
+        data-testid='deck.plank'
+        tabIndex={0}
+        {...(part.startsWith('solo')
+          ? ({ ...sizeAttrs, className } as any)
+          : {
+              item: { id },
+              size,
+              onSizeChange: setSize,
+              classNames: className,
+              order,
+              role: 'article',
+            })}
+        {...(isAttendable ? attendableAttrs : {})}
+        onKeyDown={handleKeyDown}
+      >
+        {node ? (
+          <>
+            <NodePlankHeading
+              id={id}
+              part={part.startsWith('solo-') ? 'solo' : part}
+              node={node}
+              canIncrementStart={canIncrementStart}
+              canIncrementEnd={canIncrementEnd}
+              popoverAnchorId={popoverAnchorId}
+              companioned={companioned}
+              primaryId={primaryId}
+              surfaceVariant={surfaceVariant}
+            />
+            <Surface
+              key={node.id}
+              role='article'
+              data={data}
+              limit={1}
+              fallback={PlankContentError}
+              placeholder={placeholder}
+            />
+          </>
+        ) : (
+          <PlankError id={id} part={part} />
+        )}
+        {canResize && <StackItem.ResizeHandle />}
+      </Root>
+    );
+  },
+);
+
+const SplitFrame = ({ children }: PropsWithChildren<{}>) => {
   const sizeAttrs = useMainSize();
-
-  const data = useMemo(
-    () =>
-      node && {
-        subject: node.data,
-        path,
-        popoverAnchorId,
-      },
-    [node, node?.data, path, popoverAnchorId],
-  );
-
-  // TODO(wittjosiah): Change prop to accept a component.
-  const placeholder = useMemo(() => <PlankLoading />, []);
-
-  const className = mx(
-    'attention-surface relative',
-    isSolo && mainIntrinsicSize,
-    isSolo && railGridHorizontal,
-    isSolo ? 'grid absolute inset-0' : '!border-separator border-li',
-  );
-
   return (
-    <Root
-      ref={rootElement}
-      data-testid='deck.plank'
-      tabIndex={0}
-      {...(part === 'solo'
-        ? ({ ...sizeAttrs, className } as any)
-        : {
-            item: { id },
-            size,
-            onSizeChange: setSize,
-            classNames: className,
-            order,
-            role: 'article',
-          })}
-      {...(isAttendable ? attendableAttrs : {})}
-      onKeyDown={handleKeyDown}
+    <div
+      role='none'
+      className={mx('grid grid-cols-[1fr_1fr] absolute inset-0', railGridHorizontal, mainIntrinsicSize)}
+      {...sizeAttrs}
     >
-      {node ? (
-        <>
-          <NodePlankHeading
-            id={id}
-            part={part}
-            node={node}
-            canIncrementStart={canIncrementStart}
-            canIncrementEnd={canIncrementEnd}
-            popoverAnchorId={popoverAnchorId}
-          />
-          <Surface
-            key={node.id}
-            role='article'
-            data={data}
-            limit={1}
-            fallback={PlankContentError}
-            placeholder={placeholder}
-          />
-        </>
-      ) : (
-        <PlankError id={id} part={part} />
-      )}
-      {canResize && <StackItem.ResizeHandle />}
-    </Root>
+      {children}
+    </div>
   );
-});
+};
+
+export const Plank = (props: PlankProps) => {
+  if (props.companionId) {
+    const Root = props.part === 'solo' ? SplitFrame : Fragment;
+    return (
+      <Root>
+        <PlankImpl {...props} {...(props.part === 'solo' ? { part: 'solo-primary' } : {})} companioned='primary' />
+        <PlankImpl
+          {...props}
+          {...(props.companionId.startsWith(surfaceVariantSeparator)
+            ? { surfaceVariant: props.companionId.substring(2) }
+            : { id: props.companionId, primaryId: props.id })}
+          {...(props.part === 'solo' ? { part: 'solo-companion' } : { order: props.order! + 1 })}
+          companioned='companion'
+        />
+      </Root>
+    );
+  } else {
+    return <PlankImpl {...props} />;
+  }
+};

package/src/components/DeckLayout/PlankControls.tsx

@@ -2,8 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useCallback } from 'react';
 
+import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
 import {
   Button,
   ButtonGroup,
@@ -15,7 +17,7 @@ import {
 } from '@dxos/react-ui';
 
 import { DECK_PLUGIN } from '../../meta';
-import { type DeckAction } from '../../types';
+import { DeckAction } from '../../types';
 
 export type PlankControlHandler = (event: DeckAction.PartAdjustment) => void;
 
@@ -50,6 +52,34 @@ const PlankControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> &
   );
 };
 
+const plankControlSpacing = 'pli-2 plb-3';
+
+type PlankComplimentControlsProps = {
+  primary?: string;
+};
+
+export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankComplimentControlsProps>(
+  ({ primary }, forwardedRef) => {
+    const { t } = useTranslation(DECK_PLUGIN);
+    const { dispatchPromise: dispatch } = useIntentDispatcher();
+    const handleCloseCompanion = useCallback(() => {
+      invariant(primary);
+      return dispatch(createIntent(DeckAction.ChangeCompanion, { primary, companion: null }));
+    }, []);
+    return (
+      <div ref={forwardedRef} className='contents app-no-drag'>
+        <PlankControl
+          label={t('close companion label')}
+          variant='ghost'
+          icon='ph--minus--regular'
+          onClick={handleCloseCompanion}
+          classNames={plankControlSpacing}
+        />
+      </div>
+    );
+  },
+);
+
 // TODO(wittjosiah): Duplicate of stack LayoutControls?
 //   Translations were to be duplicated between packages.
 // NOTE(thure): Pinning & unpinning are disabled indefinitely.
@@ -59,7 +89,8 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
     forwardedRef,
   ) => {
     const { t } = useTranslation(DECK_PLUGIN);
-    const buttonClassNames = variant === 'hide-disabled' ? 'disabled:hidden pli-2 plb-3' : 'pli-2 plb-3';
+    const buttonClassNames =
+      variant === 'hide-disabled' ? `disabled:hidden ${plankControlSpacing}` : plankControlSpacing;
 
     return (
       <ButtonGroup {...props} classNames={['app-no-drag', classNames]} ref={forwardedRef}>

package/src/meta.ts

@@ -6,8 +6,8 @@ import { type PluginMeta } from '@dxos/app-framework';
 
 export const DECK_PLUGIN = 'dxos.org/plugin/deck' as const;
 
-export const meta = {
+export const meta: PluginMeta = {
   id: DECK_PLUGIN,
   name: 'Deck',
   icon: 'ph--columns--regular',
-} satisfies PluginMeta;
+};

package/src/translations.ts

@@ -55,6 +55,7 @@ export default [
         'close current label': 'Close current plank',
         'close others label': 'Close other planks',
         'close all label': 'Close all planks',
+        'companion plank heading fallback label': 'Related',
       },
     },
   },

package/src/types.ts

@@ -17,6 +17,9 @@ export type NewPlankPositioning = (typeof NewPlankPositions)[number];
 export const OverscrollOptions = ['none', 'centering'] as const;
 export type Overscroll = (typeof OverscrollOptions)[number];
 
+export type Part = 'solo' | 'deck' | 'complementary';
+export type ResolvedPart = Part | 'solo-primary' | 'solo-companion';
+
 export type Panel = {
   id: string;
   label: Label;
@@ -53,13 +56,31 @@ export const Deck = S.Struct({
     description: "If false, the deck has not yet left solo mode and new planks should be solo'd.",
   }),
   active: S.mutable(S.Array(S.String)),
+  // TODO(wittjosiah): Piping into both mutable and optional caused invalid typescript output.
+  activeCompanions: S.optional(S.mutable(S.Record({ key: S.String, value: S.String }))),
   inactive: S.mutable(S.Array(S.String)),
   solo: S.optional(S.String),
   fullscreen: S.Boolean,
   plankSizing: S.mutable(PlankSizing),
+  companionFrameSizing: S.mutable(PlankSizing),
 });
 export type Deck = S.Schema.Type<typeof Deck>;
 
+export const defaultDeck = {
+  initialized: false,
+  active: [],
+  activeCompanions: {},
+  inactive: [],
+  fullscreen: false,
+  solo: undefined,
+  plankSizing: {},
+  companionFrameSizing: {},
+} satisfies Deck;
+
+export const surfaceVariantSeparator = '--';
+
+export const surfaceVariant = (id: string) => `${surfaceVariantSeparator}${id}`;
+
 export const DeckState = S.mutable(
   S.Struct({
     sidebarState: S.Literal('closed', 'collapsed', 'expanded'),
@@ -139,4 +160,12 @@ export namespace DeckAction {
     }),
     output: S.Void,
   }) {}
+
+  export class ChangeCompanion extends S.TaggedClass<ChangeCompanion>()(`${DECK_ACTION}/change-companion`, {
+    input: S.Struct({
+      primary: S.String,
+      companion: S.Union(S.String, S.Null),
+    }),
+    output: S.Void,
+  }) {}
 }