@dxos/plugin-simple-layout 0.0.0 → 0.8.4-main.03d5cd7b56

package/src/capabilities/url-handler.ts

@@ -0,0 +1,164 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities, LayoutOperation, fromUrlPath, getWorkspaceFromPath, toUrlPath } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+import { isTauri } from '@dxos/util';
+
+import { SimpleLayoutCapabilities } from '#types';
+
+/**
+ * URL handler for simple layout that syncs browser URL with layout state.
+ * URL paths map directly to qualified graph IDs with the leading `root` segment stripped.
+ * Root is represented as `/`.
+ *
+ * On Tauri, also listens for deep links via the deep-link plugin.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const { invokePromise } = yield* Capability.get(Capabilities.OperationInvoker);
+    const capabilities = yield* Capability.Service;
+
+    /** Dispatch all NavigationHandler contributions with a given URL. */
+    const dispatchNavigationHandlers = (url: URL) =>
+      Effect.gen(function* () {
+        const handlers = yield* Capability.getAll(AppCapabilities.NavigationHandler);
+        yield* Effect.all(
+          handlers.map((handler) => handler(url)),
+          { concurrency: 'unbounded' },
+        );
+      }).pipe(Effect.provideService(Capability.Service, capabilities), runAndForwardErrors);
+
+    /**
+     * Handle navigation from a URL.
+     * Dispatches to NavigationHandler contributions, then handles pathname routing.
+     */
+    const handlePathNavigation = (url?: URL) => {
+      const resolvedUrl = url ?? new URL(window.location.href);
+      void dispatchNavigationHandlers(resolvedUrl);
+
+      let pathname = resolvedUrl.pathname;
+      if (isFilePath(pathname)) {
+        log.info('[UrlHandler] Skipping file path (not a graph node)', { pathname });
+        pathname = '/';
+      }
+
+      const qualifiedId = fromUrlPath(pathname);
+      const workspace = getWorkspaceFromPath(qualifiedId);
+
+      void invokePromise(LayoutOperation.SwitchWorkspace, { subject: workspace });
+
+      const activeId = qualifiedId !== workspace ? qualifiedId : undefined;
+      if (activeId) {
+        void invokePromise(LayoutOperation.Open, { subject: [activeId] });
+      }
+    };
+
+    const onPopState = () => {
+      handlePathNavigation();
+    };
+
+    // Initial navigation.
+    yield* Effect.sync(() => handlePathNavigation());
+    window.addEventListener('popstate', onPopState);
+
+    // Tauri deep link support.
+    let unlistenDeepLink: (() => void) | undefined;
+    if (isTauri()) {
+      yield* Effect.tryPromise({
+        try: async () => {
+          const { getCurrent, onOpenUrl } = await import('@tauri-apps/plugin-deep-link');
+
+          const launchUrls = await getCurrent();
+          if (launchUrls && launchUrls.length > 0) {
+            log.info('[UrlHandler] App launched with deep links', { urls: launchUrls });
+            for (const urlString of launchUrls) {
+              handleDeepLink(urlString, handlePathNavigation);
+            }
+          }
+
+          unlistenDeepLink = await onOpenUrl((urls) => {
+            log.info('[UrlHandler] Deep links received', { urls });
+            for (const urlString of urls) {
+              handleDeepLink(urlString, handlePathNavigation);
+            }
+          });
+        },
+        catch: (error) => {
+          log.warn('[UrlHandler] Failed to initialize deep link listener', { error });
+          return error;
+        },
+      }).pipe(Effect.catchAll(() => Effect.void));
+    }
+
+    // Sync URL with layout state changes.
+    let lastWorkspace: string | undefined;
+    let lastActive: string | undefined;
+    const unsubscribe = yield* Capabilities.subscribeAtom(
+      SimpleLayoutCapabilities.State,
+      (state: SimpleLayoutCapabilities.SimpleLayoutState) => {
+        const { workspace, active } = state;
+
+        if (workspace !== lastWorkspace || active !== lastActive) {
+          lastWorkspace = workspace;
+          lastActive = active;
+
+          const path = active ? toUrlPath(active) : toUrlPath(workspace);
+          if (window.location.pathname !== path) {
+            history.pushState(null, '', `${path}${window.location.search}`);
+          }
+        }
+      },
+    );
+
+    return Capability.contributes(Capabilities.Null, null, () =>
+      Effect.sync(() => {
+        window.removeEventListener('popstate', onPopState);
+        unsubscribe();
+        unlistenDeepLink?.();
+      }),
+    );
+  }),
+);
+
+/** Check if a path is a redirect path handled elsewhere (e.g., OAuth). */
+const isRedirectPath = (pathname: string): boolean => pathname.startsWith('/redirect/');
+
+/** Paths with file extensions are not graph node paths. */
+const isFilePath = (pathname: string): boolean => /\.[a-z]+$/i.test(pathname);
+
+/** Handle a deep link URL string. Merges query params into window.location and navigates. */
+const handleDeepLink = (urlString: string, navigate: (url?: URL) => void): void => {
+  log.info('[UrlHandler] Deep link received', { url: urlString });
+  try {
+    const deepLinkUrl = new URL(urlString);
+
+    // For custom schemes (e.g., composer://a/b/c), new URL() treats the first segment as the
+    // hostname. Reconstruct the full path from hostname + pathname.
+    const fullPath =
+      deepLinkUrl.protocol !== 'https:' && deepLinkUrl.protocol !== 'http:' && deepLinkUrl.hostname
+        ? '/' + deepLinkUrl.hostname + deepLinkUrl.pathname
+        : deepLinkUrl.pathname;
+
+    if (isRedirectPath(fullPath)) {
+      return;
+    }
+
+    // Merge deep link query params into the current window URL so handlers can read them.
+    const current = new URL(window.location.href);
+    if (deepLinkUrl.search) {
+      deepLinkUrl.searchParams.forEach((value, key) => current.searchParams.set(key, value));
+    }
+    current.pathname = fullPath;
+    history.replaceState(null, '', current.pathname + current.search);
+
+    navigate(current);
+  } catch (error) {
+    log.warn('[UrlHandler] Failed to parse deep link URL', { urlString, error });
+  }
+};

