@fragments-sdk/cli 0.7.10 → 0.7.11

package/src/viewer/components/CodePanel.naming.test.tsx

@@ -43,7 +43,6 @@ describe('CodePanel authored code pipeline', () => {
     const code = __buildFallbackSnippetForTest('Button', variant);
 
     expect(code).toContain("import { Button } from '@/components/Button';");
-    expect(code).toContain('TODO: Add explicit `code` for variant "Primary"');
     expect(code).toContain("<Button variant='primary' disabled={false}>Save Changes</Button>");
   });
 

package/src/viewer/components/CodePanel.tsx

@@ -76,7 +76,6 @@ function buildFallbackSnippet(componentName: string, variant: FragmentVariant):
 
   return `import { ${componentName} } from '@/components/${componentName}';
 
-// TODO: Add explicit \`code\` for variant "${variant.name}" in this fragment file.
 ${usage}`;
 }
 

package/src/viewer/components/Layout.tsx

@@ -1,24 +1,27 @@
 import type { ReactNode } from 'react';
-import { AppShell } from '@fragments-sdk/ui';
+import { DocsPageShell } from '@fragments-sdk/shared';
 
 interface LayoutProps {
   leftSidebar: ReactNode;
   header: ReactNode;
   children: ReactNode;
+  aside?: ReactNode;
 }
 
-export function Layout({ leftSidebar, header, children }: LayoutProps) {
+export function Layout({ leftSidebar, header, children, aside }: LayoutProps) {
   return (
-    <AppShell>
-      <AppShell.Header>
-        {header}
-      </AppShell.Header>
-      <AppShell.Sidebar width="260px" collapsible="icon">
-        {leftSidebar}
-      </AppShell.Sidebar>
-      <AppShell.Main padding="none">
-        {children}
-      </AppShell.Main>
-    </AppShell>
+    <DocsPageShell
+      header={header}
+      sidebar={leftSidebar}
+      sidebarWidth="260px"
+      sidebarCollapsible="icon"
+      sidebarAriaLabel="Preview sidebar"
+      mainAriaLabel="Preview content"
+      mainPadding="none"
+      aside={aside}
+      asideWidth="240px"
+    >
+      {children}
+    </DocsPageShell>
   );
 }

package/src/viewer/components/PreviewArea.tsx

@@ -397,11 +397,12 @@ export function PreviewArea({
   if (useIframeIsolation && variant) {
     // When no specific viewport width, fill the container
     const isFullWidth = !viewportWidth;
+    const scaleFactor = zoom / 100;
 
     return (
       <div style={isFullWidth
-        ? { height: '100%', display: 'flex', flexDirection: 'column' }
-        : { minHeight: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '24px' }
+        ? { height: '100%', display: 'flex', flexDirection: 'column', overflow: 'auto' }
+        : { minHeight: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '24px', overflow: 'auto' }
       }>
         <div
           style={{
@@ -418,15 +419,24 @@ export function PreviewArea({
             }),
           }}
         >
-          <IsolatedPreviewFrame
-            fragmentPath={fragmentPath}
-            variantName={variant.name}
-            theme={previewTheme}
-            width="100%"
-            height="100%"
-            minHeight={viewportHeight || 200}
-            previewKey={previewKey}
-          />
+          <div
+            style={{
+              transform: `scale(${scaleFactor})`,
+              transformOrigin: 'top left',
+              width: zoom !== 100 ? `${100 / scaleFactor}%` : '100%',
+              height: zoom !== 100 ? `${100 / scaleFactor}%` : '100%',
+            }}
+          >
+            <IsolatedPreviewFrame
+              fragmentPath={fragmentPath}
+              variantName={variant.name}
+              theme={previewTheme}
+              width="100%"
+              height="100%"
+              minHeight={viewportHeight || 200}
+              previewKey={previewKey}
+            />
+          </div>
         </div>
       </div>
     );

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.
@@ -55,6 +57,24 @@ function resolveUiLib(nodeModulesDir: string): string {
   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,
@@ -189,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
@@ -214,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],
       },
     },
 
@@ -248,7 +270,9 @@ export async function createDevServer(
       dedupe: ["react", "react-dom"],
       alias: {
         // Resolve @fragments-sdk/ui to local source or installed package
-        "@fragments-sdk/ui": resolveUiLib(nodeModulesPath),
+        "@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

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 }} />
+  );
+}

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

