@dxos/plugin-deck 0.7.5-main.499c70c → 0.7.5-main.5ae2ba8

package/src/capabilities/react-root.tsx

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+
+import { DeckCapabilities } from './capabilities';
+import { DeckLayout } from '../components';
+import { DECK_PLUGIN } from '../meta';
+import { type DeckSettingsProps } from '../types';
+
+export default () =>
+  contributes(Capabilities.ReactRoot, {
+    id: DECK_PLUGIN,
+    root: () => {
+      const layout = useCapability(DeckCapabilities.MutableDeckState);
+      const settings = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)!.value;
+
+      const handleDismissToast = useCallback(
+        (id: string) => {
+          const index = layout.toasts.findIndex((toast) => toast.id === id);
+          if (index !== -1) {
+            // Allow time for the toast to animate out.
+            // TODO(burdon): Factor out and unregister timeout.
+            setTimeout(() => {
+              if (layout.toasts[index].id === layout.currentUndoId) {
+                layout.currentUndoId = undefined;
+              }
+              layout.toasts.splice(index, 1);
+            }, 1_000);
+          }
+        },
+        [layout.toasts],
+      );
+
+      return (
+        <DeckLayout
+          showHints={settings.showHints}
+          overscroll={settings.overscroll}
+          onDismissToast={handleDismissToast}
+        />
+      );
+    },
+  });

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
+import { SettingsStore } from '@dxos/local-storage';
+
+import { LayoutSettings } from '../components';
+import { Banner } from '../components/DeckLayout/Banner';
+import { DECK_PLUGIN } from '../meta';
+import { type DeckSettingsProps } from '../types';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, [
+    createSurface({
+      id: `${DECK_PLUGIN}/settings`,
+      role: 'article',
+      filter: (data): data is { subject: SettingsStore<DeckSettingsProps> } =>
+        data.subject instanceof SettingsStore && data.subject.prefix === DECK_PLUGIN,
+      component: ({ data: { subject } }) => <LayoutSettings settings={subject.value} />,
+    }),
+    createSurface({
+      id: `${DECK_PLUGIN}/banner`,
+      role: 'banner',
+      component: ({ data }) => {
+        return <Banner variant={data.variant} />;
+      },
+    }),
+  ]);

package/src/capabilities/settings.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes } from '@dxos/app-framework';
+import { create } from '@dxos/live-object';
+
+import { DECK_PLUGIN } from '../meta';
+import { DeckSettingsSchema, type DeckSettingsProps } from '../types';
+
+export default () => {
+  const settings = create<DeckSettingsProps>({
+    showHints: false,
+    enableNativeRedirect: false,
+    enableIdeStyleStatusbar: true,
+    newPlankPositioning: 'start',
+    overscroll: 'none',
+  });
+
+  return contributes(Capabilities.Settings, { schema: DeckSettingsSchema, prefix: DECK_PLUGIN, value: settings });
+};

package/src/capabilities/state.ts

