@wallarm-org/design-system 1.28.0 → 1.28.1

package/dist/components/RemoteShell/NavPanelContent.d.ts

@@ -1,6 +1,11 @@
 import type { FC } from 'react';
+import type { NavStackEntry } from './model';
+interface NavigationSnapshot {
+    navStack: NavStackEntry[];
+}
 interface NavPanelContentProps {
     level: number;
+    navigationSnapshot?: NavigationSnapshot;
 }
 export declare const NavPanelContent: FC<NavPanelContentProps>;
 export {};

package/dist/components/RemoteShell/NavPanelContent.js

@@ -4,10 +4,12 @@ import { Text } from "../Text/index.js";
 import { HeaderActions } from "./HeaderActions.js";
 import { findDrillNode, useRemoteShellContext } from "./model/index.js";
 import { NavItemsList } from "./NavItemsList.js";
-const NavPanelContent = ({ level: rawLevel })=>{
-    const { config, navStack, effectiveActiveItemId, navigate, drillInto, goBack } = useRemoteShellContext();
+const NavPanelContent = ({ level: rawLevel, navigationSnapshot })=>{
+    const { config, navStack: currentNavStack, navigate, drillInto, goBack } = useRemoteShellContext();
+    const navStack = navigationSnapshot?.navStack ?? currentNavStack;
     const level = Math.min(rawLevel, navStack.length - 1);
     const entry = navStack[level];
+    const activeItemId = entry.activeItemId;
     const hasHeaderActions = !!config.headerActions?.length;
     if (0 === level) return /*#__PURE__*/ jsxs(Fragment, {
         children: [
@@ -28,7 +30,7 @@ const NavPanelContent = ({ level: rawLevel })=>{
             }),
             /*#__PURE__*/ jsx(NavItemsList, {
                 items: config.items,
-                activeItemId: effectiveActiveItemId,
+                activeItemId: activeItemId,
                 onNavigate: navigate,
                 onDrillClick: drillInto
             })
@@ -54,7 +56,7 @@ const NavPanelContent = ({ level: rawLevel })=>{
             }),
             /*#__PURE__*/ jsx(NavItemsList, {
                 items: entry.items,
-                activeItemId: effectiveActiveItemId,
+                activeItemId: activeItemId,
                 onNavigate: navigate,
                 onDrillClick: drillInto
             })

package/dist/components/RemoteShell/RemoteShell.d.ts

@@ -8,7 +8,36 @@ export interface RemoteShellProps extends HTMLAttributes<HTMLDivElement>, Testab
     config: NavConfig;
     /** URL prefix stripped before matching and prepended when navigating (e.g. `"/edge"`). */
     basePath?: string;
-    /** Custom navigation handler for router integration (React Router, Next.js, etc.). */
+    /**
+     * Current pathname. When set, it is the single source of truth for the active nav
+     * item, drill level and breadcrumbs, and `window.location` is ignored.
+     *
+     * Pass it — **together with `onNavigate`** — whenever a router owns the URL: router
+     * navigations (links in page content, `router.navigate`, memory history, the host's
+     * rail) do not fire `popstate`, so without it the shell can go stale. Without
+     * `onNavigate` the shell's own navigations would only reach `window.history`, which
+     * a controlled shell ignores (a dev warning flags this).
+     *
+     * Either form is accepted: with the `basePath` prefix (what `onNavigate` receives) or
+     * without it — the prefix is stripped only when the pathname starts with a whole
+     * `basePath` segment. With TanStack Router, `useRouterState({ select: s =>
+     * s.location.pathname })` is router-relative: it excludes the router's own
+     * `basepath`. So when the router has `basepath`:
+     * - omit `basePath` here — `pathname` and `onNavigate` are then both router-relative
+     *   and `onNavigate={to => navigate({ to })}` is correct; or
+     * - keep `basePath` and strip it in `onNavigate`
+     *   (`to => navigate({ to: to.slice(basePath.length) || '/' })`), otherwise the
+     *   router prefixes it a second time.
+     *
+     * Omit it to read `window.location.pathname` (updated on `popstate` and on the
+     * shell's own navigations).
+     */
+    pathname?: string;
+    /**
+     * Navigation handler for router integration (TanStack Router, React Router,
+     * Next.js, …). Receives the target pathname, prefixed with `basePath` when one is
+     * set. Without it the shell pushes to `window.history` itself.
+     */
     onNavigate?: (pathname: string) => void;
 }
 export declare const RemoteShell: FC<RemoteShellProps>;

package/dist/components/RemoteShell/RemoteShell.js

@@ -2,14 +2,30 @@ import { jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { cn } from "../../utils/cn.js";
 import { TestIdProvider } from "../../utils/testId.js";
-import { RemoteShellContextProvider, findFirstLinkPath, matchNav, pushPathname, useLocationPathname } from "./model/index.js";
-const RemoteShell = ({ ref, className, children, config, basePath, onNavigate, 'data-testid': testId, ...props })=>{
-    const fullPathname = useLocationPathname();
-    const pathname = basePath && fullPathname.startsWith(basePath) ? fullPathname.slice(basePath.length) || '/' : fullPathname;
+import { RemoteShellContextProvider, findFirstLinkPath, matchNav, notifyPathnameChanged, pushPathname, useLocationPathname } from "./model/index.js";
+const stripBasePath = (fullPathname, basePath)=>{
+    if (!basePath) return fullPathname;
+    if (fullPathname === basePath) return '/';
+    return fullPathname.startsWith(`${basePath}/`) ? fullPathname.slice(basePath.length) : fullPathname;
+};
+const RemoteShell = ({ ref, className, children, config, basePath, onNavigate, pathname: controlledPathname, 'data-testid': testId, ...props })=>{
+    const locationPathname = useLocationPathname();
+    const fullPathname = controlledPathname ?? locationPathname;
+    const pathname = stripBasePath(fullPathname, basePath);
+    const isControlled = void 0 !== controlledPathname;
+    const hasOnNavigate = void 0 !== onNavigate;
+    useEffect(()=>{
+        if (isControlled && !hasOnNavigate && 'production' !== process.env.NODE_ENV) console.warn('[RemoteShell] `pathname` is controlled but `onNavigate` is missing: shell navigations will update `window.history` only, and the shell will keep showing the old route. Pass `onNavigate` to route them through your router.');
+    }, [
+        isControlled,
+        hasOnNavigate
+    ]);
     const setPathname = useCallback((next)=>{
         const fullPath = basePath ? `${basePath}${next}` : next;
-        if (onNavigate) onNavigate(fullPath);
-        else pushPathname(fullPath);
+        if (onNavigate) {
+            onNavigate(fullPath);
+            notifyPathnameChanged();
+        } else pushPathname(fullPath);
     }, [
         basePath,
         onNavigate
@@ -19,17 +35,14 @@ const RemoteShell = ({ ref, className, children, config, basePath, onNavigate, '
         config
     ]);
     const urlDrillLevel = navStack.length - 1;
-    const [visualDrillLevel, setVisualDrillLevel] = useState(null);
-    useEffect(()=>{
-        setVisualDrillLevel(null);
-    }, [
-        pathname
-    ]);
+    const [drillOverride, setDrillOverride] = useState(null);
+    const visualDrillLevel = drillOverride?.pathname === pathname ? drillOverride.level : null;
+    if (drillOverride && drillOverride.pathname !== pathname) setDrillOverride(null);
     const effectiveDrillLevel = visualDrillLevel ?? urlDrillLevel;
     const effectiveActiveItemId = effectiveDrillLevel < urlDrillLevel ? navStack[effectiveDrillLevel]?.activeItemId ?? activeItemId : activeItemId;
     const prefixSegmentCount = navStack[effectiveDrillLevel]?.segmentCount ?? 2 * effectiveDrillLevel;
     const navigate = useCallback((path)=>{
-        setVisualDrillLevel(null);
+        setDrillOverride(null);
         const segments = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
         const prefixSegments = segments.slice(0, prefixSegmentCount);
         setPathname(`/${[
@@ -42,7 +55,7 @@ const RemoteShell = ({ ref, className, children, config, basePath, onNavigate, '
         setPathname
     ]);
     const drillInto = useCallback((drill)=>{
-        setVisualDrillLevel(null);
+        setDrillOverride(null);
         const segments = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
         const prefixSegments = segments.slice(0, prefixSegmentCount);
         const defaultEntity = drill.entities?.[0]?.id ?? 'default';
@@ -64,15 +77,19 @@ const RemoteShell = ({ ref, className, children, config, basePath, onNavigate, '
         setPathname
     ]);
     const goBack = useCallback(()=>{
-        setVisualDrillLevel((prev)=>{
-            const current = prev ?? urlDrillLevel;
-            return Math.max(current - 1, 0);
+        setDrillOverride((prev)=>{
+            const current = prev?.pathname === pathname ? prev.level : urlDrillLevel;
+            return {
+                level: Math.max(current - 1, 0),
+                pathname
+            };
         });
     }, [
+        pathname,
         urlDrillLevel
     ]);
     const navigateTo = useCallback((href)=>{
-        setVisualDrillLevel(null);
+        setDrillOverride(null);
         href === config.productPath ? setPathname('/') : setPathname(href);
     }, [
         config.productPath,

package/dist/components/RemoteShell/RemoteShellPanel.js

@@ -7,8 +7,8 @@ import { DRILL_ANIMATION_DURATION, DRILL_ANIMATION_EASING, useDrillTransition }
 import { NavPanelContent } from "./NavPanelContent.js";
 const RemoteShellPanel = ({ ref, className, resizable, isLoading, loaderCount = 6, ...props })=>{
     const testId = useTestId('panel');
-    const { config, drillLevel } = useRemoteShellContext();
-    const { transition, clearTransition } = useDrillTransition(drillLevel);
+    const { config, drillLevel, navStack } = useRemoteShellContext();
+    const { transition, clearTransition } = useDrillTransition(drillLevel, navStack, config.productPath);
     if (isLoading) return /*#__PURE__*/ jsx("div", {
         ...props,
         ref: ref,
@@ -53,7 +53,10 @@ const RemoteShellPanel = ({ ref, className, resizable, isLoading, loaderCount =
                                     animation: `${isForward ? 'ds-nav-blur-out' : 'ds-nav-blur-in'} ${timing}`
                                 },
                                 children: /*#__PURE__*/ jsx(NavPanelContent, {
-                                    level: isForward ? transition.fromLevel : drillLevel
+                                    level: isForward ? transition.fromLevel : drillLevel,
+                                    navigationSnapshot: isForward ? {
+                                        navStack: transition.fromNavStack
+                                    } : void 0
                                 })
                             }),
                             /*#__PURE__*/ jsx("div", {
@@ -62,7 +65,10 @@ const RemoteShellPanel = ({ ref, className, resizable, isLoading, loaderCount =
                                     animation: `${isForward ? 'ds-nav-blur-in' : 'ds-nav-blur-out'} ${timing}`
                                 },
                                 children: /*#__PURE__*/ jsx(NavPanelContent, {
-                                    level: isForward ? drillLevel : transition.fromLevel
+                                    level: isForward ? drillLevel : transition.fromLevel,
+                                    navigationSnapshot: isForward ? void 0 : {
+                                        navStack: transition.fromNavStack
+                                    }
                                 })
                             })
                         ]

package/dist/components/RemoteShell/model/index.d.ts

@@ -2,4 +2,4 @@ export { type MatchNavResult, matchNav } from './matchNav';
 export { findDrillNode, findFirstLinkPath } from './navUtils';
 export { RemoteShellContextProvider, type RemoteShellContextValue, useRemoteShellContext, } from './RemoteShellContext';
 export type { BreadcrumbSegment, NavConfig, NavConfigDrill, NavConfigGroup, NavConfigHeaderAction, NavConfigLink, NavConfigNode, NavConfigSectionHeader, NavStackEntry, } from './types';
-export { pushPathname, useLocationPathname } from './useLocationPathname';
+export { notifyPathnameChanged, pushPathname, useLocationPathname } from './useLocationPathname';

package/dist/components/RemoteShell/model/index.js

@@ -1,4 +1,4 @@
 export { matchNav } from "./matchNav.js";
 export { findDrillNode, findFirstLinkPath } from "./navUtils.js";
 export { RemoteShellContextProvider, useRemoteShellContext } from "./RemoteShellContext.js";
-export { pushPathname, useLocationPathname } from "./useLocationPathname.js";
+export { notifyPathnameChanged, pushPathname, useLocationPathname } from "./useLocationPathname.js";

package/dist/components/RemoteShell/model/useDrillTransition.d.ts

@@ -1,10 +1,21 @@
+import type { NavStackEntry } from './types';
 export declare const DRILL_ANIMATION_DURATION = "220ms";
 export declare const DRILL_ANIMATION_EASING = "cubic-bezier(0.4, 0, 0.2, 1)";
 export interface DrillTransition {
     fromLevel: number;
     direction: 'forward' | 'backward';
+    fromNavStack: NavStackEntry[];
 }
-export declare const useDrillTransition: (drillLevel: number) => {
+/**
+ * Tracks drill-level changes and exposes the transition to animate.
+ *
+ * `scope` identifies the nav tree (the config's `productPath`). A level change that
+ * coincides with a scope change — the same `RemoteShell` instance re-rendered for a
+ * different product — is not animated: sliding from the previous product's menu would
+ * show the wrong items. Keyed on `productPath` rather than config identity so a config
+ * rebuilt for the same product (e.g. when scope-switcher entities load) still animates.
+ */
+export declare const useDrillTransition: (drillLevel: number, navStack: NavStackEntry[], scope: string) => {
     transition: DrillTransition | null;
     clearTransition: () => void;
 };

package/dist/components/RemoteShell/model/useDrillTransition.js

@@ -1,24 +1,36 @@
 import { useLayoutEffect, useRef, useState } from "react";
 const DRILL_ANIMATION_DURATION = '220ms';
 const DRILL_ANIMATION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
-const useDrillTransition = (drillLevel)=>{
-    const prevLevelRef = useRef(drillLevel);
+const useDrillTransition = (drillLevel, navStack, scope)=>{
+    const previousRef = useRef({
+        drillLevel,
+        navStack,
+        scope
+    });
     const [transition, setTransition] = useState(null);
     useLayoutEffect(()=>{
-        const prev = prevLevelRef.current;
-        if (prev !== drillLevel) {
-            setTransition({
-                fromLevel: prev,
-                direction: drillLevel > prev ? 'forward' : 'backward'
-            });
-            prevLevelRef.current = drillLevel;
-        }
+        const previous = previousRef.current;
+        if (previous.scope !== scope) setTransition(null);
+        else if (previous.drillLevel !== drillLevel) setTransition({
+            fromLevel: previous.drillLevel,
+            direction: drillLevel > previous.drillLevel ? 'forward' : 'backward',
+            fromNavStack: previous.navStack,
+            scope
+        });
+        previousRef.current = {
+            drillLevel,
+            navStack,
+            scope
+        };
     }, [
-        drillLevel
+        drillLevel,
+        navStack,
+        scope
     ]);
     const clearTransition = ()=>setTransition(null);
+    const activeTransition = transition && transition.scope === scope ? transition : null;
     return {
-        transition,
+        transition: activeTransition,
         clearTransition
     };
 };

package/dist/components/RemoteShell/model/useLocationPathname.d.ts

@@ -1,4 +1,6 @@
 /** Push a new pathname to the browser history and notify subscribers. */
 export declare function pushPathname(path: string): void;
+/** Notify pathname subscribers after navigation handled by an external router. */
+export declare function notifyPathnameChanged(): void;
 /** Subscribe to `window.location.pathname` via `useSyncExternalStore`. */
 export declare function useLocationPathname(): string;

package/dist/components/RemoteShell/model/useLocationPathname.js

@@ -16,9 +16,12 @@ function getSnapshot() {
 }
 function pushPathname(path) {
     window.history.pushState(null, '', path);
+    notifyPathnameChanged();
+}
+function notifyPathnameChanged() {
     for (const listener of listeners)listener();
 }
 function useLocationPathname() {
     return useSyncExternalStore(subscribe, getSnapshot);
 }
-export { pushPathname, useLocationPathname };
+export { notifyPathnameChanged, pushPathname, useLocationPathname };

package/dist/metadata/components.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.27.0",
-  "generatedAt": "2026-09-30T12:41:24.546Z",
+  "version": "1.28.0",
+  "generatedAt": "2026-09-30T12:59:20.784Z",
   "components": [
     {
       "name": "Accordion",
@@ -5341,23 +5341,28 @@
       "examples": [
         {
           "name": "Basic",
-          "code": "({ ambient }) => <Shell ambient={ambient} />",
+          "code": "({ ambient }) => (\n  <StoryRouter>\n    <Shell ambient={ambient} />\n  </StoryRouter>\n)",
           "description": "The three regions composed once — `AppShellHeader`, `AppShellRail`, `AppShellRemote` — with the content surface being the only part that scrolls. Pick a product in the rail to drill into it, and the account item at the bottom for appearance and sidebar mode."
         },
         {
           "name": "Loading",
-          "code": "({ ambient, loading }) => (\n  <Shell ambient={ambient} loading={loading} simulateProductLoading />\n)",
+          "code": "({ ambient, loading }) => (\n  <StoryRouter>\n    <Shell ambient={ambient} loading={loading} simulateProductLoading />\n  </StoryRouter>\n)",
           "description": "How the shell looks while the platform loads. The header actions and the product rail hold skeletons that sit exactly where the real items land, so nothing jumps when they arrive. Turn `loading` off in Controls to watch the swap. Opening a product also shows its own panel and content loading."
         },
         {
           "name": "RevealFlow",
-          "code": "() => {\n  const pathname = useLocationPathname();\n  const activeProduct = deriveProduct(pathname);\n\n  const [splashDone, setSplashDone] = useState(false);\n  const [sidebarMode, setSidebarMode] = useState<SidebarMode>('adaptive');\n  const [revealKey, setRevealKey] = useState(0);\n  const { theme, setTheme } = useTheme();\n  const railMode = railModeFor(sidebarMode, activeProduct === 'home');\n\n  useEffect(() => {\n    if (splashDone) return;\n    const timer = setTimeout(() => setSplashDone(true), 2000);\n    return () => clearTimeout(timer);\n  }, [splashDone]);\n\n  const handleReplay = () => {\n    setSplashDone(false);\n    setRevealKey(k => k + 1);\n  };\n\n  if (!splashDone) {\n    return (\n      <div key={revealKey} className='h-screen w-screen bg-bg-page-bg'>\n        <SplashScreen />\n      </div>\n    );\n  }\n\n  return (\n    <AppShell key={revealKey} reveal>\n      <AppShellHeader>\n        <TopHeader>\n          <TopHeaderLogo href='/'>\n            <WallarmLogo />\n          </TopHeaderLogo>\n\n          <TopHeaderActions>\n            <HeaderActions />\n          </TopHeaderActions>\n        </TopHeader>\n      </AppShellHeader>\n\n      <AppShellRail>\n        <NavRail mode={railMode}>\n          <NavRailBody>\n            <NavRailItem\n              icon={Home}\n              label='Home'\n              shortcut={['G', 'H']}\n              active={activeProduct === 'home'}\n              onClick={() => navigateToProduct('home')}\n            />\n            <RecentDropdown />\n\n            <NavRailSeparator />\n\n            <ProductNavItems activeProduct={activeProduct} />\n          </NavRailBody>\n\n          <NavRailFooterContent\n            activeProduct={activeProduct}\n            sidebarMode={sidebarMode}\n            onSidebarModeChange={setSidebarMode}\n            theme={theme}\n            onThemeChange={setTheme}\n          />\n        </NavRail>\n      </AppShellRail>\n\n      <AppShellRemote>\n        <div className='flex gap-8 absolute top-4 right-4 z-10'>\n          <Button variant='ghost' size='small' color='neutral' onClick={handleReplay}>\n            Replay animation\n          </Button>\n        </div>\n\n        <RemoteForProduct product={activeProduct} />\n      </AppShellRemote>\n    </AppShell>\n  );\n}",
+          "code": "() => (\n  <StoryRouter>\n    <RevealFlowShell />\n  </StoryRouter>\n)",
           "description": "`reveal` animates the chrome in on the first application load only. Leave it unset for an ordinary screen; this exists for prototyping the boot moment itself."
         },
         {
           "name": "LoginFlow",
-          "code": "() => {\n  const pathname = useLocationPathname();\n  const activeProduct = deriveProduct(pathname);\n\n  const [splashVisible, setSplashVisible] = useState(true);\n  const [showShell, setShowShell] = useState(false);\n  const [revealed, setRevealed] = useState(false);\n  const [flowKey, setFlowKey] = useState(0);\n  const [sidebarMode, setSidebarMode] = useState<SidebarMode>('adaptive');\n  const { theme, setTheme } = useTheme();\n  const railMode = railModeFor(sidebarMode, activeProduct === 'home');\n\n  useEffect(() => {\n    if (!splashVisible) return;\n    const timer = setTimeout(() => setSplashVisible(false), 2000);\n    return () => clearTimeout(timer);\n  }, [splashVisible]);\n\n  const handleSignIn = () => {\n    setShowShell(true);\n  };\n\n  const handleReplay = () => {\n    setShowShell(false);\n    setRevealed(false);\n    setSplashVisible(true);\n    setFlowKey(k => k + 1);\n  };\n\n  return (\n    <div\n      key={flowKey}\n      className='relative h-screen w-screen overflow-hidden bg-component-app-shell-bg'\n    >\n      {!revealed && (\n        <AnimatedBackground\n          className='absolute inset-0'\n          style={{\n            opacity: showShell ? 0 : 1,\n            transition: showShell ? 'opacity 400ms cubic-bezier(0.4, 0, 0.2, 1)' : undefined,\n          }}\n        />\n      )}\n\n      {!showShell && (\n        <div className='absolute inset-0 flex items-center justify-center z-10'>\n          <SplashScreen\n            visible={splashVisible}\n            shrinkTarget={CARD_DIMENSIONS}\n            className='bg-bg-page-bg shadow-lg'\n          >\n            <div className='flex h-full w-full flex-col items-center justify-center gap-16 p-24'>\n              <Text size='xl'>Sign In</Text>\n              <div className='flex w-full flex-col gap-12'>\n                <Input placeholder='Email' />\n                <Input placeholder='Password' type='password' />\n              </div>\n              <Button variant='primary' color='brand' className='w-full' onClick={handleSignIn}>\n                Sign In\n              </Button>\n            </div>\n          </SplashScreen>\n        </div>\n      )}\n\n      {showShell && (\n        <div className='absolute inset-0'>\n          <AppShell expandFrom={CARD_DIMENSIONS} onRevealed={() => setRevealed(true)}>\n            <AppShellHeader>\n              <TopHeader>\n                <TopHeaderLogo href='/'>\n                  <WallarmLogo />\n                </TopHeaderLogo>\n\n                <TopHeaderActions>\n                  <HeaderActions />\n                </TopHeaderActions>\n              </TopHeader>\n            </AppShellHeader>\n\n            <AppShellRail>\n              <NavRail mode={railMode}>\n                <NavRailBody>\n                  <NavRailItem\n                    icon={Home}\n                    label='Home'\n                    active={activeProduct === 'home'}\n                    onClick={() => navigateToProduct('home')}\n                  />\n\n                  <NavRailSeparator />\n\n                  <ProductNavItems activeProduct={activeProduct} />\n                </NavRailBody>\n                <NavRailFooterContent\n                  activeProduct={activeProduct}\n                  sidebarMode={sidebarMode}\n                  onSidebarModeChange={setSidebarMode}\n                  theme={theme}\n                  onThemeChange={setTheme}\n                />\n              </NavRail>\n            </AppShellRail>\n\n            <AppShellRemote>\n              <div className='flex gap-8 absolute top-4 right-4 z-10'>\n                <Button variant='ghost' size='small' color='neutral' onClick={handleReplay}>\n                  Replay animation\n                </Button>\n              </div>\n              <RemoteForProduct product={activeProduct} />\n            </AppShellRemote>\n          </AppShell>\n        </div>\n      )}\n    </div>\n  );\n}",
+          "code": "() => (\n  <StoryRouter>\n    <LoginFlowShell />\n  </StoryRouter>\n)",
           "description": "The whole entrance: the splash hands off, the content surface expands from the sign-in card into the full shell. `onRevealed` fires when it has settled."
+        },
+        {
+          "name": "WithTanStackRouter",
+          "code": "() => {\n  const [router] = useState(createShellRouter);\n\n  return <RouterProvider router={router} />;\n}",
+          "description": "`AppShell` and a `RemoteShell` per product on one TanStack Router: the root route is\nthe shell (rail → `navigate`, `AppShellRemote` → `<Outlet />`), `/$product` is the\nremote (`RemoteShell` with `pathname` + `onNavigate`, content → `<Outlet />`), and\n`/$product/$` is the page. Every way of moving — the rail, the nav panel, the\nbreadcrumbs, links in the page — goes through the router, and the active items follow."
         }
       ]
     },
@@ -56736,6 +56741,7 @@
     },
     {
       "name": "RemoteShell",
+      "description": "Strips `basePath` only on a segment boundary: `/edge-nodes` is not under `/edge`.",
       "importPath": "@wallarm-org/design-system/RemoteShell",
       "props": [
         {
@@ -56750,6 +56756,12 @@
           "required": false,
           "description": "URL prefix stripped before matching and prepended when navigating (e.g. `\"/edge\"`)."
         },
+        {
+          "name": "pathname",
+          "type": "string | undefined",
+          "required": false,
+          "description": "Current pathname. When set, it is the single source of truth for the active nav\nitem, drill level and breadcrumbs, and `window.location` is ignored.\n\nPass it — **together with `onNavigate`** — whenever a router owns the URL: router\nnavigations (links in page content, `router.navigate`, memory history, the host's\nrail) do not fire `popstate`, so without it the shell can go stale. Without\n`onNavigate` the shell's own navigations would only reach `window.history`, which\na controlled shell ignores (a dev warning flags this).\n\nEither form is accepted: with the `basePath` prefix (what `onNavigate` receives) or\nwithout it — the prefix is stripped only when the pathname starts with a whole\n`basePath` segment. With TanStack Router, `useRouterState({ select: s =>\ns.location.pathname })` is router-relative: it excludes the router's own\n`basepath`. So when the router has `basepath`:\n- omit `basePath` here — `pathname` and `onNavigate` are then both router-relative\n  and `onNavigate={to => navigate({ to })}` is correct; or\n- keep `basePath` and strip it in `onNavigate`\n  (`to => navigate({ to: to.slice(basePath.length) || '/' })`), otherwise the\n  router prefixes it a second time.\n\nOmit it to read `window.location.pathname` (updated on `popstate` and on the\nshell's own navigations)."
+        },
         {
           "name": "defaultChecked",
           "type": "boolean | undefined",
@@ -57870,7 +57882,13 @@
           ]
         }
       ],
-      "examples": []
+      "examples": [
+        {
+          "name": "Basic",
+          "code": "() => {\n  const navigate = useNavigate();\n  const pathname = useRouterState({ select: state => state.location.pathname });\n\n  return (\n    <div className='h-screen bg-bg-page-bg'>\n      <RemoteShell\n        config={edgeNavConfig}\n        basePath='/edge'\n        pathname={pathname}\n        onNavigate={to => navigate({ to })}\n      >\n        <RemoteShellPanel resizable />\n        <RemoteShellBreadcrumb />\n        <RemoteShellContent>\n          <EdgePage />\n        </RemoteShellContent>\n      </RemoteShell>\n    </div>\n  );\n}",
+          "description": "A standalone product on TanStack Router — the recommended integration. `pathname` is\nthe router’s `location.pathname` and `onNavigate` calls `navigate`, so the menu, drill\nlevel and breadcrumbs follow every navigation: the panel, the breadcrumbs and the\nrouter links in the page. This router has no `basepath` (its routes include `/edge`),\nso both sides use the full pathname. If your router sets `basepath`, its\n`location.pathname` is router-relative: omit `basePath` on `RemoteShell` (or keep it\nand strip it in `onNavigate`), otherwise `navigate` prefixes it twice."
+        }
+      ]
     },
     {
       "name": "Resizable",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wallarm-org/design-system",
-  "version": "1.28.0",
+  "version": "1.28.1",
   "description": "Core design system library with React components and Storybook documentation",
   "publishConfig": {
     "access": "public",
@@ -97,6 +97,7 @@
     "@storybook/addon-docs": "10.4.6",
     "@storybook/addon-themes": "10.4.6",
     "@tailwindcss/postcss": "4.3.3",
+    "@tanstack/react-router": "1.170.21",
     "@testing-library/jest-dom": "7.0.0",
     "@testing-library/react": "catalog:",
     "@testing-library/user-event": "catalog:",

package/dist/components/AppShell/story-content/_storyAccountDropdown.d.ts

@@ -1,11 +0,0 @@
-import { type NavRailMode } from '../../NavRail';
-import { type Theme } from '../../ThemeProvider';
-export type SidebarMode = 'adaptive' | 'expanded' | 'collapsed' | 'compact';
-/** Adaptive collapses the rail inside a product and expands it on Home; the other modes pin it. */
-export declare const railModeFor: (mode: SidebarMode, onHome: boolean) => NavRailMode;
-export declare const AccountDropdown: ({ sidebarMode, onSidebarModeChange, theme, onThemeChange, }: {
-    sidebarMode: SidebarMode;
-    onSidebarModeChange: (mode: SidebarMode) => void;
-    theme: Theme;
-    onThemeChange: (theme: Theme) => void;
-}) => import("react").JSX.Element;