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

package/src/hooks/useCompanions.ts

@@ -4,15 +4,15 @@
 
 import { useMemo } from 'react';
 
-import { useAppGraph } from '@dxos/app-framework';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { useConnections } from '@dxos/plugin-graph';
 import { byPosition } from '@dxos/util';
 
-import { PLANK_COMPANION_TYPE } from '../types';
+import { PLANK_COMPANION_TYPE } from '#types';
 
 export const useCompanions = (id?: string) => {
   const { graph } = useAppGraph();
-  const nodes = useConnections(graph, id);
+  const nodes = useConnections(graph, id, 'child');
   const companions = nodes.filter((node) => node.type === PLANK_COMPANION_TYPE);
   return useMemo(() => companions.toSorted((a, b) => byPosition(a.properties, b.properties)), [companions]);
 };

package/src/hooks/useDeckCompanions.ts

@@ -2,18 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Label, useAppGraph } from '@dxos/app-framework';
-import { ROOT_ID, useConnections, type Node } from '@dxos/plugin-graph';
-import { byPosition, type Position } from '@dxos/util';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Node, type Node as NodeType } from '@dxos/plugin-graph';
+import { useConnections } from '@dxos/plugin-graph';
+import { type Label } from '@dxos/ui-types';
+import { type Position, byPosition } from '@dxos/util';
 
-import { ATTENDABLE_PATH_SEPARATOR, DECK_COMPANION_TYPE } from '../types';
+import { DECK_COMPANION_TYPE } from '#types';
 
