@contractspec/example.saas-boilerplate 3.7.7 → 3.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.saas-boilerplate",
-  "version": "3.7.7",
+  "version": "3.8.4",
   "description": "SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -327,6 +327,13 @@
       "node": "./dist/node/ui/SaasDashboard.js",
       "default": "./dist/ui/SaasDashboard.js"
     },
+    "./ui/SaasDashboard.visualizations": {
+      "types": "./dist/ui/SaasDashboard.visualizations.d.ts",
+      "browser": "./dist/browser/ui/SaasDashboard.visualizations.js",
+      "bun": "./dist/ui/SaasDashboard.visualizations.js",
+      "node": "./dist/node/ui/SaasDashboard.visualizations.js",
+      "default": "./dist/ui/SaasDashboard.visualizations.js"
+    },
     "./ui/SaasProjectList": {
       "types": "./dist/ui/SaasProjectList.d.ts",
       "browser": "./dist/browser/ui/SaasProjectList.js",
@@ -340,6 +347,27 @@
       "bun": "./dist/ui/SaasSettingsPanel.js",
       "node": "./dist/node/ui/SaasSettingsPanel.js",
       "default": "./dist/ui/SaasSettingsPanel.js"
+    },
+    "./visualizations": {
+      "types": "./dist/visualizations/index.d.ts",
+      "browser": "./dist/browser/visualizations/index.js",
+      "bun": "./dist/visualizations/index.js",
+      "node": "./dist/node/visualizations/index.js",
+      "default": "./dist/visualizations/index.js"
+    },
+    "./visualizations/catalog": {
+      "types": "./dist/visualizations/catalog.d.ts",
+      "browser": "./dist/browser/visualizations/catalog.js",
+      "bun": "./dist/visualizations/catalog.js",
+      "node": "./dist/node/visualizations/catalog.js",
+      "default": "./dist/visualizations/catalog.js"
+    },
+    "./visualizations/selectors": {
+      "types": "./dist/visualizations/selectors.d.ts",
+      "browser": "./dist/browser/visualizations/selectors.js",
+      "bun": "./dist/visualizations/selectors.js",
+      "node": "./dist/node/visualizations/selectors.js",
+      "default": "./dist/visualizations/selectors.js"
     }
   },
   "scripts": {
@@ -358,24 +386,25 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.identity-rbac": "3.7.7",
-    "@contractspec/lib.jobs": "3.7.7",
-    "@contractspec/module.audit-trail": "3.7.7",
-    "@contractspec/module.notifications": "3.7.7",
-    "@contractspec/lib.contracts-spec": "4.0.0",
-    "@contractspec/lib.schema": "3.7.6",
-    "@contractspec/lib.example-shared-ui": "6.0.7",
-    "@contractspec/lib.design-system": "3.8.0",
-    "@contractspec/lib.runtime-sandbox": "2.7.6",
+    "@contractspec/lib.identity-rbac": "3.7.12",
+    "@contractspec/lib.jobs": "3.7.12",
+    "@contractspec/module.audit-trail": "3.7.12",
+    "@contractspec/module.notifications": "3.7.12",
+    "@contractspec/lib.contracts-spec": "5.0.0",
+    "@contractspec/lib.schema": "3.7.10",
+    "@contractspec/lib.example-shared-ui": "6.0.12",
+    "@contractspec/lib.design-system": "3.8.5",
+    "@contractspec/lib.runtime-sandbox": "2.7.10",
     "react": "19.2.0",
-    "react-dom": "19.2.0"
+    "react-dom": "19.2.0",
+    "@contractspec/lib.presentation-runtime-core": "3.9.0"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.9",
     "typescript": "^5.9.3",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.2",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.bun": "3.7.9"
   },
   "publishConfig": {
     "exports": {
@@ -701,6 +730,13 @@
         "node": "./dist/node/ui/SaasDashboard.js",
         "default": "./dist/ui/SaasDashboard.js"
       },
+      "./ui/SaasDashboard.visualizations": {
+        "types": "./dist/ui/SaasDashboard.visualizations.d.ts",
+        "browser": "./dist/browser/ui/SaasDashboard.visualizations.js",
+        "bun": "./dist/ui/SaasDashboard.visualizations.js",
+        "node": "./dist/node/ui/SaasDashboard.visualizations.js",
+        "default": "./dist/ui/SaasDashboard.visualizations.js"
+      },
       "./ui/SaasProjectList": {
         "types": "./dist/ui/SaasProjectList.d.ts",
         "browser": "./dist/browser/ui/SaasProjectList.js",
@@ -714,6 +750,27 @@
         "bun": "./dist/ui/SaasSettingsPanel.js",
         "node": "./dist/node/ui/SaasSettingsPanel.js",
         "default": "./dist/ui/SaasSettingsPanel.js"
+      },
+      "./visualizations": {
+        "types": "./dist/visualizations/index.d.ts",
+        "browser": "./dist/browser/visualizations/index.js",
+        "bun": "./dist/visualizations/index.js",
+        "node": "./dist/node/visualizations/index.js",
+        "default": "./dist/visualizations/index.js"
+      },
+      "./visualizations/catalog": {
+        "types": "./dist/visualizations/catalog.d.ts",
+        "browser": "./dist/browser/visualizations/catalog.js",
+        "bun": "./dist/visualizations/catalog.js",
+        "node": "./dist/node/visualizations/catalog.js",
+        "default": "./dist/visualizations/catalog.js"
+      },
+      "./visualizations/selectors": {
+        "types": "./dist/visualizations/selectors.d.ts",
+        "browser": "./dist/browser/visualizations/selectors.js",
+        "bun": "./dist/visualizations/selectors.js",
+        "node": "./dist/node/visualizations/selectors.js",
+        "default": "./dist/visualizations/selectors.js"
       }
     },
     "registry": "https://registry.npmjs.org/",

