@dxos/plugin-deck 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/components/Pane/Pane.tsx

@@ -0,0 +1,178 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Slot } from '@radix-ui/react-slot';
+import React, { type ComponentPropsWithRef, forwardRef } from 'react';
+
+import { AttentionSigilButton } from '@dxos/app-toolkit/ui';
+import { DensityProvider, IconButton, type ThemedClassName, composableProps, slottable } from '@dxos/react-ui';
+import { type AttendableId, type Related, useAttention } from '@dxos/react-ui-attention';
+import { iconSize, mx } from '@dxos/ui-theme';
+import type { Merge } from '@dxos/util';
+
+//
+// Pane
+//
+// A presentational, radix-style component for a single deck pane: a toolbar rail above a content body.
+// A plank always has a toolbar, so it implements that layout directly rather than wrapping the
+// generalized `Panel`. A companion pane is just a Pane whose toolbar holds `Pane.Tabs` instead of a
+// sigil/title. Intentionally free of app-framework concepts (capabilities, operations, Surface) —
+// containers compose the sigil, controls, tabs and content surface into the slots.
+//
+
+//
+// Root
+//
+
+// Root accepts arbitrary div attributes (the container wires tabIndex, data-* and key handlers), so it
+// is a plain forwarding div rather than the narrowly-typed `slottable` used by the toolbar/content slots.
+type PaneRootProps = ThemedClassName<ComponentPropsWithRef<'div'>>;
+
+const PaneRoot = forwardRef<HTMLDivElement, PaneRootProps>(({ children, ...props }, forwardedRef) => (
+  <div
+    {...composableProps(props, {
+      role: 'article',
+      classNames:
+        'dx-container flex flex-col dx-attention-surface relative dx-focus-ring-inset-over-all dx-density-lg min-w-0',
+    })}
+    ref={forwardedRef}
+  >
+    {children}
+  </div>
+));
+
+PaneRoot.displayName = 'Pane.Root';
+
+//
+// Toolbar
+//
+
+const PaneToolbar = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : 'div';
+  return (
+    <Comp
+      {...composableProps(props, {
+        style: iconSize(5),
+        classNames: 'flex items-center gap-1 px-1 shrink-0 h-(--dx-rail-content) bg-header-surface',
+      })}
+      ref={forwardedRef}
+    >
+      <DensityProvider density='lg'>{children}</DensityProvider>
+    </Comp>
+  );
+});
+
+PaneToolbar.displayName = 'Pane.Toolbar';
+
+//
+// Content
+//
+
+const PaneContent = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : 'div';
+  return (
+    <Comp {...composableProps(props, { classNames: 'flex-1 min-h-0' })} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+PaneContent.displayName = 'Pane.Content';
+
+//
+// Title
+//
+
+type PaneTitleProps = ThemedClassName<ComponentPropsWithRef<'h1'>> & AttendableId & Related;
+
+/** Attention-aware plank title; colors to the accent when the plank (or a related companion) is attended. */
+const PaneTitle = forwardRef<HTMLHeadingElement, PaneTitleProps>(
+  ({ attendableId, related, classNames, ...props }, forwardedRef) => {
+    const { hasAttention, isAncestor, isRelated } = useAttention(attendableId);
+    return (
+      <h1
+        {...props}
+        data-attention={((related && isRelated) || hasAttention || isAncestor).toString()}
+        className={mx(
+          'px-1 min-w-0 w-0 grow truncate font-medium text-base-fg data-[attention=true]:text-accent-text self-center',
+          classNames,
+        )}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+
+PaneTitle.displayName = 'Pane.Title';
+
+//
+// Tabs
+//
+
+export type PaneTab = {
+  id: string;
+  icon: string;
+  /** Already-localized label. */
+  label: string;
+};
+
+type PaneTabsProps = Merge<
+  ThemedClassName<{
+    tabs: ReadonlyArray<PaneTab>;
+    value?: string;
+    onValueChange?: (id: string) => void;
+    /** Collapse inactive tabs to icon-only once the tab count exceeds this. */
+    maxTabs?: number;
+  }>,
+  AttendableId,
+  Related
+>;
+
+/** Full-height tab strip for a companion plank's toolbar; selects among available companions. */
+const PaneTabs = forwardRef<HTMLDivElement, PaneTabsProps>(
+  ({ tabs, value, onValueChange, maxTabs = 5, attendableId, related, classNames }, forwardedRef) => {
+    // The active tab only reads as primary when the plank (shared with its companion) is attended.
+    const { hasAttention, isAncestor, isRelated } = useAttention(attendableId);
+    const attended = (related && isRelated) || hasAttention || isAncestor;
+    return (
+      <div
+        role='tablist'
+        className={mx('flex-1 min-w-0 overflow-x-auto scrollbar-none flex items-center gap-1', classNames)}
+        ref={forwardedRef}
+      >
+        {tabs.map(({ id, icon, label }) => (
+          <IconButton
+            key={id}
+            role='tab'
+            aria-selected={value === id}
+            tabIndex={value === id ? 0 : -1}
+            data-id={id}
+            icon={icon}
+            iconOnly={tabs.length > maxTabs && value !== id}
+            label={label}
+            variant={value === id && attended ? 'primary' : 'ghost'}
+            onClick={() => onValueChange?.(id)}
+          />
+        ))}
+      </div>
+    );
+  },
+);
+
+PaneTabs.displayName = 'Pane.Tabs';
+
+//
+// Pane
+//
+
+export const Pane = {
+  Root: PaneRoot,
+  Toolbar: PaneToolbar,
+  Sigil: AttentionSigilButton,
+  Title: PaneTitle,
+  Tabs: PaneTabs,
+  Content: PaneContent,
+};
+
+export type { PaneRootProps, PaneTabsProps, PaneTitleProps };

package/src/components/Pane/index.ts

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

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

@@ -0,0 +1,103 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { type Node } from '@dxos/plugin-graph';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Organization, Person } from '@dxos/types';
+
+import { DeckState, OperationHandler } from '#capabilities';
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+
+import { Plank } from './Plank';
+
+random.seed(99);
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  AppPlugin.addOperationHandlerModule({
+    activate: OperationHandler,
+  }),
+  Plugin.make,
+);
+
+const TestExtension = Capability.contributes(
+  Capabilities.ReactSurface,
+  Surface.create({
+    id: 'storyArticle',
+    filter: Surface.makeFilter(AppSurface.Article),
+    component: ({ data: { subject } }) =>
+      subject ? (
+        <Syntax.Root data={subject}>
+          <Syntax.Content>
+            <Syntax.Viewport>
+              <Syntax.Code />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
+      ) : (
+        <Loading />
+      ),
+  }),
+);
+
+// A border makes each plank's bounds obvious against the deck surface.
+const PLANK_CLASSNAMES = 'border border-separator';
+
+const useNode = (data: Obj.Any, icon: string): Node.Node =>
+  useMemo(
+    () => ({ id: data.id, type: 'test', data, properties: { label: Obj.getLabel(data) ?? 'Untitled', icon } }),
+    [data, icon],
+  );
+
+// Two planks side by side; focus either to move attention (sigil/title take the accent color).
+const DefaultStory = () => {
+  const [organization, person] = useMemo(
+    () => [Organization.make({ name: random.company.name() }), Person.make({ fullName: random.person.fullName() })],
+    [],
+  );
+  const organizationNode = useNode(organization, 'ph--building-office--regular');
+  const personNode = useNode(person, 'ph--user--regular');
+
+  return (
+    <div className='flex h-full gap-3 p-3 bg-deck-surface'>
+      <Plank node={organizationNode} classNames={PLANK_CLASSNAMES} />
+      <Plank node={personNode} classNames={PLANK_CLASSNAMES} />
+    </div>
+  );
+};
+
+const meta: Meta = {
+  title: 'plugins/plugin-deck/components/Plank',
+  decorators: [
+    withPluginManager({ plugins: [...corePlugins(), TestPlugin()], capabilities: [TestExtension] }),
+    withAttention(),
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+  ],
+  parameters: { layout: 'fullscreen', translations },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = { render: () => <DefaultStory /> };

package/src/components/Plank/Plank.tsx

@@ -0,0 +1,149 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, {
+  type ComponentProps,
+  Fragment,
+  type KeyboardEventHandler,
+  type ReactNode,
+  forwardRef,
+  useMemo,
+} from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface, AttentionSigil, type AttentionSigilAction } from '@dxos/app-toolkit/ui';
+import { type Node } from '@dxos/plugin-graph';
+import { Icon, Popover, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+
+import { meta } from '#meta';
+
+import { Pane } from '../Pane';
+
+type SurfaceProps = ComponentProps<typeof Surface.Surface>;
+
+export type PlankProps = ThemedClassName<{
+  node: Node.Node;
+  /** Attendable id; defaults to the node id. */
+  attendableId?: string;
+  /** Grouped sigil menu actions; when present the sigil opens a menu, otherwise it is a plain button. */
+  actions?: AttentionSigilAction[][];
+  onAction?: (action: AttentionSigilAction) => void;
+  /** Toolbar controls rendered after the title (e.g. close/solo/fullscreen). */
+  controls?: ReactNode;
+  /** Toolbar content rendered between the title and the controls (e.g. a NavbarEnd surface). */
+  navbarEnd?: ReactNode;
+  /** Sigil-menu footer content (e.g. a MenuFooter surface). */
+  sigilFooter?: ReactNode;
+  /** Highlight the title/sigil when a related (companion) region is attended. */
+  related?: boolean;
+  /** Render the title in a muted style (e.g. while the subject is loading). */
+  pending?: boolean;
+  /** When it matches `${meta.key}:${node.id}`, anchors a popover to the sigil. */
+  popoverAnchorId?: string;
+  /** Extra Article surface data merged over the computed defaults (e.g. companionTo/variant/path). */
+  articleData?: Partial<AppSurface.ArticleData>;
+  /** Error fallback for the content surface. */
+  fallback?: SurfaceProps['fallback'];
+  /** Loading placeholder for the content surface. */
+  placeholder?: SurfaceProps['placeholder'];
+  /** Render only the content surface, omitting the toolbar (e.g. fullscreen). */
+  headless?: boolean;
+  // TODO(burdon): Why is this required?
+  onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+}>;
+
+/**
+ * A higher-level deck pane bound to a graph {@link Node}: renders the node's sigil, title and content
+ * Surface inside a {@link Pane}, and makes itself the node's attendable region. Toolbar controls
+ * (close/solo/etc.) and framework surfaces (NavbarEnd/MenuFooter) are supplied by the container via
+ * slots so this component stays free of capabilities/operations.
+ */
+export const Plank = forwardRef<HTMLDivElement, PlankProps>(
+  (
+    {
+      classNames,
+      node,
+      attendableId = node.id,
+      actions,
+      onAction,
+      controls,
+      navbarEnd,
+      sigilFooter,
+      related,
+      pending,
+      popoverAnchorId,
+      articleData,
+      fallback,
+      placeholder,
+      headless,
+      onKeyDown,
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(meta.profile.key);
+    const attentionAttrs = useAttentionAttributes(attendableId);
+    const icon = node.properties?.icon ?? 'ph--circle-dashed--regular';
+    const label = toLocalizedString(node.properties?.label ?? '', t);
+    const data = useMemo<AppSurface.ArticleData>(
+      () => ({ attendableId, subject: node.data, properties: node.properties, popoverAnchorId, ...articleData }),
+      [attendableId, node.data, node.properties, popoverAnchorId, articleData],
+    );
+
+    // Anchor the sigil's popover only when this plank's menu is the active popover target.
+    const ActionRoot = popoverAnchorId === `${meta.profile.key}:${node.id}` ? Popover.Anchor : Fragment;
+
+    return (
+      <Pane.Root
+        ref={forwardedRef}
+        classNames={classNames}
+        tabIndex={0}
+        onKeyDown={onKeyDown}
+        {...attentionAttrs}
+        data-testid='deck.plank'
+      >
+        {!headless && (
+          <Pane.Toolbar>
+            <ActionRoot>
+              {actions && actions.length > 0 ? (
+                <AttentionSigil
+                  icon={icon}
+                  related={related}
+                  attendableId={attendableId}
+                  actions={actions}
+                  onAction={onAction}
+                  triggerLabel={label}
+                >
+                  {sigilFooter}
+                </AttentionSigil>
+              ) : (
+                <Pane.Sigil attendableId={attendableId}>
+                  <span className='sr-only'>{label}</span>
+                  <Icon icon={icon} />
+                </Pane.Sigil>
+              )}
+            </ActionRoot>
+            <Pane.Title attendableId={attendableId} related={related} classNames={pending && 'text-description'}>
+              {label}
+            </Pane.Title>
+            {navbarEnd}
+            {controls}
+          </Pane.Toolbar>
+        )}
+        <Pane.Content>
+          <Surface.Surface
+            key={node.id}
+            type={AppSurface.Article}
+            data={data}
+            limit={1}
+            fallback={fallback}
+            placeholder={placeholder}
+          />
+        </Pane.Content>
+      </Pane.Root>
+    );
+  },
+);
+
+Plank.displayName = 'Plank';

package/src/components/Plank/index.ts

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

package/src/components/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type ComponentType, lazy } from 'react';
-
-export const DeckSettings: ComponentType<any> = lazy(() => import('./DeckSettings'));
-
+export { Companion, type CompanionProps } from './Companion';
 export { Matrix } from './Matrix';
+export { Pane, type PaneTab } from './Pane';
+export { Plank, type PlankProps } from './Plank';

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';