@dxos/plugin-deck 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/capabilities/settings/settings.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability, Common } from '@dxos/app-framework';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '../../meta';
+import { DeckCapabilities, DeckSettingsSchema } from '../../types';
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: DeckSettingsSchema,
+      defaultValue: () => ({
+        showHints: false,
+        enableDeck: false,
+        enableStatusbar: false,
+        enableNativeRedirect: false,
+        newPlankPositioning: 'start' as const,
+        overscroll: 'none' as const,
+        encapsulatedPlanks: false,
+      }),
+    });
+
+    return [
+      Capability.contributes(DeckCapabilities.Settings, settingsAtom),
+      Capability.contributes(Common.Capability.Settings, {
+        prefix: meta.id,
+        schema: DeckSettingsSchema,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/capabilities/state/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const DeckState = Capability.lazy('DeckState', () => import('./state'));

package/src/capabilities/state/state.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capability, Common } from '@dxos/app-framework';
+import { createKvsStore } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+
+import { meta } from '../../meta';
+import {
+  DeckCapabilities,
+  type DeckEphemeralStateProps,
+  type DeckStateProps,
+  DeckStateSchema,
+  defaultDeck,
+  getMode,
+} from '../../types';
+
+/** Default persisted state. */
+const defaultDeckState: DeckStateProps = {
+  sidebarState: 'expanded',
+  complementarySidebarState: 'collapsed',
+  complementarySidebarPanel: undefined,
+  activeDeck: 'default',
+  previousDeck: 'default',
+  decks: {
+    default: { ...defaultDeck },
+  },
+  previousMode: {},
+};
+
+/** Default ephemeral state. */
+const defaultDeckEphemeralState: DeckEphemeralStateProps = {
+  dialogContent: null,
+  dialogOpen: false,
+  dialogBlockAlign: undefined,
+  dialogType: undefined,
+  popoverContent: null,
+  popoverAnchor: undefined,
+  popoverAnchorId: undefined,
+  popoverOpen: false,
+  toasts: [],
+  currentUndoId: undefined,
+  scrollIntoView: undefined,
+};
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const registry = yield* Capability.get(Common.Capability.AtomRegistry);
+
+    // Persisted state using KVS store.
+    const stateAtom = createKvsStore({
+      key: `${meta.id}/state`,
+      schema: DeckStateSchema,
+      defaultValue: () => ({ ...defaultDeckState }),
+    });
+
+    // Ephemeral state (not persisted, but kept alive to prevent GC resets).
+    const ephemeralAtom = Atom.make<DeckEphemeralStateProps>({ ...defaultDeckEphemeralState }).pipe(Atom.keepAlive);
+
+    // Don't allow fullscreen mode to be persisted to prevent getting stuck in it.
+    const currentState = registry.get(stateAtom);
+    const currentDeck = currentState.decks[currentState.activeDeck];
+    if (currentDeck?.fullscreen) {
+      registry.set(stateAtom, {
+        ...currentState,
+        decks: {
+          ...currentState.decks,
+          [currentState.activeDeck]: {
+            ...currentDeck,
+            fullscreen: false,
+          },
+        },
+      });
+    }
+
+    // Create derived layout atom (read-only) from both state atoms.
+    const layoutAtom = Atom.make((get) => {
+      const state = get(stateAtom);
+      const ephemeral = get(ephemeralAtom);
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return {
+        mode: getMode(deck),
+        dialogOpen: ephemeral.dialogOpen,
+        sidebarOpen: state.sidebarState === 'expanded',
+        complementarySidebarOpen: state.complementarySidebarState === 'expanded',
+        workspace: state.activeDeck,
+        active: deck.solo ? [deck.solo] : deck.active,
+        inactive: deck.inactive,
+        scrollIntoView: ephemeral.scrollIntoView,
+      } satisfies Common.Capability.Layout;
+    }).pipe(Atom.keepAlive);
+
+    return [
+      Capability.contributes(DeckCapabilities.State, stateAtom),
+      Capability.contributes(DeckCapabilities.EphemeralState, ephemeralAtom),
+      Capability.contributes(Common.Capability.Layout, layoutAtom),
+    ];
+  }),
+);

package/src/capabilities/toolkit/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const Toolkit = Capability.lazy('Toolkit', () => import('./toolkit'));

