@crombolo/next-integration 0.37.0 → 0.39.0

package/dist/client.d.ts

@@ -1,5 +1,9 @@
-import type { ReactNode } from 'react';
-export declare function RichTextLinks({ children, className, }: {
-    children: ReactNode;
-    className?: string;
-}): import("react").JSX.Element;
+/**
+ * In development, refreshes the page's server components when the CMS's
+ * content or schema changes, or once this app has revalidated what a webhook
+ * named, keeping client state. Renders nothing; does nothing in production.
+ * Listens on the route `liveReloadHandler` answers.
+ */
+export declare function CromboloLiveReload({ path }: {
+    path?: string;
+}): null;

package/dist/client.js

@@ -1,26 +1,37 @@
 /** @jsxImportSource react */
 'use client';
-import { jsx as _jsx } from "react/jsx-runtime";
 /**
- * The browser half of `<RichText>` (story 208): a click on a link to a page of
- * this site navigates with Next's router rather than reloading the page.
+ * `<CromboloLiveReload />` (story 214), which refreshes the page when the CMS's
+ * content or schema changes in development.
  */
 import { useRouter } from 'next/navigation';
-export function RichTextLinks({ children, className, }) {
+import { useEffect } from 'react';
+/**
+ * In development, refreshes the page's server components when the CMS's
+ * content or schema changes, or once this app has revalidated what a webhook
+ * named, keeping client state. Renders nothing; does nothing in production.
+ * Listens on the route `liveReloadHandler` answers.
+ */
+export function CromboloLiveReload({ path = '/api/crombolo/live' }) {
     const router = useRouter();
-    const onClick = (event) => {
-        if (event.defaultPrevented || event.button !== 0)
-            return;
-        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
-            return;
-        const link = event.target.closest('a');
-        const href = link?.getAttribute('href');
-        if (!link || !href || link.target || link.hasAttribute('download'))
-            return;
-        if (!href.startsWith('/') || href.startsWith('//') || href.startsWith('/media/'))
+    useEffect(() => {
+        if (process.env.NODE_ENV !== 'development')
             return;
-        event.preventDefault();
-        router.push(href);
-    };
-    return (_jsx("div", { className: className, onClick: onClick, children: children }));
+        const events = new EventSource(path);
+        let boot;
+        events.addEventListener('hello', (event) => {
+            const id = JSON.parse(event.data).boot;
+            if (boot !== undefined && boot !== id)
+                router.refresh();
+            boot = id;
+        });
+        events.addEventListener('reload', (event) => {
+            const { reasons } = JSON.parse(event.data);
+            if (reasons?.some((reason) => reason === 'content' || reason === 'schema'))
+                router.refresh();
+        });
+        events.addEventListener('revalidated', () => router.refresh());
+        return () => events.close();
+    }, [path, router]);
+    return null;
 }

package/dist/components.d.ts

@@ -3,14 +3,30 @@
  * Server components for crombolo values (story 208): rich text, and block lists
  * and grids rendered through a component per element type.
  */
-import type { ApiBlockGrid, ApiBlockList, ApiElement, ApiRichText } from '@crombolo/delivery-client';
-import type { ComponentType } from 'react';
+import { type ApiBlockGrid, type ApiBlockList, type ApiElement, type RichTextGenericElement, type RichTextTags, type RichTextValue } from '@crombolo/delivery-client';
+import { type ComponentType, type ReactNode } from 'react';
+/** What a tag's component in `<RichText components>` is given. */
+export interface RichTextTagProps<Node = RichTextGenericElement> {
+    node: Node;
+    /** The element's attributes, ready to spread onto the tag. */
+    props: Record<string, unknown>;
+    children?: ReactNode;
+}
+/** A component per tag, in place of the tag itself; `a`, `img` and the block tags are typed. */
+export type RichTextComponents = {
+    [Tag in keyof RichTextTags]?: ComponentType<RichTextTagProps<RichTextTags[Tag]>>;
+} & {
+    [tag: string]: ComponentType<RichTextTagProps<never>> | undefined;
+};
 /**
- * Rich text as the CMS wrote it, with links to its pages navigating in the app.
- * The markup is the CMS's own, already sanitised there.
+ * Rich text, rendered from the Delivery API's tree (story 216): each tag as
+ * itself or through `components`, a link to a page as a Next link, and each
+ * block through the component for its element type in `blocks`.
  */
-export declare function RichText({ value, className, }: {
-    value: ApiRichText | null | undefined;
+export declare function RichText({ value, components, blocks, className, }: {
+    value: RichTextValue | null | undefined;
+    components?: RichTextComponents;
+    blocks?: BlockComponents;
     className?: string;
 }): import("react").JSX.Element | null;
 /** What a block's component is given. */

package/dist/components.js

@@ -1,14 +1,91 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** @jsxImportSource react */
+/**
+ * Server components for crombolo values (story 208): rich text, and block lists
+ * and grids rendered through a component per element type.
+ */
+import { decodeEntities, walkRichText, } from '@crombolo/delivery-client';
 import { draftMode } from 'next/headers';
-import { RichTextLinks } from './client.js';
+import Link from 'next/link';
+import { createElement, Fragment } from 'react';
+const VOID = new Set(['area', 'br', 'col', 'embed', 'hr', 'img', 'input', 'source', 'track', 'wbr']);
+const REACT_NAMES = {
+    class: 'className',
+    for: 'htmlFor',
+    colspan: 'colSpan',
+    rowspan: 'rowSpan',
+    tabindex: 'tabIndex',
+    srcset: 'srcSet',
+    crossorigin: 'crossOrigin',
+    referrerpolicy: 'referrerPolicy',
+    allowfullscreen: 'allowFullScreen',
+    frameborder: 'frameBorder',
+    maxlength: 'maxLength',
+    readonly: 'readOnly',
+};
+/** What the tree adds to describe a link or block, not attributes of the tag. */
+const DESCRIBING = new Set(['destinationId', 'destinationType', 'linkType', 'route', 'content-id']);
+function styleOf(css) {
+    const style = {};
+    for (const rule of css.split(';')) {
+        const colon = rule.indexOf(':');
+        if (colon === -1)
+            continue;
+        const name = rule.slice(0, colon).trim();
+        const value = rule.slice(colon + 1).trim();
+        if (!name || !value)
+            continue;
+        const key = name.startsWith('--')
+            ? name
+            : name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+        style[key] = value;
+    }
+    return style;
+}
+/** A tree element's attributes as React props: decoded, renamed, and never a handler. */
+function propsOf(node) {
+    const props = {};
+    for (const [name, value] of Object.entries(node.attributes)) {
+        if (DESCRIBING.has(name) || typeof value !== 'string' || /^on/i.test(name))
+            continue;
+        const text = decodeEntities(value);
+        if (name === 'style')
+            props.style = styleOf(text);
+        else
+            props[REACT_NAMES[name] ?? name] = text;
+    }
+    return props;
+}
+/** Where a link to a page goes in this app: its route, with any query or anchor. */
+function routeHref(node) {
+    const route = node.attributes.route;
+    return route ? `${route.path}${route.queryString ?? ''}` : undefined;
+}
 /**
- * Rich text as the CMS wrote it, with links to its pages navigating in the app.
- * The markup is the CMS's own, already sanitised there.
+ * Rich text, rendered from the Delivery API's tree (story 216): each tag as
+ * itself or through `components`, a link to a page as a Next link, and each
+ * block through the component for its element type in `blocks`.
  */
-export function RichText({ value, className, }) {
-    if (!value?.markup)
+export function RichText({ value, components = {}, blocks = {}, className, }) {
+    if (!value?.elements.length)
         return null;
-    return (_jsx(RichTextLinks, { className: className, children: _jsx("div", { dangerouslySetInnerHTML: { __html: value.markup } }) }));
+    let key = 0;
+    const nodes = walkRichText(value, {
+        text: (node) => _jsx(Fragment, { children: decodeEntities(node.text) }, key++),
+        block: (item) => item ? (_jsx(Block, { content: item.content, settings: item.settings, components: blocks }, key++)) : null,
+        element: (node, children) => {
+            const props = propsOf(node);
+            const Own = components[node.tag];
+            const inside = VOID.has(node.tag) || children.length === 0 ? undefined : children;
+            if (Own)
+                return (_jsx(Own, { node: node, props: props, children: inside }, key++));
+            const href = node.tag === 'a' ? routeHref(node) : undefined;
+            if (href)
+                return (_jsx(Link, { ...props, href: href, children: inside }, key++));
+            return createElement(node.tag, { ...props, key: key++ }, inside);
+        },
+    });
+    return _jsx("div", { className: className, children: nodes });
 }
 async function Missing({ alias }) {
     if (!(await draftMode()).isEnabled)

package/dist/index.d.ts

@@ -85,6 +85,6 @@ export declare function metadataOf(item: {
     name: string;
     seo?: ContentItem['seo'];
 } | undefined, extra?: Metadata): Metadata;
-export type { ApiBlockGrid, ApiBlockGridItem, ApiBlockList, ApiBlockListItem, ApiContent, ApiContentReference, ApiCrop, ApiElement, ApiFocalPoint, ApiLink, ApiMedia, ApiMediaReference, ApiMediaWithCrops, ApiMenu, ApiMenuItem, ApiRichText, ApiRoute, ApiSeo, MediaItem, Paged, SearchHit, } from '@crombolo/delivery-client';
-export { isExpanded } from '@crombolo/delivery-client';
+export type { ApiBlockGrid, ApiBlockGridItem, ApiBlockList, ApiBlockListItem, ApiContent, ApiContentReference, ApiCrop, ApiElement, ApiFocalPoint, ApiLink, ApiMedia, ApiMediaReference, ApiMediaWithCrops, ApiMenu, ApiMenuItem, ApiRoute, ApiSeo, MediaItem, Paged, RichTextElement, RichTextGenericElement, RichTextTextElement, RichTextValue, SearchHit, } from '@crombolo/delivery-client';
+export { decodeEntities, isExpanded, walkRichText } from '@crombolo/delivery-client';
 export type { ContentItem, ContentQuery, DeliverySchema, RequestOptions };

package/dist/index.js

@@ -202,4 +202,4 @@ export function metadataOf(item, extra = {}) {
         ...extra,
     };
 }
-export { isExpanded } from '@crombolo/delivery-client';
+export { decodeEntities, isExpanded, walkRichText } from '@crombolo/delivery-client';

package/dist/route-handlers.d.ts

@@ -42,3 +42,11 @@ export declare function memberHandlers(crombolo: Crombolo, options: MemberHandle
  * `web/app/media/[...path]/route.ts`.
  */
 export declare function mediaHandler(crombolo: Crombolo): (request: Request) => Promise<Response>;
+/** Where the CMS streams its changes in development. */
+export declare const CMS_LIVE_EVENTS_PATH = "/crombolo/dev/events";
+/**
+ * `GET` for `<CromboloLiveReload />` in development: the CMS's change stream,
+ * and a `revalidated` event once this app has cleared what a webhook named, so
+ * a refresh after it shows the new content. 404 outside development.
+ */
+export declare function liveReloadHandler(crombolo: Crombolo): (request: Request) => Promise<Response>;

package/dist/route-handlers.js

@@ -1,7 +1,8 @@
 /**
  * Route handlers a Next.js app mounts (story 208): Draft Mode on and off from
  * the CMS's Preview button, revalidation from its webhook, a member's sign-in
- * and sign-out with PKCE, and media fetched with the member's token.
+ * and sign-out with PKCE, media fetched with the member's token, and the CMS's
+ * changes for live reload in development (story 214).
  *
  * ```ts
  * // web/app/api/crombolo/preview/route.ts
@@ -91,6 +92,7 @@ export function revalidateHandler(crombolo, options = {}) {
         if (keys.length === 0)
             return new Response('The payload names no item.', { status: 400 });
         crombolo.revalidate(keys);
+        announceRevalidation(keys);
         return Response.json({ revalidated: keys });
     };
 }
@@ -234,3 +236,80 @@ export function mediaHandler(crombolo) {
         return new Response(answer.body, { status: answer.status, headers: out });
     };
 }
+/** Where the CMS streams its changes in development. */
+export const CMS_LIVE_EVENTS_PATH = '/crombolo/dev/events';
+/**
+ * On the global object: Next.js may bundle this module once per route, and
+ * the revalidate route must reach the live route's listeners.
+ */
+const REVALIDATED = Symbol.for('crombolo.next.revalidated');
+function revalidationListeners() {
+    const holder = globalThis;
+    holder[REVALIDATED] ??= new Set();
+    return holder[REVALIDATED];
+}
+function announceRevalidation(keys) {
+    for (const listener of revalidationListeners())
+        listener(keys);
+}
+const encoder = new TextEncoder();
+/**
+ * `GET` for `<CromboloLiveReload />` in development: the CMS's change stream,
+ * and a `revalidated` event once this app has cleared what a webhook named, so
+ * a refresh after it shows the new content. 404 outside development.
+ */
+export function liveReloadHandler(crombolo) {
+    return async (request) => {
+        if (process.env.NODE_ENV !== 'development')
+            return new Response('Not Found', { status: 404 });
+        const upstream = await fetch(new URL(CMS_LIVE_EVENTS_PATH, crombolo.options.url), {
+            headers: { accept: 'text/event-stream' },
+            signal: request.signal,
+        }).catch(() => undefined);
+        if (!upstream?.ok || !upstream.body)
+            return new Response('The CMS is not streaming its changes.', { status: 502 });
+        const reader = upstream.body.getReader();
+        const decoder = new TextDecoder();
+        let listener;
+        const body = new ReadableStream({
+            async start(controller) {
+                listener = (keys) => controller.enqueue(encoder.encode(`event: revalidated\ndata: ${JSON.stringify({ keys })}\n\n`));
+                revalidationListeners().add(listener);
+                // Whole frames only, so a `revalidated` event never lands inside one of the CMS's.
+                let buffered = '';
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        buffered += decoder.decode(value, { stream: true });
+                        const end = buffered.lastIndexOf('\n\n');
+                        if (end < 0)
+                            continue;
+                        controller.enqueue(encoder.encode(buffered.slice(0, end + 2)));
+                        buffered = buffered.slice(end + 2);
+                    }
+                }
+                catch {
+                    // The page left, or the CMS restarted; the browser reconnects either way.
+                }
+                finally {
+                    if (listener)
+                        revalidationListeners().delete(listener);
+                    try {
+                        controller.close();
+                    }
+                    catch { }
+                }
+            },
+            cancel() {
+                if (listener)
+                    revalidationListeners().delete(listener);
+                void reader.cancel().catch(() => { });
+            },
+        });
+        return new Response(body, {
+            headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store' },
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/next-integration",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "A Next.js App Router front end for a crombolo site: pages, metadata, preview, revalidation, members, images and content components.",
   "license": "MIT",
   "author": "Crombolo",
@@ -69,8 +69,8 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@crombolo/common": "0.37.0",
-    "@crombolo/delivery-client": "0.37.0"
+    "@crombolo/common": "0.39.0",
+    "@crombolo/delivery-client": "0.39.0"
   },
   "peerDependencies": {
     "next": ">=15.5 <17",