cms-renderer 0.5.2 → 0.6.1

package/README.md

@@ -1,43 +1,156 @@
-# cms-renderer
+# Website
 
-A library for rendering CMS-authored content in Next.js websites.
+**CMS-powered website built with Next.js 15 and App Router**
 
 ```
-CMS (authors content) ──► tRPC API ──► Website (renders blocks)
+CMS (authors content) --> tRPC API --> Website (renders blocks)
 ```
 
-## Overview
-
-| Export | Description |
-|--------|-------------|
-| `./lib/renderer` | `ParametricRoutePage` — drop-in catch-all page component |
-| `./lib/block-renderer` | `BlockRenderer`, `walkReactNode` — core rendering primitives |
-| `./lib/block-toolbar` | `BlockToolbar` — floating edit toolbar (portal to `document.body`) |
-| `./lib/client-editable-block` | `ClientEditableBlock` — client-side span injector fallback |
-| `./lib/cms-api` | `getCmsClient` — tRPC HTTP client for Server Components |
-| `./lib/refresher` | `Refresher` — SSE-based live revalidation |
-| `./lib/proxy` | `createCmsProxy` — Next.js middleware to proxy `/admin`, `/api`, `/auth` |
-| `./lib/types` | `BlockData`, `BlockComponentRegistry`, `ResolvedRouteParams`, … |
-| `./lib/schema` | Schema utilities |
-| `./lib/custom-schemas` | Custom schema helpers |
-| `./lib/markdown-utils` | Markdown helpers |
-| `./lib/trpc` | Client-side tRPC hooks |
-| `./lib/result` | `Result<T, E>` type utilities |
-| `./lib/image/lazy-load` | Lazy image component |
+The website app fetches structured page data via tRPC and renders blocks using the ComponentMap pattern. Article content uses WASM-powered markdown rendering for performance.
 
 ---
 
 ## Quick Start
 