package/src/capabilities/toolkit/toolkit.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Capability, type CapabilityManager, Common } from '@dxos/app-framework';
+import { GenericToolkit } from '@dxos/assistant';
+import { ArtifactId } from '@dxos/assistant';
+import { type SpaceId } from '@dxos/keys';
+import { trim } from '@dxos/util';
+
+import { DeckCapabilities } from '../../types';
+
+const Toolkit$ = Toolkit.make(
+  Tool.make('open-item', {
+    description: trim`
+      Opens an item in the application.
+    `,
+    parameters: {
+      id: ArtifactId,
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+  }),
+);
+
+export namespace DeckToolkit {
+  export const Toolkit = Toolkit$;
+
+  export const createLayer = (capabilityManager: CapabilityManager.CapabilityManager) =>
+    Toolkit$.toLayer({
+      'open-item': ({ id }) =>
+        Effect.gen(function* () {
+          const registry = capabilityManager.get(Common.Capability.AtomRegistry);
+          const stateAtom = capabilityManager.get(DeckCapabilities.State);
+          const state = registry.get(stateAtom);
+          const dxn = ArtifactId.toDXN(id, state.activeDeck as SpaceId).asEchoDXN();
+          if (!dxn) {
+            // TODO(wittjosiah): Support other variants.
+            throw new Error(`Invalid object ID: ${id}`);
+          }
+
+          // TODO(wittjosiah): Get capabilities via layers.
+          const { invoke } = capabilityManager.get(Common.Capability.OperationInvoker);
+          yield* invoke(Common.LayoutOperation.Open, { subject: [`${dxn.spaceId!}:${dxn.echoId}`] });
+        }).pipe(Effect.orDie),
+    });
+}
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilityManager = yield* Capability.Service;
+
+    return Capability.contributes(
+      Common.Capability.Toolkit,
+      GenericToolkit.make(DeckToolkit.Toolkit, DeckToolkit.createLayer(capabilityManager)),
+    );
+  }),
+);

package/src/capabilities/tools/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const Tools = Capability.lazy('Tools', () => import('./tools'));

package/src/capabilities/tools/tools.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// ISSUE(burdon): tools
+// @ts-nocheck
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import {
+  Capabilities,
+  Capability,
+  LayoutAction,
+  type PromiseIntentDispatcher,
+  createIntent,
+} from '@dxos/app-framework';
+import { type OperationInvoker } from '@dxos/app-framework/plugin-operation/invoker';
+import { invariant } from '@dxos/invariant';
+import { trim } from '@dxos/util';
+
+import { meta } from '../../meta';
+import { DeckOperation } from '../../types';
+
+// TODO(burdon): Factor out.
+declare global {
+  interface ToolContextExtensions {
+    dispatch?: PromiseIntentDispatcher;
+    pivotId?: string;
+    part?: 'deck' | 'dialog';
+  }
+}
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.Tools, [
+      createTool(meta.id, {
+        name: 'show',
+        description: trim`
+        Show an item as a companion to an existing plank. 
+        When supplying IDs, they must be fully qualified like this: space-key:object-id
+      `,
+        caption: 'Showing item...',
+        // TODO(wittjosiah): Refactor Layout/Navigation/Deck actions so that they can be used directly.
+        schema: Schema.Struct({
+          id: Schema.String.annotations({
+            description: 'The ID of the item to show.',
+          }),
+        }),
+        execute: async ({ id }, { extensions }) => {
+          invariant(extensions);
+          const { pivotId, dispatch, invokePromise, part } = extensions as {
+            pivotId: string;
+            dispatch: PromiseIntentDispatcher;
+            invokePromise: OperationInvoker['invokePromise'];
+            part: string;
+          };
+          invariant(pivotId, 'No pivot ID');
+          invariant(invokePromise, 'No operation invoker');
+
+          if (part === 'deck') {
+            const { error } = await invokePromise(DeckOperation.ChangeCompanion, {
+              primary: pivotId,
+              companion: id,
+            });
+            if (error) {
+              return ToolResult.Error(error.message);
+            }
+
+            return ToolResult.Success({});
+          } else {
+            const { data, error } = await dispatch(
+              createIntent(LayoutAction.Open, {
+                subject: [id],
+                part: 'main',
+                options: {
+                  pivotId,
+                  positioning: 'end',
+                },
+              }),
+            );
+            if (error) {
+              return ToolResult.Error(error.message);
+            }
+
+            return ToolResult.Success(data);
+          }
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/url-handler/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const UrlHandler = Capability.lazy('UrlHandler', () => import('./url-handler'));

package/src/capabilities/url-handler/url-handler.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability, Common } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+
+import { DeckCapabilities, type DeckStateProps, defaultDeck } from '../../types';
+
+// TODO(wittjosiah): Cleanup the url handling. May justify introducing routing capabilities.
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const { invokeSync } = yield* Capability.get(Common.Capability.OperationInvoker);
+    const registry = yield* Capability.get(Common.Capability.AtomRegistry);
+    const stateAtom = yield* Capability.get(DeckCapabilities.State);
+
+    // Helper to get state.
+    const getState = () => registry.get(stateAtom);
+
+    // Helper to get computed deck from state.
+    const getDeck = () => {
+      const state = getState();
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return deck;
+    };
+
+    // Helper to update state.
+    const updateState = (fn: (current: DeckStateProps) => DeckStateProps) => {
+      registry.set(stateAtom, fn(getState()));
+    };
+
+    const handleNavigation = () => {
+      const pathname = window.location.pathname;
+      const state = getState();
+      if (pathname === '/reset') {
+        updateState((s) => ({
+          ...s,
+          activeDeck: 'default',
+          decks: {
+            default: { ...defaultDeck },
+          },
+        }));
+        window.location.pathname = '/';
+        return;
+      }
+
+      const [_, nextDeck, nextSolo] = pathname.split('/');
+      if (nextDeck && nextDeck !== state.activeDeck) {
+        invokeSync(Common.LayoutOperation.SwitchWorkspace, { subject: nextDeck });
+      }
+
+      const deck = getDeck();
+      if (nextSolo && nextSolo !== deck.solo) {
+        invokeSync(Common.LayoutOperation.SetLayoutMode, { subject: nextSolo, mode: 'solo' });
+      } else if (!nextSolo && deck.solo) {
+        invokeSync(Common.LayoutOperation.SetLayoutMode, { mode: 'deck' });
+      }
+    };
+
+    yield* Effect.sync(() => handleNavigation());
+    window.addEventListener('popstate', handleNavigation);
+
+    // Subscribe to state changes to update the URL.
+    let lastSolo: string | undefined;
+    let lastActiveDeck: string | undefined;
+    const unsubscribe = registry.subscribe(stateAtom, () => {
+      const state = getState();
+      const deck = getDeck();
+      const solo = deck.solo;
+      const activeDeck = state.activeDeck;
+
+      // Only update URL if relevant state changed.
+      if (solo !== lastSolo || activeDeck !== lastActiveDeck) {
+        lastSolo = solo;
+        lastActiveDeck = activeDeck;
+
+        const path = solo ? `/${activeDeck}/${solo}` : `/${activeDeck}`;
+        if (window.location.pathname !== path) {
+          // TODO(thure): In some browsers, this only preserves the most recent state change, even though this is not `history.replace`…
+          history.pushState(null, '', `${path}${window.location.search}`);
+        }
+      }
+    });
+
+    return Capability.contributes(Common.Capability.Null, null, () =>
+      Effect.sync(() => {
+        window.removeEventListener('popstate', handleNavigation);
+        unsubscribe();
+      }),
+    );
+  }),
+);

