@contractspec/example.saas-boilerplate 1.46.0 → 1.47.0

package/src/ui/overlays/demo-overlays.ts

@@ -0,0 +1,74 @@
+/**
+ * Demo Overlay Definitions for SaaS Boilerplate
+ *
+ * These overlays customize the presentation for different contexts
+ * (e.g., demo users, different subscription tiers).
+ */
+import type { OverlayDefinition } from '../../shared/overlay-types';
+
+/**
+ * Free tier overlay - shows upgrade prompts and limits
+ */
+export const saasFreeUserOverlay: OverlayDefinition = {
+  overlayId: 'saas-boilerplate.free-tier',
+  version: '1.0.0',
+  description: 'Shows limitations for free tier users',
+  appliesTo: {
+    feature: 'saas-boilerplate',
+    tier: 'free',
+  },
+  modifications: [
+    {
+      type: 'setLimit',
+      field: 'projects',
+      max: 3,
+      message: 'Upgrade to create more projects',
+    },
+    { type: 'hideField', field: 'advancedSettings', reason: 'Pro feature' },
+    {
+      type: 'addBadge',
+      position: 'header',
+      label: 'Free Plan',
+      variant: 'default',
+    },
+  ],
+};
+
+/**
+ * Demo user overlay
+ */
+export const saasDemoOverlay: OverlayDefinition = {
+  overlayId: 'saas-boilerplate.demo-user',
+  version: '1.0.0',
+  description: 'Demo mode for SaaS boilerplate',
+  appliesTo: {
+    feature: 'saas-boilerplate',
+    role: 'demo',
+  },
+  modifications: [
+    {
+      type: 'hideField',
+      field: 'billingSection',
+      reason: 'Demo users cannot access billing',
+    },
+    {
+      type: 'hideField',
+      field: 'deleteAccount',
+      reason: 'Not available in demo',
+    },
+    {
+      type: 'addBadge',
+      position: 'header',
+      label: 'Demo Mode',
+      variant: 'warning',
+    },
+  ],
+};
+
+/**
+ * All overlays for saas-boilerplate
+ */
+export const saasOverlays: OverlayDefinition[] = [
+  saasFreeUserOverlay,
+  saasDemoOverlay,
+];

package/src/ui/overlays/index.ts

@@ -0,0 +1 @@
+export * from './demo-overlays';

package/src/ui/renderers/index.ts

@@ -0,0 +1,7 @@
+// SaaS renderers
+export { projectListReactRenderer } from './project-list.renderer';
+export {
+  projectListMarkdownRenderer,
+  saasDashboardMarkdownRenderer,
+  saasBillingMarkdownRenderer,
+} from './project-list.markdown';

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

