@dxos/plugin-deck 0.8.4-main.b97322e → 0.8.4-main.bcb3aa67d6

package/src/operations/open.ts

@@ -0,0 +1,117 @@
+//
+// 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,
+  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 { updateActiveDeck } from './helpers';
+import { openEntry } from '../layout';
+import { DeckCapabilities } from '../types';
+import { computeActiveUpdates } from '../util';
+
+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);
+      const settings = yield* Capabilities.getAtomValue(DeckCapabilities.Settings);
+
+      // 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)),
+      );
+
+      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 });
+        }
+      }
+
+      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]
+            : input.subject.reduce(
+                (acc, entryId) =>
+                  openEntry(acc, entryId, {
+                    key: input.key,
+                    positioning: input.positioning ?? settings?.newPlankPositioning,
+                    pivotId: input.pivotId,
+                  }),
+                deck.active,
+              );
+
+        const { deckUpdates, toAttend: _toAttend } = computeActiveUpdates({ next, deck, attention });
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => updateActiveDeck(state, deckUpdates));
+      }
+
+      {
+        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 { updateActiveDeck } from './helpers';
+import { DeckCapabilities, type DeckState, type LayoutMode, getMode, isLayoutMode } from '../types';
+
+/**
+ * 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 { updateActiveDeck } from './helpers';
+import { DeckCapabilities } from '../types';
+import { computeActiveUpdates } from '../util';
+
+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,46 @@
+//
+// 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 { UpdatePlankSize } from './definitions';
+import { updateActiveDeck } from './helpers';
+import { DeckCapabilities } from '../types';
+
+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;

package/src/testing/DeckLayoutStoryNavigation.tsx

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { forwardRef, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph, useLayout } from '@dxos/app-toolkit/ui';
+import { Graph, Node } from '@dxos/plugin-graph';
+import { Icon, List, ListItem } from '@dxos/react-ui';
+
+export type DeckLayoutStoryNavigationProps = {
+  current?: string;
+};
+
+/**
+ * Minimal test-only navigation list for DeckLayout stories.
+ * Renders root graph children and opens them via LayoutOperation.Open on click.
+ */
+export const DeckLayoutStoryNavigation = forwardRef<HTMLDivElement, DeckLayoutStoryNavigationProps>(
+  (_props, forwardedRef) => {
+    const { graph } = useAppGraph();
+    const layout = useLayout();
+    const { invokePromise } = useOperationInvoker();
+
+    const items = useMemo(
+      () => Graph.getConnections(graph, Node.RootId, 'child').filter((node) => !Node.isActionLike(node)),
+      [graph],
+    );
+
+    const activeSet = useMemo(() => new Set(layout.active), [layout.active]);
+
+    return (
+      <div ref={forwardedRef} className='overflow-y-auto p-2'>
+        <List>
+          {items.map((node) => (
+            <ListItem.Root
+              key={node.id}
+              classNames={activeSet.has(node.id) ? 'bg-active-surface' : undefined}
+              onClick={() => void invokePromise(LayoutOperation.Open, { subject: [node.id] })}
+            >
+              {node.properties.icon && (
+                <ListItem.Endcap>
+                  <Icon icon={node.properties.icon} size={4} />
+                </ListItem.Endcap>
+              )}
+              <ListItem.Heading>
+                {typeof node.properties.label === 'string' ? node.properties.label : node.id}
+              </ListItem.Heading>
+            </ListItem.Root>
+          ))}
+        </List>
+      </div>
+    );
+  },
+);

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { DeckLayoutStoryNavigation } from './DeckLayoutStoryNavigation';