package/src/components/DeckLayout/ActiveNode.tsx

@@ -4,7 +4,7 @@
 
 import React from 'react';
 
-import { Surface, useAppGraph } from '@dxos/app-framework';
+import { Surface, useAppGraph } from '@dxos/app-framework/react';
 import { useNode } from '@dxos/plugin-graph';
 import { useAttended } from '@dxos/react-ui-attention';
 

package/src/components/DeckLayout/Banner.tsx

@@ -4,15 +4,15 @@
 
 import React from 'react';
 
-import { Surface } from '@dxos/app-framework';
-import { useTranslation, type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { Surface } from '@dxos/app-framework/react';
+import { type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { mx, osTranslations } from '@dxos/ui-theme';
 
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '../../meta';
 import { CloseSidebarButton, ToggleSidebarButton } from '../Sidebar';
 
 export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'topbar' | 'sidebar' }>) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
   return (
     <header
       className={mx(
@@ -23,7 +23,7 @@ export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'top
       )}
     >
       {variant === 'sidebar' ? <CloseSidebarButton /> : <ToggleSidebarButton />}
-      <span className='self-center grow mis-1'>{t('current app name', { ns: 'appkit' })}</span>
+      <span className='self-center grow mis-1'>{t('current app name', { ns: osTranslations })}</span>
       {variant === 'topbar' && (
         <div role='none' className='absolute inset-0 pointer-events-none'>
           <div role='none' className='grid bs-full pointer-fine:p-1 max-is-md mli-auto pointer-events-auto'>

package/src/components/DeckLayout/ContentEmpty.tsx

@@ -4,18 +4,17 @@
 
 import React from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/react';
 
-import { DeckCapabilities } from '../../capabilities';
-import { useBreakpoints } from '../../hooks';
+import { useBreakpoints, useDeckState } from '../../hooks';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
-import { ToggleSidebarButton } from '../Sidebar';
 import { fixedSidebarToggleStyles } from '../fragments';
+import { ToggleSidebarButton } from '../Sidebar';
 
 export const ContentEmpty = () => {
   const breakpoint = useBreakpoints();
-  const { deck } = useCapability(DeckCapabilities.MutableDeckState);
+  const { deck } = useDeckState();
   const layoutMode = getMode(deck);
   const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
   return (

package/src/components/DeckLayout/DeckLayout.stories.tsx

@@ -0,0 +1,51 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Capability, Common, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { DeckState, LayoutOperationResolver } from '../../capabilities';
+import { meta as pluginMeta } from '../../meta';
+import { translations } from '../../translations';
+
+import { DeckLayout } from './DeckLayout';
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: Common.ActivationEvent.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  Common.Plugin.addOperationResolverModule({
+    activate: LayoutOperationResolver,
+  }),
+  Plugin.make,
+);
+
+const meta = {
+  title: 'plugins/plugin-deck/DeckLayout',
+  component: DeckLayout,
+  render: (args) => <DeckLayout {...args} />,
+  decorators: [
+    withTheme,
+    withPluginManager({
+      plugins: [...corePlugins(), TestPlugin()],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DeckLayout>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};