@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/viewer/utils/detectRelationships.ts

@@ -1,256 +0,0 @@
-// @ts-nocheck
-/**
- * Auto-detect component relationships from rendered elements
- *
- * Analyzes React elements to discover:
- * - Composition relationships (components used within other components)
- * - Sibling relationships (components in the same category)
- * - Common usage patterns
- */
-
-import { isValidElement, type ReactNode, type ReactElement, Children } from "react";
-import type { FragmentDefinition, ComponentRelation, RelationshipType } from "../../core/index.js";
-
-interface DetectedRelationship {
-  component: string;
-  relationship: RelationshipType;
-  note: string;
-  confidence: number; // 0-1, how confident we are in this relationship
-}
-
-// Cache for relationship detection to avoid repeated expensive render() calls
-const relationshipCache = new Map<string, { timestamp: number; relationships: DetectedRelationship[] }>();
-const CACHE_TTL = 60000; // 1 minute cache
-
-// Cache for known component names (expensive to recompute for 98+ components)
-let knownComponentsCache: { count: number; set: Set<string> } | null = null;
-
-/**
- * Extract component name from a React element
- */
-function getComponentName(element: ReactElement): string | null {
-  const type = element.type;
-
-  if (typeof type === "string") {
-    // HTML element, not a component
-    return null;
-  }
-
-  if (typeof type === "function") {
-    // Function component or class component
-    return type.displayName || type.name || null;
-  }
-
-  if (typeof type === "object" && type !== null) {
-    // Could be forwardRef, memo, etc.
-    const innerType = (type as { $$typeof?: symbol; type?: unknown; render?: unknown })?.type ||
-                      (type as { render?: unknown })?.render;
-    if (typeof innerType === "function") {
-      return (innerType as { displayName?: string; name?: string }).displayName ||
-             (innerType as { name?: string }).name || null;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Recursively collect all component names from an element tree
- */
-function collectComponentNames(
-  element: ReactNode,
-  collected: Set<string> = new Set()
-): Set<string> {
-  if (!isValidElement(element)) {
-    return collected;
-  }
-
-  const name = getComponentName(element as ReactElement);
-  if (name) {
-    collected.add(name);
-  }
-
-  // Traverse children
-  const children = (element.props as { children?: ReactNode })?.children;
-  if (children) {
-    Children.forEach(children, (child) => {
-      collectComponentNames(child, collected);
-    });
-  }
-
-  return collected;
-}
-
-/**
- * Get cached set of known component names
- */
-function getKnownComponents(
-  allFragments: Array<{ path: string; fragment: FragmentDefinition }>
-): Set<string> {
-  // Invalidate cache if fragment count changed
-  if (!knownComponentsCache || knownComponentsCache.count !== allFragments.length) {
-    knownComponentsCache = {
-      count: allFragments.length,
-      set: new Set(allFragments.map(s => s.fragment.meta.name)),
-    };
-  }
-  return knownComponentsCache.set;
-}
-
-/**
- * Detect composition relationships from a fragment's variants
- */
-export function detectCompositionRelationships(
-  fragment: FragmentDefinition,
-  allFragments: Array<{ path: string; fragment: FragmentDefinition }>
-): DetectedRelationship[] {
-  const relationships: DetectedRelationship[] = [];
-  const componentName = fragment.meta.name;
-  const knownComponents = getKnownComponents(allFragments);
-  const usedComponents = new Set<string>();
-
-  // Analyze each variant's render output
-  for (const variant of fragment.variants || []) {
-    try {
-      const rendered = variant.render();
-      const componentNames = collectComponentNames(rendered);
-
-      for (const name of componentNames) {
-        if (name !== componentName && knownComponents.has(name)) {
-          usedComponents.add(name);
-        }
-      }
-    } catch {
-      // Render might fail, skip this variant
-    }
-  }
-
-  // Create composition relationships for used components
-  for (const usedComponent of usedComponents) {
-    relationships.push({
-      component: usedComponent,
-      relationship: "composition",
-      note: `Used within ${componentName} variants`,
-      confidence: 0.8,
-    });
-  }
-
-  return relationships;
-}
-
-/**
- * Detect sibling relationships based on semantic connections.
- *
- * NOTE: Category-based sibling detection was removed because it creates
- * meaningless relationships (e.g., Card → Separator just because both are "layout").
- *
- * True sibling relationships should be defined manually in the fragment definition
- * based on actual use cases (e.g., Table uses Badge for status columns).
- *
- * This function now only detects siblings when:
- * - There's a bidirectional manual relationship (A references B AND B references A)
- * - Components share overlapping variant patterns (future enhancement)
- */
-export function detectSiblingRelationships(
-  _fragment: FragmentDefinition,
-  _allFragments: Array<{ path: string; fragment: FragmentDefinition }>
-): DetectedRelationship[] {
-  // Disabled: Category-based sibling detection creates noise
-  // Meaningful sibling relationships should be defined manually
-  return [];
-}
-
-/**
- * Detect alternative relationships.
- *
- * NOTE: Pattern-based alternative detection was removed because it creates
- * weak relationships based on naming conventions rather than actual use cases.
- *
- * True alternative relationships should be defined manually in the fragment
- * definition based on actual decision criteria (e.g., "Use IconButton instead
- * of Button when only an icon is needed").
- *
- * A better approach would analyze the `whenNot` guidelines for semantic matches,
- * but that requires NLP/semantic analysis which is out of scope.
- */
-export function detectAlternativeRelationships(
-  _fragment: FragmentDefinition,
-  _allFragments: Array<{ path: string; fragment: FragmentDefinition }>
-): DetectedRelationship[] {
-  // Disabled: Pattern-based alternative detection is too weak
-  // Meaningful alternatives should be defined manually with clear rationale
-  return [];
-}
-
-/**
- * Combine all detected relationships and deduplicate
- * Uses caching to avoid expensive render() calls on subsequent views
- */
-export function detectAllRelationships(
-  fragment: FragmentDefinition,
-  allFragments: Array<{ path: string; fragment: FragmentDefinition }>
-): DetectedRelationship[] {
-  const cacheKey = fragment.meta.name;
-  const now = Date.now();
-
-  // Check cache first
-  const cached = relationshipCache.get(cacheKey);
-  if (cached && (now - cached.timestamp) < CACHE_TTL) {
-    return cached.relationships;
-  }
-
-  const all = [
-    ...detectCompositionRelationships(fragment, allFragments),
-    ...detectSiblingRelationships(fragment, allFragments),
-    ...detectAlternativeRelationships(fragment, allFragments),
-  ];
-
-  // Deduplicate by component name, keeping highest confidence
-  const byComponent = new Map<string, DetectedRelationship>();
-
-  for (const rel of all) {
-    const existing = byComponent.get(rel.component);
-    if (!existing || rel.confidence > existing.confidence) {
-      byComponent.set(rel.component, rel);
-    }
-  }
-
-  // Sort by confidence descending
-  const result = Array.from(byComponent.values()).sort((a, b) => b.confidence - a.confidence);
-
-  // Cache the result
-  relationshipCache.set(cacheKey, { timestamp: now, relationships: result });
-
-  return result;
-}
-
-/**
- * Merge manual and auto-detected relationships
- */
-export function mergeRelationships(
-  manual: ComponentRelation[] | undefined,
-  detected: DetectedRelationship[]
-): Array<ComponentRelation & { isDetected?: boolean; confidence?: number }> {
-  const result: Array<ComponentRelation & { isDetected?: boolean; confidence?: number }> = [];
-  const manualComponents = new Set((manual || []).map(r => r.component));
-
-  // Add manual relationships first
-  for (const rel of manual || []) {
-    result.push({ ...rel, isDetected: false });
-  }
-
-  // Add detected relationships that aren't already defined manually
-  for (const rel of detected) {
-    if (!manualComponents.has(rel.component)) {
-      result.push({
-        component: rel.component,
-        relationship: rel.relationship,
-        note: rel.note,
-        isDetected: true,
-        confidence: rel.confidence,
-      });
-    }
-  }
-
-  return result;
-}

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

@@ -1,10 +0,0 @@
-.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

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

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

@@ -1,274 +0,0 @@
-'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

@@ -1,129 +0,0 @@
-'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.MobileBrand>{brand}</NavigationMenu.MobileBrand>
-
-        <NavigationMenu.MobileContent>
-          {/* Render all headerNav items in the mobile drawer */}
-          <NavigationMenu.MobileSection>
-            {headerNav.map((entry) =>
-              isDropdown(entry) ? (
-                entry.items.map((child) => (
-                  <NavigationMenu.Link key={child.href} href={child.href} asChild>
-                    {renderLink({ href: child.href, label: child.label })}
-                  </NavigationMenu.Link>
-                ))
-              ) : (
-                <NavigationMenu.Link key={entry.href} href={entry.href} asChild>
-                  {renderLink({ href: entry.href, label: entry.label })}
-                </NavigationMenu.Link>
-              )
-            )}
-          </NavigationMenu.MobileSection>
-
-          {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>
-  );
-}