@sandboxsonny/ace-kit 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+type AceClientOptions = {
+  /** Where the CMS Ace API lives, e.g. `https://api.example.com`. */
+  apiUrl: string;
+  /** The domain this site has in the CMS. */
+  siteDomain: string;
+  /** How long an answer is reused, in seconds, so busy pages don't hit the API's per-IP rate limit. 0 turns caching off. */
+  cacheSeconds?: number;
+  fetchImplementation?: typeof fetch;
+  now?: () => number;
+};
+
+/** A field of a content type as `GET /public/content-types` describes it. */
+type AceFieldSchema = {
+  handle: string;
+  label: string;
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  component_key: string;
+  config: { required?: boolean; options?: string[] } | null;
+};
+
+/** A content type as `GET /public/content-types` describes it. */
+type AceContentTypeSchema = {
+  handle: string;
+  name: string;
+  fields: AceFieldSchema[];
+};
+
+/** A live entry from the public API. `Values` is the shape of its content type's fields. */
+type AceEntry<Values = Record<string, unknown>> = {
+  id: number;
+  content_type_id: number;
+  /** The content type's handle, which is the first part of the entry's address. */
+  content_type_handle: string;
+  title: string;
+  handle: string;
+  description: string;
+  values: Values;
+  created_at: string;
+  updated_at: string;
+  /** Only on a preview: true when the entry has a draft and this is it. */
+  is_draft?: boolean;
+};
+
+/**
+ * The shape of each content type's values, keyed by the content type's handle. It starts empty; running
+ * `ace-kit generate` fills it in for your site (by declaration merging), and the client then returns the right
+ * type for each content type.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface AceContentTypes {}
+
+/** The handles of your content types once types are generated; any text before that. */
+type AceContentTypeHandle = keyof AceContentTypes extends never
+  ? string
+  : Extract<keyof AceContentTypes, string>;
+
+/** The values of a content type's entries: what was generated for it, or loose before that. */
+type AceValuesOf<Handle extends string> = Handle extends keyof AceContentTypes
+  ? AceContentTypes[Handle]
+  : Record<string, unknown>;
+
+/** One link of a menu as the public API returns it, with its address already worked out. */
+type AceMenuItem = {
+  label: string;
+  /** A path on this site for a link to an entry, or the address as typed. */
+  url: string;
+  kind: "entry" | "url";
+  /** The entry an entry link goes to; null for a typed address. */
+  entry: { id: number; title: string; handle: string; content_type_handle: string } | null;
+  children: AceMenuItem[];
+};
+
+type AceMenu = {
+  name: string;
+  handle: string;
+  items: AceMenuItem[];
+};
+
+/** One link in a navigation bar, ready to draw. */
+type AceNavigationLink = {
+  label: string;
+  to: string;
+  /** Links shown under this one. */
+  children?: AceNavigationLink[];
+};
+
+/**
+ * A client for the CMS Ace public API. It runs on the server only, so the visitor's browser never talks to the
+ * API. The API finds the site from X-Forwarded-Host, which this client sets to the site's domain.
+ */
+declare function createAceClient({ apiUrl, siteDomain, cacheSeconds, fetchImplementation, now, }: AceClientOptions): {
+    /**
+     * One live entry of a content type, by its handle; null if the site has no such entry. With a preview token the
+     * entry the token was made for comes back with its draft applied (never cached); a token that has run out throws
+     * AcePreviewExpiredError.
+     */
+    getEntry<Handle extends AceContentTypeHandle>(contentTypeHandle: Handle, handle: string, options?: {
+        previewToken?: string | null;
+    }): Promise<AceEntry<AceValuesOf<Handle>> | null>;
+    /** The live entries of a content type, newest first. */
+    getEntries<Handle extends AceContentTypeHandle>(contentTypeHandle: Handle, options?: {
+        limit?: number;
+    }): Promise<AceEntry<AceValuesOf<Handle>>[]>;
+    /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
+    getMenu(handle: string): Promise<AceMenu | null>;
+    /** What the site's content types and fields are, which is what type generation reads. */
+    getContentTypes(): Promise<AceContentTypeSchema[]>;
+};
+/** The client `createAceClient` returns. */
+type AceClient = ReturnType<typeof createAceClient>;
+
+/** The preview link the editor opened has run out. Reload the editor for a new one. */
+declare class AcePreviewExpiredError extends Error {
+    constructor();
+}
+/** The CMS could not be reached, or answered with something unexpected. */
+declare class AceUnavailableError extends Error {
+    constructor(message: string);
+}
+
+/** Which entry an address is for: the content type's handle, then the entry's. */
+type AceAddress = {
+  contentTypeHandle: string;
+  entryHandle: string;
+};
+
+/** The content type and entry shown at "/". */
+declare const homeAddress: AceAddress;
+/** The path of an entry: `/{content type}/{entry}`. */
+declare const pathOfAddress: (address: AceAddress) => string;
+/**
+ * Reads an address the way Shopify does: "/{content type}/{entry}", so "/pages/about" is the entry "about" of the
+ * content type "pages". "/" is the home entry. Anything else is not a page.
+ */
+declare function addressFromPath(slug: string | undefined): AceAddress | null;
+/** Whether an address is the home entry's own address, which redirects to "/". */
+declare const isHomeAddress: (address: AceAddress) => boolean;
+/**
+ * Where a path from the CMS should really go: the home entry's own address, which redirects, is replaced by
+ * the "/" it redirects to.
+ */
+declare function visitablePath(path: string): string;
+
+/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
+type AceImageData = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A web-sized copy, for browsers that ignore `srcset`. */
+  src: string;
+  /** Copies at several widths; empty when the image is too small to need them. */
+  srcset: string;
+  width: number | null;
+  height: number | null;
+  alt_text: string;
+  content_type: string;
+};
+
+type AceImageOptions = {
+    /** How wide the image is shown, e.g. "(min-width: 64rem) 64rem, 100vw". The browser uses it to pick a copy from srcset. */
+    sizes: string;
+    /** Leave on for images below the first screen; turn off for the one at the top of the page. */
+    lazy?: boolean;
+};
+/** The attributes of an `<img>` for an image: the same for every framework. */
+type AceImageAttributes = {
+    src: string;
+    srcSet: string | undefined;
+    sizes: string | undefined;
+    width: number | undefined;
+    height: number | undefined;
+    alt: string;
+    loading: "lazy" | "eager";
+    decoding: "async";
+    fetchPriority: "high" | undefined;
+};
+/** What to put on an `<img>`: a web-sized `src`, `srcset` when there are copies, and the size so the page doesn't jump. */
+declare function imageAttributes(image: AceImageData, { sizes, lazy }: AceImageOptions): AceImageAttributes;
+
+/**
+ * Where a link in rich text goes, or null if it can't be trusted. The CMS only allows paths, web addresses,
+ * mailto: and tel:; this checks again so the page stays safe even if something else ever gets into the text.
+ */
+declare function linkAddress(address: string): string | null;
+/** Whether a link stays on this site: a path such as "/pages/about", not "//elsewhere", "https://..." or "mailto:...". */
+declare function isInternalPath(address: string): boolean;
+
+/** A CMS menu as links ready to draw. An entry link to the home entry goes to "/" so it isn't a redirect. */
+declare function linksFromMenu(menu: AceMenu): AceNavigationLink[];
+/** Whether a link is for the page being shown. "/" matches only the home page; a trailing slash is ignored. */
+declare function isCurrentPage(link: AceNavigationLink, pathname: string): boolean;
+/**
+ * A menu's links, ready to draw. If the site has no such menu, or the CMS can't be reached, `fallback` is returned
+ * instead (a missing menu must never take a whole page down); anything else that goes wrong is a bug and is thrown.
+ */
+declare function loadMenuLinks(client: AceClient, handle: string, fallback?: AceNavigationLink[]): Promise<AceNavigationLink[]>;
+
+/** What to do with a request for a page: show an entry, redirect, or explain. */
+type AcePage<Values = Record<string, unknown>> =
+  | { kind: "entry"; status: 200; entry: AceEntry<Values>; headers: Record<string, string> }
+  | { kind: "redirect"; status: 301 | 302; location: string; headers: Record<string, string> }
+  | { kind: "not-found"; status: 404; headers: Record<string, string> }
+  | { kind: "unavailable"; status: 503; headers: Record<string, string> }
+  | { kind: "preview-expired"; status: 403; headers: Record<string, string> };
+
+/**
+ * Works out what to do for a request: which entry to show, where to redirect, or which message to give. It does
+ * the same for every framework, so a route only has to act on the answer.
+ *
+ * - `slug` is the part of the path after the site's root, e.g. "pages/about" ("" or undefined for the home page).
+ * - `url` is the full request address; it carries the preview token the CMS puts in its preview frame.
+ *
+ * Addresses are `/{content type}/{entry}` as on Shopify, and `/` is the home entry. A page shown with a preview
+ * token is never cached or indexed (the answer's `headers` say so).
+ */
+declare function loadPage<Values = Record<string, unknown>>(client: AceClient, { slug, url }: {
+    slug: string | undefined;
+    url: URL;
+}): Promise<AcePage<Values>>;
+
+/** What a page that isn't an entry says: a heading and a message. Shared by every framework's notice component. */
+declare const pageNotices: Record<AcePage["kind"], {
+    heading: string;
+    message: string;
+}>;
+
+/** The address parameter the CMS puts in the preview frame's address. */
+declare const previewParameter = "cms_preview";
+/** What the CMS sends the page when the draft has changed. */
+declare const refreshMessageType = "cms-ace:refresh";
+/**
+ * The origin (`https://admin.example.com`, with no path or trailing slash) of a web address, or null if it isn't a
+ * web address. Browsers report a message's origin in exactly this form, so origins are compared in it.
+ */
+declare function originOf(address: string): string | null;
+/** Whether a message is the CMS asking the page to refresh, from the admin origin we expect and no one else. */
+declare function isRefreshRequest(event: {
+    origin: string;
+    data: unknown;
+}, adminOrigin: string): boolean;
+/** The preview token in an address, if any. */
+declare function previewTokenFrom(address: URL): string | null;
+/**
+ * Who may show this site inside a frame: itself and the CMS admin app, so the editor can preview
+ * it and nobody else can frame it (clickjacking).
+ */
+declare function framingPolicy(adminOrigin: string): string;
+/**
+ * Adds the framing policy to a response's headers without losing a Content-Security-Policy the site already sends:
+ * the policy is added to it, replacing only a `frame-ancestors` directive it already has (which would otherwise
+ * stop the CMS's editor showing the site).
+ */
+declare function addFramingPolicy(headers: Headers, adminOrigin: string): void;
+/** The headers for a page shown with a preview token: never cached, never indexed. */
+declare const previewHeaders: Record<string, string>;
+/**
+ * Swaps the page's content for the same page fetched again. Only the body's children and the title change, so
+ * the scroll position, the scripts and the styles stay as they are and nothing flashes.
+ */
+declare function swapPageContent(current: Document, fresh: Document): void;
+
+/** Fetches this page again and swaps its content in; the preview token is still in the address. */
+declare function refreshPageContent(): Promise<void>;
+/**
+ * Listens, in the browser, for the CMS asking the page to refresh (it does when the editor saves a draft) and calls
+ * `refresh`. Only messages from the admin origin count. Messages that arrive while a refresh is under way are folded
+ * into one more refresh afterwards. Returns a function that stops listening.
+ */
+declare function listenForPreviewRefresh(adminOrigin: string, refresh?: () => Promise<void>): () => void;
+
+/**
+ * A text area field's text as HTML. With `multiline` (the default) blank lines start new paragraphs (`<p>`) and a
+ * single new line is a line break; without it the text is one line, with no element around it. Every piece of text
+ * is escaped, so the result is safe to put on a page as it is.
+ */
+declare function renderTextArea(text: string | undefined, { multiline }?: {
+    multiline?: boolean;
+}): string;
+
+/** A mark on a piece of text. A link's address is already worked out: an entry link comes as its path. */
+type AceRichTextMark = { type: "bold" } | { type: "italic" } | { type: "link"; attrs: { href: string } };
+
+/**
+ * One node of a rich text document: `paragraph`, `heading` (`attrs.level` 2 to 4), `bulletList`, `orderedList`
+ * (`attrs.start`), `listItem`, `blockquote`, `hardBreak`, `text`, or `image` (`attrs.image` is the picture).
+ */
+type AceRichTextNode = {
+  type: string;
+  attrs?: { level?: number; start?: number; assetId?: number; image?: AceImageData };
+  content?: AceRichTextNode[];
+  text?: string;
+  marks?: AceRichTextMark[];
+};
+
+/** The value of a rich text field. */
+type AceRichTextDocument = { type: "doc"; content?: AceRichTextNode[] };
+
+/** How wide an image in the text is shown, so the browser picks a suitable copy from srcset. */
+declare const richTextImageSizes = "(min-width: 42rem) 42rem, 100vw";
+/** The heading level to draw: 2 to 4, whatever the document says. */
+declare const headingLevel: (node: AceRichTextNode) => 2 | 3 | 4;
+/** The number an ordered list starts at, when it isn't 1. */
+declare const listStart: (node: AceRichTextNode) => number | undefined;
+/**
+ * A rich text document as HTML. Every piece of text and every attribute is escaped, and only the kinds of
+ * content the CMS allows are drawn, so the result is safe to put on a page as it is.
+ */
+declare function renderRichText(document: AceRichTextDocument): string;
+
+export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, AceUnavailableError, type AceValuesOf, addFramingPolicy, addressFromPath, createAceClient, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, swapPageContent, visitablePath };

