cms-renderer 0.4.0 → 0.5.0

package/README.md

@@ -1,156 +1,43 @@
-# Website
+# cms-renderer
 
-**CMS-powered website built with Next.js 15 and App Router**
+A library for rendering CMS-authored content in Next.js websites.
 
 ```
-CMS (authors content) --> tRPC API --> Website (renders blocks)
+CMS (authors content) ──► tRPC API ──► Website (renders blocks)
 ```
 
-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.
+## 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 |
 
 ---
 
 ## Quick Start
 
-**Prerequisites**
-
-| Tool | Version | Check Command |
-|------|---------|---------------|
-| Bun | 1.2.8+ | `bun --version` |
-| Node.js | 18+ | `node --version` |
-
-**Installation**
-
 ```bash
-# From monorepo root
-bun install
-
-# Start the website dev server
-cd apps/website
-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.
+bun install        # from monorepo root
+bun run build      # or: bun run dev (watch mode)
 ```
 
-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)
-│   └── website/                # 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/website/
-├── 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:
+**Required env vars** (in the consuming Next.js app):
 
 ```env
-# .env.local (not required for development)
-DATABASE_URL=your-database-url
+NEXT_PUBLIC_WEBSITE_ID=<uuid>   # or pass websiteId prop directly
 ```
 
 ---
@@ -159,204 +46,193 @@ DATABASE_URL=your-database-url
 
 ### ComponentMap Pattern
 
-The website uses a registry-based pattern to map block types to React components:
+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';
 
-```typescript
-// components/blocks/index.ts
-export const blockComponents: BlockComponentRegistry = {
-  navigation: NavigationBlock,
-  header: HeaderBlock,
-  article: ArticleBlock,
-} as const;
+export const registry: Partial<BlockComponentRegistry> = {
+  'hero-block': HeroBlock,
+  'article': ArticleBlock,
+};
 ```
 
-The `BlockRenderer` uses this registry to dispatch blocks:
+Each component receives `{ content, routeParams }`:
 
 ```tsx
-// Render any block by type
-<BlockRenderer block={{ type: 'header', content: {...} }} />
+import type { BlockComponentProps, HeroBlockContent } from 'cms-renderer/lib/types';
 
-// Render a page of blocks
-{page.blocks.map((block, i) => (
-  <BlockRenderer key={i} block={block} />
-))}
+export function HeroBlock({ content }: BlockComponentProps<HeroBlockContent>) {
+  return <h1>{content.headline}</h1>;
+}
 ```
 
-### Block Types
+Custom blocks (defined via CMS schema builder) are registered by `schema_name`:
 
-| 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 |
+```ts
+registry['my-custom-schema'] = MyCustomComponent;
+```
 
-### tRPC Integration
+---
 
-**Server Component** (recommended):
+### Path-Namespaced Registry
 
-```tsx
-// Direct procedure call in Server Components
-import { createCaller } from '@/server/routers';
-import { createContext } from '@/server/trpc';
+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.
 
-export default async function Page({ params }: PageProps) {
-  const { slug } = await params;
-  const caller = createCaller(createContext());
-  const page = await caller.pages.getPage({ slug });
+```ts
+registry = {
+  // Used only on /en/... paths
+  '/{lang}/products article': ArticleBlockLocalized,
+  // Fallback for all other paths
+  'article': ArticleBlockDefault,
+};
 
-  return <PageRenderer title={page.title} blocks={page.blocks} />;
-}
+<BlockRenderer block={block} registry={registry} path="/en/products" />
 ```
 
-**Client Component** (when needed):
-
-```tsx
-'use client';
-import { trpc } from '@/lib/trpc';
-
-function PageClient({ slug }: { slug: string }) {
-  const { data, isLoading } = trpc.pages.getPage.useQuery({ slug });
+This lets you mount path-specific variants without separate route files.
 
-  if (isLoading) return <div>Loading...</div>;
-  return <PageRenderer title={data.title} blocks={data.blocks} />;
-}
-```
+---
 
-### WASM Markdown Rendering
+### ParametricRoutePage
 
-The `ArticleBlock` uses `@repo/markdown-wasm` for fast markdown-to-React conversion:
+A complete catch-all page handler. Drop it into `app/[...slug]/page.tsx`:
 
 ```tsx
