@dxos/plugin-deck 0.8.4-main.70d3990 → 0.8.4-main.7996785055

package/src/capabilities/settings/settings.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+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(AppCapabilities.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,97 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+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';
+import { sanitizePersistedState } from '../../util';
+
+/** 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(Capabilities.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);
+
+    // Sanitize persisted state on startup (see sanitizePersistedState for details).
+    const currentState = registry.get(stateAtom);
+    const sanitizedState = sanitizePersistedState(currentState);
+    if (sanitizedState !== currentState) {
+      registry.set(stateAtom, sanitizedState);
+    }
+
+    // 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 AppCapabilities.Layout;
+    }).pipe(Atom.keepAlive);
+
+    return [
+      Capability.contributes(DeckCapabilities.State, stateAtom),
+      Capability.contributes(DeckCapabilities.EphemeralState, ephemeralAtom),
+      Capability.contributes(AppCapabilities.Layout, layoutAtom),
+    ];
+  }),
+);

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,91 @@
+//
+// 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 '../../operations';
+
+// 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, {
+              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,108 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation, fromUrlPath, getWorkspaceFromPath, toUrlPath } from '@dxos/app-toolkit';
+import { invariant } from '@dxos/invariant';
+import { Node } from '@dxos/plugin-graph';
+
+import { DeckCapabilities, type DeckStateProps, defaultDeck } from '../../types';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const { invokePromise } = yield* Capability.get(Capabilities.OperationInvoker);
+    const registry = yield* Capability.get(Capabilities.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 = async () => {
+      const pathname = window.location.pathname;
+      const state = getState();
+      if (pathname === '/reset') {
+        updateState((s) => ({
+          ...s,
+          activeDeck: 'default',
+          decks: {
+            default: { ...defaultDeck },
+          },
+        }));
+        window.location.pathname = '/';
+        return;
+      }
+
+      const qualifiedId = fromUrlPath(pathname);
+      const workspace = getWorkspaceFromPath(qualifiedId);
+      if (workspace !== Node.RootId && workspace !== state.activeDeck) {
+        await invokePromise(LayoutOperation.SwitchWorkspace, { subject: workspace });
+      }
+
+      const deck = getDeck();
+      const activeId = qualifiedId !== workspace ? qualifiedId : undefined;
+      if (activeId) {
+        // Ensure the object referenced by the URL is open in the deck.
+        await invokePromise(LayoutOperation.Open, { subject: [activeId] });
+        // If not already in solo mode, switch to solo for the target object.
+        if (!deck.solo) {
+          await invokePromise(LayoutOperation.SetLayoutMode, { subject: activeId, mode: 'solo' });
+        }
+      } else if (deck.solo) {
+        // Stay in solo mode; redirect URL to reflect the current solo item.
+        // Do not switch to deck mode here — only explicit user action should change layout mode.
+        const path = toUrlPath(deck.solo);
+        if (window.location.pathname !== path) {
+          history.replaceState(null, '', `${path}${window.location.search}`);
+        }
+      }
+    };
+
+    yield* Effect.promise(() => 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 ? toUrlPath(solo) : toUrlPath(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(Capabilities.Null, null, () =>
+      Effect.sync(() => {
+        window.removeEventListener('popstate', handleNavigation);
+        unsubscribe();
+      }),
+    );
+  }),
+);

package/src/components/DeckLayout/ActiveNode.tsx

@@ -4,7 +4,8 @@
 
 import React from 'react';
 
-import { Surface, useAppGraph } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { useNode } from '@dxos/plugin-graph';
 import { useAttended } from '@dxos/react-ui-attention';
 
@@ -21,7 +22,7 @@ export const ActiveNode = () => {
     <div role='none' className='sr-only'>
       {/* TODO(wittjosiah): Weird that this is a surface, feel like it's not really render logic.
             Probably this lives in React-land currently in order to access translations? */}
-      <Surface role='document-title' data={{ subject: activeNode }} limit={1} />
+      <Surface.Surface role='document-title' data={{ subject: activeNode }} limit={1} />
     </div>
   );
 };

package/src/components/DeckLayout/Banner.tsx

@@ -4,9 +4,9 @@
 
 import React from 'react';
 
-import { Surface } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
 import { type ThemedClassName, useTranslation } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx, osTranslations } from '@dxos/ui-theme';
 
 import { meta } from '../../meta';
 import { CloseSidebarButton, ToggleSidebarButton } from '../Sidebar';
@@ -16,24 +16,24 @@ export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'top
   return (
     <header
       className={mx(
-        'flex items-stretch relative plb-1 pis-1 pie-2',
+        'flex items-stretch relative py-1 ps-1 pe-2',
         variant === 'topbar' &&
-          'fixed inset-inline-0 block-start-[env(safe-area-inset-top)] bs-[--rail-size] border-be border-separator',
+          'fixed inset-x-0 top-[env(safe-area-inset-top)] h-(--dx-rail-size) border-b border-separator',
         classNames,
       )}
     >
       {variant === 'sidebar' ? <CloseSidebarButton /> : <ToggleSidebarButton />}
-      <span className='self-center grow mis-1'>{t('current app name', { ns: 'appkit' })}</span>
+      <span className='self-center grow ms-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'>
-            <Surface role='search-input' limit={1} />
+          <div role='none' className='grid h-full pointer-fine:p-1 max-w-md mx-auto pointer-events-auto'>
+            <Surface.Surface role='search-input' limit={1} />
           </div>
         </div>
       )}
       <span role='none' className='grow' />