@@ -0,0 +1,108 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+import { create } from '@dxos/live-object';
+import { LocalStorageStore } from '@dxos/local-storage';
+import { type SidebarState } from '@dxos/react-ui';
+
+import { DeckCapabilities } from './capabilities';
+import { DECK_PLUGIN } from '../meta';
+import { getMode, type Deck, type DeckState } from '../types';
+
+const boolean = /true|false/;
+
+// TODO(thure, 18 Feb 2025): Remove after the next release.
+
+const migrateSidebarStateDefaults = {
+  [`${DECK_PLUGIN}/complementary-sidebar-state`]: 'expanded',
+  [`${DECK_PLUGIN}/sidebar-state`]: 'collapsed',
+};
+
+const migrateSidebarState = () => {
+  Object.entries(migrateSidebarStateDefaults).forEach(([key, defaultValue]) => {
+    if (boolean.test(localStorage.getItem(key) ?? 'never')) {
+      localStorage.setItem(key, defaultValue);
+    }
+  });
+};
+
+export default () => {
+  migrateSidebarState();
+
+  const state = new LocalStorageStore<DeckState>(DECK_PLUGIN, {
+    sidebarState: 'expanded',
+    complementarySidebarState: 'collapsed',
+    complementarySidebarPanel: undefined,
+    dialogContent: null,
+    dialogOpen: false,
+    dialogBlockAlign: undefined,
+    dialogType: undefined,
+    popoverContent: null,
+    popoverAnchorId: undefined,
+    popoverOpen: false,
+    toasts: [],
+    currentUndoId: undefined,
+    activeDeck: 'default',
+    previousDeck: 'default',
+    decks: {
+      default: {
+        initialized: false,
+        active: [],
+        inactive: [],
+        fullscreen: false,
+        solo: undefined,
+        plankSizing: {},
+      },
+    },
+    get deck() {
+      const deck = this.decks[this.activeDeck];
+      invariant(deck, `Deck not found: ${this.activeDeck}`);
+      return deck;
+    },
+    previousMode: {},
+    scrollIntoView: undefined,
+  });
+
+  state
+    .prop({ key: 'sidebarState', type: LocalStorageStore.enum<SidebarState>() })
+    .prop({ key: 'complementarySidebarState', type: LocalStorageStore.enum<SidebarState>() })
+    .prop({ key: 'complementarySidebarPanel', type: LocalStorageStore.string({ allowUndefined: true }) })
+    .prop({ key: 'decks', type: LocalStorageStore.json<Record<string, Deck>>() })
+    .prop({ key: 'activeDeck', type: LocalStorageStore.string() })
+    .prop({ key: 'previousDeck', type: LocalStorageStore.string() });
+
+  const layout = create<Capabilities.Layout>({
+    get mode() {
+      return getMode(state.values.deck);
+    },
+    get dialogOpen() {
+      return state.values.dialogOpen;
+    },
+    get sidebarOpen() {
+      return state.values.sidebarState === 'expanded';
+    },
+    get complementarySidebarOpen() {
+      return state.values.complementarySidebarState === 'expanded';
+    },
+    get workspace() {
+      return state.values.activeDeck;
+    },
+    get active() {
+      return state.values.deck.solo ? [state.values.deck.solo] : state.values.deck.active;
+    },
+    get inactive() {
+      return state.values.deck.inactive;
+    },
+    get scrollIntoView() {
+      return state.values.scrollIntoView;
+    },
+  });
+
+  return [
+    contributes(DeckCapabilities.DeckState, state.values, () => state.close()),
+    contributes(Capabilities.Layout, layout),
+  ];
+};

package/src/capabilities/tools.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  contributes,
+  createIntent,
+  Capabilities,
+  LayoutAction,
+  type PromiseIntentDispatcher,
+} from '@dxos/app-framework';
+import { defineTool, ToolResult } from '@dxos/artifact';
+import { S } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+
+import { meta } from '../meta';
+
+// TODO(burdon): Factor out.
+declare global {
+  interface ToolContextExtensions {
+    dispatch?: PromiseIntentDispatcher;
+    pivotId?: string;
+  }
+}
+
+export default () =>
+  contributes(Capabilities.Tools, [
+    defineTool(meta.id, {
+      name: 'show',
+      // TODO(ZaymonFC): We should update the prompt to teach the LLM the difference between object ids and fully qualified ids.
+      description: `
+        Show an item in the app. Use this tool to open an artifact. 
+        When supplying IDs to show, they must be fully qualified like space:object.
+      `,
+      caption: 'Showing item...',
+      // TODO(wittjosiah): Refactor Layout/Navigation/Deck actions so that they can be used directly.
+      schema: S.Struct({
+        id: S.String.annotations({
+          description: 'The ID of the item to show.',
+        }),
+        pivotId: S.optional(
+          S.String.annotations({
+            description: 'The ID of the chat. If provided, the item will be added after the pivot item.',
+          }),
+        ),
+      }),
+      execute: async ({ id }, { extensions }) => {
+        invariant(extensions?.dispatch, 'No intent dispatcher');
+        const { data, error } = await extensions.dispatch(
+          createIntent(LayoutAction.Open, {
+            subject: [id],
+            part: 'main',
+            options: {
+              pivotId: extensions.pivotId,
+              positioning: 'end',
+            },
+          }),
+        );
+        if (error) {
+          return ToolResult.Error(error.message);
+        }
+
+        return ToolResult.Success(data);
+      },
+    }),
+  ]);

