@dxos/plugin-deck 0.8.4-main.1068cf700f → 0.8.4-main.1c7ec43d41

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

@@ -1,96 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-
-import { Capabilities, Capability } from '@dxos/app-framework';
-import { LayoutOperation } from '@dxos/app-toolkit';
-import { invariant } from '@dxos/invariant';
-
-import { DeckCapabilities, type DeckStateProps, defaultDeck } from '../../types';
-
-// TODO(wittjosiah): Cleanup the url handling. May justify introducing routing capabilities.
-export default Capability.makeModule(
-  Effect.fnUntraced(function* () {
-    const { invokeSync } = 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 = () => {
-      const pathname = window.location.pathname;
-      const state = getState();
-      if (pathname === '/reset') {
-        updateState((s) => ({
-          ...s,
-          activeDeck: 'default',
-          decks: {
-            default: { ...defaultDeck },
-          },
-        }));
-        window.location.pathname = '/';
-        return;
-      }
-
-      const [_, nextDeck, nextSolo] = pathname.split('/');
-      if (nextDeck && nextDeck !== state.activeDeck) {
-        invokeSync(LayoutOperation.SwitchWorkspace, { subject: nextDeck });
-      }
-
-      const deck = getDeck();
-      if (nextSolo && nextSolo !== deck.solo) {
-        invokeSync(LayoutOperation.SetLayoutMode, { subject: nextSolo, mode: 'solo' });
-      } else if (!nextSolo && deck.solo) {
-        invokeSync(LayoutOperation.SetLayoutMode, { mode: 'deck' });
-      }
-    };
-
-    yield* Effect.sync(() => 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 ? `/${activeDeck}/${solo}` : `/${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/ContentEmpty.tsx

@@ -1,30 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React from 'react';
-
-import { Surface } from '@dxos/app-framework/ui';
-
-import { useBreakpoints, useDeckState } from '../../hooks';
-import { getMode } from '../../types';
-import { layoutAppliesTopbar } from '../../util';
-import { fixedSidebarToggleStyles } from '../fragments';
-import { ToggleSidebarButton } from '../Sidebar';
-
-export const ContentEmpty = () => {
-  const breakpoint = useBreakpoints();
-  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'
-      data-testid='layoutPlugin.firstRunMessage'
-    >
-      <Surface.Surface role='keyshortcuts' />
-      {!topbar && <ToggleSidebarButton variant='default' classNames={fixedSidebarToggleStyles} />}
-    </div>
-  );
-};

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

@@ -1,52 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React from 'react';
-
-import { Capability, Plugin } from '@dxos/app-framework';
-import { withPluginManager } from '@dxos/app-framework/testing';
-import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
-import { corePlugins } from '@dxos/plugin-testing';
-import { withTheme } from '@dxos/react-ui/testing';
-
-import { DeckState, LayoutOperationResolver } 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.addOperationResolverModule({
-    activate: LayoutOperationResolver,
-  }),
-  Plugin.make,
-);
-
-const meta = {
-  title: 'plugins/plugin-deck/DeckLayout',
-  component: DeckLayout,
-  render: (args) => <DeckLayout {...args} />,
-  decorators: [
-    withTheme(),
-    withPluginManager({
-      plugins: [...corePlugins(), TestPlugin()],
-    }),
-  ],
-  parameters: {
-    layout: 'fullscreen',
-    translations,
-  },
-} satisfies Meta<typeof DeckLayout>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {};

package/src/components/DeckLayout/DeckLayout.tsx

@@ -1,34 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React from 'react';
-
-import { Mosaic } from '@dxos/react-ui-mosaic';
-
-import { useDeckState } from '../../hooks';
-
-import { ActiveNode } from './ActiveNode';
-import { DeckMain } from './DeckMain';
-import { Dialog } from './Dialog';
-import { PopoverContent, PopoverRoot } from './Popover';
-import { Toaster, type ToasterProps } from './Toast';
-
-export type DeckLayoutProps = Pick<ToasterProps, 'onDismissToast'>;
-
-export const DeckLayout = ({ onDismissToast }: DeckLayoutProps) => {
-  const { state } = useDeckState();
-  const { toasts } = state;
-
-  return (
-    <Mosaic.Root>
-      <PopoverRoot>
-        <ActiveNode />
-        <DeckMain />
-        <PopoverContent />
-        <Dialog />
-        <Toaster toasts={toasts} onDismissToast={onDismissToast} />
-      </PopoverRoot>
-    </Mosaic.Root>
-  );
-};

package/src/components/DeckLayout/DeckMain.tsx

@@ -1,286 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React, { Fragment, type UIEvent, useCallback, useEffect, useMemo, useRef } from 'react';
-
-import { useAtomCapability, useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
-import { LayoutOperation } from '@dxos/app-toolkit';
-import { AttentionCapabilities } from '@dxos/plugin-attention';
-import { Main, type MainContentProps, useMediaQuery, useOnTransition } from '@dxos/react-ui';
-import { DEFAULT_HORIZONTAL_SIZE, Stack, StackContext } from '@dxos/react-ui-stack';
-import { mainPaddingTransitions, mx } from '@dxos/ui-theme';
-
-import { useBreakpoints, useDeckState, useHoistStatusbar } from '../../hooks';
-import { DeckCapabilities, getMode } from '../../types';
-import { calculateOverscroll, layoutAppliesTopbar } from '../../util';
-import { fixedComplementarySidebarToggleStyles, fixedSidebarToggleStyles } from '../fragments';
-import { Plank } from '../Plank';
-import { ComplementarySidebar, Sidebar, ToggleComplementarySidebarButton, ToggleSidebarButton } from '../Sidebar';
-
-import { ContentEmpty } from './ContentEmpty';
-import { StatusBar } from './StatusBar';
-import { Topbar } from './Topbar';
-
-export const DeckMain = () => {
-  const { invokeSync } = useOperationInvoker();
-  const settings = useAtomCapability(DeckCapabilities.Settings);
-  const { state, deck, updateState } = useDeckState();
-  const { sidebarState, complementarySidebarState, complementarySidebarPanel } = state;
-  const { active, activeCompanions, fullscreen, solo, plankSizing } = deck;
-  const layoutMode = getMode(deck);
-  const breakpoint = useBreakpoints();
-  const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
-  const hoistStatusbar = useHoistStatusbar(breakpoint, layoutMode);
-  const pluginManager = usePluginManager();
-
-  const scrollLeftRef = useRef<number>(null);
-  const deckRef = useRef<HTMLDivElement>(null);
-
-  // 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 === 'deck') {
-      // 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;
-      invokeSync(LayoutOperation.SetLayoutMode, { subject: attended[0], mode: 'solo' });
-    } else if (isNotMobile && layoutMode === 'solo' && shouldRevert.current) {
-      invokeSync(LayoutOperation.SetLayoutMode, { revert: true });
-    }
-    // NOTE: Using `layoutMode` instead of `deck` to avoid infinite loops caused by object reference changes.
-  }, [isNotMobile, layoutMode, invokeSync]);
-
-  // 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 === 'deck') {
-      invokeSync(LayoutOperation.SetLayoutMode, { subject: active[0], mode: 'solo' });
-    }
-  }, [settings?.enableDeck, invokeSync, active, layoutMode]);
-
-  /**
-   * Clear scroll restoration state if the window is resized.
-   */
-  const handleResize = useCallback(() => {
-    scrollLeftRef.current = null;
-  }, []);
-
-  useEffect(() => {
-    window.addEventListener('resize', handleResize);
-    return () => window.removeEventListener('resize', handleResize);
-  }, [handleResize]);
-
-  const restoreScroll = useCallback(() => {
-    if (deckRef.current && scrollLeftRef.current != null) {
-      deckRef.current.scrollLeft = scrollLeftRef.current;
-    }
-  }, []);
-  useOnTransition(layoutMode, (mode) => mode !== 'deck', 'deck', restoreScroll);
-
-  /**
-   * Save scroll position as the user scrolls.
-   */
-  const handleScroll = useCallback(
-    (event: UIEvent) => {
-      if (!solo && event.currentTarget === event.target) {
-        scrollLeftRef.current = (event.target as HTMLDivElement).scrollLeft;
-      }
-    },
-    [solo],
-  );
-
-  const isEmpty = !solo && active.length === 0;
-
-  const padding = useMemo(() => {
-    if (!solo && settings?.overscroll === 'centering') {
-      return calculateOverscroll(active.length);
-    }
-    return {};
-  }, [solo, settings?.overscroll, deck]);
-
-  const mainPosition = useMemo(
-    () => [
-      'grid !block-start-[env(safe-area-inset-top)]',
-      topbar && '!block-start-[calc(env(safe-area-inset-top)+var(--rail-size))]',
-      hoistStatusbar && 'lg:block-end-[--statusbar-size]',
-    ],
-    [topbar, hoistStatusbar],
-  );
-
-  const { order, itemsCount }: { order: Record<string, number>; itemsCount: number } = useMemo(() => {
-    return active.reduce(
-      (acc: { order: Record<string, number>; itemsCount: number }, entryId) => {
-        acc.order[entryId] = acc.itemsCount + 1;
-        acc.itemsCount += activeCompanions?.[entryId] ? 3 : 2;
-        return acc;
-      },
-      { order: {}, itemsCount: 0 },
-    );
-  }, [active, activeCompanions]);
-
-  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}
-    >
-      {/* Left sidebar. */}
-      <Sidebar />
-
-      {/* Right sidebar. */}
-      <ComplementarySidebar current={complementarySidebarPanel} />
-
-      {/* Dialog overlay to dismiss dialogs. */}
-      <Main.Overlay />
-
-      {/* No content. */}
-      {isEmpty && (
-        <Main.Content bounce handlesFocus classNames={mainPosition}>
-          <ContentEmpty />
-        </Main.Content>
-      )}
-
-      {/* Solo/deck mode. */}
-      {!isEmpty && (
-        <Main.Content
-          bounce
-          handlesFocus
-          classNames={mainPosition}
-          style={
-            {
-              '--main-spacing': settings?.encapsulatedPlanks ? '0.75rem' : '0',
-              '--dx-main-sidebarWidth':
-                sidebarState === 'expanded'
-                  ? 'var(--nav-sidebar-size)'
-                  : sidebarState === 'collapsed'
-                    ? 'var(--l0-size)'
-                    : '0',
-              '--dx-main-complementaryWidth':
-                complementarySidebarState === 'expanded'
-                  ? 'var(--complementary-sidebar-size)'
-                  : complementarySidebarState === 'collapsed'
-                    ? 'var(--rail-size)'
-                    : '0',
-              '--dx-main-contentFirstWidth': `${plankSizing[active[0] ?? 'never'] ?? DEFAULT_HORIZONTAL_SIZE}rem`,
-              '--dx-main-contentLastWidth': `${plankSizing[active[(active.length ?? 1) - 1] ?? 'never'] ?? DEFAULT_HORIZONTAL_SIZE}rem`,
-            } as MainContentProps['style']
-          }
-        >
-          {/* Deck mode. */}
-          <div
-            role='none'
-            className={!solo ? 'relative bg-deckSurface overflow-hidden' : 'sr-only'}
-            {...(solo && { inert: true })}
-          >
-            {!topbar && !fullscreen && <ToggleSidebarButton classNames={fixedSidebarToggleStyles} />}
-            {!topbar && !fullscreen && (
-              <ToggleComplementarySidebarButton classNames={fixedComplementarySidebarToggleStyles} />
-            )}
-            <Stack
-              ref={deckRef}
-              orientation='horizontal'
-              size='contain'
-              itemsCount={itemsCount - 1}
-              classNames={[
-                'absolute inset-block-[--main-spacing] -inset-inline-px bs-[calc(100%-2*var(--main-spacing))]',
-                mainPaddingTransitions,
-              ]}
-              style={padding}
-              onScroll={handleScroll}
-            >
-              {active.map((entryId) => (
-                <Fragment key={entryId}>
-                  <PlankSeparator order={order[entryId] - 1} encapsulate={!!settings?.enableDeck} />
-                  <Plank
-                    id={entryId}
-                    companionId={activeCompanions?.[entryId]}
-                    part='deck'
-                    order={order[entryId]}
-                    active={active}
-                    layoutMode={layoutMode}
-                    settings={settings}
-                  />
-                </Fragment>
-              ))}
-            </Stack>
-          </div>
-
-          {/* Solo mode. */}
-          <div
-            role='none'
-            className={solo ? 'relative overflow-hidden bg-deckSurface' : 'sr-only'}
-            {...(!solo && { inert: true })}
-          >
-            {!topbar && !fullscreen && <ToggleSidebarButton classNames={fixedSidebarToggleStyles} />}
-            {!topbar && !fullscreen && (
-              <ToggleComplementarySidebarButton classNames={fixedComplementarySidebarToggleStyles} />
-            )}
-            <StackContext.Provider
-              value={{
-                orientation: 'horizontal',
-                size: 'contain',
-                rail: true,
-              }}
-            >
-              <Plank
-                id={solo}
-                companionId={solo ? activeCompanions?.[solo] : undefined}
-                part='solo'
-                layoutMode={layoutMode}
-                settings={settings}
-              />
-            </StackContext.Provider>
-          </div>
-        </Main.Content>
-      )}
-
-      {/* Topbar. */}
-      {topbar && <Topbar />}
-
-      {/* Status bar. */}
-      {hoistStatusbar && <StatusBar showHints={settings?.showHints} />}
-    </Main.Root>
-  );
-};
-
-const PlankSeparator = ({ order, encapsulate }: { order: number; encapsulate?: boolean }) =>
-  order > 0 ? (
-    <span
-      role='separator'
-      className={mx('row-span-2 bg-deckSurface', encapsulate ? 'is-0' : 'is-4')}
-      style={{ gridColumn: order }}
-    />
-  ) : null;

package/src/components/DeckLayout/Fallback.tsx

@@ -1,28 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React from 'react';
-
-import { useTranslation } from '@dxos/react-ui';
-import { errorText, mx } from '@dxos/ui-theme';
-
-import { meta } from '../../meta';
-
-export const Fallback = () => {
-  const { t } = useTranslation(meta.id);
-
-  return (
-    <div role='none' className='min-bs-screen is-full flex items-center justify-center p-8'>
-      <p
-        role='alert'
-        className={mx(
-          errorText,
-          'border border-roseFill rounded-md flex items-center justify-center p-8 font-normal text-lg',
-        )}
-      >
-        {t('plugin error message')}
-      </p>
-    </div>
-  );
-};

package/src/components/DeckLayout/Topbar.tsx

@@ -1,11 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React from 'react';
-
-import { Banner } from './Banner';
-
-export const Topbar = () => {
-  return <Banner variant='topbar' />;
-};

package/src/components/Plank/Plank.stories.tsx

@@ -1,63 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React from 'react';
-
-import { Capability, Plugin } from '@dxos/app-framework';
-import { withPluginManager } from '@dxos/app-framework/testing';
-import { AppActivationEvents } from '@dxos/app-toolkit';
-import { corePlugins } from '@dxos/plugin-testing';
-import { withTheme } from '@dxos/react-ui/testing';
-import { Stack } from '@dxos/react-ui-stack';
-
-import { DeckState } from '../../capabilities';
-import { meta as pluginMeta } from '../../meta';
-import { translations } from '../../translations';
-
-import { Plank } from './Plank';
-
-const TestPlugin = Plugin.define(pluginMeta).pipe(
-  Plugin.addModule({
-    id: Capability.getModuleTag(DeckState),
-    activatesOn: AppActivationEvents.AppGraphReady,
-    activate: () => DeckState(),
-  }),
-  Plugin.make,
-);
-
-const meta = {
-  title: 'plugins/plugin-deck/Plank',
-  component: Plank,
-  render: (args) => {
-    return (
-      <Stack orientation='horizontal'>
-        <Plank {...args} />
-      </Stack>
-    );
-  },
-  decorators: [
-    withTheme(),
-    withPluginManager({
-      plugins: [...corePlugins(), TestPlugin()],
-    }),
-  ],
-  parameters: {
-    layout: 'fullscreen',
-    translations,
-  },
-} satisfies Meta<typeof Plank>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-// TODO(burdon): Need to define surface provider?
-export const Default: Story = {
-  args: {
-    id: 'plank-1',
-    part: 'solo',
-    layoutMode: 'deck',
-  },
-};