@dxos/plugin-deck 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/containers/Deck/Banner.tsx

@@ -5,15 +5,17 @@
 import React from 'react';
 
 import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 import { type ThemedClassName, useTranslation } from '@dxos/react-ui';
 import { mx, osTranslations } from '@dxos/ui-theme';
 
 import { meta } from '#meta';
+import { VersionInfo } from '#types';
 
 import { CloseSidebarButton, ToggleSidebarButton } from '../Sidebar';
 
 export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'topbar' | 'sidebar' }>) => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   return (
     <header
@@ -29,13 +31,12 @@ export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'top
       {variant === 'topbar' && (
         <div className='absolute inset-0 pointer-events-none'>
           <div className='grid h-full pointer-fine:p-1 max-w-md mx-auto pointer-events-auto'>
-            <Surface.Surface role='search-input' limit={1} />
+            <Surface.Surface type={AppSurface.SearchInput} limit={1} />
           </div>
         </div>
       )}
       <span className='grow' />
-      <Surface.Surface role='version-info' limit={1} />
-      <Surface.Surface role='notch-start' limit={1} />
+      <Surface.Surface type={VersionInfo} limit={1} />
     </header>
   );
 };

package/src/containers/Deck/Deck.tsx

@@ -3,8 +3,8 @@
 //
 
 import { DeckContent, DeckContentProps } from './DeckContent';
