@dxos/plugin-deck 0.8.1-staging.5be625a → 0.8.1-staging.9eaf14f

package/src/components/{DeckLayout/NodePlankHeading.tsx → Plank/PlankHeading.tsx}

@@ -2,64 +2,61 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { Fragment, memo, useCallback, useEffect, useMemo } from 'react';
+import React, { Fragment, memo, useCallback, useEffect, useMemo, type MouseEvent } from 'react';
 
 import { createIntent, LayoutAction, Surface, useAppGraph, useIntentDispatcher } from '@dxos/app-framework';
 import { type Node } from '@dxos/plugin-graph';
-import { Icon, Popover, toLocalizedString, useTranslation } from '@dxos/react-ui';
+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 { PlankCompanionControls, PlankControls } from './PlankControls';
+import { parseEntryId } from '../../layout';
 import { DECK_PLUGIN } from '../../meta';
-import { DeckAction, type ResolvedPart, SLUG_PATH_SEPARATOR } from '../../types';
+import { PLANK_COMPANION_TYPE, DeckAction, type ResolvedPart } from '../../types';
 import { useBreakpoints } from '../../util';
 import { soloInlinePadding } from '../fragments';
 
-export type NodePlankHeadingProps = {
+export type PlankHeadingProps = {
   id: string;
   part: ResolvedPart;
   node?: Node;
+  deckEnabled?: boolean;
   canIncrementStart?: boolean;
   canIncrementEnd?: boolean;
   popoverAnchorId?: string;
+  primaryId?: string;
   pending?: boolean;
-  actions?: StackItemSigilAction[];
   companioned?: 'primary' | 'companion';
-  primaryId?: string;
-  surfaceVariant?: string;
+  companions?: Node[];
+  actions?: StackItemSigilAction[];
 };
 
-export const NodePlankHeading = memo(
+export const PlankHeading = memo(
   ({
     id,
     part,
     node,
+    deckEnabled,
     canIncrementStart,
     canIncrementEnd,
     popoverAnchorId,
+    primaryId,
     pending,
-    actions = [],
     companioned,
-    primaryId,
-    surfaceVariant,
-  }: NodePlankHeadingProps) => {
+    companions,
+    actions = [],
+  }: PlankHeadingProps) => {
     const { t } = useTranslation(DECK_PLUGIN);
+    const { dispatchPromise: dispatch } = useIntentDispatcher();
     const { graph } = useAppGraph();
     const breakpoint = useBreakpoints();
     const icon = node?.properties?.icon ?? 'ph--placeholder--regular';
     const label = pending
       ? t('pending heading')
-      : 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;
+      : toLocalizedString(node?.properties?.label ?? ['plank heading fallback label', { ns: DECK_PLUGIN }], t);
+
+    const isCompanionNode = node?.type === PLANK_COMPANION_TYPE;
 
     useEffect(() => {
       const frame = requestAnimationFrame(() => {
@@ -70,21 +67,29 @@ export const NodePlankHeading = memo(
       return () => cancelAnimationFrame(frame);
     }, [node]);
 
-    // NOTE(Zan): Node ids may now contain a path like `${space}:${id}~comments`
-    const attendableId = id.split(SLUG_PATH_SEPARATOR).at(0);
+    const attendableId = primaryId ?? id;
     const capabilities = useMemo(
       () => ({
+        deck: deckEnabled ?? true,
         solo: breakpoint !== 'mobile' && (part === 'solo' || part === 'deck'),
         incrementStart: canIncrementStart,
         incrementEnd: canIncrementEnd,
+        companion: !isCompanionNode && companions && companions.length > 0,
       }),
-      [breakpoint, part, canIncrementStart, canIncrementEnd],
+      [breakpoint, part, companions, canIncrementStart, canIncrementEnd, isCompanionNode, deckEnabled],
     );
 
-    const sigilActions = useMemo(
-      () => node && [actions, graph.actions(node)].filter((a) => a.length > 0),
-      [actions, node, graph],
-    );
+    const { variant } = parseEntryId(id);
+    const sigilActions = useMemo(() => {
+      if (!node) {
+        return undefined;
+      } else if (variant) {
+        return [];
+      } else {
+        return [actions, graph.actions(node)].filter((a) => a.length > 0);
+      }
+    }, [actions, node, variant, graph]);
+
     const handleAction = useCallback((action: StackItemSigilAction) => {
       typeof action.data === 'function' && action.data?.({ node: action as Node, caller: DECK_PLUGIN });
     }, []);
@@ -113,53 +118,87 @@ export const NodePlankHeading = memo(
       [dispatch, id, part],
     );
 
+    const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${DECK_PLUGIN}/${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,
+            }),
+          );
+        }
+      },
+      [primaryId],
+    );
+
     return (
       <StackItem.Heading
         classNames={[
-          'plb-1 border-be border-separator items-stretch gap-1 sticky inline-start-12 app-drag',
+          'plb-1 border-be border-separator items-stretch gap-1 sticky inline-start-12 app-drag min-is-0 layout-contain',
           part === 'solo' ? soloInlinePadding : 'pli-1',
-          surfaceVariant && 'pis-3',
         ]}
       >
-        {!surfaceVariant && (
-          <ActionRoot>
-            {node && sigilActions ? (
-              <StackItem.Sigil
+        {companions && isCompanionNode ? (
+          <div role='none' className='flex-1 min-is-0 overflow-x-auto scrollbar-thin flex gap-1'>
+            {companions.map(({ id, properties: { icon, label } }) => (
+              <IconButton
+                key={id}
+                data-id={id}
                 icon={icon}
-                related={part === 'complementary'}
+                iconOnly={node?.id !== id}
+                label={toLocalizedString(label, t)}
+                size={5}
+                variant={node?.id === id ? 'primary' : 'default'}
+                onClick={handleTabClick}
+              />
+            ))}
+          </div>
+        ) : (
+          <>
+            <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}
-                triggerLabel={t('actions menu label')}
-                actions={sigilActions}
-                onAction={handleAction}
+                related={part === 'complementary'}
+                {...(pending && { classNames: 'text-description' })}
               >
-                <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>
+                {label}
+              </StackItem.HeadingLabel>
+            </TextTooltip>
+          </>
         )}
-        <TextTooltip text={label} onlyWhenTruncating>
-          <StackItem.HeadingLabel
-            attendableId={attendableId}
-            related={part === 'complementary'}
-            {...(pending && { classNames: 'text-description' })}
-          >
-            {label}
-          </StackItem.HeadingLabel>
-        </TextTooltip>
         {node && part !== 'complementary' && <Surface role='navbar-end' data={{ subject: node.data }} />}
         {companioned === 'companion' ? (
-          <PlankCompanionControls primary={surfaceVariant ? id : primaryId} />
+          <PlankCompanionControls primary={primaryId} />
         ) : (
           <PlankControls
             capabilities={capabilities}
             isSolo={part === 'solo'}
-            onClick={handlePlankAction}
             close={part === 'complementary' ? 'minify-end' : true}
+            onClick={handlePlankAction}
           />
         )}
       </StackItem.Heading>

package/src/components/Plank/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './Plank';
+export * from './PlankControls';
+export * from './PlankError';
+export * from './PlankHeading';
+export * from './PlankLoading';

package/src/components/{DeckLayout → Sidebar}/ComplementarySidebar.tsx

@@ -3,83 +3,85 @@
 //
 
 import React, {
+  Fragment,
+  type MouseEvent,
   type PropsWithChildren,
   useCallback,
   useEffect,
   useMemo,
   useState,
-  type MouseEvent,
-  Fragment,
 } from 'react';
 
 import {
-  createIntent,
   LayoutAction,
   Surface,
+  createIntent,
   useAppGraph,
-  useCapabilities,
   useCapability,
   useIntentDispatcher,
 } from '@dxos/app-framework';
-import {
-  Main,
-  useTranslation,
-  toLocalizedString,
-  IconButton,
-  ScrollArea as NaturalScrollArea,
-  type Label,
-} from '@dxos/react-ui';
-import { useAttended } from '@dxos/react-ui-attention';
+import { type Node } from '@dxos/plugin-graph';
+import { Main, useTranslation, toLocalizedString, IconButton, type Label } from '@dxos/react-ui';
 import { Tabs } from '@dxos/react-ui-tabs';
-import { byPosition } from '@dxos/util';
+import { byPosition, type Position } from '@dxos/util';
 
-import { PlankContentError } from './PlankError';
-import { PlankLoading } from './PlankLoading';
 import { ToggleComplementarySidebarButton } from './SidebarButton';
 import { DeckCapabilities } from '../../capabilities';
-import { useNode } from '../../hooks';
 import { DECK_PLUGIN } from '../../meta';
-import { type Panel } from '../../types';
+import { ATTENDABLE_PATH_SEPARATOR, DECK_COMPANION_TYPE } from '../../types';
 import { layoutAppliesTopbar, useBreakpoints, useHoistStatusbar } from '../../util';
+import { PlankContentError, PlankLoading } from '../Plank';
+
+const label = ['complementary sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
+
+const getCompanionId = (id: string) => {
+  const [_, companionId] = id.split(ATTENDABLE_PATH_SEPARATOR);
+  return companionId ?? 'never';
+};
+
+type DeckCompanion = Node<
+  any,
+  {
+    label: Label;
+    icon: string;
+    // TODO(burdon): Scroll area should be controlled by surface.
+    /** If true, the panel will not be wrapped in a scroll area. */
+    fixed?: boolean;
+    position?: Position;
+  }
+>;
+
+const useDeckCompanions = (): DeckCompanion[] => {
+  const { graph } = useAppGraph();
+  const companions = graph.nodes(graph.root, { type: DECK_COMPANION_TYPE }) as DeckCompanion[];
+  return companions.toSorted((a, b) => byPosition(a.properties, b.properties));
+};
 
 export type ComplementarySidebarProps = {
   current?: string;
 };
 
-const label = ['complementary sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
-
 export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) => {
   const { t } = useTranslation(DECK_PLUGIN);
   const { dispatchPromise: dispatch } = useIntentDispatcher();
   const layout = useCapability(DeckCapabilities.MutableDeckState);
-  const attended = useAttended();
-  const { graph } = useAppGraph();
-  const node = useNode(graph, attended[0]);
   const breakpoint = useBreakpoints();
   const topbar = layoutAppliesTopbar(breakpoint);
   const hoistStatusbar = useHoistStatusbar(breakpoint);
 
-  const panels = useCapabilities(DeckCapabilities.ComplementaryPanel);
-  const availablePanels = panels
-    .filter((panel) => {
-      if (!node || !panel.filter) {
-        return true;
-      }
-
-      return panel.filter(node);
-    })
-    .toSorted(byPosition);
-  const activePanelId = availablePanels.find((panel) => panel.id === current)?.id ?? availablePanels[0]?.id;
-  const [internalValue, setInternalValue] = useState(activePanelId);
+  const companions = useDeckCompanions();
+  const activeCompanion = companions.find((companion) => getCompanionId(companion.id) === current) ?? companions.at(0);
+  const activeId = getCompanionId(activeCompanion?.id ?? 'never');
+  const [internalValue, setInternalValue] = useState(activeId);
 
   useEffect(() => {
-    setInternalValue(activePanelId);
-  }, [activePanelId]);
+    setInternalValue(activeId);
+  }, [activeId]);
 
   const handleTabClick = useCallback(
     (event: MouseEvent) => {
       const nextValue = event.currentTarget.getAttribute('data-value') as string;
-      if (nextValue === activePanelId) {
+      if (nextValue === activeId) {
         layout.complementarySidebarState = layout.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
       } else {
         setInternalValue(nextValue);
@@ -87,21 +89,18 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
         void dispatch(createIntent(LayoutAction.UpdateComplementary, { part: 'complementary', subject: nextValue }));
       }
     },
-    [layout, activePanelId, dispatch],
+    [layout, activeId, dispatch],
   );
 
   const data = useMemo(
     () =>
-      node && {
-        id: node.id,
-        subject: node.data,
-        workspace: layout.activeDeck,
-        popoverAnchorId: layout.popoverAnchorId,
+      activeCompanion && {
+        id: activeCompanion.id,
+        subject: activeCompanion.data,
       },
-    [node, layout.popoverAnchorId],
+    [activeCompanion?.id, activeCompanion?.data],
   );
 
-  // TODO(burdon): Scroll area should be controlled by surface.
   return (
     <Main.ComplementarySidebar
       label={label}
@@ -110,29 +109,23 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
         hoistStatusbar && 'block-end-[--statusbar-size]',
       ]}
     >
-      <Tabs.Root
-        orientation='vertical'
-        verticalVariant='stateless'
-        value={internalValue}
-        attendableId={attended[0]}
-        classNames='contents'
-      >
+      <Tabs.Root orientation='vertical' verticalVariant='stateless' value={internalValue} classNames='contents'>
         <div
           role='none'
           className='absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size] pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-separator grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag'
         >
           <Tabs.Tablist classNames='grid grid-cols-1 auto-rows-[--rail-action] p-1 gap-1 !overflow-y-auto'>
-            {availablePanels.map((panel) => (
-              <Tabs.Tab key={panel.id} value={panel.id} asChild>
+            {companions.map((companion) => (
+              <Tabs.Tab key={getCompanionId(companion.id)} value={getCompanionId(companion.id)} asChild>
                 <IconButton
-                  label={toLocalizedString(panel.label, t)}
-                  icon={panel.icon}
+                  label={toLocalizedString(companion.properties.label, t)}
+                  icon={companion.properties.icon}
                   size={5}
                   iconOnly
                   tooltipSide='left'
-                  data-value={panel.id}
+                  data-value={getCompanionId(companion.id)}
                   variant={
-                    activePanelId === panel.id
+                    activeId === getCompanionId(companion.id)
                       ? layout.complementarySidebarState === 'expanded'
                         ? 'primary'
                         : 'default'
@@ -152,16 +145,16 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
             <ToggleComplementarySidebarButton />
           </div>
         </div>
-        {availablePanels.map((panel) => (
+        {companions.map((companion) => (
           <Tabs.Tabpanel
-            key={panel.id}
-            value={panel.id}
+            key={getCompanionId(companion.id)}
+            value={getCompanionId(companion.id)}
             classNames='absolute data-[state="inactive"]:-z-[1] inset-block-0 inline-start-0 is-[calc(100%-var(--r0-size))] lg:is-[--r1-size] grid grid-cols-1 grid-rows-[var(--rail-size)_1fr_min-content] pbs-[env(safe-area-inset-top)]'
             {...(layout.complementarySidebarState !== 'expanded' && { inert: 'true' })}
           >
             <ComplementarySidebarPanel
-              panel={panel}
-              activePanelId={activePanelId}
+              companion={companion}
+              activeId={activeId}
               data={data}
               hoistStatusbar={hoistStatusbar}
             />
@@ -173,45 +166,36 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
 };
 
 type ComplementarySidebarPanelProps = {
-  panel: Panel;
-  activePanelId: string;
+  companion: DeckCompanion;
+  activeId: string;
   data?: {
     id: string;
     subject: any;
-    workspace: string;
-    popoverAnchorId?: string;
   };
   hoistStatusbar: boolean;
 };
 
 const ScrollArea = ({ children }: PropsWithChildren) => {
-  return (
-    <NaturalScrollArea.Root>
-      <NaturalScrollArea.Viewport>{children}</NaturalScrollArea.Viewport>
-      <NaturalScrollArea.Scrollbar orientation='vertical'>
-        <NaturalScrollArea.Thumb />
-      </NaturalScrollArea.Scrollbar>
-    </NaturalScrollArea.Root>
-  );
+  return <div className='flex flex-col grow overflow-x-hidden overflow-y-auto scrollbar-thin'>{children}</div>;
 };
 
-const ComplementarySidebarPanel = ({ panel, activePanelId, data, hoistStatusbar }: ComplementarySidebarPanelProps) => {
+const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }: ComplementarySidebarPanelProps) => {
   const { t } = useTranslation(DECK_PLUGIN);
 
-  if (panel.id !== activePanelId || !data) {
+  if (getCompanionId(companion.id) !== activeId && !data) {
     return null;
   }
 
-  const Wrapper = panel.fixed ? Fragment : ScrollArea;
+  const Wrapper = companion.properties.fixed ? Fragment : ScrollArea;
 
   return (
     <>
       <h2 className='flex items-center pli-2 border-separator border-be font-medium'>
-        {toLocalizedString(panel.label, t)}
+        {toLocalizedString(companion.properties.label, t)}
       </h2>
       <Wrapper>
         <Surface
-          role={`complementary--${activePanelId}`}
+          role={`deck-companion--${getCompanionId(companion.id)}`}
           data={data}
           fallback={PlankContentError}
           placeholder={<PlankLoading />}

package/src/components/Sidebar/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ComplementarySidebar';
+export * from './Sidebar';
+export * from './SidebarButton';

package/src/components/index.ts

@@ -3,4 +3,4 @@
 //
 
 export * from './DeckLayout';
-export * from './LayoutSettings';
+export * from './DeckSettings';

package/src/events.ts

@@ -7,6 +7,5 @@ import { Events } from '@dxos/app-framework';
 import { DECK_PLUGIN } from './meta';
 
 export namespace DeckEvents {
-  export const SetupComplementaryPanels = Events.createStateEvent(`${DECK_PLUGIN}/setup-complementary-panels`);
   export const StateReady = Events.createStateEvent(`${DECK_PLUGIN}/state-ready`);
 }

package/src/hooks/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './useNode';
 export * from './useNodeActionExpander';
 export * from './useMainSize';

package/src/index.ts

@@ -6,3 +6,4 @@ export { DeckCapabilities } from './capabilities';
 export { DeckEvents } from './events';
 export * from './DeckPlugin';
 export * from './meta';
+export { useCompanions } from './util';

package/src/layout.ts

@@ -4,12 +4,29 @@
 
 import { produce } from 'immer';
 
+import { ATTENDABLE_PATH_SEPARATOR } from '@dxos/react-ui-attention';
+
 import { type DeckAction, type NewPlankPositioning } from './types';
 
-type OpenLayoutEntryOptions = { key?: string; positioning?: NewPlankPositioning; pivotId?: string };
+export const createEntryId = (entryId: string, variant?: string) =>
+  variant ? `${entryId}${ATTENDABLE_PATH_SEPARATOR}${variant}` : entryId;
+
+export const parseEntryId = (entryId: string) => {
+  const [id, variant] = entryId.split(ATTENDABLE_PATH_SEPARATOR);
+  return { id, variant };
+};
+
+type OpenLayoutEntryOptions = {
+  key?: string;
+  positioning?: NewPlankPositioning;
+  pivotId?: string;
+  variant?: string;
+};
 
-export const openEntry = (deck: string[], entryId: string, options?: OpenLayoutEntryOptions): string[] => {
+export const openEntry = (deck: string[], _entryId: string, options?: OpenLayoutEntryOptions): string[] => {
   return produce(deck, (draft) => {
+    const entryId = createEntryId(_entryId, options?.variant);
+
     // Check that the entry is not already in the part
     if (draft.find((id) => id === entryId)) {
       return;

package/src/meta.ts

@@ -8,6 +8,6 @@ export const DECK_PLUGIN = 'dxos.org/plugin/deck' as const;
 
 export const meta: PluginMeta = {
   id: DECK_PLUGIN,
-  name: 'Deck',
-  icon: 'ph--columns--regular',
+  name: 'Layout',
+  icon: 'ph--layout--regular',
 };

package/src/translations.ts

@@ -47,11 +47,14 @@ export default [
         'show solo plank label': 'Maximize',
         'close label': 'Close',
         'minify label': 'Minify',
+        'open companion label': 'Open companion',
+        'close companion label': 'Close companion',
         'settings overscroll label': 'Plank scrolling',
         'select overscroll placeholder': 'Select plank scrolling behavior',
         'settings overscroll centering label': 'Centering',
         'settings overscroll none label': 'None',
         'settings enable statusbar label': 'Show status bar',
+        'settings enable deck label': 'Enable Deck',
         'close current label': 'Close current plank',
         'close others label': 'Close other planks',
         'close all label': 'Close all planks',