@sjolystinnovation/app-kit 0.21.0 → 1.0.0

package/src/next-config/index.ts

@@ -1,128 +1,39 @@
 import type { NextConfig } from "next";
+import { contentImagesRewrite, securityHeaders, type CspOptions, type Header } from "./headers";
 
-/** A response header, as `next.config.ts` lists them. */
-export interface Header {
-  key: string;
-  value: string;
-}
-
-/** The API's origin, such as `https://api.example.com`. Empty when the URL is missing or invalid. */
-export function apiOrigin(apiUrl: string | undefined): string {
-  if (!apiUrl) return "";
-  try {
-    return new URL(apiUrl).origin;
-  } catch {
-    return "";
-  }
-}
-
-/** The API's base URL with its path, such as `https://api.example.com/api`, without a trailing slash. Empty when missing or invalid. */
-export function apiBaseUrl(apiUrl: string | undefined): string {
-  if (!apiUrl) return "";
-  try {
-    return new URL(apiUrl).toString().replace(/\/$/, "");
-  } catch {
-    return "";
-  }
-}
-
-export interface CspOptions {
-  /** The app's API URL, usually `process.env.NEXT_PUBLIC_API_URL`. Its origin may be fetched from. */
-  apiUrl: string | undefined;
-  /** Development builds also allow `'unsafe-eval'`, which hot reload needs. */
-  dev: boolean;
-  /** Also allow `ws:` and `wss:` to the API, for a WebSocket such as SignalR. */
-  websocket?: boolean | undefined;
-  /** Also allow images from the API origin. Not needed when images go through the content images rewrite. */
-  imgFromApi?: boolean | undefined;
-  /** Extra sources for `connect-src`. */
-  connectSrc?: readonly string[] | undefined;
-  /** Extra sources for `img-src`. */
-  imgSrc?: readonly string[] | undefined;
-  /** Sources for `frame-src`. Defaults to `'none'`, since no page embeds a frame. */
-  frameSrc?: readonly string[] | undefined;
-  /** Sources for `object-src`. Defaults to `'none'`, since no page embeds an object. */
-  objectSrc?: readonly string[] | undefined;
-}
-
-const sources = (list: readonly (string | false | undefined)[]) => list.filter(Boolean).join(" ");
-
-/**
- * The Content-Security-Policy for an app's pages. Scripts allow `'unsafe-inline'`, because a nonce
- * would make every statically rendered page dynamic.
- */
-export function contentSecurityPolicy(o: CspOptions): string {
-  const origin = apiOrigin(o.apiUrl);
-  const wsOrigin = o.websocket ? origin.replace(/^https:/, "wss:").replace(/^http:/, "ws:") : "";
-  return [
-    "default-src 'self'",
-    o.dev ? "script-src 'self' 'unsafe-eval' 'unsafe-inline'" : "script-src 'self' 'unsafe-inline'",
-    "style-src 'self' 'unsafe-inline'",
-    `img-src ${sources(["'self'", o.imgFromApi && origin, "data:", "blob:", ...(o.imgSrc ?? [])])}`,
-    `connect-src ${sources(["'self'", origin, wsOrigin, ...(o.connectSrc ?? [])])}`,
-    `frame-src ${sources(o.frameSrc ?? ["'none'"])}`,
-    `object-src ${sources(o.objectSrc ?? ["'none'"])}`,
-    "font-src 'self'",
-    "base-uri 'self'",
-    "form-action 'self'",
-    "frame-ancestors 'none'",
-    "upgrade-insecure-requests",
-  ].join("; ");
-}
-
-/** The security headers for an app's pages, including the Content-Security-Policy. */
-export function securityHeaders(o: CspOptions & { permissionsPolicy?: string | undefined }): Header[] {
-  return [
-    { key: "X-Content-Type-Options", value: "nosniff" },
-    { key: "X-Frame-Options", value: "DENY" },
-    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
-    { key: "X-DNS-Prefetch-Control", value: "on" },
-    { key: "Permissions-Policy", value: o.permissionsPolicy ?? "camera=(), microphone=(), geolocation=()" },
-    { key: "Strict-Transport-Security", value: "max-age=31536000; includeSubDomains" },
-    { key: "Content-Security-Policy", value: contentSecurityPolicy(o) },
-  ];
-}
-
-/**
- * Content images, proxied so the browser never contacts the API host. A rewrite rather than a route
- * handler, so the query string and the Accept header, which webp needs, pass through. No rewrite
- * when the API URL is missing or invalid.
- */
-export function contentImagesRewrite(apiUrl: string | undefined, o: { source?: string | undefined; upstreamPath?: string | undefined } = {}) {
-  const base = apiBaseUrl(apiUrl);
-  if (!base) return [];
-  const source = o.source ?? "/content-images";
-  const upstream = o.upstreamPath ?? "/content-images";
-  return [{ source: `${source}/:path*`, destination: `${base}${upstream}/:path*` }];
-}
+export type { CspOptions } from "./headers";
 
