@dxos/plugin-deck 0.8.1-main.ae460ac → 0.8.1-staging.31c3ee1

package/src/components/DeckLayout/DeckLayout.tsx

@@ -6,9 +6,10 @@ import { untracked } from '@preact/signals-core';
 import React, { useCallback, useEffect, useMemo, useRef, type UIEvent, Fragment, useState } from 'react';
 
 import {
+  Capabilities,
   LayoutAction,
-  createIntent,
   Surface,
+  createIntent,
   useCapability,
   useIntentDispatcher,
   usePluginManager,
@@ -19,39 +20,37 @@ 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';
 
 import { ActiveNode } from './ActiveNode';
-import { ComplementarySidebar } from './ComplementarySidebar';
 import { ContentEmpty } from './ContentEmpty';
 import { Fullscreen } from './Fullscreen';
-import { Plank } from './Plank';
-import { Sidebar } from './Sidebar';
-import { ToggleComplementarySidebarButton, ToggleSidebarButton } from './SidebarButton';
 import { StatusBar } from './StatusBar';
 import { Toast } from './Toast';
 import { Topbar } from './Topbar';
 import { DeckCapabilities } from '../../capabilities';
-import { getMode, type Overscroll } from '../../types';
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps, getMode } from '../../types';
 import { calculateOverscroll, layoutAppliesTopbar, useBreakpoints, useHoistStatusbar } from '../../util';
+import { Plank, PlankContentError } from '../Plank';
+import { ComplementarySidebar, Sidebar, ToggleComplementarySidebarButton, ToggleSidebarButton } from '../Sidebar';
 import { fixedComplementarySidebarToggleStyles, fixedSidebarToggleStyles } from '../fragments';
 
 export type DeckLayoutProps = {
-  overscroll: Overscroll;
-  showHints: boolean;
   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) => {
+export const DeckLayout = ({ onDismissToast }: DeckLayoutProps) => {
   const { dispatchPromise: dispatch } = useIntentDispatcher();
+  const settings = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)!.value;
   const context = useCapability(DeckCapabilities.MutableDeckState);
   const {
     sidebarState,
@@ -67,7 +66,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);
@@ -119,6 +118,15 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
     }
   }, [isNotMobile, deck, dispatch]);
 
+  // If deck is disabled in settings, ensure that the layout is in solo mode.
+  useEffect(() => {
+    if (!settings.enableDeck) {
+      void dispatch(
+        createIntent(LayoutAction.SetLayoutMode, { part: 'mode', subject: active[0], options: { mode: 'solo' } }),
+      );
+    }
+  }, [settings.enableDeck, dispatch, active]);
+
   /**
    * Clear scroll restoration state if the window is resized
    */
@@ -155,11 +163,11 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
   const isEmpty = !solo && active.length === 0;
 
   const padding = useMemo(() => {
-    if (!solo && overscroll === 'centering') {
+    if (!solo && settings.overscroll === 'centering') {
       return calculateOverscroll(active.length);
     }
     return {};
-  }, [solo, overscroll, deck]);
+  }, [solo, settings.overscroll, deck]);
 
   const mainPosition = useMemo(
     () => [
@@ -186,6 +194,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 />
@@ -248,18 +267,26 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
                 {!topbar && <ToggleSidebarButton classNames={fixedSidebarToggleStyles} />}
                 {!topbar && <ToggleComplementarySidebarButton classNames={fixedComplementarySidebarToggleStyles} />}
                 <Stack
+                  ref={deckRef}
                   orientation='horizontal'
                   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}
+                  onScroll={handleScroll}
                 >
-                  {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}
+                        settings={settings}
+                      />
                     </Fragment>
                   ))}
                 </Stack>
@@ -272,15 +299,23 @@ 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}
+                    settings={settings}
+                  />
                 </StackContext.Provider>
               </div>
             </Main.Content>
           )}
 
-          {/* Status bar. */}
+          {/* Topbar. */}
           {topbar && <Topbar />}
-          {hoistStatusbar && <StatusBar showHints={showHints} />}
+
+          {/* Status bar. */}
+          {hoistStatusbar && <StatusBar showHints={settings.showHints} />}
         </Main.Root>
       )}
 
@@ -303,10 +338,11 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
         onOpenChange={(nextOpen) => (context.dialogOpen = nextOpen)}
       >
         {dialogBlockAlign === 'end' ? (
-          <Surface role='dialog' data={dialogContent} limit={1} />
+          // 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} />
+            <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} />
           </Dialog.Overlay>
         )}
       </Dialog.Root>

package/src/components/DeckLayout/Fullscreen.tsx

@@ -5,11 +5,11 @@
 import React from 'react';
 
 import { Surface, useAppGraph } from '@dxos/app-framework';
+import { useNode } from '@dxos/plugin-graph';
 import { fixedInsetFlexLayout } from '@dxos/react-ui-theme';
 
 import { Fallback } from './Fallback';
 import { SURFACE_PREFIX } from './constants';
