@fragments-sdk/cli 0.7.9 → 0.7.11

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

package/src/viewer/vendor/shared/src/docs-layout.scss

@@ -0,0 +1,28 @@
+.shared-docs-main-content {
+  width: 100%;
+}
+
+.shared-docs-search-container {
+  position: relative;
+  width: 100%;
+  max-width: 240px;
+}
+
+.shared-docs-search-results {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  right: 0;
+  z-index: 100;
+}
+
+.shared-docs-search-result-label {
+  flex: 1;
+  font-weight: var(--fui-font-weight-medium);
+}
+
+.shared-docs-search-result-section {
+  font-size: var(--fui-font-size-xs);
+  color: var(--fui-text-tertiary);
+  margin-left: auto;
+}

package/src/viewer/vendor/shared/src/docs-layout.scss.d.ts

@@ -0,0 +1,2 @@
+declare const styles: string;
+export default styles;

package/src/viewer/vendor/shared/src/index.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import './docs-layout.scss';
+
+export { DocsPageShell } from './DocsPageShell';
+export { DocsSidebarNav } from './DocsSidebarNav';
+export { DocsSearchCommand } from './DocsSearchCommand';
+export { DocsHeaderBar } from './DocsHeaderBar';
+export {
+  DocsPageAsideHost,
+  DocsPageAsidePortal,
+  DocsPageAsideProvider,
+  useDocsPageAside,
+} from './DocsPageAsideHost';
+
+export type {
+  NavItem,
+  NavSection,
+  SearchItem,
+  DocsNavLinkRenderProps,
+  DocsNavLinkRenderer,
+  HeaderNavEntry,
+  HeaderNavLink,
+  HeaderNavDropdown,
+} from './types';
+export { isDropdown } from './types';

package/src/viewer/vendor/shared/src/types.ts

@@ -0,0 +1,41 @@
+import type { ReactElement } from 'react';
+
+export interface NavItem {
+  label: string;
+  href: string;
+}
+
+export interface NavSection {
+  title: string;
+  items: NavItem[];
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+}
+
+export interface SearchItem extends NavItem {
+  section: string;
+}
+
+export interface DocsNavLinkRenderProps {
+  href: string;
+  label: string;
+  onClick?: () => void;
+}
+
+export type DocsNavLinkRenderer = (props: DocsNavLinkRenderProps) => ReactElement;
+
+export interface HeaderNavLink {
+  label: string;
+  href: string;
+}
+
+export interface HeaderNavDropdown {
+  label: string;
+  items: NavItem[];
+}
+
+export type HeaderNavEntry = HeaderNavLink | HeaderNavDropdown;
+
+export function isDropdown(entry: HeaderNavEntry): entry is HeaderNavDropdown {
+  return 'items' in entry;
+}

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