cms-renderer 0.6.3 → 0.6.5

package/README.md

@@ -1,385 +1,295 @@
-# Website
+# cms-renderer
 
-**CMS-powered website built with Next.js 15 and App Router**
+`cms-renderer` is a library for rendering CMS-powered routes inside a Next.js app.
 
-```
-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.
-
----
-
-## Quick Start
+It provides:
 
-**Prerequisites**
+- A catch-all route component that fetches CMS routes and blocks from the CMS API and renders them with your React component registry
+- A proxy helper for mounting the CMS admin and API behind your app
+- Schema-fetching utilities for headless document access
+- Docs-oriented markdown rendering and styles
+- Type exports for block registries and route params
 
-| Tool | Version | Check Command |
-|------|---------|---------------|
-| Bun | 1.2.8+ | `bun --version` |
-| Node.js | 18+ | `node --version` |
+It is meant to be embedded in an existing Next.js app. It is not a standalone website.
 
-**Installation**
+## Install
 
 ```bash
-# From monorepo root
-bun install
-
-# Start the website dev server
-cd apps/renderer
-bun run dev
+npm install cms-renderer
 ```
 
-**Verification**
+This package is intended for React + Next.js applications that can reach a running CMS deployment.
 
-Open [http://localhost:3001](http://localhost:3001). You should see:
+## Exported Entry Points
 
-```
-Website
-CMS-powered website built with Next.js 15 and App Router.
-```
+Main entry points:
 
-Visit [http://localhost:3001/demo](http://localhost:3001/demo) to see the complete demo page with navigation, header, and article blocks.
+- `cms-renderer/lib/renderer` for catch-all route rendering
+- `cms-renderer/lib/types` for block and route types
+- `cms-renderer/lib/proxy` for proxying CMS admin and API traffic
+- `cms-renderer/lib/schema` for headless schema-based reads
+- `cms-renderer/lib/custom-schemas` for fetching custom schema metadata and generating Zod code
+- `cms-renderer/lib/docs-markdown` and `cms-renderer/styles/docs-markdown.css` for docs markdown rendering
+- `cms-renderer/lib/refresher` for client-side refresh on CMS updates
 
----
+Additional utility exports:
 
-## Architecture
+- `cms-renderer/lib/block-renderer`
+- `cms-renderer/lib/block-toolbar`
+- `cms-renderer/lib/client-editable-block`
+- `cms-renderer/lib/cms-api`
+- `cms-renderer/lib/markdown-utils`
+- `cms-renderer/lib/result`
+- `cms-renderer/lib/trpc`
+- `cms-renderer/lib/image/lazy-load`
 
-### How This App Fits in the Monorepo
+## Core Usage
 
-```
-auteur/
-├── apps/
-│   ├── cms/                    # Content authoring (Lexical editor)
-│   └── renderer/               # This app - renders CMS content
-└── packages/
-    ├── cms-schema/             # Shared Zod schemas
-    └── markdown-wasm/          # WASM markdown renderer
-```
+### 1. Render CMS Routes in a Catch-All Next.js Page
 
-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.
+Use the default export from `cms-renderer/lib/renderer` inside a catch-all route such as `app/[...slug]/page.tsx`.
 
-### Key Directories
+```tsx
+import ParametricRoutePage from 'cms-renderer/lib/renderer';
+import type { BlockComponentRegistry } from 'cms-renderer/lib/types';
+import HeaderBlock from '@/components/HeaderBlock';
 
-```
-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
-```
+const registry: Partial<BlockComponentRegistry> = {
+  header: HeaderBlock,
+};
+
+interface PageProps {
+  params: Promise<{ slug: string[] }>;
+  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
+}
 
