@fragments-sdk/cli 0.7.10 → 0.7.12

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/CommandPalette.tsx

@@ -336,10 +336,16 @@ export function CommandPalette({
 function fuzzyScore(text: string, query: string): number {
   if (!query) return 1;
 
+  // Require substring match for short queries to avoid scattered single-char noise
+  if (query.length <= 3 && !text.includes(query)) {
+    return 0;
+  }
+
   let score = 0;
   let queryIndex = 0;
   let consecutiveBonus = 0;
   let lastMatchIndex = -2;
+  let maxGap = 0;
 
   for (let i = 0; i < text.length && queryIndex < query.length; i++) {
     if (text[i] === query[queryIndex]) {
@@ -351,6 +357,11 @@ function fuzzyScore(text: string, query: string): number {
         score += consecutiveBonus;
       } else {
         consecutiveBonus = 0;
+        // Track max gap between matches
+        if (lastMatchIndex >= 0) {
+          const gap = i - lastMatchIndex;
+          if (gap > maxGap) maxGap = gap;
+        }
       }
 
       // Bonus for matching at word start
@@ -366,6 +377,11 @@ function fuzzyScore(text: string, query: string): number {
   // Only return score if all query characters were found
   if (queryIndex < query.length) return 0;
 
+  // Penalize large gaps between matched characters
+  if (maxGap > 5) {
+    score -= maxGap;
+  }
+
   // Bonus for shorter results (more relevant)
   score += Math.max(0, 20 - text.length);
 
@@ -375,5 +391,5 @@ function fuzzyScore(text: string, query: string): number {
   // Bonus for starts with
   if (text.startsWith(query)) score += 30;
 
-  return score;
+  return Math.max(score, 0) || 0;
 }

package/src/viewer/components/IsolatedPreviewFrame.tsx

@@ -162,91 +162,88 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
       onMouseLeave={() => setIsHovered(false)}
     >
       {/* Skeleton loading overlay (initial load) */}
-      <div
-        style={{
-          position: 'absolute',
-          inset: 0,
-          zIndex: 10,
-          transition: 'opacity 150ms',
-          opacity: showSkeleton ? 1 : 0,
-          pointerEvents: showSkeleton ? 'auto' : 'none',
-          background: 'rgba(255, 255, 255, 0.95)',
-        }}
-      >
-        <PreviewSkeleton />
-      </div>
+      {showSkeleton && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            zIndex: 10,
+            background: 'var(--bg-primary, rgba(255, 255, 255, 0.95))',
+          }}
+        >
+          <PreviewSkeleton />
+        </div>
+      )}
 
       {/* Spinner overlay (subsequent renders) */}
-      <div
-        style={{
-          position: 'absolute',
-          inset: 0,
-          zIndex: 10,
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          transition: 'opacity 150ms',
-          opacity: showSpinner ? 1 : 0,
-          pointerEvents: showSpinner ? 'auto' : 'none',
-          background: 'rgba(255, 255, 255, 0.8)',
-        }}
-      >
-        <div style={{ display: 'flex', alignItems: 'center', gap: 8, color: '#6b7280', fontSize: 14 }}>
-          <LoadingSpinner />
-          <span>Rendering...</span>
+      {showSpinner && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            zIndex: 10,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: 'color-mix(in srgb, var(--bg-primary, white) 80%, transparent)',
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8, color: 'var(--text-tertiary, #6b7280)', fontSize: 14 }}>
+            <LoadingSpinner />
+            <span>Rendering...</span>
+          </div>
         </div>
-      </div>
+      )}
 
       {/* Error overlay */}
