@fragments-sdk/viewer 0.2.1

package/src/components/ComponentGraph.tsx

@@ -0,0 +1,380 @@
+/**
+ * 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 type { FragmentDefinition, ComponentRelation, RelationshipType } from '@fragments-sdk/core';
+import { ChevronRightIcon, WandIcon } from "./Icons.js";
+import { detectAllRelationships, mergeRelationships } from "../utils/detectRelationships.js";
+import { Stack, Text, Badge, Button, CodeBlock, Separator, Box } from "@fragments-sdk/ui";
+import { TreeStructure } from "@phosphor-icons/react";
+import { PanelShell } from "./PanelShell.js";
+
+interface ComponentGraphProps {
+  /** Current fragment definition */
+  fragment: FragmentDefinition | null;
+  /** All available fragments for navigation */
+  allFragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  /** 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: "#9333ea",
+    bgColor: "rgba(147, 51, 234, 0.1)",
+    icon: "^",
+  },
+  child: {
+    label: "Child",
+    color: "#2563eb",
+    bgColor: "rgba(37, 99, 235, 0.1)",
+    icon: "v",
+  },
+  sibling: {
+    label: "Sibling",
+    color: "#16a34a",
+    bgColor: "rgba(22, 163, 74, 0.1)",
+    icon: "<->",
+  },
+  alternative: {
+    label: "Alternative",
+    color: "#d97706",
+    bgColor: "rgba(217, 119, 6, 0.1)",
+    icon: "~",
+  },
+  composition: {
+    label: "Composition",
+    color: "#0891b2",
+    bgColor: "rgba(8, 145, 178, 0.1)",
+    icon: "+",
+  },
+  complementary: {
+    label: "Complementary",
+    color: "#e11d48",
+    bgColor: "rgba(225, 29, 72, 0.1)",
+    icon: "&",
+  },
+  "used-by": {
+    label: "Used By",
+    color: "#4f46e5",
+    bgColor: "rgba(79, 70, 229, 0.1)",
+    icon: "<-",
+  },
+};
+
+export function ComponentGraph({ fragment, allFragments, onNavigate }: ComponentGraphProps) {
+  const [showAutoDetected, setShowAutoDetected] = useState(true);
+
+  // Auto-detect relationships
+  const detectedRelationships = useMemo(() => {
+    if (!fragment) return [];
+    try {
+      return detectAllRelationships(fragment, allFragments);
+    } catch {
+      return [];
+    }
+  }, [fragment, allFragments]);
+
+  // Merge manual and detected relationships
+  const allRelationships = useMemo(() => {
+    if (!fragment) return [];
+    return mergeRelationships(fragment.relations, showAutoDetected ? detectedRelationships : []);
+  }, [fragment, 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: [],
+      complementary: [],
+      "used-by": [],
+    };
+
+    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 (!fragment) return [];
+
+    const componentName = fragment.meta.name;
+    const reverse: Array<{ fragment: FragmentDefinition; relation: ComponentRelation }> = [];
+
+    for (const { fragment: otherFragment } of allFragments) {
+      if (otherFragment.meta.name === componentName) continue;
+      if (!otherFragment.relations) continue;
+
+      for (const relation of otherFragment.relations) {
+        if (relation.component === componentName) {
+          reverse.push({
+            fragment: otherFragment,
+            relation: {
+              ...relation,
+              component: otherFragment.meta.name,
+              // Flip the relationship direction for display
+              relationship: flipRelationship(relation.relationship),
+            },
+          });
+        }
+      }
+    }
+
+    return reverse;
+  }, [fragment, allFragments]);
+
+  // Check if a component exists in our fragments
+  const componentExists = (name: string) => {
+    return allFragments.some(s => s.fragment.meta.name === name);
+  };
+
+  const handleNavigate = (componentName: string) => {
+    if (componentExists(componentName) && onNavigate) {
+      onNavigate(componentName);
+    }
+  };
+
+  const hasRelations = (groupedRelations && Object.values(groupedRelations).some(g => g.length > 0)) || reverseRelations.length > 0;
+  const detectedCount = detectedRelationships.length;
+
+  // Determine empty config
+  const emptyConfig = !fragment ? {
+    icon: <TreeStructure size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+    title: "No component selected",
+    description: "Select a component to view its relationships",
+  } : !hasRelations ? {
+    icon: <TreeStructure size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+    title: "No relationships defined",
+    description: (
+      <>
+        Add a <Box as="code" padding="xs" background="secondary" rounded="sm" style={{ fontSize: '12px', display: 'inline' }}>relations</Box> array to your fragment definition to visualize component connections.
+      </>
+    ),
+    action: (
+      <CodeBlock language="typescript" code={`relations: [
+  {
+    component: "ButtonGroup",
+    relationship: "parent",
+    note: "Use ButtonGroup for multiple buttons"
+  },
+  {
+    component: "IconButton",
+    relationship: "alternative",
+    note: "Use when only an icon is needed"
+  }
+]`} />
+    ),
+  } : undefined;
+
+  // Toolbar with badges + auto-detect toggle (only when we have data)
+  const toolbar = fragment && hasRelations ? (
+    <Stack direction="row" align="center" justify="between" style={{ width: '100%' }}>
+      <Stack direction="row" align="center" gap="sm">
+        <Badge size="sm">{fragment.meta.name}</Badge>
+        <Badge size="sm" variant="default">
+          {allRelationships.length + reverseRelations.length} connection{(allRelationships.length + reverseRelations.length) !== 1 ? 's' : ''}
+        </Badge>
+      </Stack>
+      {detectedCount > 0 && (
+        <AutoDetectToggle
+          showAutoDetected={showAutoDetected}
+          onToggle={() => setShowAutoDetected(!showAutoDetected)}
+        />
+      )}
+    </Stack>
+  ) : undefined;
+
+  return (
+    <PanelShell toolbar={toolbar} empty={emptyConfig}>
+      {/* Defined relations */}
+      {groupedRelations && (
+        <Stack direction="column" gap="md">
+          {(Object.entries(groupedRelations) as [RelationshipType, ComponentRelation[]][]).map(
+            ([type, relations]) => {
+              if (relations.length === 0) return null;
+              const config = RELATIONSHIP_CONFIG[type];
+
+              return (
+                <div key={type}>
+                  <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
+                    <Text size="xs" weight="medium" style={{ textTransform: 'uppercase', letterSpacing: '0.05em', color: config.color }}>
+                      {config.label}
+                    </Text>
+                    <Separator style={{ flex: 1 }} />
+                  </Stack>
+                  <Stack direction="column" gap="sm">
+                    {relations.map((relation, index) => (
+                      <RelationCard
+                        key={`${relation.component}-${index}`}
+                        relation={relation}
+                        config={config}
+                        exists={componentExists(relation.component)}
+                        onNavigate={handleNavigate}
+                      />
+                    ))}
+                  </Stack>
+                </div>
+              );
+            }
+          )}
+        </Stack>
+      )}
+
+      {/* Reverse relations (inbound references) */}
+      {reverseRelations.length > 0 && (
+        <Box style={{ marginTop: '24px' }}>
+          <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
+            <Text size="xs" weight="medium" color="secondary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
+              Referenced By
+            </Text>
+            <Separator style={{ flex: 1 }} />
+          </Stack>
+          <Stack direction="column" gap="sm">
+            {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
+                />
+              );
+            })}
+          </Stack>
+        </Box>
+      )}
+
+      {/* Legend */}
+      <Box borderTop style={{ marginTop: '24px', paddingTop: '12px' }}>
+        <Stack direction="row" gap="md" style={{ flexWrap: 'wrap' }}>
+          {(Object.entries(RELATIONSHIP_CONFIG) as [RelationshipType, typeof RELATIONSHIP_CONFIG[RelationshipType]][]).map(
+            ([type, config]) => (
+              <Stack key={type} direction="row" align="center" gap="xs">
+                <span style={{ width: '6px', height: '6px', borderRadius: '50%', backgroundColor: config.color, flexShrink: 0 }} />
+                <Text size="xs" color="tertiary">{config.label}</Text>
+              </Stack>
+            )
+          )}
+        </Stack>
+      </Box>
+    </PanelShell>
+  );
+}
+
+function AutoDetectToggle({ showAutoDetected, onToggle }: { showAutoDetected: boolean; onToggle: () => void }) {
+  return (
+    <Button
+      onClick={onToggle}
+      variant="ghost"
+      size="sm"
+      style={{
+        background: showAutoDetected ? 'rgba(147, 51, 234, 0.1)' : 'transparent',
+        color: showAutoDetected ? '#9333ea' : undefined,
+      }}
+      title={showAutoDetected ? "Hide composition relationships detected from variants" : "Show composition relationships detected from variants"}
+    >
+      <WandIcon style={{ width: '14px', height: '14px' }} />
+      {showAutoDetected ? "Composition on" : "Composition off"}
+    </Button>
+  );
+}
+
+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) {
+  const [hovered, setHovered] = useState(false);
+
+  return (
+    <button
+      onClick={() => exists && onNavigate(relation.component)}
+      disabled={!exists}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      style={{
+        width: '100%',
+        textAlign: 'left',
+        padding: '12px',
+        borderRadius: '8px',
+        border: exists ? '1px solid transparent' : '1px dashed var(--border)',
+        transition: 'transform 150ms, box-shadow 150ms',
+        background: config.bgColor,
+        cursor: exists ? 'pointer' : 'not-allowed',
+        opacity: exists ? 1 : 0.6,
+        transform: exists && hovered ? 'scale(1.01)' : 'scale(1)',
+        boxShadow: exists && hovered ? '0 4px 6px -1px rgba(0,0,0,0.1)' : 'none',
+      }}
+    >
+      <Stack direction="row" align="center" justify="between">
+        <Stack direction="row" align="center" gap="sm" style={{ flexWrap: 'wrap' }}>
+          <Text weight="medium" size="sm" style={{ color: config.color }}>
+            {relation.component}
+          </Text>
+          {relation.isDetected && (
+            <Badge size="sm" style={{ background: 'rgba(147, 51, 234, 0.1)', color: '#9333ea' }}>
+              <WandIcon style={{ width: '10px', height: '10px' }} />
+              auto
+            </Badge>
+          )}
+          {isReverse && (
+            <Badge size="sm" variant="default">inbound</Badge>
+          )}
+          {!exists && (
+            <Text size="xs" color="secondary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
+              (not found)
+            </Text>
+          )}
+        </Stack>
+        {exists && (
+          <ChevronRightIcon style={{ width: '16px', height: '16px', color: 'var(--text-tertiary)' }} />
+        )}
+      </Stack>
+      {relation.note && (
+        <Text size="xs" color="secondary" style={{ marginTop: '4px' }}>
+          {relation.note}
+        </Text>
+      )}
+    </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 "used-by":
+      return "composition";
+    default:
+      return type;
+  }
+}

