@contractspec/lib.example-shared-ui 1.11.0 → 1.12.0

package/dist/node/hooks/useBehaviorTracking.js

@@ -0,0 +1,157 @@
+// src/hooks/useBehaviorTracking.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+"use client";
+var BEHAVIOR_STORAGE_KEY = "contractspec-behavior-data";
+var ALL_FEATURES = [
+  "playground",
+  "specs",
+  "builder",
+  "markdown",
+  "evolution",
+  "canvas_add",
+  "canvas_delete",
+  "spec_save",
+  "spec_validate",
+  "ai_suggestions"
+];
+function useBehaviorTracking(templateId) {
+  const [events, setEvents] = useState([]);
+  const sessionStartRef = useRef(new Date);
+  const [eventCount, setEventCount] = useState(0);
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(BEHAVIOR_STORAGE_KEY);
+      if (stored) {
+        const data = JSON.parse(stored);
+        setEvents(data.events.map((e) => ({
+          ...e,
+          timestamp: new Date(e.timestamp)
+        })));
+        sessionStartRef.current = new Date(data.sessionStart);
+      }
+    } catch {}
+  }, []);
+  useEffect(() => {
+    if (events.length > 0) {
+      try {
+        localStorage.setItem(BEHAVIOR_STORAGE_KEY, JSON.stringify({
+          events: events.map((e) => ({
+            ...e,
+            timestamp: e.timestamp.toISOString()
+          })),
+          sessionStart: sessionStartRef.current.toISOString()
+        }));
+      } catch {}
+    }
+  }, [events]);
+  const trackEvent = useCallback((type, metadata) => {
+    const event = {
+      type,
+      timestamp: new Date,
+      templateId,
+      metadata
+    };
+    setEvents((prev) => [...prev, event]);
+    setEventCount((prev) => prev + 1);
+  }, [templateId]);
+  const getEventsByType = useCallback((type) => {
+    return events.filter((e) => e.type === type);
+  }, [events]);
+  const getSummary = useCallback(() => {
+    const now = new Date;
+    const sessionDuration = now.getTime() - sessionStartRef.current.getTime();
+    const templateCounts = new Map;
+    for (const event of events) {
+      const count = templateCounts.get(event.templateId) ?? 0;
+      templateCounts.set(event.templateId, count + 1);
+    }
+    const mostUsedTemplates = Array.from(templateCounts.entries()).map(([templateId2, count]) => ({ templateId: templateId2, count })).sort((a, b) => b.count - a.count).slice(0, 3);
+    const modeCounts = new Map;
+    for (const event of events) {
+      if (event.type === "mode_change" && event.metadata?.mode) {
+        const mode = event.metadata.mode;
+        const count = modeCounts.get(mode) ?? 0;
+        modeCounts.set(mode, count + 1);
+      }
+    }
+    const mostUsedModes = Array.from(modeCounts.entries()).map(([mode, count]) => ({ mode, count })).sort((a, b) => b.count - a.count);
+    const featuresUsed = new Set;
+    for (const event of events) {
+      if (event.type === "mode_change" && event.metadata?.mode) {
+        featuresUsed.add(event.metadata.mode);
+      }
+      if (event.type === "feature_usage" && event.metadata?.feature) {
+        featuresUsed.add(event.metadata.feature);
+      }
+      if (event.type === "canvas_interaction") {
+        const action = event.metadata?.action;
+        if (action === "add")
+          featuresUsed.add("canvas_add");
+        if (action === "delete")
+          featuresUsed.add("canvas_delete");
+      }
+      if (event.type === "spec_edit") {
+        const action = event.metadata?.action;
+        if (action === "save")
+          featuresUsed.add("spec_save");
+        if (action === "validate")
+          featuresUsed.add("spec_validate");
+      }
+    }
+    const unusedFeatures = ALL_FEATURES.filter((f) => !featuresUsed.has(f));
+    const errorCount = events.filter((e) => e.type === "error").length;
+    const recommendations = generateRecommendations(Array.from(featuresUsed), unusedFeatures, mostUsedModes, events.length);
+    return {
+      totalEvents: events.length,
+      sessionDuration,
+      mostUsedTemplates,
+      mostUsedModes,
+      featuresUsed: Array.from(featuresUsed),
+      unusedFeatures,
+      errorCount,
+      recommendations
+    };
+  }, [events]);
+  const clear = useCallback(() => {
+    setEvents([]);
+    setEventCount(0);
+    sessionStartRef.current = new Date;
+    localStorage.removeItem(BEHAVIOR_STORAGE_KEY);
+  }, []);
+  return useMemo(() => ({
+    trackEvent,
+    getSummary,
+    getEventsByType,
+    eventCount,
+    sessionStart: sessionStartRef.current,
+    clear
+  }), [trackEvent, getSummary, getEventsByType, eventCount, clear]);
+}
+function generateRecommendations(featuresUsed, unusedFeatures, mostUsedModes, totalEvents) {
+  const recommendations = [];
+  if (unusedFeatures.includes("evolution")) {
+    recommendations.push("Try the AI Evolution mode to get automated improvement suggestions");
+  }
+  if (unusedFeatures.includes("markdown")) {
+    recommendations.push("Use Markdown preview to see documentation for your specs");
+  }
+  if (unusedFeatures.includes("builder")) {
+    recommendations.push("Explore the Visual Builder to design your UI components");
+  }
+  if (!featuresUsed.includes("spec_validate") && featuresUsed.includes("specs")) {
+    recommendations.push("Don't forget to validate your specs before saving");
+  }
+  if (featuresUsed.includes("evolution") && !featuresUsed.includes("ai_suggestions")) {
+    recommendations.push("Generate AI suggestions to get actionable improvement recommendations");
+  }
+  if (totalEvents > 50) {
+    recommendations.push("Great engagement! Consider saving your work regularly");
+  }
+  if (mostUsedModes.length === 1) {
+    recommendations.push("Try different modes to explore all sandbox capabilities");
+  }
+  return recommendations;
+}
+export {
+  useBehaviorTracking
+};

