@capacms/sdk 1.0.0-next.1 → 1.0.0-next.10

package/dist/esm/overlay/protocol.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The live preview protocol, site side. Pure: no DOM, no globals, so it can be
+ * tested under plain `node --test`.
+ *
+ * The Capa admin frames the site and the two talk over `postMessage`. Every
+ * message is a plain object `{ source, v: 1, type, ...fields }`:
+ *
+ *   admin -> site  (source "capa-admin")
+ *     hello     {}                                   sent on the frame's load
+ *     highlight { entryId, field: string | null }    entryId "" clears
+ *     outline   { on: boolean }                      outline every tagged element
+ *     refresh   {}                                   re-render the draft
+ *     patch     { entryId, fields: [{ field, value, saved }] }
+ *                                                    unsaved text, as the editor types it
+ *
+ *   site -> admin  (source "capa")
+ *     ready     { path, entries, features }          after hello, and after every navigation.
+ *                                                    `features`: what this overlay can do
+ *                                                    beyond v1 (`SITE_FEATURES`)
+ *     select    { entryId, field }                   a tagged element was clicked
+ *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it. `patch` and `features` are the
+ * same kind of addition: an admin sends `patch` only to an overlay whose
+ * `ready` lists "patch", and an older admin never reads `features`.
+ *
+ * A PATCH IS TEXT ONLY, and only where the page shows the field verbatim. The
+ * overlay changes a tagged element's text while it reads exactly `saved` (the
+ * value the page was rendered from) or what this page last patched it to, so
+ * a field the site formats (a price, a date, Markdown) is left alone until the
+ * save re-renders it (`patchedText`).
+ *
+ * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
+ * this package). If you change one side, change the other.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export declare const ADMIN_SOURCE = "capa-admin";
+export declare const SITE_SOURCE = "capa";
+/** What this overlay can do beyond v1, listed in its `ready`. */
+export declare const SITE_FEATURES: readonly string[];
+/** One field of a `patch`: the text being typed, and the saved value the page was rendered from. */
+export interface PatchField {
+    field: string;
+    value: string;
+    saved: string;
+}
+/** A `patch` past these is refused whole: no form has that many text fields, or that much text in one. */
+export declare const PATCH_MAX_FIELDS = 500;
+export declare const PATCH_MAX_LENGTH = 100000;
+export type AdminMessage = {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "hello";
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "highlight";
+    entryId: string;
+    field: string | null;
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "outline";
+    on: boolean;
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "refresh";
+} | {
+    source: typeof ADMIN_SOURCE;
+    v: 1;
+    type: "patch";
+    entryId: string;
+    fields: PatchField[];
+};
+export type SiteMessage = {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "ready";
+    path: string;
+    entries: string[];
+    features?: string[];
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "select";
+    entryId: string;
+    field: string;
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "hover";
+    entryId: string;
+    field: string | null;
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "visible";
+    entryId: string;
+    field: string;
+};
+/** The parts of a `MessageEvent` the filter reads, so a test can hand in a literal. */
+export interface MessageLike {
+    origin: string;
+    source: unknown;
+    data: unknown;
+}
+/**
+ * `https://admin.example.com/` and `https://admin.example.com` are one origin,
+ * and a configured value that is not a URL at all is dropped rather than
+ * compared as a string, because `"*"` must never mean "anyone".
+ */
+export declare function normaliseOrigins(origins: readonly string[]): string[];
+/**
+ * The one gate every incoming message goes through. A message is accepted only
+ * when all of these hold, and is `null` otherwise:
+ *
+ *   - it came from the window that framed this page (`parent`), not from a
+ *     popup, a sibling frame or this page itself
+ *   - its origin is one the site configured as its admin
+ *   - it says it is from the admin, speaks version 1, and has a known type
+ *     whose fields have the right shapes
+ *
+ * `allowedOrigins` is expected already normalised (`normaliseOrigins`).
+ */
+export declare function acceptMessage(event: MessageLike, allowedOrigins: readonly string[], parent: unknown): AdminMessage | null;
+/**
+ * The text a node should read after a patch, or null to leave it alone.
+ *
+ * Only while its text (trimmed) is the saved value or what this page last
+ * patched it to, so text the site formats is never touched. The whitespace a
+ * template put around it stays. Null too when there is nothing to change.
+ */
+export declare function patchedText(current: string, change: {
+    value: string;
+    saved: string;
+}, lastPatched: string | null, around?: {
+    lead: string;
+    trail: string;
+}): string | null;
+/**
+ * The whitespace around a node's text, which a patch keeps. A node that is
+ * only whitespace keeps it in front. The overlay remembers this from the
+ * first patch, so text typed away to nothing and back lands where it was.
+ */
+export declare function textAround(current: string): {
+    lead: string;
+    trail: string;
+};
+export declare function readyMessage(path: string, entries: string[], features?: readonly string[]): SiteMessage;
+export declare function selectMessage(entryId: string, field: string): SiteMessage;
+export declare function hoverMessage(entryId: string, field: string | null): SiteMessage;
+export declare function visibleMessage(entryId: string, field: string): SiteMessage;
+/** The part of a tagged element `pickCentred` reads, so a test can hand in literals. */
+export interface TaggedBox {
+    entryId: string;
+    field: string;
+    /** `getBoundingClientRect()`, viewport coordinates. */
+    top: number;
+    bottom: number;
+}
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+export declare function pickCentred(boxes: readonly TaggedBox[], viewportHeight: number, edge?: "top" | "bottom" | null): TaggedBox | null;
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+export declare function scrollEdge(scrollY: number, viewportHeight: number, scrollHeight: number): "top" | "bottom" | null;

