@fragments-sdk/viewer 0.2.1

package/src/components/ContractPanel.tsx

@@ -0,0 +1,241 @@
+/**
+ * ContractPanel component - displays FragmentContract metadata for AI agents.
+ * Shows propsSummary, scenarioTags, bans, and a11yRules.
+ */
+
+import { memo } from 'react';
+import type { FragmentContract } from '@fragments-sdk/core';
+import { Stack, Text, Card, Chip, Alert, EmptyState, CodeBlock, Badge, Box } from '@fragments-sdk/ui';
+
+interface ContractPanelProps {
+  contract?: FragmentContract;
+  componentName: string;
+}
+
+export const ContractPanel = memo(function ContractPanel({
+  contract,
+  componentName,
+}: ContractPanelProps) {
+  // Empty state when no contract metadata
+  if (!contract || isContractEmpty(contract)) {
+    return (
+      <EmptyState>
+        <EmptyState.Icon>
+          <svg
+            style={{ width: '48px', height: '48px', opacity: 0.5 }}
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+            />
+          </svg>
+        </EmptyState.Icon>
+        <EmptyState.Title>No contract metadata</EmptyState.Title>
+        <EmptyState.Description>
+          Add a <Box as="code" padding="xs" background="secondary" rounded="sm">contract</Box> field to the fragment definition to enable AI agent features.
+        </EmptyState.Description>
+        <EmptyState.Actions>
+          <CodeBlock
+            code={`contract: {
+  propsSummary: ['variant: primary|secondary'],
+  scenarioTags: ['form.submit', 'action.primary'],
+  a11yRules: ['A11Y_BTN_LABEL'],
+}`}
+            language="typescript"
+            compact
+          />
+        </EmptyState.Actions>
+      </EmptyState>
+    );
+  }
+
+  return (
+    <Box padding="md" style={{ fontSize: '14px' }}>
+      <Stack gap="lg">
+        {/* Props Summary */}
+        {contract.propsSummary && contract.propsSummary.length > 0 && (
+          <Section title="Props Summary">
+            <Card>
+              <Card.Body>
+                <table style={{ width: '100%', fontSize: '12px', borderCollapse: 'collapse' }}>
+                  <thead>
+                    <tr style={{ borderBottom: '1px solid var(--border)' }}>
+                      <th style={{ textAlign: 'left', padding: '8px 16px 8px 0', fontWeight: 500, color: 'var(--text-tertiary)' }}>Name</th>
+                      <th style={{ textAlign: 'left', padding: '8px 16px 8px 0', fontWeight: 500, color: 'var(--text-tertiary)' }}>Type</th>
+                      <th style={{ textAlign: 'left', padding: '8px 0', fontWeight: 500, color: 'var(--text-tertiary)' }}>Description</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {contract.propsSummary.map((prop, i) => {
+                      const parsed = parsePropSummary(prop);
+                      return (
+                        <tr key={i} style={{ borderBottom: i < contract.propsSummary!.length - 1 ? '1px solid var(--border)' : undefined }}>
+                          <td style={{ padding: '8px 16px 8px 0', verticalAlign: 'top' }}>
+                            <Text font="mono" size="xs" weight="medium">{parsed.name}</Text>
+                          </td>
+                          <td style={{ padding: '8px 16px 8px 0', verticalAlign: 'top' }}>
+                            <Badge size="sm">{parsed.type}</Badge>
+                          </td>
+                          <td style={{ padding: '8px 0', verticalAlign: 'top' }}>
+                            <Text size="xs" color="secondary">{parsed.description}</Text>
+                          </td>
+                        </tr>
+                      );
+                    })}
+                  </tbody>
+                </table>
+              </Card.Body>
+            </Card>
+          </Section>
+        )}
+
+        {/* Scenario Tags */}
+        {contract.scenarioTags && contract.scenarioTags.length > 0 && (
+          <Section title="Scenario Tags" subtitle="Used by fragments_suggest for AI queries">
+            <Stack direction="row" gap="sm" style={{ flexWrap: 'wrap' }}>
+              {contract.scenarioTags.map((tag, i) => (
+                <Chip key={i}>{tag}</Chip>
+              ))}
+            </Stack>
+          </Section>
+        )}
+
+        {/* Accessibility Rules */}
+        {contract.a11yRules && contract.a11yRules.length > 0 && (
+          <Section title="Accessibility Rules">
+            <Stack gap="sm">
+              {contract.a11yRules.map((rule, i) => (
+                <Box key={i} padding="sm" background="secondary" rounded="sm">
+                <Stack
+                  direction="row"
+                  align="center"
+                  gap="sm"
+                >
+                  <span style={{ color: '#22c55e' }}>
+                    <svg style={{ width: '16px', height: '16px' }} fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                  </span>
+                  <Text font="mono" size="xs" color="secondary">{rule}</Text>
+                </Stack>
+                </Box>
+              ))}
+            </Stack>
+          </Section>
+        )}
+
+        {/* Bans */}
+        {contract.bans && contract.bans.length > 0 && (
+          <Section title="Usage Bans" subtitle="Patterns to avoid">
+            <Stack gap="sm">
+              {contract.bans.map((ban, i) => (
+                <Alert key={i} severity="warning">
+                  <Alert.Body>
+                    <Alert.Title>
+                      <Text font="mono" size="xs">{ban.pattern}</Text>
+                    </Alert.Title>
+                    <Alert.Content>
+                      <Text size="xs" color="tertiary">{ban.message}</Text>
+                    </Alert.Content>
+                  </Alert.Body>
+                </Alert>
+              ))}
+            </Stack>
+          </Section>
+        )}
+
+        {/* Empty sections message */}
+        {isPartialContract(contract) && (
+          <Alert severity="info">
+            <Alert.Body>
+              <Alert.Content>
+                Tip: Add more contract fields to help AI agents better understand this component.
+              </Alert.Content>
+            </Alert.Body>
+          </Alert>
+        )}
+      </Stack>
+    </Box>
+  );
+});
+
+// Helper component for consistent section styling
+interface SectionProps {
+  title: string;
+  subtitle?: string;
+  children: React.ReactNode;
+}
+
+function Section({ title, subtitle, children }: SectionProps) {
+  return (
+    <div>
+      <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
+        <Text as="h3" size="xs" weight="semibold">{title}</Text>
+        {subtitle && (
+          <Text size="xs" color="tertiary">({subtitle})</Text>
+        )}
+      </Stack>
+      {children}
+    </div>
+  );
+}
+
+// Check if contract is empty or has no meaningful content
+function isContractEmpty(contract: FragmentContract): boolean {
+  return (
+    (!contract.propsSummary || contract.propsSummary.length === 0) &&
+    (!contract.scenarioTags || contract.scenarioTags.length === 0) &&
+    (!contract.a11yRules || contract.a11yRules.length === 0) &&
+    (!contract.bans || contract.bans.length === 0)
+  );
+}
+
+// Check if contract has some but not all fields
+function isPartialContract(contract: FragmentContract): boolean {
+  const fieldCount = [
+    contract.propsSummary?.length ?? 0,
+    contract.scenarioTags?.length ?? 0,
+    contract.a11yRules?.length ?? 0,
+    contract.bans?.length ?? 0,
+  ].filter(n => n > 0).length;
+
+  return fieldCount > 0 && fieldCount < 3;
+}
+
+// Parse a prop summary string like "name: type - description" or "name: type (default: value)"
+function parsePropSummary(prop: string): { name: string; type: string; description: string } {
+  // Try to match "name: type - description" format
+  const colonIndex = prop.indexOf(':');
+  if (colonIndex === -1) {
+    return { name: prop, type: '', description: '' };
+  }
+
+  const name = prop.slice(0, colonIndex).trim();
+  const rest = prop.slice(colonIndex + 1).trim();
+
+  // Check for " - description" pattern
+  const dashIndex = rest.indexOf(' - ');
+  if (dashIndex !== -1) {
+    const type = rest.slice(0, dashIndex).trim();
+    const description = rest.slice(dashIndex + 3).trim();
+    return { name, type, description };
+  }
+
+  // Check for "(default: value)" or "(default: value) description" pattern
+  const defaultMatch = rest.match(/^([^(]+)(\(default:\s*[^)]+\))(.*)$/);
+  if (defaultMatch) {
+    const type = defaultMatch[1].trim();
+    const defaultInfo = defaultMatch[2];
+    const extraDesc = defaultMatch[3].trim();
+    const description = extraDesc ? `${defaultInfo} ${extraDesc}` : defaultInfo;
+    return { name, type, description };
+  }
+
+  // Just type, no description
+  return { name, type: rest, description: '' };
+}

