@dxos/plugin-deck 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/src/components/fragments.ts

@@ -2,13 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
+// TODO(burdon): Move to these as dx-components?
+
+/** @private */
 export const soloInlinePadding =
-  'pis-[calc(env(safe-area-inset-left)+.25rem)] pie-[calc(env(safe-area-inset-left)+.25rem)]';
+  'ps-[calc(env(safe-area-inset-left)+.25rem)] pe-[calc(env(safe-area-inset-right)+.25rem)]';
 
-const sidebarToggleStyles = 'bs-[--rail-item] is-[--rail-item] absolute block-end-2 z-[1] !bg-deckSurface lg:hidden';
+const sidebarToggleStyles = 'h-(--dx-rail-item) w-(--dx-rail-item) absolute bottom-2 z-[1] !bg-deck-surface lg:hidden';
 
-export const fixedSidebarToggleStyles = mx(sidebarToggleStyles, 'inline-start-2');
+/** @private */
+export const fixedSidebarToggleStyles = mx(sidebarToggleStyles, 'left-2');
 
-export const fixedComplementarySidebarToggleStyles = mx(sidebarToggleStyles, 'inline-end-2');
+/** @private */
+export const fixedComplementarySidebarToggleStyles = mx(sidebarToggleStyles, 'right-2');

package/src/components/index.ts

@@ -3,4 +3,3 @@
 //
 
 export * from './DeckLayout';
-export * from './DeckSettings';

package/src/containers/Banner/Banner.tsx

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { Banner } from '../../components';

package/src/containers/Banner/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Banner } from './Banner';
+
+export default Banner;

package/src/containers/DeckSettings/DeckSettings.tsx

@@ -0,0 +1,113 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { Input, Select, useTranslation } from '@dxos/react-ui';
+import { Settings } from '@dxos/react-ui-form';
+
+import { meta } from '../../meta';
+import {
+  type DeckSettingsProps,
+  type NewPlankPositioning,
+  NewPlankPositions,
+  OverScrollToProps,
+  type Overscroll,
+} from '../../types';
+
+const isSocket = !!(globalThis as any).__args;
+
+export type DeckSettingsComponentProps = {
+  settings: DeckSettingsProps;
+  onSettingsChange: (fn: (current: DeckSettingsProps) => DeckSettingsProps) => void;
+};
+
+export const DeckSettings = ({ settings, onSettingsChange }: DeckSettingsComponentProps) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <Settings.Root>
+      <Settings.Section title={t('settings title', { ns: meta.id })}>
+        <Settings.Group>
+          <Settings.ItemInput title={t('settings enable deck label')}>
+            <Input.Switch
+              checked={settings.enableDeck}
+              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, enableDeck: checked }))}
+            />
+          </Settings.ItemInput>
+          <Settings.ItemInput title={t('settings encapsulated planks label')}>
+            <Input.Switch
+              checked={settings.encapsulatedPlanks ?? false}
+              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, encapsulatedPlanks: checked }))}
+            />
+          </Settings.ItemInput>
+          <Settings.ItemInput title={t('select new plank positioning label')}>
+            <Select.Root
+              disabled={!settings.enableDeck}
+              value={settings.newPlankPositioning ?? 'start'}
+              onValueChange={(value) =>
+                onSettingsChange((s) => ({ ...s, newPlankPositioning: value as NewPlankPositioning }))
+              }
+            >
+              <Select.TriggerButton placeholder={t('select new plank positioning placeholder')} />
+              <Select.Portal>
+                <Select.Content>
+                  <Select.Viewport>
+                    {NewPlankPositions.map((position) => (
+                      <Select.Option key={position} value={position}>
+                        {t(`settings new plank position ${position} label`)}
+                      </Select.Option>
+                    ))}
+                  </Select.Viewport>
+                  <Select.Arrow />
+                </Select.Content>
+              </Select.Portal>
+            </Select.Root>
+          </Settings.ItemInput>
+          <Settings.ItemInput title={t('settings overscroll label')}>
+            <Select.Root
+              disabled={!settings.enableDeck}
+              value={settings.overscroll ?? 'none'}
+              onValueChange={(value) => onSettingsChange((s) => ({ ...s, overscroll: value as Overscroll }))}
+            >
+              <Select.TriggerButton placeholder={t('select overscroll placeholder')} />
+              <Select.Portal>
+                <Select.Content>
+                  <Select.Viewport>
+                    {OverScrollToProps.map((option) => (
+                      <Select.Option key={option} value={option}>
+                        {t(`settings overscroll ${option} label`)}
+                      </Select.Option>
+                    ))}
+                  </Select.Viewport>
+                  <Select.Arrow />
+                </Select.Content>
+              </Select.Portal>
+            </Select.Root>
+          </Settings.ItemInput>
+          <Settings.ItemInput title={t('settings enable statusbar label')}>
+            <Input.Switch
+              checked={settings.enableStatusbar}
+              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, enableStatusbar: checked }))}
+            />
+          </Settings.ItemInput>
+          <Settings.ItemInput title={t('settings show hints label')}>
+            <Input.Switch
+              checked={settings.showHints}
+              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, showHints: checked }))}
+            />
+          </Settings.ItemInput>
+          {!isSocket && (
+            <Settings.ItemInput title={t('settings native redirect label')}>
+              <Input.Switch
+                checked={settings.enableNativeRedirect}
+                onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, enableNativeRedirect: checked }))}
+              />
+            </Settings.ItemInput>
+          )}
+        </Settings.Group>
+      </Settings.Section>
+    </Settings.Root>
+  );
+};