package/src/components/ComponentHeader.tsx

@@ -0,0 +1,88 @@
+import type { FragmentMeta } from '@fragments-sdk/core';
+import { Badge, Alert, Text, Stack, Separator } from '@fragments-sdk/ui';
+import { WarningIcon, BeakerIcon } from './Icons.js';
+
+interface ComponentHeaderProps {
+  meta: FragmentMeta;
+}
+
+// Map status to Badge variant
+function getStatusBadgeVariant(status: string): 'success' | 'warning' | 'error' | 'default' {
+  switch (status) {
+    case 'stable': return 'success';
+    case 'experimental': return 'warning';
+    case 'deprecated': return 'error';
+    case 'beta': return 'warning';
+    default: return 'default';
+  }
+}
+
+export function ComponentHeader({ meta }: ComponentHeaderProps) {
+  return (
+    <section id="overview" style={{ scrollMarginTop: '96px', marginBottom: '24px' }}>
+      {/* Deprecated Warning Banner */}
+      {meta.status === 'deprecated' && (
+        <div style={{ marginBottom: '20px' }}>
+          <Alert severity="error">
+            <Alert.Icon><WarningIcon /></Alert.Icon>
+            <Alert.Body>
+              <Alert.Title>Deprecated Component</Alert.Title>
+              <Alert.Content>
+                This component is deprecated and will be removed in a future version.
+                {meta.tags?.includes('migration') && ' Check the usage guidelines for migration instructions.'}
+              </Alert.Content>
+            </Alert.Body>
+          </Alert>
+        </div>
+      )}
+
+      {/* Experimental Warning Banner */}
+      {meta.status === 'experimental' && (
+        <div style={{ marginBottom: '20px' }}>
+          <Alert severity="warning">
+            <Alert.Icon><BeakerIcon /></Alert.Icon>
+            <Alert.Body>
+              <Alert.Title>Experimental Component</Alert.Title>
+              <Alert.Content>
+                This component is experimental. The API may change without notice.
+              </Alert.Content>
+            </Alert.Body>
+          </Alert>
+        </div>
+      )}
+
+      <Text as="h1" size="xl" weight="semibold" style={{ letterSpacing: '-0.025em', marginBottom: '8px' }}>
+        {meta.name}
+      </Text>
+      <Text as="p" size="base" color="secondary" style={{ lineHeight: 1.625, marginBottom: '20px' }}>
+        {meta.description}
+      </Text>
+
+      <Stack direction="row" gap="sm" wrap align="center">
+        {/* Category badge */}
+        {meta.category && (
+          <Badge variant="default">{meta.category}</Badge>
+        )}
+
+        {/* Status badge */}
+        {meta.status && (
+          <Badge variant={getStatusBadgeVariant(meta.status)}>
+            {meta.status}
+          </Badge>
+        )}
+
+        {/* Tags */}
+        {meta.tags && meta.tags.length > 0 && (
+          <>
+            <Separator orientation="vertical" />
+            {meta.tags.map((tag) => (
+              <Badge key={tag} variant="default">
+                {tag}
+              </Badge>
+            ))}
+          </>
+        )}
+      </Stack>
+    </section>
+  );
+}