package/src/components/DeviceMockup.tsx

@@ -0,0 +1,156 @@
+/**
+ * DeviceMockup - renders children inside a tablet or mobile device frame.
+ *
+ * Provides physical chrome (bezel, buttons, notch/camera, home indicator)
+ * around the content for realistic device preview.
+ */
+
+import { memo, type ReactNode } from "react";
+
+interface DeviceMockupProps {
+  type: "tablet" | "mobile";
+  width: number;
+  children: ReactNode;
+}
+
+const BEZEL_BG = "#1a1a1a";
+const BUTTON_BG = "#2a2a2a";
+
+const MOBILE_BUTTONS: Array<{
+  side: "left" | "right";
+  top: number;
+  height: number;
+}> = [
+  { side: "left", top: 96, height: 32 },
+  { side: "left", top: 144, height: 48 },
+  { side: "left", top: 208, height: 48 },
+  { side: "right", top: 128, height: 64 },
+];
+
+export const DeviceMockup = memo(function DeviceMockup({
+  type,
+  width,
+  children,
+}: DeviceMockupProps) {
+  const isMobile = type === "mobile";
+  const frameWidth = width + 24;
+  const frameHeight = isMobile ? 720 : 1024;
+  const screenHeight = frameHeight - (isMobile ? 80 : 48);
+
+  return (
+    <div style={{ position: "relative", flexShrink: 0, width: frameWidth }}>
+      {/* Bezel */}
+      <div
+        style={{
+          position: "relative",
+          borderRadius: 40,
+          background: BEZEL_BG,
+          padding: 12,
+          boxShadow:
+            "0 25px 50px -12px rgba(0, 0, 0, 0.5), inset 0 1px 0 rgba(255,255,255,0.1)",
+        }}
+      >
+        {/* Physical side buttons (mobile only) */}
+        {isMobile &&
+          MOBILE_BUTTONS.map((btn) => (
+            <div
+              key={`${btn.side}-${btn.top}`}
+              style={{
+                position: "absolute",
+                [btn.side]: -3,
+                top: btn.top,
+                width: 3,
+                height: btn.height,
+                background: BUTTON_BG,
+                borderRadius:
+                  btn.side === "left" ? "4px 0 0 4px" : "0 4px 4px 0",
+              }}
+            />
+          ))}
+
+        {/* Screen */}
+        <div
+          style={{
+            position: "relative",
+            borderRadius: 32,
+            overflow: "hidden",
+            background: "white",
+            height: screenHeight,
+          }}
+        >
+          {/* Notch (mobile) or camera dot (tablet) */}
+          {isMobile ? (
+            <div
+              style={{
+                position: "absolute",
+                top: 0,
+                left: "50%",
+                transform: "translateX(-50%)",
+                width: 120,
+                height: 30,
+                background: BEZEL_BG,
+                borderRadius: "0 0 16px 16px",
+                zIndex: 10,
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                gap: 8,
+              }}
+            >
+              <div
+                style={{
+                  width: 8,
+                  height: 8,
+                  borderRadius: "50%",
+                  background: BUTTON_BG,
+                }}
+              />
+              <div
+                style={{
+                  width: 48,
+                  height: 6,
+                  borderRadius: 9999,
+                  background: BUTTON_BG,
+                }}
+              />
+            </div>
+          ) : (
+            <div
+              style={{
+                position: "absolute",
+                top: 8,
+                left: "50%",
+                transform: "translateX(-50%)",
+                width: 12,
+                height: 12,
+                borderRadius: "50%",
+                background: BUTTON_BG,
+                zIndex: 10,
+              }}
+            />
+          )}
+
+          {/* Content area */}
+          <div style={{ width: "100%", height: "100%", overflow: "auto" }}>
+            {children}
+          </div>
+
+          {/* Home indicator bar */}
+          <div
+            style={{
+              position: "absolute",
+              bottom: 8,
+              left: "50%",
+              transform: "translateX(-50%)",
+              width: 100,
+              height: 4,
+              background: "rgba(0, 0, 0, 0.2)",
+              borderRadius: 9999,
+              zIndex: 10,
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+});

package/src/components/EmptyVariantMessage.tsx

@@ -0,0 +1,54 @@
+import { Stack, Text, Alert } from "@fragments-sdk/ui";
+
+interface EmptyVariantMessageProps {
+  reason: string;
+  variantName: string;
+  hint?: string;
+}
+
+export function EmptyVariantMessage({ reason, variantName, hint }: EmptyVariantMessageProps) {
+  return (
+    <Alert variant="warning">
+      <Alert.Body>
+        <Alert.Title>Variant "{variantName}" rendered empty</Alert.Title>
+        <Alert.Content>
+          <Stack direction="column" gap="sm">
+            <Text size="xs" color="secondary">
+              {reason}
+            </Text>
+            {hint && (
+              <Text size="xs" color="tertiary">
+                <Text as="span" size="xs" weight="semibold">
+                  Tip:
+                </Text>{" "}
+                {hint}
+              </Text>
+            )}
+            <div>
+              <Text size="xs" color="tertiary" weight="semibold">
+                Common causes:
+              </Text>
+              <ul style={{ marginTop: "4px", marginLeft: "16px", listStyleType: "disc" }}>
+                <li>
+                  <Text size="xs" color="secondary">
+                    Component requires props that weren't provided
+                  </Text>
+                </li>
+                <li>
+                  <Text size="xs" color="secondary">
+                    Component renders conditionally and conditions aren't met
+                  </Text>
+                </li>
+                <li>
+                  <Text size="xs" color="secondary">
+                    Story args reference variables that don't exist in this context
+                  </Text>
+                </li>
+              </ul>
+            </div>
+          </Stack>
+        </Alert.Content>
+      </Alert.Body>
+    </Alert>
+  );
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,97 @@
+import { Component, type ReactNode, type ErrorInfo } from 'react';
+import { Button, Alert, CodeBlock, Collapsible, Stack, Text } from '@fragments-sdk/ui';
+import { ErrorIcon, RefreshIcon } from './Icons.js';
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  componentName?: string;
+  fallback?: ReactNode;
+  onRetry?: () => void;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+  errorInfo: ErrorInfo | null;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null, errorInfo: null };
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('Component Error:', error);
+    console.error('Component Stack:', errorInfo.componentStack);
+    this.setState({ errorInfo });
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: null, errorInfo: null });
+    this.props.onRetry?.();
+  };
+
+  render() {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      const { componentName } = this.props;
+      const { error, errorInfo } = this.state;
+
+      return (
+        <Alert variant="error">
+          <Alert.Icon>
+            <ErrorIcon style={{ width: '24px', height: '24px' }} />
+          </Alert.Icon>
+          <Alert.Body>
+            <Alert.Title>
+              {componentName ? `Error rendering ${componentName}` : 'Component Error'}
+            </Alert.Title>
+            <Alert.Content>
+              <Stack direction="column" gap="sm">
+                {error && (
+                  <Text size="sm" font="mono" style={{ color: '#dc2626' }}>
+                    {error.message}
+                  </Text>
+                )}
+
+                {errorInfo?.componentStack && (
+                  <Collapsible>
+                    <Collapsible.Trigger>
+                      <Text size="xs" color="tertiary" style={{ cursor: 'pointer' }}>
+                        Show stack trace
+                      </Text>
+                    </Collapsible.Trigger>
+                    <Collapsible.Content>
+                      <div style={{ marginTop: '8px' }}>
+                        <CodeBlock language="plaintext">
+                          {error?.stack || errorInfo.componentStack}
+                        </CodeBlock>
+                      </div>
+                    </Collapsible.Content>
+                  </Collapsible>
+                )}
+
+                <div>
+                  <Button variant="danger" size="sm" onClick={this.handleRetry}>
+                    <RefreshIcon style={{ width: '14px', height: '14px' }} />
+                    Retry
+                  </Button>
+                </div>
+              </Stack>
+            </Alert.Content>
+          </Alert.Body>
+        </Alert>
+      );
+    }
+
+    return this.props.children;
+  }
+}