@dxos/plugin-deck 0.7.4 → 0.7.5-labs.5f04cf6

package/src/capabilities/navigation/intent-resolver.ts

@@ -0,0 +1,216 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { batch } from '@preact/signals-core';
+import { pipe } from 'effect';
+
+import {
+  Capabilities,
+  chain,
+  contributes,
+  createIntent,
+  createResolver,
+  LayoutAction,
+  NavigationAction,
+  openIds,
+  SLUG_PATH_SEPARATOR,
+  type LayoutEntry,
+  type LayoutPart,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { isReactiveObject, getTypename } from '@dxos/live-object';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+import { ObservabilityAction } from '@dxos/plugin-observability/types';
+
+import { setLocation } from './set-location';
+import { closeEntry, incrementPlank, openEntry } from '../../layout';
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps } from '../../types';
+import { getEffectivePart } from '../../util';
+
+// TODO(wittjosiah): Factor out navgiation from deck plugin.
+export default (context: PluginsContext) =>
+  contributes(Capabilities.IntentResolver, [
+    createResolver(NavigationAction.Open, (data) => {
+      const { graph } = context.requestCapability(Capabilities.AppGraph);
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+      const settings = context
+        .requestCapabilities(Capabilities.SettingsStore)[0]
+        ?.getStore<DeckSettingsProps>(DECK_PLUGIN)?.value;
+
+      const previouslyOpenIds = new Set<string>(openIds(location.active));
+      const layoutMode = layout.layoutMode;
+      const toAttend = batch(() => {
+        const processLayoutEntry = (partName: string, entryString: string, currentLayout: any) => {
+          // TODO(burdon): Option to toggle?
+          const toggle = false;
+          const [id, path] = entryString.split(SLUG_PATH_SEPARATOR);
+          const layoutEntry: LayoutEntry = { id, ...(path ? { path } : {}) };
+          const effectivePart = getEffectivePart(partName as LayoutPart, layoutMode);
+          if (
+            toggle &&
+            layoutMode === 'deck' &&
+            effectivePart === 'main' &&
+            currentLayout[effectivePart]?.some((entry: LayoutEntry) => entry.id === id) &&
+            !data?.noToggle
+          ) {
+            // If we're in deck mode and the main part is already open, toggle it closed.
+            return closeEntry(currentLayout, { part: effectivePart as LayoutPart, entryId: id });
+          } else {
+            return openEntry(currentLayout, effectivePart, layoutEntry, {
+              positioning: settings?.newPlankPositioning,
+            });
+          }
+        };
+
+        let newLayout = location.active;
+        Object.entries(data.activeParts).forEach(([partName, layoutEntries]) => {
+          if (Array.isArray(layoutEntries)) {
+            layoutEntries.forEach((activePartEntry: string) => {
+              newLayout = processLayoutEntry(partName, activePartEntry, newLayout);
+            });
+          } else if (typeof layoutEntries === 'string') {
+            // Legacy single string entry.
+            newLayout = processLayoutEntry(partName, layoutEntries, newLayout);
+          }
+        });
+
+        return setLocation({ next: newLayout, layout, location, attention });
+      });
+
+      const ids = openIds(location.active);
+      const newlyOpen = ids.filter((i) => !previouslyOpenIds.has(i));
+
+      return {
+        data: { open: ids },
+        intents: [
+          createIntent(LayoutAction.ScrollIntoView, { id: newlyOpen[0] ?? toAttend }),
+          ...(toAttend ? [createIntent(NavigationAction.Expose, { id: toAttend })] : []),
+          ...newlyOpen.map((id) => {
+            const active = graph?.findNode(id)?.data;
+            const typename = isReactiveObject(active) ? getTypename(active) : undefined;
+            return createIntent(ObservabilityAction.SendEvent, {
+              name: 'navigation.activate',
+              properties: {
+                id,
+                typename,
+              },
+            });
+          }),
+        ],
+      };
+    }),
+    createResolver(NavigationAction.AddToActive, (data) => {
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+      const settings = context
+        .requestCapabilities(Capabilities.SettingsStore)[0]
+        ?.getStore<DeckSettingsProps>(DECK_PLUGIN)?.value;
+
+      const layoutEntry = { id: data.id };
+      const effectivePart = getEffectivePart(data.part, layout.layoutMode);
+
+      setLocation({
+        next: openEntry(location.active, effectivePart, layoutEntry, {
+          positioning: data.positioning ?? settings?.newPlankPositioning,
+          pivotId: data.pivotId,
+        }),
+        layout,
+        location,
+        attention,
+      });
+
+      const intents = [];
+      if (data.scrollIntoView && layout.layoutMode === 'deck') {
+        intents.push(createIntent(LayoutAction.ScrollIntoView, { id: data.id }));
+      }
+
+      return { intents };
+    }),
+    createResolver(NavigationAction.Close, (data) => {
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+      let newLayout = location.active;
+      const layoutMode = layout.layoutMode;
+      const intentParts = data.activeParts;
+      Object.keys(intentParts).forEach((partName: string) => {
+        const effectivePart = getEffectivePart(partName as LayoutPart, layoutMode);
+        const ids = intentParts[partName];
+        if (Array.isArray(ids)) {
+          ids.forEach((id: string) => {
+            newLayout = closeEntry(newLayout, { part: effectivePart, entryId: id });
+          });
+        } else {
+          // Legacy single string entry
+          newLayout = closeEntry(newLayout, { part: effectivePart, entryId: ids });
+        }
+      });
+
+      const toAttend = setLocation({ next: newLayout, layout, location, attention });
+      return { intents: [createIntent(LayoutAction.ScrollIntoView, { id: toAttend })] };
+    }),
+    createResolver(NavigationAction.Set, (data) => {
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+      return batch(() => {
+        const toAttend = setLocation({ next: data.activeParts, layout, location, attention });
+        return { intents: [createIntent(LayoutAction.ScrollIntoView, { id: toAttend })] };
+      });
+    }),
+    createResolver(NavigationAction.Adjust, (adjustment) => {
+      const location = context.requestCapability(Capabilities.MutableLocation);
+      const layout = context.requestCapability(Capabilities.MutableLayout);
+      const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+      return batch(() => {
+        if (adjustment.type === 'increment-end' || adjustment.type === 'increment-start') {
+          setLocation({
+            next: incrementPlank(location.active, {
+              type: adjustment.type,
+              layoutCoordinate: adjustment.layoutCoordinate,
+            }),
+            layout,
+            location,
+            attention,
+          });
+        }
+
+        if (adjustment.type === 'solo') {
+          const entryId = adjustment.layoutCoordinate.entryId;
+          if (layout.layoutMode !== 'solo') {
+            // Solo the entry.
+            return {
+              intents: [
+                // NOTE: The order of these is important.
+                pipe(
+                  createIntent(NavigationAction.Open, { activeParts: { solo: [entryId] } }),
+                  chain(LayoutAction.SetLayoutMode, { layoutMode: 'solo' }),
+                ),
+              ],
+            };
+          } else {
+            // Un-solo the current entry.
+            return {
+              intents: [
+                // NOTE: The order of these is important.
+                pipe(
+                  createIntent(LayoutAction.SetLayoutMode, { layoutMode: 'deck' }),
+                  chain(NavigationAction.Close, { activeParts: { solo: [entryId] } }),
+                  chain(NavigationAction.Open, { activeParts: { main: [entryId] }, noToggle: true }),
+                  chain(LayoutAction.ScrollIntoView, { id: entryId }),
+                ),
+              ],
+            };
+          }
+        }
+      });
+    }),
+  ]);

