@contractspec/example.saas-boilerplate 1.46.1 → 1.48.0

package/dist/ui/renderers/project-list.renderer.d.ts

@@ -0,0 +1,9 @@
+import { PresentationRenderer } from "@contractspec/lib.contracts";
+import * as React from "react";
+
+//#region src/ui/renderers/project-list.renderer.d.ts
+
+declare const projectListReactRenderer: PresentationRenderer<React.ReactElement>;
+//#endregion
+export { projectListReactRenderer };
+//# sourceMappingURL=project-list.renderer.d.ts.map

package/dist/ui/renderers/project-list.renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-list.renderer.d.ts","names":[],"sources":["../../../src/ui/renderers/project-list.renderer.tsx"],"sourcesContent":[],"mappings":";;;;;cAOa,0BAA0B,qBAAqB,KAAA,CAAM"}

package/dist/ui/renderers/project-list.renderer.js

@@ -0,0 +1,17 @@
+import { SaasProjectList } from "../SaasProjectList.js";
+import "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/ui/renderers/project-list.renderer.tsx
+const projectListReactRenderer = {
+	target: "react",
+	render: async (desc, _ctx) => {
+		if (desc.source.type !== "component") throw new Error("Invalid source type");
+		if (desc.source.componentKey !== "SaasProjectListView") throw new Error(`Unknown component: ${desc.source.componentKey}`);
+		return /* @__PURE__ */ jsx(SaasProjectList, {});
+	}
+};
+
+//#endregion
+export { projectListReactRenderer };
+//# sourceMappingURL=project-list.renderer.js.map

package/dist/ui/renderers/project-list.renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-list.renderer.js","names":[],"sources":["../../../src/ui/renderers/project-list.renderer.tsx"],"sourcesContent":["/**\n * React renderer for SaaS Project List presentation\n */\nimport * as React from 'react';\nimport type { PresentationRenderer } from '@contractspec/lib.contracts';\nimport { SaasProjectList } from '../SaasProjectList';\n\nexport const projectListReactRenderer: PresentationRenderer<React.ReactElement> =\n  {\n    target: 'react',\n    render: async (desc, _ctx) => {\n      if (desc.source.type !== 'component') {\n        throw new Error('Invalid source type');\n      }\n\n      if (desc.source.componentKey !== 'SaasProjectListView') {\n        throw new Error(`Unknown component: ${desc.source.componentKey}`);\n      }\n\n      return <SaasProjectList />;\n    },\n  };\n"],"mappings":";;;;;AAOA,MAAa,2BACX;CACE,QAAQ;CACR,QAAQ,OAAO,MAAM,SAAS;AAC5B,MAAI,KAAK,OAAO,SAAS,YACvB,OAAM,IAAI,MAAM,sBAAsB;AAGxC,MAAI,KAAK,OAAO,iBAAiB,sBAC/B,OAAM,IAAI,MAAM,sBAAsB,KAAK,OAAO,eAAe;AAGnE,SAAO,oBAAC,oBAAkB;;CAE7B"}

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@contractspec/example.saas-boilerplate",
-  "version": "1.46.1",
+  "version": "1.48.0",
   "description": "SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings",
   "type": "module",
-  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
@@ -21,6 +20,7 @@
     "./docs/saas-boilerplate.docblock": "./dist/docs/saas-boilerplate.docblock.js",
     "./example": "./dist/example.js",
     "./handlers": "./dist/handlers/index.js",
+    "./handlers/saas.handlers": "./dist/handlers/saas.handlers.js",
     "./presentations": "./dist/presentations/index.js",
     "./project": "./dist/project/index.js",
     "./project/project.entity": "./dist/project/project.entity.js",
@@ -31,10 +31,28 @@
     "./project/project.presentation": "./dist/project/project.presentation.js",
     "./project/project.schema": "./dist/project/project.schema.js",
     "./saas-boilerplate.feature": "./dist/saas-boilerplate.feature.js",
+    "./seeders": "./dist/seeders/index.js",
     "./settings": "./dist/settings/index.js",
     "./settings/settings.entity": "./dist/settings/settings.entity.js",
     "./settings/settings.enum": "./dist/settings/settings.enum.js",
     "./shared/mock-data": "./dist/shared/mock-data.js",
