@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/viewer/server.ts

@@ -20,6 +20,7 @@ import {
 import react from "@vitejs/plugin-react";
 import { resolve, dirname, join } from "node:path";
 import { existsSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { loadConfig, discoverFragmentFiles, discoverInstalledFragments } from "../core/node.js";
 import { fragmentsPlugin } from "./vite-plugin.js";
@@ -183,6 +184,138 @@ export function useSyncExternalStoreWithSelector(subscribe, getSnapshot, getServ
   };
 }
 
+/**
+ * Vite plugin to rewrite CJS require() calls for optional peer dependencies
+ * into ESM imports. UI components use lazy require() inside try-catch for
+ * graceful degradation when optional deps aren't installed. But in the browser
+ * (Vite dev mode), require() doesn't exist — esbuild preserves it inside
+ * try-catch blocks, so it always throws and components return null.
+ *
+ * This plugin detects which optional peer deps are actually installed and
+ * rewrites require('dep') → static ESM import reference in component source.
+ */
+function optionalPeerDepsPlugin(uiLibRoot: string) {
+  // Optional peer deps from @fragments-sdk/ui that use lazy require()
+  const optionalDeps = [
+    '@tanstack/react-table',
+    'shiki',
+    'recharts',
+    'react-day-picker',
+    'date-fns',
+    'react-colorful',
+    'react-markdown',
+    'remark-gfm',
+    '@tiptap/react',
+    '@tiptap/starter-kit',
+    '@tiptap/extension-link',
+  ];
+
+  // Resolve the real path for symlink-safe comparison (pnpm uses symlinks)
+  let resolvedUiRoot: string;
+  try {
+    resolvedUiRoot = realpathSync(uiLibRoot);
+  } catch {
+    resolvedUiRoot = uiLibRoot;
+  }
+
+  // Check which deps are actually installed (pnpm puts them in the package's node_modules)
+  const availableDeps = new Set<string>();
+  for (const dep of optionalDeps) {
+    const depPath = join(uiLibRoot, '..', 'node_modules', ...dep.split('/'));
+    if (existsSync(depPath)) availableDeps.add(dep);
+  }
+
+  return {
+    name: 'fragments:optional-peer-deps',
+    enforce: 'pre' as const,
+    transform(code: string, id: string) {
+      // Only transform .tsx/.ts files from the UI lib source
+      let resolvedId: string;
+      try {
+        resolvedId = realpathSync(id);
+      } catch {
+        resolvedId = id;
+      }
+      if (!resolvedId.startsWith(resolvedUiRoot)) return;
+      if (!id.endsWith('.tsx') && !id.endsWith('.ts')) return;
+      if (!code.includes('require(')) return;
+
+      let transformed = code;
+      const imports: string[] = [];
+      let counter = 0;
+
+      for (const dep of availableDeps) {
+        const escapedDep = dep.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const regex = new RegExp(`require\\(['"]${escapedDep}['"]\\)`, 'g');
+
+        if (regex.test(code)) {
+          const varName = `__fui_dep_${counter++}`;
+          imports.push(`import * as ${varName} from '${dep}';`);
+          // Reset lastIndex after test() since regex has 'g' flag
+          regex.lastIndex = 0;
+          transformed = transformed.replace(regex, varName);
+        }
+      }
+
+      if (imports.length > 0) {
+        transformed = imports.join('\n') + '\n' + transformed;
+        return { code: transformed, map: null };
+      }
+    },
+  };
+}
+
+/**
+ * Auto-detect tsconfig.json paths and convert to Vite-compatible aliases.
+ * Handles JSON with comments (common in tsconfig files).
+ */
+async function detectTsconfigPaths(projectRoot: string): Promise<Record<string, string>> {
+  const aliases: Record<string, string> = {};
+  const tsconfigPath = join(projectRoot, 'tsconfig.json');
+  if (!existsSync(tsconfigPath)) return aliases;
+
+  try {
+    const content = await readFile(tsconfigPath, 'utf-8');
+    // Strip JSON comments (single-line and multi-line)
+    const cleaned = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+    const tsconfig = JSON.parse(cleaned);
+    const paths = tsconfig?.compilerOptions?.paths;
+    const baseUrl = tsconfig?.compilerOptions?.baseUrl || '.';
+
+    if (paths) {
+      for (const [alias, targets] of Object.entries(paths)) {
+        const target = (targets as string[])[0];
+        if (target) {
+          const cleanAlias = alias.replace('/*', '');
+          const cleanTarget = target.replace('/*', '');
+          aliases[cleanAlias] = resolve(projectRoot, baseUrl, cleanTarget);
+        }
+      }
+    }
+  } catch {
+    // Ignore parse errors — tsconfig may be invalid or use unsupported syntax
+  }
+
+  return aliases;
+}
+
+/**
+ * Detect common static asset directories that Storybook projects may reference.
+ * Returns Vite-compatible aliases for serving fonts and assets.
+ */
+async function detectStorybookAliases(projectRoot: string): Promise<Record<string, string>> {
+  const aliases: Record<string, string> = {};
+  const assetsDir = resolve(projectRoot, 'assets');
+  const fontsDir = resolve(projectRoot, 'assets/fonts');
+  if (existsSync(fontsDir)) {
+    aliases['/fonts'] = fontsDir;
+  }
+  if (existsSync(assetsDir)) {
+    aliases['/assets'] = assetsDir;
+  }
+  return aliases;
+}
+
 export interface DevServerOptions {
   /** Port to run the server on */
   port?: number;
@@ -258,6 +391,19 @@ export async function createDevServer(
   const isContextSource = existsSync(join(contextLibRoot, "types/index.ts"));
   console.log(`📁 Using node_modules: ${nodeModulesPath}`);
 
+  // Auto-detect tsconfig paths and Storybook aliases for external projects
+  const tsconfigAliases = await detectTsconfigPaths(projectRoot);
+  const storybookAliases = await detectStorybookAliases(projectRoot);
+  const storybookDir = resolve(projectRoot, '.storybook');
+  const hasStorybookDir = existsSync(storybookDir);
+
+  if (Object.keys(tsconfigAliases).length > 0) {
+    console.log(`📎 Detected ${Object.keys(tsconfigAliases).length} tsconfig path alias(es)`);
+  }
+  if (hasStorybookDir) {
+    console.log(`📘 Detected .storybook directory`);
+  }
+
   // Collect installed package roots so Vite can serve files from node_modules
   const installedPkgRoots = [...new Set(
     installedFiles.map(f => {
@@ -282,8 +428,13 @@ export async function createDevServer(
       port,
       open: open ? "/fragments/" : false,
       fs: {
-        // Allow serving files from viewer package, project, shared libs, and node_modules root
-        allow: [viewerRoot, uiLibRoot, sharedLibRoot, webmcpLibRoot, contextLibRoot, projectRoot, configDir, dirname(nodeModulesPath), ...installedPkgRoots],
+        // Allow serving files from viewer package, project, shared libs, node_modules root, and .storybook
+        allow: [
+          viewerRoot, uiLibRoot, sharedLibRoot, webmcpLibRoot, contextLibRoot,
+          projectRoot, configDir, dirname(nodeModulesPath),
+          ...(hasStorybookDir ? [storybookDir] : []),
+          ...installedPkgRoots,
+        ],
       },
     },
 
@@ -294,6 +445,9 @@ export async function createDevServer(
       // CJS interop for packages imported from within node_modules
       cjsInteropPlugin(nodeModulesPath),
 
+      // Rewrite require() → ESM import for optional peer deps (e.g., @tanstack/react-table)
+      optionalPeerDepsPlugin(uiLibRoot),
+
       // Fragments plugins (array including SVGR)
       ...fragmentsPlugin({
         fragmentFiles: allFragmentFiles,
@@ -308,6 +462,15 @@ export async function createDevServer(
       modules: {
         localsConvention: 'camelCase',
       },
+      preprocessorOptions: {
+        scss: {
+          api: 'modern-compiler' as const,
+          loadPaths: [
+            resolve(projectRoot, 'src'),
+            resolve(projectRoot, 'src/styles'),
+          ],
+        },
+      },
     },
 
     optimizeDeps: {
@@ -320,6 +483,10 @@ export async function createDevServer(
       // Dedupe ensures all imports of these packages resolve to the same copy
       dedupe: ["react", "react-dom"],
       alias: {
+        // Project-specific aliases (tsconfig paths, Storybook static dirs)
+        // Listed first — Fragments-specific aliases below take precedence
+        ...tsconfigAliases,
+        ...storybookAliases,
         // Resolve @fragments-sdk/ui to local source or installed package
         "@fragments-sdk/ui": uiLibRoot,
         // Resolve @fragments-sdk/shared to monorepo source or vendored fallback

package/src/viewer/vendor/shared/src/ComponentDocContent.module.scss

@@ -0,0 +1,10 @@
+.accessibilityList {
+  margin: 0.5rem 0 0;
+  padding-left: 1.125rem;
+  font-size: 0.8125rem;
+  line-height: 1.6;
+
+  li {
+    margin-bottom: 0.25rem;
+  }
+}

package/src/viewer/vendor/shared/src/ComponentDocContent.module.scss.d.ts

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

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

@@ -0,0 +1,274 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  Badge,
+  Box,
+  Card,
+  CardBody,
+  Grid,
+  ListRoot,
+  ListItem,
+  Stack,
+  Text,
+  Alert,
+  AlertIcon,
+  AlertBody,
+  AlertTitle,
+  AlertContent,
+  CodeBlock,
+  Link,
+} from '@fragments-sdk/ui';
+import type { DocProp } from './types';
+import { PropsTable } from './PropsTable';
+import styles from './ComponentDocContent.module.scss';
+
+/** Normalize PascalCase to lowercase with spaces: "AppSwitcher" → "app switcher" */
+function pascalToLowerSpaced(name: string): string {
+  return name.replace(/([A-Z])/g, ' $1').trim().toLowerCase();
+}
+
+/** Detect auto-generated placeholder descriptions like "ActionMenu component" */
+function isGenericDescription(name: string, description: string): boolean {
+  const lower = description.toLowerCase().trim();
+  const nameLower = name.toLowerCase();
+  const nameSpaced = pascalToLowerSpaced(name);
+  return (
+    lower === `${nameLower} component` ||
+    lower === `${nameSpaced} component` ||
+    lower === `${nameLower} component.` ||
+    lower === `${nameSpaced} component.` ||
+    (lower.startsWith('interactive ') && lower.endsWith(' element for triggering actions')) ||
+    (lower.startsWith('form ') && lower.endsWith(' for user input')) ||
+    (lower.startsWith('container ') && lower.endsWith(' for grouping content'))
+  );
+}
+
+/** Detect placeholder usage items like "Use X for its intended purpose" */
+function isGenericUsageItem(item: string): boolean {
+  const lower = item.toLowerCase().trim();
+  return (
+    (lower.startsWith('use ') && lower.endsWith(' for its intended purpose')) ||
+    lower === 'when a more specific component is available' ||
+    lower.startsWith('todo:')
+  );
+}
+
+/** Check if any real (non-placeholder) usage content exists */
+function hasRealUsageContent(usage: { when: string[]; whenNot: string[]; guidelines: string[]; accessibility: string[] }): boolean {
+  const allItems = [...usage.when, ...usage.whenNot, ...usage.guidelines, ...usage.accessibility];
+  return allItems.length > 0 && allItems.some(item => !isGenericUsageItem(item));
+}
+
+/** Filter out generic placeholder items from usage lists */
+function filterRealItems(items: string[]): string[] {
+  return items.filter(item => !isGenericUsageItem(item));
+}
+
+interface StandardReference {
+  id: string;
+  title: string;
+  url: string;
+}
+
+export interface ComponentDocContentProps {
+  name: string;
+  description: string;
+  componentId: string;
+  props: Record<string, DocProp>;
+  variants: Array<{ name: string; description?: string; code?: string }>;
+  usage: {
+    when: string[];
+    whenNot: string[];
+    guidelines: string[];
+    accessibility: string[];
+  };
+  relations: Array<{ component: string; relationship: string; note?: string }>;
+  dependencies?: Array<{ name: string }>;
+  standards?: StandardReference[];
+
+  /** Custom package name for the import path (e.g. '@payroc/react'). Defaults to '@fragments-sdk/ui'. */
+  packageName?: string;
+
+  /** Render a variant example (framework-specific). */
+  renderVariant: (variant: { name: string; description?: string; code?: string }, index: number) => ReactNode;
+  /** Render a related-component link (framework-specific). If omitted, renders plain text. */
+  renderRelatedLink?: (component: string, relationship: string, note: string | undefined, key: string) => ReactNode;
+}
+
+export function ComponentDocContent({
+  name,
+  description,
+  componentId,
+  props,
+  variants,
+  usage,
+  relations,
+  packageName,
+  dependencies,
+  standards,
+  renderVariant,
+  renderRelatedLink,
+}: ComponentDocContentProps) {
+  return (
+    <Stack gap="xl">
+      <Box as="header">
+        <Stack gap="sm">
+          <Text as="h1" size="2xl" weight="semibold">{name}</Text>
+          {!isGenericDescription(name, description) && (
+            <Text as="p" color="secondary">{description}</Text>
+          )}
+        </Stack>
+      </Box>
+
+      <Box as="section">
+        <Stack gap="md">
+          <Text as="h2" id="setup" size="xl" weight="semibold">Setup</Text>
+          <CodeBlock
+            code={`import { ${componentId} } from '${packageName || '@fragments-sdk/ui'}';`}
+            language="tsx"
+          />
+          {dependencies && dependencies.length > 0 && (
+            <Stack gap="sm">
+              <Text as="h3" size="base" weight="semibold">Dependencies</Text>
+              <Text size="sm" color="secondary">
+                This component requires additional packages:
+              </Text>
+              <CodeBlock
+                code={`npm install ${dependencies.map((d) => d.name).join(' ')}`}
+                language="bash"
+              />
+            </Stack>
+          )}
+        </Stack>
+      </Box>
+
+      {variants.length > 0 && (
+        <Box as="section">
+          <Stack gap="md">
+            <Text as="h2" id="examples" size="xl" weight="semibold">Examples</Text>
+            {variants.map((variant, index) => renderVariant(variant, index))}
+          </Stack>
+        </Box>
+      )}
+
+      {Object.keys(props).length > 0 && (
+        <Box as="section">
+          <Stack gap="md">
+            <Text as="h2" id="props" size="xl" weight="semibold">Props</Text>
+            <PropsTable props={props} />
+          </Stack>
+        </Box>
+      )}
+
+      {hasRealUsageContent(usage) && (
+      <Box as="section">
+        <Stack gap="md">
+          <Text as="h2" id="usage-guidelines" size="xl" weight="semibold">Usage Guidelines</Text>
+
+          <Grid columns={{ base: 1, md: 2 }} gap="md">
+            {filterRealItems(usage.when).length > 0 && (
+              <Box background="secondary" rounded="md" padding="md">
+                <Stack gap="sm">
+                  <Text as="h3" id="when-to-use" size="base" weight="semibold">When to use</Text>
+                  <ListRoot variant="disc" gap="xs">
+                    {filterRealItems(usage.when).map((item, i) => (
+                      <ListItem key={i}>{item}</ListItem>
+                    ))}
+                  </ListRoot>
+                </Stack>
+              </Box>
+            )}
+
+            {filterRealItems(usage.whenNot).length > 0 && (
+              <Box background="secondary" rounded="md" padding="md">
+                <Stack gap="sm">
+                  <Text as="h3" id="when-not-to-use" size="base" weight="semibold">When not to use</Text>
+                  <ListRoot variant="disc" gap="xs">
+                    {filterRealItems(usage.whenNot).map((item, i) => (
+                      <ListItem key={i}>{item}</ListItem>
+                    ))}
+                  </ListRoot>
+                </Stack>
+              </Box>
+            )}
+          </Grid>
+
+          {filterRealItems(usage.guidelines).length > 0 && (
+            <Stack gap="sm">
+              <Text as="h3" id="best-practices" size="base" weight="semibold">Best practices</Text>
+              <ListRoot variant="disc" gap="xs">
+                {filterRealItems(usage.guidelines).map((item, i) => (
+                  <ListItem key={i}>{item}</ListItem>
+                ))}
+              </ListRoot>
+            </Stack>
+          )}
+
+          {usage.accessibility.length > 0 && (
+            <Alert severity="info">
+              <AlertIcon />
+              <AlertBody>
+                <AlertTitle>Accessibility</AlertTitle>
+                <AlertContent>
+                  <ul className={styles.accessibilityList}>
+                    {usage.accessibility.map((item, i) => (
+                      <li key={i}>{item}</li>
+                    ))}
+                  </ul>
+                </AlertContent>
+              </AlertBody>
+            </Alert>
+          )}
+        </Stack>
+      </Box>
+      )}
+
+      {standards && standards.length > 0 && (
+        <Box as="section">
+          <Stack gap="sm">
+            <Text as="h2" id="standards" size="xl" weight="semibold">Standards References</Text>
+            <ListRoot variant="disc" gap="xs">
+              {standards.map((standard) => (
+                <ListItem key={standard.id}>
+                  <Link href={standard.url} target="_blank" rel="noreferrer">
+                    {standard.title}
+                  </Link>
+                </ListItem>
+              ))}
+            </ListRoot>
+          </Stack>
+        </Box>
+      )}
+
+      {relations.length > 0 && (
+        <Box as="section">
+          <Stack gap="md">
+            <Text as="h2" id="related-components" size="xl" weight="semibold">Related Components</Text>
+            <Grid columns="auto" minChildWidth="220px" gap="sm">
+              {relations.map((relation) => {
+                const key = `${relation.component}-${relation.relationship}`;
+                if (renderRelatedLink) {
+                  return renderRelatedLink(relation.component, relation.relationship, relation.note, key);
+                }
+                return (
+                  <Card key={key} variant="outlined">
+                    <CardBody>
+                      <Stack gap="xs">
+                        <Stack direction="row" align="center" justify="between">
+                          <Text weight="semibold">{relation.component}</Text>
+                          <Badge size="sm">{relation.relationship}</Badge>
+                        </Stack>
+                        {relation.note && <Text size="sm" color="secondary">{relation.note}</Text>}
+                      </Stack>
+                    </CardBody>
+                  </Card>
+                );
+              })}
+            </Grid>
+          </Stack>
+        </Box>
+      )}
+    </Stack>
+  );
+}

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

@@ -20,8 +20,6 @@ interface DocsHeaderBarProps {
   navAriaLabel?: string;
 }
 
-const EMPTY_SECTIONS: NavSection[] = [];
-
 const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
   <a href={href} onClick={onClick}>
     {label}
@@ -32,20 +30,10 @@ function defaultIsActive(href: string, currentPath: string): boolean {
   return currentPath === href || currentPath.startsWith(`${href}/`);
 }
 
-/** Named component wrapper to avoid inline render functions in JSX */
-function NavLink({ renderer, href, label, onClick }: {
-  renderer: DocsNavLinkRenderer;
-  href: string;
-  label: string;
-  onClick?: () => void;
-}) {
-  return <>{renderer({ href, label, onClick })}</>;
-}
-
 export function DocsHeaderBar({
   brand,
   headerNav,
-  mobileSections = EMPTY_SECTIONS,
+  mobileSections = [],
   currentPath,
   searchItems,
   onSearchSelect,
@@ -75,7 +63,7 @@ export function DocsHeaderBar({
                         active={isActive(child.href, currentPath)}
                         asChild
                       >
-                        <NavLink renderer={renderLink} href={child.href} label={child.label} />
+                        {renderLink({ href: child.href, label: child.label })}
                       </NavigationMenu.Link>
                     ))}
                   </div>
@@ -88,7 +76,7 @@ export function DocsHeaderBar({
                   active={isActive(entry.href, currentPath)}
                   asChild
                 >
-                  <NavLink renderer={renderLink} href={entry.href} label={entry.label} />
+                  {renderLink({ href: entry.href, label: entry.label })}
                 </NavigationMenu.Link>
               </NavigationMenu.Item>
             )
@@ -106,12 +94,12 @@ export function DocsHeaderBar({
               isDropdown(entry) ? (
                 entry.items.map((child) => (
                   <NavigationMenu.Link key={child.href} href={child.href} asChild>
-                    <NavLink renderer={renderLink} href={child.href} label={child.label} />
+                    {renderLink({ href: child.href, label: child.label })}
                   </NavigationMenu.Link>
                 ))
               ) : (
                 <NavigationMenu.Link key={entry.href} href={entry.href} asChild>
-                  <NavLink renderer={renderLink} href={entry.href} label={entry.label} />
+                  {renderLink({ href: entry.href, label: entry.label })}
                 </NavigationMenu.Link>
               )
             )}
@@ -121,7 +109,7 @@ export function DocsHeaderBar({
             <NavigationMenu.MobileSection key={section.title} label={section.title}>
               {section.items.map((item) => (
                 <NavigationMenu.Link key={item.href} href={item.href} asChild>
-                  <NavLink renderer={renderLink} href={item.href} label={item.label} />
+                  {renderLink({ href: item.href, label: item.label })}
                 </NavigationMenu.Link>
               ))}
             </NavigationMenu.MobileSection>

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

@@ -12,6 +12,7 @@ interface DocsPageShellProps {
   children: ReactNode;
   sidebarWidth?: string;
   sidebarCollapsible?: SidebarCollapsible;
+  sidebarDefaultCollapsed?: boolean;
   sidebarAriaLabel?: string;
   mainId?: string;
   mainAriaLabel?: string;
@@ -28,6 +29,7 @@ function DocsPageShellInner({
   children,
   sidebarWidth = '260px',
   sidebarCollapsible = 'offcanvas',
+  sidebarDefaultCollapsed,
   sidebarAriaLabel = 'Documentation sidebar',
   mainId = 'main-content',
   mainAriaLabel = 'Documentation content',
@@ -44,6 +46,7 @@ function DocsPageShellInner({
       <AppShell.Sidebar
         width={sidebarWidth}
         collapsible={sidebarCollapsible}
+        defaultCollapsed={sidebarDefaultCollapsed}
         aria-label={sidebarAriaLabel}
       >
         {sidebar}
@@ -70,6 +73,7 @@ function DocsPageShellPortalInner({
   children,
   sidebarWidth = '260px',
   sidebarCollapsible = 'offcanvas',
+  sidebarDefaultCollapsed,
   sidebarAriaLabel = 'Documentation sidebar',
   mainId = 'main-content',
   mainAriaLabel = 'Documentation content',
@@ -85,6 +89,7 @@ function DocsPageShellPortalInner({
       <AppShell.Sidebar
         width={sidebarWidth}
         collapsible={sidebarCollapsible}
+        defaultCollapsed={sidebarDefaultCollapsed}
         aria-label={sidebarAriaLabel}
       >
         {sidebar}

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

@@ -24,16 +24,6 @@ const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
   </a>
 );
 
-/** Named component wrapper to avoid inline render functions in JSX */
-function SidebarLink({ renderer, href, label, onClick }: {
-  renderer: DocsNavLinkRenderer;
-  href: string;
-  label: string;
-  onClick?: () => void;
-}) {
-  return <>{renderer({ href, label, onClick })}</>;
-}
-
 export function DocsSidebarNav({
   sections,
   currentPath,
@@ -59,12 +49,11 @@ export function DocsSidebarNav({
                 active={isActive(item.href, currentPath)}
                 asChild
               >
-                <SidebarLink
-                  renderer={renderLink}
-                  href={item.href}
-                  label={item.label}
-                  onClick={onNavigate}
-                />
+                {renderLink({
+                  href: item.href,
+                  label: item.label,
+                  onClick: onNavigate,
+                })}
               </Sidebar.Item>
             ))}
           </Sidebar.Section>