@dxos/plugin-deck 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/containers/Deck/Banner.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { mx, osTranslations } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { CloseSidebarButton, ToggleSidebarButton } from '../Sidebar';
+
+export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'topbar' | 'sidebar' }>) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <header
+      className={mx(
+        'flex items-stretch relative py-1 ps-1 pe-2',
+        variant === 'topbar' &&
+          '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 ms-1'>{t('current-app.name', { ns: osTranslations })}</span>
+      {variant === 'topbar' && (
+        <div className='absolute inset-0 pointer-events-none'>
+          <div 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 className='grow' />
+      <Surface.Surface role='version-info' limit={1} />
+      <Surface.Surface role='notch-start' limit={1} />
+    </header>
+  );
+};

package/src/containers/Deck/Deck.stories.tsx

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback } from 'react';
+
+import { Capability, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { useAtomCapability, usePluginManager } from '@dxos/app-framework/ui';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+import { corePlugins } from '@dxos/plugin-testing';
+
+import { DeckSettings, DeckState } from '#capabilities';
+import { useDeckState } from '#hooks';
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+import { DeckCapabilities, getMode } from '#types';
+
+import { Deck } from './Deck';
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    activatesOn: AppActivationEvents.SetupSettings,
+    activate: DeckSettings,
+  }),
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  Plugin.make,
+);
+
+const DefaultStory = () => {
+  const settings = useAtomCapability(DeckCapabilities.Settings);
+  const pluginManager = usePluginManager();
+  const { state, deck, updateState } = useDeckState();
+  const layoutMode = getMode(deck);
+
+  const handleLayoutChange = useCallback(() => {
+    console.log('layout change');
+  }, []);
+
+  return (
+    <Deck.Root
+      settings={settings}
+      pluginManager={pluginManager}
+      layoutMode={layoutMode}
+      state={state}
+      deck={deck}
+      updateState={updateState}
+      onLayoutChange={handleLayoutChange}
+    >
+      <Deck.Content>
+        <Deck.Viewport>{deck.solo ? <Deck.SoloMode /> : <Deck.MultiMode />}</Deck.Viewport>
+      </Deck.Content>
+    </Deck.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-deck/containers/Deck',
+  component: DefaultStory,
+  decorators: [
+    withPluginManager({
+      plugins: [...corePlugins(), TestPlugin()],
+      setupEvents: [AppActivationEvents.SetupSettings],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/Deck/Deck.tsx

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { DeckContent, DeckContentProps } from './DeckContent';
+import { DeckRoot, DeckLayoutChangeRequest, DeckRootProps } from './DeckRoot';
+import { DeckViewport, DeckMultiMode, DeckSoloMode, DeckViewportProps, DeckContentEmpty } from './DeckViewport';
+
+/**
+ * Radix-style composite Deck component.
+ */
+export const Deck = {
+  Root: DeckRoot,
+  Content: DeckContent,
+  Viewport: DeckViewport,
+  ContentEmpty: DeckContentEmpty,
+  MultiMode: DeckMultiMode,
+  SoloMode: DeckSoloMode,
+};
+
+export type { DeckLayoutChangeRequest, DeckRootProps, DeckContentProps, DeckViewportProps };

package/src/containers/Deck/DeckContent.tsx

@@ -0,0 +1,102 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type PropsWithChildren, useCallback, useEffect, useRef } from 'react';
+
+import { AttentionCapabilities } from '@dxos/plugin-attention';
+import { Main, useMediaQuery } from '@dxos/react-ui';
+
+import { useBreakpoints } from '#hooks';
+
+import { layoutAppliesTopbar } from '../../util';
+import { ComplementarySidebar, Sidebar } from '../Sidebar';
+import { Banner } from './Banner';
+import { useDeckContext } from './DeckRoot';
+
+const DECK_CONTENT_NAME = 'DeckContent';
+
+export type DeckContentProps = PropsWithChildren;
+
+export const DeckContent = ({ children }: DeckContentProps) => {
+  const {
+    state: { sidebarState, complementarySidebarState, complementarySidebarPanel },
+    deck: { active, fullscreen, solo },
+    updateState,
+    layoutMode,
+    settings,
+    pluginManager,
+    onLayoutChange,
+  } = useDeckContext(DECK_CONTENT_NAME);
+  const breakpoint = useBreakpoints();
+  const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
+
+  // Ensure the first plank is attended when the deck is first rendered.
+  useEffect(() => {
+    // NOTE: Not `useAttended` so that the layout component is not re-rendered when the attended list changes.
+    const attention = pluginManager.capabilities.get(AttentionCapabilities.Attention);
+    const attended = attention.getCurrent();
+    const firstId = solo ?? active[0];
+    if (attended.length === 0 && firstId) {
+      // TODO(wittjosiah): Focusing the type button is a workaround.
+      //   If the plank is directly focused on first load the focus ring appears.
+      document.querySelector<HTMLElement>(`article[data-attendable-id="${firstId}"] button`)?.focus();
+    }
+  }, []);
+
+  // Not using `breakpoint` to avoid firing when breakpoint changes between tablet and desktop.
+  // `ssr: false` to avoid using fallback values and flashing into solo mode on startup.
+  const [isNotMobile] = useMediaQuery('md');
+  const shouldRevert = useRef(false);
+  useEffect(() => {
+    if (!isNotMobile && layoutMode === 'multi') {
+      // NOTE: Not `useAttended` so that the layout component is not re-rendered when the attended list changes.
+      const attention = pluginManager.capabilities.get(AttentionCapabilities.Attention);
+      const attended = attention.getCurrent();
+      shouldRevert.current = true;
+      onLayoutChange({ subject: attended[0], mode: 'solo' });
+    } else if (isNotMobile && layoutMode === 'solo' && shouldRevert.current) {
+      onLayoutChange({ revert: true });
+    }
+    // NOTE: Using `layoutMode` instead of `deck` to avoid infinite loops caused by object reference changes.
+  }, [isNotMobile, layoutMode, onLayoutChange]);
+
+  // When deck is disabled in settings, set to solo mode if the current layout mode is deck.
+  // TODO(thure): Applying this as an effect should be avoided over emitting the operation only when the setting changes.
+  useEffect(() => {
+    if (!settings?.enableDeck && layoutMode === 'multi') {
+      onLayoutChange({ subject: active[0], mode: 'solo' });
+    }
+  }, [settings?.enableDeck, onLayoutChange, active, layoutMode]);
+
+  const handleNavigationSidebarStateChange = useCallback(
+    (next: typeof sidebarState) => {
+      updateState((s) => ({ ...s, sidebarState: next }));
+    },
+    [updateState],
+  );
+
+  const handleComplementarySidebarStateChange = useCallback(
+    (next: typeof complementarySidebarState) => {
+      updateState((s) => ({ ...s, complementarySidebarState: next }));
+    },
+    [updateState],
+  );
+
+  return (
+    <Main.Root
+      navigationSidebarState={fullscreen ? 'closed' : sidebarState}
+      complementarySidebarState={fullscreen ? 'closed' : complementarySidebarState}
+      onNavigationSidebarStateChange={handleNavigationSidebarStateChange}
+      onComplementarySidebarStateChange={handleComplementarySidebarStateChange}
+    >
+      <Sidebar />
+      <ComplementarySidebar current={complementarySidebarPanel} />
+      <Main.Overlay />
+      {children}
+      {topbar && <Banner variant='topbar' />}
+    </Main.Root>
+  );
+};
+
+DeckContent.displayName = DECK_CONTENT_NAME;

package/src/containers/Deck/DeckRoot.tsx

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { PropsWithChildren } from 'react';
+
+import { type PluginManager } from '@dxos/app-framework';
+
+import { type LayoutMode, type Settings } from '#types';
+
+import { type DeckStateHook } from '../../hooks/useDeckState';
+
+const DECK_NAME = 'Deck';
+const DECK_ROOT_NAME = 'DeckRoot';
+
+/** Request to change the layout mode. */
+export type DeckLayoutChangeRequest = { subject?: string; mode: LayoutMode } | { revert: true };
+
+//
+// Context
+//
+
+export type DeckContextValue = {
+  /** Deck plugin settings. */
+  settings?: Settings.Settings;
+  /** Plugin manager for capability access. */
+  pluginManager: PluginManager.PluginManager;
+  /** Layout mode. */
+  layoutMode: LayoutMode;
+  /** Callback for layout mode changes. */
+  onLayoutChange: (request: DeckLayoutChangeRequest) => void;
+} & Pick<DeckStateHook, 'state' | 'deck' | 'updateState'>;
+
+export const [DeckProvider, useDeckContext] = createContext<DeckContextValue>(DECK_NAME);
+
+//
+// Root
+//
+
+export type DeckRootProps = PropsWithChildren<DeckContextValue>;
+
+/**
+ * Headless root that provides Deck context.
+ */
+export const DeckRoot = ({ children, ...context }: DeckRootProps) => {
+  return <DeckProvider {...context}>{children}</DeckProvider>;
+};
+
+DeckRoot.displayName = DECK_ROOT_NAME;