@contractspec/example.saas-boilerplate 3.7.7 → 3.8.2

package/dist/visualizations/index.js

@@ -0,0 +1,218 @@
+// @bun
+// src/visualizations/catalog.ts
+import {
+  defineVisualization,
+  VisualizationRegistry
+} from "@contractspec/lib.contracts-spec/visualizations";
+var PROJECT_LIST_REF = {
+  key: "saas.project.list",
+  version: "1.0.0"
+};
+var META = {
+  version: "1.0.0",
+  domain: "saas",
+  stability: "experimental",
+  owners: ["@example.saas-boilerplate"],
+  tags: ["saas", "visualization", "projects"]
+};
+var 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." }
+  }
+});
+var 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." }
+  }
+});
+var 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." }
+  }
+});
+var 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." }
+  }
+});
+var SaasVisualizationSpecs = [
+  SaasProjectUsageVisualization,
+  SaasProjectStatusVisualization,
+  SaasProjectTierVisualization,
+  SaasProjectActivityVisualization
+];
+var SaasVisualizationRegistry = new VisualizationRegistry([
+  ...SaasVisualizationSpecs
+]);
+var SaasVisualizationRefs = SaasVisualizationSpecs.map((spec) => ({
+  key: spec.meta.key,
+  version: spec.meta.version
+}));
+
+// src/visualizations/selectors.ts
+function toDayKey(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return date.toISOString().slice(0, 10);
+}
+function createSaasVisualizationItems(projects, projectLimit = 10) {
+  const statusCounts = new Map;
+  const tierCounts = new Map;
+  const activityCounts = new Map;
+  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."
+    }
+  ];
+}
+export {
+  createSaasVisualizationItems,
+  SaasVisualizationSpecs,
+  SaasVisualizationRegistry,
+  SaasVisualizationRefs,
+  SaasProjectUsageVisualization,
+  SaasProjectTierVisualization,
+  SaasProjectStatusVisualization,
+  SaasProjectActivityVisualization
+};

package/dist/visualizations/selectors.d.ts

@@ -0,0 +1,8 @@
+import type { VisualizationSurfaceItem } from '@contractspec/lib.design-system';
+import type { Project } from '../handlers/saas.handlers';
+type DateLike = Date | string;
+interface ProjectLike extends Pick<Project, 'status' | 'tier'> {
+    createdAt: DateLike;
+}
+export declare function createSaasVisualizationItems(projects: ProjectLike[], projectLimit?: number): VisualizationSurfaceItem[];
+export {};

package/dist/visualizations/selectors.js

@@ -0,0 +1,211 @@
+// @bun
+// src/visualizations/catalog.ts
+import {
+  defineVisualization,
+  VisualizationRegistry
+} from "@contractspec/lib.contracts-spec/visualizations";
+var PROJECT_LIST_REF = {
+  key: "saas.project.list",
+  version: "1.0.0"
+};
+var META = {
+  version: "1.0.0",
+  domain: "saas",
+  stability: "experimental",
+  owners: ["@example.saas-boilerplate"],
+  tags: ["saas", "visualization", "projects"]
+};
+var 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." }
+  }
+});
+var 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." }
+  }
+});
+var 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." }
+  }
+});
+var 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." }
+  }
+});
+var SaasVisualizationSpecs = [
+  SaasProjectUsageVisualization,
+  SaasProjectStatusVisualization,
+  SaasProjectTierVisualization,
+  SaasProjectActivityVisualization
+];
+var SaasVisualizationRegistry = new VisualizationRegistry([
+  ...SaasVisualizationSpecs
+]);
+var SaasVisualizationRefs = SaasVisualizationSpecs.map((spec) => ({
+  key: spec.meta.key,
+  version: spec.meta.version
+}));
+
+// src/visualizations/selectors.ts
+function toDayKey(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return date.toISOString().slice(0, 10);
+}
+function createSaasVisualizationItems(projects, projectLimit = 10) {
+  const statusCounts = new Map;
+  const tierCounts = new Map;
+  const activityCounts = new Map;
+  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."
+    }
+  ];
+}
+export {
+  createSaasVisualizationItems
+};

package/dist/visualizations/selectors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.saas-boilerplate",
-  "version": "3.7.7",
+  "version": "3.8.2",
   "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,24 @@
     "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.10",
+    "@contractspec/lib.jobs": "3.7.10",
+    "@contractspec/module.audit-trail": "3.7.10",
+    "@contractspec/module.notifications": "3.7.10",
+    "@contractspec/lib.contracts-spec": "4.1.2",
+    "@contractspec/lib.schema": "3.7.8",
+    "@contractspec/lib.example-shared-ui": "6.0.10",
+    "@contractspec/lib.design-system": "3.8.3",
+    "@contractspec/lib.runtime-sandbox": "2.7.9",
     "react": "19.2.0",
     "react-dom": "19.2.0"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.8",
     "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.8"
   },
   "publishConfig": {
     "exports": {
@@ -701,6 +729,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 +749,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>
+	);
+}