package/dist/index.js

@@ -0,0 +1,6 @@
+export { pageNotices } from './chunk-XPZY5R5A.js';
+export { headingLevel, imageAttributes, isInternalPath, linkAddress, listStart, renderRichText, renderTextArea, richTextImageSizes } from './chunk-URLKW2YS.js';
+export { listenForPreviewRefresh, refreshPageContent } from './chunk-YN7LJWGI.js';
+export { AcePreviewExpiredError, AceUnavailableError, createAceClient, isCurrentPage, linksFromMenu, loadMenuLinks, loadPage } from './chunk-KLRCWAE4.js';
+export { addressFromPath, homeAddress, isHomeAddress, pathOfAddress, visitablePath } from './chunk-M5WR5TCR.js';
+export { addFramingPolicy, framingPolicy, isRefreshRequest, originOf, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, swapPageContent } from './chunk-YLO6IAXF.js';

package/dist/preview-script.js

@@ -0,0 +1,6 @@
+import { listenForPreviewRefresh } from './chunk-YN7LJWGI.js';
+import './chunk-YLO6IAXF.js';
+
+// src/preview/refresh-script.ts
+var adminOrigin = document.querySelector("[data-ace-preview-origin]")?.dataset.acePreviewOrigin;
+if (adminOrigin) listenForPreviewRefresh(adminOrigin);

