@uniformdev/next-app-router 20.80.2 → 20.81.1-alpha.10.sha-def425616f

package/dist/index.d.mts

@@ -1,14 +1,16 @@
-import { CanvasClient, CompositionDeliveryClient, RouteClient, ComponentInstance } from '@uniformdev/canvas';
-import { CacheMode, CanvasCacheMode, ManifestCacheMode, ProjectMapCacheMode, RewriteRequestPathResult } from '@uniformdev/next-app-router-shared';
+import { CanvasClient, CompositionDeliveryClient, RouteClient, RouteGetResponseRedirect } from '@uniformdev/canvas';
+import { CacheMode, CanvasCacheMode, ManifestCacheMode, ProjectMapCacheMode, RewriteRequestPathResult, PageState } from '@uniformdev/next-app-router-shared';
 import { ManifestClient } from '@uniformdev/context/api';
 import { ProjectMapClient } from '@uniformdev/project-map';
-import { U as UniformCompositionProps } from './UniformComposition-le6UEB_r.mjs';
-export { C as CompositionCache, a as ResolveComponentFunction, R as ResolveComponentResult, b as UniformComposition, c as createCompositionCache } from './UniformComposition-le6UEB_r.mjs';
+import { U as UniformCompositionProps } from './UniformComposition-Doa1kKRm.mjs';
+export { C as CompositionCache, a as ResolveComponentFunction, R as ResolveComponentResult, b as UniformComposition, c as createCompositionCache } from './UniformComposition-Doa1kKRm.mjs';
+import { ClientContextComponent } from '@uniformdev/next-app-router-client';
 import React from 'react';
-export { D as DataClient, a as DefaultDataClient, E as EnhanceRouteOptions, G as GetRouteFromMiddlewareOptions, b as GetRouteFromPageStateOptions, c as GetRouteOptions, R as RewriteRouteOptions, d as RewriteRouteResult, e as expireMiddlewareCacheTag } from './client-BElN_CWD.mjs';
-import { a as ResolvedRouteResult } from './resolveRouteFromCode-CuJ4JHeb.mjs';
-export { R as ResolveRouteFunction, r as resolveRouteFromCode } from './resolveRouteFromCode-CuJ4JHeb.mjs';
-import '@uniformdev/next-app-router-client';
+import { a as ResolvedRouteResult, b as ResolvedComposition, R as ResolvedCompositionResult } from './composition-CGU7iH-k.mjs';
+export { c as ResolvedNotFound, d as ResolvedRedirect } from './composition-CGU7iH-k.mjs';
+import { E as EdgeRouteFilter } from './models-C8OdCO44.mjs';
+import { b as ResolveRouteFromCodeOptions } from './resolveRouteFromPath-_rauUskz.mjs';
+export { P as PageStateSource, R as ResolveCompositionByIdOptions, a as ResolveCompositionBySlugOptions, c as ResolveRouteFromPathOptions, d as ResolveRouteFunction, r as resolveCompositionById, e as resolveCompositionBySlug, f as resolveRouteFromCode, g as resolveRouteFromPath } from './resolveRouteFromPath-_rauUskz.mjs';
 import '@uniformdev/context';
 
 type SpecificCacheMode<TCacheMode extends CacheMode> = {
@@ -202,6 +204,24 @@ type PlaygroundParameters = {
     }>;
 };
 