package/src/components/ContentError.stories.tsx

@@ -4,28 +4,29 @@
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 
+import { ErrorFallback } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
 
-import { translations } from '../translations';
-
-import { ContentError } from './ContentError';
+import { translations } from '#translations';
 
 const meta = {
-  title: 'plugins/plugin-simple-layout/ContentError',
-  component: ContentError,
-  decorators: [withTheme],
+  title: 'plugins/plugin-simple-layout/components/ErrorFallback',
+  component: ErrorFallback,
+  decorators: [withTheme()],
   parameters: {
     layout: 'centered',
     translations,
   },
-} satisfies Meta<typeof ContentError>;
+} satisfies Meta<typeof ErrorFallback>;
 
 export default meta;
 
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  args: {},
+  args: {
+    error: new Error('An unexpected error occurred'),
+  },
 };
 
 export const WithError: Story = {

package/src/components/DebugOverlay/DebugOverlay.tsx

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren, useCallback, useRef } from 'react';
+
+const DEBUG_OVERLAY_NAME = 'DebugOverlay';
+
+//
+// Context
+//
+
+type DebugOverlayContextValue = {
+  /** Log a timestamped message to the on-screen debug overlay. */
+  dbg: (msg: string) => void;
+};
+
+// Default to a no-op so hooks can call useDebugLog() safely outside of a provider.
+const [DebugOverlayProvider, useDebugLog] = createContext<DebugOverlayContextValue>(DEBUG_OVERLAY_NAME, {
+  dbg: () => {},
+});
+
+//
+// Root
+//
+
+type DebugOverlayRootProps = PropsWithChildren<{
+  /**
+   * When true (default), renders the on-screen log panel.
+   * Set to false to suppress the overlay while keeping the context available.
+   */
+  enabled?: boolean;
+  maxLines?: number;
+}>;
+
+/**
+ * Establishes a debug overlay context.
+ *
+ * When enabled, renders an on-screen monospaced log panel anchored just above
+ * the keyboard (via --kb-height CSS variable). Descendants can call
+ * useDebugLog() to obtain the dbg() function for logging.
+ *
+ * Intended for transient mobile debugging in the iOS Simulator where DevTools
+ * console output may not be accessible.
+ */
+const DebugOverlayRoot = ({ children, enabled = true, maxLines = 10 }: DebugOverlayRootProps) => {
+  const overlayRef = useRef<HTMLDivElement>(null);
+
+  const dbg = useCallback((msg: string) => {
+    if (!overlayRef.current) {
+      return;
+    }
+    const line = document.createElement('pre');
+    line.textContent = `${(performance.now() / 1000).toFixed(2).padStart(8, ' ')} ${msg}`;
+    overlayRef.current.prepend(line);
+    while (overlayRef.current.children.length > maxLines) {
+      overlayRef.current.lastChild?.remove();
+    }
+  }, []);
+
+  return (
+    <DebugOverlayProvider dbg={dbg}>
+      {children}
+      {enabled && (
+        <div
+          ref={overlayRef}
+          style={{
+            position: 'fixed',
+            bottom: 'calc(var(--kb-height, 0px) + 8px)',
+            left: 8,
+            right: 8,
+            background: 'rgba(0,0,0,0.8)',
+            color: '#0f0',
+            fontSize: 10,
+            fontFamily: 'monospace',
+            padding: 6,
+            borderRadius: 4,
+            zIndex: 9999,
+            pointerEvents: 'none',
+          }}
+        />
+      )}
+    </DebugOverlayProvider>
+  );
+};
+
+//
+// Exports
+//
+
+export const DebugOverlay = {
+  Root: DebugOverlayRoot,
+};
+
+export { useDebugLog };

