@dxos/plugin-deck 0.8.1-staging.391c573 → 0.8.1-staging.9eaf14f

package/src/components/Plank/PlankHeading.tsx

@@ -0,0 +1,207 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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, 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 { PLANK_COMPANION_TYPE, DeckAction, type ResolvedPart } from '../../types';
+import { useBreakpoints } from '../../util';
+import { soloInlinePadding } from '../fragments';
+
+export type PlankHeadingProps = {
+  id: string;
+  part: ResolvedPart;
+  node?: Node;
+  deckEnabled?: boolean;
+  canIncrementStart?: boolean;
+  canIncrementEnd?: boolean;
+  popoverAnchorId?: string;
+  primaryId?: string;
+  pending?: boolean;
+  companioned?: 'primary' | 'companion';
+  companions?: Node[];
+  actions?: StackItemSigilAction[];
+};
+
+export const PlankHeading = memo(
+  ({
+    id,
+    part,
+    node,
+    deckEnabled,
+    canIncrementStart,
+    canIncrementEnd,
+    popoverAnchorId,
+    primaryId,
+    pending,
+    companioned,
+    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(node?.properties?.label ?? ['plank heading fallback label', { ns: DECK_PLUGIN }], t);
+
+    const isCompanionNode = node?.type === PLANK_COMPANION_TYPE;
+
+    useEffect(() => {
+      const frame = requestAnimationFrame(() => {
+        // Load actions for the node.
+        node && graph.actions(node);
+      });
+
+      return () => cancelAnimationFrame(frame);
+    }, [node]);
+
+    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, companions, canIncrementStart, canIncrementEnd, isCompanionNode, deckEnabled],
+    );
+
+    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 });
+    }, []);
+
+    const handlePlankAction = useCallback(
+      (eventType: DeckAction.PartAdjustment) => {
+        if (eventType === 'solo') {
+          return dispatch(createIntent(DeckAction.Adjust, { type: eventType, id }));
+        } else if (eventType === 'close') {
+          if (part === 'complementary') {
+            return dispatch(
+              createIntent(LayoutAction.UpdateComplementary, {
+                part: 'complementary',
+                options: { state: 'collapsed' },
+              }),
+            );
+          } else {
+            return dispatch(
+              createIntent(LayoutAction.Close, { part: 'main', subject: [id], options: { state: false } }),
+            );
+          }
+        } else {
+          return dispatch(createIntent(DeckAction.Adjust, { type: eventType, id }));
+        }
+      },
+      [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 min-is-0 layout-contain',
+          part === 'solo' ? soloInlinePadding : 'pli-1',
+        ]}
+      >
+        {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}
+                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}
+                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={primaryId} />
+        ) : (
+          <PlankControls
+            capabilities={capabilities}
+            isSolo={part === 'solo'}
+            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

@@ -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;
+  name: 'Layout',
+  icon: 'ph--layout--regular',
+};

package/src/translations.ts

@@ -47,14 +47,18 @@ 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',
+        'companion plank heading fallback label': 'Related',
       },
     },
   },