package/dist/react-router-server.d.ts

@@ -0,0 +1,225 @@
+import * as react_router from 'react-router';
+import { EntryContext, AppLoadContext } from 'react-router';
+
+/** A live entry from the public API. `Values` is the shape of its content type's fields. */
+type AceEntry<Values = Record<string, unknown>> = {
+  id: number;
+  content_type_id: number;
+  /** The content type's handle, which is the first part of the entry's address. */
+  content_type_handle: string;
+  title: string;
+  handle: string;
+  description: string;
+  values: Values;
+  created_at: string;
+  updated_at: string;
+  /** Only on a preview: true when the entry has a draft and this is it. */
+  is_draft?: boolean;
+};
+
+/**
+ * The shape of each content type's values, keyed by the content type's handle. It starts empty; running
+ * `ace-kit generate` fills it in for your site (by declaration merging), and the client then returns the right
+ * type for each content type.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface AceContentTypes {}
+
+/** The handles of your content types once types are generated; any text before that. */
+type AceContentTypeHandle = keyof AceContentTypes extends never
+  ? string
+  : Extract<keyof AceContentTypes, string>;
+
+/** The values of a content type's entries: what was generated for it, or loose before that. */
+type AceValuesOf<Handle extends string> = Handle extends keyof AceContentTypes
+  ? AceContentTypes[Handle]
+  : Record<string, unknown>;
+
+/** One link of a menu as the public API returns it, with its address already worked out. */
+type AceMenuItem = {
+  label: string;
+  /** A path on this site for a link to an entry, or the address as typed. */
+  url: string;
+  kind: "entry" | "url";
+  /** The entry an entry link goes to; null for a typed address. */
+  entry: { id: number; title: string; handle: string; content_type_handle: string } | null;
+  children: AceMenuItem[];
+};
+
+type AceMenu = {
+  name: string;
+  handle: string;
+  items: AceMenuItem[];
+};
+
+/** One link in a navigation bar, ready to draw. */
+type AceNavigationLink = {
+  label: string;
+  to: string;
+  /** Links shown under this one. */
+  children?: AceNavigationLink[];
+};
+
+type AceClientOptions = {
+  /** Where the CMS Ace API lives, e.g. `https://api.example.com`. */
+  apiUrl: string;
+  /** The domain this site has in the CMS. */
+  siteDomain: string;
+  /** How long an answer is reused, in seconds, so busy pages don't hit the API's per-IP rate limit. 0 turns caching off. */
+  cacheSeconds?: number;
+  fetchImplementation?: typeof fetch;
+  now?: () => number;
+};
+
+/** A field of a content type as `GET /public/content-types` describes it. */
+type AceFieldSchema = {
+  handle: string;
+  label: string;
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  component_key: string;
+  config: { required?: boolean; options?: string[] } | null;
+};
+
+/** A content type as `GET /public/content-types` describes it. */
+type AceContentTypeSchema = {
+  handle: string;
+  name: string;
+  fields: AceFieldSchema[];
+};
+
+/**
+ * A client for the CMS Ace public API. It runs on the server only, so the visitor's browser never talks to the
+ * API. The API finds the site from X-Forwarded-Host, which this client sets to the site's domain.
+ */
+declare function createAceClient({ apiUrl, siteDomain, cacheSeconds, fetchImplementation, now, }: AceClientOptions): {
+    /**
+     * One live entry of a content type, by its handle; null if the site has no such entry. With a preview token the
+     * entry the token was made for comes back with its draft applied (never cached); a token that has run out throws
+     * AcePreviewExpiredError.
+     */
+    getEntry<Handle extends AceContentTypeHandle>(contentTypeHandle: Handle, handle: string, options?: {
+        previewToken?: string | null;
+    }): Promise<AceEntry<AceValuesOf<Handle>> | null>;
+    /** The live entries of a content type, newest first. */
+    getEntries<Handle extends AceContentTypeHandle>(contentTypeHandle: Handle, options?: {
+        limit?: number;
+    }): Promise<AceEntry<AceValuesOf<Handle>>[]>;
+    /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
+    getMenu(handle: string): Promise<AceMenu | null>;
+    /** What the site's content types and fields are, which is what type generation reads. */
+    getContentTypes(): Promise<AceContentTypeSchema[]>;
+};
+/** The client `createAceClient` returns. */
+type AceClient = ReturnType<typeof createAceClient>;
+
+/** What the root loader (`createRootLoader`) puts in the root route's data, for `useAceMenu` and `useAcePreview`. */
+type AceRootData = {
+  ace: {
+    /** The header menu's links, or the fallback. */
+    menuLinks: AceNavigationLink[];
+    /** Where the CMS admin app runs, when this page is a preview shown inside its editor; otherwise null. */
+    previewAdminOrigin: string | null;
+  };
+};
+
+/**
+ * The client for this site, made from the settings the first time it is needed. Most code only needs the functions
+ * below (`getEntry` and friends); this is for the rest of the client (`getContentTypes`).
+ */
+declare function getAceClient(): AceClient;
+/** One live entry of a content type by its handle, or `null`. See `createAceClient`. */
+declare const getEntry: AceClient["getEntry"];
+/** A content type's live entries, newest first. */
+declare const getEntries: AceClient["getEntries"];
+/** A navigation menu with every link worked out, or `null`. */
+declare const getMenu: (handle: string) => Promise<AceMenu | null>;
+/**
+ * A menu's links, ready to draw. If the site has no such menu, or the CMS can't be reached, you get `fallback`
+ * instead, so a missing menu never takes a page down.
+ */
+declare const getMenuLinks: (handle: string, options?: {
+    fallback?: AceNavigationLink[];
+}) => Promise<AceNavigationLink[]>;
+/**
+ * The loader for the route that draws every page. The route is a catch-all (`route("*", "routes/page.tsx")`):
+ *
+ *     export const loader = createPageLoader<PageValues>();
+ *     export { headers } from "@sandboxsonny/ace-kit/react-router/server";
+ *
+ * It reads the address (`/{content type}/{entry}`, with `/` the home entry), loads the entry and answers with the
+ * right status and headers: a missing page is a real 404, an unreachable CMS a 503, an expired preview a 403, and
+ * `/pages/home` redirects to `/`. Previews are never cached or indexed. Draw `loaderData` yourself.
+ */
+declare function createPageLoader<Values = Record<string, unknown>>(): ({ request }: {
+    request: Request;
+}) => Promise<Response | react_router.UNSAFE_DataWithResponseInit<{
+    kind: "not-found";
+    status: 404;
+    headers: Record<string, string>;
+} | {
+    kind: "unavailable";
+    status: 503;
+    headers: Record<string, string>;
+} | {
+    kind: "preview-expired";
+    status: 403;
+    headers: Record<string, string>;
+} | {
+    kind: "entry";
+    status: 200;
+    entry: AceEntry<Values>;
+    headers: Record<string, string>;
+}>>;
+/** `createPageLoader()` for a site that has not generated types for its content. */
+declare const loader: ({ request }: {
+    request: Request;
+}) => Promise<Response | react_router.UNSAFE_DataWithResponseInit<{
+    kind: "not-found";
+    status: 404;
+    headers: Record<string, string>;
+} | {
+    kind: "unavailable";
+    status: 503;
+    headers: Record<string, string>;
+} | {
+    kind: "preview-expired";
+    status: 403;
+    headers: Record<string, string>;
+} | {
+    kind: "entry";
+    status: 200;
+    entry: AceEntry<Record<string, unknown>>;
+    headers: Record<string, string>;
+}>>;
+/** The route's `headers`: send the ones the loader chose (a preview must never be cached or indexed). */
+declare const headers: ({ loaderHeaders }: {
+    loaderHeaders: Headers;
+}) => Headers;
+/**
+ * The root route's loader: the header menu's links, and whether this page is a preview shown inside the CMS's
+ * editor. Read them in components with `useAceMenu()`, and call `useAcePreview()` once to keep a preview fresh.
+ *
+ *     export const loader = createRootLoader({ menu: "main-menu", fallback: [{ label: "Home", to: "/" }] });
+ *
+ * The menu is the CMS menu with that handle; `fallback` is used if the site has none yet or the CMS is down.
+ */
+declare function createRootLoader({ menu, fallback }: {
+    menu: string;
+    fallback?: AceNavigationLink[];
+}): ({ request }: {
+    request: Request;
+}) => Promise<AceRootData>;
+/** How long React Router waits for deferred data before giving up, as in its default server entry. */
+declare const streamTimeout = 5000;
+/**
+ * A server entry. `app/entry.server.tsx` is one line:
+ *
+ *     export { handleRequest as default, streamTimeout } from "@sandboxsonny/ace-kit/react-router/server";
+ *
+ * It renders the page like React Router's default entry, except that it waits until the whole page is ready before
+ * answering (every page here is fully loaded by its loader, and crawlers get complete HTML), and it lets the CMS's
+ * admin app, and only it, frame the site for live preview (`Content-Security-Policy: frame-ancestors`).
+ */
+declare function handleRequest(request: Request, responseStatusCode: number, responseHeaders: Headers, routerContext: EntryContext, _loadContext: AppLoadContext): Promise<Response>;
+
+export { createPageLoader, createRootLoader, getAceClient, getEntries, getEntry, getMenu, getMenuLinks, handleRequest, headers, loader, streamTimeout };

