@dxos/plugin-simple-layout 0.0.0 → 0.8.4-main.52d7546f51

package/src/components/MobileLayout/MobileLayout.tsx

@@ -0,0 +1,305 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren, forwardRef, useEffect, useState } from 'react';
+
+import { addEventListener, combine } from '@dxos/async';
+import { log } from '@dxos/log';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+// TODO(burdon): Move into @dxos/react-ui?
+
+const MOBILE_LAYOUT_NAME = 'MobileLayout';
+const MOBILE_LAYOUT_ROOT_NAME = 'MobileLayout.Root';
+const MOBILE_LAYOUT_PANEL_NAME = 'MobileLayout.Panel';
+
+//
+// Context
+//
+
+type MobileLayoutContextValue = {
+  keyboardOpen: boolean;
+};
+
+const [MobileLayoutProvider, useMobileLayout] = createContext<MobileLayoutContextValue>(MOBILE_LAYOUT_NAME);
+
+//
+// Root
+//
+
+type MobileLayoutRootProps = ThemedClassName<
+  PropsWithChildren<{
+    transition?: number;
+    onKeyboardOpenChange?: (nextState: boolean) => void;
+  }>
+>;
+
+/**
+ * Mobile layout root container that handles iOS keyboard detection.
+ */
+// TODO(burdon): Should this be ios-only?
+const MobileLayoutRoot = forwardRef<HTMLDivElement, MobileLayoutRootProps>(
+  ({ classNames, children, transition = 250, onKeyboardOpenChange, ...props }, forwardedRef) => {
+    const { open: keyboardOpen } = useIOSKeyboard();
+    useAutoScroll();
+    useEffect(() => onKeyboardOpenChange?.(keyboardOpen), [onKeyboardOpenChange, keyboardOpen]);
+    useLockBodyScroll(keyboardOpen);
+
+    return (
+      <MobileLayoutProvider keyboardOpen={keyboardOpen}>
+        <div
+          {...props}
+          role='none'
+          style={{
+            transition: `block-size ${transition}ms ease-out`,
+            blockSize: 'calc(100vh - var(--kb-height, 0px))',
+          }}
+          className={mx('absolute top-0 left-0 right-0 flex flex-col', classNames)}
+          ref={forwardedRef}
+        >
+          {children}
+        </div>
+      </MobileLayoutProvider>
+    );
+  },
+);
+
+MobileLayoutRoot.displayName = MOBILE_LAYOUT_ROOT_NAME;
+
+//
+// Panel
+//
+
+type MobileLayoutPanelProps = ThemedClassName<
+  PropsWithChildren<{
+    safe?: {
+      top: boolean;
+      bottom: boolean;
+    };
+  }>
+>;
+
+/**
+ * Mobile layout panel that applies safe area insets.
+ */
+const MobileLayoutPanel = forwardRef<HTMLDivElement, MobileLayoutPanelProps>(
+  ({ classNames, children, safe, ...props }, forwardedRef) => {
+    return (
+      <div
+        {...props}
+        role='none'
+        style={{
+          paddingTop: safe?.top ? 'env(safe-area-inset-top)' : undefined,
+          paddingBottom: safe?.bottom ? `calc((1 - var(--kb-open, 0)) * env(safe-area-inset-bottom))` : undefined,
+        }}
+        className={mx('relative bs-full flex flex-col overflow-hidden', classNames)}
+        ref={forwardedRef}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+
+MobileLayoutPanel.displayName = MOBILE_LAYOUT_PANEL_NAME;
+
+//
+// Exports
+//
+
+export const MobileLayout = {
+  Root: MobileLayoutRoot,
+  Panel: MobileLayoutPanel,
+};
+
+export { useMobileLayout };
+
+export type { MobileLayoutRootProps, MobileLayoutPanelProps };
+
+/**
+ * Prevent auto-scroll when input is focused.
+ */
+const useAutoScroll = () => {
+  useEffect(() => {
+    // Prevent auto-scroll when input is focused.
+    return addEventListener(
+      document,
+      'focus',
+      (event: FocusEvent) => {
+        const target = event.target as HTMLElement;
+        if (
+          target.tagName === 'INPUT' ||
+          target.tagName === 'TEXTAREA' ||
+          (target.tagName === 'DIV' && target.isContentEditable)
+        ) {
+          // Prevent default focus behavior.
+          event.preventDefault();
+
+          // Manually focus without scroll.
+          target.focus({ preventScroll: true });
+
+          // Lock current scroll position.
+          const scrollX = window.scrollX;
+          const scrollY = window.scrollY;
+          requestAnimationFrame(() => {
+            window.scrollTo(scrollX, scrollY);
+          });
+
+          // TODO(burdon): Scroll to position in parent; this may need to be via an intent,
+          //  since it may be plugin-specific (e.g., codemirror document.)
+        }
+      },
+      // Important: focus events don't bubble, so capture phase is required.
+      { capture: true },
+    );
+  }, []);
+};
+
+/**
+ * Prevent iOS Safari viewport scroll when enabled.
+ * Setting overflow:hidden doesn't work on iOS, so we must preventDefault on touchmove events.
+ * Only allows scrolling if the target is within a scrollable container.
+ */
+const useLockBodyScroll = (enabled: boolean) => {
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const isScrollable = (el: HTMLElement | null, axis: 'x' | 'y'): boolean => {
+      while (el && el !== document.body) {
+        const style = getComputedStyle(el);
+        if (axis === 'y') {
+          const overflow = style.overflowY;
+          if ((overflow === 'auto' || overflow === 'scroll') && el.scrollHeight > el.clientHeight) {
+            return true;
+          }
+        } else {
+          const overflow = style.overflowX;
+          if ((overflow === 'auto' || overflow === 'scroll') && el.scrollWidth > el.clientWidth) {
+            return true;
+          }
+        }
+
+        el = el.parentElement;
+      }
+
+      return false;
+    };
+
+    let touchStartX = 0;
+    let touchStartY = 0;
+
+    return combine(
+      // Record initial touch position.
+      addEventListener(
+        document,
+        'touchstart',
+        (event: TouchEvent) => {
+          const touch = event.touches[0];
+          touchStartX = touch.clientX;
+          touchStartY = touch.clientY;
+        },
+        { passive: true },
+      ),
+
+      // Prevent scrolling the viewport.
+      addEventListener(
+        document,
+        'touchmove',
+        (event: TouchEvent) => {
+          const touch = event.touches[0];
+          const dx = Math.abs(touch.clientX - touchStartX);
+          const dy = Math.abs(touch.clientY - touchStartY);
+          if (!isScrollable(event.target as HTMLElement, dx > dy ? 'x' : 'y')) {
+            event.preventDefault();
+          }
+        },
+        { passive: false },
+      ),
+    );
+  }, [enabled]);
+};
+
+//
+// Hooks
+//
+
+type IOSKeyboard = {
+  open: boolean;
+  height: number;
+};
+
+/**
+ * Mobile container that handles iOS keyboard layout adjustments.
+ *
+ * Uses two strategies for keyboard detection:
+ * 1. Tauri iOS: Native keyboard plugin for reliable height/animation events.
+ * 2. Web/PWA: visualViewport API as fallback.
+ *
+ * iPhone (portrait, points)
+ * - Without predictive bar:  ~291 pt
+ * - With predictive bar:     ~335 pt
+ * - With accessory view:     ~380–420 pt
+ *
+ * Example:
+ * - Viewport: 874 (entire screen)
+ * - SafeArea: 96 (62+34)
+ * - Main:     778
+ * - Keyboard: 318; 413 (incl. Input Accessory View)
+ *
+ * CSS Variables set on document.documentElement:
+ * --vvh: Visual viewport height (use as container height).
+ * --kb-height: Keyboard height in pixels.
+ * --kb-open: 1 when keyboard is open, 0 when closed.
+ *
+ * NOTE: By default when an input is selected on iOS the Input Accessory View is shown above the keyboard.
+ * This can be disabled by setting the `inputAccessoryView` property to `false`.
+ *
+ * On iOS (Tauri), listens for 'keyboard' CustomEvents dispatched by the native KeyboardObserver.swift.
+ * Falls back to VisualViewport API on other platforms.
+ */
+const useIOSKeyboard = (): IOSKeyboard => {
+  const [open, setOpen] = useState(false);
+  const [height, setHeight] = useState(0);
+
+  // Detect keybaord state.
+  useEffect(() => {
+    const viewport = window.visualViewport;
+    if (!viewport) {
+      return;
+    }
+
+    // Handler for VisualViewport resize (fallback for non-iOS).
+    const initialHeight = viewport.height ?? window.innerHeight;
+
+    const updateState = (keyboardHeight: number, keyboardOpen: boolean) => {
+      setOpen(keyboardOpen);
+      setHeight(keyboardHeight);
+
+      const vvh = initialHeight - keyboardHeight;
+      document.documentElement.style.setProperty('--vvh', `${vvh}px`);
+      document.documentElement.style.setProperty('--kb-height', `${keyboardHeight}px`);
+      document.documentElement.style.setProperty('--kb-open', keyboardOpen ? '1' : '0');
+      log.info('viewport size', { initialHeight, vvh, keyboardHeight, keyboardOpen });
+    };
+
+    return combine(
+      // Handler for native iOS keyboard events (from KeyboardObserver.swift).
+      addEventListener(
+        window,
+        'keyboard' as any,
+        (event: CustomEvent<{ type: 'show' | 'hide'; height: number; duration: number }>) => {
+          const { type, height } = event.detail;
+          log.info('keyboard event', { type, height });
+          updateState(height, type === 'show');
+        },
+      ),
+    );
+  }, []);
+
+  return { open, height };
+};

package/src/components/MobileLayout/index.ts

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

package/src/components/Popover/Popover.tsx

@@ -5,10 +5,12 @@
 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 { Surface } from '@dxos/app-framework/ui';
+import { Popover, type PopoverContentInteractOutsideEvent, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { Card } from '@dxos/react-ui-mosaic';
 
-import { SimpleLayoutState } from '../../types';
+import { useSimpleLayoutState } from '../../hooks';
+import { meta } from '../../meta';
 
 const DEBOUNCE_DELAY = 40;
 
@@ -19,7 +21,7 @@ type LayoutPopoverContextValue = {
 const [LayoutPopoverProvider, useLayoutPopoverContext] = createContext<LayoutPopoverContextValue>('LayoutPopover');
 
 export const PopoverRoot = ({ children }: PropsWithChildren) => {
-  const layout = useCapability(SimpleLayoutState);
+  const { state } = useSimpleLayoutState();
   const [open, setOpen] = useState(false);
   const virtualRef = useRef<HTMLButtonElement | null>(null);
   const [virtualIter, setVirtualIter] = useState(0);
@@ -29,22 +31,22 @@ export const PopoverRoot = ({ children }: PropsWithChildren) => {
   //  the anchor further down the tree or measuring the virtual trigger's client rect.
   useEffect(() => {
     setOpen(false);
-    if (layout.popoverOpen) {
+    if (state.popoverOpen) {
       if (debounceRef.current) {
         clearTimeout(debounceRef.current);
       }
-      if (layout.popoverAnchor && virtualRef.current !== layout.popoverAnchor) {
-        virtualRef.current = layout.popoverAnchor ?? null;
+      if (state.popoverAnchor && virtualRef.current !== state.popoverAnchor) {
+        virtualRef.current = state.popoverAnchor ?? null;
         setVirtualIter((iter) => iter + 1);
       }
       debounceRef.current = setTimeout(() => setOpen(true), DEBOUNCE_DELAY);
     }
-  }, [layout.popoverOpen, layout.popoverAnchorId, layout.popoverAnchor, layout.popoverContent]);
+  }, [state.popoverOpen, state.popoverAnchorId, state.popoverAnchor, state.popoverContent]);
 
   return (
     <LayoutPopoverProvider setOpen={setOpen}>
       <Popover.Root modal={false} open={open}>
-        {layout.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
+        {state.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
         {children}
       </Popover.Root>
     </LayoutPopoverProvider>
@@ -52,10 +54,22 @@ export const PopoverRoot = ({ children }: PropsWithChildren) => {
 };
 
 export const PopoverContent = () => {
-  const layout = useCapability(SimpleLayoutState);
+  const { t } = useTranslation(meta.id);
+  const { state, updateState } = useSimpleLayoutState();
   const { setOpen } = useLayoutPopoverContext('PopoverContent');
 
-  const handleClose = useCallback(
+  const handleClose = useCallback(() => {
+    setOpen(false);
+    updateState((s) => ({
+      ...s,
+      popoverOpen: false,
+      popoverAnchor: undefined,
+      popoverAnchorId: undefined,
+      popoverSide: undefined,
+    }));
+  }, [setOpen, updateState]);
+
+  const handleInteractOutside = useCallback(
     (event: KeyboardEvent | PopoverContentInteractOutsideEvent) => {
       if (
         // TODO(thure): CodeMirror should not focus itself when it updates.
@@ -64,36 +78,40 @@ export const PopoverContent = () => {
       ) {
         event.preventDefault();
       } else {
-        setOpen(false);
-        layout.popoverOpen = false;
-        layout.popoverAnchor = undefined;
-        layout.popoverAnchorId = undefined;
-        layout.popoverSide = undefined;
+        handleClose();
       }
     },
-    [setOpen],
+    [handleClose],
   );
 
   const collisionBoundaries: HTMLElement[] = useMemo(() => {
-    const closest = layout.popoverAnchor?.closest('[data-popover-collision-boundary]') as
-      | HTMLElement
-      | null
-      | undefined;
+    const closest = state.popoverAnchor?.closest('[data-popover-collision-boundary]') as HTMLElement | null | undefined;
     return closest ? [closest] : [];
-  }, [layout.popoverAnchor]);
+  }, [state.popoverAnchor]);
 
   return (
     <Popover.Portal>
       <Popover.Content
-        side={layout.popoverSide}
-        onInteractOutside={handleClose}
-        onEscapeKeyDown={handleClose}
-        collisionBoundary={collisionBoundaries}
+        side={state.popoverSide}
         sticky='always'
         hideWhenDetached
+        collisionBoundary={collisionBoundaries}
+        onInteractOutside={handleInteractOutside}
+        onEscapeKeyDown={handleInteractOutside}
       >
         <Popover.Viewport>
-          <Surface role='card--popover' data={layout.popoverContent} limit={1} />
+          {state.popoverKind === 'base' && <Surface.Surface role='popover' data={state.popoverContent} limit={1} />}
+          {state.popoverKind === 'card' && (
+            <Card.Root border={false} classNames='popover-card-max-width'>
+              <Card.Toolbar>
+                {/* TODO(wittjosiah): Cleaner way to handle no drag handle in toolbar? */}
+                <span />
+                {state.popoverTitle ? <Card.Title>{toLocalizedString(state.popoverTitle, t)}</Card.Title> : <span />}
+                <Card.Close onClick={handleClose} />
+              </Card.Toolbar>
+              <Surface.Surface role='card--content' data={state.popoverContent} limit={1} />
+            </Card.Root>
+          )}
         </Popover.Viewport>
         <Popover.Arrow />
       </Popover.Content>

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

@@ -0,0 +1,144 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+import { type Mock, expect, fn, screen, userEvent, within } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ActionGraphProps, createMenuAction } from '@dxos/react-ui-menu';
+import { withRegistry } from '@dxos/storybook-utils';
+
+import { translations } from '../../translations';
+import { MobileLayout } from '../MobileLayout';
+
+import { AppBar, type AppBarProps } from './AppBar';
+
+const buildEmptyActions = (): ActionGraphProps => ({ nodes: [], edges: [] });
+
+const buildDefaultActions = (): ActionGraphProps => {
+  const result: ActionGraphProps = { nodes: [], edges: [] };
+  const actions = [
+    createMenuAction('action-edit', () => console.log('Edit'), {
+      icon: 'ph--pencil--regular',
+      label: 'Edit',
+    }),
+    createMenuAction('action-share', () => console.log('Share'), {
+      icon: 'ph--share--regular',
+      label: 'Share',
+    }),
+    createMenuAction('action-delete', () => console.log('Delete'), {
+      icon: 'ph--trash--regular',
+      label: 'Delete',
+    }),
+  ];
+  result.nodes.push(...actions);
+  result.edges.push(...actions.map((a) => ({ source: 'root', target: a.id })));
+  return result;
+};
+
+type StoryProps = Omit<AppBarProps, 'actions'> & {
+  actions: ActionGraphProps;
+};
+
+const DefaultStory = ({ actions: actionsProp, ...props }: StoryProps) => {
+  const actions = useMemo(() => Atom.make(actionsProp).pipe(Atom.keepAlive), [actionsProp]);
+  return (
+    <MobileLayout.Root>
+      <AppBar {...props} actions={actions} />
+    </MobileLayout.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-simple-layout/AppBar',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({
+      layout: 'column',
+      classNames: 'relative',
+    }),
+    withRegistry,
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<StoryProps>;
+
+export const Default: Story = {
+  tags: ['test'],
+  args: {
+    actions: buildDefaultActions(),
+    title: 'Document Title',
+    showBackButton: true,
+    onAction: fn(),
+    onBack: fn(),
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Verify the banner renders with the correct title.
+    await expect(canvas.getByRole('banner')).toBeInTheDocument();
+    await expect(canvas.getByText('Document Title')).toBeInTheDocument();
+
+    // Test back button click.
+    const backButton = canvas.getByRole('button', { name: /back/i });
+    await expect(backButton).toBeInTheDocument();
+    await userEvent.click(backButton);
+    await expect(args.onBack).toHaveBeenCalledTimes(1);
+
+    // Test actions menu opens and action fires.
+    const menuTrigger = canvas.getByRole('button', { name: /actions/i });
+    await expect(menuTrigger).toBeInTheDocument();
+    await userEvent.click(menuTrigger);
+
+    // Wait for menu to open and click an action (menu items render in a portal).
+    const editAction = await screen.findByRole('menuitem', { name: /edit/i });
+    await userEvent.click(editAction);
+    await expect(args.onAction).toHaveBeenCalledTimes(1);
+    await expect((args.onAction as Mock).mock.calls[0][0]).toHaveProperty('id', 'action-edit');
+  },
+};
+
+export const NoBackButton: Story = {
+  args: {
+    actions: buildDefaultActions(),
+    title: 'Home',
+    showBackButton: false,
+    onAction: (action) => console.log('Action:', action.id),
+  },
+};
+
+export const LongTitle: Story = {
+  args: {
+    actions: buildDefaultActions(),
+    title: 'This is a very long document title that should be truncated when it exceeds the available space',
+    showBackButton: true,
+    onBack: () => console.log('Back clicked'),
+    onAction: (action) => console.log('Action:', action.id),
+  },
+};
+
+export const NoActions: Story = {
+  args: {
+    actions: buildEmptyActions(),
+    title: 'Empty Document',
+    showBackButton: true,
+    onBack: () => console.log('Back clicked'),
+    onAction: (action) => console.log('Action:', action.id),
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    actions: buildEmptyActions(),
+  },
+};

package/src/components/SimpleLayout/AppBar.tsx

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import React, { Fragment } from 'react';
+
+import { IconButton, Popover, type ThemedClassName, Toolbar, useTranslation } from '@dxos/react-ui';
+import {
+  type ActionExecutor,
+  type ActionGraphProps,
+  DropdownMenu,
+  MenuProvider,
+  useMenuActions,
+} from '@dxos/react-ui-menu';
+import { mx, osTranslations } from '@dxos/ui-theme';
+
+import { meta } from '../../meta';
+import { useMobileLayout } from '../MobileLayout';
+
+const APP_BAR_NAME = 'SimpleLayout.AppBar';
+
+export type AppBarProps = ThemedClassName<{
+  /** Title/label to display in the banner. */
+  title?: string;
+  /** Action graph atom for the dropdown menu. */
+  actions: Atom.Atom<ActionGraphProps>;
+  /** Whether to show the back button. */
+  showBackButton?: boolean;
+  /** Popover anchor ID for the dropdown trigger. */
+  popoverAnchorId?: string;
+  /** Action executor callback. */
+  onAction?: ActionExecutor;
+  /** Callback when back button is clicked. */
+  onBack?: () => void;
+}>;
+
+/**
+ * AppBar component that renders a title, optional back button, and actions dropdown.
+ */
+export const AppBar = ({
+  classNames,
+  title,
+  actions,
+  showBackButton,
+  popoverAnchorId,
+  onAction,
+  onBack,
+}: AppBarProps) => {
+  const { t } = useTranslation(meta.id);
+  const menu = useMenuActions(actions);
+  const actionsValue = useAtomValue(actions);
+  const hasActions = actionsValue.nodes.length > 0;
+  const { keyboardOpen } = useMobileLayout(APP_BAR_NAME);
+
+  // Fall back to app name if no title provided.
+  const displayTitle = title ?? t('current app name', { ns: osTranslations });
+
+  // Wrap the menu trigger with Popover.Anchor when the popoverAnchorId is set.
+  const AnchorRoot = popoverAnchorId ? Popover.Anchor : Fragment;
+
+  return (
+    <Toolbar.Root
+      role='banner'
+      classNames={mx(
+        'grid grid-cols-[var(--rail-size)_1fr_var(--rail-size)] bs-[var(--rail-action)] items-center',
+        'density-fine',
+        classNames,
+      )}
+    >
+      {keyboardOpen ? (
+        <IconButton variant='ghost' icon='ph--x--regular' iconOnly label={t('done label')} />
+      ) : showBackButton ? (
+        <IconButton variant='ghost' icon='ph--caret-left--regular' iconOnly label={t('back label')} onClick={onBack} />
+      ) : (
+        <div />
+      )}
+      <h1 className='text-center truncate font-thin uppercase'>{displayTitle}</h1>
+      {hasActions ? (
+        <AnchorRoot>
+          <MenuProvider {...menu} onAction={onAction}>
+            <DropdownMenu.Root caller={meta.id}>
+              <DropdownMenu.Trigger asChild>
+                <IconButton
+                  variant='ghost'
+                  icon='ph--dots-three-vertical--regular'
+                  iconOnly
+                  label={t('actions menu label')}
+                />
+              </DropdownMenu.Trigger>
+            </DropdownMenu.Root>
+          </MenuProvider>
+        </AnchorRoot>
+      ) : (
+        <span />
+      )}
+    </Toolbar.Root>
+  );
+};
+
+AppBar.displayName = APP_BAR_NAME;