@pantheon-systems/p1-next-sdk 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +99 -1
  2. package/bin/lib/cli.js +143 -25
  3. package/bin/lib/detect.js +14 -2
  4. package/bin/lib/fs-ops.js +2 -1
  5. package/bin/lib/localized-pages.js +522 -0
  6. package/bin/lib/messages.js +38 -23
  7. package/bin/templates/localized-pages/app/[[...puckPath]]/layout.tsx.template +29 -0
  8. package/bin/templates/localized-pages/app/[[...puckPath]]/page.tsx.template +24 -0
  9. package/bin/templates/localized-pages/app/p1/layout.tsx.template +11 -0
  10. package/bin/templates/localized-pages/components/html-shell.tsx.template +28 -0
  11. package/bin/templates/localized-pages/components/locale-suggestion.module.css.template +74 -0
  12. package/bin/templates/localized-pages/components/locale-suggestion.tsx.template +94 -0
  13. package/bin/templates/localized-pages/legacy/app/[...puckPath]/page.tsx.template +23 -0
  14. package/bin/templates/localized-pages/legacy/app/layout.tsx.template +37 -0
  15. package/bin/templates/localized-pages/legacy/app/layout.v1.tsx.template +27 -0
  16. package/bin/templates/localized-pages/legacy/app/page.tsx.template +19 -0
  17. package/bin/templates/localized-pages/lib/locale-name.ts.template +9 -0
  18. package/dist/chatbot/chatbot-plugin.js +3 -0
  19. package/dist/create-published-page.d.ts +22 -9
  20. package/dist/create-published-page.js +59 -8
  21. package/dist/editor-client/editor-content.js +3 -0
  22. package/dist/editor-client/use-business-account-id.d.ts +5 -0
  23. package/dist/editor-client/use-business-account-id.js +7 -0
  24. package/dist/experimental-features/features.d.ts +16 -5
  25. package/dist/experimental-features/features.js +6 -5
  26. package/dist/experimental-features/resolve-features.d.ts +5 -2
  27. package/dist/experimental-features/resolve-features.js +7 -4
  28. package/dist/experimental-features/session-cache.d.ts +1 -1
  29. package/dist/experimental-features/session-cache.js +2 -2
  30. package/dist/experimental-features/use-p1-experimental-features.d.ts +10 -3
  31. package/dist/experimental-features/use-p1-experimental-features.js +29 -11
  32. package/dist/handler.d.ts +2 -1
  33. package/dist/index.d.ts +1 -0
  34. package/dist/index.js +1 -0
  35. package/dist/localization/index.d.ts +4 -0
  36. package/dist/localization/index.js +3 -0
  37. package/dist/localization/saved-locale.d.ts +13 -0
  38. package/dist/localization/saved-locale.js +20 -0
  39. package/dist/localization-react.d.ts +40 -0
  40. package/dist/localization-react.js +15 -0
  41. package/dist/page-localization.d.ts +12 -0
  42. package/dist/page-localization.js +9 -0
  43. package/dist/pages-handler.js +2 -2
  44. package/dist/routes/publish.d.ts +0 -2
  45. package/dist/routes/publish.js +2 -3
  46. package/dist/routes/revalidate.d.ts +4 -4
  47. package/dist/routes/revalidate.js +10 -4
  48. package/dist/server.d.ts +2 -0
  49. package/dist/server.js +1 -0
  50. package/docs/migrations/editor-layout.md +213 -0
  51. package/docs/migrations/localized-pages.md +208 -0
  52. package/package.json +9 -3
  53. package/dist/chatbot/flag-context.d.ts +0 -15
  54. package/dist/chatbot/flag-context.js +0 -13
@@ -1,5 +1,5 @@
1
1
  import type { P1ExperimentalFeatureSet } from "./features";
2
- export declare function sessionKey(clientSideId: string, userId: string, siteId: string | undefined): string;
2
+ export declare function sessionKey(clientSideId: string, userId: string, siteId: string | undefined, businessAccountId?: string | null): string;
3
3
  /** The answer already resolved for this key, or null if none has been yet. */
4
4
  export declare function peekFeatures(key: string): P1ExperimentalFeatureSet | null;
5
5
  export declare function featuresFor(key: string, resolve: () => Promise<P1ExperimentalFeatureSet>): Promise<P1ExperimentalFeatureSet>;
@@ -1,7 +1,7 @@
1
1
  const pending = new Map();
2
2
  const settled = new Map();
