@dxos/plugin-deck 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

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/compute';
+
+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 { Operation } from '@dxos/compute';
+import { log } from '@dxos/log';
+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/compute';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+
+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/compute';
+
+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,66 @@
+//
+// 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 { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+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) {
+            // Use `invoke` (synchronous) rather than `schedule` (fire-and-forget) so
+            // that the implicit "open first child" finishes BEFORE this handler
+            // returns. Otherwise, a caller that follows `SwitchWorkspace` with its
+            // own `SetLayoutMode`/`Open` (e.g. WelcomePlugin DefaultContent) has
+            // its `solo`/`active` clobbered by this scheduled Open when it later
+            // races behind the caller's state writes.
+            yield* Operation.invoke(LayoutOperation.Open, { subject: [item.id] });
+          }
+        }
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-companion.ts

@@ -0,0 +1,35 @@
+//
+// 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/compute';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+
+import { DeckCapabilities } from '../types';
+import { updateActiveDeck } from './helpers';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdateCompanion> = LayoutOperation.UpdateCompanion.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      if (input.subject === null) {
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+          updateActiveDeck(state, { companionOpen: false }),
+        );
+      } else {
+        const variant = getLinkedVariant(input.subject);
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+          updateActiveDeck(state, {
+            companionOpen: true,
+            companionVariant: variant,
+          }),
+        );
+      }
+    }),
+  ),
+);
+
+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/compute';
+
+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/compute';
+
+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,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { DeckCapabilities, DeckOperation } from '../types';
+import { updateActiveDeck } from './helpers';
+
+const handler: Operation.WithHandler<typeof DeckOperation.UpdatePlankSize> = DeckOperation.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/compute';
+
+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/compute';
+
+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/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const DeckPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { DeckOperationHandlerSet } from './operations';

package/src/translations.ts

@@ -4,67 +4,54 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Deck',
-        'settings title': 'Deck settings',
-        'main header label': 'Main header',
-        'open navigation sidebar label': 'Open sidebar',
-        'collapse navigation sidebar label': 'Minimize sidebar',
-        'open complementary sidebar label': 'Open context sidebar',
-        'close complementary sidebar label': 'Minimize context sidebar',
-        'sidebar title': 'Navigation sidebar',
-        'complementary sidebar title': 'Context sidebar',
-        'plugin error message': 'Content failed to render.',
-        'content fallback message': 'Unsupported',
-        'content fallback description':
+        'plugin.name': 'Deck',
+        'settings.title': 'Deck settings',
+        'main-header.label': 'Main header',
+        'open-navigation-sidebar.label': 'Open sidebar',
+        'collapse-navigation-sidebar.label': 'Close sidebar',
+        'open-complementary-sidebar.label': 'Open context sidebar',
+        'close-complementary-sidebar.label': 'Close context sidebar',
+        'sidebar.title': 'Navigation sidebar',
+        'complementary-sidebar.title': 'Context sidebar',
+        'plugin-error.message': 'Content failed to render.',
+        'content-fallback.message': 'Unsupported',
+        'content-fallback.description':
           'No plugin had a response for the address you navigated to. Double-check the URL, and ensure you’ve enabled a plugin that supports the object.',
