@crombolo/next-integration 0.0.0-stage → 0.37.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/dist/cache-15.d.ts

@@ -0,0 +1,2 @@
+import { type CacheAdapter } from './cache.ts';
+export declare const cache15: CacheAdapter;

package/dist/cache-15.js

@@ -0,0 +1,22 @@
+/**
+ * Next.js 15's cache for `createCrombolo` (story 208). Next 15 tags a fetch
+ * before it runs, so the keys an answer holds cannot tag it: every answer is
+ * kept under the site's tag, and any change clears them all.
+ */
+import { revalidateTag } from 'next/cache';
+import { keptHeaders, SITE_TAG } from './cache.js';
+export const cache15 = {
+    major: 15,
+    async answer(url, headers) {
+        const response = await fetch(url, {
+            headers,
+            next: { tags: [SITE_TAG], revalidate: false },
+        });
+        const body = await response.text();
+        return { status: response.status, body, headers: keptHeaders(response.headers) };
+    },
+    revalidate() {
+        ;
+        revalidateTag(SITE_TAG);
+    },
+};

package/dist/cache-16.d.ts

@@ -0,0 +1,3 @@
+import { type CacheAdapter, type KeptAnswer } from './cache.ts';
+export declare function keptAnswer(url: string, headers: Record<string, string>): Promise<KeptAnswer>;
+export declare const cache16: CacheAdapter;

package/dist/cache-16.js

@@ -0,0 +1,27 @@
+/**
+ * Next.js 16's cache for `createCrombolo` (story 208): `'use cache'`, tagged
+ * from each answer with `cacheTag`, so a publish clears exactly what holds the
+ * page and its ancestors. Needs `cacheComponents: true` in `next.config.ts`.
+ */
+import { cacheLife, cacheTag, revalidateTag } from 'next/cache';
+import { keptHeaders, MISSING_TAG, tagOf, tagsFor, unkept, } from './cache.js';
+export async function keptAnswer(url, headers) {
+    'use cache';
+    const response = await fetch(url, { headers });
+    const body = await response.text();
+    // Kept for as long as nothing changes; the webhook says when something does.
+    if (unkept(response.headers))
+        cacheLife('seconds');
+    else
+        cacheLife('max');
+    cacheTag(...tagsFor(response.status, body, response.headers));
+    return { status: response.status, body, headers: keptHeaders(response.headers) };
+}
+export const cache16 = {
+    major: 16,
+    answer: keptAnswer,
+    revalidate(keys) {
+        for (const tag of [MISSING_TAG, ...keys.map(tagOf)])
+            revalidateTag(tag, 'max');
+    },
+};

package/dist/cache.d.ts

@@ -0,0 +1,23 @@
+export interface KeptAnswer {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+}
+export interface CacheAdapter {
+    readonly major: 15 | 16;
+    /** The answer at `url`, from Next's cache when it holds one. */
+    answer(url: string, headers: Record<string, string>): Promise<KeptAnswer>;
+    /** Clears every kept answer holding one of these keys, and every kept not-found. */
+    revalidate(keys: readonly string[]): void;
+}
+/** Every adapter's answers carry this, so a whole site can be cleared at once. */
+export declare const SITE_TAG = "crombolo";
+/** Kept not-found answers, cleared on every change: a new page may answer one. */
+export declare const MISSING_TAG = "crombolo:missing";
+export declare const tagOf: (key: string) => string;
+/** The tags an answer is kept under: the site's, and each key it holds or the site named. */
+export declare function tagsFor(status: number, body: string, headers: Headers): string[];
+/** Whether the site said not to keep it: a redirect, a form, anything personal. */
+export declare function unkept(headers: Headers): boolean;
+/** The headers a kept answer needs to be read again. */
+export declare function keptHeaders(headers: Headers): Record<string, string>;

package/dist/cache.js

