@dxos/plugin-simple-layout 0.0.0

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,102 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { Surface, useCapability } from '@dxos/app-framework/react';
+import { Popover, type PopoverContentInteractOutsideEvent } from '@dxos/react-ui';
+
+import { SimpleLayoutState } from '../../types';
+
+const DEBOUNCE_DELAY = 40;
+
+type LayoutPopoverContextValue = {
+  setOpen: (open: boolean) => void;
+};
+
+const [LayoutPopoverProvider, useLayoutPopoverContext] = createContext<LayoutPopoverContextValue>('LayoutPopover');
+
+export const PopoverRoot = ({ children }: PropsWithChildren) => {
+  const layout = useCapability(SimpleLayoutState);
+  const [open, setOpen] = useState(false);
+  const virtualRef = useRef<HTMLButtonElement | null>(null);
+  const [virtualIter, setVirtualIter] = useState(0);
+  const debounceRef = useRef<NodeJS.Timeout | null>(null);
+
+  // TODO(thure): This is a workaround for the race condition between displaying a Popover and either rendering
+  //  the anchor further down the tree or measuring the virtual trigger's client rect.
+  useEffect(() => {
+    setOpen(false);
+    if (layout.popoverOpen) {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+      if (layout.popoverAnchor && virtualRef.current !== layout.popoverAnchor) {
+        virtualRef.current = layout.popoverAnchor ?? null;
+        setVirtualIter((iter) => iter + 1);
+      }
+      debounceRef.current = setTimeout(() => setOpen(true), DEBOUNCE_DELAY);
+    }
+  }, [layout.popoverOpen, layout.popoverAnchorId, layout.popoverAnchor, layout.popoverContent]);
+
+  return (
+    <LayoutPopoverProvider setOpen={setOpen}>
+      <Popover.Root modal={false} open={open}>
+        {layout.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
+        {children}
+      </Popover.Root>
+    </LayoutPopoverProvider>
+  );
+};
+
+export const PopoverContent = () => {
+  const layout = useCapability(SimpleLayoutState);
+  const { setOpen } = useLayoutPopoverContext('PopoverContent');
+
+  const handleClose = useCallback(
+    (event: KeyboardEvent | PopoverContentInteractOutsideEvent) => {
+      if (
+        // TODO(thure): CodeMirror should not focus itself when it updates.
+        event.type === 'dismissableLayer.focusOutside' &&
+        (event.currentTarget as HTMLElement | undefined)?.classList.contains('cm-content')
+      ) {
+        event.preventDefault();
+      } else {
+        setOpen(false);
+        layout.popoverOpen = false;
+        layout.popoverAnchor = undefined;
+        layout.popoverAnchorId = undefined;
+        layout.popoverSide = undefined;
+      }
+    },
+    [setOpen],
+  );
+
+  const collisionBoundaries: HTMLElement[] = useMemo(() => {
+    const closest = layout.popoverAnchor?.closest('[data-popover-collision-boundary]') as
+      | HTMLElement
+      | null
+      | undefined;
+    return closest ? [closest] : [];
+  }, [layout.popoverAnchor]);
+
+  return (
+    <Popover.Portal>
+      <Popover.Content
+        side={layout.popoverSide}
+        onInteractOutside={handleClose}
+        onEscapeKeyDown={handleClose}
+        collisionBoundary={collisionBoundaries}
+        sticky='always'
+        hideWhenDetached
+      >
+        <Popover.Viewport>
+          <Surface role='card--popover' data={layout.popoverContent} limit={1} />
+        </Popover.Viewport>
+        <Popover.Arrow />
+      </Popover.Content>
+    </Popover.Portal>
+  );
+};

package/src/components/Popover/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Popover';

package/src/components/SimpleLayout/Banner.tsx

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Common } from '@dxos/app-framework';
+import { useCapability, useOperationInvoker } from '@dxos/app-framework/react';
+import { type Node } from '@dxos/plugin-graph';
+import { IconButton, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { mx, osTranslations, surfaceZIndex } from '@dxos/ui-theme';
+
+import { meta } from '../../meta';
+import { SimpleLayoutState } from '../../types';
+
+export type BannerProps = {
+  node?: Node.Node;
+};
+
+export const Banner = ({ node }: BannerProps) => {
+  const { t } = useTranslation(meta.id);
+  const layout = useCapability(SimpleLayoutState);
+  const { invokePromise } = useOperationInvoker();
+  const label = node ? toLocalizedString(node.properties.label, t) : t('current app name', { ns: osTranslations });
+
+  const handleClick = useCallback(async () => {
+    if (layout.active) {
+      await invokePromise(Common.LayoutOperation.Close, { subject: [layout.active] });
+    } else {
+      await invokePromise(Common.LayoutOperation.SwitchWorkspace, { subject: 'default' });
+    }
+  }, [invokePromise, layout.active]);
+
+  return (
+    // Note that the HTML5 element `header` has a default role of `banner`, hence the name of this component.
+    // It should not be confused with the `heading` role (elements h1-6).
+    // TODO(burdon): Fixed or not?
+    <header
+      className={mx(
+        '_fixed flex items-center gap-2 pli-2 block-start-0 inset-inline-0 bs-[--dx-mobile-topbar-content-height,48px] bg-baseSurface border-be border-separator',
+        'grid grid-cols-[min-content_1fr_min-content]',
+        surfaceZIndex({ level: 'menu' }),
+      )}
+    >
+      {node ? (
+        <IconButton
+          iconOnly
+          variant='ghost'
+          icon='ph--caret-left--regular'
+          label={t('back label')}
+          onClick={handleClick}
+        />
+      ) : (
+        <div />
+      )}
+      <h1 className={'grow text-center truncate font-medium'}>{label}</h1>
+      {/* TODO(burdon): Menu. */}
+    </header>
+  );
+};

package/src/components/SimpleLayout/Main.tsx

@@ -0,0 +1,85 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { Activity, useMemo } from 'react';
+
+import { Surface, useAppGraph, useCapability } from '@dxos/app-framework/react';
+import { useNode } from '@dxos/plugin-graph';
+import { Main as NaturalMain } from '@dxos/react-ui';
+import { ATTENDABLE_PATH_SEPARATOR } from '@dxos/react-ui-attention';
+import { mx } from '@dxos/ui-theme';
+
+import { SimpleLayoutState } from '../../types';
+import { ContentError } from '../ContentError';
+import { ContentLoading } from '../ContentLoading';
+import { Home } from '../Home';
+
+import { Banner } from './Banner';
+import { NavBar } from './NavBar';
+
+export const Main = () => {
+  const layout = useCapability(SimpleLayoutState);
+  const id = layout.active ?? layout.workspace;
+  const { graph } = useAppGraph();
+  const node = useNode(graph, id);
+
+  const placeholder = useMemo(() => <ContentLoading />, []);
+
+  const { variant } = parseEntryId(id);
+  const data = useMemo(
+    () =>
+      node && {
+        attendableId: id,
+        subject: node.data,
+        properties: node.properties,
+        variant,
+        popoverAnchorId: layout.popoverAnchorId,
+      },
+    [node, node?.data, node?.properties, layout.popoverAnchorId, variant, id],
+  );
+
+  const handleActiveIdChange = (nextActiveId: string | null) => {
+    // eslint-disable-next-line no-console
+    console.log('[navigate]', nextActiveId);
+  };
+
+  const showNavBar = !layout.isPopover;
+
+  return (
+    <NaturalMain.Root complementarySidebarState='closed' navigationSidebarState='closed'>
+      <NaturalMain.Content bounce classNames='dx-mobile-main dx-mobile-main-scroll-area--flush !overflow-y-auto'>
+        <div
+          className={mx(
+            'bs-full overflow-hidden grid',
+            showNavBar ? 'grid-rows-[min-content_1fr_min-content]' : 'grid-rows-[min-content_1fr]',
+          )}
+        >
+          <Banner node={node} />
+          <Activity mode={id === 'default' ? 'visible' : 'hidden'}>
+            <Home />
+          </Activity>
+          <Activity mode={id !== 'default' ? 'visible' : 'hidden'}>
+            <section>
+              <Surface
+                key={id}
+                role='article'
+                data={data}
+                limit={1}
+                fallback={ContentError}
+                placeholder={placeholder}
+              />
+            </section>
+          </Activity>
+          {showNavBar && <NavBar activeId={id} onActiveIdChange={handleActiveIdChange} />}
+        </div>
+      </NaturalMain.Content>
+    </NaturalMain.Root>
+  );
+};
+
+// TODO(wittjosiah): Factor out. Copied from deck plugin.
+const parseEntryId = (entryId: string) => {
+  const [id, variant] = entryId.split(ATTENDABLE_PATH_SEPARATOR);
+  return { id, variant };
+};

package/src/components/SimpleLayout/NavBar.tsx

@@ -0,0 +1,97 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { useAppGraph } from '@dxos/app-framework/react';
+import { Node, useActionRunner, useConnections } from '@dxos/plugin-graph';
+import {
+  Avatar,
+  Button,
+  ButtonGroup,
+  DensityProvider,
+  IconButton,
+  type Size,
+  Tooltip,
+  useTranslation,
+} from '@dxos/react-ui';
+import { DropdownMenu, MenuProvider } from '@dxos/react-ui-menu';
+import { mx, surfaceZIndex } from '@dxos/ui-theme';
+
+import { meta } from '../../meta';
+
+const buttonProps = {
+  iconOnly: true,
+  size: 6 as Size,
+  classNames: 'aspect-square',
+};
+
+export type NavBarProps = {
+  activeId?: string;
+  onActiveIdChange?: (nextActiveId: string | null) => void;
+};
+
+export const NavBar = ({ activeId, onActiveIdChange }: NavBarProps) => {
+  const { t } = useTranslation(meta.id);
+  const { graph } = useAppGraph();
+  const runAction = useActionRunner();
+
+  const connections = useConnections(graph, Node.RootId);
+  const menuActions = connections.filter((node) => node.properties.disposition === 'menu');
+
+  const isBrowseActive = activeId !== 'notifications' && activeId !== 'profile';
+
+  return (
+    <DensityProvider density='coarse'>
+      <nav
+        className={mx(
+          'fixed inset-inline-0',
+          'grid grid-cols-[min-content_min-content] gap-2 place-content-center',
+          'block-end-[--dx-mobile-bottombar-inset-bottom,0px] bs-[--dx-mobile-bottombar-content-height,64px]',
+          'bg-baseSurface border-bs border-separator',
+          surfaceZIndex({ level: 'menu' }),
+        )}
+      >
+        <ButtonGroup>
+          <IconButton
+            {...buttonProps}
+            label={t('browse label')}
+            icon='ph--squares-four--regular'
+            onClick={() => onActiveIdChange?.(null)}
+            variant={isBrowseActive ? 'primary' : 'default'}
+            {...(isBrowseActive && { 'aria-current': 'location' })}
+          />
+          <IconButton
+            {...buttonProps}
+            label={t('notifications label')}
+            icon='ph--bell-simple--regular'
+            onClick={() => onActiveIdChange?.('notifications')}
+            variant={activeId === 'notifications' ? 'primary' : 'default'}
+            {...(activeId === 'notifications' && { 'aria-current': 'location' })}
+          />
+          <Button
+            variant={activeId === 'profile' ? 'primary' : 'default'}
+            onClick={() => onActiveIdChange?.('profile')}
+            classNames={buttonProps.classNames}
+          >
+            <span className='sr-only'>{t('profile label')}</span>
+            <Avatar.Root>
+              <Avatar.Label classNames='sr-only'>Profile display name</Avatar.Label>
+              <Avatar.Content size={8} status='active' hue='cyan' fallback='🗿' />
+            </Avatar.Root>
+          </Button>
+        </ButtonGroup>
+        <MenuProvider onAction={runAction}>
+          <DropdownMenu.Root items={menuActions}>
+            <Tooltip.Trigger asChild content={t('app menu label')} side='right'>
+              <DropdownMenu.Trigger asChild data-testid='spacePlugin.addSpace'>
+                <IconButton {...buttonProps} icon='ph--plus--regular' label={t('main menu label')} />
+              </DropdownMenu.Trigger>
+            </Tooltip.Trigger>
+          </DropdownMenu.Root>
+        </MenuProvider>
+      </nav>
+    </DensityProvider>
+  );
+};

package/src/components/SimpleLayout/NavBarstories.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '../../translations';
+
+import { NavBar } from './NavBar';
+
+const meta = {
+  title: 'plugins/plugin-simple-layout/NavBar',
+  component: NavBar,
+  decorators: [
+    withTheme,
+    withPluginManager({
+      plugins: [...corePlugins()],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+  argTypes: {
+    onActiveIdChange: { action: 'activeIdChanged' },
+  },
+} satisfies Meta<typeof NavBar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    activeId: undefined,
+  },
+};
+
+export const BrowseActive: Story = {
+  args: {
+    activeId: 'some-document',
+  },
+};
+
+export const NotificationsActive: Story = {
+  args: {
+    activeId: 'notifications',
+  },
+};
+
+export const ProfileActive: Story = {
+  args: {
+    activeId: 'profile',
+  },
+};

package/src/components/SimpleLayout/SimpleLayout.stories.tsx

@@ -0,0 +1,107 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+
+import { Capability, Common, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { ClientOperation, ClientPlugin } from '@dxos/plugin-client';
+import { SearchPlugin } from '@dxos/plugin-search';
+import { SpacePlugin } from '@dxos/plugin-space';
+import { SpaceOperation } from '@dxos/plugin-space/types';
+import { corePlugins } from '@dxos/plugin-testing';
+import { withTheme } from '@dxos/react-ui/testing';
+import { translations as searchTranslation } from '@dxos/react-ui-searchlist';
+import { Collection } from '@dxos/schema';
+
+import { OperationResolver, type SimpleLayoutStateOptions, State } from '../../capabilities';
+import { meta as pluginMeta } from '../../meta';
+import { type SimpleLayoutPluginOptions } from '../../SimpleLayoutPlugin';
+import { translations } from '../../translations';
+
+import { SimpleLayout } from './SimpleLayout';
+
+const TestPlugin = Plugin.define<SimpleLayoutPluginOptions>(pluginMeta).pipe(
+  Plugin.addModule(({ isPopover = false }) => ({
+    id: Capability.getModuleTag(State),
+    activatesOn: Common.ActivationEvent.Startup,
+    activatesAfter: [Common.ActivationEvent.LayoutReady],
+    activate: () => State({ initialState: { isPopover } } satisfies SimpleLayoutStateOptions),
+  })),
+  Common.Plugin.addOperationResolverModule({ activate: OperationResolver }),
+  Plugin.addModule({
+    id: 'setup',
+    activatesOn: Common.ActivationEvent.OperationInvokerReady,
+    activate: Effect.fnUntraced(function* () {
+      const { invoke } = yield* Capability.get(Common.Capability.OperationInvoker);
+      yield* invoke(ClientOperation.CreateIdentity, {});
+      const { space: work } = yield* invoke(SpaceOperation.Create, { name: 'Work Space' });
+      const { space: sharedProject } = yield* invoke(SpaceOperation.Create, { name: 'Shared Project' });
+
+      // Add collections to Work Space.
+      yield* invoke(SpaceOperation.AddObject, {
+        target: work.db,
+        object: Collection.make({ name: 'Projects', objects: [] }),
+      });
+      yield* invoke(SpaceOperation.AddObject, {
+        target: work.db,
+        object: Collection.make({ name: 'Documents', objects: [] }),
+      });
+
+      // Add collections to Shared Project.
+      yield* invoke(SpaceOperation.AddObject, {
+        target: sharedProject.db,
+        object: Collection.make({ name: 'Tasks', objects: [] }),
+      });
+      yield* invoke(SpaceOperation.AddObject, {
+        target: sharedProject.db,
+        object: Collection.make({ name: 'Notes', objects: [] }),
+      });
+    }),
+  }),
+  Plugin.make,
+);
+
+const createPluginManager = ({ isPopover }: { isPopover: boolean }) => {
+  return withPluginManager({
+    plugins: [
+      ...corePlugins(),
+      ClientPlugin({
+        onClientInitialized: ({ client }) =>
+          Effect.gen(function* () {
+            yield* Effect.promise(() => client.halo.createIdentity());
+            yield* Effect.promise(async () => {
+              await client.spaces.create({ name: 'Work Space' });
+              await client.spaces.create({ name: 'Shared Project' });
+            });
+          }),
+      }),
+      SpacePlugin({}),
+      SearchPlugin(),
+      TestPlugin({ isPopover }),
+    ],
+  });
+};
+
+const meta = {
+  title: 'plugins/plugin-simple-layout/SimpleLayout',
+  component: SimpleLayout,
+  parameters: {
+    layout: 'fullscreen',
+    translations: [...translations, ...searchTranslation],
+  },
+} satisfies Meta<typeof SimpleLayout>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withTheme, createPluginManager({ isPopover: false })],
+};
+
+export const Popover: Story = {
+  decorators: [withTheme, createPluginManager({ isPopover: true })],
+};

package/src/components/SimpleLayout/SimpleLayout.tsx

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Dialog } from '../Dialog';
+import { PopoverContent, PopoverRoot } from '../Popover';
+
+import { Main } from './Main';
+
+// TODO(wittjosiah): Support toast.
+export const SimpleLayout = () => {
+  return (
+    <PopoverRoot>
+      <Main />
+      <Dialog />
+      <PopoverContent />
+    </PopoverRoot>
+  );
+};

