@contractspec/example.saas-boilerplate 1.46.0 → 1.47.0

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';

package/src/ui/hooks/useProjectList.ts

@@ -0,0 +1,95 @@
+/**
+ * Hook for fetching and managing project list data
+ *
+ * Uses runtime-local database-backed handlers.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';
+import type {
+  Project as RuntimeProject,
+  Subscription as RuntimeSubscription,
+  SaasHandlers,
+} from '../../handlers/saas.handlers';
+
+// Re-export types for convenience
+export type Project = RuntimeProject;
+export type Subscription = RuntimeSubscription;
+
+export interface ListProjectsOutput {
+  items: Project[];
+  total: number;
+}
+
+export interface UseProjectListOptions {
+  status?: 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'all';
+  search?: string;
+  limit?: number;
+}
+
+export function useProjectList(options: UseProjectListOptions = {}) {
+  const { handlers, projectId } = useTemplateRuntime<{ saas: SaasHandlers }>();
+  const { saas } = handlers;
+
+  const [data, setData] = useState<ListProjectsOutput | null>(null);
+  const [subscription, setSubscription] = useState<Subscription | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [page, setPage] = useState(1);
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const [projectsResult, subscriptionResult] = await Promise.all([
+        saas.listProjects({
+          projectId,
+          status: options.status === 'all' ? undefined : options.status,
+          search: options.search,
+          limit: options.limit ?? 20,
+          offset: (page - 1) * (options.limit ?? 20),
+        }),
+        saas.getSubscription({ projectId }),
+      ]);
+      setData({
+        items: projectsResult.items,
+        total: projectsResult.total,
+      });
+      setSubscription(subscriptionResult);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Unknown error'));
+    } finally {
+      setLoading(false);
+    }
+  }, [saas, projectId, options.status, options.search, options.limit, page]);
+
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  // Calculate stats
+  const stats = useMemo(() => {
+    if (!data) return null;
+    const items = data.items;
+    return {
+      total: data.total,
+      activeCount: items.filter((p) => p.status === 'ACTIVE').length,
+      draftCount: items.filter((p) => p.status === 'DRAFT').length,
+      // Subscription stats are optional since they may not be seeded
+      projectLimit: 10, // Default limit for demo
+      usagePercent: Math.min((data.total / 10) * 100, 100),
+    };
+  }, [data]);
+
+  return {
+    data,
+    subscription,
+    loading,
+    error,
+    stats,
+    page,
+    refetch: fetchData,
+    nextPage: () => setPage((p) => p + 1),
+    prevPage: () => page > 1 && setPage((p) => p - 1),
+  };
+}