package/dist/esm/overlay/protocol.js

@@ -0,0 +1,240 @@
+/**
+ * The live preview protocol, site side. Pure: no DOM, no globals, so it can be
+ * tested under plain `node --test`.
+ *
+ * The Capa admin frames the site and the two talk over `postMessage`. Every
+ * message is a plain object `{ source, v: 1, type, ...fields }`:
+ *
+ *   admin -> site  (source "capa-admin")
+ *     hello     {}                                   sent on the frame's load
+ *     highlight { entryId, field: string | null }    entryId "" clears
+ *     outline   { on: boolean }                      outline every tagged element
+ *     refresh   {}                                   re-render the draft
+ *     patch     { entryId, fields: [{ field, value, saved }] }
+ *                                                    unsaved text, as the editor types it
+ *
+ *   site -> admin  (source "capa")
+ *     ready     { path, entries, features }          after hello, and after every navigation.
+ *                                                    `features`: what this overlay can do
+ *                                                    beyond v1 (`SITE_FEATURES`)
+ *     select    { entryId, field }                   a tagged element was clicked
+ *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it. `patch` and `features` are the
+ * same kind of addition: an admin sends `patch` only to an overlay whose
+ * `ready` lists "patch", and an older admin never reads `features`.
+ *
+ * A PATCH IS TEXT ONLY, and only where the page shows the field verbatim. The
+ * overlay changes a tagged element's text while it reads exactly `saved` (the
+ * value the page was rendered from) or what this page last patched it to, so
+ * a field the site formats (a price, a date, Markdown) is left alone until the
+ * save re-renders it (`patchedText`).
+ *
+ * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
+ * this package). If you change one side, change the other.
+ */
+export const PROTOCOL_VERSION = 1;
+export const ADMIN_SOURCE = "capa-admin";
+export const SITE_SOURCE = "capa";
+/** What this overlay can do beyond v1, listed in its `ready`. */
+export const SITE_FEATURES = ["patch"];
+/** A `patch` past these is refused whole: no form has that many text fields, or that much text in one. */
+export const PATCH_MAX_FIELDS = 500;
+export const PATCH_MAX_LENGTH = 100_000;
+/**
+ * `https://admin.example.com/` and `https://admin.example.com` are one origin,
+ * and a configured value that is not a URL at all is dropped rather than
+ * compared as a string, because `"*"` must never mean "anyone".
+ */
+export function normaliseOrigins(origins) {
+    const out = [];
+    for (const raw of origins) {
+        if (typeof raw !== "string" || raw.trim() === "")
+            continue;
+        try {
+            const origin = new URL(raw.trim()).origin;
+            if (origin !== "null" && !out.includes(origin))
+                out.push(origin);
+        }
+        catch {
+            // Not a URL: never an origin anybody can send from.
+        }
+    }
+    return out;
+}
+/**
+ * The one gate every incoming message goes through. A message is accepted only
+ * when all of these hold, and is `null` otherwise:
+ *
+ *   - it came from the window that framed this page (`parent`), not from a
+ *     popup, a sibling frame or this page itself
+ *   - its origin is one the site configured as its admin
+ *   - it says it is from the admin, speaks version 1, and has a known type
+ *     whose fields have the right shapes
+ *
+ * `allowedOrigins` is expected already normalised (`normaliseOrigins`).
+ */
+export function acceptMessage(event, allowedOrigins, parent) {
+    if (!event || event.source !== parent || parent == null)
+        return null;
+    if (typeof event.origin !== "string" || !allowedOrigins.includes(event.origin))
+        return null;
+    const data = event.data;
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const m = data;
+    if (m.source !== ADMIN_SOURCE || m.v !== PROTOCOL_VERSION)
+        return null;
+    switch (m.type) {
+        case "hello":
+            return { source: ADMIN_SOURCE, v: 1, type: "hello" };
+        case "refresh":
+            return { source: ADMIN_SOURCE, v: 1, type: "refresh" };
+        case "outline":
+            if (typeof m.on !== "boolean")
+                return null;
+            return { source: ADMIN_SOURCE, v: 1, type: "outline", on: m.on };
+        case "highlight":
+            if (typeof m.entryId !== "string")
+                return null;
+            if (m.field !== null && typeof m.field !== "string")
+                return null;
+            return { source: ADMIN_SOURCE, v: 1, type: "highlight", entryId: m.entryId, field: m.field };
+        case "patch": {
+            if (typeof m.entryId !== "string" || m.entryId === "")
+                return null;
+            if (!Array.isArray(m.fields) || m.fields.length > PATCH_MAX_FIELDS)
+                return null;
+            const fields = [];
+            for (const raw of m.fields) {
+                if (typeof raw !== "object" || raw === null)
+                    return null;
+                const f = raw;
+                if (typeof f.field !== "string" || f.field === "")
+                    return null;
+                if (typeof f.value !== "string" || typeof f.saved !== "string")
+                    return null;
+                if (f.value.length > PATCH_MAX_LENGTH || f.saved.length > PATCH_MAX_LENGTH)
+                    return null;
+                fields.push({ field: f.field, value: f.value, saved: f.saved });
+            }
+            return { source: ADMIN_SOURCE, v: 1, type: "patch", entryId: m.entryId, fields };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * The text a node should read after a patch, or null to leave it alone.
+ *
+ * Only while its text (trimmed) is the saved value or what this page last
+ * patched it to, so text the site formats is never touched. The whitespace a
+ * template put around it stays. Null too when there is nothing to change.
+ */
+export function patchedText(current, change, lastPatched, around = textAround(current)) {
+    const text = current.trim();
+    const ours = text === change.saved.trim() || (lastPatched !== null && text === lastPatched.trim());
+    if (!ours || text === change.value.trim())
+        return null;
+    return `${around.lead}${change.value}${around.trail}`;
+}
+/**
+ * The whitespace around a node's text, which a patch keeps. A node that is
+ * only whitespace keeps it in front. The overlay remembers this from the
+ * first patch, so text typed away to nothing and back lands where it was.
+ */
+export function textAround(current) {
+    const text = current.trim();
+    if (text === "")
+        return { lead: current, trail: "" };
+    return {
+        lead: current.slice(0, current.length - current.trimStart().length),
+        trail: current.slice(current.trimEnd().length),
+    };
+}
+export function readyMessage(path, entries, features) {
+    return features
+        ? { source: SITE_SOURCE, v: 1, type: "ready", path, entries, features: [...features] }
+        : { source: SITE_SOURCE, v: 1, type: "ready", path, entries };
+}
+export function selectMessage(entryId, field) {
+    return { source: SITE_SOURCE, v: 1, type: "select", entryId, field };
+}
+export function hoverMessage(entryId, field) {
+    return entryId === ""
+        ? { source: SITE_SOURCE, v: 1, type: "hover", entryId: "", field: null }
+        : { source: SITE_SOURCE, v: 1, type: "hover", entryId, field };
+}
+export function visibleMessage(entryId, field) {
+    return { source: SITE_SOURCE, v: 1, type: "visible", entryId, field };
+}
+/** Above any element height, so a box that misses the centre line never outranks one that crosses it. */
+const MISS_FLOOR = 1e9;
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+export function pickCentred(boxes, viewportHeight, edge = null) {
+    const centre = viewportHeight / 2;
+    let best = null;
+    let bestScore = Infinity;
+    for (const b of boxes) {
+        if (!b.entryId || !b.field)
+            continue;
+        if (b.bottom <= 0 || b.top >= viewportHeight || b.bottom <= b.top)
+            continue;
+        const height = b.bottom - b.top;
+        let score;
+        if (edge === "top") {
+            // Topmost first; of two that start together, the smaller (inner) one.
+            score = b.top * MISS_FLOOR + height;
+        }
+        else if (edge === "bottom") {
+            score = (viewportHeight - b.bottom) * MISS_FLOOR + height;
+        }
+        else {
+            // Crossing the line scores by height (smaller wins) and always beats a
+            // box that misses it, which scores by its distance from the line on top
+            // of a floor no height can reach.
+            score =
+                b.top <= centre && b.bottom >= centre
+                    ? height
+                    : MISS_FLOOR + Math.min(Math.abs(b.top - centre), Math.abs(b.bottom - centre));
+        }
+        if (score < bestScore) {
+            best = b;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+export function scrollEdge(scrollY, viewportHeight, scrollHeight) {
+    const max = scrollHeight - viewportHeight;
+    if (max <= 1)
+        return null;
+    if (scrollY <= 1)
+        return "top";
+    if (scrollY >= max - 1)
+        return "bottom";
+    return null;
+}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/dist/graphql-codegen.d.ts

@@ -0,0 +1,117 @@
+/**
+ * graphql-codegen.ts — `capa-codegen --graphql` and `capa persist`, the pure half.
+ *
+ * Reads a key's schema (introspection JSON) and a project's GraphQL documents,
+ * validates every document against that schema, and writes ONE TypeScript
+ * module holding:
+ *
+ *   - the schema as types, for `createClient<CapaQuery>()` and the typed
+ *     builder (`client.graphql.query`);
+ *   - one `TypedDocument` constant per named operation, so
+ *     `client.graphql(ArticlesPageDocument, vars)` infers the result and the
+ *     variables with no cast, and beside it `<Name>Models`, the models it
+ *     reads, for its Next.js cache tags;
+ *   - for each document written as a literal (`#graphql`, `/* capa *\/` or
+ *     gql(`...`)), an entry in `CapaDocuments` keyed by its exact text, so
+ *     `client.graphql(LITERAL, vars)` infers them too, with no import;
+ *   - `capaTreeLayout`, what `toTree` reads of the schema, so a server lays a
+ *     builder result out in REST's shape without reading the schema first.
+ *
+ * The file walk and the network live in `bin/`; everything here is a function
+ * of its inputs, so it is tested without either.
+ *
+ * `graphql` (graphql-js) is loaded on first use, never at import: it is an
+ * optional peer dependency that only these commands need, and a site that
+ * only calls `client.graphql()` must not pay for it.
+ */
+import type * as GraphQLJs from "graphql";
+import type { CapaIntrospection } from "./next/graphql/introspection";
+/** graphql-js, or an error that says how to get it. */
+export declare function loadGraphQL(): typeof GraphQLJs;
+/** One GraphQL document found in a project, with where it came from. */
+export interface DocumentSource {
+    file: string;
+    /** 1-based line of the document's first character in `file`. */
+    line: number;
+    /** The document's text as the program holds it at run time: a template's escapes are applied. */
+    text: string;
+    /**
+     * True for a literal whose type is its text (`#graphql`, `/* capa *\/`,
+     * gql(`...`)): it is sent exactly as written, and codegen keys its types by
+     * that text.
+     */
+    literal?: true;
+    /** The variable a literal is assigned to (`const CARD = ...`), which another literal's `${CARD}` names. */
+    name?: string;
+    /**
+     * For a literal with `${NAME}` in it: the text around each `${}` and the
+     * names in them, resolved against the project's other literals before the
+     * literal is read. `text` holds the template with its `${NAME}`s meanwhile.
+     */
+    template?: {
+        segments: string[];
+        names: string[];
+        asConst: boolean;
+    };
+}
+/** A template codegen does not read, and why: the CLI prints each one, so none is dropped in silence. */
+export interface SkippedDocument extends DocumentSource {
+    reason: string;
+}
+/** A template's text at run time, from its source text: line ends as LF, escapes applied. */
+export declare function cookTemplate(raw: string): string;
+/**
+ * The GraphQL documents in one file: the whole file for `.graphql` and `.gql`,
+ * and elsewhere every template that is marked as one: a `#graphql` first
+ * line, a `/* capa *\/` comment before it, or `gql` as a tag or a function.
+ * One on a comment line is an example, not a document.
+ *
+ * `skipped` names every template codegen will not read that looks meant for
+ * it, with the reason: one with `${}` inside (its text is only known at run
+ * time, so it cannot be validated or hashed ahead of it), a named operation
+ * left unmarked, and `/nextjs`'s `graphql` used as a tag.
+ */
+export declare function extractDocuments(file: string, text: string): {
+    documents: DocumentSource[];
+    skipped: SkippedDocument[];
+};
+export interface CodegenProblem {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}
+export interface GeneratedOperation {
+    name: string;
+    /** The exact text of its `<Name>Document`, and hashed for persisted queries. */
+    document: string;
+    sha256: string;
+    /** The namespaces of the models it reads, written as `<Name>Models` for its cache tags. */
+    models: string[];
+    /** For a document written as a literal: the literal's text, which is what a call with it sends, and its hash. */
+    literal?: {
+        document: string;
+        sha256: string;
+    };
+}
+export interface GraphQLCodegenResult {
+    /** The module to write. Null when a document failed. */
+    source: string | null;
+    operations: GeneratedOperation[];
+    problems: CodegenProblem[];
+    /**
+     * Each use of a deprecated field, argument, input field or enum value, with
+     * the reason the schema gives: it still works, and a later Capa-Version
+     * removes it.
+     */
+    warnings: CodegenProblem[];
+    /** Literals with a `${}` that names no literal of the project, so their text is only known at run time. */
+    skipped: SkippedDocument[];
+}
+/**
+ * The generated module for a schema and a project's documents. Problems (a
+ * syntax error, a field the key cannot read, an unnamed operation, a name used
+ * twice) are returned with their file and line, and no module is produced
+ * while any remain.
+ */
+export declare function generateGraphQLModule(introspection: CapaIntrospection, sources: DocumentSource[]): GraphQLCodegenResult;