@dxos/plugin-deck 0.7.5-labs.e27f9b9 → 0.7.5-main.2567c87

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

@@ -0,0 +1,216 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { batch } from '@preact/signals-core';
+import { pipe } from 'effect';
+
+import {
+  Capabilities,
+  chain,
+  contributes,
+  createIntent,
+  createResolver,
+  LayoutAction,
+  NavigationAction,
+  openIds,
+  SLUG_PATH_SEPARATOR,
+  type LayoutEntry,
+  type LayoutPart,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { isReactiveObject, getTypename } from '@dxos/live-object';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+import { ObservabilityAction } from '@dxos/plugin-observability/types';
+
+import { setLocation } from './set-location';
+import { closeEntry, incrementPlank, openEntry } from '../../layout';
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps } from '../../types';
+import { getEffectivePart } from '../../util';
+
+// TODO(wittjosiah): Factor out navgiation from deck plugin.
+export default (context: PluginsContext) =>
+  contributes(Capabilities.IntentResolver, [
+    createResolver(NavigationAction.Open, (data) => {
+      const { graph } = context.requestCapability(Capabilities.AppGraph);
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+      const settings = context
+        .requestCapabilities(Capabilities.SettingsStore)[0]
+        ?.getStore<DeckSettingsProps>(DECK_PLUGIN)?.value;
+
+      const previouslyOpenIds = new Set<string>(openIds(location.active));
+      const layoutMode = layout.layoutMode;
+      const toAttend = batch(() => {
+        const processLayoutEntry = (partName: string, entryString: string, currentLayout: any) => {
+          // TODO(burdon): Option to toggle?
+          const toggle = false;
+          const [id, path] = entryString.split(SLUG_PATH_SEPARATOR);
+          const layoutEntry: LayoutEntry = { id, ...(path ? { path } : {}) };
+          const effectivePart = getEffectivePart(partName as LayoutPart, layoutMode);
+          if (
+            toggle &&
+            layoutMode === 'deck' &&
+            effectivePart === 'main' &&
+            currentLayout[effectivePart]?.some((entry: LayoutEntry) => entry.id === id) &&
+            !data?.noToggle
+          ) {
+            // If we're in deck mode and the main part is already open, toggle it closed.
+            return closeEntry(currentLayout, { part: effectivePart as LayoutPart, entryId: id });
+          } else {
+            return openEntry(currentLayout, effectivePart, layoutEntry, {
+              positioning: settings?.newPlankPositioning,
+            });
+          }
+        };
+
+        let newLayout = location.active;
+        Object.entries(data.activeParts).forEach(([partName, layoutEntries]) => {
+          if (Array.isArray(layoutEntries)) {
+            layoutEntries.forEach((activePartEntry: string) => {
+              newLayout = processLayoutEntry(partName, activePartEntry, newLayout);
+            });
+          } else if (typeof layoutEntries === 'string') {
+            // Legacy single string entry.
+            newLayout = processLayoutEntry(partName, layoutEntries, newLayout);
+          }
+        });
+
+        return setLocation({ next: newLayout, layout, location, attention });
+      });
+
+      const ids = openIds(location.active);
+      const newlyOpen = ids.filter((i) => !previouslyOpenIds.has(i));
+
+      return {
+        data: { open: ids },
+        intents: [
+          createIntent(LayoutAction.ScrollIntoView, { id: newlyOpen[0] ?? toAttend }),
+          ...(toAttend ? [createIntent(NavigationAction.Expose, { id: toAttend })] : []),
+          ...newlyOpen.map((id) => {
+            const active = graph?.findNode(id)?.data;
+            const typename = isReactiveObject(active) ? getTypename(active) : undefined;
+            return createIntent(ObservabilityAction.SendEvent, {
+              name: 'navigation.activate',
+              properties: {
+                id,
+                typename,
+              },
+            });
+          }),
+        ],
+      };
+    }),
+    createResolver(NavigationAction.AddToActive, (data) => {
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+      const settings = context
+        .requestCapabilities(Capabilities.SettingsStore)[0]
+        ?.getStore<DeckSettingsProps>(DECK_PLUGIN)?.value;
+
+      const layoutEntry = { id: data.id };
+      const effectivePart = getEffectivePart(data.part, layout.layoutMode);
+
+      setLocation({
+        next: openEntry(location.active, effectivePart, layoutEntry, {
+          positioning: data.positioning ?? settings?.newPlankPositioning,
+          pivotId: data.pivotId,
+        }),
+        layout,
+        location,
+        attention,
+      });
+
+      const intents = [];
+      if (data.scrollIntoView && layout.layoutMode === 'deck') {
+        intents.push(createIntent(LayoutAction.ScrollIntoView, { id: data.id }));
+      }
+
+      return { intents };
+    }),
+    createResolver(NavigationAction.Close, (data) => {
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+      let newLayout = location.active;
+      const layoutMode = layout.layoutMode;
+      const intentParts = data.activeParts;
+      Object.keys(intentParts).forEach((partName: string) => {
+        const effectivePart = getEffectivePart(partName as LayoutPart, layoutMode);
+        const ids = intentParts[partName];
+        if (Array.isArray(ids)) {
+          ids.forEach((id: string) => {
+            newLayout = closeEntry(newLayout, { part: effectivePart, entryId: id });
+          });
+        } else {
+          // Legacy single string entry
+          newLayout = closeEntry(newLayout, { part: effectivePart, entryId: ids });
+        }
+      });
+
+      const toAttend = setLocation({ next: newLayout, layout, location, attention });
+      return { intents: [createIntent(LayoutAction.ScrollIntoView, { id: toAttend })] };
+    }),
+    createResolver(NavigationAction.Set, (data) => {
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+      return batch(() => {
+        const toAttend = setLocation({ next: data.activeParts, layout, location, attention });
+        return { intents: [createIntent(LayoutAction.ScrollIntoView, { id: toAttend })] };
+      });
+    }),
+    createResolver(NavigationAction.Adjust, (adjustment) => {
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+      return batch(() => {
+        if (adjustment.type === 'increment-end' || adjustment.type === 'increment-start') {
+          setLocation({
+            next: incrementPlank(location.active, {
+              type: adjustment.type,
+              layoutCoordinate: adjustment.layoutCoordinate,
+            }),
+            layout,
+            location,
+            attention,
+          });
+        }
+
+        if (adjustment.type === 'solo') {
+          const entryId = adjustment.layoutCoordinate.entryId;
+          if (layout.layoutMode !== 'solo') {
+            // Solo the entry.
+            return {
+              intents: [
+                // NOTE: The order of these is important.
+                pipe(
+                  createIntent(NavigationAction.Open, { activeParts: { solo: [entryId] } }),
+                  chain(LayoutAction.SetLayoutMode, { layoutMode: 'solo' }),
+                ),
+              ],
+            };
+          } else {
+            // Un-solo the current entry.
+            return {
+              intents: [
+                // NOTE: The order of these is important.
+                pipe(
+                  createIntent(LayoutAction.SetLayoutMode, { layoutMode: 'deck' }),
+                  chain(NavigationAction.Close, { activeParts: { solo: [entryId] } }),
+                  chain(NavigationAction.Open, { activeParts: { main: [entryId] }, noToggle: true }),
+                  chain(LayoutAction.ScrollIntoView, { id: entryId }),
+                ),
+              ],
+            };
+          }
+        }
+      });
+    }),
+  ]);

