@contractspec/example.saas-boilerplate 3.7.7 → 3.8.2

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

@@ -8,12 +8,29 @@ 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/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.',
+		},
+	];
+}