+    "./shared/overlay-types": "./dist/shared/overlay-types.js",
+    "./tests/operations.test-spec": "./dist/tests/operations.test-spec.js",
+    "./ui": "./dist/ui/index.js",
+    "./ui/hooks": "./dist/ui/hooks/index.js",
+    "./ui/hooks/useProjectList": "./dist/ui/hooks/useProjectList.js",
+    "./ui/hooks/useProjectMutations": "./dist/ui/hooks/useProjectMutations.js",
+    "./ui/modals": "./dist/ui/modals/index.js",
+    "./ui/modals/CreateProjectModal": "./dist/ui/modals/CreateProjectModal.js",
+    "./ui/modals/ProjectActionsModal": "./dist/ui/modals/ProjectActionsModal.js",
+    "./ui/overlays": "./dist/ui/overlays/index.js",
+    "./ui/overlays/demo-overlays": "./dist/ui/overlays/demo-overlays.js",
+    "./ui/renderers": "./dist/ui/renderers/index.js",
+    "./ui/renderers/project-list.markdown": "./dist/ui/renderers/project-list.markdown.js",
+    "./ui/renderers/project-list.renderer": "./dist/ui/renderers/project-list.renderer.js",
+    "./ui/SaasDashboard": "./dist/ui/SaasDashboard.js",
+    "./ui/SaasProjectList": "./dist/ui/SaasProjectList.js",
+    "./ui/SaasSettingsPanel": "./dist/ui/SaasSettingsPanel.js",
     "./*": "./*"
   },
   "scripts": {
@@ -48,23 +66,29 @@
     "lint": "bun lint:fix",
     "lint:fix": "eslint src --fix",
     "lint:check": "eslint src",
-    "test": "bun run"
+    "test": "bun test"
   },
   "dependencies": {
-    "@contractspec/lib.identity-rbac": "1.46.1",
-    "@contractspec/lib.jobs": "1.46.1",
-    "@contractspec/module.audit-trail": "1.46.1",
-    "@contractspec/module.notifications": "1.46.1",
-    "@contractspec/lib.contracts": "1.46.1",
-    "@contractspec/lib.schema": "1.46.1"
+    "@contractspec/lib.identity-rbac": "1.48.0",
+    "@contractspec/lib.jobs": "1.48.0",
+    "@contractspec/module.audit-trail": "1.48.0",
+    "@contractspec/module.notifications": "1.48.0",
+    "@contractspec/lib.contracts": "1.48.0",
+    "@contractspec/lib.schema": "1.48.0",
+    "@contractspec/lib.example-shared-ui": "1.2.0",
+    "@contractspec/lib.design-system": "1.48.0",
+    "@contractspec/lib.runtime-sandbox": "0.3.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
   },
   "devDependencies": {
-    "@contractspec/tool.tsdown": "1.46.1",
-    "@contractspec/tool.typescript": "1.46.1",
-    "tsdown": "^0.18.3",
-    "typescript": "^5.9.3"
+    "@contractspec/tool.tsdown": "1.48.0",
+    "@contractspec/tool.typescript": "1.48.0",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3",
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.2"
   },
