@dxos/plugin-deck 0.8.4-main.fd6878d → 0.8.4-main.fffef41

package/src/components/Plank/Plank.tsx

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { useFocusFinders } from '@fluentui/react-tabster';
 import React, {
   type KeyboardEvent,
   type PropsWithChildren,
@@ -12,14 +13,8 @@ import React, {
   useRef,
 } from 'react';
 
-import {
-  LayoutAction,
-  Surface,
-  createIntent,
-  useAppGraph,
-  useCapability,
-  useIntentDispatcher,
-} from '@dxos/app-framework';
+import { LayoutAction, createIntent } from '@dxos/app-framework';
+import { Surface, useAppGraph, useCapability, useIntentDispatcher } from '@dxos/app-framework/react';
 import { debounce } from '@dxos/async';
 import { type Node, useNode } from '@dxos/plugin-graph';
 import { ATTENDABLE_PATH_SEPARATOR, useAttentionAttributes } from '@dxos/react-ui-attention';
@@ -37,6 +32,10 @@ import { PlankLoading } from './PlankLoading';
 
 const UNKNOWN_ID = 'unknown_id';
 
+//
+// Plank
+//
+
 export type PlankProps = Pick<PlankComponentProps, 'layoutMode' | 'part' | 'path' | 'order' | 'active' | 'settings'> & {
   id?: string;
   companionId?: string;
@@ -68,7 +67,11 @@ export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProp
   const hasCompanion = !!(companionId && currentCompanion);
 
   return (
-    <PlankContainer solo={props.part === 'solo'} companion={hasCompanion}>
+    <PlankContainer
+      solo={props.part === 'solo'}
+      companion={hasCompanion}
+      encapsulate={!!props.settings?.encapsulatedPlanks}
+    >
       <PlankComponent
         id={id}
         node={node}
@@ -92,7 +95,13 @@ export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProp
   );
 });
 
-const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo: boolean; companion: boolean }>) => {
+//
+// PlankContainer
+//
+
+type PlankContainerProps = PropsWithChildren<{ solo: boolean; companion: boolean; encapsulate: boolean }>;
+
+const PlankContainer = ({ children, solo, companion, encapsulate }: PlankContainerProps) => {
   const sizeAttrs = useMainSize();
   if (!solo) {
     return children;
@@ -102,7 +111,14 @@ const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo:
   return (
     <div
       role='none'
-      className={mx('absolute inset-0 grid', companion && 'grid-cols-[1fr_1fr]', railGridHorizontal, mainIntrinsicSize)}
+      data-popover-collision-boundary={true}
+      className={mx(
+        'absolute inset-[--main-spacing] grid',
+        encapsulate && 'border border-separator rounded overflow-hidden',
+        companion && 'grid-cols-[6fr_4fr]', // TODO(burdon): Resize.
+        railGridHorizontal,
+        mainIntrinsicSize,
+      )}
       {...sizeAttrs}
     >
       {children}
@@ -110,6 +126,10 @@ const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo:
   );
 };
 
+//
+// PlankComponent
+//
+
 type PlankComponentProps = {
   layoutMode: LayoutMode;
   id: string;
@@ -117,7 +137,6 @@ type PlankComponentProps = {
   path?: string[];
   order?: number;
   active?: string[];
-  // TODO(burdon): Change to role?
   companioned?: 'primary' | 'companion';
   node?: Node;
   primary?: Node;
@@ -141,6 +160,7 @@ const PlankComponent = memo(
   }: PlankComponentProps) => {
     const { dispatchPromise: dispatch } = useIntentDispatcher();
     const { deck, popoverAnchorId, scrollIntoView } = useCapability(DeckCapabilities.DeckState);
+    const { findFirstFocusable } = useFocusFinders();
     const canResize = layoutMode === 'deck';
 
     const attentionAttrs = useAttentionAttributes(primary?.id ?? id);
@@ -164,18 +184,21 @@ const PlankComponent = memo(
 
     // 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();
+      if (event.target === event.currentTarget) {
+        switch (event.key) {
+          case 'Escape':
+            rootElement.current?.closest('main')?.focus();
+            break;
+          case 'Enter':
+            rootElement.current && findFirstFocusable(rootElement.current)?.focus();
+            break;
+        }
       }
     }, []);
 
     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' });
+        layoutMode === 'deck' && rootElement.current?.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 }));
       }