-import { useNode } from '../../hooks';
 
 export const Fullscreen = ({ id }: { id?: string }) => {
   const { graph } = useAppGraph();

package/src/components/DeckLayout/Toast.tsx

@@ -9,9 +9,9 @@ import {
   Button,
   Icon,
   Toast as NaturalToast,
+  type ToastRootProps,
   toLocalizedString,
   useTranslation,
-  type ToastRootProps,
 } from '@dxos/react-ui';
 
 import { DECK_PLUGIN } from '../../meta';

package/src/components/DeckLayout/index.ts

@@ -3,4 +3,6 @@
 //
 
 export { NAV_ID } from './constants';
+
+export * from './Banner';
 export * from './DeckLayout';

package/src/components/{LayoutSettings.tsx → DeckSettings/DeckSettings.tsx}

@@ -7,24 +7,28 @@ import React from 'react';
 import { Input, Select, useTranslation } from '@dxos/react-ui';
 import { DeprecatedFormContainer, DeprecatedFormInput } from '@dxos/react-ui-form';
 
-import { DECK_PLUGIN } from '../meta';
+import { DECK_PLUGIN } from '../../meta';
 import {
+  type DeckSettingsProps,
   type NewPlankPositioning,
   NewPlankPositions,
-  type DeckSettingsProps,
   type Overscroll,
   OverscrollOptions,
-} from '../types';
+} from '../../types';
 
 const isSocket = !!(globalThis as any).__args;
 
-export const LayoutSettings = ({ settings }: { settings: DeckSettingsProps }) => {
+export const DeckSettings = ({ settings }: { settings: DeckSettingsProps }) => {
   const { t } = useTranslation(DECK_PLUGIN);
 
   return (
     <DeprecatedFormContainer>
+      <DeprecatedFormInput label={t('settings enable deck label')}>
+        <Input.Switch checked={settings.enableDeck} onCheckedChange={(checked) => (settings.enableDeck = checked)} />
+      </DeprecatedFormInput>
       <DeprecatedFormInput label={t('select new plank positioning label')}>
         <Select.Root
+          disabled={!settings.enableDeck}
           value={settings.newPlankPositioning ?? 'start'}
           onValueChange={(value) => (settings.newPlankPositioning = value as NewPlankPositioning)}
         >
@@ -44,6 +48,7 @@ export const LayoutSettings = ({ settings }: { settings: DeckSettingsProps }) =>
       </DeprecatedFormInput>
       <DeprecatedFormInput label={t('settings overscroll label')}>
         <Select.Root
+          disabled={!settings.enableDeck}
           value={settings.overscroll ?? 'none'}
           onValueChange={(value) => (settings.overscroll = value as Overscroll)}
         >
@@ -61,6 +66,12 @@ export const LayoutSettings = ({ settings }: { settings: DeckSettingsProps }) =>
           </Select.Portal>
         </Select.Root>
       </DeprecatedFormInput>
+      <DeprecatedFormInput label={t('settings enable statusbar label')}>
+        <Input.Switch
+          checked={settings.enableStatusbar}
+          onCheckedChange={(checked) => (settings.enableStatusbar = checked)}
+        />
+      </DeprecatedFormInput>
       <DeprecatedFormInput label={t('settings show hints label')}>
         <Input.Switch checked={settings.showHints} onCheckedChange={(checked) => (settings.showHints = checked)} />
       </DeprecatedFormInput>
@@ -72,12 +83,6 @@ export const LayoutSettings = ({ settings }: { settings: DeckSettingsProps }) =>
           />
         </DeprecatedFormInput>
       )}
-      <DeprecatedFormInput label={t('settings enable statusbar label')}>
-        <Input.Switch
-          checked={settings.enableStatusbar}
-          onCheckedChange={(checked) => (settings.enableStatusbar = checked)}
-        />
-      </DeprecatedFormInput>
     </DeprecatedFormContainer>
   );
 };

package/src/components/DeckSettings/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './DeckSettings';

package/src/components/Plank/Plank.stories.tsx