-      <Surface role='header-end' limit={1} />
-      <Surface role='notch-start' limit={1} />
+      <Surface.Surface role='version-info' limit={1} />
+      <Surface.Surface role='notch-start' limit={1} />
     </header>
   );
 };

package/src/components/DeckLayout/ContentEmpty.tsx

@@ -4,10 +4,9 @@
 
 import React from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
 
-import { DeckCapabilities } from '../../capabilities';
-import { useBreakpoints } from '../../hooks';
+import { useBreakpoints, useDeckState } from '../../hooks';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
 import { fixedSidebarToggleStyles } from '../fragments';
@@ -15,16 +14,16 @@ 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 (
     <div
       role='none'
-      className='grid place-items-center p-8 relative bg-deckSurface'
+      className='grid place-items-center p-8 relative bg-deck-surface'
       data-testid='layoutPlugin.firstRunMessage'
     >
-      <Surface role='keyshortcuts' />
+      <Surface.Surface role='keyshortcuts' />
       {!topbar && <ToggleSidebarButton variant='default' classNames={fixedSidebarToggleStyles} />}
     </div>
   );

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

@@ -5,49 +5,38 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { Events, IntentPlugin, SettingsPlugin, defineModule, definePlugin } from '@dxos/app-framework';
+import { Capability, Plugin } from '@dxos/app-framework';
 import { withPluginManager } from '@dxos/app-framework/testing';
-import { AttentionPlugin } from '@dxos/plugin-attention';
-import { GraphPlugin } from '@dxos/plugin-graph';
-import { withTheme } from '@dxos/react-ui/testing';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { corePlugins } from '@dxos/plugin-testing';
+import { withLayout } from '@dxos/react-ui/testing';
 
-import { DeckStateFactory, LayoutIntentResolver } from '../../capabilities';
+import { DeckState, OperationHandler } 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: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  AppPlugin.addOperationHandlerModule({
+    activate: OperationHandler,
+  }),
+  Plugin.make,
+);
+
 const meta = {
-  title: 'plugins/plugin-deck/DeckLayout',
+  title: 'plugins/plugin-deck/components/DeckLayout',
   component: DeckLayout,
   render: (args) => <DeckLayout {...args} />,
   decorators: [
-    withTheme,
+    withLayout({ layout: 'fullscreen' }),
     withPluginManager({
-      plugins: [
-        AttentionPlugin(),
-        SettingsPlugin(),
-        IntentPlugin(),
-        GraphPlugin(),
-        definePlugin(
-          {
-            id: 'example.com/plutin/testing',
-            name: 'Testing',
-          },
-          () => [
-            defineModule({
-              id: `${pluginMeta.id}/module/deck-state`,
-              activatesOn: Events.AppGraphReady,
-              activate: () => DeckStateFactory(),
-            }),
-            defineModule({
-              id: `${pluginMeta.id}/module/layout-intent-resolver`,
-              activatesOn: Events.SetupIntentResolver,
-              activate: LayoutIntentResolver,
-            }),
-          ],
-        )(),
-      ],
+      plugins: [...corePlugins(), TestPlugin()],
     }),
   ],
   parameters: {

package/src/components/DeckLayout/DeckLayout.tsx

@@ -4,9 +4,9 @@
 
 import React from 'react';
 
-import { useCapability } from '@dxos/app-framework/react';
+import { Mosaic } from '@dxos/react-ui-mosaic';
 
-import { DeckCapabilities } from '../../capabilities';
+import { useDeckState } from '../../hooks';
 
 import { ActiveNode } from './ActiveNode';
 import { DeckMain } from './DeckMain';
@@ -17,16 +17,18 @@ import { Toaster, type ToasterProps } from './Toast';
 export type DeckLayoutProps = Pick<ToasterProps, 'onDismissToast'>;
 
 export const DeckLayout = ({ onDismissToast }: DeckLayoutProps) => {
-  const context = useCapability(DeckCapabilities.MutableDeckState);
-  const { toasts } = context;
+  const { state } = useDeckState();
+  const { toasts } = state;
 
   return (
-    <PopoverRoot>
-      <ActiveNode />
-      <DeckMain />
-      <PopoverContent />
-      <Dialog />
-      <Toaster toasts={toasts} onDismissToast={onDismissToast} />
-    </PopoverRoot>
+    <Mosaic.Root>
+      <PopoverRoot>
+        <ActiveNode />
+        <DeckMain />
+        <PopoverContent />
+        <Dialog />
+        <Toaster toasts={toasts} onDismissToast={onDismissToast} />
+      </PopoverRoot>
+    </Mosaic.Root>
   );
 };