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

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} />;
+  }
+};

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

@@ -2,8 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useCallback } from 'react';
 
+import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
 import {
   Button,
   ButtonGroup,
@@ -15,14 +17,16 @@ import {
 } from '@dxos/react-ui';
 
 import { DECK_PLUGIN } from '../../meta';
-import { type DeckAction } from '../../types';
+import { DeckAction } from '../../types';
 
 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'> & {
@@ -50,16 +54,46 @@ const PlankControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> &
   );
 };
 
+const plankControlSpacing = 'pli-2 plb-3';
+
+type PlankComplimentControlsProps = {
+  primary?: string;
+};
+
+export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankComplimentControlsProps>(
+  ({ primary }, forwardedRef) => {
+    const { t } = useTranslation(DECK_PLUGIN);
+    const { dispatchPromise: dispatch } = useIntentDispatcher();
+    const handleCloseCompanion = useCallback(() => {
+      invariant(primary);
+      return dispatch(createIntent(DeckAction.ChangeCompanion, { primary, companion: null }));
+    }, []);
+    return (
+      <div ref={forwardedRef} className='contents app-no-drag'>
+        <PlankControl
+          label={t('close companion label')}
+          variant='ghost'
+          // icon='ph--minus--regular'
+          icon='ph--caret-left--regular'
+          onClick={handleCloseCompanion}
+          classNames={plankControlSpacing}
+        />
+      </div>
+    );
+  },
+);
+
 // TODO(wittjosiah): Duplicate of stack LayoutControls?
 //   Translations were to be duplicated between packages.
 // 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);
-    const buttonClassNames = variant === 'hide-disabled' ? 'disabled:hidden pli-2 plb-3' : 'pli-2 plb-3';
+    const buttonClassNames =
+      variant === 'hide-disabled' ? `disabled:hidden ${plankControlSpacing}` : plankControlSpacing;
 
     return (
       <ButtonGroup {...props} classNames={['app-no-drag', classNames]} ref={forwardedRef}>
@@ -73,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')}
+                />
+              </>
+            )}
           </>
         )}
 
@@ -105,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')}
           />
         )} */}
 
@@ -114,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'
@@ -123,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 />}
     </>
   );