@dxos/plugin-deck 0.8.4-main.70d3990 → 0.8.4-main.74a063c4e0

package/src/operations/index.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * as DeckOperation from './definitions';
+
+export const DeckOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./add-toast'),
+  () => import('./adjust'),
+  () => import('./change-companion'),
+  () => import('./close'),
+  () => import('./open'),
+  () => import('./revert-workspace'),
+  () => import('./scroll-into-view'),
+  () => import('./set'),
+  () => import('./set-layout-mode'),
+  () => import('./show-undo'),
+  () => import('./switch-workspace'),
+  () => import('./update-complementary'),
+  () => import('./update-dialog'),
+  () => import('./update-plank-size'),
+  () => import('./update-popover'),
+  () => import('./update-sidebar'),
+);

package/src/operations/open.ts

@@ -0,0 +1,184 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import {
+  AppCapabilities,
+  LayoutOperation,
+  createEdgeExistenceChecker,
+  expandPath,
+  validateNavigationTarget,
+} from '@dxos/app-toolkit';
+import { Context } from '@dxos/context';
+import { Obj } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+import { AttentionCapabilities } from '@dxos/plugin-attention/types';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+import { Graph } from '@dxos/plugin-graph';
+import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+
+import { openSubjectsOnActiveDeck } from '../layout';
+import { DeckCapabilities } from '../types';
+import { computeActiveUpdates } from '../util';
+import { updateActiveDeck } from './helpers';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.Open> = LayoutOperation.Open.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const { graph } = yield* Capability.get(AppCapabilities.AppGraph);
+      const attention = yield* Capability.get(AttentionCapabilities.Attention);
+
+      // Validate navigation targets, redirecting to 404 if not found.
+      const capabilities = yield* Capability.Service;
+      const pathResolvers = capabilities.getAll(AppCapabilities.NavigationPathResolver);
+      const checkRemoteExistence = yield* Capability.get(ClientCapabilities.Client).pipe(
+        Effect.map((client) =>
+          createEdgeExistenceChecker((spaceId, body) => client.edge.http.execQuery(new Context(), spaceId, body)),
+        ),
+        Effect.catchAll(() => Effect.succeed(undefined)),
+      );
+
+      // Immediate: skip 404 / resolver checks but still expand the path (same as validate’s first step).
+      if (input.navigation === 'immediate') {
+        for (const subjectId of input.subject) {
+          expandPath(graph, subjectId);
+        }
+      }
+
+      const validatedSubjects = yield* Effect.all(
+        input.subject.map((subjectId) =>
+          input.navigation === 'immediate'
+            ? Effect.succeed(subjectId)
+            : validateNavigationTarget({ graph, subjectId, pathResolvers, checkRemoteExistence }),
+        ),
+      );
+      input = { ...input, subject: validatedSubjects };
+
+      {
+        const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+        if (input.workspace && state.activeDeck !== input.workspace) {
+          yield* Operation.invoke(LayoutOperation.SwitchWorkspace, { subject: input.workspace });
+        }
+      }
+
+      // Dedup subjects against the active deck using DXN identity.
+      // The same object can appear under different graph paths (e.g., via collections vs types).
+      // Resolve each subject's DXN and, if it matches an already-open deck item, remap the
+      // subject to the existing deck entry so that openEntry's exact-match check succeeds.
+      // Only needed in multi (deck) mode; solo mode replaces the single visible item anyway.
+      {
+        const deck = yield* DeckCapabilities.getDeck();
+        const active = !deck.solo && deck.initialized ? deck.active : [];
+        if (active.length > 0 && input.subject.length > 0) {
+          const resolveDxn = (qualifiedPath: string) =>
+            Effect.reduce(pathResolvers, Option.none<string>(), (acc, resolver) =>
+              Option.isSome(acc)
+                ? Effect.succeed(acc)
+                : resolver(qualifiedPath).pipe(
+                    Effect.map((opt) => Option.map(opt, (dxn) => dxn.toString())),
+                    Effect.catchAll(() => Effect.succeed(Option.none<string>())),
+                  ),
+            );
+
+          // Build DXN → deck item ID map for active items.
+          const deckDxnMap = new Map<string, string>();
+          yield* Effect.all(
+            active.map((deckId) =>
+              resolveDxn(deckId).pipe(
+                Effect.map((opt) => {
+                  if (Option.isSome(opt)) {
+                    deckDxnMap.set(opt.value, deckId);
+                  }
+                }),
+              ),
+            ),
+            { concurrency: 'unbounded' },
+          );
+
+          // Remap subjects whose DXN matches an existing deck item.
+          if (deckDxnMap.size > 0) {
+            const remapped = yield* Effect.all(
+              input.subject.map((subjectId) =>
+                resolveDxn(subjectId).pipe(
+                  Effect.map((opt) => {
+                    if (Option.isSome(opt)) {
+                      const existing = deckDxnMap.get(opt.value);
+                      if (existing && existing !== subjectId) {
+                        return existing;
+                      }
+                    }
+                    return subjectId;
+                  }),
+                ),
+              ),
+              { concurrency: 'unbounded' },
+            );
+            input = { ...input, subject: remapped };
+          }
+        }
+      }
+
+      // Compute the next active deck state and apply it.
+      // In solo or uninitialized mode the subject list replaces the deck entirely.
+      // In multi (deck) mode, subjects are merged via openSubjectsOnActiveDeck which
+      // uses stack semantics (truncate after pivot, then push new entries).
+      let previouslyOpenIds: Set<string>;
+      {
+        const deck = yield* DeckCapabilities.getDeck();
+        previouslyOpenIds = new Set<string>(deck.solo ? [deck.solo] : deck.active);
+        const next =
+          deck.solo || !deck.initialized
+            ? [...input.subject]
+            : openSubjectsOnActiveDeck(deck.active, input.subject, {
+                pivotId: input.pivotId,
+                key: input.key,
+              });
+
+        const { deckUpdates, toAttend: _toAttend } = computeActiveUpdates({ next, deck, attention });
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => updateActiveDeck(state, deckUpdates));
+      }
+
+      // Schedule side-effects for the newly opened items: scroll into view, expose in
+      // the navigation sidebar, and emit observability events.
+      // When nothing is newly opened (subject was already visible), the fallback
+      // `input.subject[0]` still triggers scroll and expose so the user is taken there.
+      {
+        const deck = yield* DeckCapabilities.getDeck();
+        const ids = deck.solo ? [deck.solo] : deck.active;
+        const newlyOpen = ids.filter((i: string) => !previouslyOpenIds.has(i));
+
+        if (input.scrollIntoView !== false && (newlyOpen[0] ?? input.subject[0])) {
+          yield* Operation.schedule(LayoutOperation.ScrollIntoView, {
+            subject: newlyOpen[0] ?? input.subject[0],
+          });
+        }
+
+        if (newlyOpen[0] ?? input.subject[0]) {
+          yield* Operation.schedule(LayoutOperation.Expose, { subject: newlyOpen[0] ?? input.subject[0] });
+        }
+
+        for (const subjectId of newlyOpen) {
+          const typename = Option.match(Graph.getNode(graph, subjectId), {
+            onNone: () => undefined,
+            onSome: (node) => {
+              const active = node.data;
+              return Obj.isObject(active) ? Obj.getTypename(active) : undefined;
+            },
+          });
+          yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+            name: 'navigation.activate',
+            properties: { subjectId, typename },
+          });
+        }
+      }
+
+      return validatedSubjects;
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/revert-workspace.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.RevertWorkspace> = LayoutOperation.RevertWorkspace.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+      yield* Operation.invoke(LayoutOperation.SwitchWorkspace, { subject: state.previousDeck });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/scroll-into-view.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.ScrollIntoView> = LayoutOperation.ScrollIntoView.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        scrollIntoView: input.subject,
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/set-layout-mode.ts

