@contractspec/example.saas-boilerplate 0.0.0-canary-20260113170453

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),
+  };
+}

package/src/ui/hooks/useProjectMutations.ts

@@ -0,0 +1,166 @@
+/**
+ * Hook for SaaS project mutations (commands)
+ *
+ * Uses runtime-local database-backed handlers for:
+ * - CreateProjectContract
+ * - UpdateProjectContract
+ * - DeleteProjectContract
+ */
+import { useCallback, useState } from 'react';
+import { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';
+import type {
+  CreateProjectInput,
+  Project,
+  UpdateProjectInput,
+  SaasHandlers,
+} from '../../handlers/saas.handlers';
+
+export interface MutationState<T> {
+  loading: boolean;
+  error: Error | null;
+  data: T | null;
+}
+
+export interface UseProjectMutationsOptions {
+  onSuccess?: () => void;
+  onError?: (error: Error) => void;
+}
+
+export function useProjectMutations(options: UseProjectMutationsOptions = {}) {
+  const { handlers, projectId } = useTemplateRuntime<{ saas: SaasHandlers }>();
+  const { saas } = handlers;
+
+  const [createState, setCreateState] = useState<MutationState<Project>>({
+    loading: false,
+    error: null,
+    data: null,
+  });
+
+  const [updateState, setUpdateState] = useState<MutationState<Project>>({
+    loading: false,
+    error: null,
+    data: null,
+  });
+
+  const [deleteState, setDeleteState] = useState<
+    MutationState<{ success: boolean }>
+  >({
+    loading: false,
+    error: null,
+    data: null,
+  });
+
+  /**
+   * Create a new project
+   */
+  const createProject = useCallback(
+    async (input: CreateProjectInput): Promise<Project | null> => {
+      setCreateState({ loading: true, error: null, data: null });
+      try {
+        const result = await saas.createProject(input, {
+          projectId,
+          organizationId: 'demo-org',
+        });
+        setCreateState({ loading: false, error: null, data: result });
+        options.onSuccess?.();
+        return result;
+      } catch (err) {
+        const error =
+          err instanceof Error ? err : new Error('Failed to create project');
+        setCreateState({ loading: false, error, data: null });
+        options.onError?.(error);
+        return null;
+      }
+    },
+    [saas, projectId, options]
+  );
+
+  /**
+   * Update a project
+   */
+  const updateProject = useCallback(
+    async (input: UpdateProjectInput): Promise<Project | null> => {
+      setUpdateState({ loading: true, error: null, data: null });
+      try {
+        const result = await saas.updateProject(input);
+        setUpdateState({ loading: false, error: null, data: result });
+        options.onSuccess?.();
+        return result;
+      } catch (err) {
+        const error =
+          err instanceof Error ? err : new Error('Failed to update project');
+        setUpdateState({ loading: false, error, data: null });
+        options.onError?.(error);
+        return null;
+      }
+    },
+    [saas, options]
+  );
+
+  /**
+   * Delete a project (soft delete)
+   */
+  const deleteProject = useCallback(
+    async (id: string): Promise<boolean> => {
+      setDeleteState({ loading: true, error: null, data: null });
+      try {
+        await saas.deleteProject(id);
+        setDeleteState({
+          loading: false,
+          error: null,
+          data: { success: true },
+        });
+        options.onSuccess?.();
+        return true;
+      } catch (err) {
+        const error =
+          err instanceof Error ? err : new Error('Failed to delete project');
+        setDeleteState({ loading: false, error, data: null });
+        options.onError?.(error);
+        return false;
+      }
+    },
+    [saas, options]
+  );
+
+  /**
+   * Archive a project (status change)
+   */
+  const archiveProject = useCallback(
+    async (id: string): Promise<Project | null> => {
+      return updateProject({ id, status: 'ARCHIVED' });
+    },
+    [updateProject]
+  );
+
+  /**
+   * Activate a project (status change)
+   */
+  const activateProject = useCallback(
+    async (id: string): Promise<Project | null> => {
+      return updateProject({ id, status: 'ACTIVE' });
+    },
+    [updateProject]
+  );
+
+  return {
+    // Mutations
+    createProject,
+    updateProject,
+    deleteProject,
+    archiveProject,
+    activateProject,
+
+    // State
+    createState,
+    updateState,
+    deleteState,
+
+    // Convenience
+    isLoading:
+      createState.loading || updateState.loading || deleteState.loading,
+  };
+}
+
+// Note: Types are re-exported from the handlers package
+// Consumers should import types directly from '@contractspec/example.saas-boilerplate/handlers'

package/src/ui/index.ts

@@ -0,0 +1,18 @@
+// Main dashboard
+export * from './SaasDashboard';
+
+// Standalone components
+export * from './SaasProjectList';
+export * from './SaasSettingsPanel';
+
+// Modals
+export * from './modals';
+
+// Hooks
+export * from './hooks';
+
+// Renderers
+export * from './renderers';
+
+// Overlays
+export * from './overlays';

package/src/ui/modals/CreateProjectModal.tsx

@@ -0,0 +1,176 @@
+'use client';
+
+/**
+ * CreateProjectModal - Form for creating a new project
+ *
+ * Wires to CreateProjectContract via useProjectMutations hook.
+ */
+import { useState } from 'react';
+import { Button, Input } from '@contractspec/lib.design-system';
+
+// Local type definition for modal props
+export interface CreateProjectInput {
+  name: string;
+  description?: string;
+  tier: 'FREE' | 'PRO' | 'ENTERPRISE';
+}
+
+interface CreateProjectModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onSubmit: (input: CreateProjectInput) => Promise<void>;
+  isLoading?: boolean;
+}
+
+const TIERS: { value: CreateProjectInput['tier']; label: string }[] = [
+  { value: 'FREE', label: 'Free' },
+  { value: 'PRO', label: 'Pro' },
+  { value: 'ENTERPRISE', label: 'Enterprise' },
+];
+
+export function CreateProjectModal({
+  isOpen,
+  onClose,
+  onSubmit,
+  isLoading = false,
+}: CreateProjectModalProps) {
+  const [name, setName] = useState('');
+  const [description, setDescription] = useState('');
+  const [tier, setTier] = useState<CreateProjectInput['tier']>('FREE');
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError(null);
+
+    // Validation
+    if (!name.trim()) {
+      setError('Project name is required');
+      return;
+    }
+
+    try {
+      await onSubmit({
+        name: name.trim(),
+        description: description.trim() || undefined,
+        tier,
+      });
+
+      // Reset form
+      setName('');
+      setDescription('');
+      setTier('FREE');
+      onClose();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to create project');
+    }
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      {/* Backdrop */}
+      <div
+        className="bg-background/80 absolute inset-0 backdrop-blur-sm"
+        onClick={onClose}
+        role="button"
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') onClose();
+        }}
+        aria-label="Close modal"
+      />
+
+      {/* Modal */}
+      <div className="bg-card border-border relative z-10 w-full max-w-md rounded-xl border p-6 shadow-xl">
+        <h2 className="mb-4 text-xl font-semibold">Create New Project</h2>
+
+        <form onSubmit={handleSubmit} className="space-y-4">
+          {/* Project Name */}
+          <div>
+            <label
+              htmlFor="project-name"
+              className="text-muted-foreground mb-1 block text-sm font-medium"
+            >
+              Project Name *
+            </label>
+            <Input
+              id="project-name"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              placeholder="e.g., My Awesome Project"
+              disabled={isLoading}
+            />
+          </div>
+
+          {/* Description */}
+          <div>
+            <label
+              htmlFor="project-description"
+              className="text-muted-foreground mb-1 block text-sm font-medium"
+            >
+              Description
+            </label>
+            <textarea
+              id="project-description"
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              placeholder="Describe what this project is about..."
+              rows={3}
+              disabled={isLoading}
+              className="border-input bg-background focus:ring-ring w-full rounded-md border px-3 py-2 text-sm focus:ring-2 focus:outline-none disabled:opacity-50"
+            />
+          </div>
+
+          {/* Tier */}
+          <div>
+            <label
+              htmlFor="project-tier"
+              className="text-muted-foreground mb-1 block text-sm font-medium"
+            >
+              Tier
+            </label>
+            <select
+              id="project-tier"
+              value={tier}
+              onChange={(e) =>
+                setTier(e.target.value as CreateProjectInput['tier'])
+              }
+              disabled={isLoading}
+              className="border-input bg-background focus:ring-ring h-10 w-full rounded-md border px-3 py-2 text-sm focus:ring-2 focus:outline-none disabled:opacity-50"
+            >
+              {TIERS.map((t) => (
+                <option key={t.value} value={t.value}>
+                  {t.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {/* Error Message */}
+          {error && (
+            <div className="bg-destructive/10 text-destructive rounded-md p-3 text-sm">
+              {error}
+            </div>
+          )}
+
+          {/* Actions */}
+          <div className="flex justify-end gap-3 pt-2">
+            <Button
+              type="button"
+              variant="ghost"
+              onPress={onClose}
+              disabled={isLoading}
+            >
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isLoading}>
+              {isLoading ? 'Creating...' : 'Create Project'}
+            </Button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}