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

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,
@@ -27,32 +28,29 @@ import { Stack, StackContext, DEFAULT_HORIZONTAL_SIZE } from '@dxos/react-ui-sta
 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 { PlankContentError } from './PlankError';
-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 = ({ 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,
@@ -120,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
    */
@@ -156,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(
     () => [
@@ -260,13 +267,13 @@ 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={itemsCount - 1}
                   style={padding}
-                  ref={deckRef}
+                  onScroll={handleScroll}
                 >
                   {active.map((entryId) => (
                     <Fragment key={entryId}>
@@ -278,6 +285,7 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
                         order={order[entryId]}
                         active={active}
                         layoutMode={layoutMode}
+                        settings={settings}
                       />
                     </Fragment>
                   ))}
@@ -296,15 +304,18 @@ export const DeckLayout = ({ overscroll, showHints, onDismissToast }: DeckLayout
                     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>
       )}
 

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/{DeckLayout → Plank}/Plank.tsx

@@ -5,8 +5,8 @@
 import React, {
   Fragment,
   type KeyboardEvent,
-  memo,
   type PropsWithChildren,
+  memo,
   useCallback,
   useLayoutEffect,
   useMemo,
@@ -14,24 +14,27 @@ import React, {
 } from 'react';
 
 import {
-  createIntent,
   LayoutAction,
   Surface,
+  createIntent,
   useCapability,
   useAppGraph,
   useIntentDispatcher,
 } from '@dxos/app-framework';
 import { debounce } from '@dxos/async';
-import { useAttendableAttributes } from '@dxos/react-ui-attention';
+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 { NodePlankHeading } from './NodePlankHeading';
 import { PlankContentError, PlankError } from './PlankError';
+import { PlankHeading } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
 import { DeckCapabilities } from '../../capabilities';
-import { useNode, useMainSize } from '../../hooks';
-import { DeckAction, type LayoutMode, type Part, type ResolvedPart, surfaceVariantSeparator } from '../../types';
+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';
 
@@ -43,42 +46,34 @@ export type PlankProps = {
   order?: number;
   active?: string[];
   layoutMode: LayoutMode;
+  settings?: DeckSettingsProps;
 };
 
-type PlankImplProps = Omit<PlankProps, 'companionId' | 'part'> & {
+type PlankImplProps = Omit<PlankProps, 'id' | 'companionId' | 'part'> & {
+  id: string;
   part: ResolvedPart;
-  surfaceVariant?: string;
+  node?: Node;
   companioned?: 'primary' | 'companion';
-  primaryId?: string;
+  primary?: Node;
+  companions?: Node[];
 };
 
 const PlankImpl = memo(
-  ({
-    id = UNKNOWN_ID,
-    part,
-    path,
-    order,
-    active,
-    layoutMode,
-    surfaceVariant,
-    companioned,
-    primaryId,
-  }: PlankImplProps) => {
+  ({ id, node, part, path, order, active, layoutMode, companioned, primary, companions, settings }: 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 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 sizeKey = `${id.split('+')[0]}${surfaceVariant ? `${surfaceVariantSeparator}${surfaceVariant}` : ''}`;
+    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) => {
@@ -116,11 +111,12 @@ const PlankImpl = memo(
       () =>
         node && {
           subject: node.data,
-          variant: surfaceVariant,
+          companionTo: primary?.data,
+          variant,
           path,
           popoverAnchorId,
         },
-      [node, node?.data, path, popoverAnchorId, surfaceVariant],
+      [node, node?.data, path, popoverAnchorId, primary?.data],
     );
 
     // TODO(wittjosiah): Change prop to accept a component.
@@ -133,7 +129,7 @@ const PlankImpl = memo(
       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 min-is-0',
+      part.startsWith('solo-') && 'row-span-2 grid-rows-subgrid min-is-0',
       part === 'solo-companion' && '!border-separator border-is',
     );
 
@@ -157,16 +153,17 @@ const PlankImpl = memo(
       >
         {node ? (
           <>
-            <NodePlankHeading
+            <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}
-              primaryId={primaryId}
-              surfaceVariant={surfaceVariant}
+              companions={companions}
             />
             <Surface
               key={node.id}
@@ -199,23 +196,35 @@ const SplitFrame = ({ children }: PropsWithChildren<{}>) => {
   );
 };
 
-export const Plank = (props: PlankProps) => {
+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 {...props} {...(props.part === 'solo' ? { part: 'solo-primary' } : {})} companioned='primary' />
         <PlankImpl
+          id={id}
+          node={node}
+          companioned='primary'
           {...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 })}
+          {...(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 {...props} />;
+    return <PlankImpl id={id} node={node} companions={companions} {...props} />;
   }
 };

package/src/components/{DeckLayout → Plank}/PlankControls.tsx

@@ -24,7 +24,9 @@ export type PlankControlHandler = (event: DeckAction.PartAdjustment) => void;
 export type PlankCapabilities = {
   incrementStart?: boolean;
   incrementEnd?: boolean;
+  deck?: boolean;
   solo?: boolean;
+  companion?: boolean;
 };
 
 export type PlankControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
@@ -71,7 +73,8 @@ export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankCompliment
         <PlankControl
           label={t('close companion label')}
           variant='ghost'
-          icon='ph--minus--regular'
+          // icon='ph--minus--regular'
+          icon='ph--caret-left--regular'
           onClick={handleCloseCompanion}
           classNames={plankControlSpacing}
         />
@@ -85,7 +88,7 @@ export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankCompliment
 // NOTE(thure): Pinning & unpinning are disabled indefinitely.
 export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
   (
-    { onClick, variant = 'default', capabilities: can, isSolo, pin, close = false, children, classNames, ...props },
+    { children, classNames, variant = 'default', capabilities, isSolo, pin, close = false, onClick, ...props },
     forwardedRef,
   ) => {
     const { t } = useTranslation(DECK_PLUGIN);
@@ -104,31 +107,33 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
           />
         )} */}
 
-        {can.solo && (
-          <PlankControl
-            label={isSolo ? t('show deck plank label') : t('show solo plank label')}
-            classNames={buttonClassNames}
-            onClick={() => onClick?.('solo')}
-            icon={isSolo ? 'ph--corners-in--regular' : 'ph--corners-out--regular'}
-          />
-        )}
-
-        {!isSolo && can.solo && (
+        {capabilities.deck && capabilities.solo && (
           <>
             <PlankControl
-              label={t('increment start label')}
-              disabled={!can.incrementStart}
+              label={isSolo ? t('show deck plank label') : t('show solo plank label')}
               classNames={buttonClassNames}
-              onClick={() => onClick?.('increment-start')}
-              icon='ph--caret-left--regular'
-            />
-            <PlankControl
-              label={t('increment end label')}
-              disabled={!can.incrementEnd}
-              classNames={buttonClassNames}
-              onClick={() => onClick?.('increment-end')}
-              icon='ph--caret-right--regular'
+              icon={isSolo ? 'ph--corners-in--regular' : 'ph--corners-out--regular'}
+              onClick={() => onClick?.('solo')}
             />
+
+            {!isSolo && (
+              <>
+                <PlankControl
+                  label={t('increment start label')}
+                  disabled={!capabilities.incrementStart}
+                  classNames={buttonClassNames}
+                  icon='ph--caret-left--regular'
+                  onClick={() => onClick?.('increment-start')}
+                />
+                <PlankControl
+                  label={t('increment end label')}
+                  disabled={!capabilities.incrementEnd}
+                  classNames={buttonClassNames}
+                  icon='ph--caret-right--regular'
+                  onClick={() => onClick?.('increment-end')}
+                />
+              </>
+            )}
           </>
         )}
 
@@ -136,8 +141,8 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
           <PlankControl
             label={t('pin end label')}
             classNames={buttonClassNames}
-            onClick={() => onClick?.('pin-end')}
             icon='ph--caret-line-right--regular'
+            onClick={() => onClick?.('pin-end')}
           />
         )} */}
 
@@ -145,7 +150,6 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
           <PlankControl
             label={t(`${typeof close === 'string' ? 'minify' : 'close'} label`)}
             classNames={buttonClassNames}
-            onClick={() => onClick?.('close')}
             data-testid='plankHeading.close'
             icon={
               close === 'minify-start'
@@ -154,6 +158,17 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
                   ? 'ph--caret-line-right--regular'
                   : 'ph--x--regular'
             }
+            onClick={() => onClick?.('close')}
+          />
+        )}
+
+        {capabilities.companion && (
+          <PlankControl
+            label={t('open companion label')}
+            classNames={buttonClassNames}
+            data-testid='plankHeading.companion'
+            icon='ph--square-split-horizontal--regular'
+            onClick={() => onClick?.('companion')}
           />
         )}
         {children}

package/src/components/{DeckLayout → Plank}/PlankError.tsx

@@ -8,7 +8,7 @@ import { type Node } from '@dxos/plugin-graph';
 import { useTranslation } from '@dxos/react-ui';
 import { descriptionText, mx } from '@dxos/react-ui-theme';
 
-import { NodePlankHeading, type NodePlankHeadingProps } from './NodePlankHeading';
+import { PlankHeading, type PlankHeadingProps } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
 import { DECK_PLUGIN } from '../../meta';
 
@@ -38,7 +38,7 @@ export const PlankError = ({
   error,
 }: {
   id: string;
-  part: NodePlankHeadingProps['part'];
+  part: PlankHeadingProps['part'];
   node?: Node;
   error?: Error;
 }) => {
@@ -48,7 +48,7 @@ export const PlankError = ({
   }, []);
   return (
     <>
-      <NodePlankHeading id={id} part={part} node={node} pending={!timedOut} />
+      <PlankHeading id={id} part={part} node={node} pending={!timedOut} />
       {timedOut ? <PlankContentError error={error} /> : <PlankLoading />}
     </>
   );