@contractspec/lib.example-shared-ui 0.0.0-canary-20260113170453

package/src/lib/component-registry.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import React, { useState, useEffect } from 'react';
+import type { TemplateId } from './types';
+
+export interface TemplateComponentRegistration {
+  list: React.ComponentType<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+  detail: React.ComponentType<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+  form?: React.ComponentType<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+}
+
+export class TemplateComponentRegistry {
+  private readonly components = new Map<
+    TemplateId,
+    TemplateComponentRegistration
+  >();
+  private readonly listeners = new Set<(templateId: TemplateId) => void>();
+
+  register(
+    templateId: TemplateId,
+    registration: TemplateComponentRegistration
+  ) {
+    this.components.set(templateId, registration);
+    this.listeners.forEach((l) => l(templateId));
+  }
+
+  get(templateId: TemplateId) {
+    return this.components.get(templateId);
+  }
+
+  subscribe(listener: (templateId: TemplateId) => void) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+}
+
+export const templateComponentRegistry = new TemplateComponentRegistry();
+
+export function registerTemplateComponents(
+  templateId: TemplateId,
+  components: TemplateComponentRegistration
+) {
+  templateComponentRegistry.register(templateId, components);
+}
+
+export function useTemplateComponents(
+  templateId: TemplateId
+): TemplateComponentRegistration | undefined {
+  const [components, setComponents] = useState(() =>
+    templateComponentRegistry.get(templateId)
+  );
+
+  useEffect(() => {
+    return templateComponentRegistry.subscribe((updatedId) => {
+      if (updatedId === templateId) {
+        setComponents(templateComponentRegistry.get(templateId));
+      }
+    });
+  }, [templateId]);
+
+  return components;
+}

package/src/lib/runtime-context.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import type { ApolloClient } from '@apollo/client';
+import type { TransformEngine } from '@contractspec/lib.contracts';
+import type {
+  TemplateDefinition,
+  TemplateId,
+  TemplateInstaller,
+} from './types';
+
+// Generic interface for handlers to avoid circular dependencies
+// Real types are defined in @contractspec/module.examples or specific example packages
+export type GenericTemplateHandlers = unknown;
+
+export interface TemplateRuntimeContextValue<
+  THandlers = GenericTemplateHandlers,
+> {
+  template: TemplateDefinition;
+  runtime: unknown; // LocalRuntimeServices
+  installer: TemplateInstaller;
+  client: ApolloClient;
+  components?: unknown; // TemplateComponentRegistration
+  /** @deprecated use template.id */
+  templateId: TemplateId;
+  projectId: string;
+  engine: TransformEngine;
+  fetchData: (
+    presentationName: string
+  ) => Promise<{ data: unknown; metadata?: unknown }>;
+  handlers: THandlers;
+  resolvePresentation?: (presentationName: string) => unknown;
+}
+
+export const TemplateRuntimeContext =
+  createContext<TemplateRuntimeContextValue | null>(null);
+
+export function useTemplateRuntime<
+  THandlers = GenericTemplateHandlers,
+>(): TemplateRuntimeContextValue<THandlers> {
+  const context = useContext(TemplateRuntimeContext);
+  if (!context) {
+    throw new Error(
+      'useTemplateRuntime must be used within a TemplateRuntimeProvider'
+    );
+  }
+  return context as TemplateRuntimeContextValue<THandlers>;
+}
+
+export interface TemplateRuntimeProviderProps {
+  templateId: TemplateId;
+  projectId?: string;
+  lazy?: boolean;
+}

package/src/lib/types.ts