-  "module": "./dist/index.js",
   "publishConfig": {
     "exports": {
       ".": "./dist/index.js",

package/src/billing/billing.presentation.ts

@@ -1,10 +1,9 @@
-import type { PresentationSpec } from '@contractspec/lib.contracts';
-import { StabilityEnum } from '@contractspec/lib.contracts';
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
 
 /**
  * Presentation for subscription overview.
  */
-export const SubscriptionPresentation: PresentationSpec = {
+export const SubscriptionPresentation = definePresentation({
   meta: {
     key: 'saas.billing.subscription',
     version: '1.0.0',
@@ -27,12 +26,12 @@ export const SubscriptionPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.billing.enabled'],
   },
-};
+});
 
 /**
  * Presentation for usage dashboard.
  */
-export const UsageDashboardPresentation: PresentationSpec = {
+export const UsageDashboardPresentation = definePresentation({
   meta: {
     key: 'saas.billing.usage',
     version: '1.0.0',
@@ -54,4 +53,4 @@ export const UsageDashboardPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.billing.enabled'],
   },
-};
+});

package/src/dashboard/dashboard.presentation.ts

@@ -1,10 +1,9 @@
-import type { PresentationSpec } from '@contractspec/lib.contracts';
-import { StabilityEnum } from '@contractspec/lib.contracts';
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
 
 /**
  * Main dashboard presentation for the SaaS application.
  */
-export const SaasDashboardPresentation: PresentationSpec = {
+export const SaasDashboardPresentation = definePresentation({
   meta: {
     key: 'saas.dashboard',
     version: '1.0.0',
@@ -27,12 +26,12 @@ export const SaasDashboardPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.enabled'],
   },
-};
+});
 
 /**
  * Settings panel presentation.
  */
-export const SettingsPanelPresentation: PresentationSpec = {
+export const SettingsPanelPresentation = definePresentation({
   meta: {
     key: 'saas.settings',
     version: '1.0.0',
@@ -54,4 +53,4 @@ export const SettingsPanelPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.enabled'],
   },
-};
+});

package/src/example.ts

@@ -1,6 +1,6 @@
-import type { ExampleSpec } from '@contractspec/lib.contracts';
+import { defineExample } from '@contractspec/lib.contracts';
 
-const example: ExampleSpec = {
+const example = defineExample({
   meta: {
     key: 'saas-boilerplate',
     version: '1.0.0',
@@ -33,6 +33,6 @@ const example: ExampleSpec = {
     studio: { enabled: true, installable: true },
     mcp: { enabled: true },
   },
-};
+});
 
 export default example;

package/src/handlers/index.ts

@@ -18,3 +18,6 @@ export {
   mockUpdateProjectHandler,
   mockDeleteProjectHandler,
 } from '../project/project.handler';
+
+// Runtime handlers (PGLite)
+export * from './saas.handlers';

package/src/handlers/saas.handlers.ts

@@ -0,0 +1,300 @@
+/**
+ * Runtime-local SaaS Boilerplate handlers
+ *
+ * Database-backed handlers for project and billing management.
+ */
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { web } from '@contractspec/lib.runtime-sandbox';
+const { generateId } = web;
+
+// ============ Types ============
+
+export interface Project {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  name: string;
+  description?: string;
+  status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED';
+  tier: 'FREE' | 'PRO' | 'ENTERPRISE';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface Subscription {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  plan: 'FREE' | 'PRO' | 'ENTERPRISE';
+  status: 'ACTIVE' | 'PAST_DUE' | 'CANCELED';
+  billingCycle: 'MONTHLY' | 'YEARLY';
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  cancelAtPeriodEnd: boolean;
+}
+
+export interface ListProjectsInput {
+  projectId: string;
+  organizationId?: string;
+  status?: Project['status'] | 'all';
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListProjectsOutput {
+  items: Project[];
+  total: number;
+  hasMore: boolean;
+}
+
+export interface CreateProjectInput {
+  name: string;
+  description?: string;
+  tier?: Project['tier'];
+}
+
+export interface UpdateProjectInput {
+  id: string;
+  name?: string;
+  description?: string;
+  status?: Project['status'];
+}
+
+// ============ Row Types ============
+
+interface ProjectRow extends Record<string, unknown> {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  name: string;
+  description: string | null;
+  status: string;
+  tier: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface SubscriptionRow extends Record<string, unknown> {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  plan: string;
+  status: string;
+  billingCycle: string;
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  cancelAtPeriodEnd: number;
+}
+
+function rowToProject(row: ProjectRow): Project {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    status: row.status as Project['status'],
+    tier: row.tier as Project['tier'],
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt),
+  };
+}
+
+function rowToSubscription(row: SubscriptionRow): Subscription {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    plan: row.plan as Subscription['plan'],
+    status: row.status as Subscription['status'],
+    billingCycle: row.billingCycle as Subscription['billingCycle'],
+    currentPeriodStart: new Date(row.currentPeriodStart),
+    currentPeriodEnd: new Date(row.currentPeriodEnd),
+    cancelAtPeriodEnd: Boolean(row.cancelAtPeriodEnd),
+  };
+}
+
+// ============ Handler Factory ============
+
+export function createSaasHandlers(db: DatabasePort) {
+  /**
+   * List projects
+   */
+  async function listProjects(
+    input: ListProjectsInput
+  ): Promise<ListProjectsOutput> {
+    const {
+      projectId,
+      organizationId,
+      status,
+      search,
+      limit = 20,
+      offset = 0,
+    } = input;
+
+    let whereClause = 'WHERE projectId = ?';
+    const params: (string | number)[] = [projectId];
+
+    if (organizationId) {
+      whereClause += ' AND organizationId = ?';
+      params.push(organizationId);
+    }
+
+    if (status && status !== 'all') {
+      whereClause += ' AND status = ?';
+      params.push(status);
+    }
+
+    if (search) {
+      whereClause += ' AND (name LIKE ? OR description LIKE ?)';
+      params.push(`%${search}%`, `%${search}%`);
+    }
+
+    const countResult = (
+      await db.query(
+        `SELECT COUNT(*) as count FROM saas_project ${whereClause}`,
+        params
+      )
+    ).rows as unknown as { count: number }[];
+    const total = countResult[0]?.count ?? 0;
+
+    const rows = (
+      await db.query(
+        `SELECT * FROM saas_project ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        [...params, limit, offset]
+      )
+    ).rows as unknown as ProjectRow[];
+
+    return {
+      items: rows.map(rowToProject),
+      total,
+      hasMore: offset + rows.length < total,
+    };
+  }
+
+  /**
+   * Get a single project
+   */
+  async function getProject(id: string): Promise<Project | null> {
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [id])
+    ).rows as unknown as ProjectRow[];
+    return rows[0] ? rowToProject(rows[0]) : null;
+  }
+
+  /**
+   * Create a project
+   */
+  async function createProject(
+    input: CreateProjectInput,
+    context: { projectId: string; organizationId: string }
+  ): Promise<Project> {
+    const id = generateId('proj');
+    const now = new Date().toISOString();
+
+    await db.execute(
+      `INSERT INTO saas_project (id, projectId, organizationId, name, description, status, tier, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        context.projectId,
+        context.organizationId,
+        input.name,
+        input.description ?? null,
+        'DRAFT',
+        input.tier ?? 'FREE',
+        now,
+        now,
+      ]
+    );
+
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [id])
+    ).rows as unknown as ProjectRow[];
+
+    return rowToProject(rows[0]!);
+  }
+
+  /**
+   * Update a project
+   */
+  async function updateProject(input: UpdateProjectInput): Promise<Project> {
+    const now = new Date().toISOString();
+    const updates: string[] = ['updatedAt = ?'];
+    const params: (string | null)[] = [now];
+
+    if (input.name !== undefined) {
+      updates.push('name = ?');
+      params.push(input.name);
+    }
+
+    if (input.description !== undefined) {
+      updates.push('description = ?');
+      params.push(input.description);
+    }
+
+    if (input.status !== undefined) {
+      updates.push('status = ?');
+      params.push(input.status);
+    }
+
+    params.push(input.id);
+
+    await db.execute(
+      `UPDATE saas_project SET ${updates.join(', ')} WHERE id = ?`,
+      params
+    );
+
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [input.id])
+    ).rows as unknown as ProjectRow[];
+
+    if (!rows[0]) {
+      throw new Error('NOT_FOUND');
+    }
+
+    return rowToProject(rows[0]);
+  }
+
+  /**
+   * Delete a project
+   */
+  async function deleteProject(id: string): Promise<void> {
+    await db.execute(`DELETE FROM saas_project WHERE id = ?`, [id]);
+  }
+
+  /**
+   * Get subscription for an organization
+   */
+  async function getSubscription(input: {
+    projectId: string;
+    organizationId?: string;
+  }): Promise<Subscription | null> {
+    let query = `SELECT * FROM saas_subscription WHERE projectId = ?`;
+    const params: string[] = [input.projectId];
+
+    if (input.organizationId) {
+      query += ' AND organizationId = ?';
+      params.push(input.organizationId);
+    }
+
+    query += ' LIMIT 1';
+
+    const rows = (await db.query(query, params))
+      .rows as unknown as SubscriptionRow[];
+    return rows[0] ? rowToSubscription(rows[0]) : null;
+  }
+
+  return {
+    listProjects,
+    getProject,
+    createProject,
+    updateProject,
+    deleteProject,
+    getSubscription,
+  };
+}
+
+export type SaasHandlers = ReturnType<typeof createSaasHandlers>;