@@ -0,0 +1,119 @@
+'use client';
+
+import { AppShell } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import { DocsPageAsideHost, DocsPageAsideProvider, useDocsPageAside } from './DocsPageAsideHost';
+
+type SidebarCollapsible = 'offcanvas' | 'icon' | 'none';
+
+interface DocsPageShellProps {
+  header: ReactNode;
+  sidebar: ReactNode;
+  children: ReactNode;
+  sidebarWidth?: string;
+  sidebarCollapsible?: SidebarCollapsible;
+  sidebarAriaLabel?: string;
+  mainId?: string;
+  mainAriaLabel?: string;
+  mainPadding?: 'none' | 'sm' | 'md' | 'lg';
+  mainClassName?: string;
+  aside?: ReactNode;
+  asideWidth?: string;
+  useAsidePortal?: boolean;
+}
+
+function DocsPageShellInner({
+  header,
+  sidebar,
+  children,
+  sidebarWidth = '260px',
+  sidebarCollapsible = 'offcanvas',
+  sidebarAriaLabel = 'Documentation sidebar',
+  mainId = 'main-content',
+  mainAriaLabel = 'Documentation content',
+  mainPadding = 'lg',
+  mainClassName,
+  aside,
+  asideWidth = '320px',
+  useAsidePortal = false,
+}: DocsPageShellProps) {
+  return (
+    <AppShell>
+      <AppShell.Header>{header}</AppShell.Header>
+
+      <AppShell.Sidebar
+        width={sidebarWidth}
+        collapsible={sidebarCollapsible}
+        aria-label={sidebarAriaLabel}
+      >
+        {sidebar}
+      </AppShell.Sidebar>
+
+      <AppShell.Main
+        id={mainId}
+        aria-label={mainAriaLabel}
+        padding={mainPadding}
+        className={mainClassName}
+      >
+        {children}
+      </AppShell.Main>
+
+      {useAsidePortal ? <DocsPageAsideHost /> : null}
+      {!useAsidePortal && aside ? <AppShell.Aside width={asideWidth}>{aside}</AppShell.Aside> : null}
+    </AppShell>
+  );
+}
+
+function DocsPageShellPortalInner({
+  header,
+  sidebar,
+  children,
+  sidebarWidth = '260px',
+  sidebarCollapsible = 'offcanvas',
+  sidebarAriaLabel = 'Documentation sidebar',
+  mainId = 'main-content',
+  mainAriaLabel = 'Documentation content',
+  mainPadding = 'lg',
+  mainClassName,
+}: DocsPageShellProps) {
+  const { asideVisible, asideWidth } = useDocsPageAside();
+
+  return (
+    <AppShell>
+      <AppShell.Header>{header}</AppShell.Header>
+
+      <AppShell.Sidebar
+        width={sidebarWidth}
+        collapsible={sidebarCollapsible}
+        aria-label={sidebarAriaLabel}
+      >
+        {sidebar}
+      </AppShell.Sidebar>
+
+      <AppShell.Main
+        id={mainId}
+        aria-label={mainAriaLabel}
+        padding={mainPadding}
+        className={mainClassName}
+      >
+        {children}
+      </AppShell.Main>
+
+      <AppShell.Aside width={asideWidth} visible={asideVisible} aria-label="On-page controls">
+        <DocsPageAsideHost />
+      </AppShell.Aside>
+    </AppShell>
+  );
+}
+
+export function DocsPageShell(props: DocsPageShellProps) {
+  if (props.useAsidePortal) {
+    return (
+      <DocsPageAsideProvider defaultWidth={props.asideWidth}>
+        <DocsPageShellPortalInner {...props} />
+      </DocsPageAsideProvider>
+    );
+  }
+
+  return <DocsPageShellInner {...props} />;
+}

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

