@dxos/plugin-deck 0.8.4-main.406dc2a → 0.8.4-main.4a85c3132b

package/src/hooks/useDeckState.ts

@@ -0,0 +1,82 @@
+//
+// 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 DeckEphemeralStateProps,
+  type DeckPluginState,
+  type DeckState,
+  type DeckStateProps,
+} 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: DeckStateProps) => DeckStateProps) => void;
+  /** Update ephemeral state. */
+  updateEphemeral: (fn: (current: DeckEphemeralStateProps) => DeckEphemeralStateProps) => 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 d = persistedState.decks[persistedState.activeDeck];
+    invariant(d, `Deck not found: ${persistedState.activeDeck}`);
+    return d;
+  }, [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: DeckStateProps) => DeckStateProps) => {
+      registry.set(stateAtom, fn(registry.get(stateAtom)));
+    },
+    [registry, stateAtom],
+  );
+
+  const updateEphemeral = useCallback(
+    (fn: (current: DeckEphemeralStateProps) => DeckEphemeralStateProps) => {
+      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,14 @@
 
 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 { meta } from '../meta';
-import type { DeckSettingsProps, LayoutMode } from '../types';
+import { DeckCapabilities, type LayoutMode } from '../types';
 
 export const useHoistStatusbar = (breakpoint: string, layoutMode?: LayoutMode): boolean => {
   const { safeAreaPadding } = useThemeContext();
-  const enableStatusbar = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(meta.id)?.value
-    .enableStatusbar;
+  const enableStatusbar = useAtomCapability(DeckCapabilities.Settings).enableStatusbar;
 
   return useMemo(() => {
     return (

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 { type Node, getGraph } 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,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type Node } from '@dxos/plugin-graph';
+
+import { parseEntryId } from '../layout';
+
+/**
+ * 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) => {
+        const { variant } = parseEntryId(companion.id);
+        return variant === preferredVariant;
+      });
+      if (preferred) {
+        const { variant } = parseEntryId(preferred.id);
+        return { companionId: preferred.id, variant };
+      }
+    }
+
+    // Fallback to first companion.
+    const first = companions[0];
+    const { variant } = parseEntryId(first.id);
+    return { companionId: first.id, variant };
+  }, [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/meta.ts

@@ -2,10 +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 meta: PluginMeta = {
+export const meta: Plugin.Meta = {
   id: 'dxos.org/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/translations.ts

@@ -34,7 +34,7 @@ export const translations = [
         'undo action label': 'Undo',
         'undo action alt': 'Undo previous action',
         'undo close label': 'Dismiss',
-        'error fallback message': 'Unable to open this item',
+        'error fallback message': 'Unable to open this object',
         'plank heading fallback label': 'Untitled',
         'actions menu label': 'Options',
         'settings deck label': 'Disable deck',
@@ -64,6 +64,7 @@ export const translations = [
         'close others label': 'Close other planks',
         'close all label': 'Close all planks',
         'companion plank heading fallback label': 'Related',
+        'open item label': 'Open',
       },
     },
   },

package/src/types/capabilities.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 DeckEphemeralStateProps, type DeckSettingsProps, type DeckState, type DeckStateProps } from '../types';
+
+export namespace DeckCapabilities {
+  export const Settings = Capability.make<Atom.Writable<DeckSettingsProps>>(`${meta.id}/capability/settings`);
+
+  /** Persisted state (stored in KVS/localStorage). */
+  export const State = Capability.make<Atom.Writable<DeckStateProps>>(`${meta.id}/capability/state`);
+
+  /** Transient/ephemeral state (not persisted). */
+  export const EphemeralState = Capability.make<Atom.Writable<DeckEphemeralStateProps>>(
+    `${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/events.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ActivationEvent } from '@dxos/app-framework';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+
+import { meta } from '../meta';
+
+import { DeckCapabilities } from './capabilities';
+
+export namespace DeckEvents {
+  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,
+  );
+}

package/src/types/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './capabilities';
+export * from './events';
 export * from './schema';

package/src/types/schema.ts

@@ -4,7 +4,9 @@
 
 import * as Schema from 'effect/Schema';
 
-import { LayoutAction } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { Label, LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
 import { type DeepReadonly } from '@dxos/util';
 
 import { meta } from '../meta';
@@ -18,8 +20,8 @@ export const DECK_COMPANION_TYPE = `${meta.id}/deck-companion`;
 export const NewPlankPositions = ['start', 'end'] as const;
 export type NewPlankPositioning = (typeof NewPlankPositions)[number];
 
-export const OverscrollOptions = ['none', 'centering'] as const;
-export type Overscroll = (typeof OverscrollOptions)[number];
+export const OverScrollToProps = ['none', 'centering'] as const;
+export type Overscroll = (typeof OverScrollToProps)[number];
 
 export type Part = 'solo' | 'deck' | 'complementary';
 export type ResolvedPart = Part | 'solo-primary' | 'solo-companion';
@@ -30,7 +32,7 @@ export const DeckSettingsSchema = Schema.Struct({
   enableStatusbar: Schema.optional(Schema.Boolean),
   enableNativeRedirect: Schema.optional(Schema.Boolean),
   newPlankPositioning: Schema.optional(Schema.Literal(...NewPlankPositions)),
-  overscroll: Schema.optional(Schema.Literal(...OverscrollOptions)),
+  overscroll: Schema.optional(Schema.Literal(...OverScrollToProps)),
   // TODO(burdon): Rename layoutMode? (e.g., bento | encapsulated?)
   encapsulatedPlanks: Schema.optional(Schema.Boolean),
 }).pipe(Schema.mutable);
@@ -44,8 +46,8 @@ export const DeckState = Schema.Struct({
   /** If false, the deck has not yet left solo mode and new planks should be soloed. */
   initialized: Schema.Boolean,
   active: Schema.mutable(Schema.Array(Schema.String)),
-  // TODO(wittjosiah): Piping into both mutable and optional caused invalid typescript output.
-  activeCompanions: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.String }))),
+  companionOpen: Schema.Boolean,
+  companionVariant: Schema.optional(Schema.String),
   inactive: Schema.mutable(Schema.Array(Schema.String)),
   solo: Schema.optional(Schema.String),
   fullscreen: Schema.Boolean,
@@ -57,7 +59,8 @@ export type DeckState = Schema.Schema.Type<typeof DeckState>;
 export const defaultDeck: DeckState = {
   initialized: false,
   active: [],
-  activeCompanions: {},
+  companionOpen: false,
+  companionVariant: undefined,
   inactive: [],
   solo: undefined,
   fullscreen: false,
@@ -77,12 +80,21 @@ export const getMode = (deck: DeckState | DeepReadonly<DeckState>): LayoutMode =
   return 'deck';
 };
 
-// State of the deck plugin.
-export const DeckPluginState = Schema.Struct({
+// Persisted plugin state (stored in KVS/localStorage).
+export const DeckStateSchema = Schema.Struct({
   sidebarState: Schema.Literal('closed', 'collapsed', 'expanded'),
   complementarySidebarState: Schema.Literal('closed', 'collapsed', 'expanded'),
   complementarySidebarPanel: Schema.optional(Schema.String),
+  activeDeck: Schema.String,
+  previousDeck: Schema.String,
+  decks: Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.mutable(DeckState) })),
+  previousMode: Schema.mutable(Schema.Record({ key: Schema.String, value: LayoutMode })),
+}).pipe(Schema.mutable);
+export type DeckStateProps = Schema.Schema.Type<typeof DeckStateSchema>;
 
+// TODO(burdon): Factor out state (in common with other layouts?)
+// Transient/ephemeral plugin state (not persisted).
+export const DeckEphemeralStateSchema = Schema.Struct({
   dialogOpen: Schema.Boolean,
   dialogType: Schema.optional(Schema.Literal('default', 'alert')),
   dialogBlockAlign: Schema.optional(Schema.Literal('start', 'center', 'end')),
@@ -95,23 +107,23 @@ export const DeckPluginState = Schema.Struct({
   popoverSide: Schema.optional(Schema.Literal('top', 'right', 'bottom', 'left')),
   popoverAnchor: Schema.optional(Schema.Any),
   popoverAnchorId: Schema.optional(Schema.String),
+  popoverKind: Schema.optional(Schema.Literal('base', 'card')),
+  popoverTitle: Schema.optional(Label.annotations({ description: 'The title of the popover.' })),
+  /** Ref of the subject to be passed to the popover Surface. */
+  popoverContentRef: Schema.optional(Schema.String),
   /** Data to be passed to the popover Surface. */
   popoverContent: Schema.optional(Schema.Any),
 
-  toasts: Schema.mutable(Schema.Array(LayoutAction.Toast)),
+  toasts: Schema.mutable(Schema.Array(LayoutOperation.Toast)),
   currentUndoId: Schema.optional(Schema.String),
 
-  activeDeck: Schema.String,
-  previousDeck: Schema.String,
-  decks: Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.mutable(DeckState) })),
-  previousMode: Schema.mutable(Schema.Record({ key: Schema.String, value: LayoutMode })),
-  deck: Schema.mutable(DeckState),
-
   /** The identifier of a component to scroll into view when it is mounted. */
   scrollIntoView: Schema.optional(Schema.String),
 }).pipe(Schema.mutable);
+export type DeckEphemeralStateProps = Schema.Schema.Type<typeof DeckEphemeralStateSchema>;
 
-export type DeckPluginState = Schema.Schema.Type<typeof DeckPluginState>;
+// Combined state type (for convenience in components that need both).
+export type DeckPluginState = DeckStateProps & DeckEphemeralStateProps;
 
 export namespace DeckAction {
   const PartAdjustmentSchema = Schema.Union(
@@ -142,9 +154,70 @@ export namespace DeckAction {
 
   export class ChangeCompanion extends Schema.TaggedClass<ChangeCompanion>()(`${meta.id}/action/change-companion`, {
     input: Schema.Struct({
-      primary: Schema.String,
       companion: Schema.Union(Schema.String, Schema.Null),
     }),
     output: Schema.Void,
   }) {}
 }
+
+/**
+ * Operations for the Deck plugin.
+ */
+export namespace DeckOperation {
+  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],
+    schema: {
+      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],
+    schema: {
+      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],
+    schema: {
+      input: Schema.Struct({
+        companion: Schema.Union(Schema.String, Schema.Null),
+      }),
+      output: Schema.Void,
+    },
+  });
+}

package/src/util/layoutAppliesTopbar.ts

@@ -6,7 +6,7 @@ import { type LayoutMode } from '../types';
 
 export const layoutAppliesTopbar = (breakpoint: string, layoutMode?: LayoutMode) => {
   return (
-    document.body.getAttribute('data-platform') === 'win' &&
+    document.body.getAttribute('data-platform') === 'windows' &&
     breakpoint === 'desktop' &&
     layoutMode !== 'solo--fullscreen'
   );

package/src/util/overscroll.ts

@@ -56,14 +56,14 @@ export const calculateOverscroll = (
   }
   if (planksCount === 1) {
     const overscrollPadding =
-      'max(0px, calc(((100dvw - var(--dx-main-sidebarWidth) - var(--dx-main-complementaryWidth) - (var(--dx-main-contentFirstWidth) + 1px)) / 2)))';
+      'max(0px, calc(((100dvw - var(--dx-main-sidebar-width) - var(--dx-main-complementary-width) - (var(--dx-main-content-first-width) + 1px)) / 2)))';
     return { paddingInlineStart: overscrollPadding, paddingInlineEnd: overscrollPadding };
   } else {
     return {
       paddingInlineStart:
-        'max(0px, calc(((100dvw - (var(--dx-main-contentFirstWidth) + 1px)) / 2) - var(--dx-main-sidebarWidth)))',
+        'max(0px, calc(((100dvw - (var(--dx-main-content-first-width) + 1px)) / 2) - var(--dx-main-sidebar-width)))',
       paddingInlineEnd:
-        'max(0px, calc(((100dvw - (var(--dx-main-contentLastWidth) + 1px)) / 2) - var(--dx-main-complementaryWidth)))',
+        'max(0px, calc(((100dvw - (var(--dx-main-content-last-width) + 1px)) / 2) - var(--dx-main-complementary-width)))',
     };
   }
 };

package/src/util/set-active.ts

@@ -2,46 +2,66 @@
 // Copyright 2025 DXOS.org
 //
 
-import { batch } from '@preact/signals-core';
-
 import { type AttentionManager } from '@dxos/plugin-attention';
 
-import { type DeckPluginState } from '../types';
+import { type DeckState } from '../types';
 
 export type SetActiveOptions = {
   next: string[];
-  state: DeckPluginState;
+  deck: DeckState;
   attention?: AttentionManager;
 };
 
-export const setActive = ({ next, state, attention }: SetActiveOptions) => {
-  return batch(() => {
-    const active = state.deck.solo ? [state.deck.solo] : state.deck.active;
-    const removed = active.filter((id) => !next.includes(id));
-    const closed = Array.from(new Set([...state.deck.inactive.filter((id) => !next.includes(id)), ...removed]));
+export type SetActiveResult = {
+  /** Updates to apply to the deck. */
+  deckUpdates: {
+    inactive: string[];
+    solo: string | undefined;
+    active: string[];
+    fullscreen: boolean;
+  };
+  /** ID of the item to attend (scroll into view) if attention changed. */
+  toAttend?: string;
+};
 
-    state.deck.inactive = closed;
+/**
+ * Computes the new active state for the deck without mutating.
+ * Returns the updates to apply and optionally an item to attend.
+ */
+export const computeActiveUpdates = ({ next, deck, attention }: SetActiveOptions): SetActiveResult => {
+  const active = deck.solo ? [deck.solo] : deck.active;
+  const removed = active.filter((id) => !next.includes(id));
+  const closed = Array.from(new Set([...deck.inactive.filter((id) => !next.includes(id)), ...removed]));
 
-    if (state.deck.solo || !state.deck.initialized) {
-      state.deck.solo = next[0];
-    } else {
-      state.deck.active = next;
-    }
+  const updates = {
+    inactive: closed,
+    solo: deck.solo,
+    active: deck.active,
+    fullscreen: deck.fullscreen,
+  };
 
-    if (state.deck.fullscreen && !state.deck.solo) {
-      state.deck.fullscreen = false;
-    }
+  if (deck.solo || !deck.initialized) {
+    updates.solo = next[0];
+  } else {
+    updates.active = next;
+  }
+
+  if (deck.fullscreen && !updates.solo) {
+    updates.fullscreen = false;
+  }
 
-    if (attention) {
-      const attended = attention.current;
-      const [attendedId] = Array.from(attended);
-      const isAttendedAvailable = !!attendedId && next.includes(attendedId);
-      if (!isAttendedAvailable) {
-        const attendedIndex = active.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 >= next.length ? next.length - 1 : attendedIndex;
-        return next[index];
-      }
+  let toAttend: string | undefined;
+  if (attention) {
+    const attended = attention.getCurrent();
+    const [attendedId] = Array.from(attended);
+    const isAttendedAvailable = !!attendedId && next.includes(attendedId);
+    if (!isAttendedAvailable) {
+      const attendedIndex = active.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 >= next.length ? next.length - 1 : attendedIndex;
+      toAttend = next[index];
     }
-  });
+  }
+
+  return { deckUpdates: updates, toAttend };
 };