@fragments-sdk/cli 0.7.9 → 0.7.11

package/src/viewer/hooks/useKeyboardShortcuts.ts

@@ -2,11 +2,15 @@
  * Keyboard Shortcuts Hook
  *
  * Provides global keyboard navigation for the viewer:
- * - j/k or ↓/↑: Navigate components
- * - [/] or ←/→: Navigate variants
+ * - ⌘↓/⌘↑: Navigate components
+ * - ⌘←/⌘→: Navigate variants
+ * - j/k or ↓/↑: Navigate components (legacy)
+ * - [/] or ←/→: Navigate variants (legacy)
  * - 1-9: Jump to variant by number
  * - t: Toggle preview theme
  * - p: Toggle panel
+ * - m: Toggle matrix view
+ * - r: Toggle responsive view
  * - cmd+shift+c: Copy link
  * - ?: Show shortcuts help
  * - Escape: Close modals/clear search
@@ -29,6 +33,10 @@ export interface ShortcutActions {
   toggleTheme: () => void;
   /** Toggle panel open/closed */
   togglePanel: () => void;
+  /** Toggle matrix view */
+  toggleMatrix: () => void;
+  /** Toggle responsive/multi-viewport view */
+  toggleResponsive: () => void;
   /** Copy shareable link */
   copyLink: () => void;
   /** Show shortcuts help */
@@ -84,6 +92,7 @@ export function useKeyboardShortcuts(
 
       // Don't capture events from input elements (except for specific shortcuts)
       const isInput = isInputElement(event.target);
+      const isMeta = event.metaKey || event.ctrlKey;
 
       // Global shortcuts that work even in inputs
       if (event.key === "Escape") {
@@ -92,19 +101,41 @@ export function useKeyboardShortcuts(
       }
 
       // cmd+shift+c: Copy link (works everywhere)
-      if ((event.metaKey || event.ctrlKey) && event.shiftKey && event.key === "c") {
+      if (isMeta && event.shiftKey && event.key === "c") {
         event.preventDefault();
         actions.copyLink?.();
         return;
       }
 
       // cmd+k: Open search/command palette (works everywhere)
-      if ((event.metaKey || event.ctrlKey) && event.key === "k") {
+      if (isMeta && event.key === "k") {
         event.preventDefault();
         actions.openSearch?.();
         return;
       }
 
+      // cmd+arrow: Navigation (works everywhere)
+      if (isMeta && event.key === "ArrowDown") {
+        event.preventDefault();
+        actions.nextComponent?.();
+        return;
+      }
+      if (isMeta && event.key === "ArrowUp") {
+        event.preventDefault();
+        actions.prevComponent?.();
+        return;
+      }
+      if (isMeta && event.key === "ArrowRight") {
+        event.preventDefault();
+        actions.nextVariant?.();
+        return;
+      }
+      if (isMeta && event.key === "ArrowLeft") {
+        event.preventDefault();
+        actions.prevVariant?.();
+        return;
+      }
+
       // Skip other shortcuts if in input
       if (isInput) return;
 
@@ -120,7 +151,7 @@ export function useKeyboardShortcuts(
         // Component navigation
         case "j":
         case "ArrowDown":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             event.preventDefault();
             actions.nextComponent?.();
           }
@@ -128,7 +159,7 @@ export function useKeyboardShortcuts(
 
         case "k":
         case "ArrowUp":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             event.preventDefault();
             actions.prevComponent?.();
           }
@@ -137,7 +168,7 @@ export function useKeyboardShortcuts(
         // Variant navigation
         case "[":
         case "ArrowLeft":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             event.preventDefault();
             actions.prevVariant?.();
           }
@@ -145,7 +176,7 @@ export function useKeyboardShortcuts(
 
         case "]":
         case "ArrowRight":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             event.preventDefault();
             actions.nextVariant?.();
           }
@@ -161,7 +192,7 @@ export function useKeyboardShortcuts(
         case "7":
         case "8":
         case "9":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             const index = parseInt(event.key, 10) - 1;
             if (index < variantCount) {
               event.preventDefault();
@@ -172,7 +203,7 @@ export function useKeyboardShortcuts(
 
         // Theme toggle
         case "t":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             event.preventDefault();
             actions.toggleTheme?.();
           }
@@ -180,12 +211,28 @@ export function useKeyboardShortcuts(
 
         // Panel toggle
         case "p":
-          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+          if (!isMeta && !event.altKey) {
             event.preventDefault();
             actions.togglePanel?.();
           }
           break;
 
+        // Matrix view toggle
+        case "m":
+          if (!isMeta && !event.altKey) {
+            event.preventDefault();
+            actions.toggleMatrix?.();
+          }
+          break;
+
+        // Responsive view toggle
+        case "v":
+          if (!isMeta && !event.altKey) {
+            event.preventDefault();
+            actions.toggleResponsive?.();
+          }
+          break;
+
         // Help
         case "?":
           event.preventDefault();
@@ -206,14 +253,15 @@ export function useKeyboardShortcuts(
  * Keyboard shortcuts data for help display
  */
 export const SHORTCUTS = [
-  { keys: ["j", "↓"], description: "Next component" },
-  { keys: ["k", "↑"], description: "Previous component" },
-  { keys: ["[", "←"], description: "Previous variant" },
-  { keys: ["]", "→"], description: "Next variant" },
+  { keys: ["⌘↓"], description: "Next component" },
+  { keys: ["⌘↑"], description: "Previous component" },
+  { keys: ["⌘→"], description: "Next variant" },
+  { keys: ["⌘←"], description: "Previous variant" },
   { keys: ["1-9"], description: "Go to variant" },
   { keys: ["t"], description: "Toggle preview theme" },
-  { keys: ["p"], description: "Toggle panel" },
-  { keys: ["⌘⇧C"], description: "Copy link" },
+  { keys: ["p"], description: "Toggle addons panel" },
+  { keys: ["m"], description: "Matrix view" },
+  { keys: ["v"], description: "Responsive view" },
   { keys: ["/", "⌘K"], description: "Search" },
   { keys: ["?"], description: "Show shortcuts" },
   { keys: ["Esc"], description: "Close / Clear" },

package/src/viewer/hooks/useViewSettings.ts

@@ -4,11 +4,10 @@
  */
 
 import { useReducer, useCallback, useMemo } from 'react';
-import type { ZoomLevel, BackgroundOption } from '../components/PreviewToolbar.js';
+import type { ZoomLevel, BackgroundOption, ViewportPreset, ViewportSize } from '../constants/ui.js';
 
 // Preview theme type (for canvas theming)
 export type PreviewTheme = 'light' | 'dark';
-import type { ViewportPreset, ViewportSize } from '../components/ViewportSelector.js';
 
 interface ViewSettings {
   zoom: ZoomLevel;

package/src/viewer/index.ts

@@ -7,5 +7,5 @@ export { fragmentsPlugin } from "./vite-plugin.js";
 export type { FragmentsPluginOptions } from "./vite-plugin.js";
 
 // Note: Viewer components (App, Layout, etc.) are NOT exported here.
-// They use @fragments/ui which is a Vite-only alias and can't be resolved by Node.js.
+// They use @fragments-sdk/ui which is resolved by the Vite dev server.
 // Vite serves these components directly from source during development.

package/src/viewer/preview-frame.html

@@ -30,19 +30,16 @@
         width: 100%;
         min-height: 100vh;
         display: flex;
-        align-items: flex-start;
-        justify-content: flex-start;
+        align-items: center;
+        justify-content: center;
         padding: 24px;
         box-sizing: border-box;
         overflow: auto;
       }
 
-      body[data-preview-mode='centered'] #preview-root {
-        align-items: center;
-        justify-content: center;
-      }
-
       body[data-preview-mode='full-bleed'] #preview-root {
+        align-items: flex-start;
+        justify-content: flex-start;
         padding: 0;
         min-height: 100vh;
       }
@@ -119,8 +116,8 @@
       }
     </style>
   </head>
-  <body data-preview-mode="centered">
-    <main>
+  <body>
+    <main style="height: 100%">
       <h1 class="sr-only">Component Preview</h1>
       <div id="preview-root">
         <div class="preview-loading">

package/src/viewer/server.ts

@@ -30,6 +30,8 @@ const cliPackageRoot = resolve(__dirname, "..");
 const viewerRoot = resolve(cliPackageRoot, "src/viewer");
 const packagesRoot = resolve(cliPackageRoot, "..");
 const localUiLibRoot = resolve(packagesRoot, "../libs/ui/src");
+const localSharedLibRoot = resolve(packagesRoot, "../libs/shared/src");
+const vendoredSharedLibRoot = resolve(viewerRoot, "vendor/shared/src");
 
 /**
  * Resolve the @fragments/ui alias to the correct path.
@@ -37,6 +39,11 @@ const localUiLibRoot = resolve(packagesRoot, "../libs/ui/src");
  * In the monorepo: use the local libs/ui/src source.
  */
 function resolveUiLib(nodeModulesDir: string): string {
+  // Prefer local monorepo source (when CLI is linked for development)
+  const localIndex = join(localUiLibRoot, "index.ts");
+  if (existsSync(localIndex)) {
+    return localUiLibRoot;
+  }
   // Check for installed @fragments-sdk/ui in project's node_modules
   const installedUi = join(nodeModulesDir, "@fragments-sdk/ui/src/index.ts");
   if (existsSync(installedUi)) {
@@ -47,10 +54,95 @@ function resolveUiLib(nodeModulesDir: string): string {
   if (existsSync(installedUiDist)) {
     return installedUiDist;
   }
-  // Fallback to local monorepo source
   return localUiLibRoot;
 }
 
+/**
+ * Resolve the @fragments-sdk/shared alias to either monorepo source
+ * or vendored viewer fallback for npm installs.
+ */
+function resolveSharedLib(): string {
+  const localIndex = join(localSharedLibRoot, "index.ts");
+  if (existsSync(localIndex)) {
+    return localSharedLibRoot;
+  }
+
+  const vendoredIndex = join(vendoredSharedLibRoot, "index.ts");
+  if (existsSync(vendoredIndex)) {
+    return vendoredSharedLibRoot;
+  }
+
+  return localSharedLibRoot;
+}
+
+/**
+ * Vite plugin to handle CJS-only packages imported from within node_modules.
+ * Vite's optimizeDeps only redirects imports from source files to pre-bundled ESM,
+ * not imports from other node_modules packages. This plugin provides virtual ESM
+ * wrappers for known CJS-only packages.
+ */
+function cjsInteropPlugin(nodeModulesPath: string) {
+  // Virtual ESM wrappers for CJS-only packages
+  const virtualModules: Record<string, string> = {
+    // use-sync-external-store/shim is CJS-only, used by @base-ui/react.
+    // Since React 18+, useSyncExternalStore is built-in — redirect to React's native export.
+    'use-sync-external-store/shim': `export { useSyncExternalStore } from 'react';`,
+    // use-sync-external-store/shim/with-selector is CJS-only, used by @base-ui/utils.
+    // Provides useSyncExternalStoreWithSelector — a selector wrapper around useSyncExternalStore.
+    'use-sync-external-store/shim/with-selector': `
+import { useSyncExternalStore, useRef, useEffect, useMemo, useDebugValue } from 'react';
+export function useSyncExternalStoreWithSelector(subscribe, getSnapshot, getServerSnapshot, selector, isEqual) {
+  var instRef = useRef(null);
+  if (instRef.current === null) instRef.current = { hasValue: false, value: null };
+  var inst = instRef.current;
+  var _useMemo = useMemo(function () {
+    var hasMemo = false, memoizedSnapshot, memoizedSelection;
+    function memoizedSelector(nextSnapshot) {
+      if (!hasMemo) {
+        hasMemo = true;
+        memoizedSnapshot = nextSnapshot;
+        var nextSelection = selector(nextSnapshot);
+        if (isEqual !== undefined && inst.hasValue && isEqual(inst.value, nextSelection))
+          return memoizedSelection = inst.value;
+        return memoizedSelection = nextSelection;
+      }
+      if (Object.is(memoizedSnapshot, nextSnapshot)) return memoizedSelection;
+      var nextSelection = selector(nextSnapshot);
+      if (isEqual !== undefined && isEqual(memoizedSelection, nextSelection)) {
+        memoizedSnapshot = nextSnapshot;
+        return memoizedSelection;
+      }
+      memoizedSnapshot = nextSnapshot;
+      return memoizedSelection = nextSelection;
+    }
+    var maybeGetServerSnapshot = getServerSnapshot === undefined ? null : getServerSnapshot;
+    return [function () { return memoizedSelector(getSnapshot()); },
+            maybeGetServerSnapshot === null ? undefined : function () { return memoizedSelector(maybeGetServerSnapshot()); }];
+  }, [getSnapshot, getServerSnapshot, selector, isEqual]);
+  var value = useSyncExternalStore(subscribe, _useMemo[0], _useMemo[1]);
+  useEffect(function () { inst.hasValue = true; inst.value = value; }, [value]);
+  useDebugValue(value);
+  return value;
+}`,
+  };
+
+  return {
+    name: 'fragments-cjs-interop',
+    enforce: 'pre' as const,
+    resolveId(source: string) {
+      if (source in virtualModules) {
+        return `\0cjs-interop:${source}`;
+      }
+      return undefined;
+    },
+    load(id: string) {
+      if (!id.startsWith('\0cjs-interop:')) return undefined;
+      const pkg = id.slice('\0cjs-interop:'.length);
+      return virtualModules[pkg];
+    },
+  };
+}
+
 export interface DevServerOptions {
   /** Port to run the server on */
   port?: number;
@@ -117,6 +209,8 @@ export async function createDevServer(
 
   // Find node_modules (handles monorepo setups)
   const nodeModulesPath = findNodeModules(projectRoot);
+  const uiLibRoot = resolveUiLib(nodeModulesPath);
+  const sharedLibRoot = resolveSharedLib();
   console.log(`📁 Using node_modules: ${nodeModulesPath}`);
 
   // Collect installed package roots so Vite can serve files from node_modules
@@ -142,8 +236,8 @@ export async function createDevServer(
       port,
       open: open ? "/fragments/" : false,
       fs: {
-        // Allow serving files from viewer package, project, UI library, and node_modules root
-        allow: [viewerRoot, resolveUiLib(nodeModulesPath), projectRoot, configDir, dirname(nodeModulesPath), ...installedPkgRoots],
+        // Allow serving files from viewer package, project, shared libs, and node_modules root
+        allow: [viewerRoot, uiLibRoot, sharedLibRoot, projectRoot, configDir, dirname(nodeModulesPath), ...installedPkgRoots],
       },
     },
 
@@ -151,6 +245,9 @@ export async function createDevServer(
       // React support (if not already in project config)
       ...(hasReactPlugin(projectViteConfig) ? [] : [react()]),
 
+      // CJS interop for packages imported from within node_modules
+      cjsInteropPlugin(nodeModulesPath),
+
       // Fragments plugins (array including SVGR)
       ...fragmentsPlugin({
         fragmentFiles: allFragmentFiles,
@@ -172,12 +269,12 @@ export async function createDevServer(
       // Dedupe ensures all imports of these packages resolve to the same copy
       dedupe: ["react", "react-dom"],
       alias: {
-        // Allow importing from viewer package
-        "@fragments/viewer": viewerRoot,
-        // Resolve @fragments/ui to installed @fragments-sdk/ui or local source
-        "@fragments/ui": resolveUiLib(nodeModulesPath),
-        // Resolve @fragments/core to the consolidated core source
-        "@fragments/core": resolve(cliPackageRoot, "src/core/index.ts"),
+        // Resolve @fragments-sdk/ui to local source or installed package
+        "@fragments-sdk/ui": uiLibRoot,
+        // Resolve @fragments-sdk/shared to monorepo source or vendored fallback
+        "@fragments-sdk/shared": sharedLibRoot,
+        // Resolve @fragments-sdk/cli/core to the CLI's own core source
+        "@fragments-sdk/cli/core": resolve(cliPackageRoot, "src/core/index.ts"),
         // Ensure ALL react imports resolve to project's node_modules
         // This is critical for viewer files loaded from outside project root
         "react": safeRealpath(join(nodeModulesPath, "react")),

package/src/viewer/styles/globals.css

@@ -1,10 +1,18 @@
 /* ============================================
- * Fragments Viewer Theme System
+ * Fragments Viewer Shell Styles
  * ============================================
- * The viewer shell (sidebar, toolbar, panels) mirrors @fragments/ui
- * tokens so previews and shell feel like the live docs experience.
+ * Viewer-specific token aliases and utility classes.
+ * Base resets (box-sizing, body, scrollbars) come from
+ * @fragments/ui globals imported via entry.tsx.
  * ============================================ */
 
+/* ============================================
+ * Token Aliases
+ * ============================================
+ * Shorthand aliases mapping to --fui-* tokens so the viewer
+ * shell CSS can use shorter variable names.
+ */
+
 :root {
   --bg-primary: var(--fui-bg-primary, #ffffff);
   --bg-secondary: var(--fui-bg-secondary, #f7f7f8);
@@ -48,60 +56,13 @@
 }
 
 /* ============================================
- * Base Element Styles
+ * Viewer-specific overrides
  * ============================================ */
 
 * {
   border-color: var(--border);
 }
 
-*::selection {
-  background-color: var(--color-accent-subtle);
-  color: var(--text-primary);
-}
-
-html {
-  scroll-behavior: smooth;
-}
-
-body {
-  margin: 0;
-  font-family: var(--fui-font-sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
-  background-color: var(--bg-primary);
-  color: var(--text-primary);
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-  font-feature-settings: "rlig" 1, "calt" 1;
-}
-
-/* ============================================
- * Scrollbar Styles
- * ============================================ */
-
-::-webkit-scrollbar {
-  width: 6px;
-  height: 6px;
-}
-
-::-webkit-scrollbar-track {
-  background-color: transparent;
-}
-
-::-webkit-scrollbar-thumb {
-  background-color: var(--text-muted);
-  border-radius: 9999px;
-}
-
-::-webkit-scrollbar-thumb:hover {
-  background-color: var(--text-tertiary);
-}
-
-/* Firefox scrollbar */
-* {
-  scrollbar-width: thin;
-  scrollbar-color: var(--text-muted) transparent;
-}
-
 /* ============================================
  * Theme-aware Utility Classes
  * ============================================ */

package/src/viewer/vendor/shared/src/DocsHeaderBar.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { Header, NavigationMenu } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import { DocsSearchCommand } from './DocsSearchCommand';
+import type { DocsNavLinkRenderer, HeaderNavEntry, NavSection, SearchItem } from './types';
+import { isDropdown } from './types';
+
+interface DocsHeaderBarProps {
+  brand: ReactNode;
+  headerNav: HeaderNavEntry[];
+  mobileSections?: NavSection[];
+  currentPath: string;
+  searchItems: SearchItem[];
+  onSearchSelect: (item: SearchItem) => void;
+  renderLink?: DocsNavLinkRenderer;
+  isActive?: (href: string, currentPath: string) => boolean;
+  actions?: ReactNode;
+  showSkipLink?: boolean;
+  navAriaLabel?: string;
+}
+
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
+  <a href={href} onClick={onClick}>
+    {label}
+  </a>
+);
+
+function defaultIsActive(href: string, currentPath: string): boolean {
+  return currentPath === href || currentPath.startsWith(`${href}/`);
+}
+
+export function DocsHeaderBar({
+  brand,
+  headerNav,
+  mobileSections = [],
+  currentPath,
+  searchItems,
+  onSearchSelect,
+  renderLink = defaultLinkRenderer,
+  isActive = defaultIsActive,
+  actions,
+  showSkipLink = true,
+  navAriaLabel = 'Primary navigation',
+}: DocsHeaderBarProps) {
+  return (
+    <Header aria-label="Documentation header">
+      <Header.Brand>{brand}</Header.Brand>
+      {showSkipLink ? <Header.SkipLink /> : null}
+
+      <NavigationMenu aria-label={navAriaLabel}>
+        <NavigationMenu.List>
+          {headerNav.map((entry) =>
+            isDropdown(entry) ? (
+              <NavigationMenu.Item key={entry.label} value={entry.label}>
+                <NavigationMenu.Trigger>{entry.label}</NavigationMenu.Trigger>
+                <NavigationMenu.Content>
+                  <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '180px' }}>
+                    {entry.items.map((child) => (
+                      <NavigationMenu.Link
+                        key={child.href}
+                        href={child.href}
+                        active={isActive(child.href, currentPath)}
+                        asChild
+                      >
+                        {renderLink({ href: child.href, label: child.label })}
+                      </NavigationMenu.Link>
+                    ))}
+                  </div>
+                </NavigationMenu.Content>
+              </NavigationMenu.Item>
+            ) : (
+              <NavigationMenu.Item key={entry.href}>
+                <NavigationMenu.Link
+                  href={entry.href}
+                  active={isActive(entry.href, currentPath)}
+                  asChild
+                >
+                  {renderLink({ href: entry.href, label: entry.label })}
+                </NavigationMenu.Link>
+              </NavigationMenu.Item>
+            )
+          )}
+        </NavigationMenu.List>
+
+        <NavigationMenu.Viewport />
+
+        <NavigationMenu.MobileContent>
+          {mobileSections.map((section) => (
+            <NavigationMenu.MobileSection key={section.title} label={section.title}>
+              {section.items.map((item) => (
+                <NavigationMenu.Link key={item.href} href={item.href} asChild>
+                  {renderLink({ href: item.href, label: item.label })}
+                </NavigationMenu.Link>
+              ))}
+            </NavigationMenu.MobileSection>
+          ))}
+        </NavigationMenu.MobileContent>
+      </NavigationMenu>
+
+      <Header.Spacer />
+
+      <Header.Search>
+        <DocsSearchCommand searchItems={searchItems} onSelect={onSearchSelect} />
+      </Header.Search>
+
+      <Header.Actions>{actions}</Header.Actions>
+    </Header>
+  );
+}

package/src/viewer/vendor/shared/src/DocsPageAsideHost.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import { createPortal } from 'react-dom';
+import * as React from 'react';
+
+interface DocsPageAsideContextValue {
+  asideVisible: boolean;
+  setAsideVisible: (visible: boolean) => void;
+  asideWidth: string;
+  setAsideWidth: (width: string) => void;
+  asideContainer: HTMLDivElement | null;
+  setAsideContainer: (container: HTMLDivElement | null) => void;
+}
+
+const DocsPageAsideContext = React.createContext<DocsPageAsideContextValue | null>(null);
+
+export function DocsPageAsideProvider({
+  children,
+  defaultWidth = '320px',
+}: {
+  children: React.ReactNode;
+  defaultWidth?: string;
+}) {
+  const [asideVisible, setAsideVisible] = React.useState(false);
+  const [asideWidth, setAsideWidth] = React.useState(defaultWidth);
+  const [asideContainer, setAsideContainer] = React.useState<HTMLDivElement | null>(null);
+
+  return (
+    <DocsPageAsideContext.Provider
+      value={{
+        asideVisible,
+        setAsideVisible,
+        asideWidth,
+        setAsideWidth,
+        asideContainer,
+        setAsideContainer,
+      }}
+    >
+      {children}
+    </DocsPageAsideContext.Provider>
+  );
+}
+
+export function useDocsPageAside() {
+  const context = React.useContext(DocsPageAsideContext);
+  if (!context) {
+    throw new Error('useDocsPageAside must be used within DocsPageAsideProvider');
+  }
+  return context;
+}
+
+export function DocsPageAsidePortal({ children, width = '320px' }: { children: React.ReactNode; width?: string }) {
+  const { setAsideVisible, setAsideWidth, asideContainer } = useDocsPageAside();
+
+  React.useEffect(() => {
+    setAsideVisible(true);
+    setAsideWidth(width);
+
+    return () => {
+      setAsideVisible(false);
+    };
+  }, [setAsideVisible, setAsideWidth, width]);
+
+  if (!asideContainer) {
+    return null;
+  }
+
+  return createPortal(children, asideContainer);
+}
+
+interface DocsPageAsideHostProps {
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export function DocsPageAsideHost({ className, style }: DocsPageAsideHostProps) {
+  const { setAsideContainer } = useDocsPageAside();
+
+  const asideContainerCallback = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      setAsideContainer(node);
+    },
+    [setAsideContainer]
+  );
+
+  return (
+    <div ref={asideContainerCallback} className={className} style={{ height: '100%', ...style }} />
+  );
+}