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

package/src/operations/update-complementary.ts

@@ -0,0 +1,33 @@
+//
+// 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.UpdateComplementary> =
+  LayoutOperation.UpdateComplementary.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* (input) {
+        const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+        const panelChanged = state.complementarySidebarPanel !== input.subject;
+        const next = input.subject ? 'expanded' : (input.state ?? state.complementarySidebarState);
+        const stateChanged = next !== state.complementarySidebarState;
+
+        if (panelChanged || stateChanged) {
+          yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => ({
+            ...state,
+            complementarySidebarPanel: panelChanged ? input.subject : state.complementarySidebarPanel,
+            complementarySidebarState: stateChanged ? next : state.complementarySidebarState,
+          }));
+        }
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/update-dialog.ts

@@ -0,0 +1,34 @@
+//
+// 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.UpdateDialog> = LayoutOperation.UpdateDialog.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        dialogOpen: input.state ?? Boolean(input.subject),
+        dialogType: input.type ?? 'default',
+        dialogBlockAlign: input.blockAlign ?? 'center',
+        dialogOverlayClasses: input.overlayClasses,
+        dialogOverlayStyle: input.overlayStyle,
+        dialogContent: input.subject
+          ? {
+              component: input.subject,
+              props: input.props,
+            }
+          : null,
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-plank-size.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
+
+import { UpdatePlankSize } from './definitions';
+import { updateActiveDeck } from './helpers';
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof UpdatePlankSize> = UpdatePlankSize.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+        updateActiveDeck(state, {
+          plankSizing: {
+            ...state.decks[state.activeDeck]?.plankSizing,
+            [input.id]: input.size,
+          },
+        }),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-popover.ts

@@ -0,0 +1,36 @@
+//
+// 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.UpdatePopover> = LayoutOperation.UpdatePopover.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        popoverOpen: input.state ?? Boolean(input.subject),
+        popoverKind: input.kind ?? 'base',
+        popoverTitle: input.kind === 'card' ? input.title : undefined,
+        popoverContentRef: input.subjectRef,
+        popoverContent:
+          typeof input.subject === 'string'
+            ? { component: input.subject, props: input.props }
+            : input.subject
+              ? { subject: input.subject }
+              : null,
+        popoverSide: input.side,
+        popoverAnchor: input.variant === 'virtual' ? input.anchor : state.popoverAnchor,
+        popoverAnchorId: input.variant !== 'virtual' ? input.anchorId : state.popoverAnchorId,
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-sidebar.ts

@@ -0,0 +1,28 @@
+//
+// 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.UpdateSidebar> = LayoutOperation.UpdateSidebar.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+      const next = input.state ?? state.sidebarState;
+      if (next !== state.sidebarState) {
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => ({
+          ...state,
+          sidebarState: next,
+        }));
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/testing/DeckLayoutStoryNavigation.tsx

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { forwardRef, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph, useLayout } from '@dxos/app-toolkit/ui';
+import { Graph, Node } from '@dxos/plugin-graph';
+import { Icon, List, ListItem } from '@dxos/react-ui';
+
+export type DeckLayoutStoryNavigationProps = {
+  current?: string;
+};
+
+/**
+ * Minimal test-only navigation list for DeckLayout stories.
+ * Renders root graph children and opens them via LayoutOperation.Open on click.
+ */
+export const DeckLayoutStoryNavigation = forwardRef<HTMLDivElement, DeckLayoutStoryNavigationProps>(
+  (_props, forwardedRef) => {
+    const { graph } = useAppGraph();
+    const layout = useLayout();
+    const { invokePromise } = useOperationInvoker();
+
+    const items = useMemo(
+      () => Graph.getConnections(graph, Node.RootId, 'child').filter((node) => !Node.isActionLike(node)),
+      [graph],
+    );
+
+    const activeSet = useMemo(() => new Set(layout.active), [layout.active]);
+
+    return (
+      <div ref={forwardedRef} className='overflow-y-auto p-2'>
+        <List>
+          {items.map((node) => (
+            <ListItem.Root
+              key={node.id}
+              classNames={activeSet.has(node.id) ? 'bg-active-surface' : undefined}
+              onClick={() => void invokePromise(LayoutOperation.Open, { subject: [node.id] })}
+            >
+              {node.properties.icon && (
+                <ListItem.Endcap>
+                  <Icon icon={node.properties.icon} size={4} />
+                </ListItem.Endcap>
+              )}
+              <ListItem.Heading>
+                {typeof node.properties.label === 'string' ? node.properties.label : node.id}
+              </ListItem.Heading>
+            </ListItem.Root>
+          ))}
+        </List>
+      </div>
+    );
+  },
+);

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { DeckLayoutStoryNavigation } from './DeckLayoutStoryNavigation';

package/src/translations.ts