@@ -190,34 +213,42 @@ const PlankComponent = memo(
     const data = useMemo(
       () =>
         node && {
+          attendableId: id,
           subject: node.data,
           companionTo: primary?.data,
+          properties: node.properties,
           variant,
           path,
           popoverAnchorId,
         },
-      [node, node?.data, path, popoverAnchorId, primary?.data, variant],
+      [node, node?.data, node?.properties, path, popoverAnchorId, primary?.data, variant],
     );
 
     // TODO(wittjosiah): Change prop to accept a component.
     const placeholder = useMemo(() => <PlankLoading />, []);
 
     const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
+    const fullscreen = layoutMode === 'solo--fullscreen';
     const className = mx(
       'attention-surface relative dx-focus-ring-inset-over-all density-coarse',
-      isSolo && mainIntrinsicSize,
-      isSolo && railGridHorizontal,
       isSolo && 'absolute inset-0',
+      isSolo && mainIntrinsicSize,
+      railGridHorizontal,
       part.startsWith('solo') && 'grid',
+      part.startsWith('solo-') && 'grid-rows-subgrid row-span-2 min-is-0',
+      fullscreen && 'grid-rows-1',
       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',
+      settings?.encapsulatedPlanks &&
+        !part.startsWith('solo') &&
+        'mli-[--main-spacing] !border-separator border rounded overflow-hidden',
     );
 
     return (
       <Root
         ref={rootElement}
         data-testid='deck.plank'
+        data-popover-collision-boundary={true}
         tabIndex={0}
         {...(part.startsWith('solo')
           ? ({ ...sizeAttrs, className } as any)
@@ -234,19 +265,21 @@ const PlankComponent = memo(
       >
         {node ? (
           <>
-            <PlankHeading
-              id={id}
-              part={part.startsWith('solo-') ? 'solo' : part}
-              node={node}
-              layoutMode={layoutMode}
-              deckEnabled={settings?.enableDeck}
-              canIncrementStart={canIncrementStart}
-              canIncrementEnd={canIncrementEnd}
-              popoverAnchorId={popoverAnchorId}
-              primaryId={primary?.id}
-              companioned={companioned}
-              companions={companions}
-            />
+            {!fullscreen && (
+              <PlankHeading
+                id={id}
+                part={part.startsWith('solo-') ? 'solo' : part}
+                node={node}
+                layoutMode={layoutMode}
+                deckEnabled={settings?.enableDeck}
+                canIncrementStart={canIncrementStart}
+                canIncrementEnd={canIncrementEnd}
+                popoverAnchorId={popoverAnchorId}
+                primaryId={primary?.id}
+                companioned={companioned}
+                companions={companions}
+              />
+            )}
             <Surface
               key={node.id}
               role='article'
@@ -259,7 +292,6 @@ const PlankComponent = memo(
         ) : (
           <PlankError id={id} part={part} />
         )}
-
         {canResize && <StackItem.ResizeHandle />}
       </Root>
     );

package/src/components/Plank/PlankControls.tsx

@@ -4,11 +4,12 @@
 
 import React, { forwardRef, useCallback } from 'react';
 
-import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+import { createIntent } from '@dxos/app-framework';
+import { useIntentDispatcher } from '@dxos/app-framework/react';
 import { invariant } from '@dxos/invariant';
 import { ButtonGroup, type ButtonGroupProps, type ButtonProps, IconButton, useTranslation } from '@dxos/react-ui';
 
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 import { DeckAction, type LayoutMode } from '../../types';
 
 export type PlankControlHandler = (event: DeckAction.PartAdjustment) => void;
@@ -32,7 +33,7 @@ export type PlankControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
 };
 
 const PlankControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> & { label: string; icon: string }) => {
-  return <IconButton iconOnly label={label} icon={icon} size={5} variant='ghost' tooltipSide='bottom' {...props} />;
+  return <IconButton label={label} icon={icon} iconOnly variant='ghost' tooltipSide='bottom' {...props} />;
 };
 
 const plankControlSpacing = 'pli-2';
@@ -43,7 +44,7 @@ type PlankComplimentControlsProps = {
 
 export const PlankCompanionControls = forwardRef<HTMLDivElement, PlankComplimentControlsProps>(
   ({ primary }, forwardedRef) => {
-    const { t } = useTranslation(DECK_PLUGIN);
+    const { t } = useTranslation(meta.id);
     const { dispatchPromise: dispatch } = useIntentDispatcher();
     const handleCloseCompanion = useCallback(() => {
       invariant(primary);
@@ -71,7 +72,7 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
     { children, classNames, variant = 'default', capabilities, layoutMode, pin, close = false, onClick, ...props },
     forwardedRef,
   ) => {
-    const { t } = useTranslation(DECK_PLUGIN);
+    const { t } = useTranslation(meta.id);
     const buttonClassNames =
       variant === 'hide-disabled' ? `disabled:hidden ${plankControlSpacing}` : plankControlSpacing;
 

package/src/components/Plank/PlankError.tsx

@@ -8,13 +8,13 @@ import { type Node } from '@dxos/plugin-graph';
 import { useTranslation } from '@dxos/react-ui';
 import { descriptionMessage, mx } from '@dxos/react-ui-theme';
 
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 
 import { PlankHeading, type PlankHeadingProps } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
 
 export const PlankContentError = ({ error }: { error?: Error }) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
   const errorString = error?.toString() ?? '';
   return (
     <div role='none' className='overflow-y-auto p-8 attention-surface grid place-items-center'>

package/src/components/Plank/PlankHeading.tsx

@@ -4,7 +4,8 @@
 
 import React, { Fragment, type MouseEvent, memo, useCallback, useEffect, useMemo } from 'react';
 
-import { LayoutAction, Surface, createIntent, useAppGraph, useIntentDispatcher } from '@dxos/app-framework';
+import { LayoutAction, createIntent } from '@dxos/app-framework';
+import { Surface, useAppGraph, useIntentDispatcher } from '@dxos/app-framework/react';
 import { type Node } from '@dxos/plugin-graph';
 import { Icon, IconButton, Popover, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { StackItem, type StackItemSigilAction } from '@dxos/react-ui-stack';
@@ -13,7 +14,7 @@ import { hoverableControls, hoverableFocusedWithinControls } from '@dxos/react-u
 
 import { useBreakpoints } from '../../hooks';
 import { parseEntryId } from '../../layout';
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 import { DeckAction, type LayoutMode, PLANK_COMPANION_TYPE, type ResolvedPart } from '../../types';
 import { soloInlinePadding } from '../fragments';
 
@@ -53,14 +54,14 @@ export const PlankHeading = memo(
     layoutMode,
     actions = [],
   }: PlankHeadingProps) => {
-    const { t } = useTranslation(DECK_PLUGIN);
+    const { t } = useTranslation(meta.id);
     const { dispatchPromise: dispatch } = useIntentDispatcher();
     const { graph } = useAppGraph();
     const breakpoint = useBreakpoints();
     const icon = node?.properties?.icon ?? 'ph--placeholder--regular';
     const label = pending
       ? t('pending heading')
-      : toLocalizedString(node?.properties?.label ?? ['plank heading fallback label', { ns: DECK_PLUGIN }], t);
+      : toLocalizedString(node?.properties?.label ?? ['plank heading fallback label', { ns: meta.id }], t);
 
     const isCompanionNode = node?.type === PLANK_COMPANION_TYPE;
 
@@ -106,7 +107,7 @@ export const PlankHeading = memo(
 
     const handleAction = useCallback(
       (action: StackItemSigilAction) => {
-        typeof action.data === 'function' && void action.data?.({ parent: node, caller: DECK_PLUGIN });
+        typeof action.data === 'function' && void action.data?.({ parent: node, caller: meta.id });
       },
       [node],
     );
@@ -135,7 +136,7 @@ export const PlankHeading = memo(
       [dispatch, id, part],
     );
 
-    const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${DECK_PLUGIN}/${node.id}` ? Popover.Anchor : Fragment;
+    const ActionRoot = node && popoverAnchorId === `dxos.org/ui/${meta.id}/${node.id}` ? Popover.Anchor : Fragment;
 
     const handleTabClick = useCallback(
       (event: MouseEvent) => {
@@ -162,7 +163,8 @@ export const PlankHeading = memo(
             ? [
                 hoverableControls,
                 hoverableFocusedWithinControls,
-                '*:transition-opacity *:opacity-[--controls-opacity] bg-transparent border-transparent transition-[background-color,border-color] hover-hover:hover:bg-headerSurface focus-within:bg-headerSurface hover-hover:hover:border-subduedSeparator focus-within:border-subduedSeparator',
+                '*:transition-opacity *:opacity-[--controls-opacity] bg-transparent border-transparent transition-[background-color,border-color]',
+                'hover-hover:hover:bg-headerSurface focus-within:bg-headerSurface hover-hover:hover:border-subduedSeparator focus-within:border-subduedSeparator',
               ]
             : []),
         ]}
@@ -178,7 +180,6 @@ export const PlankHeading = memo(
                 icon={icon}
                 iconOnly={companions.length > MAX_COMPANIONS && node?.id !== id}
                 label={toLocalizedString(label, t)}
-                size={5}
                 variant={node?.id === id ? 'primary' : 'ghost'}
                 onClick={handleTabClick}
               />
@@ -201,7 +202,7 @@ export const PlankHeading = memo(
               ) : (
                 <StackItem.SigilButton>
                   <span className='sr-only'>{label}</span>
-                  <Icon icon={icon} size={5} />
+                  <Icon icon={icon} />
                 </StackItem.SigilButton>
               )}
             </ActionRoot>

package/src/components/Sidebar/ComplementarySidebar.tsx

@@ -12,27 +12,29 @@ import React, {
   useState,
 } from 'react';
 
-import { LayoutAction, Surface, createIntent, useCapability, useIntentDispatcher } from '@dxos/app-framework';
+import { LayoutAction, createIntent } from '@dxos/app-framework';
+import { Surface, useCapability, useIntentDispatcher } from '@dxos/app-framework/react';
 import { IconButton, type Label, Main, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { Tabs } from '@dxos/react-ui-tabs';
+import { mx } from '@dxos/react-ui-theme';
 
 import { DeckCapabilities } from '../../capabilities';
 import { type DeckCompanion, getCompanionId, useBreakpoints, useDeckCompanions, useHoistStatusbar } from '../../hooks';
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
 import { PlankContentError, PlankLoading } from '../Plank';
 
 import { ToggleComplementarySidebarButton } from './SidebarButton';
 
-const label = ['complementary sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
+const label = ['complementary sidebar title', { ns: meta.id }] satisfies Label;
 
 export type ComplementarySidebarProps = {
   current?: string;
 };
 
 export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
   const { dispatchPromise: dispatch } = useIntentDispatcher();
   const layout = useCapability(DeckCapabilities.MutableDeckState);
   const layoutMode = getMode(layout.deck);
@@ -91,7 +93,11 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
       <Tabs.Root orientation='vertical' verticalVariant='stateless' value={internalValue} classNames='contents'>
         <div
           role='none'
-          className='absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size] pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-subduedSeparator grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag'
+          className={mx(
+            'absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size]',
+            'pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-subduedSeparator',
+            'grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag',
+          )}
         >
           <Tabs.Tablist classNames='grid grid-cols-1 auto-rows-[--rail-action] p-1 gap-1 !overflow-y-auto'>
             {companions.map((companion) => (
@@ -99,7 +105,6 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
                 <IconButton
                   label={toLocalizedString(companion.properties.label, t)}
                   icon={companion.properties.icon}
-                  size={5}
                   iconOnly
                   tooltipSide='left'
                   data-value={getCompanionId(companion.id)}
@@ -129,8 +134,12 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
             <Tabs.Tabpanel
               key={getCompanionId(companion.id)}
               value={getCompanionId(companion.id)}
-              classNames='absolute data-[state="inactive"]:-z-[1] inset-block-0 inline-start-0 is-[calc(100%-var(--r0-size))] lg:is-[--r1-size] grid grid-cols-1 grid-rows-[var(--rail-size)_1fr_min-content] pbs-[env(safe-area-inset-top)]'
-              {...(layout.complementarySidebarState !== 'expanded' && { inert: 'true' })}
+              classNames={[
+                'absolute data-[state="inactive"]:-z-[1] overflow-hidden',
+                'inset-block-0 inline-start-0 is-[calc(100%-var(--r0-size))] lg:is-[--r1-size]',
+                'grid grid-cols-1 grid-rows-[var(--rail-size)_1fr_min-content] pbs-[env(safe-area-inset-top)]',
+              ]}
+              {...(layout.complementarySidebarState !== 'expanded' && { inert: true })}
             >
               <ComplementarySidebarPanel
                 companion={companion}
@@ -155,12 +164,8 @@ type ComplementarySidebarPanelProps = {
   hoistStatusbar: boolean;
 };
 
-const ScrollArea = ({ children }: PropsWithChildren) => {
-  return <div className='flex flex-col grow overflow-x-hidden overflow-y-auto scrollbar-thin'>{children}</div>;
-};
-
 const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }: ComplementarySidebarPanelProps) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
 
   if (getCompanionId(companion.id) !== activeId && !data) {
     return null;
@@ -170,9 +175,20 @@ const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }
 
   return (
     <>
-      <h2 className='flex items-center pli-2 border-subduedSeparator border-be font-medium'>
-        {toLocalizedString(companion.properties.label, t)}
-      </h2>
+      <div role='none' className='flex items-center p-1 gap-1 border-be border-subduedSeparator'>
+        <IconButton
+          label={toLocalizedString(companion.properties.label, t)}
+          icon={companion.properties.icon}
+          iconOnly
+          tooltipSide='left'
+          data-value={getCompanionId(companion.id)}
+          classNames='bs-10 is-10'
+          variant='default'
+        />
+        <div role='none' className='pli-1'>
+          {toLocalizedString(companion.properties.label, t)}
+        </div>
+      </div>
       <Wrapper>
         <Surface
           role={`deck-companion--${getCompanionId(companion.id)}`}
@@ -192,3 +208,7 @@ const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }
     </>
   );
 };
+
+const ScrollArea = ({ children }: PropsWithChildren) => {
+  return <div className='flex flex-col grow overflow-x-hidden overflow-y-auto scrollbar-thin'>{children}</div>;
+};

package/src/components/Sidebar/Sidebar.tsx

@@ -4,16 +4,16 @@
 
 import React, { useMemo } from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework';
+import { Surface, useCapability } from '@dxos/app-framework/react';
 import { type Label, Main } from '@dxos/react-ui';
 
 import { DeckCapabilities } from '../../capabilities';
 import { useBreakpoints, useHoistStatusbar } from '../../hooks';
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
 
-const label = ['sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
+const label = ['sidebar title', { ns: meta.id }] satisfies Label;
 
 export const Sidebar = () => {
   const { popoverAnchorId, activeDeck: current, deck } = useCapability(DeckCapabilities.DeckState);

package/src/components/Sidebar/SidebarButton.tsx

@@ -4,24 +4,25 @@
 
 import React, { useCallback } from 'react';
 
-import { LayoutAction, createIntent, useCapability, useIntentDispatcher } from '@dxos/app-framework';
+import { LayoutAction, createIntent } from '@dxos/app-framework';
+import { useCapability, useIntentDispatcher } from '@dxos/app-framework/react';
 import { IconButton, type IconButtonProps, type ThemedClassName, useTranslation } from '@dxos/react-ui';
 
 import { DeckCapabilities } from '../../capabilities';
 import { getCompanionId, useDeckCompanions } from '../../hooks';
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 
 export const ToggleSidebarButton = ({
   classNames,
   variant = 'ghost',
 }: ThemedClassName<Pick<IconButtonProps, 'variant'>>) => {
   const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
   return (
     <IconButton
       variant={variant}
-      iconOnly
       icon='ph--sidebar--regular'
+      iconOnly
       size={4}
       label={t('open navigation sidebar label')}
       onClick={() =>
@@ -34,12 +35,12 @@ export const ToggleSidebarButton = ({
 
 export const CloseSidebarButton = () => {
   const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
   return (
     <IconButton
       variant='ghost'
-      iconOnly
       icon='ph--caret-line-left--regular'
+      iconOnly
       size={4}
       label={t('close navigation sidebar label')}
       onClick={() => (layoutContext.sidebarState = 'collapsed')}
@@ -55,18 +56,18 @@ export const ToggleComplementarySidebarButton = ({
 }: ThemedClassName<{ inR0?: boolean; current?: string }>) => {
   const { dispatchPromise: dispatch } = useIntentDispatcher();
   const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
 
   const companions = useDeckCompanions();
   const handleClick = useCallback(async () => {
     layoutContext.complementarySidebarState =
       layoutContext.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
-    const firstCompanion = companions[0];
-    if (layoutContext.complementarySidebarState === 'expanded' && !current && firstCompanion) {
+    const subject = layoutContext.complementarySidebarPanel ?? (companions[0] && getCompanionId(companions[0].id));
+    if (layoutContext.complementarySidebarState === 'expanded' && !current && subject) {
       await dispatch(
         createIntent(LayoutAction.UpdateComplementary, {
           part: 'complementary',
-          subject: getCompanionId(firstCompanion.id),
+          subject,
         }),
       );
     }
@@ -74,14 +75,14 @@ export const ToggleComplementarySidebarButton = ({
 
   return (
     <IconButton
-      iconOnly
-      onClick={handleClick}
       variant='ghost'
-      label={t('open complementary sidebar label')}
       classNames={['[&>svg]:-scale-x-100', classNames]}
       icon='ph--sidebar-simple--regular'
+      iconOnly
+      label={t('open complementary sidebar label')}
       size={inR0 ? 5 : 4}
       tooltipSide={inR0 ? 'left' : undefined}
+      onClick={handleClick}
     />
   );
 };

package/src/events.ts

@@ -4,8 +4,8 @@
 
 import { Events } from '@dxos/app-framework';
 
-import { DECK_PLUGIN } from './meta';
+import { meta } from './meta';
 
 export namespace DeckEvents {
-  export const StateReady = Events.createStateEvent(`${DECK_PLUGIN}/state-ready`);
+  export const StateReady = Events.createStateEvent(`${meta.id}/state-ready`);
 }

package/src/hooks/useCompanions.ts

@@ -4,7 +4,7 @@
 
 import { useMemo } from 'react';
 
-import { useAppGraph } from '@dxos/app-framework';
+import { useAppGraph } from '@dxos/app-framework/react';
 import { useConnections } from '@dxos/plugin-graph';
 import { byPosition } from '@dxos/util';
 

package/src/hooks/useDeckCompanions.ts

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Label, useAppGraph } from '@dxos/app-framework';
+import { type Label } from '@dxos/app-framework';
+import { useAppGraph } from '@dxos/app-framework/react';
 import { type Node, ROOT_ID, useConnections } from '@dxos/plugin-graph';
 import { type Position, byPosition } from '@dxos/util';
 

package/src/hooks/useHoistStatusbar.ts

@@ -4,16 +4,18 @@
 
 import { useMemo } from 'react';
 
-import { Capabilities, useCapability } from '@dxos/app-framework';
+import { Capabilities } from '@dxos/app-framework';
+import { useCapability } from '@dxos/app-framework/react';
 import { useThemeContext } from '@dxos/react-ui';
 
-import { DECK_PLUGIN } from '../meta';
+import { meta } from '../meta';
 import type { DeckSettingsProps, LayoutMode } from '../types';
 
 export const useHoistStatusbar = (breakpoint: string, layoutMode?: LayoutMode): boolean => {
-  const enableStatusbar = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)!.value
-    .enableStatusbar;
   const { safeAreaPadding } = useThemeContext();
+  const enableStatusbar = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(meta.id)?.value
+    .enableStatusbar;
+
   return useMemo(() => {
     return (
       breakpoint === 'desktop' &&

package/src/meta.ts

@@ -3,11 +3,14 @@
 //
 
 import { type PluginMeta } from '@dxos/app-framework';
-
-export const DECK_PLUGIN = 'dxos.org/plugin/deck' as const;
+import { trim } from '@dxos/util';
 
 export const meta: PluginMeta = {
-  id: DECK_PLUGIN,
+  id: 'dxos.org/plugin/deck',
   name: 'Layout',
+  description: trim`
+    Flexible layout system for arranging workspace views in tabs, splits, and panels.
+    Customize your workspace organization with drag-and-drop layout management.
+  `,
   icon: 'ph--layout--regular',
 };