@@ -0,0 +1,134 @@
+'use client';
+
+import { Input, Listbox } from '@fragments-sdk/ui';
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
+import type { SearchItem } from './types';
+
+interface DocsSearchCommandProps {
+  searchItems: SearchItem[];
+  onSelect: (item: SearchItem) => void;
+  placeholder?: string;
+  maxResults?: number;
+}
+
+export function DocsSearchCommand({
+  searchItems,
+  onSelect,
+  placeholder = 'Search...',
+  maxResults = 8,
+}: DocsSearchCommandProps) {
+  const [query, setQuery] = useState('');
+  const [isOpen, setIsOpen] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const results = useMemo(() => {
+    if (!query.trim()) return [];
+    const lowerQuery = query.toLowerCase();
+    return searchItems
+      .filter((item) => item.label.toLowerCase().includes(lowerQuery) || item.section.toLowerCase().includes(lowerQuery))
+      .slice(0, maxResults);
+  }, [maxResults, query, searchItems]);
+
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [results]);
+
+  useEffect(() => {
+    const handleGlobalKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+        event.preventDefault();
+        inputRef.current?.focus();
+        setIsOpen(true);
+      }
+    };
+
+    document.addEventListener('keydown', handleGlobalKeyDown);
+    return () => document.removeEventListener('keydown', handleGlobalKeyDown);
+  }, []);
+
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  const handleSelect = (item: SearchItem) => {
+    onSelect(item);
+    setIsOpen(false);
+    setQuery('');
+  };
+
+  const handleKeyDown = (event: ReactKeyboardEvent) => {
+    if (!isOpen || results.length === 0) return;
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        setSelectedIndex((prev) => (prev + 1) % results.length);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        setSelectedIndex((prev) => (prev - 1 + results.length) % results.length);
+        break;
+      case 'Enter':
+        event.preventDefault();
+        if (results[selectedIndex]) {
+          handleSelect(results[selectedIndex]);
+          inputRef.current?.blur();
+        }
+        break;
+      case 'Escape':
+        setIsOpen(false);
+        inputRef.current?.blur();
+        break;
+      default:
+        break;
+    }
+  };
+
+  return (
+    <div ref={containerRef} className="shared-docs-search-container">
+      <Input
+        ref={inputRef}
+        placeholder={placeholder}
+        aria-label="Search"
+        value={query}
+        onChange={(value) => {
+          setQuery(value);
+          setIsOpen(true);
+        }}
+        onFocus={() => setIsOpen(true)}
+        onKeyDown={handleKeyDown}
+        shortcut="⌘K"
+        size="sm"
+      />
+      {isOpen && results.length > 0 && (
+        <Listbox aria-label="Search results" className="shared-docs-search-results">
+          {results.map((item, index) => (
+            <Listbox.Item
+              key={`${item.section}:${item.href}`}
+              selected={index === selectedIndex}
+              onClick={() => handleSelect(item)}
+              onMouseEnter={() => setSelectedIndex(index)}
+            >
+              <span className="shared-docs-search-result-label">{item.label}</span>
+              <span className="shared-docs-search-result-section">{item.section}</span>
+            </Listbox.Item>
+          ))}
+        </Listbox>
+      )}
+      {isOpen && query.trim() && results.length === 0 && (
+        <Listbox aria-label="Search results" className="shared-docs-search-results">
+          <Listbox.Empty>No results found</Listbox.Empty>
+        </Listbox>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,66 @@
+'use client';
+
+import { Sidebar } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import type { DocsNavLinkRenderer, NavSection } from './types';
+
+interface DocsSidebarNavProps {
+  sections: NavSection[];
+  currentPath: string;
+  renderLink?: DocsNavLinkRenderer;
+  onNavigate?: () => void;
+  isActive?: (href: string, currentPath: string) => boolean;
+  footer?: ReactNode;
+  ariaLabel?: string;
+}
+
+function defaultIsActive(href: string, currentPath: string): boolean {
+  return currentPath === href;
+}
+
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
+  <a href={href} onClick={onClick}>
+    {label}
+  </a>
+);
+
+export function DocsSidebarNav({
+  sections,
+  currentPath,
+  renderLink = defaultLinkRenderer,
+  onNavigate,
+  isActive = defaultIsActive,
+  footer,
+  ariaLabel = 'Navigation',
+}: DocsSidebarNavProps) {
+  return (
+    <>
+      <Sidebar.Nav aria-label={ariaLabel}>
+        {sections.map((section) => (
+          <Sidebar.Section
+            key={section.title}
+            label={section.title}
+            collapsible={section.collapsible}
+            defaultOpen={section.defaultOpen}
+          >
+            {section.items.map((item) => (
+              <Sidebar.Item
+                key={item.href}
+                active={isActive(item.href, currentPath)}
+                asChild
+              >
+                {renderLink({
+                  href: item.href,
+                  label: item.label,
+                  onClick: onNavigate,
+                })}
+              </Sidebar.Item>
+            ))}
+          </Sidebar.Section>
+        ))}
+      </Sidebar.Nav>
+
+      <Sidebar.Footer>{footer}</Sidebar.Footer>
+    </>
+  );
+}