@elytracms/next 0.0.100 → 0.0.101

package/dist/index.d.ts

@@ -394,6 +394,14 @@ interface CanvasWrapContext extends CanvasRequestInfo {
      * a serializable declaration).
      */
     result: ResolvePageResult;
+    /**
+     * The request's locale — the one the page resolved and renders in (EC-720). A NAME for
+     * `result.tags.locale`, the value the route split from the URL once and that the page,
+     * its metadata, listings, assets and beacon already read: never a second derivation, so
+     * a wrapper's chrome strings and the content it wraps cannot disagree. Hand it to
+     * `elytra.loadGlobals({ locale })` for chrome the wrapper reads itself.
+     */
+    locale: Locale;
 }
 /**
  * EC-618 — what the route's `analytics` slot is told about the page it renders on: the
@@ -490,6 +498,13 @@ type CanvasPageOutcome = {
     presentation?: DeliveryPresentation;
     tags: CacheTags;
 };
+/**
+ * The outcome a page renders (EC-722): what `route.load(url)` returns once the route has
+ * answered a redirect or a not-found itself — a caller of it never branches on `kind`.
+ */
+type CanvasRenderOutcome = Extract<CanvasPageOutcome, {
+    kind: 'render';
+}>;
 /** Build the request path from a Next catch-all `slug` param. */
 declare function pathFromSlug(slug: readonly string[] | undefined): string;
 