+**Prerequisites**
+
+| Tool | Version | Check Command |
+|------|---------|---------------|
+| Bun | 1.2.8+ | `bun --version` |
+| Node.js | 18+ | `node --version` |
+
+**Installation**
+
 ```bash
-bun install        # from monorepo root
-bun run build      # or: bun run dev (watch mode)
+# From monorepo root
+bun install
+
+# Start the website dev server
+cd apps/renderer
+bun run dev
+```
+
+**Verification**
+
+Open [http://localhost:3001](http://localhost:3001). You should see:
+
+```
+Website
+CMS-powered website built with Next.js 15 and App Router.
 ```
 
-**Required env vars** (in the consuming Next.js app):
+Visit [http://localhost:3001/demo](http://localhost:3001/demo) to see the complete demo page with navigation, header, and article blocks.
+
+---
+
+## Architecture
+
+### How This App Fits in the Monorepo
+
+```
+auteur/
+├── apps/
+│   ├── cms/                    # Content authoring (Lexical editor)
+│   └── renderer/               # This app - renders CMS content
+└── packages/
+    ├── cms-schema/             # Shared Zod schemas
+    └── markdown-wasm/          # WASM markdown renderer
+```
+
+The website consumes schemas from `@repo/cms-schema` and uses `@repo/markdown-wasm` for article body rendering. It does not import from `apps/cms/` directly.
+
+### Key Directories
+
+```
+apps/renderer/
+├── app/                        # Next.js App Router pages
+│   ├── [slug]/                 # Dynamic page routes
+│   │   ├── page.tsx            # Server Component fetches via tRPC
+│   │   ├── loading.tsx         # Skeleton loading state
+│   │   └── error.tsx           # Error boundary
+│   ├── api/trpc/[trpc]/        # tRPC API handler
+│   ├── layout.tsx              # Root layout with CSS imports
+│   ├── globals.css             # CSS reset
+│   └── page.tsx                # Homepage
+├── components/
+│   ├── blocks/                 # Block components + registry
+│   │   ├── navigation-block.tsx
+│   │   ├── header-block.tsx
+│   │   ├── article-block.tsx
+│   │   ├── block-renderer.tsx  # Dispatcher component
+│   │   ├── types.ts            # BlockData discriminated union
+│   │   └── index.ts            # Exports + blockComponents registry
+│   ├── page-renderer.tsx       # Renders array of blocks
+│   └── trpc-provider.tsx       # Client-side tRPC/React Query
+├── server/
+│   ├── trpc.ts                 # tRPC initialization
+│   └── routers/
+│       ├── blocks/             # Block data procedures
+│       │   ├── get-navigation.ts
+│       │   ├── get-header.ts
+│       │   └── get-article.ts
+│       └── pages/              # Page composition procedures
+│           └── get-page.ts
+├── seed/                       # Mock data for development
+│   └── index.ts
+├── styles/
+│   └── blocks.css              # Vanilla CSS for blocks
+└── lib/
+    └── trpc.ts                 # Client-side tRPC hooks
+```
+
+### Data Flow
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Dynamic Route  │────>│   tRPC Caller   │────>│  Mock Data      │
+│  [slug]/page    │     │  pages.getPage  │     │  seed/index.ts  │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+        │
+        v
+┌─────────────────┐     ┌─────────────────┐
+│  PageRenderer   │────>│  BlockRenderer  │
+│  (iterates)     │     │  (dispatches)   │
+└─────────────────┘     └─────────────────┘
+                               │
+        ┌──────────────────────┼──────────────────────┐
+        v                      v                      v
+┌───────────────┐     ┌───────────────┐     ┌───────────────┐
+│ NavigationBlock│    │  HeaderBlock  │     │ ArticleBlock  │
+│               │     │               │     │ (WASM markdown)│
+└───────────────┘     └───────────────┘     └───────────────┘
+```
+
+---
+
+## Development Guide
+
+### Available Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `dev` | `bun run dev` | Start dev server on port 3001 |
+| `build` | `bun run build` | Production build |
+| `start` | `bun run start` | Start production server |
+| `lint` | `bun run lint` | Run Biome linter |
+| `check-types` | `bun run check-types` | TypeScript type checking |
+
+### Hot Reload Behavior
+
+- **Page changes**: Instant hot reload
+- **tRPC procedures**: Requires server restart
+- **CSS changes**: Instant hot reload
+- **Block components**: Instant hot reload
+
+### Environment Variables
+
+No environment variables are required for development. The app uses mock data from `seed/index.ts`.
+
+For production with a real database, you would add:
 
 ```env
-NEXT_PUBLIC_WEBSITE_ID=<uuid>   # or pass websiteId prop directly
+# .env.local (not required for development)
+DATABASE_URL=your-database-url
 ```
 
 ---
@@ -46,193 +159,204 @@ NEXT_PUBLIC_WEBSITE_ID=<uuid>   # or pass websiteId prop directly
 
 ### ComponentMap Pattern
 
-Map block type strings to React components via a registry:
-
-```ts
-// app/registry.ts
-import type { BlockComponentRegistry } from 'cms-renderer/lib/types';
-import HeroBlock from '@/components/hero-block';
-import ArticleBlock from '@/components/article-block';
+The website uses a registry-based pattern to map block types to React components:
 
-export const registry: Partial<BlockComponentRegistry> = {
-  'hero-block': HeroBlock,
-  'article': ArticleBlock,
-};
+```typescript
+// components/blocks/index.ts
+export const blockComponents: BlockComponentRegistry = {
+  navigation: NavigationBlock,
+  header: HeaderBlock,
+  article: ArticleBlock,
+} as const;
 ```
 
-Each component receives `{ content, routeParams }`:
+The `BlockRenderer` uses this registry to dispatch blocks:
 
 ```tsx
-import type { BlockComponentProps, HeroBlockContent } from 'cms-renderer/lib/types';
+// Render any block by type
+<BlockRenderer block={{ type: 'header', content: {...} }} />
 
-export function HeroBlock({ content }: BlockComponentProps<HeroBlockContent>) {
-  return <h1>{content.headline}</h1>;
-}
+// Render a page of blocks
+{page.blocks.map((block, i) => (
+  <BlockRenderer key={i} block={block} />
+))}
 ```
 
-Custom blocks (defined via CMS schema builder) are registered by `schema_name`:
+### Block Types
 
-```ts
-registry['my-custom-schema'] = MyCustomComponent;
-```
+| Block | Component | Content Fields |
+|-------|-----------|----------------|
+| `navigation` | `NavigationBlock` | logo, ariaLabel, links (3-level hierarchy) |
+| `header` | `HeaderBlock` | headline, subheadline, backgroundImage, ctaButton, alignment |
+| `article` | `ArticleBlock` | headline, author, publishedAt, body (markdown), tags |
 
----
+### tRPC Integration
 
-### Path-Namespaced Registry
+**Server Component** (recommended):
 
-When a page path is passed to `BlockRenderer`, registry keys of the form `"/{pattern} BlockType"` take priority over plain `"BlockType"` keys. Segments wrapped in `{…}` or `(…)` are wildcards.
+```tsx
+// Direct procedure call in Server Components
+import { createCaller } from '@/server/routers';
+import { createContext } from '@/server/trpc';
 
-```ts
-registry = {
-  // Used only on /en/... paths
-  '/{lang}/products article': ArticleBlockLocalized,
-  // Fallback for all other paths
-  'article': ArticleBlockDefault,
-};
+export default async function Page({ params }: PageProps) {
+  const { slug } = await params;
+  const caller = createCaller(createContext());
+  const page = await caller.pages.getPage({ slug });
 
-<BlockRenderer block={block} registry={registry} path="/en/products" />
+  return <PageRenderer title={page.title} blocks={page.blocks} />;
+}
 ```
 
-This lets you mount path-specific variants without separate route files.
+**Client Component** (when needed):
 
----
+```tsx
+'use client';
+import { trpc } from '@/lib/trpc';
 
-### ParametricRoutePage
+function PageClient({ slug }: { slug: string }) {
+  const { data, isLoading } = trpc.pages.getPage.useQuery({ slug });
 
-A complete catch-all page handler. Drop it into `app/[...slug]/page.tsx`:
+  if (isLoading) return <div>Loading...</div>;
+  return <PageRenderer title={data.title} blocks={data.blocks} />;
+}
+```
+
+### WASM Markdown Rendering
+
+The `ArticleBlock` uses `@repo/markdown-wasm` for fast markdown-to-React conversion:
 
 ```tsx
-// app/[...slug]/page.tsx
-import ParametricRoutePage, { generateMetadata } from 'cms-renderer/lib/renderer';
-import { registry } from '@/registry';
-
-export { generateMetadata };
-
-export default function Page(props: any) {
-  return (
-    <ParametricRoutePage
-      {...props}
-      cmsUrl={process.env.CMS_URL!}
-      apiKey={process.env.CMS_API_KEY}
-      registry={registry}
-    />
-  );
-}
+import { MarkdownRenderer } from '@repo/markdown-wasm';
+
+// Inside ArticleBlock
+<MarkdownRenderer content={body} className="article-block__content" />
 ```
 
-It handles:
-- Route lookup via `client.route.getByPath`
-- Block fetching (parallel, failures are skipped)
-- Article publish-state filtering
-- `?edit_mode=true` — enables editable wrappers (for iframe preview)
-- `?ai_preview=1` — renders AI-generated content variant at index 1
+md4w parses markdown 2.5x faster than JavaScript alternatives and outputs a traversable AST that maps directly to React components.
 
 ---
 
-### Edit Mode & BlockRenderer
-
-When `disableEditable` is `false` (i.e. `edit_mode=true`), `BlockRenderer` wraps each block with `data-cms-block` and injects `data-cms-editable` spans around every text node that corresponds to a content field.
+## API Routes Reference
 
-**How span injection works:**
+### tRPC Endpoints
 
-1. **Server-side (preferred):** `renderToWalkableTree` invokes sync function components to produce a host-element tree, then `walkReactNode` traverses it and wraps matching text values in `<span data-cms-editable … />`.
-2. **Client-side fallback:** When a component uses hooks and can't be invoked server-side, `ClientEditableBlock` takes over — it uses `MutationObserver` to re-inject spans after every React commit, keeping overlays alive through state-driven re-renders.
+| Endpoint | Method | Input | Returns |
+|----------|--------|-------|---------|
+| `blocks.getNavigation` | Query | None | Navigation data |
+| `blocks.getHeader` | Query | None | Header data |
+| `blocks.getArticle` | Query | None | Article data |
+| `pages.getPage` | Query | `{ slug: string }` | Page with blocks array |
 
-**`walkReactNode`** is also exported for custom transforms:
+### Testing Endpoints
 
-```ts
-import { walkReactNode } from 'cms-renderer/lib/block-renderer';
+```bash
+# Start the dev server
+bun run dev
 
-const highlighted = walkReactNode(tree, {
-  onText: ({ value }) => value.replace(/foo/g, '**foo**'),
-  onElement: ({ element }) => element,
-});
+# Test endpoints (in another terminal)
+curl "http://localhost:3001/api/trpc/blocks.getNavigation"
+curl "http://localhost:3001/api/trpc/blocks.getHeader"
+curl "http://localhost:3001/api/trpc/pages.getPage?input=%7B%22json%22%3A%7B%22slug%22%3A%22demo%22%7D%7D"
 ```
 
 ---
 
-### BlockToolbar
+## Testing
 
-Rendered inside every editable block. Portals to `document.body` so it never disrupts layout. Positioned by an inline script that tracks `mouseover` events on `[data-cms-block]` elements.
+The website app does not currently have unit tests. Integration testing is done via the tRPC endpoints.
 
-Actions are dispatched to the parent frame via `postMessage`:
+```bash
+# Type check
+bun run check-types
 
-```ts
-// Messages sent to window.parent:
-{ type: 'cms-block-action', action: 'move-up' | 'move-down' | 'add-block' | 'delete', blockId }
-{ type: 'cms-editable-click', blockId, blockType, contentPath }  // null contentPath = block-level click
+# Lint
+bun run lint
 ```
 
-The CMS admin panel listens for these messages to open the field editor or reorder blocks.
+Test files would live at:
+- `components/blocks/*.test.tsx` for block components
+- `server/routers/**/*.test.ts` for tRPC procedures
 
 ---
 
-### Refresher
+## Troubleshooting
 
-Subscribes to the CMS SSE stream and calls `router.refresh()` when content changes, keeping the page in sync during live editing:
+### Port 3001 Already in Use
 
-```tsx
-// app/layout.tsx
-import { Refresher } from 'cms-renderer/lib/refresher';
-
-export default function Layout({ children }) {
-  return (
-    <html>
-      <body>
-        {children}
-        <Refresher
-          websiteId={process.env.NEXT_PUBLIC_WEBSITE_ID!}
-          cmsUrl={process.env.CMS_URL!}
-          apiKey={process.env.CMS_API_KEY}
-        />
-      </body>
-    </html>
-  );
-}
+```bash
+# Find and kill the process
+lsof -i :3001
+kill -9 <PID>
+
+# Or use a different port
+bun run dev -- --port 3002
 ```
 
----
+### Cannot Find Module '@repo/cms-schema'
 
-### Proxy Middleware
+```bash
+# Run bun install from monorepo root
+cd ../..
+bun install
+```
+
+### TypeScript Errors on First Run
+
+The `.next/types` directory is generated on first dev server run:
+
+```bash
+bun run dev    # Run once to generate types
+bun run check-types  # Now type checking works
+```
 
-Proxies `/admin`, `/api`, `/auth` (and optional extra paths) to the upstream CMS server. Add to `middleware.ts`:
+### WASM Module Not Found
 
-```ts
-import { createCmsProxy } from 'cms-renderer/lib/proxy';
+If you see errors about md4w:
 
-export const middleware = createCmsProxy({
-  upstream: process.env.CMS_URL,        // or ADMIN_UPSTREAM_ORIGIN env var
-  additionalPaths: ['/uploads'],
-});
+```bash
+# Rebuild the markdown-wasm package
+cd ../../packages/markdown-wasm
+bun install
+bun run build
 ```
 
+### tRPC 'NOT_FOUND' Error
+
+The mock data only includes pages with slugs: `demo`, `about`, `blog`. Requesting other slugs returns a 404.
+
 ---
 
-## File Structure
+## Related Documentation
 
-The recommended structure for a consuming Next.js app:
+- **Tutorial**: [`_docs/cms-website-integration/`](../../_docs/cms-website-integration/00-overview.md) - Full 11-chapter tutorial
+- **CMS App**: [`apps/cms/README.md`](../cms/README.md) - Content authoring application
+- **Schema Package**: [`packages/cms-schema/`](../../packages/cms-schema/) - Shared Zod schemas
+- **Markdown Package**: [`packages/markdown-wasm/`](../../packages/markdown-wasm/) - WASM renderer
 
-```
-my-app/
-  app/
-    [...slug]/
-      page.tsx          # ParametricRoutePage
-    layout.tsx          # Refresher goes here
-  components/
-    hero-block.tsx      # Block components
-    article-block.tsx
-  registry.ts           # BlockComponentRegistry
-  middleware.ts         # createCmsProxy
+---
+
+## Contributing
+
+### Code Style
+
+This project uses [Biome](https://biomejs.dev/) for linting and formatting:
+
+```bash
+bun run lint        # Check for issues
+bun run lint --fix  # Auto-fix issues
 ```
 
----
+### Adding a New Block Type
+
+1. Define the schema in `apps/cms/app/schemas/`
+2. Add mock data to `seed/index.ts`
+3. Create the component in `components/blocks/`
+4. Add to `blockComponents` registry in `components/blocks/index.ts`
+5. Add the type to `BlockData` union in `components/blocks/types.ts`
 
-## Scripts
+### Pull Requests
 
-| Script | Description |
-|--------|-------------|
-| `bun run build` | Production build (tsup) |
-| `bun run dev` | Watch mode |
-| `bun run check-types` | TypeScript type check |
-| `bun run lint` | Biome lint |
-| `bun test` | Run tests |
+- Run `bun run check-types` before submitting
+- Run `bun run lint` to ensure code style compliance
+- Test the demo page at `/demo` renders correctly

package/dist/lib/block-renderer.d.ts

@@ -36,6 +36,10 @@ type WalkVisitors = {
      */
     onElement?: (info: ElementInfo) => React__default.ReactElement;
 };
+/**
+ * Recursively maps a ReactNode tree, allowing transformations of text nodes and/or elements.
+ * SSR-safe: does not touch DOM APIs.
+ */
 declare function walkReactNode(node: React__default.ReactNode, visitors: WalkVisitors, ctx?: {
     path?: Array<string | number>;
     parentType?: React__default.ElementType;
@@ -43,12 +47,8 @@ declare function walkReactNode(node: React__default.ReactNode, visitors: WalkVis
     inSvg?: boolean;
 }): React__default.ReactNode;
 /**
- * Renders the shared CSS and event-wiring script needed for the CMS edit
- * overlay.  Render this **once** at page level when edit mode is active —
- * e.g. just before the block list in your route component.
- *
- * If you use `BlockRenderer` standalone (outside of `ParametricRoutePage`)
- * you must render `<CmsEditableInit />` yourself somewhere on the page.
+ * Renders the shared CMS edit-mode styles and click-routing script.
+ * Place this once at the top of your page when edit_mode is active.
  */
 declare function CmsEditableInit(): React__default.JSX.Element;
 interface BlockRendererProps {
@@ -81,10 +81,13 @@ interface BlockRendererProps {
  * Uses the ComponentMap pattern: the block's `type` field determines which
  * component renders the block's `content`.
  *
- * Internally, it:
- * 1. Renders the component tree by invoking function components
- * 2. Extracts all string values from block.content
- * 3. Walks the rendered tree and wraps matching text nodes with spans
+ * In editable mode, wraps the block in a ClientEditableBlock that:
+ * - Stamps data-cms-block attributes directly on the component's root element
+ * - Injects data-cms-editable spans around matching text nodes
+ * - Portals the BlockToolbar into the component's root element
+ *
+ * Render CmsEditableInit once at the page level to include the shared styles
+ * and click-routing script.
  */
 declare function BlockRenderer({ block, registry, disableEditable, routeParams, path, }: BlockRendererProps): React__default.JSX.Element | null;