+type UniformContextProps = {
+    /**
+     * Component to initialize Uniform context on the client.
+     */
+    clientContextComponent?: ClientContextComponent;
+    /**
+     * The page's primary composition. It sets the composition metadata of the visitor's context and
+     * the default consent, and loads the contextual editing script in the editor and draft states.
+     * Takes any resolver result as is; a redirect or not found result sets no composition metadata.
+     */
+    result: ResolvedRouteResult | undefined;
+};
+/**
+ * Initializes Uniform context on the client and loads the contextual editing script. Render it
+ * once per page, next to one or more `UniformComposition` elements.
+ */
+declare function UniformContext(props: UniformContextProps): React.JSX.Element;
+
 type UniformPageParameters = {
     params: Promise<{
         code: string;
@@ -211,8 +231,13 @@ type AwaitedUniformPageParameters = {
     params: Awaited<UniformPageParameters['params']>;
 };
 
-type UniformPlaygroundProps = UniformCompositionProps;
-declare const UniformPlayground: ({ resolveRoute, ...rest }: UniformPlaygroundProps) => Promise<React.JSX.Element>;
+type UniformPlaygroundProps = UniformCompositionProps & Pick<UniformContextProps, 'clientContextComponent'>;
+/**
+ * Renders a playground page in draft mode: the composition, usually from `resolvePlaygroundRoute`,
+ * with its `UniformContext`. Renders a message outside draft mode. Keep it out of layouts that
+ * render their own `UniformContext`, which would initialize Uniform context twice.
+ */
+declare const UniformPlayground: ({ clientContextComponent, ...props }: UniformPlaygroundProps) => Promise<React.JSX.Element>;
 
 type CreateStaticParamsOptions = {
     paths: string[];
@@ -220,49 +245,64 @@ type CreateStaticParamsOptions = {
         path: string;
     }) => Promise<RewriteRequestPathResult | undefined>;
     locale?: string;
+    /**
+     * Prebuilds pages in edge mode, for apps that use `uniformEdgeMiddleware`. `true` puts every
+     * path in edge mode. A filter is asked about each path; pass the same filter the middleware uses
+     * so the prebuilt codes match the ones it rewrites to.
+     */
+    edgeMode?: boolean | EdgeRouteFilter;
 };
 /**
- * Function to generate all possible page states for the given paths in playground mode.
- * @param options
- * @returns
+ * Generates the playground code for the first of the given paths. Playground requests are drafts,
+ * which evaluate while the page renders, so there is one code per composition.
  */
 declare const createUniformPlaygroundStaticParams: (options: CreateStaticParamsOptions) => Promise<{
     code: string;
 }[]>;
 /**
- * Function to generate all possible page states for the given paths.
- * @param options
- * @returns
+ * Generates one code per published composition among the given paths, for `generateStaticParams`
+ * of the `[code]` route. Codes carry the route, not an evaluation, so each path has one static page
+ * whose variants are chosen in the browser or at the edge.
  */
 declare const createUniformStaticParams: (options: CreateStaticParamsOptions) => Promise<{
     code: string;
 }[]>;
 
-type EvaluateTestsFunction = (test: {
-    name: string;
-    component: ComponentInstance;
-}) => boolean;
-type EvaluatePersonalizationsFunction = (personalization: {
-    name: string;
-    component: ComponentInstance;
-}) => boolean;
-type PrecomputeCompositionOptions = Pick<ResolvedRouteResult, 'pageState' | 'route'> & {
-    /**
-     * Whether to evaluate tests
-     * @defaultValue true
-     */
-    evaluateTests?: boolean | EvaluateTestsFunction;
-    /**
-     * Whether to evaluate personalizations
-     * @defaultValue true
-     */
-    evaluatePersonalizations?: boolean | EvaluatePersonalizationsFunction;
-};
-declare const precomputeComposition: ({ pageState, route, evaluatePersonalizations, evaluateTests, }: PrecomputeCompositionOptions) => Promise<void>;
-
-declare const resolvePlaygroundRoute: ({ code }: {
+/**
+ * Reads the page state the middleware encoded in a `[code]` path segment: the route path,
+ * composition state, release, locale and preview settings. The resolvers accept the code
+ * directly; call this when the page needs the page state before resolving.
+ */
+declare const deserializePageState: ({ code }: {
     code: string;
-}) => Promise<ResolvedRouteResult>;
+}) => PageState;
+
+/**
+ * Returns the result when it resolved to a composition, ready for `UniformComposition`. Otherwise
+ * it throws through Next.js navigation: `notFound()` when nothing matched, `permanentRedirect` for
+ * 301 and 308 redirect targets, and `redirect` for the rest. The redirect target is built with
+ * `resolveRedirectHref`.
+ */
+declare const requireComposition: (result: ResolvedRouteResult) => ResolvedComposition;
+
+/**
+ * Resolves the composition of a playground code. The code carries the composition id, and the
+ * composition resolves in the editor state, falling back to the draft state. `route` is undefined
+ * outside draft mode, without fetching, and when the composition does not exist.
+ */
+declare const resolvePlaygroundRoute: ({ code, }: ResolveRouteFromCodeOptions) => Promise<ResolvedCompositionResult>;
+
+type ResolveRedirectHrefOptions = {
+    route: RouteGetResponseRedirect;
+    /** The path that matched the redirect, usually the result's `pageState.routePath`. */
+    routePath: string;
+};
+/**
+ * Builds the URL a redirect route sends the visitor to. Path variables in the target, such as
+ * `/new/:id`, are filled from `routePath`. Targets on the same domain come back as relative paths;
+ * absolute targets on another domain come back unchanged.
+ */
+declare const resolveRedirectHref: ({ route, routePath }: ResolveRedirectHrefOptions) => string;
 
 type CustomRoute = {
     id: string;
@@ -276,4 +316,4 @@ declare const findRouteMatch: (routes: CustomRoute[], path: string) => RouteMatc
 
 declare const serverContext: <T>(defaultValue?: T) => [() => T | undefined, (v: T) => void];
 
-export { type AwaitedUniformPageParameters, type CreateStaticParamsOptions, type CustomRoute, type GetCanvasClientOptions, type GetCompositionDeliveryClientOptions, type GetManifestClientOptions, type GetProjectMapClientOptions, type GetRouteClientOptions, type PlaygroundParameters, type RouteMatch, UniformCompositionProps, type UniformPageParameters, UniformPlayground, createUniformPlaygroundStaticParams, createUniformStaticParams, findRouteMatch, getCanvasClient, getCompositionDeliveryClient, getManifest, getManifestClient, getProjectMapClient, getRouteClient, precomputeComposition, resolvePlaygroundRoute, serverContext };
+export { type AwaitedUniformPageParameters, type CreateStaticParamsOptions, type CustomRoute, type GetCanvasClientOptions, type GetCompositionDeliveryClientOptions, type GetManifestClientOptions, type GetProjectMapClientOptions, type GetRouteClientOptions, type PlaygroundParameters, type ResolveRedirectHrefOptions, ResolveRouteFromCodeOptions, ResolvedComposition, ResolvedCompositionResult, ResolvedRouteResult, type RouteMatch, UniformCompositionProps, UniformContext, type UniformContextProps, type UniformPageParameters, UniformPlayground, type UniformPlaygroundProps, createUniformPlaygroundStaticParams, createUniformStaticParams, deserializePageState, findRouteMatch, getCanvasClient, getCompositionDeliveryClient, getManifest, getManifestClient, getProjectMapClient, getRouteClient, requireComposition, resolvePlaygroundRoute, resolveRedirectHref, serverContext };

package/dist/index.d.ts

@@ -1,14 +1,16 @@
-import { CanvasClient, CompositionDeliveryClient, RouteClient, ComponentInstance } from '@uniformdev/canvas';
-import { CacheMode, CanvasCacheMode, ManifestCacheMode, ProjectMapCacheMode, RewriteRequestPathResult } from '@uniformdev/next-app-router-shared';
+import { CanvasClient, CompositionDeliveryClient, RouteClient, RouteGetResponseRedirect } from '@uniformdev/canvas';
+import { CacheMode, CanvasCacheMode, ManifestCacheMode, ProjectMapCacheMode, RewriteRequestPathResult, PageState } from '@uniformdev/next-app-router-shared';
 import { ManifestClient } from '@uniformdev/context/api';
 import { ProjectMapClient } from '@uniformdev/project-map';
-import { U as UniformCompositionProps } from './UniformComposition-DBO-oo7J.js';
-export { C as CompositionCache, a as ResolveComponentFunction, R as ResolveComponentResult, b as UniformComposition, c as createCompositionCache } from './UniformComposition-DBO-oo7J.js';
+import { U as UniformCompositionProps } from './UniformComposition-ChDH4dMd.js';
+export { C as CompositionCache, a as ResolveComponentFunction, R as ResolveComponentResult, b as UniformComposition, c as createCompositionCache } from './UniformComposition-ChDH4dMd.js';
+import { ClientContextComponent } from '@uniformdev/next-app-router-client';
 import React from 'react';
-export { D as DataClient, a as DefaultDataClient, E as EnhanceRouteOptions, G as GetRouteFromMiddlewareOptions, b as GetRouteFromPageStateOptions, c as GetRouteOptions, R as RewriteRouteOptions, d as RewriteRouteResult, e as expireMiddlewareCacheTag } from './client-BElN_CWD.js';
-import { a as ResolvedRouteResult } from './resolveRouteFromCode-BOvjIvM2.js';
-export { R as ResolveRouteFunction, r as resolveRouteFromCode } from './resolveRouteFromCode-BOvjIvM2.js';
-import '@uniformdev/next-app-router-client';
+import { a as ResolvedRouteResult, b as ResolvedComposition, R as ResolvedCompositionResult } from './composition-CGU7iH-k.js';
+export { c as ResolvedNotFound, d as ResolvedRedirect } from './composition-CGU7iH-k.js';
+import { E as EdgeRouteFilter } from './models-C8OdCO44.js';
+import { b as ResolveRouteFromCodeOptions } from './resolveRouteFromPath-CnfnaxY2.js';
+export { P as PageStateSource, R as ResolveCompositionByIdOptions, a as ResolveCompositionBySlugOptions, c as ResolveRouteFromPathOptions, d as ResolveRouteFunction, r as resolveCompositionById, e as resolveCompositionBySlug, f as resolveRouteFromCode, g as resolveRouteFromPath } from './resolveRouteFromPath-CnfnaxY2.js';
 import '@uniformdev/context';
 
 type SpecificCacheMode<TCacheMode extends CacheMode> = {
@@ -202,6 +204,24 @@ type PlaygroundParameters = {
     }>;
 };
 
+type UniformContextProps = {
+    /**
+     * Component to initialize Uniform context on the client.
+     */
+    clientContextComponent?: ClientContextComponent;
+    /**
+     * The page's primary composition. It sets the composition metadata of the visitor's context and
+     * the default consent, and loads the contextual editing script in the editor and draft states.
+     * Takes any resolver result as is; a redirect or not found result sets no composition metadata.
+     */
+    result: ResolvedRouteResult | undefined;
+};
+/**
+ * Initializes Uniform context on the client and loads the contextual editing script. Render it
+ * once per page, next to one or more `UniformComposition` elements.
+ */
+declare function UniformContext(props: UniformContextProps): React.JSX.Element;
+
 type UniformPageParameters = {
     params: Promise<{
         code: string;
@@ -211,8 +231,13 @@ type AwaitedUniformPageParameters = {
     params: Awaited<UniformPageParameters['params']>;
 };
 
-type UniformPlaygroundProps = UniformCompositionProps;
-declare const UniformPlayground: ({ resolveRoute, ...rest }: UniformPlaygroundProps) => Promise<React.JSX.Element>;
+type UniformPlaygroundProps = UniformCompositionProps & Pick<UniformContextProps, 'clientContextComponent'>;
+/**
+ * Renders a playground page in draft mode: the composition, usually from `resolvePlaygroundRoute`,
+ * with its `UniformContext`. Renders a message outside draft mode. Keep it out of layouts that
+ * render their own `UniformContext`, which would initialize Uniform context twice.
+ */
+declare const UniformPlayground: ({ clientContextComponent, ...props }: UniformPlaygroundProps) => Promise<React.JSX.Element>;
 
 type CreateStaticParamsOptions = {
     paths: string[];
@@ -220,49 +245,64 @@ type CreateStaticParamsOptions = {
         path: string;
     }) => Promise<RewriteRequestPathResult | undefined>;
     locale?: string;
+    /**
+     * Prebuilds pages in edge mode, for apps that use `uniformEdgeMiddleware`. `true` puts every
+     * path in edge mode. A filter is asked about each path; pass the same filter the middleware uses
+     * so the prebuilt codes match the ones it rewrites to.
+     */
+    edgeMode?: boolean | EdgeRouteFilter;
 };
 /**
- * Function to generate all possible page states for the given paths in playground mode.
- * @param options
- * @returns
+ * Generates the playground code for the first of the given paths. Playground requests are drafts,
+ * which evaluate while the page renders, so there is one code per composition.
  */
 declare const createUniformPlaygroundStaticParams: (options: CreateStaticParamsOptions) => Promise<{
     code: string;
 }[]>;
 /**
- * Function to generate all possible page states for the given paths.
- * @param options
- * @returns
+ * Generates one code per published composition among the given paths, for `generateStaticParams`
+ * of the `[code]` route. Codes carry the route, not an evaluation, so each path has one static page
+ * whose variants are chosen in the browser or at the edge.
  */
 declare const createUniformStaticParams: (options: CreateStaticParamsOptions) => Promise<{
     code: string;
 }[]>;
 
-type EvaluateTestsFunction = (test: {
-    name: string;
-    component: ComponentInstance;
-}) => boolean;
-type EvaluatePersonalizationsFunction = (personalization: {
-    name: string;
-    component: ComponentInstance;
-}) => boolean;
-type PrecomputeCompositionOptions = Pick<ResolvedRouteResult, 'pageState' | 'route'> & {
-    /**
-     * Whether to evaluate tests
-     * @defaultValue true
-     */
-    evaluateTests?: boolean | EvaluateTestsFunction;
-    /**
-     * Whether to evaluate personalizations
-     * @defaultValue true
-     */
-    evaluatePersonalizations?: boolean | EvaluatePersonalizationsFunction;
-};
-declare const precomputeComposition: ({ pageState, route, evaluatePersonalizations, evaluateTests, }: PrecomputeCompositionOptions) => Promise<void>;
-
-declare const resolvePlaygroundRoute: ({ code }: {
+/**
+ * Reads the page state the middleware encoded in a `[code]` path segment: the route path,
+ * composition state, release, locale and preview settings. The resolvers accept the code
+ * directly; call this when the page needs the page state before resolving.
+ */
+declare const deserializePageState: ({ code }: {
     code: string;
-}) => Promise<ResolvedRouteResult>;
+}) => PageState;
+
+/**
+ * Returns the result when it resolved to a composition, ready for `UniformComposition`. Otherwise
+ * it throws through Next.js navigation: `notFound()` when nothing matched, `permanentRedirect` for
+ * 301 and 308 redirect targets, and `redirect` for the rest. The redirect target is built with
+ * `resolveRedirectHref`.
+ */
+declare const requireComposition: (result: ResolvedRouteResult) => ResolvedComposition;
+
+/**
+ * Resolves the composition of a playground code. The code carries the composition id, and the
+ * composition resolves in the editor state, falling back to the draft state. `route` is undefined
+ * outside draft mode, without fetching, and when the composition does not exist.
+ */
+declare const resolvePlaygroundRoute: ({ code, }: ResolveRouteFromCodeOptions) => Promise<ResolvedCompositionResult>;
+
+type ResolveRedirectHrefOptions = {
+    route: RouteGetResponseRedirect;
+    /** The path that matched the redirect, usually the result's `pageState.routePath`. */
+    routePath: string;
+};
+/**
+ * Builds the URL a redirect route sends the visitor to. Path variables in the target, such as
+ * `/new/:id`, are filled from `routePath`. Targets on the same domain come back as relative paths;
+ * absolute targets on another domain come back unchanged.
+ */
+declare const resolveRedirectHref: ({ route, routePath }: ResolveRedirectHrefOptions) => string;
 
 type CustomRoute = {
     id: string;
@@ -276,4 +316,4 @@ declare const findRouteMatch: (routes: CustomRoute[], path: string) => RouteMatc
 
 declare const serverContext: <T>(defaultValue?: T) => [() => T | undefined, (v: T) => void];
 
-export { type AwaitedUniformPageParameters, type CreateStaticParamsOptions, type CustomRoute, type GetCanvasClientOptions, type GetCompositionDeliveryClientOptions, type GetManifestClientOptions, type GetProjectMapClientOptions, type GetRouteClientOptions, type PlaygroundParameters, type RouteMatch, UniformCompositionProps, type UniformPageParameters, UniformPlayground, createUniformPlaygroundStaticParams, createUniformStaticParams, findRouteMatch, getCanvasClient, getCompositionDeliveryClient, getManifest, getManifestClient, getProjectMapClient, getRouteClient, precomputeComposition, resolvePlaygroundRoute, serverContext };
+export { type AwaitedUniformPageParameters, type CreateStaticParamsOptions, type CustomRoute, type GetCanvasClientOptions, type GetCompositionDeliveryClientOptions, type GetManifestClientOptions, type GetProjectMapClientOptions, type GetRouteClientOptions, type PlaygroundParameters, type ResolveRedirectHrefOptions, ResolveRouteFromCodeOptions, ResolvedComposition, ResolvedCompositionResult, ResolvedRouteResult, type RouteMatch, UniformCompositionProps, UniformContext, type UniformContextProps, type UniformPageParameters, UniformPlayground, type UniformPlaygroundProps, createUniformPlaygroundStaticParams, createUniformStaticParams, deserializePageState, findRouteMatch, getCanvasClient, getCompositionDeliveryClient, getManifest, getManifestClient, getProjectMapClient, getRouteClient, requireComposition, resolvePlaygroundRoute, resolveRedirectHref, serverContext };