@@ -4,66 +4,79 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Deck',
-        'settings title': 'Deck settings',
-        'main header label': 'Main header',
-        'open navigation sidebar label': 'Open sidebar',
-        'collapse navigation sidebar label': 'Minimize sidebar',
-        'open complementary sidebar label': 'Open context sidebar',
-        'close complementary sidebar label': 'Minimize context sidebar',
-        'sidebar title': 'Navigation sidebar',
-        'complementary sidebar title': 'Context sidebar',
-        'plugin error message': 'Content failed to render.',
-        'content fallback message': 'Unsupported',
-        'content fallback description':
+        'plugin.name': 'Deck',
+        'settings.title': 'Deck settings',
+        'main-header.label': 'Main header',
+        'open-navigation-sidebar.label': 'Open sidebar',
+        'collapse-navigation-sidebar.label': 'Minimize sidebar',
+        'open-complementary-sidebar.label': 'Open context sidebar',
+        'close-complementary-sidebar.label': 'Minimize context sidebar',
+        'sidebar.title': 'Navigation sidebar',
+        'complementary-sidebar.title': 'Context sidebar',
+        'plugin-error.message': 'Content failed to render.',
+        'content-fallback.message': 'Unsupported',
+        'content-fallback.description':
           'No plugin had a response for the address you navigated to. Double-check the URL, and ensure you’ve enabled a plugin that supports the object.',
-        'toggle fullscreen label': 'Toggle fullscreen',
-        'settings show hints label': 'Show hints',
-        'settings native redirect label': 'Enable native url redirect (experimental)',
-        'settings new plank position start label': 'Start',
-        'settings new plank position end label': 'End',
-        'select new plank positioning placeholder': 'Select new plank positioning',
-        'select new plank positioning label': 'New plank positioning',
-        'undo available label': 'Click to undo previous action.',
-        'undo action label': 'Undo',
-        'undo action alt': 'Undo previous action',
-        'undo close label': 'Dismiss',
-        'error fallback message': 'Unable to open this object',
-        'plank heading fallback label': 'Untitled',
-        'actions menu label': 'Options',
-        'settings deck label': 'Disable deck',
-        'pending heading': 'Loading…',
-        'insert plank label': 'Open',
-        'resize label': 'Drag to resize',
-        'pin start label': 'Pin to the left sidebar',
-        'pin end label': 'Pin to the right sidebar',
-        'increment start label': 'Move to the left',
-        'increment end label': 'Move to the right',
-        'show deck plank label': 'Return to deck',
-        'show solo plank label': 'Maximize',
-        'exit fullscreen label': 'Exit fullscreen',
-        'show fullscreen plank label': 'Fullscreen',
-        'close label': 'Close',
-        'minify label': 'Minify',
-        'open companion label': 'Open companion',
-        'close companion label': 'Close companion',
-        'settings overscroll label': 'Plank scrolling',
-        'select overscroll placeholder': 'Select plank scrolling behavior',
-        'settings overscroll centering label': 'Centering',
-        'settings overscroll none label': 'None',
-        'settings enable statusbar label': 'Show status bar',
-        'settings enable deck label': 'Enable Deck',
-        'settings encapsulated planks label': 'Encapsulated planks',
-        'close current label': 'Close current plank',
-        'close others label': 'Close other planks',
-        'close all label': 'Close all planks',
-        'companion plank heading fallback label': 'Related',
+        'toggle-fullscreen.label': 'Toggle fullscreen',
+        'settings.show-hints.label': 'Show hints',
+        'settings.show-hints.description': 'Show helpful tips and keyboard shortcut hints in the interface.',
+        'settings.native-redirect.label': 'Enable native url redirect',
+        'settings.native-redirect.description': 'Redirect supported URLs to the native desktop application.',
+        'settings.new-plank-position.start.label': 'Start',
+        'settings.new-plank-position.end.label': 'End',
+        'select-new-plank-positioning.placeholder': 'Select new plank positioning',
+        'select-new-plank-positioning.label': 'New plank positioning',
+        'select-new-plank-positioning.description':
+          'Choose whether newly opened planks appear at the start or end of the deck.',
+        'undo-available.label': 'Click to undo previous action.',
+        'undo-action.label': 'Undo',
+        'undo-action.alt': 'Undo previous action',
+        'undo-close.label': 'Dismiss',
+        'error-fallback.message': 'Unable to open this object',
+        'plank-heading-fallback.label': 'Untitled',
+        'actions-menu.label': 'Options',
+        'settings.deck.label': 'Disable deck',
+        'pending.heading': 'Loading…',
+        'insert-plank.label': 'Open',
+        'resize.label': 'Drag to resize',
+        'pin-start.label': 'Pin to the left sidebar',
+        'pin-end.label': 'Pin to the right sidebar',
+        'increment-start.label': 'Move to the left',
+        'increment-end.label': 'Move to the right',
+        'show-deck-plank.label': 'Return to deck',
+        'show-solo-plank.label': 'Maximize',
+        'exit-fullscreen.label': 'Exit fullscreen',
+        'show-fullscreen-plank.label': 'Fullscreen',
+        'close.label': 'Close',
+        'minify.label': 'Minify',
+        'open-companion.label': 'Open companion',
+        'close-companion.label': 'Close companion',
+        'settings.overscroll.label': 'Plank scrolling',
+        'settings.overscroll.description': 'Control how planks behave when scrolled to the edge of the deck.',
+        'select-overscroll.placeholder': 'Select plank scrolling behavior',
+        'settings.overscroll.centering.label': 'Centering',
+        'settings.overscroll.none.label': 'None',
+        'settings.enable-statusbar.label': 'Show status bar',
+        'settings.enable-statusbar.description': 'Display a status bar at the bottom of the application.',
+        'settings.enable-deck.label': 'Enable Deck',
+        'settings.enable-deck.description': 'Display multiple panels side by side instead of one at a time.',
+        'settings.encapsulated-planks.label': 'Encapsulated planks',
+        'settings.encapsulated-planks.description': 'Render each plank inside its own isolated container.',
+        'close-current.label': 'Close current plank',
+        'close-others.label': 'Close other planks',
+        'close-all.label': 'Close all planks',
+        'close-navigation-sidebar.button': 'Close',
+        'companion-plank-heading-fallback.label': 'Related',
+        'settings.new-plank-position-start.label': 'Start',
+        'settings.new-plank-position-end.label': 'End',
+        'settings.overscroll-centering.label': 'Centering',
+        'settings.overscroll-none.label': 'None',
       },
     },
   },