-import { MarkdownRenderer } from '@repo/markdown-wasm';
-
-// Inside ArticleBlock
-<MarkdownRenderer content={body} className="article-block__content" />
+// 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}
+    />
+  );
+}
 ```
 
-md4w parses markdown 2.5x faster than JavaScript alternatives and outputs a traversable AST that maps directly to React components.
+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
 
 ---
 
-## API Routes Reference
+### Edit Mode & BlockRenderer
 
-### tRPC Endpoints
+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.
 
-| 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 |
+**How span injection works:**
 
-### Testing 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.
 
-```bash
-# Start the dev server
-bun run dev
+**`walkReactNode`** is also exported for custom transforms:
+
+```ts
+import { walkReactNode } from 'cms-renderer/lib/block-renderer';
 
-# 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"
+const highlighted = walkReactNode(tree, {
+  onText: ({ value }) => value.replace(/foo/g, '**foo**'),
+  onElement: ({ element }) => element,
+});
 ```
 
 ---
 
-## Testing
+### BlockToolbar
 
-The website app does not currently have unit tests. Integration testing is done via the tRPC endpoints.
+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.
 
-```bash
-# Type check
-bun run check-types
+Actions are dispatched to the parent frame via `postMessage`:
 
-# Lint
-bun run lint
+```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
 ```
 
-Test files would live at:
-- `components/blocks/*.test.tsx` for block components
-- `server/routers/**/*.test.ts` for tRPC procedures
+The CMS admin panel listens for these messages to open the field editor or reorder blocks.
 
 ---
 
-## Troubleshooting
-
-### Port 3001 Already in Use
-
-```bash
-# Find and kill the process
-lsof -i :3001
-kill -9 <PID>
-
-# Or use a different port
-bun run dev -- --port 3002
-```
+### Refresher
 
-### Cannot Find Module '@repo/cms-schema'
+Subscribes to the CMS SSE stream and calls `router.refresh()` when content changes, keeping the page in sync during live editing:
 
-```bash
-# Run bun install from monorepo root
-cd ../..
-bun install
+```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>
+  );
+}
 ```
 
-### 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
-```
+### Proxy Middleware
 
-### WASM Module Not Found
+Proxies `/admin`, `/api`, `/auth` (and optional extra paths) to the upstream CMS server. Add to `middleware.ts`:
 
-If you see errors about md4w:
+```ts
+import { createCmsProxy } from 'cms-renderer/lib/proxy';
 
-```bash
-# Rebuild the markdown-wasm package
-cd ../../packages/markdown-wasm
-bun install
-bun run build
+export const middleware = createCmsProxy({
+  upstream: process.env.CMS_URL,        // or ADMIN_UPSTREAM_ORIGIN env var
+  additionalPaths: ['/uploads'],
+});
 ```
 
-### tRPC 'NOT_FOUND' Error
-
-The mock data only includes pages with slugs: `demo`, `about`, `blog`. Requesting other slugs returns a 404.
-
 ---
 
-## Related Documentation
+## File Structure
 
-- **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
+The recommended structure for a consuming Next.js app:
 
----
-
-## 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
+```
+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
 ```
 
-### 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`
+---
 
-### Pull Requests
+## Scripts
 
-- Run `bun run check-types` before submitting
-- Run `bun run lint` to ensure code style compliance
-- Test the demo page at `/demo` renders correctly
+| 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 |

package/dist/lib/block-renderer.js