package/src/components/DebugOverlay/index.ts

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

package/src/components/Dialog/Dialog.tsx

@@ -4,33 +4,44 @@
 
 import React from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 import { AlertDialog, Dialog as NaturalDialog } from '@dxos/react-ui';
+import { ErrorFallback } from '@dxos/react-ui';
 
-import { SimpleLayoutState } from '../../types';
-import { ContentError } from '../ContentError';
+import { useSimpleLayoutState } from '#hooks';
 
 export const Dialog = () => {
-  const layout = useCapability(SimpleLayoutState);
+  const { state, updateState } = useSimpleLayoutState();
 
-  const DialogRoot = layout.dialogType === 'alert' ? AlertDialog.Root : NaturalDialog.Root;
-  const DialogOverlay = layout.dialogType === 'alert' ? AlertDialog.Overlay : NaturalDialog.Overlay;
+  const DialogRoot = state.dialogType === 'alert' ? AlertDialog.Root : NaturalDialog.Root;
+  const DialogOverlay = state.dialogType === 'alert' ? AlertDialog.Overlay : NaturalDialog.Overlay;
 
   return (
     <DialogRoot
-      modal={layout.dialogBlockAlign !== 'end'}
-      open={layout.dialogOpen}
-      onOpenChange={(nextOpen) => (layout.dialogOpen = nextOpen)}
+      modal={state.dialogBlockAlign !== 'end'}
+      open={state.dialogOpen}
+      onOpenChange={(nextOpen) => updateState((state) => ({ ...state, dialogOpen: nextOpen }))}
     >
-      {layout.dialogBlockAlign === 'end' ? (
-        <Surface role='dialog' data={layout.dialogContent} limit={1} fallback={ContentError} placeholder={<div />} />
+      {state.dialogBlockAlign === 'end' ? (
+        <Surface.Surface
+          type={AppSurface.Dialog}
+          data={state.dialogContent ?? undefined}
+          limit={1}
+          fallback={ErrorFallback}
+        />
       ) : (
         <DialogOverlay
-          blockAlign={layout.dialogBlockAlign}
-          classNames={layout.dialogOverlayClasses}
-          style={layout.dialogOverlayStyle}
+          blockAlign={state.dialogBlockAlign}
+          classNames={state.dialogOverlayClasses}
+          style={state.dialogOverlayStyle}
         >
-          <Surface role='dialog' data={layout.dialogContent} limit={1} fallback={ContentError} />
+          <Surface.Surface
+            type={AppSurface.Dialog}
+            data={state.dialogContent ?? undefined}
+            limit={1}
+            fallback={ErrorFallback}
+          />
         </DialogOverlay>
       )}
     </DialogRoot>

package/src/components/Home/Home.tsx

@@ -4,135 +4,135 @@
 
 import React, { useCallback, useEffect, useMemo, useRef } from 'react';
 
-import { Common } from '@dxos/app-framework';
-import { useAppGraph, useOperationInvoker } from '@dxos/app-framework/react';
-import { Graph, Node, useConnections } from '@dxos/plugin-graph';
-import { Avatar, Icon, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
-import { Card } from '@dxos/react-ui-mosaic';
-import { SearchList, useSearchListItem, useSearchListResults } from '@dxos/react-ui-searchlist';
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Node, useConnections } from '@dxos/plugin-graph';
+import { Avatar, Icon, ScrollArea, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { Card } from '@dxos/react-ui';
+import { Mosaic, type MosaicStackTileComponent } from '@dxos/react-ui-mosaic';
+import { SearchPanel, useSearchListItem, useSearchListResults } from '@dxos/react-ui-search';
 import { mx } from '@dxos/ui-theme';
+import { byPosition, getHostPlatform, isTauri } from '@dxos/util';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
 
-type HomeProps = ThemedClassName;
+import { useExpandPath } from '../hooks';
 
-export const Home = ({ classNames }: HomeProps) => {
+export type HomeProps = {};
+
+/**
+ * Home screen.
+ */
+export const Home = (_: HomeProps) => {
   const { t } = useTranslation(meta.id);
-  const workspaces = useWorkspaces();
-  useLoadDescendents(Node.RootId);
+  const userAccountItem = useItemsByDisposition('user-account')[0];
+  const pinnedItems = useItemsByDisposition('pin-end', true);
+  const workspaceItems = useItemsByDisposition('workspace');
+  useExpandPath(Node.RootId);
+
+  const items = useMemo(
+    () => [...(userAccountItem ? [userAccountItem] : []), ...pinnedItems, ...workspaceItems],
+    [userAccountItem, pinnedItems, workspaceItems],
+  );
 
   const { results, handleSearch } = useSearchListResults({
-    items: workspaces,
+    items,
     extract: (node) => toLocalizedString(node.properties.label, t),
   });
 
+  const autoFocus = !isTauri() || getHostPlatform() !== 'ios';
+
   return (
-    <div className={mx('flex flex-col pli-3', classNames)}>
-      {/* <div className='container-max-width'>{t('workspaces heading')}</div> */}
-      <SearchList.Root onSearch={handleSearch} classNames='container-max-width'>
-        <div className='plb-3'>
-          <SearchList.Input placeholder={t('search placeholder')} autoFocus />
-        </div>
-        <SearchList.Content>
-          <SearchList.Viewport classNames='flex flex-col gap-1'>
-            {results.map((node) => (
-              <Workspace key={node.id} node={node} />
-            ))}
-          </SearchList.Viewport>
-        </SearchList.Content>
-      </SearchList.Root>
-    </div>
+    <SearchPanel onSearch={handleSearch}>
+      <Mosaic.Container asChild>
+        <ScrollArea.Root centered padding thin>
+          <ScrollArea.Viewport>
+            <Mosaic.Stack
+              classNames='gap-1'
+              draggable={false}
+              items={results}
+              getId={(item) => item.id}
+              Tile={WorkspaceTile}
+            />
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Mosaic.Container>
+    </SearchPanel>
   );
 };
 
-const Workspace = ({ node }: { node: Node.Node }) => {
+const WorkspaceTile: MosaicStackTileComponent<Node.Node> = (props) => {
+  const data = props.data;
   const { t } = useTranslation(meta.id);
   const { invokePromise } = useOperationInvoker();
   const { selectedValue, registerItem, unregisterItem } = useSearchListItem();
-  const ref = useRef<HTMLDivElement>(null);
+  const name = toLocalizedString(data.properties.label, t);
+  const isSelected = selectedValue === data.id;
+  const cardRef = useRef<HTMLDivElement>(null);
+
+  useExpandPath(data.id);
 
   const handleSelect = useCallback(
-    () => invokePromise(Common.LayoutOperation.SwitchWorkspace, { subject: node.id }),
-    [invokePromise, node.id],
+    () => invokePromise(LayoutOperation.SwitchWorkspace, { subject: data.id }),
+    [invokePromise, data.id],
   );
 
-  useLoadDescendents(node.id);
-
-  const name = toLocalizedString(node.properties.label, t);
-  const isSelected = selectedValue === node.id;
-
   // Register this workspace with the search context.
   useEffect(() => {
-    if (ref.current) {
-      registerItem(node.id, ref.current, handleSelect);
+    if (cardRef.current) {
+      registerItem(data.id, cardRef.current, handleSelect);
     }
 
-    return () => unregisterItem(node.id);
-  }, [node.id, handleSelect, registerItem, unregisterItem]);
+    return () => unregisterItem(data.id);
+  }, [data.id, handleSelect, registerItem, unregisterItem]);
 
   // Scroll into view when selected.
   useEffect(() => {
-    if (isSelected && ref.current) {
-      ref.current.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    if (isSelected && cardRef.current) {
+      cardRef.current.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
     }
   }, [isSelected]);
 
   return (
     <Card.Root
-      ref={ref}
       role='button'
-      tabIndex={-1}
+      fullWidth
+      tabIndex={-1} // TODO(burdon): Use Mosaic.Focus.
       data-selected={isSelected}
-      classNames={mx('dx-focus-ring', isSelected && 'bg-hoverOverlay')}
+      classNames={mx('dx-focus-ring', isSelected && 'bg-hover-overlay')}
       onClick={handleSelect}
+      ref={cardRef}
     >
-      <Card.Chrome classNames='grid grid-cols-[min-content_1fr_min-content] items-center gap-cardSpacingInline pie-cardSpacingInline'>
+      <Card.Toolbar density='fine'>
         <Avatar.Root>
           <Avatar.Content
-            hue={node.properties.hue}
-            icon={node.properties.icon}
-            hueVariant='surface'
+            icon={data.properties.icon}
+            hue={data.properties.hue}
+            hueVariant='transparent'
             variant='square'
-            size={12}
+            size={8}
             fallback={name}
           />
-          <Avatar.Label>{name}</Avatar.Label>
+          <Avatar.Label classNames='cursor-pointer'>{name}</Avatar.Label>
           <Icon icon='ph--caret-right--regular' />
         </Avatar.Root>
-      </Card.Chrome>
+      </Card.Toolbar>
     </Card.Root>
   );
 };
 
-const useLoadDescendents = (nodeId?: string) => {
-  const { graph } = useAppGraph();
-
-  useEffect(() => {
-    const frame = requestAnimationFrame(() => {
-      if (nodeId) {
-        Graph.expand(graph, nodeId, 'outbound');
-        Graph.getConnections(graph, nodeId, 'outbound').forEach((child) => {
-          Graph.expand(graph, child.id, 'outbound');
-        });
-      }
-    });
-
-    return () => cancelAnimationFrame(frame);
-  }, [nodeId, graph]);
+/** Filters nodes by disposition. */
+const filterItems = (node: Node.Node, disposition: string) => {
+  return node.properties.disposition === disposition;
 };
 
-const useWorkspaces = () => {
+/** Returns root-level items filtered by disposition. */
+const useItemsByDisposition = (disposition: string, sort = false) => {
   const { graph } = useAppGraph();
-
-  // Get root connections to find collections.
-  const rootConnections = useConnections(graph, Node.RootId);
-  const collections = useMemo(
-    () => rootConnections.filter((node) => node.properties.disposition === 'collection'),
-    [rootConnections],
-  );
-
-  // Get first collection's children as workspaces.
-  // TODO(wittjosiah): Support multiple collections or nested workspaces if needed.
-  const firstCollection = collections[0];
-  return useConnections(graph, firstCollection?.id);
+  const connections = useConnections(graph, Node.RootId, 'child');
+  return useMemo(() => {
+    const filtered = connections.filter((node) => filterItems(node, disposition));
+    return sort ? filtered.toSorted((a, b) => byPosition(a.properties, b.properties)) : filtered;
+  }, [connections, disposition, sort]);
 };

package/src/components/{ContentLoading.stories.tsx → Loading/Loading.stories.tsx}

@@ -6,16 +6,16 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 
 import { withTheme } from '@dxos/react-ui/testing';
 
-import { ContentLoading } from './ContentLoading';
+import { Loading } from './Loading';
 
 const meta = {
-  title: 'plugins/plugin-simple-layout/ContentLoading',
-  component: ContentLoading,
-  decorators: [withTheme],
+  title: 'plugins/plugin-simple-layout/components/Loading',
+  component: Loading,
+  decorators: [withTheme()],
   parameters: {
     layout: 'centered',
   },
-} satisfies Meta<typeof ContentLoading>;
+} satisfies Meta<typeof Loading>;
 
 export default meta;
 

package/src/components/{ContentLoading.tsx → Loading/Loading.tsx}

@@ -5,6 +5,6 @@
 import React from 'react';
 
 // TODO(burdon): Show skeleton: https://github.com/dxos/dxos/issues/8259
-export const ContentLoading = () => {
-  return <div role='none' className='grid place-items-center attention-surface' />;
+export const Loading = () => {
+  return <div className='grid place-items-center dx-attention-surface' />;
 };

package/src/components/Loading/index.ts

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