fix(core): support multiple submenu viewport bindings and root restore

Settings menus register two submenu panels; bindChild previously replaced
the active subscription so viewport transitions never ran for the first
panel. Track bindings per view, restore the root panel when returning from
a submenu, and animate initial open height via syncRoot.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sampotts

packages/core/src/dom/ui/menu/create-menu.ts

@@ -286,7 +286,8 @@ export function createMenu(options: MenuOptions): MenuApi {
       openRafId = 0;
       // Root view children may connect after the menu host (HTML custom elements).
       // Re-measure on open so viewport CSS variables reflect the mounted panel.
-      viewport?.syncRoot(getNavigationInput().current.stack.length > 0);
+      const hasActiveSubmenu = getNavigationInput().current.stack.length > 0;
+      viewport?.syncRoot(hasActiveSubmenu, { animate: !hasActiveSubmenu });
       // Guard against close() being called before the RAF fires — active
       // stays true during the closing animation, so also check status.
       if (!popover.input.current.active || popover.input.current.status === 'ending' || highlightedItem) return;

packages/core/src/dom/ui/menu/menu-viewport.ts

@@ -31,12 +31,17 @@ export interface MenuViewportAttrs {
   'data-menu-viewport': '';
 }
 
+export interface MenuViewportSyncRootOptions {
+  /** Animate viewport width/height when establishing the root panel size (e.g. first open). */
+  animate?: boolean;
+}
+
 export interface MenuViewportApi {
   /**
    * When no submenu is on the navigation stack, remeasure and size for the root panel.
    * With an active submenu, only preserves `data-transitioning` during in-flight resizes.
    */
-  syncRoot(hasActiveSubmenu: boolean): void;
+  syncRoot(hasActiveSubmenu: boolean, options?: MenuViewportSyncRootOptions): void;
   /** Subscribe to a submenu view transition and drive viewport/root coordination. */
   bindChild(view: HTMLElement, transition: MenuViewTransitionApi): () => void;
   destroy(): void;
@@ -63,7 +68,7 @@ interface MenuViewportState {
   navigation: MenuViewportNavigationContext | null;
   viewportTransitionId: number;
   viewportTransitioning: boolean;
-  childUnsubscribe: (() => void) | null;
+  childUnsubscribes: Map<HTMLElement, () => void>;
   rootAttrsUnsubscribe: (() => void) | null;
   cancelViewportSettle: (() => void) | null;
   childPhaseKeys: WeakMap<HTMLElement, string>;
@@ -375,7 +380,11 @@ function restoreRootPanelToResting(state: MenuViewportState): void {
   setViewportSize(state.content, size);
 }
 
-function syncRoot(state: MenuViewportState, hasActiveSubmenu: boolean): void {
+function syncRoot(
+  state: MenuViewportState,
+  hasActiveSubmenu: boolean,
+  options: MenuViewportSyncRootOptions = {}
+): void {
   const { content } = state;
 
   if (hasActiveSubmenu) {
@@ -394,7 +403,32 @@ function syncRoot(state: MenuViewportState, hasActiveSubmenu: boolean): void {
   // to root size before the back animation finishes.
   if (!rootView || getActiveMenuViewElement(viewport)) return;
 
+  connectRootView(state, rootView);
+
+  const rootPhase = state.rootTransition.input.current.phase;
+
+  if (rootPhase !== 'active' && rootPhase !== 'entering') {
+    state.rootTransition.sync({
+      active: true,
+      direction: state.navigation?.direction() ?? 'back',
+      triggerId: null,
+    });
+  }
+
   const size = measureRootMenuView(state, rootView, resolveMeasureMinWidth(content));
+  const current = getCurrentViewportSize(content);
+
+  if (options.animate && (!current || !isContentSizeValid(current))) {
+    const fromSize: ContentSize =
+      current && current.width > 0 ? { width: current.width, height: 0 } : { width: size.width, height: 0 };
+    const viewportTransitionId = startViewportTransition(state);
+
+    setViewportSize(content, fromSize);
+    forceLayout(content);
+    setViewportSize(content, size);
+    scheduleViewportTransitionAttrsClear(state, viewportTransitionId);
+    return;
+  }
 
   clearViewportTransition(state);
   setViewportSize(content, size);
@@ -423,7 +457,7 @@ export function createMenuViewport(
     navigation: options.navigation ?? null,
     viewportTransitionId: 0,
     viewportTransitioning: false,
-    childUnsubscribe: null,
+    childUnsubscribes: new Map(),
     rootAttrsUnsubscribe: null,
     cancelViewportSettle: null,
     childPhaseKeys: new WeakMap(),
@@ -436,13 +470,11 @@ export function createMenuViewport(
   }
 
   return {
-    syncRoot(hasActiveSubmenu) {
-      syncRoot(state, hasActiveSubmenu);
+    syncRoot(hasActiveSubmenu, options) {
+      syncRoot(state, hasActiveSubmenu, options);
     },
 
     bindChild(view, transition) {
-      state.childUnsubscribe?.();
-
       const syncChild = (): void => {
         const viewState = transition.input.current;
         const phaseKey = `${viewState.phase}:${viewState.direction}`;
@@ -453,23 +485,31 @@ export function createMenuViewport(
         syncChildViewPhase(state, view, viewState);
       };
 
+      state.childUnsubscribes.get(view)?.();
+
       const unsubscribe = transition.input.subscribe(syncChild);
-      state.childUnsubscribe = unsubscribe;
+      state.childUnsubscribes.set(view, unsubscribe);
       syncChild();
 
       return () => {
+        const existing = state.childUnsubscribes.get(view);
+
+        if (existing !== unsubscribe) return;
+
         unsubscribe();
-        if (state.childUnsubscribe === unsubscribe) {
-          state.childUnsubscribe = null;
-        }
+        state.childUnsubscribes.delete(view);
         state.childPhaseKeys.delete(view);
       };
     },
 
     destroy() {
       state.viewportTransitionId += 1;
-      state.childUnsubscribe?.();
-      state.childUnsubscribe = null;
+
+      for (const unsubscribe of state.childUnsubscribes.values()) {
+        unsubscribe();
+      }
+
+      state.childUnsubscribes.clear();
       state.rootAttrsUnsubscribe?.();
       state.rootAttrsUnsubscribe = null;
       state.cancelViewportSettle?.();

packages/core/src/dom/ui/menu/tests/menu-viewport.test.ts

@@ -44,6 +44,7 @@ function createMockTransition(state: MenuViewTransitionState): MenuViewTransitio
 
 interface ViewportSyncOptions {
   hasActiveSubmenu?: boolean;
+  animate?: boolean;
   view?: HTMLElement | null;
   viewState?: MenuViewTransitionState | null;
 }
@@ -52,10 +53,10 @@ function syncMenuViewport(content: HTMLElement | null, sync: ViewportSyncOptions
   if (!content) return;
 
   const viewport = getViewport(content);
-  const { hasActiveSubmenu = false, view = null, viewState = null } = sync;
+  const { hasActiveSubmenu = false, animate, view = null, viewState = null } = sync;
 
   if (!view || !viewState) {
-    viewport.syncRoot(hasActiveSubmenu);
+    viewport.syncRoot(hasActiveSubmenu, animate ? { animate } : undefined);
     flush();
     return;
   }
@@ -600,6 +601,64 @@ describe('createMenuViewport', () => {
     expect(resetSpy).not.toHaveBeenCalled();
   });
 
+  it('keeps earlier submenu views subscribed when additional views register', () => {
+    const content = addElement();
+    const rootView = document.createElement('div');
+    const firstView = document.createElement('div');
+    const secondView = document.createElement('div');
+
+    applyAttrs(rootView, getMenuViewAttrs({ root: true }));
+    firstView.setAttribute('data-menu-view', '');
+    secondView.setAttribute('data-menu-view', '');
+    content.append(rootView, firstView, secondView);
+
+    mockMenuViewSize(rootView, {
+      currentWidth: 160,
+      currentHeight: 100,
+      naturalWidth: 160,
+      naturalHeight: 100,
+    });
+    mockMenuViewSize(firstView, {
+      currentWidth: 200,
+      currentHeight: 120,
+      naturalWidth: 200,
+      naturalHeight: 120,
+    });
+    mockMenuViewSize(secondView, {
+      currentWidth: 240,
+      currentHeight: 140,
+      naturalWidth: 240,
+      naturalHeight: 140,
+    });
+
+    const viewport = createMenuViewport(content);
+
+    const firstTransition = createMockTransition({
+      phase: 'hidden',
+      direction: 'forward',
+      triggerId: 'trigger-1',
+    });
+    const secondTransition = createMockTransition({
+      phase: 'hidden',
+      direction: 'forward',
+      triggerId: 'trigger-2',
+    });
+
+    viewport.bindChild(firstView, firstTransition);
+    viewport.bindChild(secondView, secondTransition);
+    secondView.hidden = true;
+
+    (firstTransition.input as WritableState<MenuViewTransitionState>).patch({
+      phase: 'entering',
+      direction: 'forward',
+      triggerId: 'trigger-1',
+    });
+    flush();
+
+    expect(content.style.getPropertyValue('--media-menu-width')).toBe('160px');
+    expect(content.style.getPropertyValue('--media-menu-height')).toBe('100px');
+  });
+
   it('bindChild cleanup only unsubscribes the view it bound', () => {
     const content = addElement();
     const rootView = document.createElement('div');
@@ -937,4 +996,64 @@ describe('createMenuViewport', () => {
     expect(content.style.getPropertyValue('--media-menu-width')).toBe('160px');
     expect(content.style.getPropertyValue('--media-menu-height')).toBe('');
   });
+
+  it('restores the root panel when syncRoot runs after the root was hidden for a submenu', () => {
+    const content = addElement();
+    const rootView = document.createElement('div');
+    const menuView = document.createElement('div');
+
+    applyAttrs(rootView, getMenuViewAttrs({ root: true }));
+    menuView.setAttribute('data-menu-view', '');
+    content.append(rootView, menuView);
+
+    mockMenuViewSize(rootView, {
+      currentWidth: 180,
+      currentHeight: 74,
+      naturalWidth: 180,
+      naturalHeight: 74,
+    });
+
+    const rootTransition = createMenuViewTransition({ persistent: true });
+    let hasActiveSubmenu = true;
+    const viewport = createMenuViewport(content, rootTransition, {
+      navigation: {
+        hasActiveSubmenu: () => hasActiveSubmenu,
+        direction: () => 'back' as const,
+      },
+    });
+
+    viewport.syncRoot(true);
+    flush();
+
+    expect(rootView.hasAttribute('data-open')).toBe(false);
+
+    hasActiveSubmenu = false;
+    menuView.hidden = true;
+    viewport.syncRoot(false);
+    flush();
+
+    expect(rootView.hasAttribute('data-open')).toBe(true);
+    expect(content.style.getPropertyValue('--media-menu-height')).toBe('74px');
+  });
+
+  it('animates the initial root viewport size when animate is requested', () => {
+    const content = addElement();
+    const rootView = document.createElement('div');
+
+    applyAttrs(rootView, getMenuViewAttrs({ root: true }));
+    content.append(rootView);
+
+    mockMenuViewSize(rootView, {
+      currentWidth: 180,
+      currentHeight: 74,
+      naturalWidth: 180,
+      naturalHeight: 74,
+    });
+
+    syncMenuViewport(content, { animate: true });
+
+    expect(content.hasAttribute('data-transitioning')).toBe(true);
+    expect(content.style.getPropertyValue('--media-menu-width')).toBe('180px');
+    expect(content.style.getPropertyValue('--media-menu-height')).toBe('74px');
+  });
 });