package/src/capabilities/navigation/location.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, type LayoutParts } from '@dxos/app-framework';
+import { LocalStorageStore } from '@dxos/local-storage';
+
+import { NAV_ID } from '../../components';
+
+// NOTE: The key is this currently for backwards compatibility of storage.
+const LOCATION_KEY = 'dxos.org/settings/layout';
+
+export default () => {
+  // TODO(wittjosiah): This active state is not a generic navigation state but quite deck specific.
+  //   It is also closely tied to the layout mode state (which also seems quite deck specific).
+  //   The layout and navigation interfaces need to be revisited and cleaned up.
+  //   Doing this cleanup should also help simplify some of the convoluted logic for managing it.
+  const location = new LocalStorageStore<Capabilities.MutableLocation>(LOCATION_KEY, {
+    active: { sidebar: [{ id: NAV_ID }] },
+    closed: [],
+  });
+
+  location
+    .prop({ key: 'active', type: LocalStorageStore.json<LayoutParts>() })
+    .prop({ key: 'closed', type: LocalStorageStore.json<string[]>() });
+
+  return contributes(Capabilities.Location, location.values, () => location.close());
+};

package/src/capabilities/navigation/set-location.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { openIds, type Layout, type LayoutParts, type Capabilities } from '@dxos/app-framework';
+import { type AttentionManager } from '@dxos/plugin-attention';
+
+export type SetLocationOptions = {
+  next: LayoutParts;
+  location: Capabilities.MutableLocation;
+  layout: Layout;
+  attention?: AttentionManager;
+};
+
+export const setLocation = ({ next, location, layout, attention }: SetLocationOptions) => {
+  const part = layout.layoutMode === 'solo' ? 'solo' : 'main';
+  const ids = openIds(next, [part]);
+
+  const current = openIds(location.active, [part]);
+  const removed = current.filter((id) => !ids.includes(id));
+  const closed = Array.from(new Set([...location.closed.filter((id) => !ids.includes(id)), ...removed]));
+
+  location.closed = closed;
+  location.active = next;
+
+  if (attention) {
+    const attended = attention.current;
+    const [attendedId] = Array.from(attended);
+    const isAttendedAvailable = !!attendedId && ids.includes(attendedId);
+    if (!isAttendedAvailable) {
+      const currentIds = location.active[part]?.map(({ id }) => id) ?? [];
+      const attendedIndex = currentIds.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 >= ids.length ? ids.length - 1 : attendedIndex;
+      return next[part]?.[index].id;
+    }
+  }
+};