package/src/index.ts

@@ -9,6 +9,11 @@ export * from './dashboard';
 
 // Export feature and example metadata
 export * from './saas-boilerplate.feature';
+export * from './ui';
+export {
+  createSaasHandlers,
+  type SaasHandlers,
+} from './handlers/saas.handlers';
 export { default as example } from './example';
 
 // Import docs for registration

package/src/project/project.presentation.ts

@@ -1,11 +1,10 @@
-import type { PresentationSpec } from '@contractspec/lib.contracts';
-import { StabilityEnum } from '@contractspec/lib.contracts';
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
 import { ProjectModel } from './project.schema';
 
 /**
  * Presentation for displaying a list of projects.
  */
-export const ProjectListPresentation: PresentationSpec = {
+export const ProjectListPresentation = definePresentation({
   meta: {
     key: 'saas.project.list',
     version: '1.0.0',
@@ -29,12 +28,12 @@ export const ProjectListPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.projects.enabled'],
   },
-};
+});
 
 /**
  * Presentation for project detail view.
  */
-export const ProjectDetailPresentation: PresentationSpec = {
+export const ProjectDetailPresentation = definePresentation({
   meta: {
     key: 'saas.project.detail',
     version: '1.0.0',
@@ -56,4 +55,4 @@ export const ProjectDetailPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.projects.enabled'],
   },
-};
+});

