@contractspec/example.saas-boilerplate 3.7.6 → 3.8.2

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.',
+		},
+	];
+}

package/tsconfig.json

@@ -1,10 +1,9 @@
 {
-  "extends": "@contractspec/tool.typescript/react-library.json",
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"],
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  }
+	"extends": "@contractspec/tool.typescript/react-library.json",
+	"include": ["src"],
+	"exclude": ["node_modules", "dist"],
+	"compilerOptions": {
+		"rootDir": "src",
+		"outDir": "dist"
+	}
 }
-

package/tsdown.config.js

@@ -1,6 +1,10 @@
-import { defineConfig, moduleLibrary, withDevExports } from '@contractspec/tool.bun';
+import {
+	defineConfig,
+	moduleLibrary,
+	withDevExports,
+} from '@contractspec/tool.bun';
 
 export default defineConfig((options) => ({
-  ...moduleLibrary,
-  ...withDevExports,
+	...moduleLibrary,
+	...withDevExports,
 }));