@dxos/plugin-deck 0.7.5-main.9d26e3a → 0.7.5-main.9d2a38b

package/src/DeckPlugin.ts

@@ -0,0 +1,123 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { setAutoFreeze } from 'immer';
+
+import { allOf, Capabilities, contributes, defineModule, definePlugin, Events, oneOf } from '@dxos/app-framework';
+import { AttentionEvents } from '@dxos/plugin-attention';
+import { translations as stackTranslations } from '@dxos/react-ui-stack';
+
+import {
+  AppGraphBuilder,
+  CheckAppScheme,
+  DeckState,
+  LayoutIntentResolver,
+  LayoutState,
+  LocationState,
+  NavigationIntentResolver,
+  ReactContext,
+  ReactRoot,
+  DeckSettings,
+  ReactSurface,
+  UrlHandler,
+} from './capabilities';
+import { DeckEvents } from './events';
+import { meta } from './meta';
+import translations from './translations';
+
+// NOTE(Zan): When producing values with immer, we shouldn't auto-freeze them because
+//   our signal implementation needs to add some hidden properties to the produced values.
+// TODO(Zan): Move this to a more global location if we use immer more broadly.
+setAutoFreeze(false);
+
+export const DeckPlugin = () =>
+  definePlugin(meta, [
+    //
+    // Settings
+    //
+
+    defineModule({
+      id: `${meta.id}/module/settings`,
+      activatesOn: Events.SetupSettings,
+      activate: DeckSettings,
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-surface`,
+      activatesOn: Events.Startup,
+      activate: ReactSurface,
+    }),
+
+    //
+    // Layout
+    //
+
+    defineModule({
+      id: `${meta.id}/module/layout`,
+      activatesOn: oneOf(Events.Startup, Events.SetupAppGraph),
+      activatesAfter: [Events.LayoutReady],
+      activate: LayoutState,
+    }),
+    defineModule({
+      id: `${meta.id}/module/deck`,
+      activatesOn: oneOf(Events.Startup, Events.SetupAppGraph),
+      activatesAfter: [DeckEvents.StateReady],
+      activate: DeckState,
+    }),
+    defineModule({
+      id: `${meta.id}/module/translations`,
+      activatesOn: Events.SetupTranslations,
+      activate: () => contributes(Capabilities.Translations, [...translations, ...stackTranslations]),
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-context`,
+      activatesOn: Events.Startup,
+      activate: ReactContext,
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-root`,
+      activatesOn: Events.Startup,
+      activate: ReactRoot,
+    }),
+    defineModule({
+      id: `${meta.id}/module/layout-intent-resolver`,
+      activatesOn: Events.SetupIntents,
+      activate: LayoutIntentResolver,
+    }),
+    defineModule({
+      id: `${meta.id}/module/app-graph-builder`,
+      activatesOn: Events.SetupAppGraph,
+      activate: AppGraphBuilder,
+    }),
+
+    //
+    // Navigation
+    //
+
+    defineModule({
+      id: `${meta.id}/module/location`,
+      activatesOn: oneOf(Events.Startup, Events.SetupAppGraph),
+      activatesAfter: [Events.LocationReady],
+      activate: LocationState,
+    }),
+    defineModule({
+      id: `${meta.id}/module/check-app-scheme`,
+      activatesOn: Events.SettingsReady,
+      activate: CheckAppScheme,
+    }),
+    defineModule({
+      id: `${meta.id}/module/url`,
+      activatesOn: allOf(
+        Events.DispatcherReady,
+        Events.LayoutReady,
+        Events.LocationReady,
+        AttentionEvents.AttentionReady,
+      ),
+      activate: UrlHandler,
+    }),
+    defineModule({
+      id: `${meta.id}/module/navigation-intent-resolver`,
+      activatesOn: Events.SetupIntents,
+      activate: NavigationIntentResolver,
+    }),
+  ]);

package/src/capabilities/capabilities.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { defineCapability, type Label } from '@dxos/app-framework';
+import { type DeepReadonly } from '@dxos/util';
+
+import { type DeckContextType } from '../components';
+import { DECK_PLUGIN } from '../meta';
+
+export namespace DeckCapabilities {
+  export const DeckState = defineCapability<DeepReadonly<DeckContextType>>(`${DECK_PLUGIN}/capability/state`);
+  export const MutableDeckState = defineCapability<DeckContextType>(`${DECK_PLUGIN}/capability/state`);
+  export const ComplementaryPanel = defineCapability<{ id: string; label: Label; icon: string }>(
+    `${DECK_PLUGIN}/capability/complementary-panel`,
+  );
+}

package/src/capabilities/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './capabilities';
+export * from './layout';
+export * from './navigation';
+export * from './settings';

package/src/capabilities/layout/app-graph-builder.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  Capabilities,
+  contributes,
+  createIntent,
+  LayoutAction,
+  NavigationAction,
+  openIds,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+import { createExtension, type Node, ROOT_ID } from '@dxos/plugin-graph';
+
+import { DECK_PLUGIN } from '../../meta';
+
+export default (context: PluginsContext) =>
+  contributes(
+    Capabilities.AppGraphBuilder,
+    createExtension({
+      id: DECK_PLUGIN,
+      filter: (node): node is Node<null> => node.id === ROOT_ID,
+      actions: () => {
+        // NOTE(Zan): This is currently disabled.
+        // TODO(Zan): Fullscreen needs to know the active node and provide that to the layout part.
+        const _fullscreen = {
+          id: `${LayoutAction.SetLayoutMode._tag}/fullscreen`,
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            await dispatch(createIntent(LayoutAction.SetLayoutMode, { layoutMode: 'fullscreen' }));
+          },
+          properties: {
+            label: ['toggle fullscreen label', { ns: DECK_PLUGIN }],
+            icon: 'ph--arrows-out--regular',
+            keyBinding: {
+              macos: 'ctrl+meta+f',
+              windows: 'shift+ctrl+f',
+            },
+          },
+        };
+
+        const closeCurrent = {
+          id: `${NavigationAction.Close._tag}/current`,
+          data: async () => {
+            const attention = context.requestCapability(AttentionCapabilities.Attention);
+            const attended = attention.current.at(-1);
+            if (attended) {
+              const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+              await dispatch(createIntent(NavigationAction.Close, { activeParts: { main: [attended] } }));
+            }
+          },
+          properties: {
+            label: ['close current label', { ns: DECK_PLUGIN }],
+            icon: 'ph--x--regular',
+          },
+        };
+
+        const closeOthers = {
+          id: `${NavigationAction.Close._tag}/others`,
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            const location = context.requestCapability(Capabilities.Location);
+            const attention = context.requestCapability(AttentionCapabilities.Attention);
+            const attended = attention.current.at(-1);
+            const ids = openIds(location.active, ['main']).filter((id) => id !== attended);
+            await dispatch(
+              createIntent(NavigationAction.Close, {
+                activeParts: { main: ids },
+              }),
+            );
+          },
+          properties: {
+            label: ['close others label', { ns: DECK_PLUGIN }],
+            icon: 'ph--x-square--regular',
+          },
+        };
+
+        const closeAll = {
+          id: `${NavigationAction.Close._tag}/all`,
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            const location = context.requestCapability(Capabilities.Location);
+            await dispatch(
+              createIntent(NavigationAction.Close, {
+                activeParts: { main: openIds(location.active, ['main']) },
+              }),
+            );
+          },
+          properties: {
+            label: ['close all label', { ns: DECK_PLUGIN }],
+            icon: 'ph--x-circle--regular',
+          },
+        };
+
+        const layoutMode = context.requestCapabilities(Capabilities.Layout)[0]?.layoutMode;
+        return layoutMode === 'deck' ? [closeCurrent, closeOthers, closeAll] : [];
+      },
+    }),
+  );

package/src/capabilities/layout/deck.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { contributes } from '@dxos/app-framework';
+import { LocalStorageStore } from '@dxos/local-storage';
+
+import { type DeckContextType } from '../../components';
+import { DeckCapabilities } from '../capabilities';
+
+// NOTE: The key is this currently for backwards compatibility of storage.
+const DECK_KEY = 'dxos.org/settings/deck';
+
+export default () => {
+  const deck = new LocalStorageStore<DeckContextType>(DECK_KEY, {
+    plankSizing: {},
+    currentUndoId: undefined,
+    // TODO(Zan): Cap depth!
+    layoutModeHistory: [],
+  });
+
+  deck.prop({ key: 'plankSizing', type: LocalStorageStore.json<Record<string, number>>() });
+
+  return contributes(DeckCapabilities.DeckState, deck.values, () => deck.close());
+};

package/src/capabilities/layout/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const DeckState = lazy(() => import('./deck'));
+export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
+export const LayoutIntentResolver = lazy(() => import('./intent-resolver'));
+export const LayoutState = lazy(() => import('./state'));
+export const ReactContext = lazy(() => import('./react-context'));
+export const ReactRoot = lazy(() => import('./react-root'));

package/src/capabilities/layout/intent-resolver.ts

@@ -0,0 +1,128 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { batch } from '@preact/signals-core';
+
+import {
+  Capabilities,
+  createResolver,
+  contributes,
+  IntentAction,
+  LayoutAction,
+  openIds,
+  Toast as ToastSchema,
+  type LayoutMode,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { S } from '@dxos/echo-schema';
+import { log } from '@dxos/log';
+
+import { DECK_PLUGIN } from '../../meta';
+import { DeckAction } from '../../types';
+import { DeckCapabilities } from '../capabilities';
+
+export default (context: PluginsContext) =>
+  contributes(Capabilities.IntentResolver, [
+    createResolver(DeckAction.UpdatePlankSize, (data) => {
+      const deck = context.requestCapability(DeckCapabilities.MutableDeckState);
+      deck.plankSizing[data.id] = data.size;
+    }),
+    createResolver(IntentAction.ShowUndo, (data) => {
+      const deck = context.requestCapability(DeckCapabilities.MutableDeckState);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const { undoPromise: undo } = context.requestCapability(Capabilities.IntentDispatcher);
+
+      // TODO(wittjosiah): Support undoing further back than the last action.
+      if (deck.currentUndoId) {
+        layout.toasts = layout.toasts.filter((toast) => toast.id !== deck.currentUndoId);
+      }
+      deck.currentUndoId = `${IntentAction.ShowUndo._tag}-${Date.now()}`;
+      layout.toasts = [
+        ...layout.toasts,
+        {
+          id: deck.currentUndoId,
+          title: data.message ?? ['undo available label', { ns: DECK_PLUGIN }],
+          duration: 10_000,
+          actionLabel: ['undo action label', { ns: DECK_PLUGIN }],
+          actionAlt: ['undo action alt', { ns: DECK_PLUGIN }],
+          closeLabel: ['undo close label', { ns: DECK_PLUGIN }],
+          onAction: () => undo(),
+        },
+      ];
+    }),
+    createResolver(
+      LayoutAction.SetLayout,
+      ({ element, state, component, subject, anchorId, dialogBlockAlign, dialogType }) => {
+        const layout = context.requestCapability(Capabilities.MutableLayout);
+        switch (element) {
+          case 'sidebar': {
+            layout.sidebarOpen = state ?? !layout.sidebarOpen;
+            break;
+          }
+
+          case 'complementary': {
+            layout.complementarySidebarOpen = !!state;
+            // TODO(thure): Hoist content into the c11y sidebar of Deck.
+            // layout.complementarySidebarContent = component || subject ? { component, subject } : null;
+            break;
+          }
+
+          case 'dialog': {
+            layout.dialogOpen = state ?? Boolean(component);
+            layout.dialogContent = component ? { component, subject } : null;
+            layout.dialogBlockAlign = dialogBlockAlign ?? 'center';
+            layout.dialogType = dialogType;
+            break;
+          }
+
+          case 'popover': {
+            layout.popoverOpen = state ?? Boolean(component);
+            layout.popoverContent = component ? { component, subject } : null;
+            layout.popoverAnchorId = anchorId;
+            break;
+          }
+
+          case 'toast': {
+            if (S.is(ToastSchema)(subject)) {
+              layout.toasts = [...layout.toasts, subject];
+            }
+            break;
+          }
+        }
+      },
+    ),
+    createResolver(LayoutAction.SetLayoutMode, (data) => {
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const deck = context.requestCapability(DeckCapabilities.MutableDeckState);
+
+      const setMode = (mode: LayoutMode) => {
+        const main = openIds(location.active, ['main']);
+        const solo = openIds(location.active, ['solo']);
+        const current = layout.layoutMode === 'solo' ? solo : main;
+        // When un-soloing, the solo entry is added to the deck.
+        const next = mode === 'solo' ? solo : [...main, ...solo];
+        const removed = current.filter((id) => !next.includes(id));
+        const closed = Array.from(new Set([...location.closed.filter((id) => !next.includes(id)), ...removed]));
+
+        location.closed = closed;
+        layout.layoutMode = mode;
+      };
+
+      return batch(() => {
+        if ('layoutMode' in data) {
+          deck.layoutModeHistory.push(layout.layoutMode);
+          setMode(data.layoutMode);
+        } else if (data.revert) {
+          setMode(deck.layoutModeHistory.pop() ?? 'solo');
+        } else {
+          log.warn('Invalid layout mode', data);
+        }
+      });
+    }),
+    createResolver(LayoutAction.ScrollIntoView, ({ id }) => {
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      layout.scrollIntoView = id;
+    }),
+  ]);

package/src/capabilities/layout/react-context.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+
+import { DeckContext, LayoutContext } from '../../components';
+import { DECK_PLUGIN } from '../../meta';
+import { DeckCapabilities } from '../capabilities';
+
+export default () =>
+  contributes(Capabilities.ReactContext, {
+    id: DECK_PLUGIN,
+    context: (props: PropsWithChildren) => {
+      const layout = useCapability(Capabilities.Layout);
+      const deck = useCapability(DeckCapabilities.MutableDeckState);
+
+      return (
+        <LayoutContext.Provider value={layout}>
+          <DeckContext.Provider value={deck}>{props.children}</DeckContext.Provider>
+        </LayoutContext.Provider>
+      );
+    },
+  });

package/src/capabilities/layout/react-root.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Capabilities, contributes, useCapabilities, useCapability } from '@dxos/app-framework';
+
+import { DeckLayout } from '../../components';
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps } from '../../types';
+import { DeckCapabilities } from '../capabilities';
+
+export default () =>
+  contributes(Capabilities.ReactRoot, {
+    id: DECK_PLUGIN,
+    root: () => {
+      const layout = useCapability(Capabilities.Layout);
+      const location = useCapability(Capabilities.Location);
+      const deck = useCapability(DeckCapabilities.MutableDeckState);
+      const settings = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)!.value;
+      const panels = useCapabilities(DeckCapabilities.ComplementaryPanel);
+
+      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 === deck.currentUndoId) {
+                deck.currentUndoId = undefined;
+              }
+              layout.toasts.splice(index, 1);
+            }, 1_000);
+          }
+        },
+        [layout.toasts],
+      );
+
+      return (
+        <DeckLayout
+          layoutParts={location.active}
+          showHints={settings.showHints}
+          overscroll={settings.overscroll}
+          toasts={layout.toasts}
+          panels={panels}
+          onDismissToast={handleDismissToast}
+        />
+      );
+    },
+  });

package/src/capabilities/layout/state.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, type LayoutMode, type Layout } from '@dxos/app-framework';
+import { LocalStorageStore } from '@dxos/local-storage';
+
+// NOTE: The key is this currently for backwards compatibility of storage.
+const LAYOUT_KEY = 'dxos.org/settings/layout';
+
+export default () => {
+  const layout = new LocalStorageStore<Layout>(LAYOUT_KEY, {
+    layoutMode: 'solo',
+    sidebarOpen: true,
+    complementarySidebarOpen: false,
+    dialogContent: null,
+    dialogOpen: false,
+    dialogBlockAlign: undefined,
+    dialogType: undefined,
+    popoverContent: null,
+    popoverAnchorId: undefined,
+    popoverOpen: false,
+    toasts: [],
+  });
+
+  layout
+    .prop({ key: 'layoutMode', type: LocalStorageStore.enum<LayoutMode>() })
+    .prop({ key: 'sidebarOpen', type: LocalStorageStore.bool() })
+    .prop({ key: 'complementarySidebarOpen', type: LocalStorageStore.bool() });
+
+  return contributes(Capabilities.Layout, layout.values, () => layout.close());
+};

package/src/capabilities/navigation/check-app-scheme.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, type PluginsContext } from '@dxos/app-framework';
+
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps } from '../../types';
+
+const isSocket = !!(globalThis as any).__args;
+
+// TODO(mjamesderocher): Can we get this directly from Socket?
+const appScheme = 'composer://';
+
+// TODO(mjamesderocher): Factor out as part of NavigationPlugin.
+const checkAppScheme = (url: string) => {
+  const iframe = document.createElement('iframe');
+  iframe.style.display = 'none';
+  document.body.appendChild(iframe);
+
+  iframe.src = url + window.location.pathname.replace(/^\/+/, '') + window.location.search;
+
+  const timer = setTimeout(() => {
+    document.body.removeChild(iframe);
+  }, 3000);
+
+  window.addEventListener('pagehide', (event) => {
+    clearTimeout(timer);
+    document.body.removeChild(iframe);
+  });
+};
+
+export default async (context: PluginsContext) => {
+  const settingsStore = context.requestCapability(Capabilities.SettingsStore);
+  const settings = settingsStore.getStore<DeckSettingsProps>(DECK_PLUGIN)?.value;
+  if (!isSocket && settings?.enableNativeRedirect) {
+    checkAppScheme(appScheme);
+  }
+
+  return contributes(Capabilities.Null, null);
+};

package/src/capabilities/navigation/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const CheckAppScheme = lazy(() => import('./check-app-scheme'));
+export const LocationState = lazy(() => import('./location'));
+export const NavigationIntentResolver = lazy(() => import('./intent-resolver'));
+export const UrlHandler = lazy(() => import('./url-handler'));