package/src/index.ts

@@ -14,6 +14,7 @@ export * from './project';
 export * from './saas-boilerplate.feature';
 export * from './settings';
 export * from './ui';
+export * from './visualizations';
 
 // Import docs for registration
 import './docs';

package/src/saas-boilerplate.feature.ts

@@ -4,6 +4,7 @@
  * Defines the feature module for the SaaS application foundation.
  */
 import { defineFeature } from '@contractspec/lib.contracts-spec';
+import { SaasVisualizationRefs } from './visualizations';
 
 /**
  * SaaS Boilerplate feature module that bundles project management,
@@ -102,6 +103,8 @@ export const SaasBoilerplateFeature = defineFeature({
 		},
 	],
 
+	visualizations: SaasVisualizationRefs,
+
 	// Capability requirements
 	capabilities: {
 		requires: [

package/src/ui/SaasDashboard.tsx

@@ -30,6 +30,7 @@ import {
 import { useProjectMutations } from './hooks/useProjectMutations';
 import { CreateProjectModal } from './modals/CreateProjectModal';
 import { ProjectActionsModal } from './modals/ProjectActionsModal';
+import { SaasVisualizationOverview } from './SaasDashboard.visualizations';
 
 type Tab = 'projects' | 'billing' | 'settings';
 
@@ -115,6 +116,13 @@ export function SaasDashboard() {
 				</StatCardGroup>
 			)}
 
+			{data && stats && (
+				<SaasVisualizationOverview
+					projectLimit={stats.projectLimit}
+					projects={data.items}
+				/>
+			)}
+
 			{/* Navigation Tabs */}
 			<nav className="flex gap-1 rounded-lg bg-muted p-1" role="tablist">
 				{tabs.map((tab) => (

package/src/ui/SaasDashboard.visualizations.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import {
+	VisualizationCard,
+	VisualizationGrid,
+} from '@contractspec/lib.design-system';
+import type { Project } from '../handlers/saas.handlers';
+import { createSaasVisualizationItems } from '../visualizations';
+
+export function SaasVisualizationOverview({
+	projects,
+	projectLimit,
+}: {
+	projects: Project[];
+	projectLimit: number;
+}) {
+	const items = createSaasVisualizationItems(projects, projectLimit);
+
+	return (
+		<section className="space-y-3">
+			<div>
+				<h3 className="font-semibold text-lg">Portfolio Visualizations</h3>
+				<p className="text-muted-foreground text-sm">
+					Contract-backed charts for project mix, capacity, and activity.
+				</p>
+			</div>
+			<VisualizationGrid>
+				{items.map((item) => (
+					<VisualizationCard
+						key={item.key}
+						data={item.data}
+						description={item.description}
+						height={item.height}
+						spec={item.spec}
+						title={item.title}
+					/>
+				))}
+			</VisualizationGrid>
+		</section>
+	);
+}

package/src/ui/renderers/project-list.markdown.ts

@@ -3,17 +3,34 @@
  *
  * Uses dynamic import to ensure correct build order.
  */
-import type { PresentationRenderer } from '@contractspec/lib.contracts-spec/presentations/transform-engine';
+import type { PresentationRenderer } from '@contractspec/lib.presentation-runtime-core/transform-engine';
 import {
 	mockGetSubscriptionHandler,
 	mockListProjectsHandler,
 } from '../../handlers';
+import { createSaasVisualizationItems } from '../../visualizations';
 
-interface ProjectItem {
-	id: string;
-	name: string;
-	status: string;
-	description?: string;
+type ListProjectsResult = Awaited<ReturnType<typeof mockListProjectsHandler>>;
+type ProjectItem = ListProjectsResult['projects'][number];
+type VisualizationProject = Parameters<
+	typeof createSaasVisualizationItems
+>[0][number];
+
+const PROJECT_TIERS: VisualizationProject['tier'][] = [
+	'FREE',
+	'PRO',
+	'ENTERPRISE',
+];
+
+function toVisualizationProject(
+	project: ProjectItem,
+	index: number
+): VisualizationProject {
+	return {
+		status: project.status === 'DELETED' ? 'ARCHIVED' : project.status,
+		tier: PROJECT_TIERS[index % PROJECT_TIERS.length] ?? 'FREE',
+		createdAt: project.createdAt,
+	};
 }
 
 /**
@@ -39,11 +56,7 @@ export const projectListMarkdownRenderer: PresentationRenderer<{
 			offset: 0,
 		});
 
-		// The example handler returns 'projects', not 'items'
-		const items =
-			(data as { projects?: ProjectItem[]; items?: ProjectItem[] }).projects ??
-			(data as { items?: ProjectItem[] }).items ??
-			[];
+		const items = data.projects ?? [];
 
 		const lines: string[] = [
 			'# Projects',
@@ -100,12 +113,15 @@ export const saasDashboardMarkdownRenderer: PresentationRenderer<{
 			mockGetSubscriptionHandler(),
 		]);
 
-		const projects =
-			(projectsData as { projects?: ProjectItem[] }).projects ?? [];
+		const projects = projectsData.projects ?? [];
 		const activeProjects = projects.filter((p) => p.status === 'ACTIVE').length;
 		const archivedProjects = projects.filter(
 			(p) => p.status === 'ARCHIVED'
 		).length;
+		const visualizations = createSaasVisualizationItems(
+			projects.map(toVisualizationProject),
+			10
+		);
 
 		const lines: string[] = [
 			'# SaaS Dashboard',
@@ -122,10 +138,18 @@ export const saasDashboardMarkdownRenderer: PresentationRenderer<{
 			`| Subscription Plan | ${subscription.planName} |`,
 			`| Subscription Status | ${subscription.status} |`,
 			'',
-			'## Projects',
-			'',
 		];
 
+		lines.push('## Visualization Overview');
+		lines.push('');
+		for (const item of visualizations) {
+			lines.push(`- **${item.title}** via \`${item.spec.meta.key}\``);
+		}
+
+		lines.push('');
+		lines.push('## Projects');
+		lines.push('');
+
 		if (projects.length === 0) {
 			lines.push('_No projects yet._');
 		} else {

package/src/ui/renderers/project-list.renderer.tsx

@@ -2,7 +2,7 @@
  * React renderer for SaaS Project List presentation
  */
 
-import type { PresentationRenderer } from '@contractspec/lib.contracts-spec/presentations/transform-engine';
+import type { PresentationRenderer } from '@contractspec/lib.presentation-runtime-core/transform-engine';
 import * as React from 'react';
 import { SaasProjectList } from '../SaasProjectList';
 

package/src/visualizations/catalog.ts

@@ -0,0 +1,153 @@
+import {
+	defineVisualization,
+	VisualizationRegistry,
+} from '@contractspec/lib.contracts-spec/visualizations';
+
+const PROJECT_LIST_REF = {
+	key: 'saas.project.list',
+	version: '1.0.0',
+} as const;
+const META = {
+	version: '1.0.0',
+	domain: 'saas',
+	stability: 'experimental' as const,
+	owners: ['@example.saas-boilerplate'],
+	tags: ['saas', 'visualization', 'projects'],
+};
+
+export const SaasProjectUsageVisualization = defineVisualization({
+	meta: {
+		...META,
+		key: 'saas-boilerplate.visualization.project-usage',
+		title: 'Project Capacity',
+		description: 'Current project count against the current plan limit.',
+		goal: 'Show usage against the active plan allowance.',
+		context: 'SaaS account overview.',
+	},
+	source: { primary: PROJECT_LIST_REF, resultPath: 'data' },
+	visualization: {
+		kind: 'metric',
+		measure: 'totalProjects',
+		comparisonMeasure: 'projectLimit',
+		measures: [
+			{
+				key: 'totalProjects',
+				label: 'Projects',
+				dataPath: 'totalProjects',
+				format: 'number',
+			},
+			{
+				key: 'projectLimit',
+				label: 'Plan Limit',
+				dataPath: 'projectLimit',
+				format: 'number',
+			},
+		],
+		table: { caption: 'Current project count and plan limit.' },
+	},
+});
+
+export const SaasProjectStatusVisualization = defineVisualization({
+	meta: {
+		...META,
+		key: 'saas-boilerplate.visualization.project-status',
+		title: 'Project Status',
+		description: 'Distribution of project states.',
+		goal: 'Show the mix of active, draft, and archived projects.',
+		context: 'Project portfolio overview.',
+	},
+	source: { primary: PROJECT_LIST_REF, resultPath: 'data' },
+	visualization: {
+		kind: 'pie',
+		nameDimension: 'status',
+		valueMeasure: 'projects',
+		dimensions: [
+			{ key: 'status', label: 'Status', dataPath: 'status', type: 'category' },
+		],
+		measures: [
+			{
+				key: 'projects',
+				label: 'Projects',
+				dataPath: 'projects',
+				format: 'number',
+			},
+		],
+		table: { caption: 'Project counts by status.' },
+	},
+});
+
+export const SaasProjectTierVisualization = defineVisualization({
+	meta: {
+		...META,
+		key: 'saas-boilerplate.visualization.project-tiers',
+		title: 'Tier Comparison',
+		description: 'Distribution of projects across tiers.',
+		goal: 'Compare how the current portfolio is distributed by tier.',
+		context: 'Plan and packaging overview.',
+	},
+	source: { primary: PROJECT_LIST_REF, resultPath: 'data' },
+	visualization: {
+		kind: 'cartesian',
+		variant: 'bar',
+		xDimension: 'tier',
+		yMeasures: ['projects'],
+		dimensions: [
+			{ key: 'tier', label: 'Tier', dataPath: 'tier', type: 'category' },
+		],
+		measures: [
+			{
+				key: 'projects',
+				label: 'Projects',
+				dataPath: 'projects',
+				format: 'number',
+				color: '#1d4ed8',
+			},
+		],
+		table: { caption: 'Project counts by tier.' },
+	},
+});
+
+export const SaasProjectActivityVisualization = defineVisualization({
+	meta: {
+		...META,
+		key: 'saas-boilerplate.visualization.project-activity',
+		title: 'Recent Project Activity',
+		description: 'Daily project creation activity.',
+		goal: 'Show recent project activity over time.',
+		context: 'Project portfolio trend view.',
+	},
+	source: { primary: PROJECT_LIST_REF, resultPath: 'data' },
+	visualization: {
+		kind: 'cartesian',
+		variant: 'line',
+		xDimension: 'day',
+		yMeasures: ['projects'],
+		dimensions: [{ key: 'day', label: 'Day', dataPath: 'day', type: 'time' }],
+		measures: [
+			{
+				key: 'projects',
+				label: 'Projects',
+				dataPath: 'projects',
+				format: 'number',
+				color: '#0f766e',
+			},
+		],
+		table: { caption: 'Daily project creation counts.' },
+	},
+});
+
+export const SaasVisualizationSpecs = [
+	SaasProjectUsageVisualization,
+	SaasProjectStatusVisualization,
+	SaasProjectTierVisualization,
+	SaasProjectActivityVisualization,
+] as const;
+
+export const SaasVisualizationRegistry = new VisualizationRegistry([
+	...SaasVisualizationSpecs,
+]);
+
+export const SaasVisualizationRefs = SaasVisualizationSpecs.map((spec) => ({
+	key: spec.meta.key,
+	version: spec.meta.version,
+}));

package/src/visualizations/index.ts

@@ -0,0 +1,2 @@
+export * from './catalog';
+export * from './selectors';

package/src/visualizations/selectors.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'bun:test';
+import { createSaasVisualizationItems } from './selectors';
+
+describe('saas visualization selectors', () => {
+	it('creates dashboard visualization items', () => {
+		const items = createSaasVisualizationItems(
+			[
+				{
+					status: 'ACTIVE',
+					tier: 'PRO',
+					createdAt: '2026-03-18T10:00:00Z',
+				},
+				{
+					status: 'DRAFT',
+					tier: 'FREE',
+					createdAt: '2026-03-19T10:00:00Z',
+				},
+			],
+			10
+		);
+
+		expect(items).toHaveLength(4);
+		expect(items[0]?.title).toBe('Project Capacity');
+	});
+});

package/src/visualizations/selectors.ts

@@ -0,0 +1,85 @@
+import type { VisualizationSurfaceItem } from '@contractspec/lib.design-system';
+import type { Project } from '../handlers/saas.handlers';
+import {
+	SaasProjectActivityVisualization,
+	SaasProjectStatusVisualization,
+	SaasProjectTierVisualization,
+	SaasProjectUsageVisualization,
+} from './catalog';
+
+type DateLike = Date | string;
+
+interface ProjectLike extends Pick<Project, 'status' | 'tier'> {
+	createdAt: DateLike;
+}
+
+function toDayKey(value: DateLike): string {
+	const date = value instanceof Date ? value : new Date(value);
+	return date.toISOString().slice(0, 10);
+}
+
+export function createSaasVisualizationItems(
+	projects: ProjectLike[],
+	projectLimit = 10
+): VisualizationSurfaceItem[] {
+	const statusCounts = new Map<string, number>();
+	const tierCounts = new Map<string, number>();
+	const activityCounts = new Map<string, number>();
+
+	for (const project of projects) {
+		statusCounts.set(
+			project.status,
+			(statusCounts.get(project.status) ?? 0) + 1
+		);
+		tierCounts.set(project.tier, (tierCounts.get(project.tier) ?? 0) + 1);
+		const day = toDayKey(project.createdAt);
+		activityCounts.set(day, (activityCounts.get(day) ?? 0) + 1);
+	}
+
+	return [
+		{
+			key: 'saas-capacity',
+			spec: SaasProjectUsageVisualization,
+			data: { data: [{ totalProjects: projects.length, projectLimit }] },
+			title: 'Project Capacity',
+			description: 'Current project count compared to the active limit.',
+			height: 220,
+		},
+		{
+			key: 'saas-status',
+			spec: SaasProjectStatusVisualization,
+			data: {
+				data: Array.from(statusCounts.entries()).map(([status, count]) => ({
+					status,
+					projects: count,
+				})),
+			},
+			title: 'Project Status',
+			description: 'Status mix across the current project portfolio.',
+			height: 260,
+		},
+		{
+			key: 'saas-tier',
+			spec: SaasProjectTierVisualization,
+			data: {
+				data: Array.from(tierCounts.entries()).map(([tier, count]) => ({
+					tier,
+					projects: count,
+				})),
+			},
+			title: 'Tier Comparison',
+			description: 'How projects are distributed across tiers.',
+		},
+		{
+			key: 'saas-activity',
+			spec: SaasProjectActivityVisualization,
+			data: {
+				data: Array.from(activityCounts.entries())
+					.sort(([left], [right]) => left.localeCompare(right))
+					.map(([day, count]) => ({ day, projects: count })),
+			},
+			title: 'Recent Project Activity',
+			description: 'Daily project creation activity.',
+		},
+	];
+}