@@ -0,0 +1,42 @@
+/**
+ * What a caching adapter does for `createCrombolo`, one per Next.js major
+ * (story 208): keep the Delivery API's answers in Next's cache, tagged with the
+ * content they hold, and clear them when the site says it changed.
+ */
+import { contentKeysIn } from '@crombolo/delivery-client';
+/** Every adapter's answers carry this, so a whole site can be cleared at once. */
+export const SITE_TAG = 'crombolo';
+/** Kept not-found answers, cleared on every change: a new page may answer one. */
+export const MISSING_TAG = 'crombolo:missing';
+/** Next.js keeps at most this many tags on one entry. */
+const MAX_TAGS = 128;
+export const tagOf = (key) => `crombolo:${key.toLowerCase()}`;
+/** The tags an answer is kept under: the site's, and each key it holds or the site named. */
+export function tagsFor(status, body, headers) {
+    if (status === 404)
+        return [SITE_TAG, MISSING_TAG];
+    let parsed = null;
+    try {
+        parsed = body ? JSON.parse(body) : null;
+    }
+    catch { }
+    const named = (headers.get('surrogate-key') ?? headers.get('cache-tag') ?? '')
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    const keys = new Set([...contentKeysIn(parsed), ...named.map((k) => k.toLowerCase())]);
+    return [SITE_TAG, ...[...keys].map(tagOf)].slice(0, MAX_TAGS);
+}
+/** Whether the site said not to keep it: a redirect, a form, anything personal. */
+export function unkept(headers) {
+    return /\b(no-store|private)\b/i.test(headers.get('cache-control') ?? '');
+}
+/** The headers a kept answer needs to be read again. */
+export function keptHeaders(headers) {
+    const out = {};
+    for (const name of ['content-type', 'etag', 'cache-control', 'surrogate-key', 'cache-tag']) {
+        const value = headers.get(name);
+        if (value !== null)
+            out[name] = value;
+    }
+    return out;
+}

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+export declare function RichTextLinks({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/client.js

@@ -0,0 +1,26 @@
+/** @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.
+ */
+import { useRouter } from 'next/navigation';
+export function RichTextLinks({ children, className, }) {
+    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/'))
+            return;
+        event.preventDefault();
+        router.push(href);
+    };
+    return (_jsx("div", { className: className, onClick: onClick, children: children }));
+}

package/dist/components.d.ts

@@ -0,0 +1,31 @@
+/** @jsxImportSource react */
+/**
+ * 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';
+/**
+ * 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.
+ */
+export declare function RichText({ value, className, }: {
+    value: ApiRichText | null | undefined;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** What a block's component is given. */
+export interface BlockComponentProps<Content = ApiElement, Settings = ApiElement> {
+    content: Content;
+    settings: Settings | null;
+}
+export type BlockComponents = Record<string, ComponentType<BlockComponentProps<never, never>>>;
+/** A block list, each item through the component for its element type. */
+export declare function BlockList({ value, components, }: {
+    value: ApiBlockList | null | undefined;
+    components: BlockComponents;
+}): import("react").JSX.Element | null;
+/** A block grid, laid out in its columns, areas included. */
+export declare function BlockGrid({ value, components, }: {
+    value: ApiBlockGrid | null | undefined;
+    components: BlockComponents;
+}): import("react").JSX.Element | null;

package/dist/components.js

@@ -0,0 +1,45 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { draftMode } from 'next/headers';
+import { RichTextLinks } from './client.js';
+/**
+ * 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.
+ */
+export function RichText({ value, className, }) {
+    if (!value?.markup)
+        return null;
+    return (_jsx(RichTextLinks, { className: className, children: _jsx("div", { dangerouslySetInnerHTML: { __html: value.markup } }) }));
+}
+async function Missing({ alias }) {
+    if (!(await draftMode()).isEnabled)
+        return null;
+    return (_jsxs("div", { "data-crombolo-missing-block": alias, style: { border: '1px dashed #c00', padding: '1rem' }, children: ["There is no component for the block \u201C", alias, "\u201D yet."] }));
+}
+function Block({ content, settings, components, }) {
+    if (!content)
+        return null;
+    const Component = components[content.contentType];
+    return Component ? (_jsx(Component, { content: content, settings: settings })) : (_jsx(Missing, { alias: content.contentType }));
+}
+/** A block list, each item through the component for its element type. */
+export function BlockList({ value, components, }) {
+    if (!value?.items.length)
+        return null;
+    return (_jsx(_Fragment, { children: value.items.map((item, index) => (_jsx(Block, { content: item.content, settings: item.settings, components: components }, item.content?.id ?? index))) }));
+}
+function GridItems({ items, components, }) {
+    return (_jsx(_Fragment, { children: items.map((item, index) => (_jsxs("div", { className: "crombolo-grid-item", style: { gridColumn: `span ${item.columnSpan}`, gridRow: `span ${item.rowSpan}` }, children: [_jsx(Block, { content: item.content, settings: item.settings, components: components }), item.areas.map((area) => (_jsx("div", { className: "crombolo-grid-area", "data-area": area.alias, style: {
+                        display: 'grid',
+                        gridTemplateColumns: `repeat(${item.areaGridColumns}, minmax(0, 1fr))`,
+                        gridColumn: `span ${area.columnSpan}`,
+                    }, children: _jsx(GridItems, { items: area.items, components: components }) }, area.alias)))] }, item.content?.id ?? index))) }));
+}
+/** A block grid, laid out in its columns, areas included. */
+export function BlockGrid({ value, components, }) {
+    if (!value?.items.length)
+        return null;
+    return (_jsx("div", { className: "crombolo-grid", style: {
+            display: 'grid',
+            gridTemplateColumns: `repeat(${value.gridColumns}, minmax(0, 1fr))`,
+        }, children: _jsx(GridItems, { items: value.items, components: components }) }));
+}

package/dist/image-loader.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `next/image` for crombolo media (story 208): the CMS resizes, so the loader
+ * writes its imaging query rather than Next's optimiser doing the work.
+ *
+ * ```ts
+ * // next.config.ts
+ * images: { loader: 'custom', loaderFile: './lib/image-loader.ts' }
+ * // lib/image-loader.ts
+ * export { default } from '@crombolo/next-integration/image-loader'
+ * ```
+ */
+import type { ApiCrop, ApiFocalPoint } from '@crombolo/delivery-client';
+export interface ImageLoaderProps {
+    src: string;
+    width: number;
+    quality?: number;
+}
+/** Adds the width, quality and a modern format to a media address, keeping a crop it carries. */
+export default function cromboloImageLoader({ src, width, quality }: ImageLoaderProps): string;
+/** What a picked image needs for `<Image>`: an address carrying its crop or focal point, and its size. */
+export declare function cromboloImage(media: {
+    url: string;
+    width: number | null;
+    height: number | null;
+    name: string;
+    focalPoint?: ApiFocalPoint | null;
+    crops?: ApiCrop[] | null;
+}, options?: {
+    crop?: string;
+    alt?: string;
+}): {
+    src: string;
+    width: number;
+    height: number;
+    alt: string;
+};

package/dist/image-loader.js

@@ -0,0 +1,37 @@
+/** Adds the width, quality and a modern format to a media address, keeping a crop it carries. */
+export default function cromboloImageLoader({ src, width, quality }) {
+    const [path, query = ''] = src.split('?');
+    const params = new URLSearchParams(query);
+    params.set('width', String(width));
+    if (!params.has('quality'))
+        params.set('quality', String(quality ?? 75));
+    if (!params.has('format'))
+        params.set('format', 'webp');
+    return `${path}?${params.toString()}`;
+}
+/** What a picked image needs for `<Image>`: an address carrying its crop or focal point, and its size. */
+export function cromboloImage(media, options = {}) {
+    const params = new URLSearchParams();
+    const crop = options.crop ? media.crops?.find((c) => c.alias === options.crop) : undefined;
+    let width = media.width ?? 0;
+    let height = media.height ?? 0;
+    if (crop) {
+        width = crop.width;
+        height = crop.height;
+        if (crop.coordinates) {
+            const { x1, y1, x2, y2 } = crop.coordinates;
+            params.set('cc', [x1, y1, x2, y2].join(','));
+        }
+        else if (media.focalPoint)
+            params.set('rxy', `${media.focalPoint.left},${media.focalPoint.top}`);
+    }
+    else if (media.focalPoint)
+        params.set('rxy', `${media.focalPoint.left},${media.focalPoint.top}`);
+    const query = params.toString();
+    return {
+        src: query ? `${media.url}?${query}` : media.url,
+        width,
+        height,
+        alt: options.alt ?? media.name,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A Next.js App Router front end for a crombolo site (story 208).
+ *
+ * `createCrombolo()` wraps the typed Delivery API client for server
+ * components: answers kept in Next's cache and tagged by the content they hold,
+ * drafts in Draft Mode, a member's own reads, route lookup as a `Result`, and
+ * Next's `Metadata` from a page's search and sharing details.
+ * docs/delivery-api.md, "A Next.js front end".
+ */
+import { type Result } from '@crombolo/common';
+import { type ContentItem, type ContentQuery, type DeliveryClient, type DeliverySchema, type RequestOptions } from '@crombolo/delivery-client';
+import type { Metadata } from 'next';
+import type { CacheAdapter } from './cache.ts';
+import { type MemberSession } from './session.ts';
+export { assertSafeLocation, type FieldError, isOk, isOutcome, type MatchHandlers, Ok, Outcome, type OutcomeStatus, ok, Result, } from '@crombolo/common';
+export type { CacheAdapter, KeptAnswer } from './cache.ts';
+export { SITE_TAG, tagOf, tagsFor } from './cache.ts';
+export type { MemberSession } from './session.ts';
+export interface CromboloOptions {
+    /** The CMS's address, such as `https://cms.example.com`. */
+    url: string;
+    /** The Delivery API key, for a site whose API is not public, and for preview. */
+    apiKey?: string;
+    /** Next's cache, from `./cache-16` or `./cache-15`; without one, every read revalidates by ETag. */
+    cache?: CacheAdapter;
+    /** `etag` revalidates every read rather than keeping it until the webhook clears it. */
+    revalidate?: 'tags' | 'etag';
+    /** The hostname routes resolve for, as the site's domains pick a root and culture. */
+    host?: string;
+    culture?: string;
+    startItem?: string;
+    /** `CROMBOLO_NEXT_SECRET`, which seals a member's session; read from the environment when unset. */
+    secret?: string;
+    /** The Delivery API's path, when the site serves it somewhere else. */
+    apiPath?: string;
+}
+/** What a page lookup can answer instead of a page. */
+export type PageStatus = 301 | 302 | 303 | 307 | 308 | 401 | 403 | 404;
+/** The reads a page makes, through whichever client the request calls for. */
+export interface CromboloReads<Schema extends DeliverySchema = DeliverySchema> {
+    readonly client: DeliveryClient<Schema>;
+    /** The page at an address, a redirect, or a refusal, as the site would answer it. */
+    page(path: string, options?: {
+        host?: string;
+        expand?: string;
+    }): Promise<Result<ContentItem<Schema>, PageStatus>>;
+    /** `page()` ended with Next's own `redirect`, `permanentRedirect`, `notFound`, `unauthorized` or `forbidden`. */
+    resolvePage(path: string, options?: {
+        host?: string;
+        expand?: string;
+    }): Promise<ContentItem<Schema>>;
+    /** The site's not-found page for a hostname, when it has one. */
+    notFoundPage(options?: {
+        host?: string;
+    }): Promise<ContentItem<Schema> | undefined>;
+    item: DeliveryClient<Schema>['item'];
+    items: DeliveryClient<Schema>['items'];
+    content: DeliveryClient<Schema>['content'];
+    mediaItem: DeliveryClient<Schema>['mediaItem'];
+    media: DeliveryClient<Schema>['media'];
+    menu: DeliveryClient<Schema>['menu'];
+    search: DeliveryClient<Schema>['search'];
+    form: DeliveryClient<Schema>['form'];
+    sitemap: DeliveryClient<Schema>['sitemap'];
+}
+export interface Crombolo<Schema extends DeliverySchema = DeliverySchema> extends CromboloReads<Schema> {
+    readonly options: CromboloOptions;
+    /** Reads revalidated by ETag on every call, for a page rendered per request. */
+    readonly fresh: CromboloReads<Schema>;
+    /**
+     * The signed-in member's reads, never kept, or undefined for a visitor.
+     * Reads the session cookie, so the page renders per request.
+     */
+    member(): Promise<(CromboloReads<Schema> & {
+        session: MemberSession;
+    }) | undefined>;
+    /** Next's `Metadata` from a page's search and sharing details (`seo: true`). */
+    metadata(item: ContentItem<Schema> | undefined, extra?: Metadata): Metadata;
+    /** Clears every kept answer holding these keys. */
+    revalidate(keys: readonly string[]): void;
+}
+export declare function createCrombolo<Schema extends DeliverySchema = DeliverySchema>(options: CromboloOptions): Crombolo<Schema>;
+/** Next's `Metadata` from a page's `seo` details; `extra` wins field by field. Pure. */
+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 { ContentItem, ContentQuery, DeliverySchema, RequestOptions };