@fragments-sdk/cli 0.9.0 → 0.10.0

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

@@ -0,0 +1,68 @@
+.container {
+  margin: 1.5rem 0;
+  overflow-x: auto;
+}
+
+.empty {
+  color: var(--fui-text-tertiary);
+  font-style: italic;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+
+  th, td {
+    text-align: left;
+    padding: 0.75rem;
+    border-bottom: 1px solid var(--fui-border);
+  }
+
+  th {
+    font-weight: var(--fui-font-weight-semibold);
+    color: var(--fui-text-secondary);
+    background-color: var(--fui-bg-secondary);
+  }
+
+  td {
+    vertical-align: top;
+  }
+}
+
+.propName {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+
+  code {
+    font-weight: var(--fui-font-weight-semibold);
+  }
+}
+
+.type {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.values {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+}
+
+.value {
+  font-size: 0.75rem;
+  background-color: var(--fui-bg-tertiary);
+  padding: 0.125rem 0.375rem;
+  border-radius: var(--fui-radius-sm);
+}
+
+.default {
+  color: var(--fui-color-accent);
+}
+
+.noDefault {
+  color: var(--fui-text-tertiary);
+}

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

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

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

@@ -0,0 +1,76 @@
+'use client';
+
+import { Badge } from '@fragments-sdk/ui';
+import type { DocProp } from './types';
+import styles from './PropsTable.module.scss';
+
+/** Detect auto-generated descriptions like "variant prop" */
+function isGenericPropDescription(name: string, description: string): boolean {
+  const lower = description.toLowerCase().trim();
+  return lower === `${name.toLowerCase()} prop` || lower === `${name.toLowerCase()} property`;
+}
+
+interface PropsTableProps {
+  props: Record<string, DocProp>;
+}
+
+export function PropsTable({ props }: PropsTableProps) {
+  const propEntries = Object.entries(props);
+
+  if (propEntries.length === 0) {
+    return <p className={styles.empty}>No props documented</p>;
+  }
+
+  return (
+    <div className={styles.container}>
+      <table className={styles.table}>
+        <thead>
+          <tr>
+            <th>Prop</th>
+            <th>Type</th>
+            <th>Default</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {propEntries.map(([name, prop]) => (
+            <tr key={name}>
+              <td>
+                <span className={styles.propName}>
+                  <code>{name}</code>
+                  {prop.required && (
+                    <Badge size="sm" variant="error">
+                      Required
+                    </Badge>
+                  )}
+                </span>
+              </td>
+              <td>
+                <span className={styles.type}>
+                  <code>{prop.type}</code>
+                  {prop.values && (
+                    <span className={styles.values}>
+                      {prop.values.map((v) => (
+                        <code key={v} className={styles.value}>
+                          {v}
+                        </code>
+                      ))}
+                    </span>
+                  )}
+                </span>
+              </td>
+              <td>
+                {prop.default !== undefined ? (
+                  <code className={styles.default}>{String(prop.default)}</code>
+                ) : (
+                  <span className={styles.noDefault}>Not set</span>
+                )}
+              </td>
+              <td>{prop.description && !isGenericPropDescription(name, prop.description) ? prop.description : '—'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

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

@@ -0,0 +1,114 @@
+// Shared variant preview card — used by docs and CLI viewer
+.card {
+  border: 1px solid var(--fui-border);
+  border-radius: var(--fui-radius-lg);
+  overflow: hidden;
+  background-color: var(--fui-bg-primary);
+}
+
+.highlighted {
+  border-color: var(--fui-color-accent);
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--fui-color-accent) 40%, transparent);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-4);
+  padding: var(--fui-space-2) var(--fui-space-4);
+  background-color: var(--fui-bg-primary);
+  border-bottom: 1px solid var(--fui-border);
+}
+
+.headerContent {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  font-size: var(--fui-font-size-sm);
+  font-weight: var(--fui-font-weight-semibold);
+  color: var(--fui-text-primary);
+  margin: 0;
+  line-height: 1.4;
+}
+
+.description {
+  font-size: var(--fui-font-size-xs);
+  color: var(--fui-text-tertiary);
+  margin: var(--fui-space-0-5) 0 0 0;
+  line-height: 1.4;
+}
+
+// Preview area with subtle dotted grid pattern
+.previewPanel {
+  position: relative;
+  padding: var(--fui-space-4);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--fui-bg-primary);
+
+  // Subtle dotted grid pattern
+  background-image: radial-gradient(circle, var(--fui-border) 1px, transparent 1px);
+  background-size: 24px 24px;
+}
+
+// Code panel
+.codePanel {
+  background-color: var(--fui-bg-tertiary);
+  padding: 0 !important; // Override Tabs panel padding
+
+  // Override CodeBlock styles for embedded use
+  :global([class*="CodeBlock_container"]) {
+    border: none;
+    border-radius: 0;
+    margin: 0;
+  }
+
+  :global([class*="CodeBlock_wrapper"]) {
+    border-top-left-radius: 0;
+    border-top-right-radius: 0;
+    border: none;
+  }
+
+  :global([class*="CodeBlock_title"]) {
+    display: none;
+  }
+}
+
+.placeholder {
+  color: var(--fui-text-tertiary);
+  font-style: italic;
+  font-size: var(--fui-font-size-sm);
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2);
+  flex-shrink: 0;
+}
+
+// Override Tabs styling for preview cards
+.card {
+  :global([class*="Tabs_root"]) {
+    display: flex;
+    flex-direction: column;
+  }
+
+  // Tabs list sits inline with header
+  :global([class*="Tabs_list"]) {
+    padding: 0;
+    border-bottom: none;
+    background-color: transparent;
+    flex-shrink: 0;
+  }
+
+  :global([class*="Tabs_listPills"]) {
+    margin: 0;
+  }
+
+}

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

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

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

@@ -0,0 +1,134 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { CodeBlock, Tabs } from '@fragments-sdk/ui';
+import styles from './VariantPreviewCard.module.scss';
+
+/** Detect auto-generated descriptions like "Alternative Layout variant" or "Default ActionMenu" */
+function isGenericVariantDescription(name: string, description: string): boolean {
+  const lower = description.toLowerCase().trim();
+  const nameLower = name.toLowerCase().trim();
+  return (
+    lower === `${nameLower} variant` ||
+    lower === `default ${nameLower}` ||
+    lower === nameLower ||
+    // "Default SomeComponent" — "Default" followed by a PascalCase component name
+    /^default [a-z][a-z0-9]*$/i.test(description.trim())
+  );
+}
+
+export interface VariantPreviewCardProps {
+  name: string;
+  description?: string;
+  code?: string;
+  children: ReactNode;
+  isLoading?: boolean;
+  error?: string | null;
+  defaultTab?: 'preview' | 'code';
+  highlight?: boolean;
+  id?: string;
+  headerActions?: ReactNode;
+  className?: string;
+}
+
+export function VariantPreviewCard({
+  name,
+  description,
+  code,
+  children,
+  isLoading,
+  error,
+  defaultTab = 'preview',
+  highlight,
+  id,
+  headerActions,
+  className,
+}: VariantPreviewCardProps) {
+  const cardClassName = [
+    styles.card,
+    highlight && styles.highlighted,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const hasPreview = !!children;
+  const hasCode = typeof code === 'string' && code.length > 0;
+
+  // No preview, code only — render without tabs
+  if (!hasPreview && hasCode) {
+    return (
+      <div className={cardClassName} id={id}>
+        <div className={styles.header}>
+          <div className={styles.headerContent}>
+            <h3 className={styles.title}>{name}</h3>
+            {description && !isGenericVariantDescription(name, description) && <p className={styles.description}>{description}</p>}
+          </div>
+          {headerActions && <div className={styles.headerActions}>{headerActions}</div>}
+        </div>
+        <div className={styles.codePanel}>
+          <CodeBlock code={code} language="tsx" />
+        </div>
+      </div>
+    );
+  }
+
+  // No code — render preview only, no tabs
+  if (!hasCode) {
+    return (
+      <div className={cardClassName} id={id}>
+        <div className={styles.header}>
+          <div className={styles.headerContent}>
+            <h3 className={styles.title}>{name}</h3>
+            {description && !isGenericVariantDescription(name, description) && <p className={styles.description}>{description}</p>}
+          </div>
+          {headerActions && <div className={styles.headerActions}>{headerActions}</div>}
+        </div>
+        <div className={styles.previewPanel}>
+          {isLoading ? (
+            <div className={styles.placeholder}>Loading preview...</div>
+          ) : error ? (
+            <div className={styles.placeholder}>Preview error: {error}</div>
+          ) : (
+            children
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  // Both preview and code — render with tabs
+  return (
+    <div className={cardClassName} id={id}>
+      <Tabs defaultValue={defaultTab}>
+        <div className={styles.header}>
+          <div className={styles.headerContent}>
+            <h3 className={styles.title}>{name}</h3>
+            {description && !isGenericVariantDescription(name, description) && <p className={styles.description}>{description}</p>}
+          </div>
+          <div className={styles.headerActions}>
+            {headerActions}
+            <Tabs.List variant="pills">
+              <Tabs.Tab value="preview">Preview</Tabs.Tab>
+              <Tabs.Tab value="code">Code</Tabs.Tab>
+            </Tabs.List>
+          </div>
+        </div>
+
+        <Tabs.Panel value="preview" className={styles.previewPanel}>
+          {isLoading ? (
+            <div className={styles.placeholder}>Loading preview...</div>
+          ) : error ? (
+            <div className={styles.placeholder}>Preview error: {error}</div>
+          ) : (
+            children
+          )}
+        </Tabs.Panel>
+
+        <Tabs.Panel value="code" className={styles.codePanel}>
+          <CodeBlock code={code} language="tsx" />
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+}

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

@@ -24,3 +24,11 @@ export type {
   HeaderNavDropdown,
 } from './types';
 export { isDropdown } from './types';
+
+export { VariantPreviewCard } from './VariantPreviewCard';
+export type { VariantPreviewCardProps } from './VariantPreviewCard';
+
+export { PropsTable } from './PropsTable';
+export { ComponentDocContent } from './ComponentDocContent';
+export type { ComponentDocContentProps } from './ComponentDocContent';
+export type { DocProp } from './types';

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

@@ -39,3 +39,15 @@ export type HeaderNavEntry = HeaderNavLink | HeaderNavDropdown;
 export function isDropdown(entry: HeaderNavEntry): entry is HeaderNavDropdown {
   return 'items' in entry;
 }
+
+/**
+ * Prop documentation type for shared PropsTable / ComponentDocContent.
+ * Intentionally simple — consumers map their richer types into this shape.
+ */
+export interface DocProp {
+  type: string;
+  description: string;
+  required?: boolean;
+  default?: unknown;
+  values?: string[];
+}

package/src/viewer/vite-plugin.ts

@@ -1506,7 +1506,7 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
     // Load virtual modules
     load(id) {
       if (id === VIRTUAL_FRAGMENTS_RESOLVED) {
-        return generateFragmentsModule(fragmentFiles, config, previewConfigPath);
+        return generateFragmentsModule(fragmentFiles, config, previewConfigPath, projectRoot);
       }
       if (id === VIRTUAL_VIEWER_ENTRY_RESOLVED) {
         return generateViewerEntry();
@@ -1636,6 +1636,19 @@ function extractComponentName(filePath: string): string {
  * Reads the file and looks for `dependencies: [{ name: '...' }, ...]` patterns.
  * Returns an array of package names, or empty array if extraction fails.
  */
+/**
+ * Read the consumer project's package.json name field.
+ * Used to show the correct import path in the docs view.
+ */
+async function readProjectPackageName(root: string): Promise<string | null> {
+  try {
+    const pkgJson = JSON.parse(await readFile(resolve(root, "package.json"), "utf-8"));
+    return pkgJson.name || null;
+  } catch {
+    return null;
+  }
+}
+
 async function extractDependenciesFromSource(absolutePath: string): Promise<string[]> {
   try {
     const source = await readFile(absolutePath, "utf-8");
@@ -1670,7 +1683,8 @@ async function extractDependenciesFromSource(absolutePath: string): Promise<stri
 async function generateFragmentsModule(
   fragmentFiles: Array<{ absolutePath: string; relativePath: string }>,
   config: FragmentsConfig,
-  previewConfigPath: string | null
+  previewConfigPath: string | null,
+  projectRoot: string
 ): Promise<string> {
   const authoredVariantCodeCache = new Map<string, Record<string, string>>();
 
@@ -1699,6 +1713,11 @@ async function generateFragmentsModule(
     }
   }
 
+  // Compute sub-component map from story file paths (build-time)
+  const storyOnlyFiles = fragmentFiles.filter(f => isStoryFile(f.relativePath));
+  const { detectSubComponentPaths: _detectSubs } = await import("../core/index.js");
+  const subComponentMap = _detectSubs(storyOnlyFiles);
+
   // Group files by base component path to identify pairs
   const filesByBasePath = new Map<string, {
     storyFile?: { absolutePath: string; relativePath: string };
@@ -1750,11 +1769,16 @@ async function generateFragmentsModule(
       const fragmentSource = files.fragmentFile || primaryFile;
       const dependencies = await extractDependenciesFromSource(fragmentSource.absolutePath);
 
+      // Sub-component detection (only applies to story files)
+      const parentComponent = isStory ? subComponentMap.get(primaryFile.relativePath) : undefined;
+
       return `  {
     path: "${primaryFile.relativePath}",
     isStory: ${isStory},
     componentName: ${JSON.stringify(componentName)},
     dependencies: ${JSON.stringify(dependencies)},
+    isSubComponent: ${!!parentComponent},
+    parentComponent: ${parentComponent ? JSON.stringify(parentComponent) : 'null'},
     loader: () => import("${primaryFile.absolutePath}"),
     metadataLoader: ${metadataPath ? `() => import("${metadataPath}")` : 'null'},
     authoredVariantCode: ${JSON.stringify(authoredVariantCode)}
@@ -1782,10 +1806,16 @@ setPreviewConfig({
 `
     : "";
 
+  // Serialize storybook filter config for the virtual module
+  const storybookFilterConfig = JSON.stringify(config.storybook ?? {});
+
   return `
-import { storyModuleToFragment, setPreviewConfig } from "@fragments-sdk/cli/core";
+import { storyModuleToFragment, setPreviewConfig, checkStoryExclusion, isForceIncluded, isConfigExcluded } from "@fragments-sdk/cli/core";
 ${previewImport}
 ${previewSetup}
+// Storybook filter config (deep-merged with defaults at build time)
+const storybookFilterConfig = ${storybookFilterConfig};
+
 // Lazy fragment loaders (supports both .fragment.tsx and .stories.tsx)
 const fragmentLoaders = [
 ${loaders}
@@ -1848,8 +1878,24 @@ function mergeAuthoredVariantCode(fragment, authoredVariantCode) {
   return fragment;
 }
 
+// Diagnostics: track exclusions for FRAGMENTS_DEBUG
+const exclusionLog = [];
+
+/**
+ * Try to load a paired .fragment.tsx file as fallback when a story is excluded.
+ * Returns the fragment if available, null otherwise.
+ */
+async function tryFallbackFragment(loader) {
+  if (!loader.metadataLoader) return null;
+  try {
+    const mod = await loader.metadataLoader();
+    return mod?.default ? { path: loader.path, fragment: mod.default } : null;
+  } catch { return null; }
+}
+
 // Load all fragments (for initial render)
 // Gracefully handles individual failures - one bad story won't break all fragments
+// Applies smart filtering for Storybook stories (SVG icons, deprecated, test stories, sub-components)
 export async function loadAllFragments() {
   const results = await Promise.all(
     fragmentLoaders.map(async (loader) => {
@@ -1859,6 +1905,30 @@ export async function loadAllFragments() {
           return cached ? { path: loader.path, fragment: cached } : null;
         }
 
+        // --- Pre-load filtering (config-level and sub-component checks) ---
+        if (loader.isStory) {
+          // Force-include bypasses all filters
+          if (!isForceIncluded(loader.componentName, storybookFilterConfig)) {
+            // Config explicit exclude
+            if (isConfigExcluded(loader.componentName, storybookFilterConfig)) {
+              exclusionLog.push({ component: loader.componentName, reason: 'config-excluded', detail: 'Matches storybook.exclude pattern', path: loader.path });
+              const fallback = await tryFallbackFragment(loader);
+              if (fallback) return fallback;
+              loadedFragments.set(loader.path, null);
+              return null;
+            }
+
+            // Sub-component check (directory-based, computed at build time)
+            if (loader.isSubComponent && storybookFilterConfig.excludeSubComponents !== false) {
+              exclusionLog.push({ component: loader.componentName, reason: 'sub-component', detail: 'Sub-component of ' + loader.parentComponent, path: loader.path });
+              const fallback = await tryFallbackFragment(loader);
+              if (fallback) return fallback;
+              loadedFragments.set(loader.path, null);
+              return null;
+            }
+          }
+        }
+
         const module = await loader.loader();
 
         // Convert story modules to fragments at runtime
@@ -1870,6 +1940,29 @@ export async function loadAllFragments() {
             loadedFragments.set(loader.path, null);
             return null;
           }
+
+          // --- Post-load filtering (needs loaded module data) ---
+          if (!isForceIncluded(loader.componentName, storybookFilterConfig)) {
+            const meta = module.default || {};
+            const exclusion = checkStoryExclusion({
+              storybookTitle: meta.title,
+              componentName: fragment.meta?.name || loader.componentName,
+              componentDisplayName: meta.component?.displayName,
+              componentFunctionName: meta.component?.name,
+              tags: meta.tags,
+              variantCount: fragment.variants?.length || 0,
+              filePath: loader.path,
+              config: storybookFilterConfig,
+            });
+
+            if (exclusion.excluded) {
+              exclusionLog.push({ component: fragment.meta?.name || loader.componentName, reason: exclusion.reason, detail: exclusion.detail, path: loader.path });
+              const fallback = await tryFallbackFragment(loader);
+              if (fallback) return fallback;
+              loadedFragments.set(loader.path, null);
+              return null;
+            }
+          }
         } else {
           fragment = module.default;
         }
@@ -1911,6 +2004,15 @@ export async function loadAllFragments() {
       }
     })
   );
+
+  // Log exclusions in debug mode
+  if (exclusionLog.length > 0) {
+    console.log("[Fragments] Filtered " + exclusionLog.length + " component(s)");
+    if (typeof process !== 'undefined' && process.env?.FRAGMENTS_DEBUG) {
+      console.table(exclusionLog);
+    }
+  }
+
   // Filter out nulls (fragments that had no component)
   return results.filter(r => r !== null);
 }
@@ -1959,9 +2061,12 @@ export async function loadFragment(path) {
 let fragments = [];
 const fragmentsPromise = loadAllFragments().then(s => { fragments = s; return s; });
 
-export { fragments, fragmentsPromise };
+export { fragments, fragmentsPromise, exclusionLog };
 export const config = ${JSON.stringify(config)};
 
+// Auto-detect consumer package name from package.json
+export const projectPackageName = ${JSON.stringify(await readProjectPackageName(projectRoot))};
+
 // HMR support
 if (import.meta.hot) {
   import.meta.hot.accept();