@@ -0,0 +1,239 @@
+/**
+ * Markdown renderer for SaaS Project List presentation
+ *
+ * Uses dynamic import to ensure correct build order.
+ */
+import type { PresentationRenderer } from '@contractspec/lib.contracts';
+import {
+  mockListProjectsHandler,
+  mockGetSubscriptionHandler,
+} from '@contractspec/example.saas-boilerplate/handlers';
+
+interface ProjectItem {
+  id: string;
+  name: string;
+  status: string;
+  description?: string;
+}
+
+/**
+ * Markdown renderer for saas-boilerplate.project.list presentation
+ * Only handles ProjectListView component
+ */
+export const projectListMarkdownRenderer: PresentationRenderer<{
+  mimeType: string;
+  body: string;
+}> = {
+  target: 'markdown',
+  render: async (desc, _ctx) => {
+    // Only handle ProjectListView
+    if (
+      desc.source.type !== 'component' ||
+      desc.source.componentKey !== 'ProjectListView'
+    ) {
+      throw new Error('projectListMarkdownRenderer: not ProjectListView');
+    }
+
+    const data = await mockListProjectsHandler({
+      limit: 20,
+      offset: 0,
+    });
+
+    // The example handler returns 'projects', not 'items'
+    const items =
+      (data as { projects?: ProjectItem[]; items?: ProjectItem[] }).projects ??
+      (data as { items?: ProjectItem[] }).items ??
+      [];
+
+    const lines: string[] = [
+      '# Projects',
+      '',
+      `**Total**: ${data.total} projects`,
+      '',
+    ];
+
+    if (items.length === 0) {
+      lines.push('_No projects found._');
+    } else {
+      lines.push('| Status | Project | Description |');
+      lines.push('|--------|---------|-------------|');
+      for (const project of items) {
+        const status =
+          project.status === 'ACTIVE'
+            ? '✅'
+            : project.status === 'ARCHIVED'
+              ? '📦'
+              : '⏸️';
+        lines.push(
+          `| ${status} | **${project.name}** | ${project.description ?? '-'} |`
+        );
+      }
+    }
+
+    return {
+      mimeType: 'text/markdown',
+      body: lines.join('\n'),
+    };
+  },
+};
+
+/**
+ * Markdown renderer for saas-boilerplate.dashboard presentation
+ * Only handles SaasDashboard component
+ */
+export const saasDashboardMarkdownRenderer: PresentationRenderer<{
+  mimeType: string;
+  body: string;
+}> = {
+  target: 'markdown',
+  render: async (desc, _ctx) => {
+    // Only handle SaasDashboard
+    if (
+      desc.source.type !== 'component' ||
+      desc.source.componentKey !== 'SaasDashboard'
+    ) {
+      throw new Error('saasDashboardMarkdownRenderer: not SaasDashboard');
+    }
+
+    const [projectsData, subscription] = await Promise.all([
+      mockListProjectsHandler({ limit: 50 }),
+      mockGetSubscriptionHandler(),
+    ]);
+
+    const projects =
+      (projectsData as { projects?: ProjectItem[] }).projects ?? [];
+    const activeProjects = projects.filter((p) => p.status === 'ACTIVE').length;
+    const archivedProjects = projects.filter(
+      (p) => p.status === 'ARCHIVED'
+    ).length;
+
+    const lines: string[] = [
+      '# SaaS Dashboard',
+      '',
+      '> Organization overview and usage summary',
+      '',
+      '## Summary',
+      '',
+      '| Metric | Value |',
+      '|--------|-------|',
+      `| Total Projects | ${projectsData.total} |`,
+      `| Active Projects | ${activeProjects} |`,
+      `| Archived Projects | ${archivedProjects} |`,
+      `| Subscription Plan | ${subscription.planName} |`,
+      `| Subscription Status | ${subscription.status} |`,
+      '',
+      '## Projects',
+      '',
+    ];
+
+    if (projects.length === 0) {
+      lines.push('_No projects yet._');
+    } else {
+      lines.push('| Status | Project | Description |');
+      lines.push('|--------|---------|-------------|');
+      for (const project of projects.slice(0, 10)) {
+        const status =
+          project.status === 'ACTIVE'
+            ? '✅'
+            : project.status === 'ARCHIVED'
+              ? '📦'
+              : '⏸️';
+        lines.push(
+          `| ${status} | **${project.name}** | ${project.description ?? '-'} |`
+        );
+      }
+      if (projects.length > 10) {
+        lines.push(
+          `| ... | ... | _${projectsData.total - 10} more projects_ |`
+        );
+      }
+    }
+
+    lines.push('');
+    lines.push('## Subscription');
+    lines.push('');
+    lines.push(`- **Plan**: ${subscription.planName}`);
+    lines.push(`- **Status**: ${subscription.status}`);
+    if (subscription.currentPeriodEnd) {
+      lines.push(
+        `- **Period End**: ${new Date(subscription.currentPeriodEnd).toLocaleDateString()}`
+      );
+    }
+
+    return {
+      mimeType: 'text/markdown',
+      body: lines.join('\n'),
+    };
+  },
+};
+
+/**
+ * Markdown renderer for saas-boilerplate.billing.settings presentation
+ * Only handles SubscriptionView component
+ */
+export const saasBillingMarkdownRenderer: PresentationRenderer<{
+  mimeType: string;
+  body: string;
+}> = {
+  target: 'markdown',
+  render: async (desc, _ctx) => {
+    // Only handle SubscriptionView
+    if (
+      desc.source.type !== 'component' ||
+      desc.source.componentKey !== 'SubscriptionView'
+    ) {
+      throw new Error('saasBillingMarkdownRenderer: not SubscriptionView');
+    }
+
+    const subscription = await mockGetSubscriptionHandler();
+
+    const lines: string[] = [
+      '# Billing & Subscription',
+      '',
+      '> Current subscription details and billing information',
+      '',
+      '## Subscription Details',
+      '',
+      '| Property | Value |',
+      '|----------|-------|',
+      `| Plan | ${subscription.planName} |`,
+      `| Status | ${subscription.status} |`,
+      `| ID | ${subscription.id} |`,
+      `| Period Start | ${new Date(subscription.currentPeriodStart).toLocaleDateString()} |`,
+      `| Period End | ${new Date(subscription.currentPeriodEnd).toLocaleDateString()} |`,
+    ];
+
+    lines.push('');
+    lines.push('## Plan Limits');
+    lines.push('');
+    lines.push(`- **Projects**: ${subscription.limits.projects}`);
+    lines.push(`- **Users**: ${subscription.limits.users}`);
+
+    lines.push('');
+    lines.push('## Plan Features');
+    lines.push('');
+
+    if (subscription.planName.toLowerCase().includes('free')) {
+      lines.push('- ✅ Up to 3 projects');
+      lines.push('- ✅ Basic support');
+      lines.push('- ❌ Priority support');
+      lines.push('- ❌ Advanced analytics');
+    } else if (subscription.planName.toLowerCase().includes('pro')) {
+      lines.push('- ✅ Unlimited projects');
+      lines.push('- ✅ Priority support');
+      lines.push('- ✅ Advanced analytics');
+      lines.push('- ❌ Custom integrations');
+    } else {
+      lines.push('- ✅ Unlimited projects');
+      lines.push('- ✅ Priority support');
+      lines.push('- ✅ Advanced analytics');
+      lines.push('- ✅ Custom integrations');
+      lines.push('- ✅ Dedicated support');
+    }
+
+    return {
+      mimeType: 'text/markdown',
+      body: lines.join('\n'),
+    };
+  },
+};

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

@@ -0,0 +1,22 @@
+/**
+ * React renderer for SaaS Project List presentation
+ */
+import * as React from 'react';
+import type { PresentationRenderer } from '@contractspec/lib.contracts';
+import { SaasProjectList } from '../SaasProjectList';
+
+export const projectListReactRenderer: PresentationRenderer<React.ReactElement> =
+  {
+    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 <SaasProjectList />;
+    },
+  };

package/tsconfig.json

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