package/src/capabilities/navigation/location.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, type LayoutParts } from '@dxos/app-framework';
+import { LocalStorageStore } from '@dxos/local-storage';
+
+import { NAV_ID } from '../../components';
+
+// NOTE: The key is this currently for backwards compatibility of storage.
+const LOCATION_KEY = 'dxos.org/settings/layout';
+
+export default () => {
+  // TODO(wittjosiah): This active state is not a generic navigation state but quite deck specific.
+  //   It is also closely tied to the layout mode state (which also seems quite deck specific).
+  //   The layout and navigation interfaces need to be revisited and cleaned up.
+  //   Doing this cleanup should also help simplify some of the convoluted logic for managing it.
+  const location = new LocalStorageStore<Capabilities.MutableLocation>(LOCATION_KEY, {
+    active: { sidebar: [{ id: NAV_ID }] },
+    closed: [],
+  });
+
+  location
+    .prop({ key: 'active', type: LocalStorageStore.json<LayoutParts>() })
+    .prop({ key: 'closed', type: LocalStorageStore.json<string[]>() });
+
+  return contributes(Capabilities.Location, location.values, () => location.close());
+};

package/src/capabilities/navigation/set-location.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { openIds, type Layout, type LayoutParts, type Capabilities } from '@dxos/app-framework';
+import { type AttentionManager } from '@dxos/plugin-attention';
+
+export type SetLocationOptions = {
+  next: LayoutParts;
+  location: Capabilities.MutableLocation;
+  layout: Layout;
+  attention?: AttentionManager;
+};
+
+export const setLocation = ({ next, location, layout, attention }: SetLocationOptions) => {
+  const part = layout.layoutMode === 'solo' ? 'solo' : 'main';
+  const ids = openIds(next, [part]);
+
+  const current = openIds(location.active, [part]);
+  const removed = current.filter((id) => !ids.includes(id));
+  const closed = Array.from(new Set([...location.closed.filter((id) => !ids.includes(id)), ...removed]));
+
+  location.closed = closed;
+  location.active = next;
+
+  if (attention) {
+    const attended = attention.current;
+    const [attendedId] = Array.from(attended);
+    const isAttendedAvailable = !!attendedId && ids.includes(attendedId);
+    if (!isAttendedAvailable) {
+      const currentIds = location.active[part]?.map(({ id }) => id) ?? [];
+      const attendedIndex = currentIds.indexOf(attendedId);
+      // If outside of bounds, focus on the first/last plank, otherwise focus on the new plank in the same position.
+      const index = attendedIndex === -1 ? 0 : attendedIndex >= ids.length ? ids.length - 1 : attendedIndex;
+      return next[part]?.[index].id;
+    }
+  }
+};