-        'toggle fullscreen label': 'Toggle fullscreen',
-        'settings show hints label': 'Show hints',
-        'settings native redirect label': 'Enable native url redirect (experimental)',
-        'settings new plank position start label': 'Start',
-        'settings new plank position end label': 'End',
-        'select new plank positioning placeholder': 'Select new plank positioning',
-        'select new plank positioning label': 'New plank positioning',
-        'undo available label': 'Click to undo previous action.',
-        'undo action label': 'Undo',
-        'undo action alt': 'Undo previous action',
-        'undo close label': 'Dismiss',
-        'error fallback message': 'Unable to open this object',
-        'plank heading fallback label': 'Untitled',
-        'actions menu label': 'Options',
-        'settings deck label': 'Disable deck',
-        'pending heading': 'Loading…',
-        'insert plank label': 'Open',
-        'resize label': 'Drag to resize',
-        'pin start label': 'Pin to the left sidebar',
-        'pin end label': 'Pin to the right sidebar',
-        'increment start label': 'Move to the left',
-        'increment end label': 'Move to the right',
-        'show deck plank label': 'Return to deck',
-        'show solo plank label': 'Maximize',
-        'exit fullscreen label': 'Exit fullscreen',
-        'show fullscreen plank label': 'Fullscreen',
-        'close label': 'Close',
-        'minify label': 'Minify',
-        'open companion label': 'Open companion',
-        'close companion label': 'Close companion',
-        'settings overscroll label': 'Plank scrolling',
-        'select overscroll placeholder': 'Select plank scrolling behavior',
-        'settings overscroll centering label': 'Centering',
-        'settings overscroll none label': 'None',
-        'settings enable statusbar label': 'Show status bar',
-        'settings enable deck label': 'Enable Deck',
-        'settings encapsulated planks label': 'Encapsulated planks',
-        'close current label': 'Close current plank',
-        'close others label': 'Close other planks',
-        'close all label': 'Close all planks',
-        'companion plank heading fallback label': 'Related',
-        'open item label': 'Open',
+        'toggle-fullscreen.label': 'Toggle fullscreen',
+        'undo-available.label': 'Click to undo previous action.',
+        'undo-action.label': 'Undo',
+        'undo-action.alt': 'Undo previous action',
+        'undo-close.label': 'Dismiss',
+        'error-fallback.message': 'Unable to open this object',
+        'plank-heading-fallback.label': 'Untitled',
+        'actions-menu.label': 'Options',
+        'settings.deck.label': 'Disable deck',
+        'pending.heading': 'Loading…',
+        'insert-plank.label': 'Open',
+        'resize.label': 'Drag to resize',
+        'pin-start.label': 'Pin to the left sidebar',
+        'pin-end.label': 'Pin to the right sidebar',
+        'increment-start.label': 'Move to the left',
+        'increment-end.label': 'Move to the right',
+        'show-deck-plank.label': 'Return to deck',
+        'show-solo-plank.label': 'Maximize',
+        'exit-fullscreen.label': 'Exit fullscreen',
+        'show-fullscreen-plank.label': 'Fullscreen',
+        'close.label': 'Close',
+        'minify.label': 'Minify',
+        'open-companion.label': 'Open companion',
+        'close-companion.label': 'Close companion',
+        'close-current.label': 'Close current plank',
+        'close-others.label': 'Close other planks',
+        'close-all.label': 'Close all planks',
+        'close-navigation-sidebar.button': 'Close',
+        'companion-plank-heading-fallback.label': 'Related',
       },
     },
   },

package/src/types/DeckCapabilities.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+
+import { meta } from '#meta';
+
+import { type EphemeralDeckState, type DeckState, type StoredDeckState } from './schema';
+
+export const Settings = Capability.make<Atom.Writable<import('./Settings').Settings>>(`${meta.id}.capability.settings`);
+
+/** Persisted state (stored in KVS/localStorage). */
+export const State = Capability.make<Atom.Writable<StoredDeckState>>(`${meta.id}.capability.state`);
+
+/** Transient/ephemeral state (not persisted). */
+export const EphemeralState = Capability.make<Atom.Writable<EphemeralDeckState>>(
+  `${meta.id}.capability.ephemeral-state`,
+);
+
+/** Get the current active deck from state. */
+export const getDeck = (): Effect.Effect<DeckState, Error, Capability.Service> =>
+  Effect.gen(function* () {
+    const state = yield* Capabilities.getAtomValue(State);
+    const deck = state.decks[state.activeDeck];
+    invariant(deck, `Deck not found: ${state.activeDeck}`);
+    return deck;
+  });

package/src/types/DeckEvents.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type ActivationEvent } from '@dxos/app-framework';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+
+import * as DeckCapabilities from './DeckCapabilities';
+
+export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(
+  `${meta.id}.state-ready`,
+);
+
+/** Fired when DeckSettings capability is ready. */
+export const SettingsReady: ActivationEvent.ActivationEvent = AppActivationEvents.createSettingsEvent(
+  DeckCapabilities.Settings.identifier,
+);