@@ -186,28 +186,18 @@ function BlockRenderer({
       "data-cms-block": true,
       "data-block-id": block.id,
       "data-block-type": block.type,
-      style: { position: "relative" },
+      style: { display: "contents" },
       children: [
         /* @__PURE__ */ jsx("style", { children: `
         [data-cms-block] {
-          position: relative;
-        }
-        [data-cms-block]:hover {
-          outline: 2px solid #3b82f6;
-          outline-offset: 4px;
+          display: contents;
         }
         [data-cms-editable] {
+          display: contents;
           cursor: pointer;
-          border-radius: 2px;
-        }
-        [data-cms-editable]:hover {
-          outline: 2px solid #3b82f6;
-          outline-offset: 2px;
         }
         .cms-block-toolbar {
-          position: absolute;
-          bottom: 8px;
-          left: 50%;
+          position: fixed;
           transform: translateX(-50%);
           display: flex;
           gap: 4px;
@@ -218,11 +208,7 @@ function BlockRenderer({
           opacity: 0;
           pointer-events: none;
           transition: opacity 0.15s ease;
-          z-index: 1000;
-        }
-        [data-cms-block]:hover .cms-block-toolbar {
-          opacity: 1;
-          pointer-events: auto;
+          z-index: 9999;
         }
         .cms-block-toolbar button {
           display: flex;
@@ -266,34 +252,70 @@ function BlockRenderer({
             (function() {
               if (!window.__cmsEditableInitialized) {
                 window.__cmsEditableInitialized = true;
+                var _ab = null;
+
+                function _tb(bid) {
+                  return document.querySelector('.cms-block-toolbar[data-block-id="' + bid + '"]');
+                }
+
+                function _show(bid, target) {
+                  var tb = _tb(bid);
+                  if (tb && target) {
+                    var r = target.getBoundingClientRect();
+                    tb.style.left = Math.round(r.left + r.width / 2) + 'px';
+                    tb.style.top = Math.round(r.bottom + 8) + 'px';
+                    tb.style.opacity = '1';
+                    tb.style.pointerEvents = 'auto';
+                  }
+                }
+
+                function _hide(bid) {
+                  var tb = _tb(bid);
+                  if (tb) { tb.style.opacity = '0'; tb.style.pointerEvents = 'none'; }
+                }
+
+                document.addEventListener('mouseover', function(e) {
+                  if (e.target.closest('.cms-block-toolbar')) return;
+                  var bel = e.target.closest('[data-cms-block]');
+                  var bid = bel ? bel.getAttribute('data-block-id') : null;
+                  if (bid === _ab) return;
+                  if (_ab) _hide(_ab);
+                  _ab = bid;
+                  if (bid) _show(bid, e.target);
+                });
 
                 document.addEventListener('click', function(e) {
                   if (e.target.closest('.cms-block-toolbar')) return;
 
-                  var editableTarget = e.target.closest('[data-cms-editable]');
-                  if (editableTarget) {
-                    var message = {
-                      type: 'cms-editable-click',
-                      blockId: editableTarget.getAttribute('data-block-id'),
-                      blockType: editableTarget.getAttribute('data-block-type'),
-                      contentPath: editableTarget.getAttribute('data-content-path')
-                    };
+                  var path = e.composedPath ? e.composedPath() : [e.target];
+                  var et = null;
+                  for (var i = 0; i < path.length; i++) {
+                    var n = path[i];
+                    if (n.nodeType === 1 && n.hasAttribute && n.hasAttribute('data-cms-editable')) { et = n; break; }
+                  }
+                  if (!et) et = e.target.closest && e.target.closest('[data-cms-editable]');
+
+                  if (et) {
                     if (window.parent && window.parent !== window) {
-                      window.parent.postMessage(message, '*');
+                      window.parent.postMessage({
+                        type: 'cms-editable-click',
+                        blockId: et.getAttribute('data-block-id'),
+                        blockType: et.getAttribute('data-block-type'),
+                        contentPath: et.getAttribute('data-content-path')
+                      }, '*');
                     }
                     return;
                   }
 
-                  var blockTarget = e.target.closest('[data-cms-block]');
-                  if (blockTarget) {
-                    var message = {
-                      type: 'cms-editable-click',
-                      blockId: blockTarget.getAttribute('data-block-id'),
-                      blockType: blockTarget.getAttribute('data-block-type'),
-                      contentPath: null
-                    };
+                  var bt = e.target.closest && e.target.closest('[data-cms-block]');
+                  if (bt) {
                     if (window.parent && window.parent !== window) {
-                      window.parent.postMessage(message, '*');
+                      window.parent.postMessage({
+                        type: 'cms-editable-click',
+                        blockId: bt.getAttribute('data-block-id'),
+                        blockType: bt.getAttribute('data-block-type'),
+                        contentPath: null
+                      }, '*');
                     }
                   }
                 });