@ds-mo/ui 1.10.0 → 1.11.0

package/src/wc/components/AppShell/AppShell.tsx

@@ -1,5 +1,16 @@
 import { Component, Prop, Element, Watch, h, Host } from '@stencil/core';
 import type { NavChromeStyle } from '../../nav/nav-chrome';
+import {
+  CHROME_TRANSITION_END,
+  CHROME_TRANSITION_START,
+  type ChromeTransitionDetail,
+} from '../../nav/chrome-transition';
+import {
+  isPanelNavCollapsed,
+  panelWidthPxFromTokens,
+  readPanelNavWidthTokens,
+  type PanelNavWidthTokens,
+} from '../../nav/shell-chrome-metrics';
 import {
   SHELL_GRADIENT_IMAGE_VAR,
   SHELL_GRADIENT_OPACITY,
@@ -22,9 +33,12 @@ export class AppShell {
   /** Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`. */
   @Prop({ attribute: 'nav-style', reflect: true }) navStyle: NavChromeStyle = 'dashboard';
 
-  /** When `true`, paints the shared chrome surface (bg + wash + grid) behind panel, bar, and tools. */
+  /** When `true`, paints the radial wash behind panel, bar, and tools (synced to shell layout). */
   @Prop({ reflect: true }) gradient: boolean = false;
 
+  /** When `true`, paints the diagonal grid overlay on the shared chrome layer. Independent of `gradient`. */
+  @Prop({ reflect: true }) grid: boolean = false;
+
   /**
    * Optional custom gradient for `background-image` (e.g. SVG URL).
    * When set, overrides the built-in radial wash.
@@ -34,31 +48,72 @@ export class AppShell {
   @Element() el!: HTMLElement;
 
   private resizeObserver: ResizeObserver | null = null;
+  private chromeSyncRafId = 0;
+  private chromeTransitionDepth = 0;
+  private panelWidthTokens: PanelNavWidthTokens = { expandedPx: 0, collapsedPx: 0 };
+  private cachedShellWidth = 0;
+  private cachedShellHeight = 0;
 
   componentDidLoad() {
     this.syncSlottedNavStyle();
     this.connectMetricsObserver();
-    this.scheduleChromeSync();
-  }
-
-  private scheduleChromeSync() {
-    this.syncChrome();
-    requestAnimationFrame(() => this.syncChrome());
+    this.el.addEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);
+    this.el.addEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);
+    requestAnimationFrame(() => {
+      this.cachePanelWidthTokens();
+      this.scheduleChromeSync();
+    });
   }
 
   disconnectedCallback() {
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
+    if (this.chromeSyncRafId) {
+      cancelAnimationFrame(this.chromeSyncRafId);
+      this.chromeSyncRafId = 0;
+    }
+    this.el.removeEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);
+    this.el.removeEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);
   }
 
   @Watch('navStyle')
   @Watch('gradient')
+  @Watch('grid')
   @Watch('gradientSrc')
   onShellPropsChange() {
     this.syncSlottedNavStyle();
     this.scheduleChromeSync();
   }
 
+  private onChromeTransitionStart = (event: Event) => {
+    const source = (event as CustomEvent<ChromeTransitionDetail>).detail?.source;
+    if (source === 'panel-nav') {
+      this.chromeTransitionDepth += 1;
+      this.cachedShellWidth = this.el.clientWidth;
+      this.cachedShellHeight = this.el.clientHeight;
+      this.syncChrome();
+    }
+  };
+
+  private onChromeTransitionEnd = (event: Event) => {
+    const source = (event as CustomEvent<ChromeTransitionDetail>).detail?.source;
+    if (source !== 'panel-nav') return;
+
+    this.chromeTransitionDepth = Math.max(0, this.chromeTransitionDepth - 1);
+    if (this.chromeTransitionDepth === 0) {
+      this.scheduleChromeSync();
+    }
+  };
+
+  /** Coalesce ResizeObserver bursts to one layout read per frame. */
+  private scheduleChromeSync() {
+    if (this.chromeSyncRafId) return;
+    this.chromeSyncRafId = requestAnimationFrame(() => {
+      this.chromeSyncRafId = 0;
+      this.syncChrome();
+    });
+  }
+
   private syncSlottedNavStyle() {
     const panel = this.el.querySelector('ds-panel-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;
     const bar = this.el.querySelector('ds-bar-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;
@@ -73,11 +128,19 @@ export class AppShell {
   }
 
   private connectMetricsObserver() {
-    this.resizeObserver = new ResizeObserver(() => this.scheduleChromeSync());
+    this.resizeObserver = new ResizeObserver(() => {
+      if (this.chromeTransitionDepth > 0) return;
+      this.scheduleChromeSync();
+    });
     this.resizeObserver.observe(this.el);
     const panelWrap = this.el.querySelector('.app-shell__panel');
     if (panelWrap) this.resizeObserver.observe(panelWrap);
-    this.scheduleChromeSync();
+  }
+
+  private cachePanelWidthTokens() {
+    const navRoot = this.el.querySelector('ds-panel-nav .panel-nav') as HTMLElement | null;
+    if (!navRoot) return;
+    this.panelWidthTokens = readPanelNavWidthTokens(navRoot);
   }
 
   private applyGradientVars(target: HTMLElement, vars: Record<string, string | null>) {
@@ -114,32 +177,79 @@ export class AppShell {
     }
   }
 
-  private syncChrome() {
-    const panel = this.el.querySelector('ds-panel-nav') as HTMLElement | null;
-    const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;
-    const targets = [this.el, panel, bar].filter((el): el is HTMLElement => el !== null);
+  private resolvePanelWidthPx(panelNav: HTMLElement | null): number {
+    const navRoot = panelNav?.querySelector('.panel-nav') as HTMLElement | null;
+
+    if (this.chromeTransitionDepth > 0 && this.panelWidthTokens.expandedPx > 0) {
+      const collapsed = isPanelNavCollapsed(panelNav, navRoot);
+      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);
+    }
 
-    const shellRect = this.el.getBoundingClientRect();
     const panelWrap = this.el.querySelector('.app-shell__panel') as HTMLElement | null;
-    const panelWidth = panelWrap?.getBoundingClientRect().width ?? 0;
+    const measured = panelWrap?.getBoundingClientRect().width ?? 0;
+    if (measured > 0) return measured;
 
-    const panelPosition = shellGradientPositionPanel();
-    const barPosition = shellGradientPositionBar(panelWidth);
+    if (this.panelWidthTokens.expandedPx > 0) {
+      const collapsed = isPanelNavCollapsed(panelNav, navRoot);
+      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);
+    }
 
-    this.syncChromeLayoutVars(panel, bar, panelPosition, barPosition);
+    return 0;
+  }
+
+  private resolveShellDimensions(): { width: number; height: number } {
+    if (this.chromeTransitionDepth > 0 && this.cachedShellWidth > 0) {
+      return {
+        width: this.cachedShellWidth,
+        height: this.cachedShellHeight || this.el.clientHeight,
+      };
+    }
+
+    const rect = this.el.getBoundingClientRect();
+    return { width: rect.width, height: rect.height };
+  }
+
+  private chromeLayerActive(): boolean {
+    return this.gradient || this.grid;
+  }
+
+  private syncChrome() {
+    const panelNav = this.el.querySelector('ds-panel-nav') as HTMLElement | null;
+    const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;
+    const targets = [this.el, panelNav, bar].filter((el): el is HTMLElement => el !== null);
+
+    const clearLayoutVars = () => {
+      if (panelNav) panelNav.style.removeProperty(SHELL_GRADIENT_POSITION_PANEL_VAR);
+      if (bar) bar.style.removeProperty(SHELL_GRADIENT_POSITION_BAR_VAR);
+    };
+
+    if (!this.chromeLayerActive()) {
+      this.clearGradientPaintVars(targets);
+      clearLayoutVars();
+      return;
+    }
 
     if (!this.gradient) {
       this.clearGradientPaintVars(targets);
+      clearLayoutVars();
       return;
     }
 
+    const { width: shellWidth, height: shellHeight } = this.resolveShellDimensions();
+    const panelWidth = this.resolvePanelWidthPx(panelNav);
+
+    const panelPosition = shellGradientPositionPanel();
+    const barPosition = shellGradientPositionBar(panelWidth);
+
+    this.syncChromeLayoutVars(panelNav, bar, panelPosition, barPosition);
+
     const image = this.gradientSrc.trim()
       ? `url(${this.gradientSrc.trim()})`
       : buildShellRadialGradient();
 
     const size = shellGradientSize({
-      width: shellRect.width,
-      height: shellRect.height,
+      width: shellWidth,
+      height: shellHeight,
       panelWidth,
     });
     const opacity = SHELL_GRADIENT_OPACITY;
@@ -168,16 +278,18 @@ export class AppShell {
   }
 
   render() {
+    const chromeActive = this.chromeLayerActive();
     const shellCls: Record<string, boolean> = {
       'app-shell': true,
       'app-shell--gradient': this.gradient,
+      'app-shell--grid': this.grid,
       [`app-shell--${this.navStyle}`]: true,
     };
 
     return (
       <Host class={shellCls}>
         <div class="app-shell__row">
-          {this.gradient ? <div class="app-shell__chrome" aria-hidden="true" /> : null}
+          {chromeActive ? <div class="app-shell__chrome" aria-hidden="true" /> : null}
           <div class="app-shell__panel">
             <slot name="panel" />
           </div>

package/src/wc/components/BarNav/BarNav.tsx

@@ -28,6 +28,12 @@ import {
   tabsOverflowContainer,
   tabsToMenuSections,
 } from './bar-nav-tabs-menu-utils';
+import {
+  CHROME_TRANSITION_END,
+  CHROME_TRANSITION_START,
+  type ChromeTransitionDetail,
+} from '../../nav/chrome-transition';
+import { readCssVarWidthPx } from '../../nav/shell-chrome-metrics';
 
 @Component({
   tag: 'ds-bar-nav',
@@ -91,6 +97,7 @@ export class BarNav {
 
   private static readonly HOST_PROP_SYNC_BUDGET = 8;
   private static readonly INTRINSIC_WIDTH_RETRY_MAX = 3;
+  private static readonly OVERFLOW_HYSTERESIS_PX = 8;
 
   private headerEl: HTMLElement | null = null;
   private triggerEl: HTMLButtonElement | null = null;
@@ -102,6 +109,9 @@ export class BarNav {
   private resizeObserver: ResizeObserver | null = null;
   private overflowCheckScheduled = false;
   private intrinsicWidthRetryCount = 0;
+  private chromeTransitionDepth = 0;
+  private chromeTransitionShell: HTMLElement | null = null;
+  private toolsDrawerOpening = false;
   /** Matches `basePath` once tabs + URL are reconciled for the active section. */
   @State() private committedSection = '';
   /** Section waiting for URL + tabs to catch up after a cross-area navigation. */
@@ -174,10 +184,15 @@ export class BarNav {
     this.syncHostPropsIfNeeded();
     this.scheduleDeferredHostPropSync();
     this.setupOverflowObserver();
+    this.bindChromeTransitionListeners();
     this.scheduleOverflowCheck();
   }
 
   componentDidRender() {
+    if (this.chromeTransitionDepth > 0) {
+      this.syncMenuAnchor();
+      return;
+    }
     this.scheduleOverflowCheck();
     this.syncMenuAnchor();
     if (this.tabsCollapsed) {
@@ -189,8 +204,63 @@ export class BarNav {
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
     this.syncTriggerLabelObserver(true);
+    this.unbindChromeTransitionListeners();
   }
 
+  private bindChromeTransitionListeners() {
+    const shell = this.el.closest('ds-app-shell');
+    if (!shell) return;
+    this.chromeTransitionShell = shell;
+    shell.addEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);
+    shell.addEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);
+  }
+
+  private unbindChromeTransitionListeners() {
+    if (!this.chromeTransitionShell) return;
+    this.chromeTransitionShell.removeEventListener(
+      CHROME_TRANSITION_START,
+      this.onChromeTransitionStart,
+    );
+    this.chromeTransitionShell.removeEventListener(
+      CHROME_TRANSITION_END,
+      this.onChromeTransitionEnd,
+    );
+    this.chromeTransitionShell = null;
+  }
+
+  private onChromeTransitionStart = (event: Event) => {
+    const source = (event as CustomEvent<ChromeTransitionDetail>).detail?.source;
+    if (source === 'panel-nav') {
+      this.chromeTransitionDepth += 1;
+      return;
+    }
+    if (source === 'panel-tools') {
+      this.toolsDrawerOpening = true;
+      this.el.classList.add('bar-nav--tools-drawer-opening');
+      if (this.resolvedTabs.length > 0 && !this.hideTabsForDetailRoute) {
+        this.tabsCollapsed = true;
+        this.menuOpen = false;
+      }
+      this.scheduleOverflowCheck();
+    }
+  };
+
+  private onChromeTransitionEnd = (event: Event) => {
+    const source = (event as CustomEvent<ChromeTransitionDetail>).detail?.source;
+    if (source === 'panel-nav') {
+      this.chromeTransitionDepth = Math.max(0, this.chromeTransitionDepth - 1);
+      if (this.chromeTransitionDepth === 0) {
+        this.scheduleOverflowCheck();
+      }
+      return;
+    }
+    if (source === 'panel-tools') {
+      this.toolsDrawerOpening = false;
+      this.el.classList.remove('bar-nav--tools-drawer-opening');
+      this.scheduleOverflowCheck();
+    }
+  };
+
   /** Re-resolve props assigned by the host after componentWillLoad (Angular ngAfterViewInit). */
   private syncHostPropsIfNeeded() {
     if (
@@ -224,15 +294,20 @@ export class BarNav {
   private setupOverflowObserver() {
     if (typeof ResizeObserver === 'undefined' || !this.headerEl) return;
     this.resizeObserver?.disconnect();
-    this.resizeObserver = new ResizeObserver(() => this.scheduleOverflowCheck());
+    this.resizeObserver = new ResizeObserver(() => {
+      if (this.chromeTransitionDepth > 0) return;
+      this.scheduleOverflowCheck();
+    });
     this.resizeObserver.observe(this.headerEl);
   }
 
   private scheduleOverflowCheck() {
+    if (this.chromeTransitionDepth > 0) return;
     if (this.overflowCheckScheduled) return;
     this.overflowCheckScheduled = true;
     requestAnimationFrame(() => {
       this.overflowCheckScheduled = false;
+      if (this.chromeTransitionDepth > 0) return;
       this.updateTabsCollapsed();
       this.updateTriggerLabelTruncation();
     });
@@ -292,7 +367,20 @@ export class BarNav {
     const available =
       this.headerEl.clientWidth - horizontalPadding - actionsWidth - spacing;
 
-    return Math.max(0, available);
+    return Math.max(0, available - this.toolsDrawerOpeningReservePx());
+  }
+
+  /** While the tools drawer is opening, reserve width not yet claimed by flex shrink. */
+  private toolsDrawerOpeningReservePx(): number {
+    if (!this.toolsDrawerOpening) return 0;
+
+    const tools = this.el.closest('ds-app-shell')?.querySelector('ds-panel-tools') as HTMLElement | null;
+    if (!tools) return 0;
+
+    const drawerTarget = readCssVarWidthPx(tools, '--_panel-tools-drawer-width');
+    const drawerNow =
+      tools.querySelector('.panel-tools__drawer')?.getBoundingClientRect().width ?? 0;
+    return Math.max(0, drawerTarget - drawerNow);
   }
 
   private getTabsIntrinsicWidth(): number {
@@ -327,6 +415,7 @@ export class BarNav {
       intrinsicWidth,
       this.getLeftZoneAvailableWidth(),
       this.tabsCollapsed,
+      BarNav.OVERFLOW_HYSTERESIS_PX,
     );
 
     if (shouldCollapse !== this.tabsCollapsed) {

package/src/wc/components/PanelNav/PanelNav.tsx

@@ -1,4 +1,5 @@
 import { Component, Prop, Event, EventEmitter, Watch, State, Element, h, Host } from '@stencil/core';
+import type { ChromeTransitionDetail } from '../../nav/chrome-transition';
 import type { NavChromeStyle } from '../../nav/nav-chrome';
 import {
   deriveActiveIdFromUrl,
@@ -69,6 +70,13 @@ export class PanelNav {
   /** Emitted when the collapse toggle is clicked. Detail = new collapsed state. */
   @Event() dsNavToggle!: EventEmitter<boolean>;
 
+  /** Bubbling lifecycle — `ds-app-shell` pauses chrome metrics during width motion. */
+  @Event({ bubbles: true, composed: true })
+  dsChromeTransitionStart!: EventEmitter<ChromeTransitionDetail>;
+
+  @Event({ bubbles: true, composed: true })
+  dsChromeTransitionEnd!: EventEmitter<ChromeTransitionDetail>;
+
   /** Emitted when the footer left button (gear / dashboard) is clicked. */
   @Event() dsNavFooterAction!: EventEmitter<void>;
 
@@ -181,6 +189,7 @@ export class PanelNav {
 
   private startCollapseAnimation() {
     this.isAnimating = true;
+    this.dsChromeTransitionStart.emit({ source: 'panel-nav' });
     const panel = this.el.querySelector('.panel-nav') as HTMLElement | null;
     if (this.transitionEndHandler) {
       panel?.removeEventListener('transitionend', this.transitionEndHandler);
@@ -188,6 +197,7 @@ export class PanelNav {
     this.transitionEndHandler = (e: TransitionEvent) => {
       if (e.propertyName === 'width') {
         this.isAnimating = false;
+        this.dsChromeTransitionEnd.emit({ source: 'panel-nav' });
         panel?.removeEventListener('transitionend', this.transitionEndHandler!);
       }
     };

package/src/wc/components/PanelTools/PanelTools.tsx

@@ -1,4 +1,5 @@
 import { Component, Prop, Event, EventEmitter, Element, State, Watch, h, Host } from '@stencil/core';
+import type { ChromeTransitionDetail } from '../../nav/chrome-transition';
 import {
   PANEL_TOOLS_LABELS,
   PANEL_TOOLS_PRIMARY_TOOL_ID,
@@ -37,6 +38,13 @@ export class PanelTools {
     selected: boolean;
   }>;
 
+  /** Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion. */
+  @Event({ bubbles: true, composed: true })
+  dsChromeTransitionStart!: EventEmitter<ChromeTransitionDetail>;
+
+  @Event({ bubbles: true, composed: true })
+  dsChromeTransitionEnd!: EventEmitter<ChromeTransitionDetail>;
+
   /** Arms open vs close easing for the in-flight width transition. */
   @State() private motion: 'opening' | 'closing' | 'idle' = 'idle';
 
@@ -74,6 +82,7 @@ export class PanelTools {
   openChanged(isOpen: boolean, wasOpen?: boolean) {
     if (this.readyForMotion && wasOpen !== undefined && wasOpen !== isOpen) {
       this.motion = isOpen ? 'opening' : 'closing';
+      this.dsChromeTransitionStart.emit({ source: 'panel-tools' });
     }
     this.deferMotionEnable();
   }
@@ -97,6 +106,7 @@ export class PanelTools {
     if (event.target !== this.el.querySelector('.panel-tools__drawer')) return;
     if (event.propertyName !== 'max-width') return;
     this.motion = 'idle';
+    this.dsChromeTransitionEnd.emit({ source: 'panel-tools' });
   };
 
   /** Rail selection follows `open` immediately — independent of the slide animation. */

package/src/wc/components.d.ts

@@ -26,6 +26,7 @@ import { MenuItemData, MenuSection } from "./components/Menu/menu-types";
 import { MenuAlign, MenuSide } from "./components/Menu/menu-position";
 import { ModalWidth } from "./components/Modal/Modal";
 import { PanelNavGroup, PanelNavRouterMode, PanelNavUserActionDetail } from "./components/PanelNav/panel-nav-types";
+import { ChromeTransitionDetail } from "./nav/chrome-transition";
 import { PanelToolsItem, PanelToolsToolId } from "./components/PanelTools/panel-tools-types";
 import { RadioOption } from "./components/RadioGroup/RadioGroup";
 import { ScrollbarVariant } from "./components/Scrollbar/Scrollbar";
@@ -63,6 +64,7 @@ export { MenuItemData, MenuSection } from "./components/Menu/menu-types";
 export { MenuAlign, MenuSide } from "./components/Menu/menu-position";
 export { ModalWidth } from "./components/Modal/Modal";
 export { PanelNavGroup, PanelNavRouterMode, PanelNavUserActionDetail } from "./components/PanelNav/panel-nav-types";
+export { ChromeTransitionDetail } from "./nav/chrome-transition";
 export { PanelToolsItem, PanelToolsToolId } from "./components/PanelTools/panel-tools-types";
 export { RadioOption } from "./components/RadioGroup/RadioGroup";
 export { ScrollbarVariant } from "./components/Scrollbar/Scrollbar";
@@ -97,7 +99,7 @@ export namespace Components {
     }
     interface DsAppShell {
         /**
-          * When `true`, paints the shared chrome surface (bg + wash + grid) behind panel, bar, and tools.
+          * When `true`, paints the radial wash behind panel, bar, and tools (synced to shell layout).
           * @default false
          */
         "gradient": boolean;
@@ -106,6 +108,11 @@ export namespace Components {
           * @default ''
          */
         "gradientSrc": string;
+        /**
+          * When `true`, paints the diagonal grid overlay on the shared chrome layer. Independent of `gradient`.
+          * @default false
+         */
+        "grid": boolean;
         /**
           * Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`.
           * @default 'dashboard'
@@ -1476,6 +1483,8 @@ declare global {
     interface HTMLDsPanelNavElementEventMap {
         "dsNavSelect": string;
         "dsNavToggle": boolean;
+        "dsChromeTransitionStart": ChromeTransitionDetail;
+        "dsChromeTransitionEnd": ChromeTransitionDetail;
         "dsNavFooterAction": void;
         "dsNavUserAction": PanelNavUserActionDetail;
     }
@@ -1498,6 +1507,8 @@ declare global {
     id: PanelToolsToolId;
     selected: boolean;
   };
+        "dsChromeTransitionStart": ChromeTransitionDetail;
+        "dsChromeTransitionEnd": ChromeTransitionDetail;
     }
     interface HTMLDsPanelToolsElement extends Components.DsPanelTools, HTMLStencilElement {
         addEventListener<K extends keyof HTMLDsPanelToolsElementEventMap>(type: K, listener: (this: HTMLDsPanelToolsElement, ev: DsPanelToolsCustomEvent<HTMLDsPanelToolsElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -1775,7 +1786,7 @@ declare namespace LocalJSX {
     }
     interface DsAppShell {
         /**
-          * When `true`, paints the shared chrome surface (bg + wash + grid) behind panel, bar, and tools.
+          * When `true`, paints the radial wash behind panel, bar, and tools (synced to shell layout).
           * @default false
          */
         "gradient"?: boolean;
@@ -1784,6 +1795,11 @@ declare namespace LocalJSX {
           * @default ''
          */
         "gradientSrc"?: string;
+        /**
+          * When `true`, paints the diagonal grid overlay on the shared chrome layer. Independent of `gradient`.
+          * @default false
+         */
+        "grid"?: boolean;
         /**
           * Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`.
           * @default 'dashboard'
@@ -2378,6 +2394,11 @@ declare namespace LocalJSX {
           * @default 'dashboard'
          */
         "navStyle"?: NavChromeStyle;
+        "onDsChromeTransitionEnd"?: (event: DsPanelNavCustomEvent<ChromeTransitionDetail>) => void;
+        /**
+          * Bubbling lifecycle — `ds-app-shell` pauses chrome metrics during width motion.
+         */
+        "onDsChromeTransitionStart"?: (event: DsPanelNavCustomEvent<ChromeTransitionDetail>) => void;
         /**
           * Emitted when the footer left button (gear / dashboard) is clicked.
          */
@@ -2431,6 +2452,11 @@ declare namespace LocalJSX {
           * @default ''
          */
         "itemsJson"?: string;
+        "onDsChromeTransitionEnd"?: (event: DsPanelToolsCustomEvent<ChromeTransitionDetail>) => void;
+        /**
+          * Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion.
+         */
+        "onDsChromeTransitionStart"?: (event: DsPanelToolsCustomEvent<ChromeTransitionDetail>) => void;
         /**
           * Emitted when a rail button is toggled. Detail = { id, selected }.
          */
@@ -2855,6 +2881,7 @@ declare namespace LocalJSX {
     interface DsAppShellAttributes {
         "navStyle": NavChromeStyle;
         "gradient": boolean;
+        "grid": boolean;
         "gradientSrc": string;
     }
     interface DsBadgeAttributes {

package/src/wc/nav/chrome-transition.ts

@@ -0,0 +1,10 @@
+/** Bubbling/composed events — `ds-app-shell` and `ds-bar-nav` coordinate during width motion. */
+
+export const CHROME_TRANSITION_START = 'dsChromeTransitionStart';
+export const CHROME_TRANSITION_END = 'dsChromeTransitionEnd';
+
+export type ChromeTransitionSource = 'panel-nav' | 'panel-tools';
+
+export interface ChromeTransitionDetail {
+  source: ChromeTransitionSource;
+}

package/src/wc/nav/index.ts

@@ -33,8 +33,22 @@ export {
   shellGradientPositionPanel,
   shellGradientPositionBar,
   shellChromeSurfacePosition,
+  shellChromeLayerActive,
 } from './shell-gradient';
 export type { ShellGradientLayout } from './shell-gradient';
+export type { ChromeTransitionDetail, ChromeTransitionSource } from './chrome-transition';
+export {
+  CHROME_TRANSITION_END,
+  CHROME_TRANSITION_START,
+} from './chrome-transition';
+export {
+  barGradientPositionFromPanelWidth,
+  isPanelNavCollapsed,
+  panelWidthPxFromTokens,
+  readCssVarWidthPx,
+  readPanelNavWidthTokens,
+} from './shell-chrome-metrics';
+export type { PanelNavWidthTokens } from './shell-chrome-metrics';
 export {
   BADGE_GRADIENT_POSITION_VAR,
   badgeGradientPosition,

package/src/wc/nav/shell-chrome-metrics.ts

@@ -0,0 +1,49 @@
+import { shellGradientPositionBar } from './shell-gradient';
+
+/** Read a `var(--token)` width in px using a hidden probe (works with calc() tokens). */
+export function readCssVarWidthPx(context: HTMLElement, cssVarName: string): number {
+  if (typeof document === 'undefined') return 0;
+
+  const probe = document.createElement('div');
+  probe.style.cssText =
+    'position:absolute;visibility:hidden;pointer-events:none;height:0;width:var(' +
+    cssVarName +
+    ');';
+  context.appendChild(probe);
+  const width = probe.getBoundingClientRect().width;
+  context.removeChild(probe);
+  return width;
+}
+
+export interface PanelNavWidthTokens {
+  expandedPx: number;
+  collapsedPx: number;
+}
+
+/** Resolve panel-nav expanded/collapsed widths from scoped CSS vars on `.panel-nav`. */
+export function readPanelNavWidthTokens(navRoot: HTMLElement): PanelNavWidthTokens {
+  return {
+    expandedPx: readCssVarWidthPx(navRoot, '--_nav-width'),
+    collapsedPx: readCssVarWidthPx(navRoot, '--_nav-width-collapsed'),
+  };
+}
+
+export function isPanelNavCollapsed(
+  panelNavHost: HTMLElement | null,
+  navRoot: HTMLElement | null,
+): boolean {
+  if (navRoot?.classList.contains('panel-nav--collapsed')) return true;
+  const collapsedProp = (panelNavHost as (HTMLElement & { collapsed?: boolean }) | null)?.collapsed;
+  return collapsedProp === true;
+}
+
+export function panelWidthPxFromTokens(
+  tokens: PanelNavWidthTokens,
+  collapsed: boolean,
+): number {
+  return collapsed ? tokens.collapsedPx : tokens.expandedPx;
+}
+
+export function barGradientPositionFromPanelWidth(panelWidthPx: number): string {
+  return shellGradientPositionBar(panelWidthPx);
+}

package/src/wc/nav/shell-gradient.ts

@@ -10,6 +10,11 @@ export const SHELL_CHROME_SURFACE_POSITION_VAR = '--ds-shell-chrome-surface-posi
 /** Layer opacity for the nav gradient wash. */
 export const SHELL_GRADIENT_OPACITY = '0.1';
 
+/** Whether the shared chrome layer (bg + optional wash/grid) should mount. */
+export function shellChromeLayerActive(gradient: boolean, grid: boolean): boolean {
+  return gradient || grid;
+}
+
 const GRADIENT_GEOMETRY = '100% 100% at 0% 0%';
 
 /**