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

package/src/OverlayContextProvider.tsx

@@ -0,0 +1,341 @@
+'use client';
+
+import * as React from 'react';
+import { useContext, useMemo } from 'react';
+import type { TemplateId } from './lib/types';
+
+/**
+ * Overlay modification operation types (for OverlayContextProvider)
+ */
+export type OverlayModificationOp =
+  | { op: 'hide' }
+  | { op: 'relabel'; label: string }
+  | { op: 'reorder'; position: number }
+  | { op: 'restyle'; className?: string; variant?: string }
+  | { op: 'set-default'; value: unknown };
+
+/**
+ * Overlay spec for a field or component
+ */
+export interface OverlaySpec {
+  id: string;
+  target: string; // path to the field/component
+  modifications: OverlayModificationOp[];
+  conditions?: {
+    role?: string[];
+    device?: 'mobile' | 'desktop' | 'any';
+    featureFlags?: string[];
+  };
+}
+
+/**
+ * Context value for overlay engine
+ */
+export interface OverlayContextValue {
+  /** Current overlays */
+  overlays: OverlaySpec[];
+  /** Apply overlays to a component */
+  applyOverlay: <T extends Record<string, unknown>>(
+    path: string,
+    target: T
+  ) => T;
+  /** Check if a field should be hidden */
+  isHidden: (path: string) => boolean;
+  /** Get relabeled text */
+  getLabel: (path: string, defaultLabel: string) => string;
+  /** Get position for reordering */
+  getPosition: (path: string, defaultPosition: number) => number;
+  /** Get style modifications */
+  getStyle: (path: string) => { className?: string; variant?: string };
+  /** Get default value */
+  getDefault: <T>(path: string, defaultValue: T) => T;
+  /** Current user role */
+  role: string;
+  /** Current device type */
+  device: 'mobile' | 'desktop';
+}
+
+const OverlayContext = React.createContext<OverlayContextValue | null>(null);
+
+export interface OverlayContextProviderProps extends React.PropsWithChildren {
+  templateId: TemplateId;
+  role?: string;
+  device?: 'mobile' | 'desktop';
+}
+
+/**
+ * Provider for overlay engine context.
+ * Loads template-specific overlays and provides helper functions.
+ */
+export function OverlayContextProvider({
+  templateId,
+  role = 'user',
+  device = 'desktop',
+  children,
+}: OverlayContextProviderProps) {
+  // Load template-specific overlays
+  const overlays = useMemo(
+    () => getTemplateOverlays(templateId, role),
+    [templateId, role]
+  );
+
+  // Filter overlays based on current context
+  const activeOverlays = useMemo(() => {
+    return overlays.filter((overlay) => {
+      const conditions = overlay.conditions;
+      if (!conditions) return true;
+
+      if (conditions.role && !conditions.role.includes(role)) {
+        return false;
+      }
+
+      if (
+        conditions.device &&
+        conditions.device !== 'any' &&
+        conditions.device !== device
+      ) {
+        return false;
+      }
+
+      return true;
+    });
+  }, [overlays, role, device]);
+
+  // Create overlay map for quick lookups
+  const overlayMap = useMemo(() => {
+    const map = new Map<string, OverlaySpec>();
+    for (const overlay of activeOverlays) {
+      map.set(overlay.target, overlay);
+    }
+    return map;
+  }, [activeOverlays]);
+
+  // Apply overlay to a target object
+  const applyOverlay = useMemo(
+    () =>
+      <T extends Record<string, unknown>>(path: string, target: T): T => {
+        const overlay = overlayMap.get(path);
+        if (!overlay) return target;
+
+        let result = { ...target };
+        for (const mod of overlay.modifications) {
+          switch (mod.op) {
+            case 'hide':
+              result = { ...result, hidden: true };
+              break;
+            case 'relabel':
+              result = { ...result, label: mod.label };
+              break;
+            case 'reorder':
+              result = { ...result, position: mod.position };
+              break;
+            case 'restyle':
+              result = {
+                ...result,
+                className: mod.className,
+                variant: mod.variant,
+              };
+              break;
+            case 'set-default':
+              result = { ...result, defaultValue: mod.value };
+              break;
+          }
+        }
+        return result;
+      },
+    [overlayMap]
+  );
+
+  // Check if field is hidden
+  const isHidden = useMemo(
+    () =>
+      (path: string): boolean => {
+        const overlay = overlayMap.get(path);
+        return overlay?.modifications.some((m) => m.op === 'hide') ?? false;
+      },
+    [overlayMap]
+  );
+
+  // Get relabeled text
+  const getLabel = useMemo(
+    () =>
+      (path: string, defaultLabel: string): string => {
+        const overlay = overlayMap.get(path);
+        const relabel = overlay?.modifications.find((m) => m.op === 'relabel');
+        return relabel && relabel.op === 'relabel'
+          ? relabel.label
+          : defaultLabel;
+      },
+    [overlayMap]
+  );
+
+  // Get position for reordering
+  const getPosition = useMemo(
+    () =>
+      (path: string, defaultPosition: number): number => {
+        const overlay = overlayMap.get(path);
+        const reorder = overlay?.modifications.find((m) => m.op === 'reorder');
+        return reorder && reorder.op === 'reorder'
+          ? reorder.position
+          : defaultPosition;
+      },
+    [overlayMap]
+  );
+
+  // Get style modifications
+  const getStyle = useMemo(
+    () =>
+      (path: string): { className?: string; variant?: string } => {
+        const overlay = overlayMap.get(path);
+        const restyle = overlay?.modifications.find((m) => m.op === 'restyle');
+        if (restyle && restyle.op === 'restyle') {
+          return {
+            className: restyle.className,
+            variant: restyle.variant,
+          };
+        }
+        return {};
+      },
+    [overlayMap]
+  );
+
+  // Get default value
+  const getDefault = useMemo(
+    () =>
+      <T,>(path: string, defaultValue: T): T => {
+        const overlay = overlayMap.get(path);
+        const setDefault = overlay?.modifications.find(
+          (m) => m.op === 'set-default'
+        );
+        return setDefault && setDefault.op === 'set-default'
+          ? (setDefault.value as T)
+          : defaultValue;
+      },
+    [overlayMap]
+  );
+
+  const value = useMemo<OverlayContextValue>(
+    () => ({
+      overlays: activeOverlays,
+      applyOverlay,
+      isHidden,
+      getLabel,
+      getPosition,
+      getStyle,
+      getDefault,
+      role,
+      device,
+    }),
+    [
+      activeOverlays,
+      applyOverlay,
+      isHidden,
+      getLabel,
+      getPosition,
+      getStyle,
+      getDefault,
+      role,
+      device,
+    ]
+  );
+
+  return (
+    <OverlayContext.Provider value={value}>{children}</OverlayContext.Provider>
+  );
+}
+
+/**
+ * Hook to access overlay context
+ */
+export function useOverlayContext(): OverlayContextValue {
+  const context = useContext(OverlayContext);
+  if (!context) {
+    throw new Error(
+      'useOverlayContext must be used within an OverlayContextProvider'
+    );
+  }
+  return context;
+}
+
+/**
+ * Hook to check if within overlay context
+ */
+export function useIsInOverlayContext(): boolean {
+  return useContext(OverlayContext) !== null;
+}
+
+/**
+ * Get template-specific overlays
+ */
+function getTemplateOverlays(
+  templateId: TemplateId,
+  _role: string
+): OverlaySpec[] {
+  // Demo overlays for each template
+  const templateOverlays: Record<string, OverlaySpec[]> = {
+    'crm-pipeline': [
+      {
+        id: 'crm-hide-internal-fields',
+        target: 'deal.internalNotes',
+        modifications: [{ op: 'hide' }],
+        conditions: { role: ['viewer', 'user'] },
+      },
+      {
+        id: 'crm-relabel-value',
+        target: 'deal.value',
+        modifications: [{ op: 'relabel', label: 'Deal Amount' }],
+      },
+    ],
+    'saas-boilerplate': [
+      {
+        id: 'saas-hide-billing',
+        target: 'settings.billing',
+        modifications: [{ op: 'hide' }],
+        conditions: { role: ['viewer'] },
+      },
+      {
+        id: 'saas-restyle-plan',
+        target: 'settings.plan',
+        modifications: [{ op: 'restyle', variant: 'premium' }],
+        conditions: { role: ['admin'] },
+      },
+    ],
+    'agent-console': [
+      {
+        id: 'agent-hide-cost',
+        target: 'run.cost',
+        modifications: [{ op: 'hide' }],
+        conditions: { role: ['viewer'] },
+      },
+      {
+        id: 'agent-relabel-tokens',
+        target: 'run.tokens',
+        modifications: [{ op: 'relabel', label: 'Token Usage' }],
+      },
+    ],
+    'todos-app': [
+      {
+        id: 'todos-hide-assignee',
+        target: 'task.assignee',
+        modifications: [{ op: 'hide' }],
+        conditions: { device: 'mobile' },
+      },
+    ],
+    'messaging-app': [
+      {
+        id: 'messaging-reorder-timestamp',
+        target: 'message.timestamp',
+        modifications: [{ op: 'reorder', position: 0 }],
+      },
+    ],
+    'recipe-app-i18n': [
+      {
+        id: 'recipe-relabel-servings',
+        target: 'recipe.servings',
+        modifications: [{ op: 'relabel', label: 'Portions' }],
+      },
+    ],
+  };
+
+  return templateOverlays[templateId] ?? [];
+}