@@ -0,0 +1,43 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type StoryObj, type Meta } from '@storybook/react';
+
+import { IntentPlugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { GraphPlugin } from '@dxos/plugin-graph';
+import { withTheme, withLayout } from '@dxos/storybook-utils';
+
+import { Plank } from './Plank';
+import translations from '../../translations';
+
+// TODO(burdon): invariant violation: No capability found for dxos.org/plugin/deck/capability/state
+const meta: Meta<typeof Plank> = {
+  title: 'plugins/plugin-deck/Plank',
+  component: Plank,
+  decorators: [
+    withPluginManager({
+      plugins: [IntentPlugin(), GraphPlugin()],
+    }),
+    withTheme,
+    withLayout({ fullscreen: true, tooltips: true }),
+  ],
+  parameters: {
+    layout: 'centered',
+    translations,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    id: 'plank-1',
+    part: 'solo',
+  },
+};

package/src/components/Plank/Plank.tsx

@@ -0,0 +1,230 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, {
+  Fragment,
+  type KeyboardEvent,
+  type PropsWithChildren,
+  memo,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import {
+  LayoutAction,
+  Surface,
+  createIntent,
+  useCapability,
+  useAppGraph,
+  useIntentDispatcher,
+} from '@dxos/app-framework';
+import { debounce } from '@dxos/async';
+import { useNode, type Node } from '@dxos/plugin-graph';
+import { ATTENDABLE_PATH_SEPARATOR, useAttendableAttributes } from '@dxos/react-ui-attention';
+import { StackItem, railGridHorizontal } from '@dxos/react-ui-stack';
+import { mainIntrinsicSize, mx } from '@dxos/react-ui-theme';
+
+import { PlankContentError, PlankError } from './PlankError';
+import { PlankHeading } from './PlankHeading';
+import { PlankLoading } from './PlankLoading';
+import { DeckCapabilities } from '../../capabilities';
+import { useMainSize } from '../../hooks';
+import { parseEntryId } from '../../layout';
+import { DeckAction, type LayoutMode, type Part, type ResolvedPart, type DeckSettingsProps } from '../../types';
+import { useCompanions } from '../../util';
+
+const UNKNOWN_ID = 'unknown_id';
+
+export type PlankProps = {
+  id?: string;
+  companionId?: string;
+  part: Part;
+  path?: string[];
+  order?: number;
+  active?: string[];
+  layoutMode: LayoutMode;
+  settings?: DeckSettingsProps;
+};
+
+type PlankImplProps = Omit<PlankProps, 'id' | 'companionId' | 'part'> & {
+  id: string;
+  part: ResolvedPart;
+  node?: Node;
+  companioned?: 'primary' | 'companion';
+  primary?: Node;
+  companions?: Node[];
+};
+
+const PlankImpl = memo(
+  ({ id, node, part, path, order, active, layoutMode, companioned, primary, companions, settings }: PlankImplProps) => {
+    const { dispatchPromise: dispatch } = useIntentDispatcher();
+    const { deck, popoverAnchorId, scrollIntoView } = useCapability(DeckCapabilities.DeckState);
+    const rootElement = useRef<HTMLDivElement | null>(null);
+    const canResize = layoutMode === 'deck';
+    const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
+
+    const attendableAttrs = useAttendableAttributes(primary?.id ?? 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 { variant } = parseEntryId(id);
+    const sizeKey = `${id.split('+')[0]}${variant ? `${ATTENDABLE_PATH_SEPARATOR}${variant}` : ''}`;
+    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 =
+      (layoutMode === 'solo' && part.startsWith('solo')) || (layoutMode === 'deck' && part === 'deck');
+
+    const sizeAttrs = useMainSize();
+
+    const data = useMemo(
+      () =>
+        node && {
+          subject: node.data,
+          companionTo: primary?.data,
+          variant,
+          path,
+          popoverAnchorId,
+        },
+      [node, node?.data, path, popoverAnchorId, primary?.data],
+    );
+
+    // TODO(wittjosiah): Change prop to accept a component.
+    const placeholder = useMemo(() => <PlankLoading />, []);
+
+    const className = mx(
+      'attention-surface relative',
+      isSolo && mainIntrinsicSize,
+      isSolo && railGridHorizontal,
+      isSolo && 'absolute inset-0',
+      part.startsWith('solo') && 'grid',
+      part === 'deck' && (companioned === 'companion' ? '!border-separator border-ie' : '!border-separator border-li'),
+      part.startsWith('solo-') && 'row-span-2 grid-rows-subgrid 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 ? (
+          <>
+            <PlankHeading
+              id={id}
+              part={part.startsWith('solo-') ? 'solo' : part}
+              node={node}
+              deckEnabled={settings?.enableDeck}
+              canIncrementStart={canIncrementStart}
+              canIncrementEnd={canIncrementEnd}
+              popoverAnchorId={popoverAnchorId}
+              primaryId={primary?.id}
+              companioned={companioned}
+              companions={companions}
+            />
+            <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();
+  return (
+    <div
+      role='none'
+      className={mx('grid grid-cols-[1fr_1fr] absolute inset-0', railGridHorizontal, mainIntrinsicSize)}
+      {...sizeAttrs}
+    >
+      {children}
+    </div>
+  );
+};
+
+export const Plank = ({ id = UNKNOWN_ID, ...props }: PlankProps) => {
+  const { graph } = useAppGraph();
+  const node = useNode(graph, id);
+  const companions = useCompanions(id);
+  const currentCompanion = companions.find(({ id }) => id === props.companionId);
+
+  if (props.companionId) {
+    const Root = props.part === 'solo' ? SplitFrame : Fragment;
+    return (
+      <Root>
+        <PlankImpl
+          id={id}
+          node={node}
+          companioned='primary'
+          {...props}
+          {...(props.part === 'solo' ? { part: 'solo-primary' } : {})}
+        />
+        <PlankImpl
+          id={props.companionId}
+          node={currentCompanion}
+          companioned='companion'
+          primary={node}
+          companions={companions}
+          {...props}
+          {...(props.part === 'solo' ? { part: 'solo-companion' } : { order: props.order! + 1 })}
+        />
+      </Root>
+    );
+  } else {
+    return <PlankImpl id={id} node={node} companions={companions} {...props} />;
+  }
+};