package/dist/react-router-server.js

@@ -0,0 +1,89 @@
+import { createAceClient, loadMenuLinks, loadPage } from './chunk-KLRCWAE4.js';
+import './chunk-M5WR5TCR.js';
+import { previewTokenFrom, addFramingPolicy } from './chunk-YLO6IAXF.js';
+import { createReadableStreamFromReadable } from '@react-router/node';
+import { PassThrough } from 'stream';
+import { renderToPipeableStream } from 'react-dom/server';
+import { redirect, data, ServerRouter } from 'react-router';
+import { jsx } from 'react/jsx-runtime';
+
+// src/react-router/settings.ts
+function getAceSettings() {
+  return {
+    apiUrl: process.env.ACE_API_URL ?? "http://localhost:8080",
+    siteDomain: process.env.ACE_SITE_DOMAIN ?? "localhost",
+    previewAdminOrigin: process.env.ACE_PREVIEW_ADMIN_ORIGIN ?? "http://localhost:5173"
+  };
+}
+if (typeof window !== "undefined" && typeof process === "undefined") {
+  throw new Error(
+    "@sandboxsonny/ace-kit/react-router/server is server-only, but it was loaded in the browser. Use it only in a route's loader, headers or entry.server.tsx, not in a component. Components and hooks are in @sandboxsonny/ace-kit/react-router."
+  );
+}
+var client;
+function getAceClient() {
+  if (!client) {
+    const { apiUrl, siteDomain } = getAceSettings();
+    client = createAceClient({ apiUrl, siteDomain });
+  }
+  return client;
+}
+var getEntry = ((...parameters) => getAceClient().getEntry(...parameters));
+var getEntries = ((...parameters) => getAceClient().getEntries(...parameters));
+var getMenu = (handle) => getAceClient().getMenu(handle);
+var getMenuLinks = (handle, options = {}) => loadMenuLinks(getAceClient(), handle, options.fallback ?? []);
+function createPageLoader() {
+  return async function loader2({ request }) {
+    const url = new URL(request.url);
+    const slug = url.pathname.replace(/^\/+|\/+$/g, "");
+    const page = await loadPage(getAceClient(), { slug, url });
+    if (page.kind === "redirect") return redirect(page.location, { status: page.status, headers: page.headers });
+    return data(page, { status: page.status, headers: page.headers });
+  };
+}
+var loader = createPageLoader();
+var headers = ({ loaderHeaders }) => loaderHeaders;
+function createRootLoader({ menu, fallback = [] }) {
+  return async function loader2({ request }) {
+    const menuLinks = await loadMenuLinks(getAceClient(), menu, fallback);
+    const previewAdminOrigin = previewTokenFrom(new URL(request.url)) ? getAceSettings().previewAdminOrigin : null;
+    return { ace: { menuLinks, previewAdminOrigin } };
+  };
+}
+var streamTimeout = 5e3;
+function handleRequest(request, responseStatusCode, responseHeaders, routerContext, _loadContext) {
+  addFramingPolicy(responseHeaders, getAceSettings().previewAdminOrigin);
+  if (request.method.toUpperCase() === "HEAD") {
+    return Promise.resolve(new Response(null, { status: responseStatusCode, headers: responseHeaders }));
+  }
+  return new Promise((resolve, reject) => {
+    let statusCode = responseStatusCode;
+    let shellRendered = false;
+    let timeoutId = setTimeout(() => abort(), streamTimeout + 1e3);
+    const { pipe, abort } = renderToPipeableStream(/* @__PURE__ */ jsx(ServerRouter, { context: routerContext, url: request.url }), {
+      onAllReady() {
+        shellRendered = true;
+        const body = new PassThrough({
+          final(callback) {
+            clearTimeout(timeoutId);
+            timeoutId = void 0;
+            callback();
+          }
+        });
+        responseHeaders.set("Content-Type", "text/html");
+        pipe(body);
+        resolve(new Response(createReadableStreamFromReadable(body), { headers: responseHeaders, status: statusCode }));
+      },
+      onShellError(error) {
+        clearTimeout(timeoutId);
+        reject(error);
+      },
+      onError(error) {
+        statusCode = 500;
+        if (shellRendered) console.error(error);
+      }
+    });
+  });
+}
+
+export { createPageLoader, createRootLoader, getAceClient, getEntries, getEntry, getMenu, getMenuLinks, handleRequest, headers, loader, streamTimeout };