@contractspec/example.analytics-dashboard 3.7.6 → 3.9.2

package/dist/ui/hooks/useAnalyticsData.js

@@ -1,7 +1,598 @@
 // @bun
+// src/visualizations/specs.breakdown.ts
+import { defineVisualization } from "@contractspec/lib.contracts-spec/visualizations";
+var QUERY_REF = { key: "analytics.query.execute", version: "1.0.0" };
+var META = {
+  version: "1.0.0",
+  domain: "analytics",
+  stability: "experimental",
+  owners: ["@example.analytics-dashboard"],
+  tags: ["analytics", "dashboard", "visualization"]
+};
+var ChannelMixVisualization = defineVisualization({
+  meta: {
+    ...META,
+    key: "analytics.visualization.channel-mix",
+    title: "Channel Mix",
+    description: "Session distribution across acquisition channels.",
+    goal: "Explain which channels currently drive the largest share of traffic.",
+    context: "Marketing attribution dashboard."
+  },
+  source: { primary: QUERY_REF, resultPath: "data" },
+  visualization: {
+    kind: "pie",
+    nameDimension: "channel",
+    valueMeasure: "sessions",
+    dimensions: [
+      {
+        key: "channel",
+        label: "Channel",
+        dataPath: "channel",
+        type: "category"
+      }
+    ],
+    measures: [{ key: "sessions", label: "Sessions", dataPath: "sessions" }],
+    table: { caption: "Sessions by acquisition channel." }
+  }
+});
+var EngagementHeatmapVisualization = defineVisualization({
+  meta: {
+    ...META,
+    key: "analytics.visualization.engagement-heatmap",
+    title: "Engagement Heatmap",
+    description: "Average engagement score by weekday and time band.",
+    goal: "Reveal the highest-engagement time windows for product activity.",
+    context: "Usage analytics dashboard."
+  },
+  source: { primary: QUERY_REF, resultPath: "data" },
+  visualization: {
+    kind: "heatmap",
+    xDimension: "timeBand",
+    yDimension: "weekday",
+    valueMeasure: "engagementScore",
+    dimensions: [
+      {
+        key: "timeBand",
+        label: "Time Band",
+        dataPath: "timeBand",
+        type: "category"
+      },
+      {
+        key: "weekday",
+        label: "Weekday",
+        dataPath: "weekday",
+        type: "category"
+      }
+    ],
+    measures: [
+      {
+        key: "engagementScore",
+        label: "Engagement",
+        dataPath: "engagementScore"
+      }
+    ],
+    table: { caption: "Engagement score by weekday and time band." }
+  }
+});
+var ConversionFunnelVisualization = defineVisualization({
+  meta: {
+    ...META,
+    key: "analytics.visualization.conversion-funnel",
+    title: "Conversion Funnel",
+    description: "Progression through the main acquisition funnel.",
+    goal: "Show where the product is losing the largest share of prospects.",
+    context: "Growth dashboard."
+  },
+  source: { primary: QUERY_REF, resultPath: "data" },
+  visualization: {
+    kind: "funnel",
+    nameDimension: "stage",
+    valueMeasure: "users",
+    sort: "descending",
+    dimensions: [
+      { key: "stage", label: "Stage", dataPath: "stage", type: "category" }
+    ],
+    measures: [{ key: "users", label: "Users", dataPath: "users" }],
+    table: { caption: "Users per conversion stage." }
+  }
+});
+var AccountCoverageGeoVisualization = defineVisualization({
+  meta: {
+    ...META,
+    key: "analytics.visualization.account-coverage-geo",
+    title: "Account Coverage",
+    description: "High-value accounts plotted on a slippy-map surface.",
+    goal: "Locate where active commercial concentration is strongest.",
+    context: "Territory coverage dashboard."
+  },
+  source: { primary: QUERY_REF, resultPath: "data" },
+  visualization: {
+    kind: "geo",
+    mode: "slippy-map",
+    variant: "scatter",
+    nameDimension: "city",
+    latitudeDimension: "latitude",
+    longitudeDimension: "longitude",
+    valueMeasure: "accounts",
+    dimensions: [
+      { key: "city", label: "City", dataPath: "city", type: "category" },
+      {
+        key: "latitude",
+        label: "Latitude",
+        dataPath: "latitude",
+        type: "latitude"
+      },
+      {
+        key: "longitude",
+        label: "Longitude",
+        dataPath: "longitude",
+        type: "longitude"
+      }
+    ],
+    measures: [{ key: "accounts", label: "Accounts", dataPath: "accounts" }],
+    table: { caption: "Account concentration by city." }
+  }
+});
+
+// src/visualizations/specs.performance.ts
+import { defineVisualization as defineVisualization2 } from "@contractspec/lib.contracts-spec/visualizations";
+var QUERY_REF2 = { key: "analytics.query.execute", version: "1.0.0" };
+var META2 = {
+  version: "1.0.0",
+  domain: "analytics",
+  stability: "experimental",
+  owners: ["@example.analytics-dashboard"],
+  tags: ["analytics", "dashboard", "visualization"]
+};
+var RevenueMetricVisualization = defineVisualization2({
+  meta: {
+    ...META2,
+    key: "analytics.visualization.revenue-metric",
+    title: "Revenue Snapshot",
+    description: "Current recurring revenue with prior-period comparison.",
+    goal: "Highlight the headline commercial metric for the dashboard.",
+    context: "Executive revenue overview."
+  },
+  source: { primary: QUERY_REF2, resultPath: "data" },
+  visualization: {
+    kind: "metric",
+    measure: "totalRevenue",
+    comparisonMeasure: "priorRevenue",
+    dimensions: [
+      { key: "period", label: "Period", dataPath: "period", type: "time" }
+    ],
+    measures: [
+      {
+        key: "totalRevenue",
+        label: "Revenue",
+        dataPath: "totalRevenue",
+        format: "currency"
+      },
+      {
+        key: "priorRevenue",
+        label: "Prior Revenue",
+        dataPath: "priorRevenue",
+        format: "currency"
+      }
+    ],
+    sparkline: { dimension: "period", measure: "totalRevenue" },
+    table: { caption: "Revenue trend and prior period values." }
+  }
+});
+var RevenueTrendVisualization = defineVisualization2({
+  meta: {
+    ...META2,
+    key: "analytics.visualization.revenue-trend",
+    title: "Revenue Trend",
+    description: "Monthly revenue progression for the current quarter.",
+    goal: "Track whether revenue growth is accelerating or stalling.",
+    context: "Quarterly commercial dashboard."
+  },
+  source: { primary: QUERY_REF2, resultPath: "data" },
+  visualization: {
+    kind: "cartesian",
+    variant: "line",
+    xDimension: "date",
+    yMeasures: ["revenue"],
+    dimensions: [
+      { key: "date", label: "Month", dataPath: "date", type: "time" }
+    ],
+    measures: [
+      {
+        key: "revenue",
+        label: "Revenue",
+        dataPath: "revenue",
+        format: "currency",
+        color: "#0f766e"
+      }
+    ],
+    thresholds: [
+      { key: "target", value: 140000, label: "Target", color: "#dc2626" }
+    ],
+    table: { caption: "Monthly revenue values." }
+  }
+});
+var RegionalRevenueVisualization = defineVisualization2({
+  meta: {
+    ...META2,
+    key: "analytics.visualization.regional-revenue",
+    title: "Regional Revenue",
+    description: "Revenue split by sales territory.",
+    goal: "Compare the strongest and weakest performing territories.",
+    context: "Territory planning and commercial comparison."
+  },
+  source: { primary: QUERY_REF2, resultPath: "data" },
+  visualization: {
+    kind: "cartesian",
+    variant: "bar",
+    xDimension: "region",
+    yMeasures: ["revenue"],
+    dimensions: [
+      { key: "region", label: "Region", dataPath: "region", type: "category" }
+    ],
+    measures: [
+      {
+        key: "revenue",
+        label: "Revenue",
+        dataPath: "revenue",
+        format: "currency",
+        color: "#1d4ed8"
+      }
+    ],
+    table: { caption: "Revenue by region." }
+  }
+});
+var RetentionAreaVisualization = defineVisualization2({
+  meta: {
+    ...META2,
+    key: "analytics.visualization.retention-area",
+    title: "Retention Curve",
+    description: "Weekly retention progression across the active cohort.",
+    goal: "Show whether user retention remains above the desired floor.",
+    context: "Product health dashboard."
+  },
+  source: { primary: QUERY_REF2, resultPath: "data" },
+  visualization: {
+    kind: "cartesian",
+    variant: "area",
+    xDimension: "week",
+    yMeasures: ["retentionRate"],
+    dimensions: [
+      { key: "week", label: "Week", dataPath: "week", type: "category" }
+    ],
+    measures: [
+      {
+        key: "retentionRate",
+        label: "Retention",
+        dataPath: "retentionRate",
+        format: "percentage",
+        color: "#16a34a"
+      }
+    ],
+    thresholds: [
+      { key: "floor", value: 0.5, label: "Floor", color: "#f59e0b" }
+    ],
+    table: { caption: "Weekly retention rate." }
+  }
+});
+var PipelineScatterVisualization = defineVisualization2({
+  meta: {
+    ...META2,
+    key: "analytics.visualization.pipeline-scatter",
+    title: "Pipeline Velocity",
+    description: "Deal-cycle length against win rate for active accounts.",
+    goal: "Spot outliers where the sales cycle is long but conversion remains weak.",
+    context: "Commercial operations dashboard."
+  },
+  source: { primary: QUERY_REF2, resultPath: "data" },
+  visualization: {
+    kind: "cartesian",
+    variant: "scatter",
+    xDimension: "cycleDays",
+    yMeasures: ["winRate"],
+    dimensions: [
+      {
+        key: "cycleDays",
+        label: "Cycle Days",
+        dataPath: "cycleDays",
+        type: "number"
+      }
+    ],
+    measures: [
+      {
+        key: "winRate",
+        label: "Win Rate",
+        dataPath: "winRate",
+        format: "percentage",
+        color: "#7c3aed"
+      },
+      {
+        key: "arr",
+        label: "ARR",
+        dataPath: "arr",
+        format: "currency"
+      }
+    ],
+    series: [
+      {
+        key: "pipeline",
+        label: "Accounts",
+        measure: "winRate",
+        type: "scatter",
+        color: "#7c3aed"
+      }
+    ],
+    table: { caption: "Sales cycle and win rate per account." }
+  }
+});
+
+// src/visualizations/catalog.ts
+import { VisualizationRegistry } from "@contractspec/lib.contracts-spec/visualizations";
+var AnalyticsVisualizationSpecs = [
+  RevenueMetricVisualization,
+  RevenueTrendVisualization,
+  RegionalRevenueVisualization,
+  RetentionAreaVisualization,
+  PipelineScatterVisualization,
+  ChannelMixVisualization,
+  EngagementHeatmapVisualization,
+  ConversionFunnelVisualization,
+  AccountCoverageGeoVisualization
+];
+var AnalyticsVisualizationRegistry = new VisualizationRegistry([
+  ...AnalyticsVisualizationSpecs
+]);
+var AnalyticsVisualizationRefs = AnalyticsVisualizationSpecs.map((spec) => refOf(spec));
+var AnalyticsVisualizationSpecMap = new Map(AnalyticsVisualizationSpecs.map((spec) => [
+  visualizationRefKey(spec.meta),
+  spec
+]));
+var AnalyticsVisualizationSampleData = {
+  [visualizationRefKey(RevenueMetricVisualization.meta)]: {
+    data: [
+      { period: "2025-11-01", totalRevenue: 112000, priorRevenue: 103000 },
+      { period: "2025-12-01", totalRevenue: 119000, priorRevenue: 110000 },
+      { period: "2026-01-01", totalRevenue: 126500, priorRevenue: 116000 },
+      { period: "2026-02-01", totalRevenue: 133000, priorRevenue: 124000 },
+      { period: "2026-03-01", totalRevenue: 145500, priorRevenue: 133000 }
+    ]
+  },
+  [visualizationRefKey(RevenueTrendVisualization.meta)]: {
+    data: [
+      { date: "2025-11-01", revenue: 112000 },
+      { date: "2025-12-01", revenue: 119000 },
+      { date: "2026-01-01", revenue: 126500 },
+      { date: "2026-02-01", revenue: 133000 },
+      { date: "2026-03-01", revenue: 145500 }
+    ]
+  },
+  [visualizationRefKey(RegionalRevenueVisualization.meta)]: {
+    data: [
+      { region: "North America", revenue: 210000 },
+      { region: "EMEA", revenue: 174000 },
+      { region: "APAC", revenue: 132000 },
+      { region: "LATAM", revenue: 88000 }
+    ]
+  },
+  [visualizationRefKey(RetentionAreaVisualization.meta)]: {
+    data: [
+      { week: "Week 1", retentionRate: 0.71 },
+      { week: "Week 2", retentionRate: 0.66 },
+      { week: "Week 3", retentionRate: 0.62 },
+      { week: "Week 4", retentionRate: 0.58 },
+      { week: "Week 5", retentionRate: 0.55 },
+      { week: "Week 6", retentionRate: 0.53 }
+    ]
+  },
+  [visualizationRefKey(PipelineScatterVisualization.meta)]: {
+    data: [
+      { cycleDays: 18, winRate: 0.31, arr: 82000 },
+      { cycleDays: 26, winRate: 0.44, arr: 65000 },
+      { cycleDays: 33, winRate: 0.27, arr: 91000 },
+      { cycleDays: 14, winRate: 0.56, arr: 47000 },
+      { cycleDays: 21, winRate: 0.48, arr: 59000 },
+      { cycleDays: 39, winRate: 0.22, arr: 114000 }
+    ]
+  },
+  [visualizationRefKey(ChannelMixVisualization.meta)]: {
+    data: [
+      { channel: "Direct", sessions: 4200 },
+      { channel: "Organic Search", sessions: 3600 },
+      { channel: "Paid Search", sessions: 2100 },
+      { channel: "Partner", sessions: 1400 },
+      { channel: "Referral", sessions: 900 }
+    ]
+  },
+  [visualizationRefKey(EngagementHeatmapVisualization.meta)]: {
+    data: [
+      { weekday: "Mon", timeBand: "09:00", engagementScore: 74 },
+      { weekday: "Mon", timeBand: "13:00", engagementScore: 82 },
+      { weekday: "Tue", timeBand: "09:00", engagementScore: 69 },
+      { weekday: "Tue", timeBand: "13:00", engagementScore: 88 },
+      { weekday: "Wed", timeBand: "09:00", engagementScore: 77 },
+      { weekday: "Wed", timeBand: "13:00", engagementScore: 91 },
+      { weekday: "Thu", timeBand: "09:00", engagementScore: 72 },
+      { weekday: "Thu", timeBand: "13:00", engagementScore: 86 },
+      { weekday: "Fri", timeBand: "09:00", engagementScore: 65 },
+      { weekday: "Fri", timeBand: "13:00", engagementScore: 79 }
+    ]
+  },
+  [visualizationRefKey(ConversionFunnelVisualization.meta)]: {
+    data: [
+      { stage: "Visited Site", users: 12000 },
+      { stage: "Started Trial", users: 4200 },
+      { stage: "Activated Workspace", users: 2400 },
+      { stage: "Requested Demo", users: 980 },
+      { stage: "Closed Won", users: 310 }
+    ]
+  },
+  [visualizationRefKey(AccountCoverageGeoVisualization.meta)]: {
+    data: [
+      { city: "Paris", latitude: 48.8566, longitude: 2.3522, accounts: 48 },
+      { city: "London", latitude: 51.5072, longitude: -0.1276, accounts: 62 },
+      { city: "New York", latitude: 40.7128, longitude: -74.006, accounts: 71 },
+      { city: "Toronto", latitude: 43.6532, longitude: -79.3832, accounts: 36 },
+      {
+        city: "Singapore",
+        latitude: 1.3521,
+        longitude: 103.8198,
+        accounts: 29
+      }
+    ]
+  }
+};
+function refOf(spec) {
+  return { key: spec.meta.key, version: spec.meta.version };
+}
+function visualizationRefKey(ref) {
+  return `${ref.key}.v${ref.version}`;
+}
+
+// src/visualizations/widgets.ts
+var LEGACY_VISUALIZATION_REFS = {
+  METRIC: refOf(RevenueMetricVisualization),
+  LINE_CHART: refOf(RevenueTrendVisualization),
+  BAR_CHART: refOf(RegionalRevenueVisualization),
+  AREA_CHART: refOf(RetentionAreaVisualization),
+  SCATTER_PLOT: refOf(PipelineScatterVisualization),
+  PIE_CHART: refOf(ChannelMixVisualization),
+  HEATMAP: refOf(EngagementHeatmapVisualization),
+  FUNNEL: refOf(ConversionFunnelVisualization),
+  MAP: refOf(AccountCoverageGeoVisualization)
+};
+function createExampleWidgets(dashboardId) {
+  return [
+    widget(dashboardId, "widget_revenue_metric", "Revenue Snapshot", "METRIC", 0, 0, 4, 2, {
+      layout: "single",
+      bindings: [binding(RevenueMetricVisualization, 200)]
+    }),
+    widget(dashboardId, "widget_revenue_trend", "Revenue Trend", "LINE_CHART", 4, 0, 8, 4, {
+      layout: "single",
+      bindings: [binding(RevenueTrendVisualization)]
+    }),
+    widget(dashboardId, "widget_regional_revenue", "Regional Revenue", "BAR_CHART", 0, 2, 6, 4, {
+      layout: "single",
+      bindings: [binding(RegionalRevenueVisualization)]
+    }),
+    widget(dashboardId, "widget_channel_mix", "Channel Mix", "PIE_CHART", 6, 2, 6, 4, {
+      layout: "single",
+      bindings: [binding(ChannelMixVisualization)]
+    }),
+    widget(dashboardId, "widget_retention", "Retention Curve", "AREA_CHART", 0, 6, 6, 4, {
+      layout: "single",
+      bindings: [binding(RetentionAreaVisualization)]
+    }),
+    widget(dashboardId, "widget_pipeline", "Pipeline Velocity", "SCATTER_PLOT", 6, 6, 6, 4, {
+      layout: "single",
+      bindings: [binding(PipelineScatterVisualization)]
+    }),
+    widget(dashboardId, "widget_heatmap", "Engagement Heatmap", "HEATMAP", 0, 10, 8, 4, {
+      layout: "single",
+      bindings: [binding(EngagementHeatmapVisualization)]
+    }),
+    widget(dashboardId, "widget_funnel", "Conversion Funnel", "FUNNEL", 8, 10, 4, 4, {
+      layout: "single",
+      bindings: [binding(ConversionFunnelVisualization)]
+    }),
+    widget(dashboardId, "widget_geo", "Account Coverage", "MAP", 0, 14, 12, 5, {
+      layout: "single",
+      bindings: [binding(AccountCoverageGeoVisualization, 360)]
+    }),
+    widget(dashboardId, "widget_comparison", "Commercial Comparison", "EMBED", 0, 19, 12, 6, {
+      layout: "comparison",
+      description: "Compare regional distribution, channel balance, and funnel shape.",
+      bindings: [
+        binding(RegionalRevenueVisualization, 240),
+        binding(ChannelMixVisualization, 240),
+        binding(ConversionFunnelVisualization, 240)
+      ]
+    }),
+    widget(dashboardId, "widget_timeline", "Growth Timeline", "EMBED", 0, 25, 12, 6, {
+      layout: "timeline",
+      description: "Track revenue and retention over the same reporting cadence.",
+      bindings: [
+        binding(RevenueTrendVisualization, 220),
+        binding(RetentionAreaVisualization, 220)
+      ]
+    })
+  ];
+}
+function resolveAnalyticsWidget(widget) {
+  const config = parseWidgetConfig(widget);
+  const bindings = config.bindings.map((binding) => {
+    const spec = AnalyticsVisualizationSpecMap.get(visualizationRefKey(binding.ref));
+    if (!spec)
+      return null;
+    return {
+      key: `${widget.id}:${visualizationRefKey(binding.ref)}`,
+      spec,
+      data: binding.data,
+      title: binding.title ?? spec.meta.title,
+      description: binding.description ?? spec.meta.description,
+      height: binding.height
+    };
+  }).filter((binding) => Boolean(binding));
+  if (!bindings.length)
+    return null;
+  return {
+    id: widget.id,
+    name: widget.name,
+    description: config.description,
+    layout: config.layout,
+    gridX: widget.gridX,
+    gridY: widget.gridY,
+    gridWidth: widget.gridWidth,
+    gridHeight: widget.gridHeight,
+    bindings
+  };
+}
+function parseWidgetConfig(widget) {
+  if (isAnalyticsWidgetConfig(widget.config)) {
+    return widget.config;
+  }
+  const legacyRef = LEGACY_VISUALIZATION_REFS[widget.type];
+  return legacyRef ? {
+    layout: "single",
+    bindings: [
+      {
+        ref: legacyRef,
+        data: AnalyticsVisualizationSampleData[visualizationRefKey(legacyRef)]
+      }
+    ]
+  } : { layout: "single", bindings: [] };
+}
+function binding(spec, height = 280) {
+  return {
+    ref: refOf(spec),
+    data: AnalyticsVisualizationSampleData[visualizationRefKey(spec.meta)],
+    height
+  };
+}
+function widget(dashboardId, id, name, type, gridX, gridY, gridWidth, gridHeight, config) {
+  const now = new Date;
+  return {
+    id,
+    dashboardId,
+    name,
+    type,
+    gridX,
+    gridY,
+    gridWidth,
+    gridHeight,
+    config,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function isAnalyticsWidgetConfig(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return (candidate.layout === "single" || candidate.layout === "comparison" || candidate.layout === "timeline") && Array.isArray(candidate.bindings);
+}
 // src/ui/hooks/useAnalyticsData.ts
-import { useCallback, useEffect, useState } from "react";
 import { useTemplateRuntime } from "@contractspec/lib.example-shared-ui";
+import { useCallback, useEffect, useState } from "react";
 "use client";
 function useAnalyticsData(projectId = "local-project") {
   const { handlers } = useTemplateRuntime();
@@ -27,7 +618,7 @@ function useAnalyticsData(projectId = "local-project") {
         if (first) {
           setSelectedDashboard(first);
           const dashboardWidgets = await analytics.getWidgets(first.id);
-          setWidgets(dashboardWidgets);
+          setWidgets(dashboardWidgets.length > 0 ? dashboardWidgets : createExampleWidgets(first.id));
         }
       }
     } catch (err) {
@@ -42,7 +633,7 @@ function useAnalyticsData(projectId = "local-project") {
   const selectDashboard = useCallback(async (dashboard) => {
     setSelectedDashboard(dashboard);
     const dashboardWidgets = await analytics.getWidgets(dashboard.id);
-    setWidgets(dashboardWidgets);
+    setWidgets(dashboardWidgets.length > 0 ? dashboardWidgets : createExampleWidgets(dashboard.id));
   }, [analytics]);
   const stats = {
     totalDashboards: dashboards.length,

package/dist/ui/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Analytics Dashboard Template Components
  */
-export * from './renderers';
 export { AnalyticsDashboard } from './AnalyticsDashboard';
 export * from './hooks';
+export * from './renderers';