@@ -0,0 +1,84 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+import { isNonNullable } from '@dxos/util';
+
+import { DeckCapabilities, type DeckState, type LayoutMode, getMode, isLayoutMode } from '../types';
+import { updateActiveDeck } from './helpers';
+
+/**
+ * Transitions between layout modes (multi, solo, solo--fullscreen) or reverts to the previous mode.
+ * Computes which planks become active/inactive and persists the previous mode for revert support.
+ */
+const handler: Operation.WithHandler<typeof LayoutOperation.SetLayoutMode> = LayoutOperation.SetLayoutMode.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      if ('mode' in input && !isLayoutMode(input.mode)) {
+        return;
+      }
+
+      const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+      const deck = yield* DeckCapabilities.getDeck();
+
+      const computeModeUpdate = (mode: LayoutMode, subject?: string): Partial<DeckState> => {
+        const current = deck.solo ? [deck.solo] : deck.active;
+        const next = (mode !== 'multi' ? [subject ?? deck.solo ?? deck.active[0]] : [...deck.active, deck.solo]).filter(
+          isNonNullable,
+        );
+
+        const removed = current.filter((id: string) => !next.includes(id));
+        const closed = Array.from(new Set([...deck.inactive.filter((id: string) => !next.includes(id)), ...removed]));
+
+        const soloUpdate =
+          mode !== 'multi' && next[0]
+            ? { solo: next[0] }
+            : mode === 'multi' && deck.solo
+              ? { solo: undefined, initialized: true }
+              : {};
+
+        const fullscreenUpdate = mode === 'solo--fullscreen' ? { fullscreen: !deck.fullscreen } : {};
+
+        return {
+          inactive: closed,
+          ...soloUpdate,
+          ...fullscreenUpdate,
+        };
+      };
+
+      if ('mode' in input) {
+        const currentMode = getMode(deck);
+        const subject = 'subject' in input ? input.subject : undefined;
+        const deckUpdates = computeModeUpdate(input.mode as LayoutMode, subject);
+
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => {
+          const newPreviousMode =
+            currentMode !== input.mode
+              ? { ...state.previousMode, [state.activeDeck]: currentMode }
+              : state.previousMode;
+          return {
+            ...updateActiveDeck(state, deckUpdates),
+            previousMode: newPreviousMode,
+          };
+        });
+
+        if (subject) {
+          yield* Operation.schedule(LayoutOperation.Expose, { subject });
+        }
+      } else if ('revert' in input) {
+        const deckUpdates = computeModeUpdate(state.previousMode[state.activeDeck]);
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => updateActiveDeck(state, deckUpdates));
+      } else {
+        log.warn('Invalid layout mode', input);
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/set.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+import { AttentionCapabilities } from '@dxos/plugin-attention/types';
+
+import { DeckCapabilities } from '../types';
+import { computeActiveUpdates } from '../util';
+import { updateActiveDeck } from './helpers';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.Set> = LayoutOperation.Set.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const deck = yield* DeckCapabilities.getDeck();
+      const attention = yield* Capability.get(AttentionCapabilities.Attention);
+
+      const { deckUpdates, toAttend } = computeActiveUpdates({
+        next: input.subject as string[],
+        deck,
+        attention,
+      });
+      yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => updateActiveDeck(state, deckUpdates));
+
+      if (toAttend) {
+        yield* Operation.schedule(LayoutOperation.ScrollIntoView, { subject: toAttend });
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/show-undo.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability, UndoOperation } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { meta } from '#meta';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof UndoOperation.ShowUndo> = UndoOperation.ShowUndo.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const historyTracker = yield* Capability.get(Capabilities.HistoryTracker);
+
+      const newUndoId = `show-undo-${Date.now()}`;
+      // TODO(wittjosiah): Support undoing further back than the last action.
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => {
+        const filteredToasts = state.currentUndoId
+          ? state.toasts.filter((toast) => toast.id !== state.currentUndoId)
+          : state.toasts;
+
+        const toast: LayoutOperation.Toast = {
+          id: newUndoId,
+          title: input.message ?? ['undo-available.label', { ns: meta.id }],
+          duration: 10_000,
+          actionLabel: ['undo-action.label', { ns: meta.id }],
+          actionAlt: ['undo-action.alt', { ns: meta.id }],
+          closeLabel: ['undo-close.label', { ns: meta.id }],
+          onAction: () => historyTracker.undoPromise(),
+        };
+
+        return {
+          ...state,
+          currentUndoId: newUndoId,
+          toasts: [...filteredToasts, toast],
+        };
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/switch-workspace.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities, isPinnedWorkspace, LayoutOperation } from '@dxos/app-toolkit';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { Graph, Node } from '@dxos/plugin-graph';
+
+import { DeckCapabilities, defaultDeck } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.SwitchWorkspace> = LayoutOperation.SwitchWorkspace.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const { graph } = yield* Capability.get(AppCapabilities.AppGraph);
+
+      {
+        const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+        // TODO(wittjosiah): This is a hack to prevent the previous deck from being set for pinned items.
+        //   Ideally this should be worked into the data model in a generic way.
+        const shouldUpdatePrevious = !isPinnedWorkspace(state.activeDeck);
+
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => {
+          const newDecks = state.decks[input.subject]
+            ? state.decks
+            : { ...state.decks, [input.subject]: { ...defaultDeck } };
+          return {
+            ...state,
+            previousDeck: shouldUpdatePrevious ? state.activeDeck : state.previousDeck,
+            activeDeck: input.subject,
+            decks: newDecks,
+          };
+        });
+      }
+
+      {
+        const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+        const deck = state.decks[input.subject];
+        invariant(deck, `Deck not found: ${input.subject}`);
+
+        const first = deck.solo ? deck.solo : deck.active[0];
+        if (first) {
+          yield* Operation.schedule(LayoutOperation.ScrollIntoView, { subject: first });
+        } else {
+          const [item] = Graph.getConnections(graph, input.subject, 'child').filter(
+            (node) => !Node.isActionLike(node) && !node.properties.disposition,
+          );
+          if (item) {
+            yield* Operation.schedule(LayoutOperation.Open, { subject: [item.id] });
+          }
+        }
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-complementary.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdateComplementary> =
+  LayoutOperation.UpdateComplementary.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* (input) {
+        const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+        const panelChanged = state.complementarySidebarPanel !== input.subject;
+        const next = input.subject ? 'expanded' : (input.state ?? state.complementarySidebarState);
+        const stateChanged = next !== state.complementarySidebarState;
+
+        if (panelChanged || stateChanged) {
+          yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => ({
+            ...state,
+            complementarySidebarPanel: panelChanged ? input.subject : state.complementarySidebarPanel,
+            complementarySidebarState: stateChanged ? next : state.complementarySidebarState,
+          }));
+        }
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/update-dialog.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdateDialog> = LayoutOperation.UpdateDialog.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        dialogOpen: input.state ?? Boolean(input.subject),
+        dialogType: input.type ?? 'default',
+        dialogBlockAlign: input.blockAlign ?? 'center',
+        dialogOverlayClasses: input.overlayClasses,
+        dialogOverlayStyle: input.overlayStyle,
+        dialogContent: input.subject
+          ? {
+              component: input.subject,
+              props: input.props,
+            }
+          : null,
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-plank-size.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+import { UpdatePlankSize } from './definitions';
+import { updateActiveDeck } from './helpers';
+
+const handler: Operation.WithHandler<typeof UpdatePlankSize> = UpdatePlankSize.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+        updateActiveDeck(state, {
+          plankSizing: {
+            ...state.decks[state.activeDeck]?.plankSizing,
+            [input.id]: input.size,
+          },
+        }),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-popover.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdatePopover> = LayoutOperation.UpdatePopover.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        popoverOpen: input.state ?? Boolean(input.subject),
+        popoverKind: input.kind ?? 'base',
+        popoverTitle: input.kind === 'card' ? input.title : undefined,
+        popoverContentRef: input.subjectRef,
+        popoverContent:
+          typeof input.subject === 'string'
+            ? { component: input.subject, props: input.props }
+            : input.subject
+              ? { subject: input.subject }
+              : null,
+        popoverSide: input.side,
+        popoverAnchor: input.variant === 'virtual' ? input.anchor : state.popoverAnchor,
+        popoverAnchorId: input.variant !== 'virtual' ? input.anchorId : state.popoverAnchorId,
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-sidebar.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdateSidebar> = LayoutOperation.UpdateSidebar.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+      const next = input.state ?? state.sidebarState;
+      if (next !== state.sidebarState) {
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => ({
+          ...state,
+          sidebarState: next,
+        }));
+      }
+    }),
+  ),
+);
+
+export default handler;