@contractspec/lib.example-shared-ui 0.0.0-canary-20260113170453

package/src/SpecEditorPanel.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+import { useCallback, useEffect } from 'react';
+import { Button, LoaderBlock } from '@contractspec/lib.design-system';
+import { Badge } from '@contractspec/lib.ui-kit-web/ui/badge';
+import type { TemplateId } from './lib/types';
+import { useSpecContent } from './hooks/useSpecContent';
+
+export interface SpecEditorProps {
+  projectId: string;
+  type?: 'CAPABILITY' | 'DATAVIEW' | 'WORKFLOW' | 'POLICY' | 'COMPONENT';
+  content: string;
+  onChange: (content: string) => void;
+  metadata?: Record<string, unknown>;
+  onSave?: () => void;
+  onValidate?: () => void;
+}
+
+export interface SpecEditorPanelProps {
+  templateId: TemplateId;
+  /** SpecEditor component passed as a prop (for dynamic import compatibility) */
+  SpecEditor: React.ComponentType<SpecEditorProps>;
+  /** Callback for logging actions */
+  onLog?: (message: string) => void;
+}
+
+/**
+ * Spec editor panel that wraps SpecEditor with persisted spec content.
+ * Uses useSpecContent hook to manage spec persistence and validation.
+ */
+export function SpecEditorPanel({
+  templateId,
+  SpecEditor,
+  onLog,
+}: SpecEditorPanelProps) {
+  const {
+    content,
+    loading,
+    isDirty,
+    validation,
+    setContent,
+    save,
+    validate,
+    reset,
+    lastSaved,
+  } = useSpecContent(templateId);
+
+  // Log when spec is loaded
+  useEffect(() => {
+    if (!loading && content) {
+      onLog?.(`Spec loaded for ${templateId}`);
+    }
+  }, [loading, content, templateId, onLog]);
+
+  const handleSave = useCallback(() => {
+    save();
+    onLog?.('Spec saved locally');
+  }, [save, onLog]);
+
+  const handleValidate = useCallback(() => {
+    const result = validate();
+    if (result.valid) {
+      onLog?.('Spec validation passed');
+    } else {
+      const errorCount = result.errors.filter(
+        (e) => e.severity === 'error'
+      ).length;
+      const warnCount = result.errors.filter(
+        (e) => e.severity === 'warning'
+      ).length;
+      onLog?.(`Spec validation: ${errorCount} errors, ${warnCount} warnings`);
+    }
+  }, [validate, onLog]);
+
+  const handleReset = useCallback(() => {
+    reset();
+    onLog?.('Spec reset to template defaults');
+  }, [reset, onLog]);
+
+  if (loading) {
+    return <LoaderBlock label="Loading spec..." />;
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Spec Toolbar */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Button variant="default" size="sm" onClick={handleSave}>
+            Save
+          </Button>
+          <Button variant="outline" size="sm" onClick={handleValidate}>
+            Validate
+          </Button>
+          {isDirty && (
+            <Badge
+              variant="secondary"
+              className="border-amber-500/30 bg-amber-500/20 text-amber-400"
+            >
+              Unsaved changes
+            </Badge>
+          )}
+          {validation && (
+            <Badge
+              variant={validation.valid ? 'default' : 'destructive'}
+              className={
+                validation.valid
+                  ? 'border-green-500/30 bg-green-500/20 text-green-400'
+                  : ''
+              }
+            >
+              {validation.valid
+                ? 'Valid'
+                : `${validation.errors.filter((e) => e.severity === 'error').length} errors`}
+            </Badge>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          {lastSaved && (
+            <span className="text-muted-foreground text-xs">
+              Last saved: {new Date(lastSaved).toLocaleTimeString()}
+            </span>
+          )}
+          <Button variant="ghost" size="sm" onPress={handleReset}>
+            Reset
+          </Button>
+        </div>
+      </div>
+
+      {/* Validation Errors */}
+      {validation && validation.errors.length > 0 && (
+        <div className="rounded-lg border border-amber-500/50 bg-amber-500/10 p-3">
+          <p className="mb-2 text-xs font-semibold text-amber-400 uppercase">
+            Validation Issues
+          </p>
+          <ul className="space-y-1">
+            {validation.errors.map((error, index) => (
+              <li
+                key={`${error.line}-${error.message}-${index}`}
+                className={`text-xs ${
+                  error.severity === 'error' ? 'text-red-400' : 'text-amber-400'
+                }`}
+              >
+                Line {error.line}: {error.message}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Editor */}
+      <div className="border-border bg-card rounded-2xl border p-4">
+        <SpecEditor
+          projectId="sandbox"
+          type="CAPABILITY"
+          content={content}
+          onChange={setContent}
+          metadata={{ template: templateId }}
+          onSave={handleSave}
+          onValidate={handleValidate}
+        />
+      </div>
+    </div>
+  );
+}

package/src/TemplateShell.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+
+import { LocalDataIndicator } from './LocalDataIndicator';
+import {
+  SaveToStudioButton,
+  type SaveToStudioButtonProps,
+} from './SaveToStudioButton';
+
+export interface TemplateShellProps {
+  title: string;
+  description?: string;
+  sidebar?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
+  showSaveAction?: boolean;
+  saveProps?: SaveToStudioButtonProps;
+}
+
+export const TemplateShell = ({
+  title,
+  description,
+  sidebar,
+  actions,
+  showSaveAction = true,
+  saveProps,
+  children,
+}: TemplateShellProps) => (
+  <div className="space-y-6">
+    <header className="border-border bg-card rounded-2xl border p-6 shadow-sm">
+      <div className="flex flex-wrap items-center justify-between gap-4">
+        <div>
+          <p className="text-muted-foreground text-sm font-semibold tracking-wide uppercase">
+            ContractSpec Templates
+          </p>
+          <h1 className="text-3xl font-bold">{title}</h1>
+          {description ? (
+            <p className="text-muted-foreground mt-2 max-w-2xl text-sm">
+              {description}
+            </p>
+          ) : null}
+        </div>
+        <div className="flex flex-col items-end gap-2">
+          <LocalDataIndicator />
+          {showSaveAction ? <SaveToStudioButton {...saveProps} /> : null}
+        </div>
+      </div>
+      {actions ? <div className="mt-4">{actions}</div> : null}
+    </header>
+
+    <div
+      className={
+        sidebar ? 'grid gap-6 lg:grid-cols-[minmax(0,1fr)_320px]' : 'w-full'
+      }
+    >
+      <main className="space-y-4 p-2">{children}</main>
+      {sidebar ? (
+        <aside className="border-border bg-card rounded-2xl border p-4">
+          {sidebar}
+        </aside>
+      ) : null}
+    </div>
+  </div>
+);

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export * from './useSpecContent';
+export * from './useEvolution';
+export * from './useBehaviorTracking';
+export * from './useWorkflowComposer';
+export * from './useRegistryTemplates';

package/src/hooks/useBehaviorTracking.ts

@@ -0,0 +1,327 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { TemplateId } from '../lib/types';
+
+/**
+ * Behavior event types
+ */
+export type BehaviorEventType =
+  | 'template_view'
+  | 'mode_change'
+  | 'spec_edit'
+  | 'canvas_interaction'
+  | 'presentation_view'
+  | 'feature_usage'
+  | 'error'
+  | 'navigation';
+
+/**
+ * Behavior event data
+ */
+export interface BehaviorEvent {
+  type: BehaviorEventType;
+  timestamp: Date;
+  templateId: TemplateId;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Behavior summary for a session
+ */
+export interface BehaviorSummary {
+  totalEvents: number;
+  sessionDuration: number;
+  mostUsedTemplates: { templateId: TemplateId; count: number }[];
+  mostUsedModes: { mode: string; count: number }[];
+  featuresUsed: string[];
+  unusedFeatures: string[];
+  errorCount: number;
+  recommendations: string[];
+}
+
+/**
+ * Hook return type
+ */
+export interface UseBehaviorTrackingReturn {
+  /** Track a behavior event */
+  trackEvent: (
+    type: BehaviorEventType,
+    metadata?: Record<string, unknown>
+  ) => void;
+  /** Get behavior summary */
+  getSummary: () => BehaviorSummary;
+  /** Get events for a specific type */
+  getEventsByType: (type: BehaviorEventType) => BehaviorEvent[];
+  /** Total event count */
+  eventCount: number;
+  /** Session start time */
+  sessionStart: Date;
+  /** Clear all tracked data */
+  clear: () => void;
+}
+
+/**
+ * Storage key for behavior data
+ */
+const BEHAVIOR_STORAGE_KEY = 'contractspec-behavior-data';
+
+/**
+ * All available features in the sandbox
+ */
+const ALL_FEATURES = [
+  'playground',
+  'specs',
+  'builder',
+  'markdown',
+  'evolution',
+  'canvas_add',
+  'canvas_delete',
+  'spec_save',
+  'spec_validate',
+  'ai_suggestions',
+];
+
+/**
+ * Hook for tracking user behavior in the sandbox.
+ * Provides insights into usage patterns and feature adoption.
+ */
+export function useBehaviorTracking(
+  templateId: TemplateId
+): UseBehaviorTrackingReturn {
+  const [events, setEvents] = useState<BehaviorEvent[]>([]);
+  const sessionStartRef = useRef<Date>(new Date());
+  const [eventCount, setEventCount] = useState(0);
+
+  // Load persisted events on mount
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(BEHAVIOR_STORAGE_KEY);
+      if (stored) {
+        const data = JSON.parse(stored) as {
+          events: (Omit<BehaviorEvent, 'timestamp'> & { timestamp: string })[];
+          sessionStart: string;
+        };
+        setEvents(
+          data.events.map((e) => ({
+            ...e,
+            timestamp: new Date(e.timestamp),
+          }))
+        );
+        sessionStartRef.current = new Date(data.sessionStart);
+      }
+    } catch {
+      // Ignore storage errors
+    }
+  }, []);
+
+  // Persist events when they change
+  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 {
+        // Ignore storage errors
+      }
+    }
+  }, [events]);
+
+  /**
+   * Track a behavior event
+   */
+  const trackEvent = useCallback(
+    (type: BehaviorEventType, metadata?: Record<string, unknown>) => {
+      const event: BehaviorEvent = {
+        type,
+        timestamp: new Date(),
+        templateId,
+        metadata,
+      };
+      setEvents((prev) => [...prev, event]);
+      setEventCount((prev) => prev + 1);
+    },
+    [templateId]
+  );
+
+  /**
+   * Get events by type
+   */
+  const getEventsByType = useCallback(
+    (type: BehaviorEventType): BehaviorEvent[] => {
+      return events.filter((e) => e.type === type);
+    },
+    [events]
+  );
+
+  /**
+   * Get behavior summary
+   */
+  const getSummary = useCallback((): BehaviorSummary => {
+    const now = new Date();
+    const sessionDuration = now.getTime() - sessionStartRef.current.getTime();
+
+    // Count templates
+    const templateCounts = new Map<TemplateId, number>();
+    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(([templateId, count]) => ({ templateId, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 3);
+
+    // Count modes from mode_change events
+    const modeCounts = new Map<string, number>();
+    for (const event of events) {
+      if (event.type === 'mode_change' && event.metadata?.mode) {
+        const mode = event.metadata.mode as string;
+        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);
+
+    // Track features used
+    const featuresUsed = new Set<string>();
+    for (const event of events) {
+      if (event.type === 'mode_change' && event.metadata?.mode) {
+        featuresUsed.add(event.metadata.mode as string);
+      }
+      if (event.type === 'feature_usage' && event.metadata?.feature) {
+        featuresUsed.add(event.metadata.feature as string);
+      }
+      if (event.type === 'canvas_interaction') {
+        const action = event.metadata?.action as string;
+        if (action === 'add') featuresUsed.add('canvas_add');
+        if (action === 'delete') featuresUsed.add('canvas_delete');
+      }
+      if (event.type === 'spec_edit') {
+        const action = event.metadata?.action as string;
+        if (action === 'save') featuresUsed.add('spec_save');
+        if (action === 'validate') featuresUsed.add('spec_validate');
+      }
+    }
+
+    // Find unused features
+    const unusedFeatures = ALL_FEATURES.filter((f) => !featuresUsed.has(f));
+
+    // Count errors
+    const errorCount = events.filter((e) => e.type === 'error').length;
+
+    // Generate recommendations
+    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]);
+
+  /**
+   * Clear all tracking data
+   */
+  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]
+  );
+}
+
+/**
+ * Generate recommendations based on behavior
+ */
+function generateRecommendations(
+  featuresUsed: string[],
+  unusedFeatures: string[],
+  mostUsedModes: { mode: string; count: number }[],
+  totalEvents: number
+): string[] {
+  const recommendations: string[] = [];
+
+  // Recommend unused features
+  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'
+    );
+  }
+
+  // Time-based recommendations
+  if (totalEvents > 50) {
+    recommendations.push(
+      'Great engagement! Consider saving your work regularly'
+    );
+  }
+
+  // Mode variety recommendations
+  if (mostUsedModes.length === 1) {
+    recommendations.push(
+      'Try different modes to explore all sandbox capabilities'
+    );
+  }
+
+  return recommendations;
+}