cms-renderer 0.0.0

package/lib/__tests__/enrich-block-images.test.ts

@@ -0,0 +1,394 @@
+import { beforeAll, beforeEach, describe, expect, it, mock } from 'bun:test';
+
+// =============================================================================
+// Mocks - Must be set up BEFORE any imports that use these modules
+// =============================================================================
+
+// Mock 'server-only' to allow running in test environment
+// This must be called before the module that imports it is loaded
+mock.module('server-only', () => ({}));
+
+// Mock generateSignedImageData to return predictable signed data
+const mockGenerateSignedImageData = mock(
+  (config: { assetId: string; width: number; height: number; url: string }) => ({
+    signedSrcset: `signed-srcset-${config.assetId}`,
+    signedFallbackSrcset: `signed-fallback-srcset-${config.assetId}`,
+    signedDefaultSrc: `signed-default-src-${config.assetId}`,
+  })
+);
+
+mock.module('../image-transforms.server', () => ({
+  generateSignedImageData: mockGenerateSignedImageData,
+}));
+
+// =============================================================================
+// Dynamic Import - Must happen after mocks are registered
+// =============================================================================
+
+type EnrichFunction = <T extends Record<string, unknown>>(content: T | null) => T | null;
+let enrichBlockWithSignedUrls: EnrichFunction;
+
+beforeAll(async () => {
+  const mod = await import('../enrich-block-images');
+  enrichBlockWithSignedUrls = mod.enrichBlockWithSignedUrls;
+});
+
+// =============================================================================
+// Test Data
+// =============================================================================
+
+const createResolvedImageRef = (id: string = '12345678-1234-1234-1234-123456789abc') => ({
+  alt: 'Test image',
+  _asset: {
+    id,
+    url: '/api/dev/storage/test.jpg',
+    width: 1920,
+    height: 1080,
+    lqip: 'data:image/jpeg;base64,/9j/...',
+  },
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('enrichBlockWithSignedUrls', () => {
+  beforeEach(() => {
+    mockGenerateSignedImageData.mockClear();
+  });
+
+  describe('Null/Undefined Handling', () => {
+    it('returns null when content is null', () => {
+      const result = enrichBlockWithSignedUrls(null);
+      expect(result).toBeNull();
+    });
+
+    it('returns content unchanged when it has no image references', () => {
+      const content = { title: 'Hello', count: 42 };
+      const result = enrichBlockWithSignedUrls(content);
+      expect(result).toEqual(content);
+    });
+  });
+
+  describe('Image Reference Detection', () => {
+    it('detects resolved image reference with alt and _asset', () => {
+      const imageRef = createResolvedImageRef();
+      const content = { backgroundImage: imageRef };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledTimes(1);
+      expect(result?.backgroundImage._signed).toBeDefined();
+    });
+
+    it('ignores objects missing _asset.id', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: {
+            url: '/test.jpg',
+            width: 1920,
+            height: 1080,
+          },
+        },
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+      expect((result?.notAnImage as Record<string, unknown>)._signed).toBeUndefined();
+    });
+
+    it('ignores objects missing alt', () => {
+      const content = {
+        notAnImage: {
+          _asset: {
+            id: '12345678-1234-1234-1234-123456789abc',
+            url: '/test.jpg',
+            width: 1920,
+            height: 1080,
+          },
+        },
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+      expect((result?.notAnImage as Record<string, unknown>)._signed).toBeUndefined();
+    });
+
+    it('ignores objects where _asset is null', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: null,
+        },
+      };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+    });
+
+    it('ignores objects where _asset is missing id', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: {
+            url: '/test.jpg',
+            width: 1920,
+            height: 1080,
+          },
+        },
+      };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+    });
+
+    it('ignores objects where _asset is missing url', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: {
+            id: '12345678-1234-1234-1234-123456789abc',
+            width: 1920,
+            height: 1080,
+          },
+        },
+      };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+    });
+
+    it('ignores objects where _asset is missing width', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: {
+            id: '12345678-1234-1234-1234-123456789abc',
+            url: '/test.jpg',
+            height: 1080,
+          },
+        },
+      };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+    });
+
+    it('ignores objects where _asset is missing height', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: {
+            id: '12345678-1234-1234-1234-123456789abc',
+            url: '/test.jpg',
+            width: 1920,
+          },
+        },
+      };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+    });
+
+    it('requires _asset.id to be a 36-character UUID', () => {
+      const content = {
+        notAnImage: {
+          alt: 'Test',
+          _asset: {
+            id: 'short-id', // Not 36 characters
+            url: '/test.jpg',
+            width: 1920,
+            height: 1080,
+          },
+        },
+      };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Recursive Traversal', () => {
+    it('traverses nested objects', () => {
+      const imageRef = createResolvedImageRef();
+      const content = {
+        section: {
+          hero: {
+            backgroundImage: imageRef,
+          },
+        },
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledTimes(1);
+      expect(result?.section.hero.backgroundImage._signed).toBeDefined();
+    });
+
+    it('traverses arrays', () => {
+      const imageRef1 = createResolvedImageRef('11111111-1111-1111-1111-111111111111');
+      const imageRef2 = createResolvedImageRef('22222222-2222-2222-2222-222222222222');
+
+      const content = {
+        images: [imageRef1, imageRef2],
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledTimes(2);
+      expect(result?.images[0]._signed).toBeDefined();
+      expect(result?.images[1]._signed).toBeDefined();
+    });
+
+    it('traverses deeply nested arrays within objects', () => {
+      const imageRef = createResolvedImageRef();
+      const content = {
+        sections: [
+          {
+            cards: [
+              {
+                thumbnail: imageRef,
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledTimes(1);
+      expect(result?.sections[0].cards[0].thumbnail._signed).toBeDefined();
+    });
+
+    it('handles multiple image references at different levels', () => {
+      const heroImage = createResolvedImageRef('11111111-1111-1111-1111-111111111111');
+      const thumbnailImage = createResolvedImageRef('22222222-2222-2222-2222-222222222222');
+
+      const content = {
+        hero: heroImage,
+        sidebar: {
+          thumbnail: thumbnailImage,
+        },
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledTimes(2);
+      expect(result?.hero._signed).toBeDefined();
+      expect(result?.sidebar.thumbnail._signed).toBeDefined();
+    });
+  });
+
+  describe('Signed URL Data', () => {
+    it('adds _signed with signedSrcset, signedFallbackSrcset, and signedDefaultSrc', () => {
+      const imageRef = createResolvedImageRef();
+      const content = { image: imageRef };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(result?.image._signed).toEqual({
+        signedSrcset: 'signed-srcset-asset-123',
+        signedFallbackSrcset: 'signed-fallback-srcset-asset-123',
+        signedDefaultSrc: 'signed-default-src-asset-123',
+      });
+    });
+
+    it('passes correct config to generateSignedImageData', () => {
+      const imageRef = createResolvedImageRef();
+      const content = { image: imageRef };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledWith(
+        {
+          assetId: 'asset-123',
+          width: 1920,
+          height: 1080,
+          url: '/api/dev/storage/test.jpg',
+        },
+        expect.objectContaining({})
+      );
+    });
+
+    it('passes focalPoint option when transformation includes hx/hy', () => {
+      const imageRef = {
+        ...createResolvedImageRef(),
+        _asset: {
+          ...createResolvedImageRef()._asset,
+          transformation: 'hx=0.3&hy=0.7',
+        },
+      };
+      const content = { image: imageRef };
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(mockGenerateSignedImageData).toHaveBeenCalledWith(expect.objectContaining({}), {
+        focalPoint: { x: 0.3, y: 0.7 },
+      });
+    });
+  });
+
+  describe('Immutability', () => {
+    it('does not mutate the original object', () => {
+      const imageRef = createResolvedImageRef();
+      const content = { image: imageRef };
+      const originalContent = JSON.stringify(content);
+
+      enrichBlockWithSignedUrls(content);
+
+      expect(JSON.stringify(content)).toBe(originalContent);
+      expect((content.image as Record<string, unknown>)._signed).toBeUndefined();
+    });
+
+    it('returns a new object with signed data', () => {
+      const imageRef = createResolvedImageRef();
+      const content = { image: imageRef };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(result).not.toBe(content);
+      expect(result?.image).not.toBe(content.image);
+    });
+  });
+
+  describe('Primitive Values', () => {
+    it('preserves primitive values', () => {
+      const content = {
+        title: 'Hello World',
+        count: 42,
+        enabled: true,
+        ratio: 3.14,
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(result).toEqual(content);
+    });
+
+    it('preserves nested primitive values alongside images', () => {
+      const imageRef = createResolvedImageRef();
+      const content = {
+        title: 'Hero Section',
+        order: 1,
+        visible: true,
+        image: imageRef,
+      };
+
+      const result = enrichBlockWithSignedUrls(content);
+
+      expect(result?.title).toBe('Hero Section');
+      expect(result?.order).toBe(1);
+      expect(result?.visible).toBe(true);
+      expect(result?.image._signed).toBeDefined();
+    });
+  });
+});

package/lib/block-renderer.tsx

@@ -0,0 +1,60 @@
+/**
+ * Block Renderer Component
+ *
+ * Dispatches block data to the appropriate component using the ComponentMap pattern.
+ * This is the main entry point for rendering blocks from the CMS.
+ */
+
+import type { BlockComponentRegistry, BlockData } from './types';
+
+// -----------------------------------------------------------------------------
+// Props
+// -----------------------------------------------------------------------------
+
+interface BlockRendererProps {
+  /**
+   * The block data to render.
+   * Must have a `type` field that maps to a registered component.
+   */
+  block: BlockData;
+  registry: Partial<BlockComponentRegistry>;
+}
+
+// -----------------------------------------------------------------------------
+// Component
+// -----------------------------------------------------------------------------
+
+/**
+ * Renders a single block by dispatching to the appropriate component.
+ *
+ * Uses the ComponentMap pattern: the block's `type` field determines which
+ * component renders the block's `content`.
+ *
+ * @example
+ * ```tsx
+ * // Render a single block
+ * <BlockRenderer block={{ type: 'header', content: { headline: 'Hello' } }} />
+ *
+ * // Render an array of blocks
+ * {page.blocks.map((block, index) => (
+ *   <BlockRenderer key={index} block={block} />
+ * ))}
+ * ```
+ */
+export function BlockRenderer({ block, registry }: BlockRendererProps) {
+  const Component = registry[block.type];
+
+  if (!Component) {
+    // Log warning in development, render nothing in production
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`[BlockRenderer] Unknown block type: ${block.type}`);
+    }
+    return null;
+  }
+
+  // TypeScript cannot narrow the content type through the component lookup,
+  // so we use a type assertion here. Runtime safety is guaranteed by the
+  // discriminated union and the blockComponents registry.
+  // biome-ignore lint/suspicious/noExplicitAny: Type safety ensured by BlockData discriminated union
+  return <Component content={block.content as any} />;
+}

package/lib/cms-api.ts

@@ -0,0 +1,86 @@
+/**
+ * CMS API Client
+ *
+ * Creates an HTTP-based tRPC client for calling the CMS API.
+ * Used in Server Components to fetch routes and blocks from the CMS.
+ */
+
+import type { AppRouter } from '@repo/cms-schema/trpc';
+import { type CreateTRPCClient, createTRPCClient, httpBatchLink } from '@trpc/client';
+import { cache } from 'react';
+import superjson from 'superjson';
+
+/** Type alias for the CMS API client */
+type CmsClient = CreateTRPCClient<AppRouter>;
+
+/**
+ * Get the CMS API URL from environment variables.
+ * Falls back to localhost:3000 for development.
+ */
+function getCmsApiUrl(): string {
+  const cmsUrl = process.env.NEXT_PUBLIC_CMS_URL || 'http://localhost:3000';
+  return `${cmsUrl}/api/trpc`;
+}
+
+/** Options for creating a CMS client */
+export interface CmsClientOptions {
+  /** API key for authentication (passed as query parameter) */
+  apiKey?: string;
+}
+
+/**
+ * Create a custom fetch function that appends API key as query parameter.
+ */
+function createFetchWithApiKey(apiKey?: string) {
+  return async (url: URL | RequestInfo, options?: RequestInit): Promise<Response> => {
+    let finalUrl = url;
+
+    // Append api_key to URL if provided
+    if (apiKey) {
+      const urlObj = new URL(url.toString());
+      urlObj.searchParams.set('api_key', apiKey);
+      finalUrl = urlObj.toString();
+    }
+
+    const response = await fetch(finalUrl, options);
+
+    return response;
+  };
+}
+
+/**
+ * Create a tRPC client for the CMS API.
+ * Client is created lazily to ensure environment variables are available at runtime.
+ */
+function createCmsClient(options?: CmsClientOptions): CmsClient {
+  const url = getCmsApiUrl();
+  console.log('[CMS API] Creating client with URL:', url);
+
+  return createTRPCClient<AppRouter>({
+    links: [
+      httpBatchLink({
+        url,
+        transformer: superjson,
+        fetch: createFetchWithApiKey(options?.apiKey),
+      }),
+    ],
+  });
+}
+
+/**
+ * Get a CMS client with optional API key.
+ * Uses React's cache() to dedupe requests within a single render.
+ */
+export function getCmsClient(options?: CmsClientOptions): CmsClient {
+  // If no API key, use the cached default client
+  if (!options?.apiKey) {
+    return getDefaultCmsClient();
+  }
+  // With API key, create a new client (keys are request-specific)
+  return createCmsClient(options);
+}
+
+/**
+ * Cached default CMS client (no auth) for public requests.
+ */
+const getDefaultCmsClient = cache(() => createCmsClient());