package/src/containers/DeckSettings/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { DeckSettings } from './DeckSettings';
+
+export default DeckSettings;

package/src/containers/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const Banner: ComponentType<any> = lazy(() => import('./Banner'));
+export const DeckSettings: ComponentType<any> = lazy(() => import('./DeckSettings'));

package/src/hooks/index.ts

@@ -5,6 +5,8 @@
 export * from './useBreakpoints';
 export * from './useCompanions';
 export * from './useDeckCompanions';
+export * from './useDeckState';
 export * from './useHoistStatusbar';
 export * from './useMainSize';
 export * from './useNodeActionExpander';
+export * from './useSelectedCompanion';

package/src/hooks/useCompanions.ts

@@ -4,7 +4,7 @@
 
 import { useMemo } from 'react';
 
-import { useAppGraph } from '@dxos/app-framework';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { useConnections } from '@dxos/plugin-graph';
 import { byPosition } from '@dxos/util';
 
@@ -12,7 +12,7 @@ import { PLANK_COMPANION_TYPE } from '../types';
 
 export const useCompanions = (id?: string) => {
   const { graph } = useAppGraph();
-  const nodes = useConnections(graph, id);
+  const nodes = useConnections(graph, id, 'child');
   const companions = nodes.filter((node) => node.type === PLANK_COMPANION_TYPE);
   return useMemo(() => companions.toSorted((a, b) => byPosition(a.properties, b.properties)), [companions]);
 };

package/src/hooks/useDeckCompanions.ts

@@ -2,8 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Label, useAppGraph } from '@dxos/app-framework';
-import { type Node, ROOT_ID, useConnections } from '@dxos/plugin-graph';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Node, type Node as NodeType } from '@dxos/plugin-graph';
+import { useConnections } from '@dxos/plugin-graph';
+import { type Label } from '@dxos/ui-types';
 import { type Position, byPosition } from '@dxos/util';
 
 import { ATTENDABLE_PATH_SEPARATOR, DECK_COMPANION_TYPE } from '../types';
@@ -13,7 +15,7 @@ export const getCompanionId = (id: string) => {
   return companionId ?? 'never';
 };
 
-export type DeckCompanion = Node<
+export type DeckCompanion = NodeType.Node<
   any,
   {
     label: Label;
@@ -27,7 +29,7 @@ export type DeckCompanion = Node<
 
 export const useDeckCompanions = (): DeckCompanion[] => {
   const { graph } = useAppGraph();
-  const connections = useConnections(graph, ROOT_ID);
+  const connections = useConnections(graph, Node.RootId, 'child');
   const companions = connections.filter((node) => node.type === DECK_COMPANION_TYPE) as DeckCompanion[];
   return companions.toSorted((a, b) => byPosition(a.properties, b.properties));
 };

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,15 @@
 
 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 enableStatusbar = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(meta.id)!.value
-    .enableStatusbar;
   const { safeAreaPadding } = useThemeContext();
+  const enableStatusbar = useAtomCapability(DeckCapabilities.Settings).enableStatusbar;
+
   return useMemo(() => {
     return (
       breakpoint === 'desktop' &&

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',
@@ -59,10 +59,12 @@ export const translations = [
         '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',
+        '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';