3
- export function sessionKey(clientSideId, userId, siteId) {
4
- return `${clientSideId}|${userId}|${siteId ?? ""}`;
3
+ export function sessionKey(clientSideId, userId, siteId, businessAccountId) {
4
+ return `${clientSideId}|${userId}|${siteId ?? ""}|${businessAccountId ?? ""}`;
5
5
  }
6
6
  export function peekFeatures(key) {
7
7
  return settled.get(key) ?? null;
@@ -8,6 +8,13 @@ export interface UseP1ExperimentalFeaturesOptions {
8
8
  userId: string | null | undefined;
9
9
  /** The site being edited. Absent narrows evaluation to the user alone. */
10
10
  siteId?: string | null;
11
+ /**
12
+ * The id of the current site's Business account, so a feature can be targeted by
13
+ * Business account. `undefined` means still loading and `null` means there is none.
14
+ * Evaluation never waits for it: only a feature targeted by Business account is held
15
+ * off until it settles, and is then answered for it.
16
+ */
17
+ businessAccountId?: string | null;
11
18
  }
12
19
  export interface P1ExperimentalFeatures {
13
20
  /**
@@ -22,14 +29,14 @@ export interface P1ExperimentalFeatures {
22
29
  resolved: boolean;
23
30
  }
24
31
  /**
25
- * Which experimental features are turned on for this person, on this site.
32
+ * Which experimental features are turned on for this person, on this site, in this Business account.
26
33
  *
27
34
  * Availability is Pantheon's to decide, so a caller asks and wires the answer through
28
35
  * rather than configuring anything: an unset flag, an unreachable LaunchDarkly and a
29
36
  * signed-out reader all report off.
30
37
  *
31
- * Resolved once per user and site for the life of the page and shared between every
32
- * caller, so this can be called from as many components as need it. A flag changed
38
+ * Resolved once per user and site for the life of the page, plus once more per Business
39
+ * account for features targeted by it, and shared between every caller, so this can be called from as many components as need it. A flag changed
33
40
  * mid-session takes effect on the next load.
34
41
  */
35
42
  export declare function useP1ExperimentalFeatures(options: UseP1ExperimentalFeaturesOptions): P1ExperimentalFeatures;
@@ -1,20 +1,41 @@
1
1
  "use client";
2
2
  import { useEffect, useMemo, useState } from "react";
3
3
  import { resolveClientSideId } from "../launchdarkly/client-side-id";
4
- import { ALL_OFF } from "./features";
4
+ import { ALL_OFF, BUSINESS_ACCOUNT_TARGETED_FEATURES, } from "./features";
5
5
  import { buildFeatureContext, resolveFeatures } from "./resolve-features";
6
6
  import { featuresFor, peekFeatures, sessionKey } from "./session-cache";
7
7
  function peek(key) {
8
8
  return key ? peekFeatures(key) : null;
9
9
  }
10
10
  export function useP1ExperimentalFeatures(options) {
11
- const { userId, siteId } = options;
11
+ const { userId, siteId, businessAccountId } = options;
12
12
  const clientSideId = resolveClientSideId();
13
- const key = clientSideId && userId
14
- ? sessionKey(clientSideId, userId, siteId ?? undefined)
13
+ const targetsBusinessAccount = BUSINESS_ACCOUNT_TARGETED_FEATURES.length > 0;
14
+ const key = clientSideId && userId ? sessionKey(clientSideId, userId, siteId ?? undefined) : null;
15
+ const businessAccountKey = clientSideId && userId && targetsBusinessAccount && businessAccountId
16
+ ? sessionKey(clientSideId, userId, siteId ?? undefined, businessAccountId)
15
17
  : null;
18
+ const base = useAnswer(key, clientSideId, userId, siteId, undefined);
19
+ const withBusinessAccount = useAnswer(businessAccountKey, clientSideId, userId, siteId, businessAccountId);
20
+ const waitingForBusinessAccount = targetsBusinessAccount &&
21
+ (businessAccountId === undefined || (businessAccountKey !== null && !withBusinessAccount));
22
+ const features = useMemo(() => {
23
+ if (!base) {
24
+ return null;
25
+ }
26
+ const merged = { ...base };
27
+ for (const feature of BUSINESS_ACCOUNT_TARGETED_FEATURES) {
28
+ merged[feature] = waitingForBusinessAccount ? false : (withBusinessAccount ?? base)[feature];
29
+ }
30
+ return merged;
31
+ }, [base, withBusinessAccount, waitingForBusinessAccount]);
32
+ return useMemo(() => ({
33
+ isEnabled: (feature) => (features ?? ALL_OFF)[feature],
34
+ resolved: features !== null && !waitingForBusinessAccount,
35
+ }), [features, waitingForBusinessAccount]);
36
+ }
37
+ function useAnswer(key, clientSideId, userId, siteId, businessAccountId) {
16
38
  const [answer, setAnswer] = useState(() => ({ key, features: peek(key) }));
17
- const features = answer.key === key ? answer.features : peek(key);
18
39
  useEffect(() => {
19
40
  if (!key || !userId) {
20
41
  return;
@@ -25,7 +46,7 @@ export function useP1ExperimentalFeatures(options) {
25
46
  return;
26
47
  }
27
48
  let active = true;
28
- void featuresFor(key, () => resolveFeatures(clientSideId, buildFeatureContext(userId, siteId ?? undefined))).then((resolved) => {
49
+ void featuresFor(key, () => resolveFeatures(clientSideId, buildFeatureContext(userId, siteId ?? undefined, businessAccountId))).then((resolved) => {
29
50
  if (active) {
30
51
  setAnswer({ key, features: resolved });
31
52
  }
@@ -33,9 +54,6 @@ export function useP1ExperimentalFeatures(options) {
33
54
  return () => {
34
55
  active = false;
35
56
  };
36
- }, [key, clientSideId, userId, siteId]);
37
- return useMemo(() => ({
38
- isEnabled: (feature) => (features ?? ALL_OFF)[feature],
39
- resolved: features !== null,
40
- }), [features]);
57
+ }, [key, clientSideId, userId, siteId, businessAccountId]);
58
+ return answer.key === key ? answer.features : peek(key);
41
59
  }
package/dist/handler.d.ts CHANGED
@@ -21,7 +21,8 @@ export type P1HandlerConfig = P1DataConfig & {
21
21
  * Dynamic segment this app renders public pages from, as Next.js names it for
22
22
  * revalidatePath. Publishing a route template invalidates it so instance URLs
23
23
  * that resolve by template fall-through alone are refreshed too. Defaults to
24
- * the scaffolded app's `/[...puckPath]`.
24
+ * both `/[...puckPath]` and `/[[...puckPath]]`; an app rendering pages from
25
+ * another segment names it here.
25
26
  */
26
27
  publicPageSegment?: string;
27
28
  };
package/dist/index.d.ts CHANGED
@@ -4,3 +4,4 @@ export { createP1EditorClient } from "./editor-client";
4
4
  export type { CreateP1EditorClientOptions, P1EditorContext, P1EditorExtensions, } from "./editor-client";
5
5
  export { useP1ExperimentalFeatures } from "./experimental-features";
6
6
  export type { P1ExperimentalFeature, P1ExperimentalFeatures, UseP1ExperimentalFeaturesOptions, } from "./experimental-features";
7
+ export { P1LocalizationProvider, useP1Localization, type P1Localization, type PublishedPageLocalization, } from "./localization-react";
package/dist/index.js CHANGED
@@ -2,3 +2,4 @@ export { P1NextRouterProvider } from "./P1NextRouterProvider";
2
2
  export { parseEditorSegments, editorPagePathFromUrlPath, } from "./editor-paths";
3
3
  export { createP1EditorClient } from "./editor-client";
4
4
  export { useP1ExperimentalFeatures } from "./experimental-features";
5
+ export { P1LocalizationProvider, useP1Localization, } from "./localization-react";
@@ -0,0 +1,4 @@
1
+ export type { LocalePolicy, PageListEntry, PageListResult, PageLocalization, PageLocaleVariant, SiteLocales, } from "@pantheon-systems/css-client";
2
+ export { getMatchingLocale, isLocalized, isSameLocale, resolveVisitorLocale, type ResolveVisitorLocaleOptions, } from "@pantheon-systems/css-client/localization";
3
+ export { SAVED_LOCALE_COOKIE, getSavedLocale, saveLocale, } from "./saved-locale";
4
+ export { getHreflangAlternates, getLocaleVariants, getSavedLocaleSuggestion, type LocaleVariant, type SavedLocaleSuggestionOptions, } from "@pantheon-systems/css-client/localization";
@@ -0,0 +1,3 @@
1
+ export { getMatchingLocale, isLocalized, isSameLocale, resolveVisitorLocale, } from "@pantheon-systems/css-client/localization";
2
+ export { SAVED_LOCALE_COOKIE, getSavedLocale, saveLocale, } from "./saved-locale";
3
+ export { getHreflangAlternates, getLocaleVariants, getSavedLocaleSuggestion, } from "@pantheon-systems/css-client/localization";
@@ -0,0 +1,13 @@
1
+ /** Name of the cookie that remembers the visitor's chosen locale. */
2
+ export declare const SAVED_LOCALE_COOKIE = "p1_locale";
3
+ /**
4
+ * The visitor's saved locale, read in the browser.
5
+ *
6
+ * @returns The saved locale, or `null` when none is saved, the value is not a locale tag, or there is no `document`.
7
+ */
8
+ export declare function getSavedLocale(): string | null;
9
+ /**
10
+ * Remembers `locale` as the visitor's choice for later visits, in a site-wide
11
+ * cookie that lasts a year. Does nothing outside a browser.
12
+ */
13
+ export declare function saveLocale(locale: string): void;
@@ -0,0 +1,20 @@
1
+ import { parseCookie, stringifySetCookie } from "cookie";
2
+ export const SAVED_LOCALE_COOKIE = "p1_locale";
3
+ const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
4
+ const LOCALE_TAG = /^[A-Za-z]{2,8}([-_][A-Za-z0-9]{1,8})*$/;
5
+ export function getSavedLocale() {
6
+ if (typeof document === "undefined")
7
+ return null;
8
+ const value = parseCookie(document.cookie)[SAVED_LOCALE_COOKIE];
9
+ return value !== undefined && LOCALE_TAG.test(value) ? value : null;
10
+ }
11
+ export function saveLocale(locale) {
12
+ if (typeof document === "undefined")
13
+ return;
14
+ document.cookie = stringifySetCookie(SAVED_LOCALE_COOKIE, locale, {
15
+ path: "/",
16
+ maxAge: ONE_YEAR_SECONDS,
17
+ sameSite: "lax",
18
+ secure: location.protocol === "https:",
19
+ });
20
+ }
@@ -0,0 +1,40 @@
1
+ import { type ReactNode } from "react";
2
+ import type { PageLocalization, SiteLocales } from "@pantheon-systems/css-client";
3
+ import type { LocaleVariant } from "@pantheon-systems/css-client/localization";
4
+ /**
5
+ * A localized page as the render pipeline describes it to the app. Plain JSON,
6
+ * so it crosses from server to client components.
7
+ */
8
+ export type PublishedPageLocalization = {
9
+ /** The page's locale, or `null` when it has none set. */
10
+ locale: string | null;
11
+ /** The path of the page. */
12
+ path: string;
13
+ siteLocales: SiteLocales;
14
+ localization: PageLocalization;
15
+ /**
16
+ * The page itself and its other locale variants: those in the site's locales
17
+ * first, in the site's order, then those with `locale: null`.
18
+ */
19
+ variants: LocaleVariant[];
20
+ };
21
+ /** What `useP1Localization` returns. */
22
+ export type P1Localization = {
23
+ /** The page's locale, or `null` outside a localized page. */
24
+ locale: string | null;
25
+ /** The site's locales, or `null` outside a localized page. */
26
+ siteLocales: SiteLocales | null;
27
+ /** Every locale variant of the page, for a language switcher. Empty outside a localized page. */
28
+ variants: LocaleVariant[];
29
+ };
30
+ /**
31
+ * Makes a localized page's details available to `useP1Localization` below it.
32
+ * `createPublishedPage` renders it around the app's client for every page on a
33
+ * site with locales.
34
+ */
35
+ export declare function P1LocalizationProvider({ value, children, }: {
36
+ value: P1Localization;
37
+ children?: ReactNode;
38
+ }): import("react").JSX.Element;
39
+ /** The current page's locale and its locale variants. */
40
+ export declare function useP1Localization(): P1Localization;
@@ -0,0 +1,15 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { createContext, useContext } from "react";
4
+ const LocalizationContext = createContext(null);
5
+ export function P1LocalizationProvider({ value, children, }) {
6
+ return _jsx(LocalizationContext.Provider, { value: value, children: children });
7
+ }
8
+ export function useP1Localization() {
9
+ const page = useContext(LocalizationContext);
10
+ return {
11
+ locale: page?.locale ?? null,
12
+ siteLocales: page?.siteLocales ?? null,
13
+ variants: page?.variants ?? [],
14
+ };
15
+ }
@@ -0,0 +1,12 @@
1
+ import type { Data } from "@puckeditor/core";
2
+ import type { PageLocalization, SiteLocales } from "@pantheon-systems/css-client";
3
+ /**
4
+ * A published page's localization and the site's locales, as carried on the
5
+ * page data returned by `loadPublishedPage`.
6
+ *
7
+ * @returns Both, or `null` when the site has no locales or the page carries no locale variants.
8
+ */
9
+ export declare function getPageLocalization(data: Data): {
10
+ localization: PageLocalization;
11
+ siteLocales: SiteLocales;
12
+ } | null;
@@ -0,0 +1,9 @@
1
+ import { isLocalized } from "@pantheon-systems/css-client/localization";
2
+ export function getPageLocalization(data) {
3
+ const props = data.root?.props;
4
+ const localization = props?._localization;
5
+ const siteLocales = props?._siteLocales;
6
+ if (!Array.isArray(localization?.variants) || !isLocalized(siteLocales))
7
+ return null;
8
+ return { localization, siteLocales };
9
+ }
@@ -25,8 +25,8 @@ export function createP1Pages(opts) {
25
25
  console.warn("[p1-next-sdk] The P1 editor now renders from pages.Layout, but this " +
26
26
  "app rendered pages.Page without it — the editor will be empty. Mount " +
27
27
  "it at app/p1/(editor)/layout.tsx, or run: " +
28
- "npx @pantheon-systems/p1-next-sdk migrate — see " +
29
- "docs/MIGRATION-EDITOR-LAYOUT.md");
28
+ "npx @pantheon-systems/p1-next-sdk migrate editor-layout — see " +
29
+ "node_modules/@pantheon-systems/p1-next-sdk/docs/migrations/editor-layout.md");
30
30
  }
31
31
  return null;
32
32
  }
@@ -1,7 +1,5 @@
1
1
  import { NextResponse } from "next/server";
2
- import { DEFAULT_PUBLIC_PAGE_SEGMENT } from "./revalidate";
3
2
  export { postPublish as POST };
4
- export { DEFAULT_PUBLIC_PAGE_SEGMENT };
5
3
  export declare function postPublish(request: Request, { publicPageSegment }?: {
6
4
  publicPageSegment?: string;
7
5
  }): Promise<NextResponse<{
@@ -1,9 +1,8 @@
1
1
  import { NextResponse } from "next/server";
2
2
  import { normalizePath, persistPublishedPage } from "@pantheon-systems/puck-css/server";
3
- import { DEFAULT_PUBLIC_PAGE_SEGMENT, revalidatePublishedPath } from "./revalidate";
3
+ import { revalidatePublishedPath } from "./revalidate";
4
4
  export { postPublish as POST };
5
- export { DEFAULT_PUBLIC_PAGE_SEGMENT };
6
- export async function postPublish(request, { publicPageSegment = DEFAULT_PUBLIC_PAGE_SEGMENT } = {}) {
5
+ export async function postPublish(request, { publicPageSegment } = {}) {
7
6
  const payload = (await request.json());
8
7
  const path = payload.path === "/" ? "/" : normalizePath(payload.path);
9
8
  if (path === null) {
@@ -16,11 +16,11 @@
16
16
  import { NextResponse } from "next/server";
17
17
  export { postRevalidate as POST };
18
18
  /**
19
- * Dynamic segment rendering public pages, as Next.js names it for
20
- * revalidatePath. Overridable for an app whose catch-all directory is not
21
- * `[...puckPath]`.
19
+ * Dynamic segments that may render public pages, as Next.js names them for
20
+ * revalidatePath: the required and the optional catch-all. An app whose
21
+ * catch-all directory is neither names its own.
22
22
  */
23
- export declare const DEFAULT_PUBLIC_PAGE_SEGMENT = "/[...puckPath]";
23
+ export declare const DEFAULT_PUBLIC_PAGE_SEGMENTS: readonly string[];
24
24
  /**
25
25
  * Invalidate every cached route the content at `path` can be served through.
26
26
  *
@@ -2,17 +2,23 @@ import { revalidatePath } from "next/cache";
2
2
  import { NextResponse } from "next/server";
3
3
  import { isRouteTemplatePath, normalizePath, listOverridePathsForBase, } from "@pantheon-systems/puck-css/server";
4
4
  export { postRevalidate as POST };
5
- export const DEFAULT_PUBLIC_PAGE_SEGMENT = "/[...puckPath]";
6
- export async function revalidatePublishedPath(path, publicPageSegment = DEFAULT_PUBLIC_PAGE_SEGMENT) {
5
+ export const DEFAULT_PUBLIC_PAGE_SEGMENTS = [
6
+ "/[...puckPath]",
7
+ "/[[...puckPath]]",
8
+ ];
9
+ export async function revalidatePublishedPath(path, publicPageSegment) {
7
10
  revalidatePath(path);
8
11
  if (!isRouteTemplatePath(path))
9
12
  return;
10
13
  for (const p of await listOverridePathsForBase(path)) {
11
14
  revalidatePath(p);
12
15
  }
13
- revalidatePath(publicPageSegment, "page");
16
+ const segments = publicPageSegment === undefined ? DEFAULT_PUBLIC_PAGE_SEGMENTS : [publicPageSegment];
17
+ for (const segment of segments) {
18
+ revalidatePath(segment, "page");
19
+ }
14
20
  }
15
- export async function postRevalidate(request, { publicPageSegment = DEFAULT_PUBLIC_PAGE_SEGMENT } = {}) {
21
+ export async function postRevalidate(request, { publicPageSegment } = {}) {
16
22
  const payload = (await request.json().catch(() => null));
17
23
  const raw = typeof payload?.path === "string" ? payload.path : null;
18
24
  if (raw === null) {
package/dist/server.d.ts CHANGED
@@ -5,5 +5,7 @@ export { createCssQueryFetchers, type CreateCssQueryFetchersOptions } from "./cs
5
5
  export { createP1Middleware, type P1MiddlewareConfig } from "./middleware";
6
6
  export { createPublishedPage, type CreatePublishedPageConfig, type PublishedPageClientProps, type PublishedPageMetadata, } from "./create-published-page";
7
7
  export { loadPublishedPage, loadRouteTemplateKeys, type LoadPublishedPageOptions, type PublishedPageResult, } from "./published-page";
8
+ export { getPageLocalization } from "./page-localization";
9
+ export type { PublishedPageLocalization } from "./localization-react";
8
10
  export { buildPageMetadata, type PageHeadMetadata, type PageMetaFields, type SiteMetaDefaults, } from "./page-metadata";
9
11
  export { resolvePageMetadata, type ResolvePageMetadataOptions, type PageMetadataContext, type AuthoredPageMeta, } from "./resolve-page-metadata";
package/dist/server.js CHANGED
@@ -5,5 +5,6 @@ export { createCssQueryFetchers } from "./css-query-fetchers";
5
5
  export { createP1Middleware } from "./middleware";
6
6
  export { createPublishedPage, } from "./create-published-page";
7
7
  export { loadPublishedPage, loadRouteTemplateKeys, } from "./published-page";
8
+ export { getPageLocalization } from "./page-localization";
8
9
  export { buildPageMetadata, } from "./page-metadata";
9
10
  export { resolvePageMetadata, } from "./resolve-page-metadata";
@@ -0,0 +1,213 @@
1
+ # Migration Guide: Persistent Editor Layout
2
+
3
+ This guide covers upgrading to `@pantheon-systems/p1-next-sdk@0.8.x`, in which the P1 editor renders from a persistent **layout** instead of the catch-all **page**. This is what lets the editor survive navigation between documents without a full remount (no more teardown of providers, auth, and the Puck canvas iframe on every page switch).
4
+
5
+ New projects scaffolded with `create-p1-starter-kit@0.8.x` already have the new structure — this guide is only for **existing apps upgrading the SDK**.
6
+
7
+ ## Breaking: the editor moved from `pages.Page` to `pages.Layout`
8
+
9
+ `createP1Pages()` now returns a `Layout` that renders the editor, and `Page` is intentionally empty. The editor must be mounted from a static route segment — an `(editor)` route group — so it persists across route-param changes. `EditorClient` is now rendered with **no props** and derives the edited page from the URL.
10
+
11
+ > **This is a silent breaking change for JavaScript apps.** If you upgrade but keep only the old `app/p1/[[...p1]]/page.tsx` (`export default pages.Page`), `pages.Page` renders `null` and the editor is **blank with no build error**. TypeScript apps get a compile error first — the `EditorClient` prop type changed from `{ path: string }` to no props — but JS apps get no signal. In development the SDK logs a one-time warning pointing here.
12
+
13
+ ## Recommended: run the codemod
14
+
15
+ From your project root, on a clean git tree:
16
+
17
+ ```bash
18
+ npx @pantheon-systems/p1-next-sdk migrate editor-layout
19
+ ```
20
+
21
+ It restructures the routes for you and leaves sibling routes (`/p1/merge`, `/p1/api`, `/p1/auth`) untouched. It writes code that only newer P1 packages export, so it checks the suite you have installed first and tells you to upgrade before it touches anything. Step 6 below needs a newer suite than the route move does; against an older one the codemod says so, skips that step alone, and leaves your existing chatbot gate working. Preview first with `--dry-run`; the codemod refuses to run on a dirty tree unless you pass `--force`, is safe to re-run (idempotent), and **bails with a pointer back to this guide** if your files have diverged from the starter shape. If it bails, follow the manual steps below.
22
+
23
+ ```bash
24
+ npx @pantheon-systems/p1-next-sdk migrate editor-layout --dry-run # preview
25
+ npx @pantheon-systems/p1-next-sdk migrate editor-layout # apply
26
+ ```
27
+
28
+ Review the diff and commit it as its own change.
29
+
30
+ ## Manual steps
31
+
32
+ If you customized the editor route and the codemod bailed, apply the same transform by hand. The move adds one real on-disk directory (`(editor)/`) that the URL never sees, so **every relative import in a moved file gains one `../`**.
33
+
34
+ ### 1. Move the catch-all into an `(editor)` route group
35
+
36
+ ```
37
+ app/p1/[[...p1]]/page.tsx -> app/p1/(editor)/[[...p1]]/p1-pages.tsx (+ new page.tsx)
38
+ app/p1/[[...p1]]/editor-client.tsx -> app/p1/(editor)/[[...p1]]/editor-client.tsx
39
+ app/p1/(editor)/layout.tsx (new)
40
+ ```
41
+
42
+ Sibling routes stay **outside** the group so the editor never wraps them:
43
+
44
+ ```
45
+ app/p1/merge/… app/p1/api/… app/p1/auth/… (unchanged)
46
+ ```
47
+
48
+ ### 2. Split `page.tsx` into a shared factory module + a thin page
49
+
50
+ Extract the `createP1Pages(...)` call into `p1-pages.tsx` and **export** it, so both the layout and the page can import it. Deepen the `config` import by one level, and drop the `puck.css` side-effect import (it moves to the layout).
51
+
52
+ `app/p1/(editor)/[[...p1]]/p1-pages.tsx`:
53
+ ```diff
54
+ -import "@puckeditor/core/puck.css";
55
+ import { createP1Pages } from "@pantheon-systems/p1-next-sdk/server";
56
+ -import config from "../../../puck.config";
57
+ +import config from "../../../../puck.config";
58
+ import { EditorClientWrapper } from "./editor-client";
59
+
60
+ -const pages = createP1Pages({
61
+ +export const pages = createP1Pages({
62
+ config,
63
+ // …your existing options…
64
+ EditorClient: EditorClientWrapper,
65
+ });
66
+ -
67
+ -export default pages.Page;
68
+ -export const generateMetadata = pages.generateMetadata;
69
+ -export const dynamic = "force-dynamic";
70
+ ```
71
+
72
+ `app/p1/(editor)/[[...p1]]/page.tsx` (new, thin):
73
+ ```tsx
74
+ import { pages } from "./p1-pages";
75
+
76
+ export default pages.Page;
77
+ export const generateMetadata = pages.generateMetadata;
78
+ export const dynamic = "force-dynamic";
79
+ ```
80
+
81
+ ### 3. Add the `(editor)` layout
82
+
83
+ `app/p1/(editor)/layout.tsx` (new):
84
+ ```tsx
85
+ import "@puckeditor/core/puck.css";
86
+ import { pages } from "./[[...p1]]/p1-pages";
87
+
88
+ export default pages.Layout;
89
+ ```
90
+
91
+ The editor layout (the one rendering `pages.Layout`) must live at the `(editor)` group, **not** at `app/p1/layout.tsx` — a layout at `/p1` would wrap every sibling route (`/p1/merge`, …) and render the editor on top of them. A root layout at `app/p1/layout.tsx` that renders only the `<html>` and `<body>`, as the [localized published pages](./localized-pages.md) guide adds, is fine.
92
+
93
+ ### 4. Derive the edited path from the URL in `editor-client.tsx`
94
+
95
+ `EditorClient` is rendered by the layout with no props, so it reads the path from the URL instead of a prop. Add `usePathname` and `editorPagePathFromUrlPath`, and drop the `{ path }` parameter:
96
+
97
+ ```diff
98
+ -import { useRouter } from "next/navigation";
99
+ +import { usePathname, useRouter } from "next/navigation";
100
+ -import { P1NextRouterProvider } from "@pantheon-systems/p1-next-sdk";
101
+ +import { P1NextRouterProvider, editorPagePathFromUrlPath } from "@pantheon-systems/p1-next-sdk";
102
+ ```
103
+
104
+ ```diff
105
+ -export function EditorClientWrapper({ path }: { path: string }) {
106
+ +export function EditorClientWrapper() {
107
+ + const pathname = usePathname();
108
+ + const path = editorPagePathFromUrlPath(pathname);
109
+ // …rest of the component unchanged…
110
+ ```
111
+
112
+ Then deepen the remaining relative imports in this file by one level (`../../../…` → `../../../../…`).
113
+
114
+ ### 5. Remove any `NON_EDITOR_ROUTES` opt-out list
115
+
116
+ Earlier versions kept the editor off sibling routes with a hand-maintained `NON_EDITOR_ROUTES` array. The `(editor)` route group makes siblings editor-free by construction, so delete that list.
117
+
118
+ ### 6. Hand the AI chatbot's rollout gate to the SDK
119
+
120
+ Optional, and the one step with its own version requirement: it imports
121
+ `@pantheon-systems/p1-next-sdk/chatbot`, so skip it if your installed suite predates that
122
+ entry point. The app-level gate below keeps working until the rollout flag retires.
123
+
124
+ Earlier starters carried the chatbot's rollout plumbing themselves: a local
125
+ `ChatbotFlagProvider`, a hardcoded flag key, a `lib/chatbot-flag/` directory, and a
126
+ feature-flag SDK in the app's own `package.json`. Whether the chatbot is available to a
127
+ site is Pantheon's decision, not the application's, so it now lives behind
128
+ `@pantheon-systems/p1-next-sdk/chatbot` — and nothing in your project has to change when
129
+ the rollout ends.
130
+
131
+ ```diff
132
+ -import { createAIChatPlugin } from "@pantheon-systems/p1-ai-chat";
133
+ -import { useFlags } from "launchdarkly-react-client-sdk";
134
+ +import { P1ChatbotProvider, useP1Chatbot } from "@pantheon-systems/p1-next-sdk/chatbot";
135
+ -import { ChatbotFlagProvider } from "../../../../components/ChatbotFlagProvider";
136
+ -import { shouldShowChatbot, CHATBOT_FLAG_KEY } from "../../../../lib/chatbot-flag/feature-gate";
137
+ -import { createGenerateWithAIHandler } from "../../../../lib/chatbot-flag/ai-generate";
138
+ -import { getDraftRequestChannel } from "../../../../lib/chatbot-flag/draft-request-channel";
139
+ ```
140
+
141
+ Swap the provider:
142
+
143
+ ```diff
144
+ - <ChatbotFlagProvider>
145
+ + <P1ChatbotProvider>
146
+ <EditorContent path={path} />
147
+ - </ChatbotFlagProvider>
148
+ + </P1ChatbotProvider>
149
+ ```
150
+
151
+ There is nothing left to branch on — an unavailable chatbot contributes no plugins, no
152
+ handler and an unchanged remount key:
153
+
154
+ ```diff
155
+ - const flags = useFlags();
156
+ - const agentUrl = process.env.NEXT_PUBLIC_AGENT_URL;
157
+ - const chatbotEnabled = shouldShowChatbot(flags[CHATBOT_FLAG_KEY], agentUrl);
158
+ - const draftRequests = getDraftRequestChannel();
159
+ - const aiPlugin = React.useMemo(
160
+ - () =>
161
+ - chatbotEnabled && agentUrl
162
+ - ? createAIChatPlugin({ agentUrl, draftRequests, onPageCreated: handlePageCreated })
163
+ - : null,
164
+ - [chatbotEnabled, agentUrl, draftRequests, handlePageCreated],
165
+ - );
166
+ + const chatbot = useP1Chatbot({ onPageCreated: handlePageCreated });
167
+ const additionalPlugins = React.useMemo(
168
+ - () => (aiPlugin ? [...p1Plugins, mediaPlugin, aiPlugin] : [...p1Plugins, mediaPlugin]),
169
+ - [p1Plugins, mediaPlugin, aiPlugin],
170
+ + () => [...p1Plugins, mediaPlugin, ...chatbot.plugins],
171
+ + [p1Plugins, mediaPlugin, chatbot.plugins],
172
+ );
173
+ ```
174
+
175
+ ```diff
176
+ pluginOptions: {
177
+ onDocumentSelect: handleDocumentSelect,
178
+ - onGenerateWithAI: createGenerateWithAIHandler(draftRequests, chatbotEnabled),
179
+ - showAIPanelToggle: chatbotEnabled,
180
+ + ...chatbot.pluginOptions,
181
+ ```
182
+
183
+ ```diff
184
+ - <Puck key={`${puckKey}-${chatbotEnabled ? "ai" : "no-ai"}`} {...puckProps as any} _experimentalFullScreenCanvas={true} />
185
+ + <Puck key={`${puckKey}${chatbot.editorKeySuffix}`} {...puckProps as any} _experimentalFullScreenCanvas={true} />
186
+ ```
187
+
188
+ Nothing imports the old gate afterwards, so it can go — the codemod leaves these for you
189
+ rather than deleting files it was not asked to move:
190
+
191
+ - `lib/chatbot-flag/` and `components/ChatbotFlagProvider.tsx`, plus their test files
192
+ - `launchdarkly-react-client-sdk` and `@pantheon-systems/p1-ai-chat` in `package.json`
193
+ - `NEXT_PUBLIC_LD_CLIENT_ID` in `.env` / `.env.example`
194
+
195
+ `NEXT_PUBLIC_AGENT_URL` still applies, and still belongs to the environment rather than
196
+ to your source.
197
+
198
+ ## Minimum structure after migration
199
+
200
+ ```
201
+ app/p1/
202
+ (editor)/
203
+ layout.tsx # export default pages.Layout
204
+ [[...p1]]/
205
+ p1-pages.tsx # export const pages = createP1Pages({ … })
206
+ page.tsx # re-exports pages.Page / generateMetadata / dynamic
207
+ editor-client.tsx # EditorClientWrapper() — derives path from the URL
208
+ merge/ # siblings stay outside (editor)
209
+ api/
210
+ auth/
211
+ ```
212
+
213
+ The editor is mounted at `/p1`; the client derives the edited page via `editorPagePathFromUrlPath`, whose base path defaults to `/p1`. If you mount the editor somewhere else, pass the matching base path to `editorPagePathFromUrlPath`.