@@ -834,6 +849,31 @@ interface CanvasRoute {
     applyCacheTags: (result: {
         tags: CacheTags;
     }) => void;
+    /**
+     * EC-722 — resolve one URL for a route of YOUR OWN and settle its status, before any
+     * `<Suspense>` boundary: `const outcome = await route.load('/blog/' + slug)`.
+     *
+     * It does what {@link Page} does before rendering, and nothing else: reads the request's
+     * perspective, resolves a published request through your
+     * {@link CanvasRouteOptions.published} cache function with the SAME key `Page` hands it
+     * (one entry; a draft resolves fresh), and answers a redirect with
+     * `redirect()`/`permanentRedirect()` and a missing document with `notFound()` itself —
+     * so what comes back is always a page to render.
+     *
+     * **Call it outside every `<Suspense>` boundary** (the route's page, not a suspended
+     * child). Inside one, the response status is already committed when the call settles:
+     * measured, a hand-written route that resolved and called `notFound()` inside
+     * `<Suspense>` answered a missing document with HTTP 200 (EC-567 V11). Outside, under
+     * Cache Components, it is legal because a published request is a cache read through
+     * `published` — the reason the catch-all page can stand outside a boundary too. Without
+     * `published`, a live-mode read outside `<Suspense>` fails `next build` under Cache
+     * Components (the same rule `Page` lives by); without Cache Components it is a plain
+     * dynamic read.
+     *
+     * Your route's own `generateMetadata` can delegate to {@link generateMetadata} with the
+     * catch-all slug of the same URL; `load` fires no `onTags` (the route's `Page` does).
+     */
+    load: (url: string) => Promise<CanvasRenderOutcome>;
     /**
      * `export const generateStaticParams = route.generateStaticParams` — needed in the
      * catch-all page file only when the HOST enables `cacheComponents` (that flag's
@@ -873,7 +913,8 @@ declare function requestPerspective(): Promise<Perspective>;
 /**
  * Create the canvas route for `app/[[...slug]]/page.tsx` — `{ Page, generateMetadata,
  * generateStaticParams }` to export, plus `resolve` / `applyCacheTags` for the host's
- * own cache function ({@link CanvasRouteOptions.published}).
+ * own cache function ({@link CanvasRouteOptions.published}) and `load` for a route of the
+ * host's own (EC-722 — {@link CanvasRoute.load}).
  */
 declare function createCanvasRoute(options: CanvasRouteOptions): CanvasRoute;
 
@@ -951,7 +992,7 @@ declare function seoMetadata(doc: Record<string, unknown> | null | undefined, ct
  * page segment's `openGraph` object REPLACES the layout's whole `openGraph`, so a
  * site-wide `type`, `siteName`, site image or `locale` declared once in the root
  * layout never reached a canvas page, and both real sites hand-rolled around it
- * differently (NK-039's page hook, Konditorei's post bypass). This is the one
+ * differently (a page hook on one, a post bypass on the other). This is the one
  * merge, applied by the canvas route to whatever builds the page's metadata (the
  * kit's default or the host's `metadata` option): every object-valued key the
  * page sets (`openGraph`, `twitter`, `robots`, `alternates`, …) is merged one
@@ -1336,7 +1377,7 @@ interface ElytraImageProps {
     quality?: number;
     className?: string;
     /**
-     * Loading strategy forwarded to `next/image` (EC-428/NK-026). `'eager'` opts an
+     * Loading strategy forwarded to `next/image` (EC-428). `'eager'` opts an
      * image out of lazy-loading without the preload `priority` implies. Next throws
      * on `priority` + `loading='lazy'` together, so {@link ElytraImage} drops `lazy`
      * when `priority` is set (priority wins) — delivery never crashes.
@@ -1597,6 +1638,12 @@ interface SiteGlobals {
 interface ResolveGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
     perspective?: Perspective;
+    /**
+     * The request's locale (EC-720). Default: the source's default locale. A locale the
+     * project does not declare throws a located `unknown-locale` error — read silently, it
+     * would serve every field from the default locale's fallback and look like a translation
+     * gap rather than a wrong argument.
+     */
     locale?: Locale;
     conventions?: GlobalsConventions;
 }
@@ -1830,6 +1877,16 @@ interface HostCanvasRouteOptions {
 interface LoadGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
     perspective?: Perspective;
+    /**
+     * The request's locale (EC-720) — the chrome's settings, menus and link paths are read in
+     * it. Default: the project's default locale, which is every page's locale on a
+     * single-locale site. On a multi-locale site pass the locale the page renders in: from a
+     * layout in the catch-all segment, `resolveLocale({ pathname: pathFromSlug(slug) },
+     * locales)` — the SAME split the catch-all resolves the page with — or a `wrap`
+     * function's `ctx.locale`. A locale the project does not declare is an error, never a
+     * silent read of the default.
+     */
+    locale?: Locale;
 }
 /**
  * Which world {@link ElytraHost.loadContent} reads from.
@@ -1920,7 +1977,8 @@ interface ElytraHost<Collections extends readonly CollectionDef[] = readonly Col
     /**
      * Load + resolve the site-chrome globals (settings singleton, navigation by
      * slot alias, link/asset resolution — see `host-globals.ts`). One content
-     * load per call; published perspective by default.
+     * load per call; published perspective and the project's default locale by
+     * default — pass the request's `locale` on a multi-locale site (EC-720).
      *
      * An UNCACHED read, like {@link loadContent}: under `cacheComponents`, render the
      * chrome that awaits it inside `<Suspense>` — and keep the canvas page OUTSIDE
@@ -2132,4 +2190,4 @@ declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken:
  */
 declare const PACKAGE = "@elytracms/next";
 
-export { type AssetImageLoaderOptions, type BakedListing, type BotGateVerdict, CANVAS_VALIDATION_SLUG, type CanvasBeaconProps, type CanvasCacheKey, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type FixedWindowLimiter, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type IngestBotGate, type IngestEnrich, type IngestEvaluation, type IngestRouteHandlers, type IngestRouteOptions, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SeoMetadataContext, type SiteGlobals, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasBeaconProps, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createFixedWindowLimiter, createIngestRoute, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultIngestClientKey, defineHostComponents, docCacheTag, elytraHostImage, evaluateIngestRequest, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isCrossOrigin, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, readCappedBody, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };
+export { type AssetImageLoaderOptions, type BakedListing, type BotGateVerdict, CANVAS_VALIDATION_SLUG, type CanvasBeaconProps, type CanvasCacheKey, type CanvasContentRequest, type CanvasPageOutcome, type CanvasRenderOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type FixedWindowLimiter, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type IngestBotGate, type IngestEnrich, type IngestEvaluation, type IngestRouteHandlers, type IngestRouteOptions, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SeoMetadataContext, type SiteGlobals, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasBeaconProps, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createFixedWindowLimiter, createIngestRoute, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultIngestClientKey, defineHostComponents, docCacheTag, elytraHostImage, evaluateIngestRequest, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isCrossOrigin, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, readCappedBody, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };

package/dist/index.js

@@ -2,7 +2,7 @@ import { registerComponents, createRenderContext, renderDocumentBodyItems, docum
 import { isBlockSequenceValueShape } from '@elytracms/core/rich-text';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { cacheTags, isDocumentHistory, assetWithoutUrlIssue, assetMetaDriftIssue, resolvedAsset, parseDeliveredDocuments, parseDeliveredRedirects, createContentClient, createContentContext } from '@elytracms/core/content';
-import { DEFAULT_SEO_FIELD, parseLocaleConfig, documentKey, readLiveRedirects, SEO_SUBFIELDS, splitLocalePath, DRAFT_PERSPECTIVE, splitPath, localeUrlPath, variantOf, DRAFT_VARIANT, createRouter, deliverCompositionProps, presentationBodyFields } from '@elytracms/core/cms-core';
+import { DEFAULT_SEO_FIELD, parseLocaleConfig, documentKey, readLiveRedirects, SEO_SUBFIELDS, DRAFT_PERSPECTIVE, splitPath, localeUrlPath, variantOf, DRAFT_VARIANT, createRouter, splitLocalePath, deliverCompositionProps, presentationBodyFields, validateLocale } from '@elytracms/core/cms-core';
 export { DRAFT_PERSPECTIVE, documentSchema, localeConfigSchema, localeUrlPath, parseLocaleConfig, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection, variantOf } from '@elytracms/core/cms-core';
 import { assetMetaLens, assetMetaDrift, assetReadLocale, redirectRecordKind } from '@elytracms/core/persistence';
 import { propFieldLookupOf } from '@elytracms/core/component-registry';
@@ -309,7 +309,8 @@ function canvasWrapContext(result, info) {
     ...info,
     ...collection !== void 0 ? { collection } : {},
     document: result.document,
-    result
+    result,
+    locale: result.tags.locale
   };
 }
 function canvasBeaconProps(result, info) {
@@ -442,10 +443,13 @@ function populatePageLinks(body, client, registry) {
   }
   return { links, docKeys: Object.keys(refs) };
 }
-async function resolveCanvasPage(source, url, perspective, options = {}) {
+function resolveRequestPage(source, url, perspective) {
   const { locale, path } = splitLocalePath(url, source.locales);
   const client = source.client({ perspective, locale });
-  const resolved = client.resolvePage(path);
+  return { locale, client, resolved: client.resolvePage(path) };
+}
+async function resolveCanvasPage(source, url, perspective, options = {}) {
+  const { locale, client, resolved } = resolveRequestPage(source, url, perspective);
   if (resolved.status === "redirect" && resolved.redirect) {
     return {
       kind: "redirect",
@@ -626,41 +630,49 @@ function createCanvasRoute(options) {
     if (perspective !== "published" || !options.published) return resolveFresh(url, perspective);
     return options.published(keyFor(url));
   };
-  const Page = async (props) => {
-    const { slug } = await props.params;
-    const url = pathFromSlug(slug);
-    if (url === CANVAS_VALIDATION_PATH) return notFound();
-    const perspective = await requestPerspective();
-    const outcome = await loadOutcome(url, perspective);
-    options.onTags?.(outcome.tags, { url, perspective });
+  const settle = (outcome) => {
     switch (outcome.kind) {
       case "redirect":
         return outcome.permanent ? permanentRedirect(outcome.target) : redirect(outcome.target);
       case "not-found":
         return notFound();
-      case "render": {
-        const rendered = /* @__PURE__ */ jsx(
-          CanvasRenderer,
-          {
-            result: outcome.result,
-            components: options.components,
-            assets: outcome.assets,
-            relations: outcome.relations,
-            listings: outcome.listings,
-            links: outcome.links,
-            presentation: outcome.presentation
-          }
-        );
-        const page = options.wrap ? options.wrap(rendered, canvasWrapContext(outcome.result, { url, perspective })) : rendered;
-        const Beacon = options.analytics;
-        if (!Beacon || perspective !== "published") return page;
-        return /* @__PURE__ */ jsxs(Fragment, { children: [
-          page,
-          /* @__PURE__ */ jsx(Beacon, { ...canvasBeaconProps(outcome.result, { url}) })
-        ] });
-      }
+      case "render":
+        return outcome;
     }
   };
+  const load = async (url) => {
+    if (url === CANVAS_VALIDATION_PATH) return notFound();
+    const perspective = await requestPerspective();
+    return settle(await loadOutcome(url, perspective));
+  };
+  const Page = async (props) => {
+    const { slug } = await props.params;
+    const url = pathFromSlug(slug);
+    if (url === CANVAS_VALIDATION_PATH) return notFound();
+    const perspective = await requestPerspective();
+    const loaded = await loadOutcome(url, perspective);
+    options.onTags?.(loaded.tags, { url, perspective });
+    const outcome = settle(loaded);
+    const rendered = /* @__PURE__ */ jsx(
+      CanvasRenderer,
+      {
+        result: outcome.result,
+        components: options.components,
+        assets: outcome.assets,
+        relations: outcome.relations,
+        listings: outcome.listings,
+        links: outcome.links,
+        presentation: outcome.presentation
+      }
+    );
+    const page = options.wrap ? options.wrap(rendered, canvasWrapContext(outcome.result, { url, perspective })) : rendered;
+    const Beacon = options.analytics;
+    if (!Beacon || perspective !== "published") return page;
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      page,
+      /* @__PURE__ */ jsx(Beacon, { ...canvasBeaconProps(outcome.result, { url}) })
+    ] });
+  };
   const pageMetadata = async (props) => {
     const { slug } = await props.params;
     const url = pathFromSlug(slug);
@@ -683,7 +695,7 @@ function createCanvasRoute(options) {
   const generateStaticParams = async () => [
     { slug: [...CANVAS_VALIDATION_SLUG] }
   ];
-  return { Page, generateMetadata, resolve, applyCacheTags, generateStaticParams };
+  return { Page, generateMetadata, resolve, applyCacheTags, load, generateStaticParams };
 }
 function originOf(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
@@ -1189,9 +1201,14 @@ async function loadLiveContent(options, perspective) {
   }
   return assembleLiveSource(payload, options, perspective);
 }
-
-// src/host-globals.ts
 var DEFAULT_ITEMS_FIELDS = ["items", "links"];
+function assertDeclaredLocale(source, locale) {
+  const [issue] = validateLocale(source.locales, locale);
+  if (!issue) return;
+  throw new Error(
+    `Elytra chrome globals: ${issue.code} at ${issue.path.join(".")} \u2014 the locale "${locale}" is not one of this project's locales (it declares ${source.locales.locales.join(", ")}). Pass the locale the page renders in \u2014 resolveLocale({ pathname }, locales) splits it from the URL exactly as the catch-all does \u2014 or omit it for the default locale.`
+  );
+}
 function record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
 }
@@ -1207,7 +1224,8 @@ function resolveGlobals(source, options = {}) {
   const settingsCollection = conventions.settingsCollection ?? "settings";
   const navigationCollection = conventions.navigationCollection ?? "navigation";
   const itemsFields = conventions.navigationItemsFields ?? DEFAULT_ITEMS_FIELDS;
-  const client = source.client({ perspective, ...options.locale ? { locale: options.locale } : {} });
+  if (options.locale !== void 0) assertDeclaredLocale(source, options.locale);
+  const client = source.client({ perspective, ...options.locale !== void 0 ? { locale: options.locale } : {} });
   const assets = source.assets?.(options.locale) ?? [];
   const assetById = new Map(assets.map((asset) => [asset.id, asset]));
   const listDocs = (collection) => {
@@ -1445,6 +1463,8 @@ function createElytraHost(options) {
     const source = await loadContent({ perspective });
     return resolveGlobals(source, {
       perspective,
+      // EC-720: the request's locale, judged against the project's locales by the core.
+      ...globalsOptions.locale !== void 0 ? { locale: globalsOptions.locale } : {},
       ...globals ? { conventions: globals } : {}
     });
   };
@@ -1481,9 +1501,7 @@ function createElytraHost(options) {
   const pageOpensFullBleed = async (slug) => {
     const perspective = await requestPerspective();
     const source = await loadContent({ perspective });
-    const { locale, path } = splitLocalePath(pathFromSlug(slug), source.locales);
-    const client = source.client({ perspective, locale });
-    const resolved = client.resolvePage(path);
+    const { resolved } = resolveRequestPage(source, pathFromSlug(slug), perspective);
     return firstBlockFullBleed(resolved.document, components.registry);
   };
   const frontendUrl = projectFrontendUrl(project);