+/** Options for `defineAppConfig`. */
 export interface AppConfigOptions extends CspOptions {
-  /** Proxy `/content-images/*` to the API. See `contentImagesRewrite`. */
+  /**
+   * Whether to proxy `/content-images/*` to the API. The rewrite keeps the browser off the API host
+   * and passes the query string and the Accept header through.
+   */
   contentImages?: boolean | undefined;
   /**
-   * Headers for particular paths. Every path gets the page headers, and these come after them, so
-   * they replace a page header of the same name.
+   * The headers for particular paths. Every path gets the page headers, and these come after them,
+   * so they replace a page header of the same name.
    */
   pathHeaders?: readonly { source: string; headers: Header[] }[] | undefined;
-  /** Replaces the default Permissions-Policy. */
+  /** A Permissions-Policy that replaces the default one. */
   permissionsPolicy?: string | undefined;
   /**
-   * Seconds a cache may go on serving a page after it goes stale. Next's default is a year, long
-   * enough for a browser to hand back an old page and fetch the current one behind it. Defaults to
-   * 300, matching the client router cache's stale time.
+   * The number of seconds a cache may go on serving a page after it goes stale. Next's default is a
+   * year, long enough for a browser to hand back an old page and fetch the current one behind it.
+   * Defaults to `300`, matching the client router cache's stale time.
    */
   expireTime?: number | undefined;
   /**
-   * Write revalidated pages to disk. Off by default: with a read-only root filesystem Next cannot
-   * write to `.next/server/app`, so the incremental cache stays in memory.
+   * Whether to write revalidated pages to disk. Defaults to `false`. With a read-only root
+   * filesystem, Next cannot write to `.next/server/app`, so the incremental cache stays in memory.
    */
   isrFlushToDisk?: boolean | undefined;
 }
 
 /**
- * The shared Next config for an app: the standalone build, app-kit transpiled, no `X-Powered-By`,
- * the security headers on every page, and optionally the content images rewrite. `extra` is merged
- * over it, with `transpilePackages` and `images` combined.
+ * Builds the shared Next config for an app: the standalone build, app-kit transpiled, no
+ * `X-Powered-By`, the security headers on every page, and optionally the content images rewrite.
+ * `extra` is merged over it, with `transpilePackages` and `images` combined.
  */
 export function defineAppConfig(o: AppConfigOptions, extra: NextConfig = {}): NextConfig {
   const pageHeaders = securityHeaders(o);

package/src/payments/PaymentReturn.tsx

@@ -5,32 +5,34 @@ import Link from "next/link";
 import type { ReactNode } from "react";
 import { cx } from "../ui/cx";
 
+/** The outcome of a payment, as `PaymentReturn` shows it. */
 export type PaymentReturnState = "success" | "pending" | "failed";
 
-/** The text and the way on for one state. */
+/** The text and the next step for one state. */
 export interface PaymentReturnContent {
   title: string;
   body: string;
-  /** Where the button goes. */
+  /** The button's link target. */
   href: string;
   /** The button's text. */
   cta: string;
   /** A smaller line under the body. */
   note?: string | undefined;
-  /** Anything more under the body, such as a receipt link. */
+  /** Any more content under the body, such as a receipt link. */
   extra?: ReactNode;
 }
 
+/** Props for `PaymentReturn`. */
 export interface PaymentReturnProps {
   state: PaymentReturnState;
   success: PaymentReturnContent;
   pending: PaymentReturnContent;
   failed: PaymentReturnContent;
-  /** Checks the status again. Shows a button for it while pending. */
+  /** A function that checks the status again. While the state is pending, a button runs it. */
   onRefresh?: (() => void) | undefined;
   /** The refresh button's text. Defaults to `Check again`. */
   refreshLabel?: string | undefined;
-  /** Classes for placing it, on the outer element. */
+  /** The classes for placing the component, on its outer element. */
   className?: string | undefined;
 }
 
@@ -42,8 +44,8 @@ const refresh = "px-4 py-2.5 rounded-payment-button bg-button-primary-bg/80 text
 const secondary = "py-2.5 rounded-payment-button bg-payment-secondary-bg hover:bg-payment-secondary-hover-bg text-payment-secondary-text text-sm transition-colors";
 
 /**
- * What a user sees on coming back from a payment provider: confirmed, still pending, or failed.
- * The app decides the state, such as with `usePollUntilFinal`.
+ * Renders what a user sees on coming back from a payment provider: confirmed, still pending, or
+ * failed. The app decides the state, such as with `usePollUntilFinal`.
  */
 export function PaymentReturn({ state, success, pending, failed, onRefresh, refreshLabel = "Check again", className }: PaymentReturnProps) {
   const content = { success, pending, failed }[state];

package/src/payments/formatNok.ts

@@ -1,4 +1,4 @@
-/** An amount in øre as Norwegian kroner, such as `NOK 373,75`. */
+/** Formats an amount in øre as Norwegian kroner, such as `NOK 373,75`. */
 export function formatNok(ore: number): string {
   return `NOK ${(ore / 100).toFixed(2).replace(".", ",")}`;
 }

package/src/payments/usePollUntilFinal.ts

@@ -2,26 +2,28 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 
+/** What `usePollUntilFinal` returns. */
 export interface PollResult<T> {
   /** The latest value, or null before the first answer. */
   data: T | null;
-  /** True until a final value, the last retry or a failed fetch. */
+  /** True until a final value, the last retry, or a failed fetch. */
   loading: boolean;
   /** Polls again from the start, with the spinner showing. */
   refresh: () => void;
 }
 
+/** Options for `usePollUntilFinal`. */
 export interface PollOptions {
-  /** How many more times to fetch after the first. Defaults to 8. */
+  /** The number of fetches after the first. Defaults to `8`. */
   retries?: number | undefined;
-  /** Milliseconds between fetches. Defaults to 4000. */
+  /** The milliseconds between fetches. Defaults to `4000`. */
   delayMs?: number | undefined;
 }
 
 /**
  * Fetches until the value is final, such as an order a payment provider has not confirmed yet when
- * the user comes back from it. Stops after the retries, on a failed fetch and on unmount. Each fetch
- * uses the latest `fetcher` and `isFinal` given.
+ * the user comes back from it. Stops after the retries, on a failed fetch, and on unmount. Each
+ * fetch uses the latest `fetcher` and `isFinal` given.
  */
 export function usePollUntilFinal<T>(
   fetcher: () => Promise<T | null>,

package/src/sections/SectionRenderer.tsx

@@ -0,0 +1,275 @@
+// No "use client" and no hooks, so a server component can render the sections.
+
+import { CheckIcon } from "@heroicons/react/24/outline";
+import type { ComponentType, ReactNode } from "react";
+import { Markdown } from "../markdown/Markdown";
+import { ContentImage } from "../ui/ContentImage";
+import { SmartLink } from "./SmartLink";
+import type { BaseSection, ContactSection, CtaSection, FeatureSection, HeroSection, ImageSection, SectionOf, TextSection } from "./types";
+
+/** What a section renderer gets to draw an image. */
+export interface SectionImageProps {
+  imageId: string;
+  alt: string;
+  /** The widths the image is shown at, for a responsive image. A plain image may ignore it. */
+  sizes: string;
+  className: string;
+  /** The intrinsic size, only where the image keeps its own ratio. */
+  width?: number | undefined;
+  height?: number | undefined;
+}
+
+/** What a link in a section gets. */
+export interface SectionLinkProps {
+  href: string;
+  className?: string | undefined;
+  children: ReactNode;
+}
+
+/** Intrinsic image sizes by image id. */
+export type ImageDimensions = Record<string, { width: number; height: number }>;
+
+/** The app's pieces the renderers draw with. */
+export interface SectionRenderContext {
+  /** Turns a button's path into the link it points at, such as one with the locale in front. Defaults to the path as it is. */
+  href: (path: string) => string;
+  /** The link for buttons. Defaults to `SmartLink`. */
+  Link: ComponentType<SectionLinkProps>;
+  /** The image for image sections. Defaults to `ContentImage`. */
+  Image: ComponentType<SectionImageProps>;
+  /** Intrinsic sizes by image id, for the image layouts that keep the image's ratio. */
+  imageDimensions: ImageDimensions;
+}
+
+/** Draws one section type. */
+export type SectionRenderFn<S> = (section: S, context: SectionRenderContext) => ReactNode;
+
+/** A renderer per section type. An app's renderers replace the defaults for the same type. */
+export type SectionRenderers<S extends BaseSection> = {
+  [K in S["type"]]?: SectionRenderFn<SectionOf<S, K>>;
+};
+
+function ScrimText({ text, big }: { text: string; big?: boolean }) {
+  if (!text) return null;
+  return (
+    <div className="absolute inset-0 bg-black/40 flex items-center justify-center p-6">
+      <p className={`text-white font-black text-center whitespace-pre-line ${big ? "text-3xl sm:text-5xl max-w-3xl" : "text-2xl sm:text-4xl max-w-2xl"}`}>{text}</p>
+    </div>
+  );
+}
+
+/** The plain hero: the heading and the buttons on the primary color. */
+export const heroRenderer: SectionRenderFn<HeroSection> = (section, { href, Link }) => (
+  <section className="bg-primary">
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 py-20 sm:py-28">
+      <h1 className="text-4xl sm:text-6xl font-black tracking-tight text-primary-foreground max-w-3xl whitespace-pre-line">{section.heading}</h1>
+      {section.subheading && <p className="mt-5 text-lg text-primary-foreground/80 max-w-xl whitespace-pre-line">{section.subheading}</p>}
+      <div className="mt-8 flex flex-wrap gap-3">
+        {section.primaryLabel && (
+          <Link href={href(section.primaryHref || "#")} className="rounded-lg bg-gray-900 text-white font-semibold px-6 py-3 hover:bg-gray-800 transition">
+            {section.primaryLabel}
+          </Link>
+        )}
+        {section.secondaryLabel && (
+          <Link href={href(section.secondaryHref || "#")} className="rounded-lg bg-white text-gray-900 font-semibold px-6 py-3 hover:bg-gray-100 transition">
+            {section.secondaryLabel}
+          </Link>
+        )}
+      </div>
+    </div>
+  </section>
+);
+
+/** A card with the ticked bullets. Empty bullets are left out. */
+export const featureRenderer: SectionRenderFn<FeatureSection> = section => (
+  <section className="max-w-7xl mx-auto px-4 sm:px-6 py-16">
+    {section.heading && <h2 className="text-2xl font-bold text-gray-900 mb-6">{section.heading}</h2>}
+    <div className="w-full sm:max-w-md rounded-2xl border border-gray-200 p-6">
+      {section.text && <p className="text-sm text-gray-600">{section.text}</p>}
+      <ul className="mt-4 space-y-2">
+        {section.bullets.filter(Boolean).map((item, i) => (
+          <li key={i} className="flex items-center gap-2 text-sm text-gray-700">
+            <CheckIcon className="h-4 w-4 text-gray-900 shrink-0" />
+            {item}
+          </li>
+        ))}
+      </ul>
+    </div>
+  </section>
+);
+
+/** Options for `createTextRenderer`. */
+export interface TextRendererOptions {
+  /** The classes on the element around the Markdown body. Defaults to `space-y-4 text-gray-700`. */
+  bodyClassName?: string | undefined;
+}
+
+/** The heading and the Markdown body. */
+export function createTextRenderer({ bodyClassName = "space-y-4 text-gray-700" }: TextRendererOptions = {}): SectionRenderFn<TextSection> {
+  return section => (
+    <section className="max-w-3xl mx-auto px-4 sm:px-6 py-12">
+      {section.heading && <h2 className="text-2xl font-bold text-gray-900 mb-4">{section.heading}</h2>}
+      <div className={bodyClassName}>
+        <Markdown>{section.body}</Markdown>
+      </div>
+    </section>
+  );
+}
+
+/** Options for `createContactRenderer`. */
+export interface ContactRendererOptions {
+  /** The app's contact form, shown below the heading and the text. */
+  form?: ReactNode;
+  /** The classes on the section, which has the id `contact`. Defaults to `bg-gray-50 border-t border-gray-200`. */
+  className?: string | undefined;
+}
+
+/** The heading and the text above the app's contact form, as the `#contact` anchor. */
+export function createContactRenderer({ form = null, className = "bg-gray-50 border-t border-gray-200" }: ContactRendererOptions = {}): SectionRenderFn<ContactSection> {
+  return section => (
+    <section id="contact" className={className}>
+      <div className="max-w-3xl mx-auto px-4 sm:px-6 py-16">
+        {section.heading && <h2 className="text-2xl font-bold text-gray-900">{section.heading}</h2>}
+        {section.text && <p className="mt-1 text-sm text-gray-600 mb-6">{section.text}</p>}
+        {form}
+      </div>
+    </section>
+  );
+}
+
+/** The band with a heading and one button, on the primary color. */
+export const ctaRenderer: SectionRenderFn<CtaSection> = (section, { href, Link }) => (
+  <section className="bg-primary">
+    <div className="max-w-5xl mx-auto px-4 sm:px-6 py-14 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-6">
+      <div>
+        <h2 className="text-2xl sm:text-3xl font-black text-primary-foreground whitespace-pre-line">{section.heading}</h2>
+        {section.text && <p className="mt-2 text-primary-foreground/80 whitespace-pre-line">{section.text}</p>}
+      </div>
+      {section.primaryLabel && (
+        <Link href={href(section.primaryHref || "#")} className="shrink-0 rounded-lg bg-gray-900 text-white font-semibold px-6 py-3 hover:bg-gray-800 transition">
+          {section.primaryLabel}
+        </Link>
+      )}
+    </div>
+  </section>
+);
+
+/** Options for `createImageRenderer`. */
+export interface ImageRendererOptions {
+  /**
+   * Whether the layouts that keep the image's ratio (standard, left and right) pass the intrinsic
+   * size from `imageDimensions` and add `h-auto`, so the browser reserves the space. Defaults to true.
+   */
+  intrinsicSize?: boolean | undefined;
+}
+
+/** An uploaded image in its layout. Nothing renders without an image. */
+export function createImageRenderer({ intrinsicSize = true }: ImageRendererOptions = {}): SectionRenderFn<ImageSection> {
+  return (section, { Image, imageDimensions }) => {
+    if (section.imageId == null) return null;
+    const layout = section.layout ?? "standard";
+    const intrinsic = intrinsicSize ? imageDimensions[section.imageId] : undefined;
+    const size = intrinsicSize ? { width: intrinsic?.width, height: intrinsic?.height } : {};
+    const auto = intrinsicSize ? " h-auto" : "";
+
+    if (layout === "full") {
+      return (
+        <section className="py-8">
+          <Image imageId={section.imageId} alt={section.alt} sizes="100vw" className="w-full max-h-[70vh] object-cover" />
+        </section>
+      );
+    }
+
+    if (layout === "overlay") {
+      return (
+        <section className="max-w-7xl mx-auto px-4 sm:px-6 py-8">
+          <div className="relative rounded-2xl overflow-hidden">
+            <Image imageId={section.imageId} alt={section.alt} sizes="(max-width: 1280px) 100vw, 1280px" className="w-full h-[420px] object-cover" />
+            <ScrimText text={section.text} />
+          </div>
+        </section>
+      );
+    }
+
+    if (layout === "overlayFull") {
+      return (
+        <section className="relative">
+          <Image imageId={section.imageId} alt={section.alt} sizes="100vw" className="w-full h-[480px] object-cover" />
+          <ScrimText text={section.text} big />
+        </section>
+      );
+    }
+
+    if (layout === "left" || layout === "right") {
+      return (
+        <section className="max-w-7xl mx-auto px-4 sm:px-6 py-8">
+          <div className="grid sm:grid-cols-2 gap-8 items-center">
+            <Image
+              imageId={section.imageId}
+              alt={section.alt}
+              sizes="(max-width: 640px) 100vw, 640px"
+              {...size}
+              className={`w-full${auto} rounded-2xl ${layout === "right" ? "sm:order-2" : ""}`}
+            />
+            {section.text && <p className="text-gray-700 leading-relaxed whitespace-pre-line">{section.text}</p>}
+          </div>
+        </section>
+      );
+    }
+
+    return (
+      <section className="max-w-5xl mx-auto px-4 sm:px-6 py-8">
+        <figure>
+          <Image imageId={section.imageId} alt={section.alt} sizes="(max-width: 1024px) 100vw, 1024px" {...size} className={`w-full${auto} rounded-2xl`} />
+          {section.caption && <figcaption className="mt-2 text-center text-sm text-gray-500">{section.caption}</figcaption>}
+        </figure>
+      </section>
+    );
+  };
+}
+
+/**
+ * The renderers for the shared types. `feed` and `stats` have none, since only the app knows its
+ * items and its live numbers. `contact` renders no form until the app registers one through
+ * `createContactRenderer`.
+ */
+const defaultSectionRenderers = {
+  hero: heroRenderer,
+  feature: featureRenderer,
+  text: createTextRenderer(),
+  contact: createContactRenderer(),
+  cta: ctaRenderer,
+  image: createImageRenderer(),
+};
+
+const defaultContext: SectionRenderContext = {
+  href: path => path,
+  Link: SmartLink,
+  Image: ContentImage,
+  imageDimensions: {},
+};
+
+/** Props for `SectionRenderer`. */
+export interface SectionRendererProps<S extends BaseSection> {
+  section: S;
+  /** The app's renderers. They replace the defaults for the same type, and add the app's own types. */
+  renderers?: SectionRenderers<S> | undefined;
+  /** The app's link, image, path mapping and image sizes. Anything left out keeps its default. */
+  context?: Partial<SectionRenderContext> | undefined;
+}
+
+/**
+ * Renders one section through the renderer for its type. A hidden section, or one whose type has
+ * no renderer, renders nothing. It holds no state, so it works in a server component.
+ */
+export function SectionRenderer<S extends BaseSection>({ section, renderers, context }: SectionRendererProps<S>) {
+  if (!section.visible) return null;
+  const all = { ...defaultSectionRenderers, ...renderers } as unknown as Record<string, SectionRenderFn<S> | undefined>;
+  const render = all[section.type];
+  if (!render) return null;
+  return <>{render(section, { ...defaultContext, ...definedOnly(context) })}</>;
+}
+
+function definedOnly(context: Partial<SectionRenderContext> | undefined): Partial<SectionRenderContext> {
+  return Object.fromEntries(Object.entries(context ?? {}).filter(([, value]) => value !== undefined));
+}

package/src/sections/SectionsEditor.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import { ArrowDownIcon, ArrowUpIcon, DocumentDuplicateIcon, EyeIcon, EyeSlashIcon, PlusIcon, TrashIcon } from "@heroicons/react/24/outline";
+import { useState, type ComponentType } from "react";
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import {
+  ContactSectionEditor,
+  CtaSectionEditor,
+  FeatureSectionEditor,
+  FeedSectionEditor,
+  HeroSectionEditor,
+  ImageSectionEditor,
+  StatsSectionEditor,
+  TextSectionEditor,
+  type SectionEditorProps,
+  type SectionImages,
+} from "./editors";
+import { cloneSection as defaultClone } from "./factory";
+import { defaultSectionsEditorStrings, defaultSectionTypeLabels, type SectionsEditorStrings } from "./sectionsEditorStrings";
+import { SHARED_SECTION_TYPES, type BaseSection, type SectionOf } from "./types";
+
+/** An editor per section type. An app's editors replace the defaults for the same type. */
+export type SectionEditors<S extends BaseSection> = {
+  [K in S["type"]]?: ComponentType<SectionEditorProps<SectionOf<S, K>>>;
+};
+
+/** The editors for the shared types. The stats editor offers only the manual number until the app registers its sources. */
+const defaultSectionEditors = {
+  hero: HeroSectionEditor,
+  feature: FeatureSectionEditor,
+  text: TextSectionEditor,
+  feed: FeedSectionEditor,
+  contact: ContactSectionEditor,
+  cta: CtaSectionEditor,
+  stats: StatsSectionEditor,
+  image: ImageSectionEditor,
+};
+
+/** Props for `SectionsEditor`. */
+export interface SectionsEditorProps<S extends BaseSection> {
+  sections: S[];
+  onChange: (sections: S[]) => void;
+  /** Makes a new section of the type, such as one from `createSectionFactory`. */
+  createSection: (type: S["type"]) => S;
+  /** Copies a section with a new id. Defaults to `cloneSection`. */
+  cloneSection?: ((section: S) => S) | undefined;
+  /** The types the add list offers, in order. Defaults to `SHARED_SECTION_TYPES`. */
+  types?: readonly S["type"][] | undefined;
+  /** The type the add list starts on. Defaults to the first of `types`. */
+  initialAddType?: S["type"] | undefined;
+  /** The app's editors. They replace the defaults for the same type, and add the app's own types. */
+  editors?: SectionEditors<S> | undefined;
+  images: SectionImages;
+  strings?: TextOverrides<SectionsEditorStrings> | undefined;
+  /** The name of each type, on its badge and in the add list. Missing types keep the default, or show the type itself. */
+  typeLabels?: Partial<Record<S["type"], string>> | undefined;
+  /** Renders the cards and the add row without the wrapping element, for a page that already spaces its children. */
+  unwrapped?: boolean | undefined;
+}
+
+/**
+ * The admin editor for a page of sections. It is controlled: every change, whether an edit, a
+ * move, a copy, a removal or a new section, goes out through `onChange`.
+ */
+export function SectionsEditor<S extends BaseSection>({
+  sections,
+  onChange,
+  createSection,
+  cloneSection = defaultClone,
+  types = SHARED_SECTION_TYPES as readonly string[] as readonly S["type"][],
+  initialAddType,
+  editors,
+  images,
+  strings,
+  typeLabels,
+  unwrapped = false,
+}: SectionsEditorProps<S>) {
+  const text = withDefaults(defaultSectionsEditorStrings, strings);
+  const [addType, setAddType] = useState<S["type"] | undefined>(initialAddType ?? types[0]);
+  const labels: Record<string, string | undefined> = { ...defaultSectionTypeLabels, ...typeLabels };
+  const label = (type: string) => labels[type] ?? type;
+  const allEditors = { ...defaultSectionEditors, ...editors } as unknown as Record<string, ComponentType<SectionEditorProps<S>> | undefined>;
+
+  const patch = (id: string, changes: Partial<S>) => onChange(sections.map(s => (s.id === id ? ({ ...s, ...changes } as S) : s)));
+
+  const move = (index: number, dir: -1 | 1) => {
+    const target = index + dir;
+    if (target < 0 || target >= sections.length) return;
+    const next = [...sections];
+    [next[index], next[target]] = [next[target], next[index]];
+    onChange(next);
+  };
+
+  const duplicate = (index: number) => {
+    const next = [...sections];
+    next.splice(index + 1, 0, cloneSection(sections[index]));
+    onChange(next);
+  };
+
+  const content = (
+    <>
+      {sections.map((section, index) => {
+        const Editor = allEditors[section.type];
+        return (
+          <div key={section.id} className="rounded-2xl border border-gray-200 p-5">
+            <div className="flex items-center justify-between mb-4">
+              <span className="inline-flex items-center rounded-full bg-gray-100 px-3 py-1 text-xs font-semibold text-gray-700">{label(section.type)}</span>
+              <div className="flex items-center gap-1">
+                <button type="button" onClick={() => patch(section.id, { visible: !section.visible } as Partial<S>)} title={section.visible ? text.hide : text.show} className="p-2 rounded-lg text-gray-500 hover:text-gray-900 hover:bg-gray-100">
+                  {section.visible ? <EyeIcon className="h-4 w-4" /> : <EyeSlashIcon className="h-4 w-4" />}
+                </button>
+                <button type="button" onClick={() => move(index, -1)} disabled={index === 0} title={text.moveUp} className="p-2 rounded-lg text-gray-500 hover:text-gray-900 hover:bg-gray-100 disabled:opacity-30">
+                  <ArrowUpIcon className="h-4 w-4" />
+                </button>
+                <button type="button" onClick={() => move(index, 1)} disabled={index === sections.length - 1} title={text.moveDown} className="p-2 rounded-lg text-gray-500 hover:text-gray-900 hover:bg-gray-100 disabled:opacity-30">
+                  <ArrowDownIcon className="h-4 w-4" />
+                </button>
+                <button type="button" onClick={() => duplicate(index)} title={text.duplicate} className="p-2 rounded-lg text-gray-500 hover:text-gray-900 hover:bg-gray-100">
+                  <DocumentDuplicateIcon className="h-4 w-4" />
+                </button>
+                <button type="button" onClick={() => onChange(sections.filter(s => s.id !== section.id))} title={text.remove} className="p-2 rounded-lg text-red-500 hover:text-red-700 hover:bg-red-50">
+                  <TrashIcon className="h-4 w-4" />
+                </button>
+              </div>
+            </div>
+            {Editor && <Editor section={section} patch={changes => patch(section.id, changes)} strings={text} images={images} />}
+          </div>
+        );
+      })}
+
+      <div className="flex items-center gap-2 pt-2">
+        <select value={addType} onChange={e => setAddType(e.target.value as S["type"])} className="rounded-lg border border-gray-300 px-3 py-2 text-sm">
+          {types.map(t => (
+            <option key={t} value={t}>
+              {label(t)}
+            </option>
+          ))}
+        </select>
+        <button
+          type="button"
+          onClick={() => addType !== undefined && onChange([...sections, createSection(addType)])}
+          className="inline-flex items-center gap-1.5 rounded-lg bg-gray-100 text-gray-700 font-medium px-4 py-2 text-sm hover:bg-gray-200 transition"
+        >
+          <PlusIcon className="h-4 w-4" /> {text.addSection}
+        </button>
+      </div>
+    </>
+  );
+
+  return unwrapped ? content : <div className="space-y-4">{content}</div>;
+}