@@ -0,0 +1,84 @@
+export type TemplateId = string;
+
+export type TemplateCategory =
+  | 'productivity'
+  | 'communication'
+  | 'content'
+  | 'business'
+  | 'ai';
+
+export type TemplateComplexity = 'beginner' | 'intermediate' | 'advanced';
+
+export interface TemplateDefinition {
+  id: TemplateId;
+  name: string;
+  description: string;
+  category: TemplateCategory;
+  complexity: TemplateComplexity;
+  icon: string;
+  features: string[];
+  tags: string[];
+  schema: {
+    models: string[];
+    contracts: string[];
+  };
+  components: {
+    list: string;
+    detail: string;
+    form?: string;
+    dashboard?: string;
+  };
+  preview?: {
+    demoUrl?: string;
+    videoUrl?: string;
+  };
+  docs?: {
+    quickstart?: string;
+    reference?: string;
+  };
+  /** Package name for external examples that can be cloned via Git */
+  package?: string;
+  /** Whether this template uses the new cross-cutting modules */
+  usesModules?: string[];
+  /** Feature spec key from the example package */
+  featureSpec?: string;
+  /** List of presentation names available for this template */
+  presentations?: string[];
+  /** List of render targets supported (default: ['react']) */
+  renderTargets?: ('react' | 'markdown' | 'json' | 'xml')[];
+}
+
+export interface TemplateFilter {
+  category?: TemplateCategory;
+  complexity?: TemplateComplexity;
+  tag?: string;
+}
+
+export interface InstallTemplateOptions {
+  projectId?: string;
+}
+
+export interface SaveTemplateOptions {
+  endpoint?: string;
+  token?: string;
+  projectName: string;
+  organizationId: string;
+  templateId: TemplateId;
+}
+
+export interface SaveTemplateResult {
+  projectId: string;
+  status: string;
+}
+
+/**
+ * Interface for the TemplateInstaller class.
+ * Mirrors the public API of the implementation in @contractspec/module.examples
+ */
+export interface TemplateInstaller {
+  install(
+    templateId: TemplateId,
+    options?: InstallTemplateOptions
+  ): Promise<void>;
+  saveToStudio(options: SaveTemplateOptions): Promise<SaveTemplateResult>;
+}

package/src/overlay-types.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared Overlay Type Definitions
+ *
+ * These types are used across all template overlays to ensure consistency.
+ */
+
+export interface OverlayDefinition {
+  overlayId: string;
+  version: string;
+  description: string;
+  appliesTo: {
+    presentation?: string;
+    role?: string;
+    feature?: string;
+    tier?: string;
+  };
+  modifications: OverlayModification[];
+}
+
+export type OverlayModification =
+  | { type: 'hideField'; field: string; reason?: string }
+  | { type: 'renameLabel'; field: string; newLabel: string }
+  | { type: 'addBadge'; position: string; label: string; variant?: string }
+  | { type: 'setDefault'; field: string; value: unknown }
+  | { type: 'setLimit'; field: string; max: number; message?: string };

package/src/utils/fetchPresentationData.ts

@@ -0,0 +1,48 @@
+/**
+ * Fetch Presentation Data Utility
+ *
+ * Types for presentation data fetching.
+ * Actual fetching logic is now handled via TemplateRuntimeContext and dependency injection.
+ */
+import type { TemplateId } from '../lib/types';
+
+/**
+ * Data fetcher result type
+ */
+export interface PresentationDataResult {
+  data: unknown;
+  metadata?: {
+    total?: number;
+    timestamp?: Date;
+    source?: string;
+  };
+}
+
+/**
+ * @deprecated Use fetchData from TemplateRuntimeContext instead.
+ */
+/**
+ * @deprecated Use fetchData from TemplateRuntimeContext instead.
+ */
+export async function fetchPresentationData(
+  _presentationName: string,
+  _templateId: TemplateId
+): Promise<PresentationDataResult> {
+  throw new Error(
+    'fetchPresentationData is deprecated. Use fetchData from TemplateRuntimeContext.'
+  );
+}
+
+/**
+ * @deprecated
+ */
+export function hasPresentationDataFetcher(_presentationName: string): boolean {
+  return false;
+}
+
+/**
+ * @deprecated
+ */
+export function getRegisteredPresentationFetchers(): string[] {
+  return [];
+}