package/src/capabilities/navigation/tools.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  Capabilities,
+  contributes,
+  createIntent,
+  NavigationAction,
+  type PromiseIntentDispatcher,
+} from '@dxos/app-framework';
+import { defineTool, ToolResult } from '@dxos/artifact';
+import { S } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+
+// TODO(burdon): Factor out.
+declare global {
+  interface ToolContextExtensions {
+    dispatch?: PromiseIntentDispatcher;
+  }
+}
+
+export default () =>
+  contributes(Capabilities.Tools, [
+    defineTool({
+      name: 'show',
+      // TODO(ZaymonFC): We should update the prompt to teach the LLM the difference between object ids and fully qualified ids.
+      description:
+        'Show an item in the app. Use this tool to open an artifact. When supplying IDs to show, they must be fully qualified like space:object.',
+      // TODO(wittjosiah): Refactor Layout/Navigation/Deck actions so that they can be used directly.
+      schema: S.Struct({
+        id: S.String.annotations({
+          description: 'The ID of the item to show.',
+        }),
+        pivotId: S.optional(
+          S.String.annotations({
+            description: 'The ID of the chat. If provided, the item will be added after the pivot item.',
+          }),
+        ),
+      }),
+      execute: async ({ id, pivotId }, { extensions }) => {
+        invariant(extensions?.dispatch, 'No intent dispatcher');
+        const { data, error } = await extensions.dispatch(
+          createIntent(NavigationAction.AddToActive, {
+            id,
+            part: 'main',
+            pivotId,
+          }),
+        );
+        if (error) {
+          return ToolResult.Error(error.message);
+        }
+
+        return ToolResult.Success(data);
+      },
+    }),
+  ]);

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

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  Capabilities,
+  contributes,
+  createIntent,
+  LayoutAction,
+  type LayoutParts,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { scheduledEffect } from '@dxos/echo-signals/core';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+
+import { setLocation as naturalSetLocation } from './set-location';
+import { NAV_ID } from '../../components';
+import { mergeLayoutParts, removePart, soloPartToUri, uriToSoloPart } from '../../layout';
+
+export default async (context: PluginsContext) => {
+  const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher) ?? {};
+  const location = context.requestCapability(Capabilities.MutableLocation);
+  const layout = context.requestCapability(Capabilities.MutableLayout);
+  const attention = context.requestCapability(AttentionCapabilities.Attention);
+
+  const handleNavigation = async () => {
+    const setLocation = (next: LayoutParts) => naturalSetLocation({ next, layout, location, attention });
+
+    const pathname = window.location.pathname;
+    if (pathname === '/reset') {
+      setLocation({ sidebar: [{ id: NAV_ID }] });
+      location.closed = [];
+      layout.layoutMode = 'solo';
+      window.location.pathname = '/';
+      return;
+    }
+
+    const startingLayout = removePart(location.active, 'solo');
+    const layoutFromUri = uriToSoloPart(pathname);
+    if (!layoutFromUri) {
+      const toAttend = setLocation(startingLayout);
+      layout.layoutMode = 'deck';
+      await dispatch?.(createIntent(LayoutAction.ScrollIntoView, { id: toAttend }));
+      return;
+    }
+
+    const toAttend = setLocation(mergeLayoutParts(layoutFromUri, startingLayout));
+    layout.layoutMode = 'solo';
+    await dispatch?.(createIntent(LayoutAction.ScrollIntoView, { id: toAttend }));
+  };
+
+  await handleNavigation();
+  window.addEventListener('popstate', handleNavigation);
+
+  const unsubscribe = scheduledEffect(
+    () => ({ selectedPath: soloPartToUri(location.active) }),
+    ({ selectedPath }) => {
+      // TODO(thure): In some browsers, this only preserves the most recent state change, even though this is not `history.replace`…
+      history.pushState(null, '', `/${selectedPath}${window.location.search}`);
+    },
+  );
+
+  return contributes(Capabilities.Null, null, () => {
+    window.removeEventListener('popstate', handleNavigation);
+    unsubscribe();
+  });
+};