package/src/types/Settings.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+// TODO(Zan): In the future we should consider adding new planks adjacent to the attended plank.
+export const NewPlankPositions = ['start', 'end'] as const;
+export type NewPlankPositioning = (typeof NewPlankPositions)[number];
+
+export const OverScrollToProps = ['none', 'centering'] as const;
+export type Overscroll = (typeof OverScrollToProps)[number];
+
+export const Settings = Schema.Struct({
+  showHints: Schema.optional(Schema.Boolean),
+  enableDeck: Schema.optional(Schema.Boolean),
+  enableStatusbar: Schema.optional(Schema.Boolean),
+  enableNativeRedirect: Schema.optional(Schema.Boolean),
+  newPlankPositioning: Schema.optional(Schema.Literal(...NewPlankPositions)),
+  overscroll: Schema.optional(Schema.Literal(...OverScrollToProps)),
+  // TODO(burdon): Rename layoutMode? (e.g., bento | encapsulated?)
+  encapsulatedPlanks: Schema.optional(Schema.Boolean),
+}).pipe(Schema.mutable);
+export type Settings = Schema.Schema.Type<typeof Settings>;

package/src/types/capabilities.ts

@@ -5,27 +5,28 @@
 import { type Atom } from '@effect-atom/atom-react';
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common } from '@dxos/app-framework';
+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';
+import { meta } from '#meta';
+import * as Settings from './Settings';
+import { type EphemeralDeckState, type DeckState, type StoredDeckState } from './schema';
 
 export namespace DeckCapabilities {
-  export const Settings = Capability.make<Atom.Writable<DeckSettingsProps>>(`${meta.id}/capability/settings`);
+  export const Settings = Capability.make<Atom.Writable<Settings.Settings>>(`${meta.id}.capability.settings`);
 
   /** Persisted state (stored in KVS/localStorage). */
-  export const State = Capability.make<Atom.Writable<DeckStateProps>>(`${meta.id}/capability/state`);
+  export const State = Capability.make<Atom.Writable<StoredDeckState>>(`${meta.id}.capability.state`);
 
   /** Transient/ephemeral state (not persisted). */
-  export const EphemeralState = Capability.make<Atom.Writable<DeckEphemeralStateProps>>(
-    `${meta.id}/capability/ephemeral-state`,
+  export const EphemeralState = Capability.make<Atom.Writable<EphemeralDeckState>>(
+    `${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* Common.Capability.getAtomValue(State);
+      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

@@ -2,19 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type ActivationEvent, Common } from '@dxos/app-framework';
+import { type ActivationEvent } from '@dxos/app-framework';
+import { AppActivationEvents } from '@dxos/app-toolkit';
 
-import { meta } from '../meta';
+import { meta } from '#meta';
 
 import { DeckCapabilities } from './capabilities';
 
 export namespace DeckEvents {
-  export const StateReady: ActivationEvent.ActivationEvent = Common.ActivationEvent.createStateEvent(
-    `${meta.id}/state-ready`,
+  export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(
+    `${meta.id}.state-ready`,
   );
 
   /** Fired when DeckSettings capability is ready. */
-  export const SettingsReady: ActivationEvent.ActivationEvent = Common.ActivationEvent.createSettingsEvent(
+  export const SettingsReady: ActivationEvent.ActivationEvent = AppActivationEvents.createSettingsEvent(
     DeckCapabilities.Settings.identifier,
   );
 }

package/src/types/index.ts

@@ -5,3 +5,4 @@
 export * from './capabilities';
 export * from './events';
 export * from './schema';
+export * as Settings from './Settings';