package/dist/node/hooks/useEvolution.js

@@ -0,0 +1,260 @@
+// src/hooks/useEvolution.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+"use client";
+var EVOLUTION_STORAGE_KEY = "contractspec-evolution-data";
+function useEvolution(templateId) {
+  const [usageStats, setUsageStats] = useState([]);
+  const [anomalies, setAnomalies] = useState([]);
+  const [suggestions, setSuggestions] = useState([]);
+  const [hints, setHints] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const metricsRef = useRef([]);
+  const [operationCount, setOperationCount] = useState(0);
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(`${EVOLUTION_STORAGE_KEY}-${templateId}`);
+      if (stored) {
+        const data = JSON.parse(stored);
+        setSuggestions(data.suggestions.map((s) => ({
+          ...s,
+          createdAt: new Date(s.createdAt)
+        })));
+      }
+    } catch {}
+  }, [templateId]);
+  useEffect(() => {
+    try {
+      localStorage.setItem(`${EVOLUTION_STORAGE_KEY}-${templateId}`, JSON.stringify({ suggestions }));
+    } catch {}
+  }, [suggestions, templateId]);
+  const trackOperation = useCallback((operationName, durationMs, success, errorCode) => {
+    const sample = {
+      operation: {
+        name: operationName,
+        version: "1.0.0",
+        tenantId: "sandbox"
+      },
+      durationMs,
+      success,
+      timestamp: new Date,
+      errorCode
+    };
+    metricsRef.current.push(sample);
+    setOperationCount((prev) => prev + 1);
+  }, []);
+  const analyzeUsage = useCallback(() => {
+    const samples = metricsRef.current;
+    if (samples.length < 5)
+      return;
+    const groups = new Map;
+    for (const sample of samples) {
+      const key = `${sample.operation.name}.v${sample.operation.version}`;
+      const arr = groups.get(key) ?? [];
+      arr.push(sample);
+      groups.set(key, arr);
+    }
+    const stats = [];
+    const detectedAnomalies = [];
+    groups.forEach((opSamples) => {
+      if (opSamples.length < 3)
+        return;
+      const durations = opSamples.map((s) => s.durationMs).sort((a, b) => a - b);
+      const errors = opSamples.filter((s) => !s.success);
+      const totalCalls = opSamples.length;
+      const errorRate = errors.length / totalCalls;
+      const averageLatencyMs = durations.reduce((sum, value) => sum + value, 0) / totalCalls;
+      const timestamps = opSamples.map((s) => s.timestamp.getTime());
+      const firstSample = opSamples[0];
+      if (!firstSample)
+        return;
+      const stat = {
+        operation: firstSample.operation,
+        totalCalls,
+        successRate: 1 - errorRate,
+        errorRate,
+        averageLatencyMs,
+        p95LatencyMs: percentile(durations, 0.95),
+        p99LatencyMs: percentile(durations, 0.99),
+        maxLatencyMs: Math.max(...durations),
+        lastSeenAt: new Date(Math.max(...timestamps)),
+        windowStart: new Date(Math.min(...timestamps)),
+        windowEnd: new Date(Math.max(...timestamps)),
+        topErrors: errors.reduce((acc, s) => {
+          if (s.errorCode) {
+            acc[s.errorCode] = (acc[s.errorCode] ?? 0) + 1;
+          }
+          return acc;
+        }, {})
+      };
+      stats.push(stat);
+      if (errorRate > 0.1) {
+        detectedAnomalies.push({
+          operation: stat.operation,
+          severity: errorRate > 0.3 ? "high" : errorRate > 0.2 ? "medium" : "low",
+          metric: "error-rate",
+          description: `Error rate ${(errorRate * 100).toFixed(1)}% exceeds threshold`,
+          detectedAt: new Date,
+          threshold: 0.1,
+          observedValue: errorRate
+        });
+      }
+      if (stat.p99LatencyMs > 500) {
+        detectedAnomalies.push({
+          operation: stat.operation,
+          severity: stat.p99LatencyMs > 1000 ? "high" : stat.p99LatencyMs > 750 ? "medium" : "low",
+          metric: "latency",
+          description: `P99 latency ${stat.p99LatencyMs.toFixed(0)}ms exceeds threshold`,
+          detectedAt: new Date,
+          threshold: 500,
+          observedValue: stat.p99LatencyMs
+        });
+      }
+    });
+    setUsageStats(stats);
+    setAnomalies(detectedAnomalies);
+    const newHints = detectedAnomalies.map((anomaly) => ({
+      operation: anomaly.operation,
+      category: anomaly.metric === "latency" ? "performance" : "error-handling",
+      summary: anomaly.metric === "latency" ? "Latency regression detected" : "Error spike detected",
+      justification: anomaly.description,
+      recommendedActions: anomaly.metric === "latency" ? [
+        "Add caching layer",
+        "Optimize database queries",
+        "Consider pagination"
+      ] : [
+        "Add retry logic",
+        "Improve error handling",
+        "Add circuit breaker"
+      ]
+    }));
+    setHints(newHints);
+  }, []);
+  const generateSuggestions = useCallback(async () => {
+    if (anomalies.length === 0)
+      return;
+    setLoading(true);
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    const newSuggestions = anomalies.map((anomaly) => ({
+      id: `suggestion-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      intent: {
+        id: `intent-${anomaly.operation.name}`,
+        type: anomaly.metric === "latency" ? "latency-regression" : anomaly.metric === "error-rate" ? "error-spike" : "throughput-drop",
+        description: anomaly.description,
+        operation: anomaly.operation,
+        confidence: {
+          score: anomaly.severity === "high" ? 0.9 : anomaly.severity === "medium" ? 0.7 : 0.5,
+          sampleSize: usageStats.find((s) => s.operation.name === anomaly.operation.name)?.totalCalls ?? 0
+        }
+      },
+      target: anomaly.operation,
+      proposal: {
+        summary: generateSuggestionSummary(anomaly),
+        rationale: generateSuggestionRationale(anomaly),
+        changeType: anomaly.metric === "error-rate" ? "policy-update" : "revision",
+        recommendedActions: generateRecommendedActions(anomaly)
+      },
+      confidence: anomaly.severity === "high" ? 0.85 : anomaly.severity === "medium" ? 0.7 : 0.55,
+      createdAt: new Date,
+      createdBy: "ai-evolution-agent",
+      status: "pending",
+      priority: anomaly.severity
+    }));
+    setSuggestions((prev) => [...prev, ...newSuggestions]);
+    setLoading(false);
+  }, [anomalies, usageStats]);
+  const approveSuggestion = useCallback((id, _notes) => {
+    setSuggestions((prev) => prev.map((s) => s.id === id ? { ...s, status: "approved" } : s));
+  }, []);
+  const rejectSuggestion = useCallback((id, _notes) => {
+    setSuggestions((prev) => prev.map((s) => s.id === id ? { ...s, status: "rejected" } : s));
+  }, []);
+  const clear = useCallback(() => {
+    metricsRef.current = [];
+    setOperationCount(0);
+    setUsageStats([]);
+    setAnomalies([]);
+    setSuggestions([]);
+    setHints([]);
+    localStorage.removeItem(`${EVOLUTION_STORAGE_KEY}-${templateId}`);
+  }, [templateId]);
+  return useMemo(() => ({
+    usageStats,
+    anomalies,
+    suggestions,
+    hints,
+    loading,
+    trackOperation,
+    analyzeUsage,
+    generateSuggestions,
+    approveSuggestion,
+    rejectSuggestion,
+    clear,
+    operationCount
+  }), [
+    usageStats,
+    anomalies,
+    suggestions,
+    hints,
+    loading,
+    trackOperation,
+    analyzeUsage,
+    generateSuggestions,
+    approveSuggestion,
+    rejectSuggestion,
+    clear,
+    operationCount
+  ]);
+}
+function percentile(values, p) {
+  if (!values.length)
+    return 0;
+  if (values.length === 1)
+    return values[0] ?? 0;
+  const idx = Math.min(values.length - 1, Math.floor(p * values.length));
+  return values[idx] ?? 0;
+}
+function generateSuggestionSummary(anomaly) {
+  if (anomaly.metric === "latency") {
+    return `Add caching and pagination to ${anomaly.operation.name} to reduce latency`;
+  }
+  if (anomaly.metric === "error-rate") {
+    return `Add retry policy and circuit breaker to ${anomaly.operation.name}`;
+  }
+  return `Optimize ${anomaly.operation.name} for improved throughput`;
+}
+function generateSuggestionRationale(anomaly) {
+  if (anomaly.metric === "latency") {
+    return `The operation ${anomaly.operation.name} is experiencing P99 latency of ${anomaly.observedValue?.toFixed(0)}ms, which is above the recommended threshold of ${anomaly.threshold}ms. This can impact user experience and downstream operations.`;
+  }
+  if (anomaly.metric === "error-rate") {
+    return `The error rate for ${anomaly.operation.name} is ${((anomaly.observedValue ?? 0) * 100).toFixed(1)}%, indicating potential issues with input validation, external dependencies, or resource limits.`;
+  }
+  return `Throughput for ${anomaly.operation.name} has dropped significantly, suggesting potential bottlenecks or reduced demand that should be investigated.`;
+}
+function generateRecommendedActions(anomaly) {
+  if (anomaly.metric === "latency") {
+    return [
+      "Add response caching for frequently accessed data",
+      "Implement pagination for large result sets",
+      "Optimize database queries with proper indexing",
+      "Consider adding a GraphQL DataLoader for batching"
+    ];
+  }
+  if (anomaly.metric === "error-rate") {
+    return [
+      "Add input validation at the contract level",
+      "Implement retry policy with exponential backoff",
+      "Add circuit breaker for external dependencies",
+      "Enhance error logging for better debugging"
+    ];
+  }
+  return [
+    "Review resource allocation and scaling policies",
+    "Check for upstream routing or load balancer issues",
+    "Validate feature flag configurations",
+    "Monitor dependency health metrics"
+  ];
+}
+export {
+  useEvolution
+};

package/dist/node/hooks/useRegistryTemplates.js

@@ -0,0 +1,31 @@
+// src/hooks/useRegistryTemplates.ts
+import { useQuery } from "@tanstack/react-query";
+function useRegistryTemplates() {
+  return useQuery({
+    queryKey: ["registryTemplates"],
+    queryFn: async () => {
+      const registryUrl = process.env.NEXT_PUBLIC_CONTRACTSPEC_REGISTRY_URL ?? "";
+      if (!registryUrl)
+        return [];
+      const res = await fetch(`${registryUrl.replace(/\/$/, "")}/r/contractspec.json`, {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      });
+      if (!res.ok)
+        return [];
+      const json = await res.json();
+      const items = json.items ?? [];
+      return items.filter((i) => i.type === "contractspec:template").map((i) => ({
+        id: i.name,
+        name: i.title ?? i.name,
+        description: i.description,
+        tags: i.meta?.tags ?? [],
+        source: "registry",
+        registryUrl
+      }));
+    }
+  });
+}
+export {
+  useRegistryTemplates
+};