@fragments-sdk/cli 0.7.8 → 0.7.10

package/src/viewer/constants/ui.ts

@@ -126,6 +126,20 @@ export const VIEWPORT_PRESETS = {
 
 export type ViewportPreset = keyof typeof VIEWPORT_PRESETS | 'custom';
 
+export interface ViewportSize {
+  width: number | null;
+  height: number | null;
+}
+
+/**
+ * Get viewport width from preset.
+ */
+export function getViewportWidth(viewport: ViewportPreset, customSize: ViewportSize): number | null {
+  if (viewport === 'custom') return customSize.width;
+  if (viewport === 'responsive') return null;
+  return VIEWPORT_PRESETS[viewport]?.width ?? null;
+}
+
 /**
  * Get CSS background style for preview pane.
  */

package/src/viewer/entry.tsx

@@ -4,11 +4,10 @@ import { App } from "./components/App.js";
 import { ThemeProvider } from "./components/ThemeProvider.js";
 import { ToastProvider } from "./components/Toast.js";
 import { AppSkeleton } from "./components/SkeletonLoader.js";
-// Viewer shell styles - independent from UI library
-// UI library styles are only loaded in the isolated preview area
+// Fragments UI globals - base resets (box-sizing, body, scrollbars) + --fui-* CSS variables
+import "@fragments-sdk/ui";
+// Viewer-specific token aliases and utility classes
 import "./styles/globals.css";
-// Fragments UI globals - adds --fui-* CSS variables for dogfooding UI components
-import "@fragments/ui";
 
 // App-level error boundary that catches any unhandled errors
 class AppErrorBoundary extends Component<{ children: ReactNode }, { hasError: boolean; error: Error | null; errorInfo: ErrorInfo | null }> {

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

@@ -37,6 +37,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 +52,77 @@ function resolveUiLib(nodeModulesDir: string): string {
   if (existsSync(installedUiDist)) {
     return installedUiDist;
   }
-  // Fallback to local monorepo source
   return localUiLibRoot;
 }
 
+/**
+ * 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;
@@ -151,6 +223,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 +247,10 @@ 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": resolveUiLib(nodeModulesPath),
+        // 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/vite-plugin.ts

@@ -1566,6 +1566,41 @@ function getBaseComponentPath(filePath: string): string {
   return filePath.replace(/\.(fragment|stories)\.(tsx?|jsx?)$/, "");
 }
 
+/**
+ * Extract component name from a fragment/story file path.
+ * e.g., "src/components/Chart/Chart.fragment.tsx" -> "Chart"
+ * e.g., "@fragments-sdk/ui/src/components/Button/Button.fragment.tsx" -> "Button"
+ */
+function extractComponentName(filePath: string): string {
+  const match = filePath.match(/([^/\\]+)\.(fragment|stories)\.(tsx?|jsx?)$/);
+  return match ? match[1] : filePath.split("/").pop() || filePath;
+}
+
+/**
+ * Extract dependency names from a fragment source file (best effort).
+ * Reads the file and looks for `dependencies: [{ name: '...' }, ...]` patterns.
+ * Returns an array of package names, or empty array if extraction fails.
+ */
+async function extractDependenciesFromSource(absolutePath: string): Promise<string[]> {
+  try {
+    const source = await readFile(absolutePath, "utf-8");
+    // Match the dependencies array in the defineFragment call
+    const depsMatch = source.match(/dependencies:\s*\[([\s\S]*?)\]/);
+    if (!depsMatch) return [];
+
+    // Extract name values from dependency objects
+    const names: string[] = [];
+    const nameRegex = /name:\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = nameRegex.exec(depsMatch[1])) !== null) {
+      names.push(match[1]);
+    }
+    return names;
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Generate the virtual fragments module.
  * Uses dynamic imports for lazy loading - fragments are loaded on demand.
@@ -1577,11 +1612,11 @@ function getBaseComponentPath(filePath: string): string {
  * - Merge METADATA from .fragment.tsx (Figma URLs, AI descriptions, usage guidelines)
  * - This gives us the best of both worlds: working renders + rich metadata
  */
-function generateFragmentsModule(
+async function generateFragmentsModule(
   fragmentFiles: Array<{ absolutePath: string; relativePath: string }>,
   config: FragmentsConfig,
   previewConfigPath: string | null
-): string {
+): Promise<string> {
   // Group files by base component path to identify pairs
   const filesByBasePath = new Map<string, {
     storyFile?: { absolutePath: string; relativePath: string };
@@ -1605,8 +1640,8 @@ function generateFragmentsModule(
 
   // Generate loaders with metadata merge support
   // Priority: stories for rendering, fragment for metadata (Figma URLs, etc.)
-  const loaders = Array.from(filesByBasePath.values())
-    .map((files) => {
+  const loaderEntries = await Promise.all(
+    Array.from(filesByBasePath.values()).map(async (files) => {
       // Determine which file to use for rendering
       const primaryFile = files.storyFile || files.fragmentFile;
       if (!primaryFile) return null;
@@ -1618,15 +1653,25 @@ function generateFragmentsModule(
         ? files.fragmentFile.absolutePath
         : null;
 
+      // Extract component name from file path
+      const componentName = extractComponentName(primaryFile.relativePath);
+
+      // Extract dependencies from source (best effort, for error stubs)
+      const fragmentSource = files.fragmentFile || primaryFile;
+      const dependencies = await extractDependenciesFromSource(fragmentSource.absolutePath);
+
       return `  {
     path: "${primaryFile.relativePath}",
     isStory: ${isStory},
+    componentName: ${JSON.stringify(componentName)},
+    dependencies: ${JSON.stringify(dependencies)},
     loader: () => import("${primaryFile.absolutePath}"),
     metadataLoader: ${metadataPath ? `() => import("${metadataPath}")` : 'null'}
   }`;
     })
-    .filter(Boolean)
-    .join(",\n");
+  );
+
+  const loaders = loaderEntries.filter(Boolean).join(",\n");
 
   // Generate preview config import if available
   const previewImport = previewConfigPath
@@ -1647,7 +1692,7 @@ setPreviewConfig({
     : "";
 
   return `
-import { storyModuleToFragment, setPreviewConfig } from "@fragments/core";
+import { storyModuleToFragment, setPreviewConfig } from "@fragments-sdk/cli/core";
 ${previewImport}
 ${previewSetup}
 // Lazy fragment loaders (supports both .fragment.tsx and .stories.tsx)
@@ -1739,11 +1784,27 @@ export async function loadAllFragments() {
         return { path: loader.path, fragment };
       } catch (error) {
         console.warn("[Fragments] Failed to load " + loader.path + ":", error.message);
-        return null;
+        // Create an error stub so the component still appears in the sidebar
+        // with a helpful message about what went wrong
+        return {
+          path: loader.path,
+          fragment: {
+            meta: {
+              name: loader.componentName || loader.path,
+              description: 'Failed to load',
+              category: '',
+            },
+            variants: [],
+            _loadError: {
+              message: error.message,
+              dependencies: loader.dependencies || [],
+            },
+          },
+        };
       }
     })
   );
-  // Filter out failed loads
+  // Filter out nulls (fragments that had no component)
   return results.filter(r => r !== null);
 }