package/src/capabilities/url-handler.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, createIntent, LayoutAction, type PluginsContext } from '@dxos/app-framework';
+import { scheduledEffect } from '@dxos/echo-signals/core';
+
+import { DeckCapabilities } from './capabilities';
+
+// TODO(wittjosiah): Cleanup the url handling. May justify introducing routing capabilities.
+export default async (context: PluginsContext) => {
+  const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher) ?? {};
+  const state = context.requestCapability(DeckCapabilities.MutableDeckState);
+
+  const handleNavigation = async () => {
+    const pathname = window.location.pathname;
+    if (pathname === '/reset') {
+      state.activeDeck = 'default';
+      state.decks = {
+        default: {
+          initialized: false,
+          active: [],
+          inactive: [],
+          fullscreen: false,
+          solo: undefined,
+          plankSizing: {},
+        },
+      };
+      window.location.pathname = '/';
+      return;
+    }
+
+    const [_, nextDeck, nextSolo] = pathname.split('/');
+    if (nextDeck && nextDeck !== state.activeDeck) {
+      await dispatch(createIntent(LayoutAction.SwitchWorkspace, { part: 'workspace', subject: nextDeck }));
+    }
+
+    if (nextSolo && nextSolo !== state.deck.solo) {
+      await dispatch(
+        createIntent(LayoutAction.SetLayoutMode, { part: 'mode', subject: nextSolo, options: { mode: 'solo' } }),
+      );
+    } else if (!nextSolo && state.deck.solo) {
+      await dispatch(createIntent(LayoutAction.SetLayoutMode, { part: 'mode', options: { mode: 'deck' } }));
+    }
+  };
+
+  await handleNavigation();
+  window.addEventListener('popstate', handleNavigation);
+
+  const unsubscribe = scheduledEffect(
+    () => ({ solo: state.deck.solo, activeDeck: state.activeDeck }),
+    ({ solo, activeDeck }) => {
+      const path = solo ? `/${activeDeck}/${solo}` : `/${activeDeck}`;
+      if (window.location.pathname !== path) {
+        // TODO(thure): In some browsers, this only preserves the most recent state change, even though this is not `history.replace`…
+        history.pushState(null, '', `${path}${window.location.search}`);
+      }
+    },
+  );
+
+  return contributes(Capabilities.Null, null, () => {
+    window.removeEventListener('popstate', handleNavigation);
+    unsubscribe();
+  });
+};

package/src/components/DeckLayout/ActiveNode.tsx

@@ -4,8 +4,7 @@
 
 import React from 'react';
 
-import { Surface } from '@dxos/app-framework';
-import { useGraph } from '@dxos/plugin-graph';
+import { Surface, useAppGraph } from '@dxos/app-framework';
 import { useAttended } from '@dxos/react-ui-attention';
 
 import { useNode, useNodeActionExpander } from '../../hooks';
@@ -13,7 +12,7 @@ import { useNode, useNodeActionExpander } from '../../hooks';
 // TODO(burdon): Factor out to effect in plugin set document title.
 export const ActiveNode = () => {
   const [id] = useAttended();
-  const { graph } = useGraph();
+  const { graph } = useAppGraph();
   const activeNode = useNode(graph, id);
   useNodeActionExpander(activeNode);
 

package/src/components/DeckLayout/Banner.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Surface } from '@dxos/app-framework';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import { CloseSidebarButton, ToggleSidebarButton } from './SidebarButton';
+
+export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'topbar' | 'sidebar' }>) => {
+  return (
+    <header
+      className={mx(
+        'flex items-stretch relative plb-1 pis-1 pie-2',
+        variant === 'topbar' &&
+          'fixed inset-inline-0 block-start-[env(safe-area-inset-top)] bs-[--rail-size] border-be border-separator',
+        classNames,
+      )}
+    >
+      {variant === 'sidebar' ? <CloseSidebarButton /> : <ToggleSidebarButton />}
+      <span className='self-center grow mis-1'>Composer</span>
+      {variant === 'topbar' && (
+        <div role='none' className='absolute inset-0 pointer-events-none'>
+          <div role='none' className='grid bs-full pointer-fine:p-1 max-is-md mli-auto pointer-events-auto'>
+            <Surface role='search-input' limit={1} />
+          </div>
+        </div>
+      )}
+      <span role='none' className='grow' />
+      <Surface role='header-end' limit={1} />
+      <Surface role='notch-start' limit={1} />
+    </header>
+  );
+};

package/src/components/DeckLayout/ComplementarySidebar.tsx

@@ -2,89 +2,219 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { useMemo } from 'react';
+import React, {
+  type PropsWithChildren,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  type MouseEvent,
+  Fragment,
+} from 'react';
 
 import {
   createIntent,
-  type LayoutCoordinate,
-  NavigationAction,
-  SLUG_PATH_SEPARATOR,
+  LayoutAction,
   Surface,
+  useAppGraph,
+  useCapabilities,
+  useCapability,
   useIntentDispatcher,
 } from '@dxos/app-framework';
-import { useGraph } from '@dxos/plugin-graph';
-import { Main, ScrollArea } from '@dxos/react-ui';
+import { Main, useTranslation, toLocalizedString, IconButton, ScrollArea as NaturalScrollArea } from '@dxos/react-ui';
 import { useAttended } from '@dxos/react-ui-attention';