-export const getCompanionId = (id: string) => {
-  const [_, companionId] = id.split(ATTENDABLE_PATH_SEPARATOR);
-  return companionId ?? 'never';
-};
-
-export type DeckCompanion = Node<
+export type DeckCompanion = NodeType.Node<
   any,
   {
     label: Label;
@@ -27,7 +24,7 @@ export type DeckCompanion = Node<
 
 export const useDeckCompanions = (): DeckCompanion[] => {
   const { graph } = useAppGraph();
-  const connections = useConnections(graph, ROOT_ID);
+  const connections = useConnections(graph, Node.RootId, 'child');
   const companions = connections.filter((node) => node.type === DECK_COMPANION_TYPE) as DeckCompanion[];
   return companions.toSorted((a, b) => byPosition(a.properties, b.properties));
 };

package/src/hooks/useDeckState.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import { useCallback, useMemo } from 'react';
+
+import { Capabilities } from '@dxos/app-framework';
+import { useCapability } from '@dxos/app-framework/ui';
+import { invariant } from '@dxos/invariant';
+
+import {
+  DeckCapabilities,
+  type EphemeralDeckState,
+  type DeckPluginState,
+  type DeckState,
+  type StoredDeckState,
+} from '#types';
+
+export type DeckStateHook = {
+  /** Combined state value (reactive). Includes both persisted and ephemeral state. */
+  state: DeckPluginState;
+  /** The active deck, computed from decks[activeDeck]. */
+  deck: DeckState;
+  /** Update persisted state. */
+  updateState: (fn: (current: StoredDeckState) => StoredDeckState) => void;
+  /** Update ephemeral state. */
+  updateEphemeral: (fn: (current: EphemeralDeckState) => EphemeralDeckState) => void;
+};
+
+/**
+ * Hook to access the deck plugin state reactively.
+ * Returns the combined state, the active deck, and update functions for each atom.
+ */
+export const useDeckState = (): DeckStateHook => {
+  const registry = useCapability(Capabilities.AtomRegistry);
+  const stateAtom = useCapability(DeckCapabilities.State);
+  const ephemeralAtom = useCapability(DeckCapabilities.EphemeralState);
+  const persistedState = useAtomValue(stateAtom);
+  const ephemeralState = useAtomValue(ephemeralAtom);
+
+  // Compute deck from decks[activeDeck] to ensure it's always current.
+  const deck = useMemo(() => {
+    const deck = persistedState.decks[persistedState.activeDeck];
+    invariant(deck, `Deck not found: ${persistedState.activeDeck}`);
+    return deck;
+  }, [persistedState.decks, persistedState.activeDeck]);
+
+  // Combine persisted and ephemeral state into a unified view.
+  const state = useMemo(
+    (): DeckPluginState => ({
+      ...persistedState,
+      ...ephemeralState,
+    }),
+    [persistedState, ephemeralState],
+  );
+
+  const updateState = useCallback(
+    (fn: (current: StoredDeckState) => StoredDeckState) => {
+      registry.set(stateAtom, fn(registry.get(stateAtom)));
+    },
+    [registry, stateAtom],
+  );
+
+  const updateEphemeral = useCallback(
+    (fn: (current: EphemeralDeckState) => EphemeralDeckState) => {
+      registry.set(ephemeralAtom, fn(registry.get(ephemeralAtom)));
+    },
+    [registry, ephemeralAtom],
+  );
+
+  return useMemo(() => ({ state, deck, updateState, updateEphemeral }), [state, deck, updateState, updateEphemeral]);
+};

package/src/hooks/useHoistStatusbar.ts

@@ -4,16 +4,15 @@
 
 import { useMemo } from 'react';
 
-import { Capabilities, useCapability } from '@dxos/app-framework';
+import { useAtomCapability } from '@dxos/app-framework/ui';
 import { useThemeContext } from '@dxos/react-ui';
 
-import { DECK_PLUGIN } from '../meta';
-import type { DeckSettingsProps, LayoutMode } from '../types';
+import { DeckCapabilities, type LayoutMode } from '#types';
 
 export const useHoistStatusbar = (breakpoint: string, layoutMode?: LayoutMode): boolean => {
-  const enableStatusbar = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)!.value
-    .enableStatusbar;
   const { safeAreaPadding } = useThemeContext();
+  const enableStatusbar = useAtomCapability(DeckCapabilities.Settings).enableStatusbar;
+
   return useMemo(() => {
     return (
       breakpoint === 'desktop' &&

package/src/hooks/useMainSize.ts

@@ -7,7 +7,7 @@ import { useMainContext } from '@dxos/react-ui';
 export const useMainSize = () => {
   const { navigationSidebarState, complementarySidebarState } = useMainContext('DeckPluginPlank');
   return {
-    'data-sidebar-inline-start-state': navigationSidebarState,
-    'data-sidebar-inline-end-state': complementarySidebarState,
+    'data-sidebar-left-state': navigationSidebarState,
+    'data-sidebar-right-state': complementarySidebarState,
   };
 };

package/src/hooks/useNodeActionExpander.ts

@@ -4,14 +4,14 @@
 
 import { useEffect } from 'react';
 
-import { getGraph, type Node } from '@dxos/plugin-graph';
+import { Graph, type Node } from '@dxos/plugin-graph';
 
-export const useNodeActionExpander = (node?: Node) => {
+export const useNodeActionExpander = (node?: Node.Node) => {
   useEffect(() => {
     if (node) {
       const frame = requestAnimationFrame(() => {
-        const graph = getGraph(node);
-        void graph.expand(node.id);
+        const graph = Graph.getGraph(node);
+        void Graph.expand(graph, node.id, 'action');
       });
       return () => cancelAnimationFrame(frame);
     }

package/src/hooks/useSelectedCompanion.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { type Node } from '@dxos/plugin-graph';
+
+/**
+ * Resolves which companion to show based on variant preference.
+ * Falls back to first available if preferred variant not found.
+ */
+export const useSelectedCompanion = (companions: Node.Node[], preferredVariant?: string) => {
+  return useMemo(() => {
+    if (companions.length === 0) {
+      return { companionId: undefined, variant: undefined };
+    }
+
+    // Try to find companion matching the preferred variant.
+    if (preferredVariant) {
+      const preferred = companions.find((companion) => getLinkedVariant(companion.id) === preferredVariant);
+      if (preferred) {
+        return { companionId: preferred.id, variant: getLinkedVariant(preferred.id) };
+      }
+    }
+
+    // Fallback to first companion.
+    const first = companions[0];
+    return { companionId: first.id, variant: getLinkedVariant(first.id) };
+  }, [companions, preferredVariant]);
+};

package/src/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { DeckCapabilities } from './capabilities';
-export { DeckEvents } from './events';
+export { DeckCapabilities, DeckEvents } from './types';
 export * from './DeckPlugin';
 export * from './meta';
 export { useCompanions } from './hooks';

package/src/layout.ts

@@ -4,29 +4,16 @@
 
 import { produce } from 'immer';
 
-import { ATTENDABLE_PATH_SEPARATOR } from '@dxos/react-ui-attention';
-
-import { type DeckAction, type NewPlankPositioning } from './types';
-
-export const createEntryId = (entryId: string, variant?: string) =>
-  variant ? `${entryId}${ATTENDABLE_PATH_SEPARATOR}${variant}` : entryId;
-
-export const parseEntryId = (entryId: string) => {
-  const [id, variant] = entryId.split(ATTENDABLE_PATH_SEPARATOR);
-  return { id, variant };
-};
+import { type DeckAction, type Settings } from '#types';
 
 type OpenLayoutEntryOptions = {
   key?: string;
-  positioning?: NewPlankPositioning;
+  positioning?: Settings.NewPlankPositioning;
   pivotId?: string;
-  variant?: string;
 };
 
-export const openEntry = (deck: string[], _entryId: string, options?: OpenLayoutEntryOptions): string[] => {
+export const openEntry = (deck: string[], entryId: string, options?: OpenLayoutEntryOptions): string[] => {
   return produce(deck, (draft) => {
-    const entryId = createEntryId(_entryId, options?.variant);
-
     // Check that the entry is not already in the part
     if (draft.find((id) => id === entryId)) {
       return;

package/src/meta.ts

@@ -2,12 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const DECK_PLUGIN = 'dxos.org/plugin/deck' as const;
-
-export const meta: PluginMeta = {
-  id: DECK_PLUGIN,
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.deck',
   name: 'Layout',
+  description: trim`
+    Flexible layout system for arranging workspace views in tabs, splits, and panels.
+    Customize your workspace organization with drag-and-drop layout management.
+  `,
   icon: 'ph--layout--regular',
 };

package/src/operations/add-toast.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.AddToast> = LayoutOperation.AddToast.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        toasts: [...state.toasts, input as LayoutOperation.Toast],
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/adjust.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+import { AttentionCapabilities } from '@dxos/plugin-attention/types';
+import { Graph } from '@dxos/plugin-graph';
+import { byPosition } from '@dxos/util';
+
+import { Adjust, ChangeCompanion } from './definitions';
+import { updateActiveDeck } from './helpers';
+import { incrementPlank } from '../layout';
+import { DeckCapabilities, PLANK_COMPANION_TYPE } from '../types';
+import { computeActiveUpdates } from '../util';
+
+const handler: Operation.WithHandler<typeof Adjust> = Adjust.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const _state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+      const deck = yield* DeckCapabilities.getDeck();
+      const attention = yield* Capability.get(AttentionCapabilities.Attention);
+      const { graph } = yield* Capability.get(AppCapabilities.AppGraph);
+
+      let soloOperation:
+        | { type: 'solo'; entryId: string; mode: string }
+        | { type: 'unsolo'; entryId: string }
+        | undefined;
+
+      if (input.type === 'increment-end' || input.type === 'increment-start') {
+        const next = incrementPlank(deck.active, input);
+        const { deckUpdates } = computeActiveUpdates({ next, deck, attention });
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => updateActiveDeck(state, deckUpdates));
+      }
+
+      if (input.type.startsWith('solo')) {
+        const entryId = input.id;
+        if (!deck.solo) {
+          soloOperation = { type: 'solo', entryId, mode: input.type };
+        } else {
+          if (input.type === 'solo--fullscreen') {
+            soloOperation = { type: 'solo', entryId, mode: 'solo--fullscreen' };
+          } else if (input.type === 'solo') {
+            soloOperation = { type: 'unsolo', entryId };
+          }
+        }
+      }
+
+      if (soloOperation?.type === 'solo') {
+        yield* Operation.invoke(LayoutOperation.SetLayoutMode, {
+          subject: soloOperation.entryId,
+          mode: soloOperation.mode,
+        });
+      } else if (soloOperation?.type === 'unsolo') {
+        yield* Operation.invoke(LayoutOperation.SetLayoutMode, { mode: 'multi' });
+        yield* Operation.invoke(LayoutOperation.Open, { subject: [soloOperation.entryId] });
+      }
+
+      if (input.type === 'companion') {
+        const companion = Function.pipe(
+          Graph.getNode(graph, input.id),
+          Option.map((node) =>
+            Graph.getConnections(graph, node.id, 'child')
+              .filter((n) => n.type === PLANK_COMPANION_TYPE)
+              .toSorted((a, b) => byPosition(a.properties, b.properties)),
+          ),
+          Option.flatMap((companions) => (companions.length > 0 ? Option.some(companions[0]) : Option.none())),
+        );
+
+        if (Option.isSome(companion)) {
+          yield* Operation.invoke(ChangeCompanion, { companion: companion.value.id });
+        }
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/change-companion.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { Operation } from '@dxos/operation';
+
+import { ChangeCompanion } from './definitions';
+import { updateActiveDeck } from './helpers';
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof ChangeCompanion> = ChangeCompanion.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      if (input.companion === null) {
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+          updateActiveDeck(state, { companionOpen: false }),
+        );
+      } else {
+        const variant = getLinkedVariant(input.companion);
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+          updateActiveDeck(state, {
+            companionOpen: true,
+            companionVariant: variant,
+          }),
+        );
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/close.ts

@@ -0,0 +1,35 @@
+//
+// 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 { closeEntry } from '../layout';
+import { DeckCapabilities } from '../types';
+import { computeActiveUpdates } from '../util';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.Close> = LayoutOperation.Close.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const deck = yield* DeckCapabilities.getDeck();
+      const attention = yield* Capability.get(AttentionCapabilities.Attention);
+
+      const active = deck.solo ? [deck.solo] : deck.active;
+      const next = input.subject.reduce((acc, id) => closeEntry(acc, id), active);
+      const { deckUpdates, toAttend } = computeActiveUpdates({ next, 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/definitions.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
+
+import { meta } from '#meta';
+
+const PartAdjustmentSchema = Schema.Union(
+  Schema.Literal('close').annotations({ description: 'Close the plank.' }),
+  Schema.Literal('companion').annotations({ description: 'Open the companion plank.' }),
+  Schema.Literal('solo').annotations({ description: 'Solo the plank.' }),
+  Schema.Literal('solo--fullscreen').annotations({ description: 'Fullscreen the plank.' }),
+  Schema.Literal('increment-start').annotations({ description: 'Move the plank towards the start of the deck.' }),
+  Schema.Literal('increment-end').annotations({ description: 'Move the plank towards the end of the deck.' }),
+);
+export type PartAdjustment = Schema.Schema.Type<typeof PartAdjustmentSchema>;
+
+export const Adjust = Operation.make({
+  meta: {
+    key: `${meta.id}.operation.adjust`,
+    name: 'Adjust',
+    description: 'Adjust the layout of a plank.',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    id: Schema.String.annotations({ description: 'The id of the plank to adjust.' }),
+    type: PartAdjustmentSchema.annotations({ description: 'The type of adjustment to make.' }),
+  }),
+  output: Schema.Void,
+});
+
+export const UpdatePlankSize = Operation.make({
+  meta: {
+    key: `${meta.id}.operation.update-plank-size`,
+    name: 'Update Plank Size',
+    description: 'Update the size of a plank.',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    id: Schema.String.annotations({ description: 'The id of the plank to resize.' }),
+    size: Schema.Number.annotations({ description: 'The new size of the plank.' }),
+  }),
+  output: Schema.Void,
+});
+
+export const ChangeCompanion = Operation.make({
+  meta: {
+    key: `${meta.id}.operation.change-companion`,
+    name: 'Change Companion',
+    description: 'Change the companion plank for a primary plank.',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    companion: Schema.Union(Schema.String, Schema.Null),
+  }),
+  output: Schema.Void,
+});

package/src/operations/helpers.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+import { type DeckState, type StoredDeckState } from '../types';
+
+export const updateActiveDeck = (current: StoredDeckState, deckUpdates: Partial<DeckState>): StoredDeckState => {
+  const currentDeck = current.decks[current.activeDeck];
+  invariant(currentDeck, `Deck not found: ${current.activeDeck}`);
+  return {
+    ...current,
+    decks: {
+      ...current.decks,
+      [current.activeDeck]: {
+        ...currentDeck,
+        ...deckUpdates,
+      },
+    },
+  };
+};

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'),
+);