package/src/capabilities/navigation/url-handler.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  Capabilities,
+  contributes,
+  createIntent,
+  LayoutAction,
+  type LayoutParts,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { scheduledEffect } from '@dxos/echo-signals/core';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+
+import { setLocation as naturalSetLocation } from './set-location';
+import { NAV_ID } from '../../components';
+import { mergeLayoutParts, removePart, soloPartToUri, uriToSoloPart } from '../../layout';
+
+export default async (context: PluginsContext) => {
+  const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher) ?? {};
+  const location = context.requestCapability(Capabilities.MutableLocation);
+  const layout = context.requestCapability(Capabilities.MutableLayout);
+  const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+  const handleNavigation = async () => {
+    const setLocation = (next: LayoutParts) => naturalSetLocation({ next, layout, location, attention });
+
+    const pathname = window.location.pathname;
+    if (pathname === '/reset') {
+      setLocation({ sidebar: [{ id: NAV_ID }] });
+      location.closed = [];
+      layout.layoutMode = 'solo';
+      window.location.pathname = '/';
+      return;
+    }
+
+    const startingLayout = removePart(location.active, 'solo');
+    const layoutFromUri = uriToSoloPart(pathname);
+    if (!layoutFromUri) {
+      const toAttend = setLocation(startingLayout);
+      layout.layoutMode = 'deck';
+      await dispatch?.(createIntent(LayoutAction.ScrollIntoView, { id: toAttend }));
+      return;
+    }
+
+    const toAttend = setLocation(mergeLayoutParts(layoutFromUri, startingLayout));
+    layout.layoutMode = 'solo';
+    await dispatch?.(createIntent(LayoutAction.ScrollIntoView, { id: toAttend }));
+  };
+
+  await handleNavigation();
+  window.addEventListener('popstate', handleNavigation);
+
+  const unsubscribe = scheduledEffect(
+    () => ({ selectedPath: soloPartToUri(location.active) }),
+    ({ selectedPath }) => {
+      // TODO(thure): In some browsers, this only preserves the most recent state change, even though this is not `history.replace`…
+      history.pushState(null, '', `/${selectedPath}${window.location.search}`);
+    },
+  );
+
+  return contributes(Capabilities.Null, null, () => {
+    window.removeEventListener('popstate', handleNavigation);
+    unsubscribe();
+  });
+};

package/src/capabilities/settings/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const DeckSettings = lazy(() => import('./settings'));

package/src/capabilities/settings/react-surface.tsx

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+
+import { LayoutSettings } from '../../components';
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps } from '../../types';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, {
+    id: DECK_PLUGIN,
+    role: 'settings',
+    filter: (data): data is any => data.subject === DECK_PLUGIN,
+    component: () => {
+      const store = useCapability(Capabilities.SettingsStore);
+      const settings = store.getStore<DeckSettingsProps>(DECK_PLUGIN)!.value;
+      return <LayoutSettings settings={settings} />;
+    },
+  });

package/src/capabilities/{settings.ts → settings/settings.ts}

@@ -5,16 +5,17 @@
 import { Capabilities, contributes } from '@dxos/app-framework';
 import { create } from '@dxos/live-object';
 
-import { DECK_PLUGIN } from '../meta';
-import { DeckSettingsSchema, type DeckSettingsProps } from '../types';
+import { DECK_PLUGIN } from '../../meta';
+import { DeckSettingsSchema, type DeckSettingsProps } from '../../types';
 
 export default () => {
   const settings = create<DeckSettingsProps>({
     showHints: false,
+    customSlots: false,
+    flatDeck: false,
     enableNativeRedirect: false,
-    enableIdeStyleStatusbar: true,
     newPlankPositioning: 'start',
-    overscroll: 'none',
+    overscroll: 'centering',
   });
 
   return contributes(Capabilities.Settings, { schema: DeckSettingsSchema, prefix: DECK_PLUGIN, value: settings });

package/src/components/DeckContext.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, createContext, useContext } from 'react';
+
+import { type LayoutMode } from '@dxos/app-framework';
+import { raise } from '@dxos/debug';
+
+export type PlankSizing = Record<string, number>;
+export type DeckContextType = {
+  plankSizing: PlankSizing;
+  currentUndoId: string | undefined;
+  layoutModeHistory: LayoutMode[];
+};
+
+export const DeckContext: Context<DeckContextType | null> = createContext<DeckContextType | null>(null);
+
+export const useDeckContext = (): DeckContextType => useContext(DeckContext) ?? raise(new Error('Missing DeckContext'));

package/src/components/DeckLayout/ActiveNode.tsx

@@ -4,7 +4,8 @@
 
 import React from 'react';
 
-import { Surface, useAppGraph } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework';
+import { useGraph } from '@dxos/plugin-graph';
 import { useAttended } from '@dxos/react-ui-attention';
 
 import { useNode, useNodeActionExpander } from '../../hooks';
@@ -12,7 +13,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 } = useAppGraph();
+  const { graph } = useGraph();
   const activeNode = useNode(graph, id);
   useNodeActionExpander(activeNode);