-import { railGridHorizontal, StackContext } from '@dxos/react-ui-stack';
-import { mx } from '@dxos/react-ui-theme';
+import { Tabs } from '@dxos/react-ui-tabs';
+import { byPosition } from '@dxos/util';
 
-import { NodePlankHeading } from './NodePlankHeading';
 import { PlankContentError } from './PlankError';
 import { PlankLoading } from './PlankLoading';
-import { useNode, useNodeActionExpander } from '../../hooks';
+import { ToggleComplementarySidebarButton } from './SidebarButton';
+import { DeckCapabilities } from '../../capabilities';
+import { useNode } from '../../hooks';
+import { DECK_PLUGIN } from '../../meta';
 import { type Panel } from '../../types';
-import { useLayout } from '../LayoutContext';
+import { layoutAppliesTopbar, useBreakpoints, useHoistStatusbar } from '../../util';
 
 export type ComplementarySidebarProps = {
-  panels: Panel[];
   current?: string;
 };
 
-export const ComplementarySidebar = ({ panels, current }: ComplementarySidebarProps) => {
-  const { popoverAnchorId } = useLayout();
-  const attended = useAttended();
-  const panel = (panels.find((p) => p.id === current) ?? panels[0])?.id;
-  const id = attended[0] ? `${attended[0]}${SLUG_PATH_SEPARATOR}${panel}` : undefined;
-  const { graph } = useGraph();
-  const node = useNode(graph, id);
+export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) => {
+  const { t } = useTranslation(DECK_PLUGIN);
   const { dispatchPromise: dispatch } = useIntentDispatcher();
-  useNodeActionExpander(node);
+  const layout = useCapability(DeckCapabilities.MutableDeckState);
+  const attended = useAttended();
+  const { graph } = useAppGraph();
+  const node = useNode(graph, attended[0]);
+  const breakpoint = useBreakpoints();
+  const topbar = layoutAppliesTopbar(breakpoint);
+  const hoistStatusbar = useHoistStatusbar(breakpoint);
 
-  const actions = useMemo(
-    () =>
-      panels.map(({ id, label, icon }) => ({
-        id: `complementary-${id}`,
-        data: () => {
-          void dispatch(createIntent(NavigationAction.Open, { activeParts: { complementary: id } }));
-        },
-        properties: {
-          label,
-          icon,
-          menuItemType: 'toggle',
-          isChecked: panel === id,
-        },
-      })),
-    [panel],
+  const panels = useCapabilities(DeckCapabilities.ComplementaryPanel);
+  const availablePanels = panels
+    .filter((panel) => {
+      if (!node || !panel.filter) {
+        return true;
+      }
+
+      return panel.filter(node);
+    })
+    .toSorted(byPosition);
+  const activePanelId = availablePanels.find((panel) => panel.id === current)?.id ?? availablePanels[0]?.id;
+  const [internalValue, setInternalValue] = useState(activePanelId);
+
+  useEffect(() => {
+    setInternalValue(activePanelId);
+  }, [activePanelId]);
+
+  const handleTabClick = useCallback(
+    (event: MouseEvent) => {
+      const nextValue = event.currentTarget.getAttribute('data-value') as string;
+      if (nextValue === activePanelId) {
+        layout.complementarySidebarState = layout.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
+      } else {
+        setInternalValue(nextValue);
+        layout.complementarySidebarState = 'expanded';
+        void dispatch(createIntent(LayoutAction.UpdateComplementary, { part: 'complementary', subject: nextValue }));
+      }
+    },
+    [layout, activePanelId, dispatch],
   );
 
-  // TODO(wittjosiah): Ensure that id is always defined.
-  const coordinate: LayoutCoordinate = useMemo(() => ({ entryId: id ?? 'unknown', part: 'complementary' }), [id]);
+  const data = useMemo(
+    () =>
+      node && {
+        id: node.id,
+        subject: node.data,
+        workspace: layout.activeDeck,
+        popoverAnchorId: layout.popoverAnchorId,
+      },
+    [node, layout.popoverAnchorId],
+  );
 
   // TODO(burdon): Scroll area should be controlled by surface.
   return (
-    <Main.ComplementarySidebar>
-      <StackContext.Provider value={{ size: 'contain', orientation: 'horizontal', rail: true }}>
-        <div role='none' className={mx(railGridHorizontal, 'grid grid-cols-[100%] bs-full')}>
-          <NodePlankHeading coordinate={coordinate} node={node} popoverAnchorId={popoverAnchorId} actions={actions} />
-          <ScrollArea.Root>
-            <ScrollArea.Viewport>
-              {node && (
-                <Surface
-                  key={id}
-                  role={`complementary--${panel}`}
-                  limit={1}
-                  data={{ id, subject: node.properties.object ?? node.properties.space, popoverAnchorId }}
-                  fallback={PlankContentError}
-                  placeholder={<PlankLoading />}
+    <Main.ComplementarySidebar
+      classNames={[
+        topbar && 'block-start-[calc(env(safe-area-inset-top)+var(--rail-size))]',
+        hoistStatusbar && 'block-end-[--statusbar-size]',
+      ]}
+    >
+      <Tabs.Root
+        orientation='vertical'
+        verticalVariant='stateless'
+        value={internalValue}
+        attendableId={attended[0]}
+        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-separator 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'>
+            {availablePanels.map((panel) => (
+              <Tabs.Tab key={panel.id} value={panel.id} asChild>
+                <IconButton
+                  label={toLocalizedString(panel.label, t)}
+                  icon={panel.icon}
+                  size={5}
+                  iconOnly
+                  tooltipSide='left'
+                  data-value={panel.id}
+                  variant={
+                    activePanelId === panel.id
+                      ? layout.complementarySidebarState === 'expanded'
+                        ? 'primary'
+                        : 'default'
+                      : 'ghost'
+                  }
+                  onClick={handleTabClick}
                 />
-              )}
-              <ScrollArea.Scrollbar orientation='vertical'>
-                <ScrollArea.Thumb />
-              </ScrollArea.Scrollbar>
-            </ScrollArea.Viewport>
-          </ScrollArea.Root>
+              </Tabs.Tab>
+            ))}
+          </Tabs.Tablist>
+          {!hoistStatusbar && (
+            <div role='none' className='grid grid-cols-1 auto-rows-[--rail-item] p-1 overflow-y-auto'>
+              <Surface role='status-bar--r0-footer' limit={1} />
+            </div>
+          )}
+          <div role='none' className='hidden lg:grid grid-cols-1 auto-rows-[--rail-action] p-1'>
+            <ToggleComplementarySidebarButton />
+          </div>
         </div>
-      </StackContext.Provider>
+        {availablePanels.map((panel) => (
+          <Tabs.Tabpanel
+            key={panel.id}
+            value={panel.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' })}
+          >
+            <ComplementarySidebarPanel
+              panel={panel}
+              activePanelId={activePanelId}
+              data={data}
+              hoistStatusbar={hoistStatusbar}
+            />
+          </Tabs.Tabpanel>
+        ))}
+      </Tabs.Root>
     </Main.ComplementarySidebar>
   );
 };
+
+type ComplementarySidebarPanelProps = {
+  panel: Panel;
+  activePanelId: string;
+  data?: {
+    id: string;
+    subject: any;
+    workspace: string;
+    popoverAnchorId?: string;
+  };
+  hoistStatusbar: boolean;
+};
+
+const ScrollArea = ({ children }: PropsWithChildren) => {
+  return (
+    <NaturalScrollArea.Root>
+      <NaturalScrollArea.Viewport>{children}</NaturalScrollArea.Viewport>
+      <NaturalScrollArea.Scrollbar orientation='vertical'>
+        <NaturalScrollArea.Thumb />
+      </NaturalScrollArea.Scrollbar>
+    </NaturalScrollArea.Root>
+  );
+};
+
+const ComplementarySidebarPanel = ({ panel, activePanelId, data, hoistStatusbar }: ComplementarySidebarPanelProps) => {
+  const { t } = useTranslation(DECK_PLUGIN);
+
+  if (panel.id !== activePanelId || !data) {
+    return null;
+  }
+
+  const Wrapper = panel.fixed ? Fragment : ScrollArea;
+
+  return (
+    <>
+      <h2 className='flex items-center pli-2 border-separator border-be font-medium'>
+        {toLocalizedString(panel.label, t)}
+      </h2>
+      <Wrapper>
+        <Surface
+          role={`complementary--${activePanelId}`}
+          data={data}
+          fallback={PlankContentError}
+          placeholder={<PlankLoading />}
+        />
+      </Wrapper>
+      {!hoistStatusbar && (
+        <div
+          role='contentinfo'
+          className='flex flex-wrap justify-center items-center border-bs border-separator pbs-1 pbe-[max(env(safe-area-inset-bottom),0.25rem)]'
+        >
+          <Surface role='status-bar--r1-footer' limit={1} />
+        </div>
+      )}
+    </>
+  );
+};