package/src/PersonalizationInsights.tsx

@@ -0,0 +1,293 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+import { Button } from '@contractspec/lib.design-system';
+import { Card } from '@contractspec/lib.ui-kit-web/ui/card';
+import { Badge } from '@contractspec/lib.ui-kit-web/ui/badge';
+import type { TemplateId } from './lib/types';
+import {
+  type BehaviorSummary,
+  useBehaviorTracking,
+} from './hooks/useBehaviorTracking';
+
+export interface PersonalizationInsightsProps {
+  templateId: TemplateId;
+  /** Whether to show in collapsed mode */
+  collapsed?: boolean;
+  /** Toggle collapsed state */
+  onToggle?: () => void;
+}
+
+/**
+ * Component showing personalization insights based on user behavior.
+ * Displays usage patterns, recommendations, and feature adoption.
+ */
+export function PersonalizationInsights({
+  templateId,
+  collapsed = false,
+  onToggle,
+}: PersonalizationInsightsProps) {
+  const { getSummary, eventCount, clear, sessionStart } =
+    useBehaviorTracking(templateId);
+
+  const [showDetails, setShowDetails] = useState(false);
+
+  const summary = useMemo(() => getSummary(), [getSummary]);
+
+  const formatDuration = useCallback((ms: number) => {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m`;
+    }
+    if (minutes > 0) {
+      return `${minutes}m ${seconds % 60}s`;
+    }
+    return `${seconds}s`;
+  }, []);
+
+  const handleClear = useCallback(() => {
+    clear();
+  }, [clear]);
+
+  // Collapsed view
+  if (collapsed) {
+    return (
+      <button
+        onClick={onToggle}
+        className="flex items-center gap-2 rounded-lg border border-blue-500/30 bg-blue-500/10 px-3 py-2 text-sm transition hover:bg-blue-500/20"
+        type="button"
+      >
+        <span>📊</span>
+        <span>Insights</span>
+        <Badge variant="secondary">{eventCount}</Badge>
+      </button>
+    );
+  }
+
+  return (
+    <Card className="overflow-hidden">
+      {/* Header */}
+      <div className="flex items-center justify-between border-b border-blue-500/20 bg-blue-500/5 px-4 py-3">
+        <div className="flex items-center gap-2">
+          <span>📊</span>
+          <span className="font-semibold">Personalization Insights</span>
+        </div>
+        <div className="flex items-center gap-2">
+          <Button
+            variant="ghost"
+            size="sm"
+            onPress={() => setShowDetails(!showDetails)}
+          >
+            {showDetails ? 'Hide Details' : 'Show Details'}
+          </Button>
+          {onToggle && (
+            <button
+              onClick={onToggle}
+              className="text-muted-foreground hover:text-foreground p-1"
+              type="button"
+              title="Collapse"
+            >
+              ✕
+            </button>
+          )}
+        </div>
+      </div>
+
+      <div className="p-4">
+        {/* Quick Stats */}
+        <div className="mb-4 grid grid-cols-2 gap-3 md:grid-cols-4">
+          <StatCard
+            label="Session Time"
+            value={formatDuration(summary.sessionDuration)}
+            icon="⏱️"
+          />
+          <StatCard
+            label="Events Tracked"
+            value={summary.totalEvents.toString()}
+            icon="📈"
+          />
+          <StatCard
+            label="Features Used"
+            value={`${summary.featuresUsed.length}/${summary.featuresUsed.length + summary.unusedFeatures.length}`}
+            icon="✨"
+          />
+          <StatCard
+            label="Errors"
+            value={summary.errorCount.toString()}
+            icon="⚠️"
+            variant={summary.errorCount > 0 ? 'warning' : 'success'}
+          />
+        </div>
+
+        {/* Recommendations */}
+        {summary.recommendations.length > 0 && (
+          <div className="mb-4">
+            <h4 className="mb-2 text-xs font-semibold text-blue-400 uppercase">
+              Recommendations
+            </h4>
+            <ul className="space-y-1">
+              {summary.recommendations.map((rec, index) => (
+                <li key={index} className="flex items-start gap-2 text-sm">
+                  <span className="text-blue-400">💡</span>
+                  <span>{rec}</span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {/* Unused Features */}
+        {summary.unusedFeatures.length > 0 && (
+          <div className="mb-4">
+            <h4 className="mb-2 text-xs font-semibold text-blue-400 uppercase">
+              Try These Features
+            </h4>
+            <div className="flex flex-wrap gap-2">
+              {summary.unusedFeatures.slice(0, 5).map((feature) => (
+                <Badge key={feature} variant="secondary">
+                  {formatFeatureName(feature)}
+                </Badge>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Detailed View */}
+        {showDetails && (
+          <DetailedInsights summary={summary} sessionStart={sessionStart} />
+        )}
+
+        {/* Footer Actions */}
+        <div className="mt-4 flex justify-end border-t border-blue-500/10 pt-4">
+          <Button variant="ghost" size="sm" onPress={handleClear}>
+            Clear Data
+          </Button>
+        </div>
+      </div>
+    </Card>
+  );
+}
+
+/**
+ * Stat card component
+ */
+function StatCard({
+  label,
+  value,
+  icon,
+  variant = 'default',
+}: {
+  label: string;
+  value: string;
+  icon: string;
+  variant?: 'default' | 'warning' | 'success';
+}) {
+  const bgColors = {
+    default: 'bg-blue-500/5 border-blue-500/20',
+    warning: 'bg-amber-500/5 border-amber-500/20',
+    success: 'bg-green-500/5 border-green-500/20',
+  };
+
+  return (
+    <div className={`rounded-lg border p-3 text-center ${bgColors[variant]}`}>
+      <div className="mb-1 text-lg">{icon}</div>
+      <div className="text-lg font-bold">{value}</div>
+      <div className="text-muted-foreground text-xs">{label}</div>
+    </div>
+  );
+}
+
+/**
+ * Detailed insights section
+ */
+function DetailedInsights({
+  summary,
+  sessionStart,
+}: {
+  summary: BehaviorSummary;
+  sessionStart: Date;
+}) {
+  return (
+    <div className="mt-4 space-y-4 border-t border-blue-500/10 pt-4">
+      {/* Most Used Templates */}
+      {summary.mostUsedTemplates.length > 0 && (
+        <div>
+          <h4 className="mb-2 text-xs font-semibold text-blue-400 uppercase">
+            Most Used Templates
+          </h4>
+          <div className="space-y-1">
+            {summary.mostUsedTemplates.map(({ templateId, count }) => (
+              <div
+                key={templateId}
+                className="flex items-center justify-between text-sm"
+              >
+                <span>{formatTemplateId(templateId)}</span>
+                <span className="text-muted-foreground">{count} events</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Most Used Modes */}
+      {summary.mostUsedModes.length > 0 && (
+        <div>
+          <h4 className="mb-2 text-xs font-semibold text-blue-400 uppercase">
+            Mode Usage
+          </h4>
+          <div className="space-y-1">
+            {summary.mostUsedModes.map(({ mode, count }) => (
+              <div
+                key={mode}
+                className="flex items-center justify-between text-sm"
+              >
+                <span>{formatFeatureName(mode)}</span>
+                <span className="text-muted-foreground">{count} switches</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Features Used */}
+      <div>
+        <h4 className="mb-2 text-xs font-semibold text-blue-400 uppercase">
+          Features Used
+        </h4>
+        <div className="flex flex-wrap gap-2">
+          {summary.featuresUsed.map((feature) => (
+            <Badge
+              key={feature}
+              variant="default"
+              className="border-green-500/30 bg-green-500/20 text-green-400"
+            >
+              ✓ {formatFeatureName(feature)}
+            </Badge>
+          ))}
+        </div>
+      </div>
+
+      {/* Session Info */}
+      <div className="text-muted-foreground text-xs">
+        Session started: {sessionStart.toLocaleString()}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Format feature name for display
+ */
+function formatFeatureName(feature: string): string {
+  return feature.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Format template ID for display
+ */
+function formatTemplateId(id: string): string {
+  return id.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}

package/src/SaveToStudioButton.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { useState } from 'react';
+import { Sparkles } from 'lucide-react';
+import { useTemplateRuntime } from './lib/runtime-context';
+
+export interface SaveToStudioButtonProps {
+  organizationId?: string;
+  projectName?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export function SaveToStudioButton({
+  organizationId = 'demo-org',
+  projectName,
+  endpoint,
+  token,
+}: SaveToStudioButtonProps) {
+  const { installer, templateId, template } = useTemplateRuntime();
+  const [status, setStatus] = useState<'idle' | 'saving' | 'saved' | 'error'>(
+    'idle'
+  );
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSave = async () => {
+    setStatus('saving');
+    setError(null);
+    try {
+      await installer.saveToStudio({
+        templateId,
+        projectName: projectName ?? `${template.name} demo`,
+        organizationId,
+        endpoint,
+        token,
+      });
+      setStatus('saved');
+      setTimeout(() => setStatus('idle'), 3000);
+    } catch (err) {
+      setStatus('error');
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    }
+  };
+
+  return (
+    <div className="flex flex-col items-end gap-1">
+      <button
+        type="button"
+        className="btn-primary inline-flex items-center gap-2 text-sm"
+        onClick={handleSave}
+        disabled={status === 'saving'}
+      >
+        <Sparkles className="h-4 w-4" />
+        {status === 'saving' ? 'Publishing…' : 'Save to Studio'}
+      </button>
+      {status === 'error' && error ? (
+        <p className="text-destructive text-xs">{error}</p>
+      ) : null}
+      {status === 'saved' ? (
+        <p className="text-xs text-emerald-400">Template sent to Studio.</p>
+      ) : null}
+    </div>
+  );
+}