@dxos/plugin-deck 0.6.13 → 0.6.14-main.69511f5

package/src/components/DeckLayout/DeckLayout.tsx

@@ -3,21 +3,14 @@
 //
 
 import { Sidebar as MenuIcon } from '@phosphor-icons/react';
-import React, { useCallback, useEffect, useMemo, useRef, useState, useLayoutEffect, type UIEvent } from 'react';
+import { untracked } from '@preact/signals-core';
+import React, { useCallback, useEffect, useMemo, useRef, type UIEvent } from 'react';
 
-import {
-  SLUG_PATH_SEPARATOR,
-  type Attention,
-  type LayoutEntry,
-  type LayoutParts,
-  Surface,
-  type Toast as ToastSchema,
-  firstIdInPart,
-  usePlugin,
-} from '@dxos/app-framework';
-import { Button, Dialog, Main, Popover, useTranslation } from '@dxos/react-ui';
+import { type LayoutParts, Surface, type Toast as ToastSchema, firstIdInPart, usePlugin } from '@dxos/app-framework';
+import { type AttentionPluginProvides } from '@dxos/plugin-attention';
+import { Button, Dialog, Main, Popover, useOnTransition, useTranslation } from '@dxos/react-ui';
 import { Deck } from '@dxos/react-ui-deck';
-import { getSize } from '@dxos/react-ui-theme';
+import { getSize, mainPaddingTransitions } from '@dxos/react-ui-theme';
 
 import { ActiveNode } from './ActiveNode';
 import { ComplementarySidebar } from './ComplementarySidebar';