package/src/saas-boilerplate.feature.ts

@@ -3,13 +3,13 @@
  *
  * Defines the feature module for the SaaS application foundation.
  */
-import type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+import { defineFeature } from '@contractspec/lib.contracts';
 
 /**
  * SaaS Boilerplate feature module that bundles project management,
  * billing, and settings operations into an installable feature.
  */
-export const SaasBoilerplateFeature: FeatureModuleSpec = {
+export const SaasBoilerplateFeature = defineFeature({
   meta: {
     key: 'saas-boilerplate',
     title: 'SaaS Boilerplate',
@@ -110,4 +110,4 @@ export const SaasBoilerplateFeature: FeatureModuleSpec = {
       { key: 'notifications', version: '1.0.0' },
     ],
   },
-};
+});

package/src/seeders/index.ts

@@ -0,0 +1,28 @@
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+
+export async function seedSaasBoilerplate(params: {
+  projectId: string;
+  db: DatabasePort;
+}) {
+  const { projectId, db } = params;
+
+  const existing = await db.query(
+    `SELECT COUNT(*) as count FROM saas_project WHERE "projectId" = $1`,
+    [projectId]
+  );
+  if ((existing.rows[0]?.count as number) > 0) return;
+
+  await db.execute(
+    `INSERT INTO saas_project (id, "projectId", "organizationId", name, description, status, tier)
+     VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+    [
+      'saas_proj_1',
+      projectId,
+      'org_demo',
+      'Demo Project',
+      'A demo SaaS project',
+      'ACTIVE',
+      'PRO',
+    ]
+  );
+}

package/src/shared/overlay-types.ts

@@ -0,0 +1,39 @@
+export interface OverlayDefinition {
+  overlayId: string;
+  version: string;
+  description: string;
+  appliesTo: Record<string, string>;
+  modifications: OverlayModification[];
+}
+
+export type OverlayModification =
+  | HideFieldModification
+  | RenameLabelModification
+  | AddBadgeModification
+  | SetLimitModification;
+
+export interface HideFieldModification {
+  type: 'hideField';
+  field: string;
+  reason?: string;
+}
+
+export interface RenameLabelModification {
+  type: 'renameLabel';
+  field: string;
+  newLabel: string;
+}
+
+export interface AddBadgeModification {
+  type: 'addBadge';
+  position: 'header' | 'footer';
+  label: string;
+  variant: 'warning' | 'info' | 'error' | 'success' | 'default';
+}
+
+export interface SetLimitModification {
+  type: 'setLimit';
+  field: string;
+  max: number;
+  message: string;
+}