-### Data Flow
+export default async function Page({ params, searchParams }: PageProps) {
+  const { slug } = await params;
 
-```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  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)│
-└───────────────┘     └───────────────┘     └───────────────┘
+  return (
+    <ParametricRoutePage
+      registry={registry}
+      cmsUrl={process.env.NEXT_PUBLIC_CMS_URL!}
+      apiKey={process.env.CMS_API_KEY}
+      websiteId={process.env.NEXT_PUBLIC_WEBSITE_ID}
+      params={Promise.resolve({ slug })}
+      searchParams={searchParams}
+    />
+  );
+}
 ```
 
----
+What the route component does:
 
-## Development Guide
+- Resolves the incoming path from the catch-all slug
+- Fetches the route definition from the CMS API
+- Fetches each referenced block
+- Maps each block to your registry by `schema_name`
+- Renders built-in and custom block types
+- Supports `edit_mode` and `ai_preview` query params
 
-### Available Scripts
+### 2. Register Block Components
 
-| 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 |
+Block components receive `content` and optional `routeParams`.
 
-### Hot Reload Behavior
+```tsx
+import type { BlockComponentProps } from 'cms-renderer/lib/types';
+
+type HeroProps = BlockComponentProps<{
+  headline: string;
+  subheadline?: string;
+}>;
+
+export default function HeroBlock({ content }: HeroProps) {
+  return (
+    <section>
+      <h1>{content.headline}</h1>
+      {content.subheadline ? <p>{content.subheadline}</p> : null}
+    </section>
+  );
+}
+```
 
-- **Page changes**: Instant hot reload
-- **tRPC procedures**: Requires server restart
-- **CSS changes**: Instant hot reload
-- **Block components**: Instant hot reload
+Useful types are exported from `cms-renderer/lib/types`:
 
-### Environment Variables
+- `BlockData`
+- `BlockComponentProps<T>`
+- `BlockComponentRegistry`
+- `ResolvedRouteParams`
 
-No environment variables are required for development. The app uses mock data from `seed/index.ts`.
+### 3. Configure Environment
 
-For production with a real database, you would add:
+Required for route rendering:
 
 ```env
-# .env.local (not required for development)
-DATABASE_URL=your-database-url
+NEXT_PUBLIC_CMS_URL=https://cms.example.com
+NEXT_PUBLIC_WEBSITE_ID=00000000-0000-0000-0000-000000000000
 ```
 
----
-
-## Key Concepts
-
-### ComponentMap Pattern
-
-The website uses a registry-based pattern to map block types to React components:
+Optional:
 
-```typescript
-// components/blocks/index.ts
-export const blockComponents: BlockComponentRegistry = {
-  navigation: NavigationBlock,
-  header: HeaderBlock,
-  article: ArticleBlock,
-} as const;
+```env
+CMS_API_KEY=your-api-key
+ADMIN_UPSTREAM_ORIGIN=https://cms.example.com
+NEXT_PUBLIC_CMS_API_URL=https://cms.example.com
 ```
 
-The `BlockRenderer` uses this registry to dispatch blocks:
+`ParametricRoutePage` requires:
 
-```tsx
-// Render any block by type
-<BlockRenderer block={{ type: 'header', content: {...} }} />
+- `cmsUrl`, passed as a prop
+- a website ID, passed as a prop or available through environment variables
 
-// Render a page of blocks
-{page.blocks.map((block, i) => (
-  <BlockRenderer key={i} block={block} />
-))}
-```
+`websiteId` can be passed explicitly to `ParametricRoutePage`, or it can be read from:
 
-### Block Types
+- `NEXT_PUBLIC_WEBSITE_ID`
+- `WEBSITE_ID`
+- `CMS_WEBSITE_ID`
 
-| 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 |
+Use `CMS_API_KEY` when your CMS requires authenticated access.
 
-### tRPC Integration
+`NEXT_PUBLIC_CMS_API_URL` is only used by the default `schema` export from `cms-renderer/lib/schema`. If you call `configureSchema(...)` directly, pass `cmsUrl` explicitly instead.
 
-**Server Component** (recommended):
+If no website ID is available, `ParametricRoutePage` throws at runtime.
 
-```tsx
-// Direct procedure call in Server Components
-import { createCaller } from '@/server/routers';
-import { createContext } from '@/server/trpc';
+## CMS Proxy
 
-export default async function Page({ params }: PageProps) {
-  const { slug } = await params;
-  const caller = createCaller(createContext());
-  const page = await caller.pages.getPage({ slug });
+Use `createCmsProxy` when your app needs to proxy `/admin`, `/api`, `/auth`, and related CMS assets to an upstream CMS deployment.
+Use it from `proxy.ts` or `middleware.ts`, depending on how your Next.js app is structured.
 
-  return <PageRenderer title={page.title} blocks={page.blocks} />;
-}
-```
+```ts
+import { createCmsProxy, cmsProxyMatcher } from 'cms-renderer/lib/proxy';
+import type { NextRequest } from 'next/server';
 
-**Client Component** (when needed):
+const cmsProxy = createCmsProxy({
+  upstream: process.env.ADMIN_UPSTREAM_ORIGIN,
+});
 
-```tsx
-'use client';
-import { trpc } from '@/lib/trpc';
-
-function PageClient({ slug }: { slug: string }) {
-  const { data, isLoading } = trpc.pages.getPage.useQuery({ slug });
-
-  if (isLoading) return <div>Loading...</div>;
-  return <PageRenderer title={data.title} blocks={data.blocks} />;
+export async function middleware(request: NextRequest) {
+  return cmsProxy(request);
 }
-```
-
-### Edit-Mode Block Toolbar
 
-When a page is rendered inside the CMS iframe, hovering a block shows a floating toolbar with move-up / move-down / add / delete controls.
-
-**Viewport-aware positioning**
-
-On `mouseenter`, the block's `DOMRect` is captured and passed to `BlockToolbar`. After the toolbar renders, a `useLayoutEffect` measures the toolbar's actual dimensions and tries up to five candidate placements in order, stopping at the first one that fits fully inside the viewport:
-
-| # | Placement |
-|---|-----------|
-| 1 | Below block, centered |
-| 2 | Above block, centered |
-| 3 | Below block, right-aligned |
-| 4 | Below block, left-aligned |
-| 5 | Above block, right-aligned |
+export const config = {
+  matcher: cmsProxyMatcher,
+};
+```
 
-If none of the five candidates fit (e.g. the block is larger than the viewport), the toolbar falls back to candidate 1 clamped to the viewport edges. The toolbar starts with `visibility: hidden` and is made visible only after positioning, so there is no positional flash.
+The proxy helper:
 
-**Components involved**
+- Forwards `/admin`, `/api`, and `/auth`
+- Can proxy additional custom path prefixes
+- Rewrites redirects back to the current host when appropriate
+- Rewrites cookies for the current deployment host
+- Proxies admin-originated static asset requests
 
-- `lib/client-editable-block.tsx` — captures the block rect on hover and portals `BlockToolbar` to `document.body`
-- `lib/block-toolbar.tsx` — runs the candidate loop in `useLayoutEffect` and applies `top`/`left` directly on the element
+## Headless Schema Access
 
-### WASM Markdown Rendering
+Use `configureSchema` or the default `schema` export when you want published documents for a custom schema outside the block renderer.
 
-The `ArticleBlock` uses `@repo/markdown-wasm` for fast markdown-to-React conversion:
+```ts
+import { configureSchema } from 'cms-renderer/lib/schema';
 
-```tsx
-import { MarkdownRenderer } from '@repo/markdown-wasm';
+const cms = configureSchema({
+  cmsUrl: process.env.NEXT_PUBLIC_CMS_URL!,
+  apiKey: process.env.CMS_API_KEY,
+  websiteId: process.env.NEXT_PUBLIC_WEBSITE_ID,
+});
 
-// Inside ArticleBlock
-<MarkdownRenderer content={body} className="article-block__content" />
+const posts = await cms.name('post').fetchAll();
+const post = await cms.name('post').fetchSingleById('document-id');
+const frenchPosts = await cms.name('post').translation('fr').fetchAll();
 ```
 
-md4w parses markdown 2.5x faster than JavaScript alternatives and outputs a traversable AST that maps directly to React components.
+Available methods:
 
----
+- `fetchAll()`
+- `fetchSingle()`
+- `fetchSingleById(id)`
+- `translation(language)`
 
-## API Routes Reference
+If you use the default `schema` export, it reads `NEXT_PUBLIC_CMS_API_URL` from the environment. If your app already has a CMS base URL under a different variable name, prefer `configureSchema(...)` and pass `cmsUrl` explicitly.
 
-### tRPC Endpoints
+## Custom Schema Code Generation
 
-| 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 |
+Use `cms-renderer/lib/custom-schemas` to fetch custom schema metadata and generate typed Zod schema code for your app.
 
-### Testing Endpoints
+```ts
+import {
+  fetchAllCustomSchemaFields,
+  saveZodSchemaCode,
+} from 'cms-renderer/lib/custom-schemas';
 
-```bash
-# Start the dev server
-bun run dev
+const schemas = await fetchAllCustomSchemaFields({
+  cmsUrl: process.env.NEXT_PUBLIC_CMS_URL!,
+  apiKey: process.env.CMS_API_KEY,
+  websiteId: process.env.NEXT_PUBLIC_WEBSITE_ID!,
+});
 
-# 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"
+await saveZodSchemaCode(schemas, 'generated/cms-schemas.ts');
 ```
 
----
+Also exported:
 
-## Testing
+- `fetchCustomSchemaFields(options, schemaName)`
+- `buildZodSchemas(schemas)`
 
-The website app does not currently have unit tests. Integration testing is done via the tRPC endpoints.
+## Docs Markdown
 
-```bash
-# Type check
-bun run check-types
+`cms-renderer` includes a docs-oriented markdown boundary for starter apps and docs sites.
 
-# Lint
-bun run lint
-```
-
-Test files would live at:
-- `components/blocks/*.test.tsx` for block components
-- `server/routers/**/*.test.ts` for tRPC procedures
-
----
-
-## Troubleshooting
-
-### Port 3001 Already in Use
-
-```bash
-# Find and kill the process
-lsof -i :3001
-kill -9 <PID>
+```tsx
+import { DocsMarkdown } from 'cms-renderer/lib/docs-markdown';
+import 'cms-renderer/styles/docs-markdown.css';
 
-# Or use a different port
-bun run dev -- --port 3002
+export default async function Page() {
+  return <DocsMarkdown content={'# Hello\n\nThis came from the CMS.'} />;
+}
 ```
 
-### Cannot Find Module '@repo/cms-schema'
-
-```bash
-# Run bun install from monorepo root
-cd ../..
-bun install
-```
+`DocsMarkdown` supports:
 
-### TypeScript Errors on First Run
+- WASM-backed markdown parsing
+- Syntax-highlighted code blocks
+- Optional custom image rendering via `renderImage`
+- Default styling through `styles/docs-markdown.css`
 
-The `.next/types` directory is generated on first dev server run:
+## Live Refresh
 
-```bash
-bun run dev    # Run once to generate types
-bun run check-types  # Now type checking works
-```
+Use `Refresher` in client components to refresh the current route when CMS content changes.
+You can also provide `onInvalidate` to run app-specific invalidation before `router.refresh()`.
 
-### WASM Module Not Found
+```tsx
+'use client';
 
-If you see errors about md4w:
+import { Refresher } from 'cms-renderer/lib/refresher';
 
-```bash
-# Rebuild the markdown-wasm package
-cd ../../packages/markdown-wasm
-bun install
-bun run build
+export function CmsLiveRefresh() {
+  return (
+    <Refresher
+      cmsUrl={process.env.NEXT_PUBLIC_CMS_URL!}
+      websiteId={process.env.NEXT_PUBLIC_WEBSITE_ID!}
+      apiKey={process.env.NEXT_PUBLIC_CMS_API_KEY}
+    />
+  );
+}
 ```
 
-### tRPC 'NOT_FOUND' Error
-
-The mock data only includes pages with slugs: `demo`, `about`, `blog`. Requesting other slugs returns a 404.
+## Edit Mode
 
----
+When the page is rendered with `edit_mode=true` or `edit_mode=1`, the renderer enables editable wrappers and block toolbar behavior for CMS iframe editing.
 
-## Related Documentation
+In normal public traffic, you do not need to do anything special for edit mode.
+This mode is intended for CMS-integrated editing flows, not for public pages.
 
-- **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
+## Contributor Notes
 
----
-
-## Contributing
-
-### Code Style
-
-This project uses [Biome](https://biomejs.dev/) for linting and formatting:
+Useful package scripts:
 
 ```bash
-bun run lint        # Check for issues
-bun run lint --fix  # Auto-fix issues
+bun run build
+bun run check-types
+bun run lint
+bun run test
+bun run test:coverage
 ```
 
-### 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
-
-- Run `bun run check-types` before submitting
-- Run `bun run lint` to ensure code style compliance
-- Test the demo page at `/demo` renders correctly
+`dist/` is generated by `tsup` during build and publish.

package/dist/lib/block-renderer.js

@@ -216,7 +216,8 @@ function BlockRenderer({
     }
     return null;
   }
-  const component = /* @__PURE__ */ jsx(Component, { content: block.content, routeParams });
+  const language = routeParams ? Object.values(routeParams).find((p) => p.schemaName === "language")?.value : void 0;
+  const component = /* @__PURE__ */ jsx(Component, { content: block.content, routeParams, language });
   if (disableEditable) {
     return component;
   }