-import { DeckRoot, DeckLayoutChangeRequest, DeckRootProps } from './DeckRoot';
-import { DeckViewport, DeckMultiMode, DeckSoloMode, DeckViewportProps, DeckContentEmpty } from './DeckViewport';
+import { DeckLayoutChangeRequest, DeckRoot, DeckRootProps } from './DeckRoot';
+import { DeckContentEmpty, DeckMultiMode, DeckSoloMode, DeckViewport, DeckViewportProps } from './DeckViewport';
 
 /**
  * Radix-style composite Deck component.
@@ -18,4 +18,4 @@ export const Deck = {
   SoloMode: DeckSoloMode,
 };
 
-export type { DeckLayoutChangeRequest, DeckRootProps, DeckContentProps, DeckViewportProps };
+export type { DeckContentProps, DeckLayoutChangeRequest, DeckRootProps, DeckViewportProps };

package/src/containers/Deck/DeckPlank.tsx

@@ -0,0 +1,187 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useFocusFinders } from '@fluentui/react-tabster';
+import React, { type KeyboardEvent, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Splitter, type ThemedClassName } from '@dxos/react-ui';
+
+import { Companion, Plank } from '#components';
+import { useCompanionSplit } from '#hooks';
+import { type LayoutMode, type ResolvedPart, type Settings } from '#types';
+
+import { PlankCompanionControls, PlankControls } from './PlankControls';
+import { PlankErrorFallback, PlankLoading } from './PlankFallback';
+import { useDeckPlank } from './useDeckPlank';
+
+const PLANK_LOADING = <PlankLoading />;
+
+export type DeckPlankProps = ThemedClassName<{
+  id: string;
+  part: ResolvedPart;
+  layoutMode: LayoutMode;
+  active?: string[];
+  /** Whether the companion pane should be shown for this plank (gated further by attention in multi-mode). */
+  companionShown?: boolean;
+  settings?: Settings.Settings;
+  path?: string[];
+}>;
+
+/**
+ * Connected deck plank: resolves the node, companions, actions and operation handlers via
+ * {@link useDeckPlank} and renders the presentational {@link Plank} — wrapped in a {@link Splitter}
+ * beside a {@link Companion} when a companion is open. Replaces the legacy
+ * `PlankContainer`/`PlankComponent`/`PlankHeading` tree.
+ */
+export const DeckPlank = memo(
+  ({ id, part, layoutMode, active, companionShown, settings, path, classNames }: DeckPlankProps) => {
+    const { findFirstFocusable } = useFocusFinders();
+    const rootRef = useRef<HTMLDivElement>(null);
+    const {
+      node,
+      companions,
+      resolvedCompanionId,
+      hasCompanion,
+      companionOrientation,
+      capabilities,
+      sigilActions,
+      popoverAnchorId,
+      scrollIntoView,
+      onAction,
+      onAdjust,
+      onScrollIntoView,
+      onUpdateCompanion,
+    } = useDeckPlank({ id, part, layoutMode, active, companionShown, deckEnabled: settings?.enableDeck });
+
+    // Memoize the split point per orientation so toggling side-by-side ↔ stacked restores each one.
+    const { size: companionSize, onSizeChange: onCompanionSizeChange } = useCompanionSplit(companionOrientation);
+
+    // Newly opened/navigated planks are flagged via `scrollIntoView`; focus the pane so it gains
+    // attention, then clear the one-shot flag.
+    useEffect(() => {
+      if (scrollIntoView === id) {
+        rootRef.current?.focus();
+        onScrollIntoView(undefined);
+      }
+    }, [scrollIntoView, id, onScrollIntoView]);
+
+    // Tabster's focus group should move focus to Main on Escape, but something blocks it; handle directly.
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLDivElement>) => {
+        if (event.target === event.currentTarget) {
+          switch (event.key) {
+            case 'Escape':
+              event.currentTarget.closest('main')?.focus();
+              break;
+            case 'Enter':
+              findFirstFocusable(event.currentTarget)?.focus();
+              break;
+          }
+        }
+      },
+      [findFirstFocusable],
+    );
+
+    // Stable reference so Plank's useMemo on articleData doesn't bust every render.
+    const articleData = useMemo(() => ({ path }), [path]);
+
+    // Keep the companion panel mounted for 250ms after hasCompanion goes false so the Splitter's
+    // CSS transition can complete before the subtree is removed from the DOM.
+    const [companionMounted, setCompanionMounted] = useState(hasCompanion);
+    useEffect(() => {
+      if (hasCompanion) {
+        setCompanionMounted(true);
+        return;
+      }
+      const timer = setTimeout(() => setCompanionMounted(false), 250);
+      return () => clearTimeout(timer);
+    }, [hasCompanion]);
+
+    const companionControls = useMemo(() => <PlankCompanionControls primary={id} />, [id]);
+
+    if (!node) {
+      return PLANK_LOADING;
+    }
+
+    const controls = (
+      <PlankControls
+        capabilities={capabilities}
+        layoutMode={layoutMode}
+        close={part === 'complementary' ? 'minify-end' : true}
+        onClick={onAdjust}
+      />
+    );
+
+    const navbarEnd =
+      part !== 'complementary' ? (
+        <Surface.Surface type={AppSurface.NavbarEnd} data={{ subject: node.data } satisfies AppSurface.NavbarEndData} />
+      ) : undefined;
+
+    const sigilFooter = (
+      <Surface.Surface type={AppSurface.MenuFooter} data={{ subject: node.data } satisfies AppSurface.MenuFooterData} />
+    );
+
+    // In fullscreen the toolbar is hidden so the content fills the viewport.
+    const headless = layoutMode === 'solo--fullscreen';
+
+    // Splitter.Root is always the outer element so <Plank> stays at the same tree position regardless of
+    // whether the companion is open. A root-element-type change (Plank ↔ Splitter.Root) would force React
+    // to unmount and remount the entire subtree on every companion toggle, resetting article state.
+    //
+    // `mode` drives the animated open/close: switching between 'split' and 'start' triggers the Splitter's
+    // built-in 250ms CSS transition. `companionMounted` trails `hasCompanion` by 250ms on close so the
+    // panel stays in the DOM long enough for the collapse animation to finish before being unmounted.
+    return (
+      <Splitter.Root
+        orientation={companionOrientation}
+        anchor='end'
+        mode={hasCompanion ? 'split' : 'start'}
+        resizable={hasCompanion}
+        size={companionSize}
+        minSize={20}
+        onSizeChange={onCompanionSizeChange}
+        classNames={classNames}
+      >
+        <Splitter.Panel position='start'>
+          <Plank
+            ref={rootRef}
+            node={node}
+            attendableId={id}
+            related={part === 'complementary'}
+            actions={sigilActions}
+            onAction={onAction}
+            popoverAnchorId={popoverAnchorId}
+            articleData={articleData}
+            controls={controls}
+            navbarEnd={navbarEnd}
+            sigilFooter={sigilFooter}
+            fallback={PlankErrorFallback}
+            placeholder={PLANK_LOADING}
+            headless={headless}
+            onKeyDown={handleKeyDown}
+          />
+        </Splitter.Panel>
+        {companionMounted && (
+          <>
+            <Splitter.Handle />
+            <Splitter.Panel position='end'>
+              <Companion
+                companions={companions}
+                value={resolvedCompanionId}
+                onValueChange={onUpdateCompanion}
+                attendableId={id}
+                companionTo={node.data}
+                controls={companionControls}
+              />
+            </Splitter.Panel>
+          </>
+        )}
+      </Splitter.Root>
+    );
+  },
+);
+
+DeckPlank.displayName = 'DeckPlank';