camox 0.43.0 → 0.45.0

package/dist/features/runtime/pageClient.js

@@ -1,17 +1,32 @@
+import { createDraftScope } from "../../lib/draft-scope.js";
+import { restoreArtifactSources } from "./artifactSources.js";
+import { getPageBlockTypes } from "./pageBlockTypes.js";
+import { loadRuntimeChrome } from "./runtimeChromeLoader.js";
 import { PageApp } from "./pageApp.js";
 import { readHydrationData } from "./hydrationData.js";
-import { QueryClient } from "@tanstack/react-query";
 import { jsx } from "react/jsx-runtime";
+import { QueryClient } from "@tanstack/react-query";
 import { hydrateRoot } from "react-dom/client";
 
 //#region src/features/runtime/pageClient.tsx
-function hydratePageWithApp(camoxApp) {
+async function hydratePageWithApp(camoxApp) {
 	const root = document.getElementById("root");
 	if (!root) throw new Error("Camox runtime root element was not found.");
 	const queryClient = new QueryClient();
+	const hydrationData = readHydrationData();
+	const input = {
+		...hydrationData,
+		dehydratedState: restoreArtifactSources(hydrationData.dehydratedState, root)
+	};
+	await Promise.all([camoxApp.loadBlocks(getPageBlockTypes(input.dehydratedState)).catch((error) => console.error("Camox: a block of this page failed to load.", error)), input.presentation === "studio" ? loadRuntimeChrome() : void 0]);
+	const draftScope = createDraftScope({
+		queryClient,
+		browser: window
+	});
 	hydrateRoot(root, /* @__PURE__ */ jsx(PageApp, {
 		camoxApp,
-		input: readHydrationData(),
+		draftScope,
+		input,
 		queryClient
 	}));
 }

package/dist/features/runtime/pageNavigation.js

@@ -1,61 +1,156 @@
+import { DraftScopeContext, draftNamedBy } from "../../lib/draft-scope.js";
+import { PageAlternatesContext, ViewLocaleContext } from "../../lib/view-locale-context.js";
 import { NavigationProvider } from "../navigation/navigation.js";
+import { fetchRuntimeJson, getNavigationTarget } from "./navigationTarget.js";
+import { reads } from "../../lib/studio-reads.js";
+import { createPrefetchCache, listenForLinkIntent } from "./linkPrefetch.js";
+import { PageViewportContext } from "./pageViewport.js";
+import { sendPageView } from "./analytics.js";
+import { getPageBlockTypes } from "./pageBlockTypes.js";
 import { createPageHeadInput } from "./runtime.js";
+import { createRouteAnnouncer, focusNewPage } from "./navigationAccessibility.js";
 import { createNavigationRequestTracker } from "./navigationRequest.js";
-import { getNavigationTarget, runtimePath } from "./navigationTarget.js";
-import { hydrate } from "@tanstack/react-query";
+import { createScrollRestoration } from "./scrollRestoration.js";
+import { c } from "react/compiler-runtime";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
+import { hydrate } from "@tanstack/react-query";
 import { createHead, renderDOMHead } from "@unhead/react/client";
 
 //#region src/features/runtime/pageNavigation.tsx
 function preserveStableLayoutBlockCaches(dehydratedState, current, next) {
-	if (!current || !next || current.id !== next.id || current.layoutId !== next.layoutId || current.version !== next.version) return dehydratedState;
+	if (!current || !next || current.layoutId !== next.layoutId || current.version !== next.version) return dehydratedState;
 	if (!dehydratedState || typeof dehydratedState !== "object" || !("queries" in dehydratedState) || !Array.isArray(dehydratedState.queries)) return dehydratedState;
 	const ids = new Set(current.blockIds);
 	return {
 		...dehydratedState,
 		queries: dehydratedState.queries.filter((query) => {
-			const key = query.queryKey;
-			return !(key?.[0] === "camox" && key[1] === "blocks" && key[2] === "get" && typeof key[3] === "number" && ids.has(key[3]));
+			const blockId = query.queryKey && reads.blockBundle.paramsOf(query.queryKey);
+			return !(blockId && ids.has(blockId));
 		})
 	};
 }
-function PageNavigationProvider({ children, initialInput, queryClient }) {
-	const [input, setInput] = React.useState(initialInput);
+function sameLocale(a, b) {
+	return a.tag === b.tag && a.isDefault === b.isDefault;
+}
+/**
+* `value`, kept while it says the same: each render's response is new JSON, which would otherwise
+* give every consumer a new value.
+*/
+function useSameJson(value) {
+	const $ = c(4);
+	let t0;
+	if ($[0] !== value) {
+		t0 = JSON.stringify(value);
+		$[0] = value;
+		$[1] = t0;
+	} else t0 = $[1];
+	const json = t0;
+	let t1;
+	if ($[2] !== json) {
+		t1 = JSON.parse(json);
+		$[2] = json;
+		$[3] = t1;
+	} else t1 = $[3];
+	return t1;
+}
+function prefetchKey(pathname, draft) {
+	return JSON.stringify({
+		pathname,
+		draft
+	});
+}
+function PageNavigationProvider({ camoxApp, children, initialInput, queryClient }) {
+	const draftScope = React.useContext(DraftScopeContext);
+	if (!draftScope) throw new Error("PageNavigationProvider needs a DraftScopeContext provider");
+	const [{ input, source, generation }, setLocation] = React.useState(() => {
+		draftScope.adopt(initialInput);
+		return {
+			input: initialInput,
+			generation: 0
+		};
+	});
 	const current = React.useRef(initialInput);
 	const [requests] = React.useState(createNavigationRequestTracker);
+	const ownsWindow = initialInput.presentation !== "studio";
+	const scroll = React.useRef(null);
+	const restoration = React.useCallback(() => scroll.current ??= createScrollRestoration(window), []);
+	const pendingScroll = React.useRef(null);
+	const takeScroll = (href) => {
+		const pending = pendingScroll.current;
+		if (pending?.href !== href) return null;
+		pendingScroll.current = null;
+		return pending.intent;
+	};
+	const position = React.useCallback((viewport, intent, href) => {
+		const fragment = restoration().apply(viewport, intent, new URL(href).hash);
+		if (intent !== "resume" && (fragment || intent !== "fragment")) focusNewPage(viewport.document, fragment);
+	}, [restoration]);
+	const pendingAnnouncement = React.useRef(null);
+	const announcer = React.useRef(null);
+	const loadPage = React.useCallback(async (pathname, draft, signal) => {
+		const response = await fetchRuntimeJson(draftScope, "/_camox/data", initialInput.runtimeBasePath, { path: pathname }, draft, signal);
+		if (!response.ok) throw new Error(`Navigation failed: ${response.status}`);
+		const next = await response.json();
+		if (next.pathname !== pathname || !next.dehydratedState) throw new Error("Invalid navigation response");
+		await camoxApp.loadBlocks(getPageBlockTypes(next.dehydratedState));
+		return next;
+	}, [
+		camoxApp,
+		draftScope,
+		initialInput.runtimeBasePath
+	]);
+	const [prefetched] = React.useState(() => createPrefetchCache());
 	const headManager = React.useRef(null);
-	const navigate = React.useCallback(async ({ to, replace, pop = false }) => {
+	const { analytics } = initialInput;
+	const navigate = React.useCallback(async ({ to, replace, source, draft, pop = false, refresh = false }) => {
 		const request = requests.begin();
-		const target = getNavigationTarget(to, window.location.href, initialInput.runtimeBasePath);
+		const href = pop ? to : draftScope.hrefFor(to, {
+			from: window.location.href,
+			draft
+		});
+		const target = getNavigationTarget(href, window.location.href, initialInput.runtimeBasePath);
 		if (!target) {
 			if (replace) window.location.replace(to);
 			else window.location.assign(to);
 			return;
 		}
+		if (pop) restoration().save();
+		if (!pop && !refresh && target.url.href === current.current.href) {
+			const viewport = restoration().viewport();
+			if (target.url.hash && viewport) position(viewport, "fragment", target.url.href);
+			return;
+		}
 		try {
 			let next = current.current;
-			if (target.pathname !== next.pathname || pop) {
-				const url = new URL(runtimePath("/_camox/data", initialInput.runtimeBasePath), window.location.origin);
-				url.searchParams.set("path", target.pathname);
-				const response = await fetch(url, {
-					credentials: "same-origin",
-					headers: { Accept: "application/json" },
-					signal: request.signal
-				});
-				if (!response.ok) throw new Error(`Navigation failed: ${response.status}`);
-				next = await response.json();
-				if (next.pathname !== target.pathname || !next.dehydratedState) throw new Error("Invalid navigation response");
-			}
+			const targetDraft = draftNamedBy(target.url.href);
+			const fetched = target.pathname !== next.pathname || refresh || targetDraft !== draftNamedBy(next.href);
+			if (fetched) next = await (!refresh && prefetched.take(prefetchKey(target.pathname, targetDraft)) || loadPage(target.pathname, targetDraft, request.signal));
 			if (!request.isCurrent()) return;
-			hydrate(queryClient, preserveStableLayoutBlockCaches(next.dehydratedState, current.current.layoutIdentity, next.layoutIdentity));
+			const switching = (next.draftId ?? null) !== (current.current.draftId ?? null) || !sameLocale(next.locale, current.current.locale);
+			const positions = restoration();
+			if (!pop) {
+				if (replace || refresh) window.history.replaceState(window.history.state, "", target.url.href);
+				else {
+					positions.save();
+					window.history.pushState(positions.stateForNewEntry(), "", target.url.href);
+				}
+			}
+			positions.entered();
+			const intent = pop ? "restore" : refresh || replace && !fetched ? null : fetched ? "enter" : "fragment";
+			pendingScroll.current = intent && {
+				href: window.location.href,
+				intent
+			};
+			pendingAnnouncement.current = fetched && !refresh ? next.pathname : null;
+			if (fetched) draftScope.adopt(next);
+			hydrate(queryClient, switching ? next.dehydratedState : preserveStableLayoutBlockCaches(next.dehydratedState, current.current.layoutIdentity, next.layoutIdentity));
 			next = {
 				...next,
-				href: target.url.href
+				href: window.location.href
 			};
+			const previous = current.current;
 			current.current = next;
-			if (!pop) if (replace) window.history.replaceState(null, "", target.url.href);
-			else window.history.pushState(null, "", target.url.href);
 			if (!headManager.current) {
 				document.querySelectorAll("[data-camox-page-head]").forEach((element) => element.remove());
 				headManager.current = { head: createHead() };
@@ -64,8 +159,13 @@ function PageNavigationProvider({ children, initialInput, queryClient }) {
 			manager.entry?.dispose();
 			manager.entry = manager.head.push(createPageHeadInput(next.head ?? {}));
 			renderDOMHead(manager.head);
-			React.startTransition(() => setInput(next));
-			if (!pop && !replace && !target.url.hash) window.scrollTo({ top: 0 });
+			if (ownsWindow && analytics && next.pathname !== previous.pathname) sendPageView(analytics, window);
+			if (ownsWindow) document.documentElement.lang = next.locale.tag;
+			React.startTransition(() => setLocation((location) => ({
+				input: next,
+				source: pop ? void 0 : source,
+				generation: location.generation + (switching ? 1 : 0)
+			})));
 		} catch {
 			if (!request.isCurrent()) return;
 			if (pop) window.location.reload();
@@ -73,10 +173,117 @@ function PageNavigationProvider({ children, initialInput, queryClient }) {
 			else window.location.assign(target.url.href);
 		}
 	}, [
+		analytics,
+		draftScope,
 		initialInput.runtimeBasePath,
+		loadPage,
+		ownsWindow,
+		position,
+		prefetched,
 		queryClient,
-		requests
+		requests,
+		restoration
+	]);
+	const prefetchLink = React.useCallback((anchor) => {
+		if (anchor.hasAttribute("download") || anchor.target && anchor.target !== "_self") return;
+		const href = draftScope.hrefFor(anchor.href, { from: window.location.href });
+		const target = getNavigationTarget(href, window.location.href, initialInput.runtimeBasePath);
+		if (!target || target.pathname === current.current.pathname) return;
+		const draft = draftNamedBy(target.url.href);
+		prefetched.prefetch(prefetchKey(target.pathname, draft), () => loadPage(target.pathname, draft, new AbortController().signal));
+	}, [
+		draftScope,
+		initialInput.runtimeBasePath,
+		loadPage,
+		prefetched
+	]);
+	const pageViewport = React.useMemo(() => ({
+		opened(viewport, href) {
+			restoration().apply(viewport, takeScroll(href) ?? "restore", new URL(href).hash);
+		},
+		placed(href) {
+			takeScroll(href);
+		},
+		attach(viewport) {
+			restoration().setViewport(viewport);
+			return () => {
+				const positions = restoration();
+				if (positions.viewport() === viewport) positions.setViewport(ownsWindow ? window : null);
+			};
+		},
+		prefetchLink
+	}), [
+		ownsWindow,
+		position,
+		prefetchLink,
+		restoration
 	]);
+	React.useEffect(() => {
+		const positions = restoration();
+		if (ownsWindow) {
+			positions.setViewport(window);
+			positions.apply(window, "resume", window.location.hash);
+		}
+		announcer.current = createRouteAnnouncer(document);
+		return () => {
+			announcer.current?.dispose();
+			announcer.current = null;
+			scroll.current?.dispose();
+			scroll.current = null;
+		};
+	}, [ownsWindow, restoration]);
+	const firstPageView = React.useRef(false);
+	React.useEffect(() => {
+		if (!ownsWindow || !analytics || firstPageView.current) return;
+		firstPageView.current = true;
+		sendPageView(analytics, window);
+	}, [analytics, ownsWindow]);
+	React.useEffect(() => {
+		if (!ownsWindow) return;
+		return listenForLinkIntent(document, prefetchLink);
+	}, [ownsWindow, prefetchLink]);
+	React.useEffect(() => {
+		const unsubscribe = draftScope.subscribe(() => prefetched.clear());
+		return () => {
+			unsubscribe();
+			prefetched.clear();
+		};
+	}, [draftScope, prefetched]);
+	React.useLayoutEffect(() => {
+		const intent = takeScroll(input.href);
+		const viewport = scroll.current?.viewport();
+		if (intent && viewport) position(viewport, intent, input.href);
+		const announced = pendingAnnouncement.current;
+		pendingAnnouncement.current = null;
+		if (announced) {
+			const viewport = scroll.current?.viewport();
+			announcer.current?.announce(viewport?.document ?? document, announced);
+		}
+	}, [input]);
+	React.useEffect(() => {
+		const adoptBrowserUrl = () => {
+			const url = new URL(window.location.href);
+			if (url.href === current.current.href || url.pathname !== new URL(current.current.href).pathname) return;
+			const next = {
+				...current.current,
+				href: url.href,
+				draftId: draftScope.current() ?? void 0
+			};
+			current.current = next;
+			setLocation((location) => ({
+				...location,
+				input: next
+			}));
+		};
+		adoptBrowserUrl();
+		return draftScope.subscribe(({ move }) => {
+			if (move === "started") return adoptBrowserUrl();
+			if (move === "left") navigate({
+				to: window.location.href,
+				refresh: true
+			});
+		});
+	}, [draftScope, navigate]);
 	React.useEffect(() => {
 		const onClick = (event) => {
 			if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
@@ -102,16 +309,31 @@ function PageNavigationProvider({ children, initialInput, queryClient }) {
 		initialInput.runtimeBasePath,
 		requests
 	]);
-	const url_0 = new URL(input.href);
+	const url = new URL(input.href);
+	const viewLocale = useSameJson({
+		locale: input.locale,
+		locales: input.locales
+	});
+	const alternates = useSameJson(input.alternates ?? null);
 	return /* @__PURE__ */ jsx(NavigationProvider, {
 		location: {
 			href: input.href,
 			pathname: input.pathname,
-			hash: url_0.hash,
-			search: url_0.search
+			hash: url.hash,
+			search: url.search,
+			source
 		},
 		navigate,
-		children: children(input)
+		children: /* @__PURE__ */ jsx(ViewLocaleContext, {
+			value: viewLocale,
+			children: /* @__PURE__ */ jsx(PageAlternatesContext, {
+				value: alternates,
+				children: /* @__PURE__ */ jsx(PageViewportContext, {
+					value: pageViewport,
+					children: /* @__PURE__ */ jsx(React.Fragment, { children: children(input) }, generation)
+				})
+			})
+		})
 	});
 }
 

package/dist/features/runtime/pageServer.d.ts

@@ -1,9 +1,7 @@
 import { CamoxApp } from "../../core/createApp.js";
 import { PageRenderInput } from "./runtime.js";
-
 //#region src/features/runtime/pageServer.d.ts
-declare function renderPageWithApp(input: PageRenderInput & {
+export declare function renderPageWithApp(input: PageRenderInput & {
   camoxApp: CamoxApp;
 }): Promise<string>;
-//#endregion
-export { renderPageWithApp };
+//#endregion

package/dist/features/runtime/pageServer.js

@@ -1,14 +1,21 @@
+import { createDraftScope } from "../../lib/draft-scope.js";
+import { prefetchIcons } from "../../core/lib/icons.js";
+import { loadRuntimeChrome } from "./runtimeChromeLoader.js";
 import { PageApp } from "./pageApp.js";
-import { QueryClient, hydrate } from "@tanstack/react-query";
 import { jsx } from "react/jsx-runtime";
+import { QueryClient, dehydrate, hydrate } from "@tanstack/react-query";
 import { renderToString } from "react-dom/server";
 
 //#region src/features/runtime/pageServer.tsx
 async function renderPageWithApp(input) {
 	const queryClient = new QueryClient();
 	hydrate(queryClient, input.dehydratedState);
+	await Promise.all([prefetchIcons(queryClient, input.dehydratedState, input.camoxApp.getBlocks().map(({ _internal }) => [_internal.contentSchema, _internal.settingsSchema])), input.presentation === "studio" ? loadRuntimeChrome() : void 0]);
+	Object.assign(input.dehydratedState, dehydrate(queryClient));
+	const draftScope = createDraftScope({ queryClient });
 	return renderToString(/* @__PURE__ */ jsx(PageApp, {
 		camoxApp: input.camoxApp,
+		draftScope,
 		input,
 		queryClient
 	}));

package/dist/features/runtime/pageViewport.js

@@ -0,0 +1,7 @@
+import * as React from "react";
+
+//#region src/features/runtime/pageViewport.ts
+const PageViewportContext = React.createContext(null);
+
+//#endregion
+export { PageViewportContext };

package/dist/features/runtime/runtime.d.ts

@@ -1,65 +1,102 @@
-import { CamoxApp } from "../../core/createApp.js";
 import { CamoxDocument } from "../../core/defineDocument.js";
-import { createServerApiClient } from "../routes/pageRuntime.js";
+import { AnyLayoutLoaderResult } from "../../core/createLayout.js";
+import { CamoxApp } from "../../core/createApp.js";
+import { AlternatePath, LocaleView } from "../../lib/locale-path.js";
+import { AnalyticsProviders } from "./analytics.js";
+import { RuntimeOwnedRouteKind } from "./runtimeRoutes.js";
 import { StudioRenderInput } from "./studioApp.js";
+import { DraftRead, MemberProject, createServerApiClient } from "../routes/pageRuntime.js";
 import { UseHeadInput } from "unhead/types";
-
 //#region src/features/runtime/runtime.d.ts
-type RuntimeRouteKind = "data" | "health" | "og" | "page" | "registry" | "sitemap" | "studio" | "studio-content" | "studio-nested";
-interface RuntimeRouteMatch {
+export type RuntimeRouteKind = RuntimeOwnedRouteKind | "canvas" | "page" | "studio" | "studio-content" | "studio-nested";
+export interface RuntimeRouteMatch {
   kind: RuntimeRouteKind;
   pathname: string;
 }
-interface LayoutIdentity {
-  blockIds: number[];
-  id: number;
+export interface LayoutIdentity {
+  blockIds: string[];
   layoutId: string;
   version: string;
 }
-interface PageRenderInput {
+export interface PageRenderInput extends DraftRead {
+  /**
+   * The page in every locale it exists in, the rendered one included, which the alternates hook
+   * returns. Left out where the render shows no page.
+   */
+  alternates?: AlternatePath[];
+  /**
+   * The analytics providers whose scripts the server added, so the page client sends them page
+   * views. Only a visitor's Live page carries them.
+   */
+  analytics?: AnalyticsProviders;
+  /** Authenticate before rendering, to show the Studio around the page. */
+  previewHandoff?: boolean;
   previewDocument?: string;
   routeKind?: "studio" | "studio-content" | "studio-nested";
-  project?: Awaited<ReturnType<ReturnType<typeof createServerApiClient>["projects"]["getBySlug"]>>;
+  /**
+   * A location only the Canvas shows, instead of a Page: the Canvas
+   * with nothing selected, or with a block of the Block Catalog selected.
+   */
+  canvasOnly?: {
+    blockId?: string;
+  };
+  project?: MemberProject;
   presentation?: "public" | "studio";
   derived?: {
     layoutId: string;
-    data: unknown;
+    result?: AnyLayoutLoaderResult;
     layout: Awaited<ReturnType<ReturnType<typeof createServerApiClient>["layouts"]["get"]>>["layout"];
   };
   apiUrl: string;
   authenticationUrl: string;
   dehydratedState: unknown;
-  environmentName?: string;
   head: unknown;
   href: string;
   layoutIdentity: LayoutIdentity | null;
   loaderData: unknown;
+  /** The locale the render shows, named by the path's prefix. */
+  locale: LocaleView;
+  /** The locales of the scope the render reads: Live's, or its draft's. */
+  locales: LocaleView[];
+  /**
+   * The full runtime path, with the locale's prefix (`/de/preise`). The locale-relative path is
+   * `parseLocalePath(pathname, locales).path`.
+   */
   pathname: string;
-  projectSlug: string;
+  projectUuid: string;
   runtimeBasePath: string;
-  source: "live" | "draft";
 }
-interface RuntimeOptions {
+export interface RuntimeOptions {
   apiUrl?: string;
   authenticationUrl?: string;
-  environmentName?: string;
+  /** Where the browser loads each block from, so a page can preload the blocks it renders. */
+  blockPreloads?: {
+    /** Each block's module path, by block id. */
+    modulePaths: Record<string, string>;
+    /** The built chunks each block module needs, by module path. `null` in dev. */
+    chunks: Record<string, string[]> | null;
+  };
+  /**
+   * Dev mode: every render reads the caller's development draft and ignores the URL's draft
+   * (ADR 0006).
+   */
+  developmentDraft?: boolean;
   pageClientEntryUrl?: string;
   studioClientEntryUrl?: string;
   getCamoxApp?: () => Promise<CamoxApp>;
   getDocument?: () => Promise<CamoxDocument>;
-  projectSlug?: string;
+  projectUuid?: string;
   renderPage?: (input: PageRenderInput) => Promise<string>;
   renderStudio?: (input: StudioRenderInput) => Promise<string>;
   runtimeBasePath?: string;
   stylesheetUrl?: string;
   studioStylesheetUrl?: string;
 }
-declare function getRuntimePathname(url: string, runtimeBasePath?: string): string | null;
-declare function matchRuntimeRoute(pathname: string): RuntimeRouteMatch;
-declare function createPageHeadInput(head: {
+export declare function getRuntimePathname(url: string, runtimeBasePath?: string): string | null;
+export declare function matchRuntimeRoute(pathname: string): RuntimeRouteMatch;
+export declare function createPageHeadInput(head: {
   meta?: Array<Record<string, string>>;
   links?: Array<Record<string, string>>;
 }): UseHeadInput;
-declare function handleCamoxRequest(request: Request, options?: RuntimeOptions): Promise<Response | null>;
-//#endregion
-export { LayoutIdentity, PageRenderInput, RuntimeOptions, RuntimeRouteKind, RuntimeRouteMatch, createPageHeadInput, getRuntimePathname, handleCamoxRequest, matchRuntimeRoute };
+export declare function handleCamoxRequest(request: Request, options?: RuntimeOptions): Promise<Response | null>;
+//#endregion