@@ -35,11 +28,10 @@ import { useLayout } from '../LayoutContext';
 
 export type DeckLayoutProps = {
   layoutParts: LayoutParts;
-  attention: Attention;
   toasts: ToastSchema[];
   flatDeck?: boolean;
   overscroll: Overscroll;
-  showHintsFooter: boolean;
+  showHints: boolean;
   slots?: {
     wallpaper?: { classNames?: string };
   };
@@ -48,11 +40,10 @@ export type DeckLayoutProps = {
 
 export const DeckLayout = ({
   layoutParts,
-  attention,
   toasts,
   flatDeck,
   overscroll,
-  showHintsFooter,
+  showHints,
   slots,
   onDismissToast,
 }: DeckLayoutProps) => {
@@ -70,36 +61,44 @@ export const DeckLayout = ({
   } = context;
   const { t } = useTranslation(DECK_PLUGIN);
   const { plankSizing } = useDeckContext();
+  // NOTE: Not `useAttended` so that the layout component is not re-rendered when the attended list changes.
+  const attentionPlugin = usePlugin<AttentionPluginProvides>('dxos.org/plugin/attention');
   const searchPlugin = usePlugin('dxos.org/plugin/search');
   const fullScreenSlug = useMemo(() => firstIdInPart(layoutParts, 'fullScreen'), [layoutParts]);
 
-  const [scrollLeft, setScrollLeft] = useState<number | null>(null);
-  const deckRef = useRef<HTMLDivElement | null>(null);
-  const restoreScrollRef = useRef<boolean>(false);
+  const scrollLeftRef = useRef<number | null>();
+  const deckRef = useRef<HTMLDivElement>(null);
+
+  // Ensure the first plank is attended when the deck is first rendered.
+  useEffect(() => {
+    const attended = untracked(() => attentionPlugin?.provides.attention.attended ?? []);
+    const firstId = layoutMode === 'solo' ? firstIdInPart(layoutParts, 'solo') : firstIdInPart(layoutParts, 'main');
+    if (attended.length === 0 && firstId) {
+      // TODO(wittjosiah): Focusing the type button is a workaround.
+      //   If the plank is directly focused on first load the focus ring appears.
+      document.querySelector<HTMLElement>(`article[data-attendable-id="${firstId}"] button`)?.focus();
+    }
+  }, []);
 
   /**
    * Clear scroll restoration state if the window is resized
    */
   const handleResize = useCallback(() => {
-    setScrollLeft(null);
+    scrollLeftRef.current = null;
   }, []);
+
   useEffect(() => {
     window.addEventListener('resize', handleResize);
     return () => window.removeEventListener('resize', handleResize);
   }, [handleResize]);
 
-  /**
-   * Restore scroll when returning to deck mode
-   */
-  useLayoutEffect(() => {
-    if (layoutMode !== 'deck') {
-      restoreScrollRef.current = true;
-    } else if (restoreScrollRef.current && deckRef.current && scrollLeft) {
-      // console.log('[restoring scrollLeft]', scrollLeft);
-      deckRef.current.scrollLeft = scrollLeft;
-      restoreScrollRef.current = false;
+  const restoreScroll = useCallback(() => {
+    if (deckRef.current && scrollLeftRef.current != null) {
+      deckRef.current.scrollLeft = scrollLeftRef.current;
     }
-  }, [layoutMode, deckRef.current, scrollLeft]);
+  }, []);
+
+  useOnTransition(layoutMode, (mode) => mode !== 'deck', 'deck', restoreScroll);
 
   /**
    * Save scroll position as the user scrolls
@@ -107,48 +106,20 @@ export const DeckLayout = ({
   const handleScroll = useCallback(
     (event: UIEvent) => {
       if (layoutMode === 'deck' && event.currentTarget === event.target) {
-        // console.log('[save scroll left]', (event.target as HTMLDivElement).scrollLeft);
-        setScrollLeft((event.target as HTMLDivElement).scrollLeft);
+        scrollLeftRef.current = (event.target as HTMLDivElement).scrollLeft;
       }
     },
     [layoutMode],
   );
 
-  const complementarySlug = useMemo(() => {
-    const entry = layoutParts.complementary?.at(0);
-    if (entry) {
-      return entry.path ? `${entry.id}${SLUG_PATH_SEPARATOR}${entry.path}` : entry.id;
-    }
-  }, [layoutParts]);
-
-  const firstAttendedId = useMemo(() => Array.from(attention.attended ?? [])[0], [attention.attended]);
+  const isEmpty = layoutParts.main?.length === 0 && layoutParts.solo?.length === 0;
 
-  useEffect(() => {
-    // TODO(burdon): Can we prevent the need to re-scroll since the planks are preserved?
-    //  E.g., hide the deck and just move the solo article?
-    if (layoutMode === 'deck' && firstAttendedId) {
-      // setTimeout(() => {
-      // const el = deckRef.current?.querySelector(`article[data-attendable-id="${firstAttendedId}"]`);
-      // el?.scrollIntoView({ behavior: 'smooth', inline: 'center' });
-      // }, 0);
-    }
-  }, [layoutMode, firstAttendedId]);
-
-  // TODO(burdon): Needs cleaning up.
-  const parts: LayoutEntry[] = useMemo(() => {
-    const parts = [...(layoutParts.main ?? [])];
-    for (const part of layoutParts.solo ?? []) {
-      if (!parts.find((entry) => entry.id === part.id)) {
-        parts.push(part);
-      }
+  const padding = useMemo(() => {
+    if (layoutMode === 'deck' && overscroll === 'centering') {
+      return calculateOverscroll(layoutParts.main, plankSizing, sidebarOpen, complementarySidebarOpen);
     }
-    return parts;
-  }, [layoutParts.main, layoutParts.solo]);
-
-  const padding =
-    layoutMode === 'deck' && overscroll === 'centering'
-      ? calculateOverscroll(layoutParts.main, plankSizing, sidebarOpen, complementarySidebarOpen)
-      : {};
+    return {};
+  }, [layoutMode, overscroll, layoutParts.main, plankSizing, sidebarOpen, complementarySidebarOpen]);
 
   if (layoutMode === 'fullscreen') {
     return <Fullscreen id={fullScreenSlug} />;
@@ -167,31 +138,22 @@ export const DeckLayout = ({
         }
       }}
     >
-      {/* TODO(burdon): Factor out hook to set document title. */}
-      <ActiveNode id={firstAttendedId} />
+      <ActiveNode />
 
       <Main.Root
         navigationSidebarOpen={context.sidebarOpen}
         onNavigationSidebarOpenChange={(next) => (context.sidebarOpen = next)}
-        {...(complementarySidebarOpen !== null && {
-          complementarySidebarOpen: /* complementaryAvailable && */ context.complementarySidebarOpen as boolean,
-          onComplementarySidebarOpenChange: (next) => (context.complementarySidebarOpen = next),
-        })}
+        complementarySidebarOpen={context.complementarySidebarOpen}
+        onComplementarySidebarOpenChange={(next) => (context.complementarySidebarOpen = next)}
       >
         {/* Notch */}
         <Main.Notch classNames='z-[21]'>
           <Surface role='notch-start' />
-          <Button
-            // disabled={!sidebarAvailable}
-            onClick={() => (context.sidebarOpen = !context.sidebarOpen)}
-            variant='ghost'
-            classNames='p-1'
-          >
+          <Button onClick={() => (context.sidebarOpen = !context.sidebarOpen)} variant='ghost' classNames='p-1'>
             <span className='sr-only'>{t('open navigation sidebar label')}</span>
             <MenuIcon weight='light' className={getSize(5)} />
           </Button>
           <Button
-            // disabled={!complementaryAvailable}
             onClick={() => (context.complementarySidebarOpen = !context.complementarySidebarOpen)}
             variant='ghost'
             classNames='p-1'
@@ -203,38 +165,51 @@ export const DeckLayout = ({
         </Main.Notch>
 
         {/* Left sidebar. */}
-        <Sidebar attention={attention} layoutParts={layoutParts} />
+        <Sidebar layoutParts={layoutParts} />
 
         {/* Right sidebar. */}
-        <ComplementarySidebar id={complementarySlug} layoutParts={layoutParts} flatDeck={flatDeck} />
+        <ComplementarySidebar panel={layoutParts.complementary?.[0].id} flatDeck={flatDeck} />
 
         {/* Dialog overlay to dismiss dialogs. */}
         <Main.Overlay />
 
         {/* No content. */}
-        {parts.length === 0 && (
+        {isEmpty && (
           <Main.Content handlesFocus>
             <ContentEmpty />
           </Main.Content>
         )}
 
         {/* Solo/deck mode. */}
-        {parts.length !== 0 && (
+        {!isEmpty && (
           <Main.Content bounce classNames='grid block-end-[--statusbar-size]' handlesFocus>
             <div role='none' className='relative'>
               <Deck.Root
                 style={padding}
-                classNames={[!flatDeck && 'bg-deck', 'absolute inset-0', slots?.wallpaper?.classNames]}
+                classNames={[
+                  !flatDeck && 'bg-deck',
+                  mainPaddingTransitions,
+                  'absolute inset-0',
+                  slots?.wallpaper?.classNames,
+                ]}
                 solo={layoutMode === 'solo'}
                 onScroll={handleScroll}
                 ref={deckRef}
               >
-                {parts.map((layoutEntry) => (
+                <Plank
+                  entry={layoutParts.solo?.[0] ?? { id: 'unknown-solo' }}
+                  layoutParts={layoutParts}
+                  part='solo'
+                  layoutMode={layoutMode}
+                  flatDeck={flatDeck}
+                  searchEnabled={!!searchPlugin}
+                />
+                {layoutParts.main?.map((layoutEntry) => (
                   <Plank
                     key={layoutEntry.id}
                     entry={layoutEntry}
                     layoutParts={layoutParts}
-                    part={layoutMode === 'solo' && layoutEntry.id === layoutParts.solo?.[0]?.id ? 'solo' : 'main'}
+                    part='main'
                     layoutMode={layoutMode}
                     flatDeck={flatDeck}
                     searchEnabled={!!searchPlugin}
@@ -245,15 +220,8 @@ export const DeckLayout = ({
           </Main.Content>
         )}
 
-        <StatusBar />
-
-        {/* Help hints. */}
-        {/* TODO(burdon): Need to make room for this in status bar. */}
-        {showHintsFooter && (
-          <div className='fixed bottom-0 left-0 right-0 h-[32px] z-[1] flex justify-center'>
-            <Surface role='hints' limit={1} />
-          </div>
-        )}
+        {/* Footer status. */}
+        <StatusBar showHints={showHints} />
 
         {/* Global popovers. */}
         <Popover.Portal>

package/src/components/DeckLayout/NodePlankHeading.tsx

@@ -2,157 +2,160 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Placeholder } from '@phosphor-icons/react';
-import React, { Fragment, useEffect } from 'react';
+import React, { Fragment, memo, useEffect, useMemo } from 'react';
 
 import {
   LayoutAction,
   NavigationAction,
-  SLUG_COLLECTION_INDICATOR,
   SLUG_PATH_SEPARATOR,
   Surface,
   useIntentDispatcher,
-  indexInPart,
-  partLength,
-  type LayoutParts,
-  type LayoutPart,
-  type LayoutEntry,
+  type LayoutCoordinate,
 } from '@dxos/app-framework';
 import { type Node, useGraph } from '@dxos/plugin-graph';
-import { Popover, toLocalizedString, useMediaQuery, useTranslation } from '@dxos/react-ui';
-import { PlankHeading, plankHeadingIconProps } from '@dxos/react-ui-deck';
+import { Icon, Popover, toLocalizedString, useMediaQuery, useTranslation } from '@dxos/react-ui';
+import { PlankHeading, type PlankHeadingAction } from '@dxos/react-ui-deck';
 import { TextTooltip } from '@dxos/react-ui-text-tooltip';
 
 import { DECK_PLUGIN } from '../../meta';
 
-export const NodePlankHeading = ({
-  node,
-  id,
-  layoutParts,
-  layoutPart,
-  // TODO(wittjosiah): Unused?
-  layoutEntry,
-  popoverAnchorId,
-  pending,
-  flatDeck,
-}: {
+export type NodePlankHeadingProps = {
+  coordinate: LayoutCoordinate;
   node?: Node;
-  id?: string;
-  layoutParts?: LayoutParts;
-  layoutPart?: LayoutPart;
-  layoutEntry?: LayoutEntry;
+  canIncrementStart?: boolean;
+  canIncrementEnd?: boolean;
   popoverAnchorId?: string;
   pending?: boolean;
   flatDeck?: boolean;
-}) => {
-  const { t } = useTranslation(DECK_PLUGIN);
-  const { graph } = useGraph();
-  const Icon = node?.properties?.icon ?? Placeholder;
-  const label = pending
-    ? t('pending heading')
-    : toLocalizedString(node?.properties?.label ?? ['plank heading fallback label', { ns: DECK_PLUGIN }], t);
-  const dispatch = useIntentDispatcher();
-  const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${DECK_PLUGIN}/${node.id}` ? Popover.Anchor : Fragment;
-  const [isNotMobile] = useMediaQuery('md');
-
-  useEffect(() => {
-    const frame = requestAnimationFrame(() => {
-      // Load actions for the node.
-      node && graph.actions(node);
-    });
+  actions?: PlankHeadingAction[];
+};
 
-    return () => cancelAnimationFrame(frame);
-  }, [node]);
+export const NodePlankHeading = memo(
+  ({
+    coordinate,
+    node,
+    canIncrementStart,
+    canIncrementEnd,
+    popoverAnchorId,
+    pending,
+    flatDeck,
+    actions = [],
+  }: NodePlankHeadingProps) => {
+    const { t } = useTranslation(DECK_PLUGIN);
+    const { graph } = useGraph();
+    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 dispatch = useIntentDispatcher();
+    const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${DECK_PLUGIN}/${node.id}` ? Popover.Anchor : Fragment;
+    const [isNotMobile] = useMediaQuery('md');
 
-  // NOTE(Zan): Node ids may now contain a path like `${space}:${id}~comments`
-  const attendableId = id?.split(SLUG_PATH_SEPARATOR).at(0);
+    useEffect(() => {
+      const frame = requestAnimationFrame(() => {
+        // Load actions for the node.
+        node && graph.actions(node);
+      });
 
-  const layoutCoordinate = layoutPart !== undefined && id !== undefined ? { part: layoutPart, entryId: id } : undefined;
-  const index = indexInPart(layoutParts, layoutCoordinate);
-  const length = partLength(layoutParts, layoutPart);
+      return () => cancelAnimationFrame(frame);
+    }, [node]);
 
-  const canIncrementStart =
-    layoutPart === 'main' && index !== undefined && index > 0 && length !== undefined && length > 1;
-  const canIncrementEnd = layoutPart === 'main' && index !== undefined && index < length - 1 && length !== undefined;
+    const layoutPart = coordinate.part;
+    // NOTE(Zan): Node ids may now contain a path like `${space}:${id}~comments`
+    const attendableId = coordinate.entryId.split(SLUG_PATH_SEPARATOR).at(0);
+    const capabilities = useMemo(
+      () => ({
+        solo: (layoutPart === 'solo' || layoutPart === 'main') && isNotMobile,
+        incrementStart: canIncrementStart,
+        incrementEnd: canIncrementEnd,
+      }),
+      [isNotMobile, layoutPart, canIncrementStart, canIncrementEnd],
+    );
 
-  return (
-    <PlankHeading.Root {...((layoutPart !== 'main' || !flatDeck) && { classNames: 'pie-1 border-b border-separator' })}>
-      <ActionRoot>
-        {node ? (
-          <PlankHeading.ActionsMenu
-            Icon={Icon}
+    return (
+      <PlankHeading.Root
+        {...((layoutPart !== 'main' || !flatDeck) && { classNames: 'pie-1 border-b border-separator' })}
+      >
+        <ActionRoot>
+          {node ? (
+            <PlankHeading.ActionsMenu
+              icon={icon}
+              related={layoutPart === 'complementary'}
+              attendableId={attendableId}
+              triggerLabel={t('actions menu label')}
+              actions={[actions, graph.actions(node)].filter((a) => a.length > 0)}
+              onAction={(action) =>
+                typeof action.data === 'function' && action.data?.({ node: action as Node, caller: DECK_PLUGIN })
+              }
+            >
+              <Surface role='menu-footer' data={{ object: node.data }} />
+            </PlankHeading.ActionsMenu>
+          ) : (
+            <PlankHeading.Button>
+              <span className='sr-only'>{label}</span>
+              <Icon icon={icon} size={5} />
+            </PlankHeading.Button>
+          )}
+        </ActionRoot>
+        <TextTooltip text={label} onlyWhenTruncating>
+          <PlankHeading.Label
             attendableId={attendableId}
-            triggerLabel={t('actions menu label')}
-            actions={graph.actions(node)}
-            onAction={(action) =>
-              typeof action.data === 'function' && action.data?.({ node: action as Node, caller: DECK_PLUGIN })
-            }
+            related={layoutPart === 'complementary'}
+            {...(pending && { classNames: 'text-description' })}
           >
-            <Surface role='menu-footer' data={{ object: node.data }} />
-          </PlankHeading.ActionsMenu>
-        ) : (
-          <PlankHeading.Button>
-            <span className='sr-only'>{label}</span>
-            <Icon {...plankHeadingIconProps} />
-          </PlankHeading.Button>
+            {label}
+          </PlankHeading.Label>
+        </TextTooltip>
+        {node && layoutPart !== 'complementary' && (
+          // TODO(Zan): What are we doing with layout coordinate here?
+          <Surface role='navbar-end' direction='inline-reverse' data={{ object: node.data }} />
         )}
-      </ActionRoot>
-      <TextTooltip text={label} onlyWhenTruncating>
-        <PlankHeading.Label attendableId={node?.id} {...(pending && { classNames: 'text-description' })}>
-          {label}
-        </PlankHeading.Label>
-      </TextTooltip>
-      {node && layoutPart !== 'complementary' && (
-        // TODO(Zan): What are we doing with layout coordinate here?
-        <Surface role='navbar-end' direction='inline-reverse' data={{ object: node.data }} />
-      )}
-      {/* NOTE(thure): Pinning & unpinning are temporarily disabled */}
-      <PlankHeading.Controls
-        capabilities={{
-          solo: (layoutPart === 'solo' || layoutPart === 'main') && isNotMobile,
-          incrementStart: canIncrementStart,
-          incrementEnd: canIncrementEnd,
-        }}
-        isSolo={layoutPart === 'solo'}
-        onClick={(eventType) => {
-          if (!layoutPart) {
-            return;
-          }
-
-          if (eventType === 'solo') {
-            return dispatch([
-              {
-                action: NavigationAction.ADJUST,
-                data: { type: eventType, layoutCoordinate: { part: 'main', entryId: id } },
-              },
-            ]);
-          }
+        {/* NOTE(thure): Pinning & unpinning are temporarily disabled */}
+        <PlankHeading.Controls
+          capabilities={capabilities}
+          isSolo={layoutPart === 'solo'}
+          onClick={(eventType) => {
+            if (!layoutPart) {
+              return;
+            }
 
-          // TODO(Zan): Update this to use the new layout actions.
-          return dispatch(
-            eventType === 'close'
-              ? layoutPart === 'complementary'
-                ? {
-                    action: LayoutAction.SET_LAYOUT,
-                    data: {
-                      element: 'complementary',
-                      state: false,
-                    },
-                  }
-                : {
-                    action: NavigationAction.CLOSE,
-                    data: {
-                      activeParts: {
-                        complementary: [`${id}${SLUG_PATH_SEPARATOR}comments${SLUG_COLLECTION_INDICATOR}`],
-                        [layoutPart]: [id],
-                      },
+            // TODO(Zan): Update this to use the new layout actions.
+            if (eventType === 'solo') {
+              return dispatch([
+                {
+                  action: NavigationAction.ADJUST,
+                  data: { type: eventType, layoutCoordinate: { part: 'main', entryId: coordinate.entryId } },
+                },
+              ]);
+            } else if (eventType === 'close') {
+              if (layoutPart === 'complementary') {
+                return dispatch({
+                  action: LayoutAction.SET_LAYOUT,
+                  data: {
+                    element: 'complementary',
+                    state: false,
+                  },
+                });
+              } else {
+                return dispatch({
+                  action: NavigationAction.CLOSE,
+                  data: {
+                    activeParts: {
+                      [layoutPart]: [coordinate.entryId],
                     },
-                  }
-              : { action: NavigationAction.ADJUST, data: { type: eventType, layoutCoordinate } },
-          );
-        }}
-        close={layoutCoordinate?.part === 'complementary' ? 'minify-end' : true}
-      />
-    </PlankHeading.Root>
-  );
-};
+                  },
+                });
+              }
+            } else {
+              return dispatch({
+                action: NavigationAction.ADJUST,
+                data: { type: eventType, layoutCoordinate: coordinate },
+              });
+            }
+          }}
+          close={layoutPart === 'complementary' ? 'minify-end' : true}
+        />
+      </PlankHeading.Root>
+    );
+  },
+);