-      <div
-        style={{
-          position: 'absolute',
-          inset: 0,
-          zIndex: 10,
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          padding: '16px',
-          transition: 'opacity 150ms',
-          opacity: frameError && !isLoading ? 1 : 0,
-          pointerEvents: frameError && !isLoading ? 'auto' : 'none',
-          background: 'rgba(254, 242, 242, 0.95)',
-        }}
-      >
+      {frameError && !isLoading && (
         <div
           style={{
-            background: 'white',
-            border: '1px solid #fecaca',
-            borderRadius: 8,
-            padding: 16,
-            maxWidth: 400,
+            position: 'absolute',
+            inset: 0,
+            zIndex: 10,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            padding: '16px',
+            background: 'rgba(254, 242, 242, 0.95)',
           }}
         >
-          <div style={{ color: '#dc2626', fontWeight: 500, marginBottom: 8 }}>
-            Preview Error
-          </div>
-          <div style={{ color: '#991b1b', fontSize: 13, marginBottom: retryCount < MAX_RETRIES ? 12 : 0 }}>
-            {frameError}
+          <div
+            style={{
+              background: 'white',
+              border: '1px solid #fecaca',
+              borderRadius: 8,
+              padding: 16,
+              maxWidth: 400,
+            }}
+          >
+            <div style={{ color: '#dc2626', fontWeight: 500, marginBottom: 8 }}>
+              Preview Error
+            </div>
+            <div style={{ color: '#991b1b', fontSize: 13, marginBottom: retryCount < MAX_RETRIES ? 12 : 0 }}>
+              {frameError}
+            </div>
+            {retryCount < MAX_RETRIES && (
+              <button
+                onClick={handleRetry}
+                style={{
+                  padding: '6px 12px',
+                  fontSize: 13,
+                  fontWeight: 500,
+                  color: 'white',
+                  background: '#dc2626',
+                  border: 'none',
+                  borderRadius: 6,
+                  cursor: 'pointer',
+                }}
+              >
+                Retry ({MAX_RETRIES - retryCount} remaining)
+              </button>
+            )}
           </div>
-          {retryCount < MAX_RETRIES && (
-            <button
-              onClick={handleRetry}
-              style={{
-                padding: '6px 12px',
-                fontSize: 13,
-                fontWeight: 500,
-                color: 'white',
-                background: '#dc2626',
-                border: 'none',
-                borderRadius: 6,
-                cursor: 'pointer',
-              }}
-            >
-              Retry ({MAX_RETRIES - retryCount} remaining)
-            </button>
-          )}
         </div>
-      </div>
+      )}
 
       {/* The iframe */}
       <iframe

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/LeftSidebar.tsx

@@ -14,16 +14,26 @@ function fuzzyMatch(text: string, pattern: string): FuzzyMatch | null {
   const textLower = text.toLowerCase();
   const patternLower = pattern.toLowerCase();
 
+  // Require substring match for short queries (<=3 chars) to avoid scattered single-char noise
+  if (patternLower.length <= 3 && !textLower.includes(patternLower)) {
+    return null;
+  }
+
   const indices: number[] = [];
   let patternIdx = 0;
   let score = 0;
   let consecutiveBonus = 0;
+  let maxGap = 0;
 
   for (let i = 0; i < textLower.length && patternIdx < patternLower.length; i++) {
     if (textLower[i] === patternLower[patternIdx]) {
       indices.push(i);
-      if (indices.length > 1 && indices[indices.length - 2] === i - 1) {
-        consecutiveBonus += 5;
+      if (indices.length > 1) {
+        const gap = i - indices[indices.length - 2];
+        if (gap === 1) {
+          consecutiveBonus += 5;
+        }
+        if (gap > maxGap) maxGap = gap;
       }
       if (i === 0 || text[i - 1] === ' ' || text[i - 1] === '-' || text[i - 1] === '_') {
         score += 10;
@@ -36,9 +46,19 @@ function fuzzyMatch(text: string, pattern: string): FuzzyMatch | null {
     return null;
   }
 
+  // Penalize large gaps between matched characters
+  if (maxGap > 5) {
+    score -= maxGap * 2;
+  }
+
   score += consecutiveBonus;
   score += (patternLower.length / textLower.length) * 20;
 
+  // Reject very low scores (scattered single-char matches)
+  if (score <= 0 && patternLower.length > 1) {
+    return null;
+  }
+
   return { score, indices };
 }
 
@@ -364,7 +384,7 @@ export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect,
       <Sidebar.Footer>
         <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', width: '100%' }}>
           <Text size="xs" color="tertiary">
-            {isFilterActive ? `${flatItems.length} / ${fragments.length}` : fragments.length} components
+            {isFilterActive || searchResults ? `${flatItems.length} of ${fragments.length}` : fragments.length} components
           </Text>
           <Sidebar.CollapseToggle />
         </div>

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/hooks/useKeyboardShortcuts.ts

@@ -262,7 +262,7 @@ export const SHORTCUTS = [
   { keys: ["p"], description: "Toggle addons panel" },
   { keys: ["m"], description: "Matrix view" },
   { keys: ["v"], description: "Responsive view" },
-  { keys: ["/", "⌘K"], description: "Search" },
+  { keys: ["/", "⌘K"], description: "Command palette" },
   { keys: ["?"], description: "Show shortcuts" },
   { keys: ["Esc"], description: "Close / Clear" },
 ];

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