package/src/components/SimpleLayout/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './SimpleLayout';

package/src/components/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ContentLoading';
+export * from './Home';
+export * from './Popover';
+export * from './SimpleLayout';

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useSpotlightDismiss';

package/src/hooks/useSpotlightDismiss.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Based on the frontend-driven dismiss pattern from:
+// https://github.com/Jedliu/tauri-template-demo
+
+import { useEffect } from 'react';
+
+import { log } from '@dxos/log';
+import { isTauri } from '@dxos/util';
+
+/**
+ * Get the Tauri window API from the global object.
+ * Returns undefined if not running in Tauri.
+ */
+const getTauriWindow = (): any => {
+  const tauri = (globalThis as any).__TAURI__;
+  return tauri?.window;
+};
+
+/**
+ * Get the Tauri core API (invoke) from the global object.
+ * Returns undefined if not running in Tauri.
+ */
+const getTauriCore = (): any => {
+  const tauri = (globalThis as any).__TAURI__;
+  return tauri?.core;
+};
+
+/**
+ * Hook to set up spotlight panel dismiss behavior.
+ * When running in Tauri popover mode, listens for focus loss and Escape key
+ * to dismiss the spotlight panel.
+ */
+export const useSpotlightDismiss = (isPopover: boolean | undefined) => {
+  // Handle blur (click outside) to dismiss spotlight.
+  useEffect(() => {
+    if (!isPopover || !isTauri()) {
+      return;
+    }
+
+    let cleanup: (() => void) | undefined;
+
+    const setup = async () => {
+      try {
+        const tauriWindow = getTauriWindow();
+        const tauriCore = getTauriCore();
+        if (!tauriWindow || !tauriCore) {
+          return;
+        }
+
+        const win = tauriWindow.getCurrentWindow();
+        const unlisten = await win.onFocusChanged(async ({ payload }: { payload: boolean }) => {
+          if (!payload) {
+            await tauriCore.invoke('hide_spotlight');
+          }
+        });
+        cleanup = unlisten;
+      } catch (err) {
+        log.catch(err);
+      }
+    };
+
+    void setup();
+
+    return () => {
+      cleanup?.();
+    };
+  }, [isPopover]);
+
+  // Handle Escape key to dismiss spotlight.
+  useEffect(() => {
+    if (!isPopover || !isTauri()) {
+      return;
+    }
+
+    const handleKeyDown = async (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        try {
+          const tauriCore = getTauriCore();
+          if (tauriCore) {
+            await tauriCore.invoke('hide_spotlight');
+          }
+        } catch (err) {
+          log.catch(err);
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [isPopover]);
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './SimpleLayoutPlugin';

package/src/meta.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
+
+export const meta: Plugin.Meta = {
+  id: 'dxos.org/plugin/simple-layout',
+  name: 'Simple Layout',
+  description: trim`
+    Minimal layout plugin for simplified UI contexts like popover windows.
+    Provides basic content rendering without sidebars or complex navigation.
+  `,
+  icon: 'ph--layout--regular',
+};