package/src/capabilities/settings/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const DeckSettings = lazy(() => import('./settings'));

package/src/capabilities/settings/react-surface.tsx

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+
+import { LayoutSettings } from '../../components';
+import { DECK_PLUGIN } from '../../meta';
+import { type DeckSettingsProps } from '../../types';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, {
+    id: DECK_PLUGIN,
+    role: 'settings',
+    filter: (data): data is any => data.subject === DECK_PLUGIN,
+    component: () => {
+      const store = useCapability(Capabilities.SettingsStore);
+      const settings = store.getStore<DeckSettingsProps>(DECK_PLUGIN)!.value;
+      return <LayoutSettings settings={settings} />;
+    },
+  });

package/src/capabilities/settings/settings.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes } from '@dxos/app-framework';
+import { create } from '@dxos/live-object';
+
+import { DECK_PLUGIN } from '../../meta';
+import { DeckSettingsSchema, type DeckSettingsProps } from '../../types';
+
+export default () => {
+  const settings = create<DeckSettingsProps>({
+    showHints: false,
+    customSlots: false,
+    flatDeck: false,
+    enableNativeRedirect: false,
+    newPlankPositioning: 'start',
+    overscroll: 'centering',
+  });
+
+  return contributes(Capabilities.Settings, { schema: DeckSettingsSchema, prefix: DECK_PLUGIN, value: settings });
+};

package/src/components/DeckContext.ts

@@ -4,10 +4,15 @@
 
 import { type Context, createContext, useContext } from 'react';
 
+import { type LayoutMode } from '@dxos/app-framework';
 import { raise } from '@dxos/debug';
 
 export type PlankSizing = Record<string, number>;
-export type DeckContextType = { plankSizing: PlankSizing };
+export type DeckContextType = {
+  plankSizing: PlankSizing;
+  currentUndoId: string | undefined;
+  layoutModeHistory: LayoutMode[];
+};
 
 export const DeckContext: Context<DeckContextType | null> = createContext<DeckContextType | null>(null);
 

package/src/components/DeckLayout/ActiveNode.tsx

@@ -21,7 +21,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={{ activeNode }} limit={1} />
+      <Surface role='document-title' data={{ subject: activeNode }} limit={1} />
     </div>
   );
 };

package/src/components/DeckLayout/Banner.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Surface } from '@dxos/app-framework';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import { CloseSidebarButton, ToggleSidebarButton } from './SidebarButton';
+
+export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'topbar' | 'sidebar' }>) => {
+  return (
+    <header
+      className={mx(
+        'flex items-stretch relative plb-1 pis-1 pie-2',
+        variant === 'topbar' &&
+          'fixed inset-inline-0 block-start-[env(safe-area-inset-top)] bs-[--rail-size] border-be border-separator',
+        classNames,
+      )}
+    >
+      {variant === 'sidebar' ? <CloseSidebarButton /> : <ToggleSidebarButton />}
+      <span className='self-center grow mis-1'>Composer</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>
+        </div>
+      )}
+      <span role='none' className='grow' />
+      <Surface role='header-end' limit={1} />
+      <Surface role='notch-start' limit={1} />
+    </header>
+  );
+};