@contractspec/example.saas-boilerplate 1.46.1 → 1.48.0

package/src/tests/operations.test-spec.ts

@@ -0,0 +1,109 @@
+import { defineTestSpec } from '@contractspec/lib.contracts';
+
+export const ProjectListTest = defineTestSpec({
+  meta: {
+    key: 'saas.project.list.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for listing projects',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.project.list', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.project.list' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.project.list' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const ProjectGetTest = defineTestSpec({
+  meta: {
+    key: 'saas.project.get.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for getting project',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.project.get', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.project.get' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.project.get' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const BillingSubscriptionGetTest = defineTestSpec({
+  meta: {
+    key: 'saas.billing.subscription.get.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for getting subscription',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.billing.subscription.get', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.billing.subscription.get' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.billing.subscription.get' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const BillingUsageSummaryTest = defineTestSpec({
+  meta: {
+    key: 'saas.billing.usage.summary.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for getting usage summary',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.billing.usage.summary', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.billing.usage.summary' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.billing.usage.summary' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});

package/src/ui/SaasDashboard.tsx

@@ -0,0 +1,325 @@
+'use client';
+
+/**
+ * SaaS Dashboard
+ *
+ * Fully integrated with ContractSpec example handlers
+ * and design-system components.
+ *
+ * Commands wired:
+ * - CreateProjectContract -> Create Project button + modal
+ * - UpdateProjectContract -> Edit project via modal
+ * - DeleteProjectContract -> Delete project via modal
+ */
+import { useState, useCallback } from 'react';
+import {
+  StatCard,
+  StatCardGroup,
+  StatusChip,
+  EntityCard,
+  EmptyState,
+  LoaderBlock,
+  ErrorState,
+  Button,
+} from '@contractspec/lib.design-system';
+import {
+  useProjectList,
+  type Project,
+  type Subscription,
+} from './hooks/useProjectList';
+import { useProjectMutations } from './hooks/useProjectMutations';
+import { CreateProjectModal } from './modals/CreateProjectModal';
+import { ProjectActionsModal } from './modals/ProjectActionsModal';
+
+type Tab = 'projects' | 'billing' | 'settings';
+
+function getStatusTone(
+  status: Project['status']
+): 'success' | 'warning' | 'neutral' | 'danger' {
+  switch (status) {
+    case 'ACTIVE':
+      return 'success';
+    case 'DRAFT':
+      return 'neutral';
+    case 'ARCHIVED':
+      return 'warning';
+    default:
+      return 'neutral';
+  }
+}
+
+export function SaasDashboard() {
+  const [activeTab, setActiveTab] = useState<Tab>('projects');
+  const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);
+  const [selectedProject, setSelectedProject] = useState<Project | null>(null);
+  const [isProjectActionsOpen, setIsProjectActionsOpen] = useState(false);
+
+  const { data, subscription, loading, error, stats, refetch } =
+    useProjectList();
+
+  const mutations = useProjectMutations({
+    onSuccess: () => {
+      refetch();
+    },
+  });
+
+  const handleProjectClick = useCallback((project: Project) => {
+    setSelectedProject(project);
+    setIsProjectActionsOpen(true);
+  }, []);
+
+  const tabs: { id: Tab; label: string; icon: string }[] = [
+    { id: 'projects', label: 'Projects', icon: '📁' },
+    { id: 'billing', label: 'Billing', icon: '💳' },
+    { id: 'settings', label: 'Settings', icon: '⚙️' },
+  ];
+
+  if (loading && !data) {
+    return <LoaderBlock label="Loading dashboard..." />;
+  }
+
+  if (error) {
+    return (
+      <ErrorState
+        title="Failed to load dashboard"
+        description={error.message}
+        onRetry={refetch}
+        retryLabel="Retry"
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <h2 className="text-2xl font-bold">SaaS Dashboard</h2>
+        {activeTab === 'projects' && (
+          <Button onPress={() => setIsCreateModalOpen(true)}>
+            <span className="mr-2">+</span> New Project
+          </Button>
+        )}
+      </div>
+
+      {/* Stats Row */}
+      {stats && subscription && (
+        <StatCardGroup>
+          <StatCard label="Projects" value={stats.total.toString()} />
+          <StatCard label="Active" value={stats.activeCount.toString()} />
+          <StatCard label="Draft" value={stats.draftCount.toString()} />
+          <StatCard
+            label="Plan"
+            value={subscription.plan}
+            hint={subscription.status}
+          />
+        </StatCardGroup>
+      )}
+
+      {/* Navigation Tabs */}
+      <nav className="bg-muted flex gap-1 rounded-lg p-1" role="tablist">
+        {tabs.map((tab) => (
+          <button
+            key={tab.id}
+            type="button"
+            role="tab"
+            aria-selected={activeTab === tab.id}
+            onClick={() => setActiveTab(tab.id)}
+            className={`flex flex-1 items-center justify-center gap-2 rounded-md px-4 py-2 text-sm font-medium transition-colors ${
+              activeTab === tab.id
+                ? 'bg-background text-foreground shadow-sm'
+                : 'text-muted-foreground hover:text-foreground'
+            }`}
+          >
+            <span>{tab.icon}</span>
+            {tab.label}
+          </button>
+        ))}
+      </nav>
+
+      {/* Tab Content */}
+      <div className="min-h-[400px]" role="tabpanel">
+        {activeTab === 'projects' && (
+          <ProjectsTab data={data} onProjectClick={handleProjectClick} />
+        )}
+        {activeTab === 'billing' && <BillingTab subscription={subscription} />}
+        {activeTab === 'settings' && <SettingsTab />}
+      </div>
+
+      {/* Create Project Modal */}
+      <CreateProjectModal
+        isOpen={isCreateModalOpen}
+        onClose={() => setIsCreateModalOpen(false)}
+        onSubmit={async (input) => {
+          await mutations.createProject(input);
+        }}
+        isLoading={mutations.createState.loading}
+      />
+
+      {/* Project Actions Modal */}
+      <ProjectActionsModal
+        isOpen={isProjectActionsOpen}
+        project={selectedProject}
+        onClose={() => {
+          setIsProjectActionsOpen(false);
+          setSelectedProject(null);
+        }}
+        onUpdate={async (input) => {
+          await mutations.updateProject(input);
+        }}
+        onArchive={async (projectId) => {
+          await mutations.archiveProject(projectId);
+        }}
+        onActivate={async (projectId) => {
+          await mutations.activateProject(projectId);
+        }}
+        onDelete={async (projectId) => {
+          await mutations.deleteProject(projectId);
+        }}
+        isLoading={mutations.isLoading}
+      />
+    </div>
+  );
+}
+
+interface ProjectsTabProps {
+  data: ReturnType<typeof useProjectList>['data'];
+  onProjectClick?: (project: Project) => void;
+}
+
+function ProjectsTab({ data, onProjectClick }: ProjectsTabProps) {
+  if (!data?.items.length) {
+    return (
+      <EmptyState
+        title="No projects yet"
+        description="Create your first project to get started."
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+        {data.items.map((project: Project) => (
+          <EntityCard
+            key={project.id}
+            cardTitle={project.name}
+            cardSubtitle={project.tier}
+            meta={
+              <p className="text-muted-foreground text-sm">
+                {project.description}
+              </p>
+            }
+            chips={
+              <StatusChip
+                tone={getStatusTone(project.status)}
+                label={project.status}
+              />
+            }
+            footer={
+              <div className="flex w-full items-center justify-between">
+                <span className="text-muted-foreground text-xs">
+                  {project.updatedAt.toLocaleDateString()}
+                </span>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onPress={() => onProjectClick?.(project)}
+                >
+                  Actions
+                </Button>
+              </div>
+            }
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function BillingTab({ subscription }: { subscription: Subscription | null }) {
+  if (!subscription) return null;
+
+  return (
+    <div className="space-y-6">
+      <div className="border-border bg-card rounded-xl border p-6">
+        <div className="flex items-start justify-between">
+          <div>
+            <h3 className="text-lg font-semibold">{subscription.plan} Plan</h3>
+            <p className="text-muted-foreground text-sm">
+              Current period:{' '}
+              {subscription.currentPeriodStart.toLocaleDateString()} -{' '}
+              {subscription.currentPeriodEnd.toLocaleDateString()}
+            </p>
+            <p className="text-muted-foreground text-sm">
+              Billing cycle: {subscription.billingCycle}
+            </p>
+          </div>
+          <StatusChip tone="success" label={subscription.status} />
+        </div>
+
+        <div className="mt-4 flex gap-3">
+          <Button variant="outline" onPress={() => alert('Upgrade clicked!')}>
+            Upgrade Plan
+          </Button>
+          <Button
+            variant="ghost"
+            onPress={() => alert('Manage Billing clicked!')}
+          >
+            Manage Billing
+          </Button>
+        </div>
+      </div>
+
+      {subscription.cancelAtPeriodEnd && (
+        <div className="border-border bg-destructive/10 text-destructive rounded-xl border p-4">
+          <p className="text-sm font-medium">
+            ⚠️ Your subscription will be cancelled at the end of the current
+            period.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function SettingsTab() {
+  return (
+    <div className="space-y-6">
+      <div className="border-border bg-card rounded-xl border p-6">
+        <h3 className="mb-4 text-lg font-semibold">Organization Settings</h3>
+        <div className="space-y-4">
+          <div>
+            <label htmlFor="org-name" className="text-sm font-medium">
+              Organization Name
+            </label>
+            <input
+              id="org-name"
+              type="text"
+              defaultValue="Demo Organization"
+              className="border-input bg-background mt-1 block w-full rounded-md border px-3 py-2"
+            />
+          </div>
+          <div>
+            <label htmlFor="timezone" className="text-sm font-medium">
+              Default Timezone
+            </label>
+            <select
+              id="timezone"
+              className="border-input bg-background mt-1 block w-full rounded-md border px-3 py-2"
+            >
+              <option>UTC</option>
+              <option>America/New_York</option>
+              <option>Europe/London</option>
+              <option>Asia/Tokyo</option>
+            </select>
+          </div>
+          <div className="pt-2">
+            <Button onPress={() => alert('Settings saved!')}>
+              Save Settings
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/ui/SaasProjectList.tsx

@@ -0,0 +1,113 @@
+'use client';
+
+/**
+ * SaaS Project List - Standalone project list component
+ */
+import {
+  StatCard,
+  StatCardGroup,
+  StatusChip,
+  EntityCard,
+  EmptyState,
+  LoaderBlock,
+  ErrorState,
+  Button,
+} from '@contractspec/lib.design-system';
+import { useProjectList, type Project } from './hooks/useProjectList';
+
+interface SaasProjectListProps {
+  onProjectClick?: (projectId: string) => void;
+  onCreateProject?: () => void;
+}
+
+function getStatusTone(
+  status: Project['status']
+): 'success' | 'warning' | 'neutral' | 'danger' {
+  switch (status) {
+    case 'ACTIVE':
+      return 'success';
+    case 'DRAFT':
+      return 'neutral';
+    case 'ARCHIVED':
+      return 'danger';
+    default:
+      return 'neutral';
+  }
+}
+
+export function SaasProjectList({
+  onProjectClick,
+  onCreateProject,
+}: SaasProjectListProps) {
+  const { data, loading, error, stats, refetch } = useProjectList();
+
+  if (loading && !data) {
+    return <LoaderBlock label="Loading projects..." />;
+  }
+
+  if (error) {
+    return (
+      <ErrorState
+        title="Failed to load projects"
+        description={error.message}
+        onRetry={refetch}
+        retryLabel="Retry"
+      />
+    );
+  }
+
+  if (!data?.items.length) {
+    return (
+      <EmptyState
+        title="No projects found"
+        description="Create your first project to get started."
+        primaryAction={
+          onCreateProject ? (
+            <Button onPress={onCreateProject}>Create Project</Button>
+          ) : undefined
+        }
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      {stats && (
+        <StatCardGroup>
+          <StatCard label="Total Projects" value={stats.total.toString()} />
+          <StatCard label="Active" value={stats.activeCount.toString()} />
+          <StatCard label="Draft" value={stats.draftCount.toString()} />
+        </StatCardGroup>
+      )}
+
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+        {data.items.map((project: Project) => (
+          <EntityCard
+            key={project.id}
+            cardTitle={project.name}
+            cardSubtitle={project.tier}
+            meta={
+              <p className="text-muted-foreground text-sm">
+                {project.description}
+              </p>
+            }
+            chips={
+              <StatusChip
+                tone={getStatusTone(project.status)}
+                label={project.status}
+              />
+            }
+            footer={
+              <span className="text-muted-foreground text-xs">
+                {project.updatedAt.toLocaleDateString()}
+              </span>
+            }
+            onClick={
+              onProjectClick ? () => onProjectClick(project.id) : undefined
+            }
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/ui/SaasSettingsPanel.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+/**
+ * SaaS Settings Panel - Organization and user settings
+ */
+import { useState } from 'react';
+import { Button } from '@contractspec/lib.design-system';
+
+export function SaasSettingsPanel() {
+  const [orgName, setOrgName] = useState('Demo Organization');
+  const [timezone, setTimezone] = useState('UTC');
+
+  return (
+    <div className="space-y-6">
+      <div className="border-border bg-card rounded-xl border p-6">
+        <h3 className="mb-4 text-lg font-semibold">Organization Settings</h3>
+        <div className="space-y-4">
+          <div>
+            <label
+              htmlFor="setting-org-name"
+              className="block text-sm font-medium"
+            >
+              Organization Name
+            </label>
+            <input
+              id="setting-org-name"
+              type="text"
+              value={orgName}
+              onChange={(e) => setOrgName(e.target.value)}
+              className="border-input bg-background mt-1 block w-full rounded-md border px-3 py-2"
+            />
+          </div>
+          <div>
+            <label
+              htmlFor="setting-timezone"
+              className="block text-sm font-medium"
+            >
+              Default Timezone
+            </label>
+            <select
+              id="setting-timezone"
+              value={timezone}
+              onChange={(e) => setTimezone(e.target.value)}
+              className="border-input bg-background mt-1 block w-full rounded-md border px-3 py-2"
+            >
+              <option value="UTC">UTC</option>
+              <option value="America/New_York">America/New_York</option>
+              <option value="Europe/London">Europe/London</option>
+              <option value="Asia/Tokyo">Asia/Tokyo</option>
+            </select>
+          </div>
+        </div>
+        <div className="mt-6">
+          <Button variant="default">Save Changes</Button>
+        </div>
+      </div>
+
+      <div className="border-border bg-card rounded-xl border p-6">
+        <h3 className="mb-4 text-lg font-semibold">Notifications</h3>
+        <div className="space-y-3">
+          {[
+            { label: 'Email notifications', defaultChecked: true },
+            { label: 'Usage alerts', defaultChecked: true },
+            { label: 'Weekly digest', defaultChecked: false },
+          ].map((item) => (
+            <label key={item.label} className="flex items-center gap-3">
+              <input
+                type="checkbox"
+                defaultChecked={item.defaultChecked}
+                className="border-input h-4 w-4 rounded"
+              />
+              <span className="text-sm">{item.label}</span>
+            </label>
+          ))}
+        </div>
+      </div>
+
+      <div className="rounded-xl border border-red-200 bg-red-50 p-6 dark:border-red-900 dark:bg-red-950/20">
+        <h3 className="mb-2 text-lg font-semibold text-red-700 dark:text-red-400">
+          Danger Zone
+        </h3>
+        <p className="mb-4 text-sm text-red-600 dark:text-red-300">
+          These actions are irreversible. Please proceed with caution.
+        </p>
+        <div className="flex gap-3">
+          <Button variant="secondary" size="sm">
+            Export Data
+          </Button>
+          <Button variant="secondary" size="sm">
+            Delete Organization
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/ui/hooks/index.ts

@@ -0,0 +1,10 @@
+'use client';
+
+export { useProjectList, type UseProjectListOptions } from './useProjectList';
+export {
+  useProjectMutations,
+  type UseProjectMutationsOptions,
+} from './useProjectMutations';
+
+// Note: For project types (CreateProjectInput, UpdateProjectInput, Project), import directly from:
+// import type { Project, CreateProjectInput, etc. } from '@contractspec/example.saas-boilerplate/handlers';