@fragments-sdk/cli 0.2.2

package/src/viewer/components/ComponentGraph.tsx

@@ -0,0 +1,394 @@
+/**
+ * Component Graph Panel - Visualizes component relationships
+ *
+ * Displays a visual graph showing:
+ * - The current component in the center
+ * - Related components (parent, child, sibling, alternative, composition)
+ * - Auto-detected relationships from render analysis
+ * - Click to navigate to related components
+ */
+
+import { useMemo, useState } from "react";
+import clsx from "clsx";
+import type { SegmentDefinition, ComponentRelation, RelationshipType } from "../../core/index.js";
+import { ChevronRightIcon, EmptyIcon, WandIcon } from "./Icons.js";
+import { detectAllRelationships, mergeRelationships } from "../utils/detectRelationships.js";
+
+interface ComponentGraphProps {
+  /** Current segment definition */
+  segment: SegmentDefinition | null;
+  /** All available segments for navigation */
+  allSegments: Array<{ path: string; segment: SegmentDefinition }>;
+  /** Callback when a component is clicked */
+  onNavigate?: (componentName: string) => void;
+}
+
+const RELATIONSHIP_CONFIG: Record<RelationshipType, { label: string; color: string; bgColor: string; icon: string }> = {
+  parent: {
+    label: "Parent",
+    color: "text-purple-600 dark:text-purple-400",
+    bgColor: "bg-purple-100 dark:bg-purple-900/30",
+    icon: "^",
+  },
+  child: {
+    label: "Child",
+    color: "text-blue-600 dark:text-blue-400",
+    bgColor: "bg-blue-100 dark:bg-blue-900/30",
+    icon: "v",
+  },
+  sibling: {
+    label: "Sibling",
+    color: "text-green-600 dark:text-green-400",
+    bgColor: "bg-green-100 dark:bg-green-900/30",
+    icon: "<->",
+  },
+  alternative: {
+    label: "Alternative",
+    color: "text-amber-600 dark:text-amber-400",
+    bgColor: "bg-amber-100 dark:bg-amber-900/30",
+    icon: "~",
+  },
+  composition: {
+    label: "Composition",
+    color: "text-cyan-600 dark:text-cyan-400",
+    bgColor: "bg-cyan-100 dark:bg-cyan-900/30",
+    icon: "+",
+  },
+};
+
+export function ComponentGraph({ segment, allSegments, onNavigate }: ComponentGraphProps) {
+  const [showAutoDetected, setShowAutoDetected] = useState(true);
+
+  // Auto-detect relationships
+  const detectedRelationships = useMemo(() => {
+    if (!segment) return [];
+    try {
+      return detectAllRelationships(segment, allSegments);
+    } catch {
+      return [];
+    }
+  }, [segment, allSegments]);
+
+  // Merge manual and detected relationships
+  const allRelationships = useMemo(() => {
+    if (!segment) return [];
+    return mergeRelationships(segment.relations, showAutoDetected ? detectedRelationships : []);
+  }, [segment, detectedRelationships, showAutoDetected]);
+
+  // Group relations by type
+  const groupedRelations = useMemo(() => {
+    if (allRelationships.length === 0) return null;
+
+    const groups: Record<RelationshipType, Array<ComponentRelation & { isDetected?: boolean; confidence?: number }>> = {
+      parent: [],
+      child: [],
+      sibling: [],
+      alternative: [],
+      composition: [],
+    };
+
+    for (const relation of allRelationships) {
+      groups[relation.relationship].push(relation);
+    }
+
+    return groups;
+  }, [allRelationships]);
+
+  // Find reverse relations (components that reference this one)
+  const reverseRelations = useMemo(() => {
+    if (!segment) return [];
+
+    const componentName = segment.meta.name;
+    const reverse: Array<{ segment: SegmentDefinition; relation: ComponentRelation }> = [];
+
+    for (const { segment: otherSegment } of allSegments) {
+      if (otherSegment.meta.name === componentName) continue;
+      if (!otherSegment.relations) continue;
+
+      for (const relation of otherSegment.relations) {
+        if (relation.component === componentName) {
+          reverse.push({
+            segment: otherSegment,
+            relation: {
+              ...relation,
+              component: otherSegment.meta.name,
+              // Flip the relationship direction for display
+              relationship: flipRelationship(relation.relationship),
+            },
+          });
+        }
+      }
+    }
+
+    return reverse;
+  }, [segment, allSegments]);
+
+  // Check if a component exists in our segments
+  const componentExists = (name: string) => {
+    return allSegments.some(s => s.segment.meta.name === name);
+  };
+
+  const handleNavigate = (componentName: string) => {
+    if (componentExists(componentName) && onNavigate) {
+      onNavigate(componentName);
+    }
+  };
+
+  // No segment selected
+  if (!segment) {
+    return (
+      <div className="h-full flex flex-col">
+        <div className="p-4 border-b border-gray-200 dark:border-gray-700">
+          <h3 className="font-medium text-gray-900 dark:text-gray-100 flex items-center gap-2">
+            Component Graph
+          </h3>
+        </div>
+        <div className="flex-1 flex items-center justify-center p-8 text-center">
+          <div className="max-w-md">
+            <div className="w-12 h-12 rounded-full bg-gray-100 dark:bg-gray-800 flex items-center justify-center mx-auto mb-4">
+              <EmptyIcon className="w-6 h-6 text-gray-400" />
+            </div>
+            <p className="text-sm text-gray-500 dark:text-gray-400">
+              Select a component to view its relationships
+            </p>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  const hasRelations = (groupedRelations && Object.values(groupedRelations).some(g => g.length > 0)) || reverseRelations.length > 0;
+  const detectedCount = detectedRelationships.length;
+
+  // No relations defined
+  if (!hasRelations) {
+    return (
+      <div className="h-full flex flex-col">
+        <div className="p-4 border-b border-gray-200 dark:border-gray-700">
+          <h3 className="font-medium text-gray-900 dark:text-gray-100 flex items-center gap-2">
+            Component Graph
+          </h3>
+        </div>
+        <div className="flex-1 flex items-center justify-center p-8 text-center">
+          <div className="max-w-md">
+            <div className="w-12 h-12 rounded-full bg-gray-100 dark:bg-gray-800 flex items-center justify-center mx-auto mb-4">
+              <EmptyIcon className="w-6 h-6 text-gray-400" />
+            </div>
+            <h4 className="font-medium text-gray-700 dark:text-gray-300 mb-2">
+              No relationships defined
+            </h4>
+            <p className="text-sm text-gray-500 dark:text-gray-400">
+              This component doesn't have any defined relationships. Add a <code className="px-1 py-0.5 bg-gray-100 dark:bg-gray-800 rounded text-xs">relations</code> array to your segment definition to visualize component connections.
+            </p>
+            <div className="mt-4 p-3 bg-gray-50 dark:bg-gray-800/50 rounded-lg text-left">
+              <pre className="text-xs text-gray-600 dark:text-gray-400 overflow-x-auto">
+{`relations: [
+  {
+    component: "ButtonGroup",
+    relationship: "parent",
+    note: "Use ButtonGroup for multiple buttons"
+  },
+  {
+    component: "IconButton",
+    relationship: "alternative",
+    note: "Use when only an icon is needed"
+  }
+]`}
+              </pre>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="h-full flex flex-col">
+      {/* Header */}
+      <div className="p-4 border-b border-gray-200 dark:border-gray-700">
+        <div className="flex items-center justify-between">
+          <h3 className="font-medium text-gray-900 dark:text-gray-100 flex items-center gap-2">
+            Component Graph
+          </h3>
+          {detectedCount > 0 && (
+            <button
+              onClick={() => setShowAutoDetected(!showAutoDetected)}
+              className={clsx(
+                "flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium transition-colors",
+                showAutoDetected
+                  ? "bg-purple-100 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300"
+                  : "text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+              )}
+              title={showAutoDetected ? "Hide composition relationships detected from variants" : "Show composition relationships detected from variants"}
+            >
+              <WandIcon className="w-3.5 h-3.5" />
+              {showAutoDetected ? "Composition on" : "Composition off"}
+            </button>
+          )}
+        </div>
+        <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+          Relationships for <span className="font-medium">{segment.meta.name}</span>
+          {showAutoDetected && detectedCount > 0 && (
+            <span className="ml-1">
+              ({detectedCount} from variants)
+            </span>
+          )}
+        </p>
+      </div>
+
+      {/* Graph visualization */}
+      <div className="flex-1 overflow-y-auto p-4">
+        {/* Defined relations */}
+        {groupedRelations && (
+          <div className="space-y-4">
+            {(Object.entries(groupedRelations) as [RelationshipType, ComponentRelation[]][]).map(
+              ([type, relations]) => {
+                if (relations.length === 0) return null;
+                const config = RELATIONSHIP_CONFIG[type];
+
+                return (
+                  <div key={type}>
+                    <div className="flex items-center gap-2 mb-2">
+                      <span className={clsx("text-xs font-medium uppercase tracking-wide", config.color)}>
+                        {config.label}
+                      </span>
+                      <div className="flex-1 h-px bg-gray-200 dark:bg-gray-700" />
+                    </div>
+                    <div className="space-y-2">
+                      {relations.map((relation, index) => (
+                        <RelationCard
+                          key={`${relation.component}-${index}`}
+                          relation={relation}
+                          config={config}
+                          exists={componentExists(relation.component)}
+                          onNavigate={handleNavigate}
+                        />
+                      ))}
+                    </div>
+                  </div>
+                );
+              }
+            )}
+          </div>
+        )}
+
+        {/* Reverse relations (inbound references) */}
+        {reverseRelations.length > 0 && (
+          <div className="mt-6">
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">
+                Referenced By
+              </span>
+              <div className="flex-1 h-px bg-gray-200 dark:bg-gray-700" />
+            </div>
+            <div className="space-y-2">
+              {reverseRelations.map(({ relation }, index) => {
+                const config = RELATIONSHIP_CONFIG[relation.relationship];
+                return (
+                  <RelationCard
+                    key={`reverse-${relation.component}-${index}`}
+                    relation={relation}
+                    config={config}
+                    exists={componentExists(relation.component)}
+                    onNavigate={handleNavigate}
+                    isReverse
+                  />
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Legend */}
+        <div className="mt-8 pt-4 border-t border-gray-200 dark:border-gray-700">
+          <div className="text-xs font-medium text-gray-500 dark:text-gray-400 mb-2">Legend</div>
+          <div className="grid grid-cols-2 gap-2">
+            {(Object.entries(RELATIONSHIP_CONFIG) as [RelationshipType, typeof RELATIONSHIP_CONFIG[RelationshipType]][]).map(
+              ([type, config]) => (
+                <div key={type} className="flex items-center gap-2">
+                  <span className={clsx("w-2 h-2 rounded-full", config.bgColor, config.color)} />
+                  <span className="text-xs text-gray-600 dark:text-gray-400">{config.label}</span>
+                </div>
+              )
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+interface RelationCardProps {
+  relation: ComponentRelation & { isDetected?: boolean; confidence?: number };
+  config: typeof RELATIONSHIP_CONFIG[RelationshipType];
+  exists: boolean;
+  onNavigate: (name: string) => void;
+  isReverse?: boolean;
+}
+
+function RelationCard({ relation, config, exists, onNavigate, isReverse }: RelationCardProps) {
+  return (
+    <button
+      onClick={() => exists && onNavigate(relation.component)}
+      disabled={!exists}
+      className={clsx(
+        "w-full text-left p-3 rounded-lg border transition-[transform,box-shadow] duration-150",
+        config.bgColor,
+        exists
+          ? "cursor-pointer hover:shadow-md hover:scale-[1.01] border-transparent"
+          : "cursor-not-allowed opacity-60 border-dashed border-gray-300 dark:border-gray-600"
+      )}
+    >
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2 flex-wrap">
+          <span className={clsx("font-medium text-sm", config.color)}>
+            {relation.component}
+          </span>
+          {relation.isDetected && (
+            <span className="flex items-center gap-0.5 text-[10px] uppercase tracking-wide text-purple-600 dark:text-purple-400 bg-purple-100 dark:bg-purple-900/30 px-1.5 py-0.5 rounded">
+              <WandIcon className="w-2.5 h-2.5" />
+              auto
+            </span>
+          )}
+          {isReverse && (
+            <span className="text-[10px] uppercase tracking-wide text-gray-500 dark:text-gray-400 bg-gray-200 dark:bg-gray-700 px-1.5 py-0.5 rounded">
+              inbound
+            </span>
+          )}
+          {!exists && (
+            <span className="text-[10px] uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              (not found)
+            </span>
+          )}
+        </div>
+        {exists && (
+          <ChevronRightIcon className="w-4 h-4 text-gray-400" />
+        )}
+      </div>
+      {relation.note && (
+        <p className="text-xs text-gray-600 dark:text-gray-400 mt-1">
+          {relation.note}
+        </p>
+      )}
+    </button>
+  );
+}
+
+/**
+ * Flip a relationship for reverse display.
+ * e.g., if Button has child: IconButton, then IconButton sees Button as parent
+ */
+function flipRelationship(type: RelationshipType): RelationshipType {
+  switch (type) {
+    case "parent":
+      return "child";
+    case "child":
+      return "parent";
+    case "sibling":
+      return "sibling";
+    case "alternative":
+      return "alternative";
+    case "composition":
+      return "composition";
+  }
+}

package/src/viewer/components/ComponentHeader.tsx

@@ -0,0 +1,85 @@
+import type { SegmentMeta } from '../../core/index.js';
+import clsx from 'clsx';
+import { getStatusConfig } from '../constants/ui.js';
+import { WarningIcon, BeakerIcon } from './Icons.js';
+
+interface ComponentHeaderProps {
+  meta: SegmentMeta;
+}
+
+export function ComponentHeader({ meta }: ComponentHeaderProps) {
+  return (
+    <section id="overview" className="scroll-mt-24 mb-6">
+      {/* Deprecated Warning Banner */}
+      {meta.status === 'deprecated' && (
+        <div className="mb-5 p-4 rounded-xl border border-red-500/30 bg-red-500/10">
+          <div className="flex items-start gap-3">
+            <WarningIcon className="w-5 h-5 text-red-500 flex-shrink-0 mt-0.5" />
+            <div>
+              <h3 className="text-sm font-semibold text-red-600 dark:text-red-400 mb-1">
+                Deprecated Component
+              </h3>
+              <p className="text-sm text-red-600/80 dark:text-red-400/80">
+                This component is deprecated and will be removed in a future version.
+                {meta.tags?.includes('migration') && ' Check the usage guidelines for migration instructions.'}
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Experimental Warning Banner */}
+      {meta.status === 'experimental' && (
+        <div className="mb-5 p-4 rounded-xl border border-purple-500/30 bg-purple-500/10">
+          <div className="flex items-start gap-3">
+            <BeakerIcon className="w-5 h-5 text-purple-500 flex-shrink-0 mt-0.5" />
+            <div>
+              <h3 className="text-sm font-semibold text-purple-600 dark:text-purple-400 mb-1">
+                Experimental Component
+              </h3>
+              <p className="text-sm text-purple-600/80 dark:text-purple-400/80">
+                This component is experimental. The API may change without notice.
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+
+      <h1 className="text-2xl font-semibold text-primary tracking-tight mb-2">
+        {meta.name}
+      </h1>
+      <p className="text-base text-secondary leading-relaxed mb-5">
+        {meta.description}
+      </p>
+
+      <div className="flex flex-wrap items-center gap-2">
+        {/* Category badge */}
+        {meta.category && (
+          <span className="badge badge-default">{meta.category}</span>
+        )}
+
+        {/* Status badge */}
+        {meta.status && (() => {
+          const config = getStatusConfig(meta.status);
+          return config ? (
+            <span className={clsx('badge', config.badge)}>
+              {meta.status}
+            </span>
+          ) : null;
+        })()}
+
+        {/* Tags */}
+        {meta.tags && meta.tags.length > 0 && (
+          <>
+            <span className="text-[--text-muted] mx-1">|</span>
+            {meta.tags.map((tag) => (
+              <span key={tag} className="badge badge-default">
+                {tag}
+              </span>
+            ))}
+          </>
+        )}
+      </div>
+    </section>
+  );
+}