@seamlet/astro 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,50 @@
+// src/index.ts
+import { fileURLToPath } from "url";
+var CONFIG_MODULE = "virtual:seamlet/config";
+var SITE_MODULE = "virtual:seamlet/site";
+var RESOLVED_CONFIG_MODULE = `\0${CONFIG_MODULE}`;
+function seamlet(options) {
+  const cmsOrigin = new URL(options.cms).origin;
+  return {
+    name: "@seamlet/astro",
+    hooks: {
+      "astro:config:setup": ({
+        config,
+        injectRoute,
+        injectScript,
+        updateConfig
+      }) => {
+        const siteModule = fileURLToPath(new URL(options.site, config.root));
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "seamlet-modules",
+                resolveId: (id) => {
+                  if (id === CONFIG_MODULE) return RESOLVED_CONFIG_MODULE;
+                  if (id === SITE_MODULE) return siteModule;
+                  return void 0;
+                },
+                load: (id) => id === RESOLVED_CONFIG_MODULE ? `export const cmsOrigin = ${JSON.stringify(cmsOrigin)};` : void 0
+              }
+            ]
+          }
+        });
+        injectScript("page", `import "@seamlet/astro/client";`);
+        injectRoute({
+          pattern: "/preview/[...page]",
+          entrypoint: "@seamlet/astro/routes/preview.astro",
+          prerender: false
+        });
+        injectRoute({
+          pattern: "/media/[site]/[file]",
+          entrypoint: "@seamlet/astro/routes/media",
+          prerender: false
+        });
+      }
+    }
+  };
+}
+export {
+  seamlet as default
+};

package/dist/messages-DIMwt3Kn.d.ts

@@ -0,0 +1,143 @@
+import { F as Fields, d as Content } from './content-DKVM1CUQ.js';
+import { F as FieldPath } from './parse-content-DF2dL2FG.js';
+
+interface Box {
+    readonly top: number;
+    readonly left: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+
+type Shortcut = "save" | "undo" | "redo";
+declare function shortcutOf(event: KeyboardEvent): Shortcut | undefined;
+
+type InlineEditingOutcome = "kept" | "reverted";
+
+/**
+ * The version of what the two say to each other. A site updates @seamlet/astro when it likes, so the
+ * editor may meet a bridge of another version: it tells by this number, said with `ready`, instead
+ * of misreading the page. Raised whenever a message changes in a way the other side cannot read.
+ */
+declare const PROTOCOL_VERSION = 1;
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** A marked element of the page and where it is. */
+interface MarkerBox {
+    readonly path: string;
+    readonly box: Box;
+}
+/** A link on the page that is not a field. */
+interface LinkBox {
+    /** The address as the site wrote it. */
+    readonly href: string;
+    readonly box: Box;
+}
+/** Where everything the editor draws over is on the page now. */
+interface PageLayout {
+    /** Every marked element that takes space, in the order of the page. */
+    readonly markers: readonly MarkerBox[];
+    readonly viewport: Viewport;
+    /** The link under the pointer, if it is not a field. */
+    readonly link: LinkBox | undefined;
+}
+/** A key the editor acts on: its shortcuts, and Escape that closes what is open. */
+type EditorKey = Shortcut | "escape";
+/** What the page tells the editor. */
+type PageMessage = 
+/** The bridge runs and waits for the editor to connect; it speaks this version of the protocol. */
+{
+    readonly type: "ready";
+    readonly protocol: number;
+} | {
+    readonly type: "layout";
+    readonly layout: PageLayout;
+}
+/** The pointer moved onto a marked element, or off all of them. */
+ | {
+    readonly type: "hover";
+    readonly path: string | undefined;
+}
+/** A click on a marked element, or outside all of them. */
+ | {
+    readonly type: "click";
+    readonly target: {
+        readonly path: string;
+        readonly point: Point;
+    } | undefined;
+} | {
+    readonly type: "link-click";
+    readonly href: string;
+} | {
+    readonly type: "key";
+    readonly key: EditorKey;
+}
+/** A file is dragged over the page: over a photo that takes it, or elsewhere. */
+ | {
+    readonly type: "file-drag";
+    readonly path: string | undefined;
+} | {
+    readonly type: "file-drag-end";
+} | {
+    readonly type: "file-drop";
+    readonly path: string;
+    readonly file: File;
+} | {
+    readonly type: "typing-started";
+    readonly path: string;
+}
+/** The element does not show the text as it is: the field is edited in a popover. */
+ | {
+    readonly type: "typing-refused";
+    readonly path: string;
+} | {
+    readonly type: "typed";
+    readonly path: string;
+    readonly text: string;
+} | {
+    readonly type: "typing-ended";
+    readonly path: string;
+    readonly outcome: InlineEditingOutcome;
+} | {
+    readonly type: "rendered";
+} | {
+    readonly type: "render-failed";
+};
+/** What the editor tells the page. */
+type EditorMessage = 
+/** The editor took the page; the schema tells the bridge which fields take a photo. */
+{
+    readonly type: "connect";
+    readonly schema: Fields;
+}
+/** Show the page with this content. */
+ | {
+    readonly type: "render";
+    readonly content: Content;
+}
+/** Type the text of the field right in its element, if the element shows it as it is. */
+ | {
+    readonly type: "start-typing";
+    readonly path: string;
+    readonly text: string;
+    readonly isSingleLine: boolean;
+    readonly point: Point;
+} | {
+    readonly type: "stop-typing";
+}
+/** Bring the field, or the closest marked element around it, into view. */
+ | {
+    readonly type: "scroll-to";
+    readonly path: FieldPath;
+};
+/** The message the page sent, or undefined for anything that is not one. */
+declare function readPageMessage(data: unknown): PageMessage | undefined;
+/** The message the editor sent, or undefined for anything that is not one. */
+declare function readEditorMessage(data: unknown): EditorMessage | undefined;
+
+export { type Box as B, type EditorMessage as E, type InlineEditingOutcome as I, type LinkBox as L, type MarkerBox as M, type PageMessage as P, type Shortcut as S, type Viewport as V, type EditorKey as a, PROTOCOL_VERSION as b, type PageLayout as c, type Point as d, readPageMessage as e, readEditorMessage as r, shortcutOf as s };

package/dist/parse-content-DF2dL2FG.d.ts

@@ -0,0 +1,54 @@
+import { F as Fields, C as ContentOf } from './content-DKVM1CUQ.js';
+
+/** Where a value lives in the content: field names and, inside a collection, record indexes. */
+type FieldPath = readonly (string | number)[];
+type ContentIssue = {
+    readonly path: FieldPath;
+    readonly code: "invalid-type";
+} | {
+    readonly path: FieldPath;
+    readonly code: "invalid-date";
+} | {
+    readonly path: FieldPath;
+    readonly code: "too-long";
+    readonly maxLength: number;
+} | {
+    readonly path: FieldPath;
+    readonly code: "below-min";
+    readonly min: number;
+} | {
+    readonly path: FieldPath;
+    readonly code: "above-max";
+    readonly max: number;
+} | {
+    readonly path: FieldPath;
+    readonly code: "missing-image-src";
+} | {
+    readonly path: FieldPath;
+    readonly code: "missing-link-href";
+} | {
+    readonly path: FieldPath;
+    readonly code: "unsupported-link-href";
+};
+interface ParsedContent<C> {
+    readonly content: C;
+    readonly issues: readonly ContentIssue[];
+}
+declare function formatFieldPath(path: FieldPath): string;
+/**
+ * The length that `maxLength` limits: characters as people see them (grapheme clusters), so
+ * "й" and "👍🏽" are one character each, whatever number of code units they take.
+ */
+declare function countCharacters(text: string): number;
+/**
+ * Brings any input to the shape of the schema, so the result is always content of that schema:
+ * - a field missing from the input (the schema grew after the content was saved) gets its default;
+ * - a value of the wrong type or format gets the default too, and an issue;
+ * - a value of the right type that breaks a rule of its field (too long, below the minimum) is
+ *   kept, with an issue: nothing a person typed is lost;
+ * - keys the schema does not know are dropped.
+ * Content with issues is valid to show and edit, but not to save.
+ */
+declare function parseContent<F extends Fields>(schema: F, input: unknown): ParsedContent<ContentOf<F>>;
+
+export { type ContentIssue as C, type FieldPath as F, type ParsedContent as P, countCharacters as c, formatFieldPath as f, parseContent as p };

package/dist/preview-requests.d.ts

@@ -0,0 +1,18 @@
+/** Far more than the content of a site ever takes; a bigger body is not a draft. */
+declare const MAX_DRAFT_BYTES: number;
+type DraftReading = {
+    readonly isRead: true;
+    readonly draft: unknown;
+} | {
+    readonly isRead: false;
+    readonly response: Response;
+};
+/**
+ * The draft in the JSON body of a request. A form of another site cannot send JSON, so only the
+ * page's own bridge renders a draft.
+ */
+declare function readDraft(request: Request): Promise<DraftReading>;
+/** Whether a name can be a photo uploaded to the CMS: the hash of its bytes, as WebP. */
+declare function isUploadedPhoto(fileName: string | undefined): fileName is string;
+
+export { type DraftReading, MAX_DRAFT_BYTES, isUploadedPhoto, readDraft };

package/dist/preview-requests.js

@@ -0,0 +1,10 @@
+import {
+  MAX_DRAFT_BYTES,
+  isUploadedPhoto,
+  readDraft
+} from "./chunk-P2OQOZBC.js";
+export {
+  MAX_DRAFT_BYTES,
+  isUploadedPhoto,
+  readDraft
+};

package/dist/protocol.d.ts

@@ -0,0 +1,19 @@
+export { B as Box, a as EditorKey, E as EditorMessage, I as InlineEditingOutcome, L as LinkBox, M as MarkerBox, b as PROTOCOL_VERSION, c as PageLayout, P as PageMessage, d as Point, S as Shortcut, V as Viewport, r as readEditorMessage, e as readPageMessage, s as shortcutOf } from './messages-DIMwt3Kn.js';
+import { F as Fields, I as ImageField } from './content-DKVM1CUQ.js';
+import { F as FieldPath } from './parse-content-DF2dL2FG.js';
+
+declare function carriesFiles(event: DragEvent): boolean;
+
+/** The image field a marker points at, or undefined when it points at anything else. */
+declare function imageFieldAt(schema: Fields, path: string | undefined): {
+    readonly path: FieldPath;
+    readonly field: ImageField;
+} | undefined;
+
+/**
+ * The path a site marked for a field: the path itself or, when the site did not mark it, the
+ * closest path around it (the record of a price the page shows only as part of the record).
+ */
+declare function closestMarkedPath(path: FieldPath, isMarked: (path: string) => boolean): string | undefined;
+
+export { carriesFiles, closestMarkedPath, imageFieldAt };

package/dist/protocol.js

@@ -0,0 +1,19 @@
+import {
+  PROTOCOL_VERSION,
+  carriesFiles,
+  closestMarkedPath,
+  imageFieldAt,
+  readEditorMessage,
+  readPageMessage,
+  shortcutOf
+} from "./chunk-HRAL4X6W.js";
+import "./chunk-EC42AIQC.js";
+export {
+  PROTOCOL_VERSION,
+  carriesFiles,
+  closestMarkedPath,
+  imageFieldAt,
+  readEditorMessage,
+  readPageMessage,
+  shortcutOf
+};

package/dist/routes/media.d.ts

@@ -0,0 +1,5 @@
+import { APIRoute } from 'astro';
+
+declare const GET: APIRoute;
+
+export { GET };

package/dist/routes/media.js

@@ -0,0 +1,28 @@
+import {
+  isUploadedPhoto
+} from "../chunk-P2OQOZBC.js";
+
+// src/routes/media.ts
+import { cmsOrigin } from "virtual:seamlet/config";
+import site from "virtual:seamlet/site";
+var NOT_FOUND = 404;
+var GET = async ({ params }) => {
+  const fileName = params["file"];
+  const isOurs = params["site"] === site.id && isUploadedPhoto(fileName);
+  if (!isOurs) {
+    return new Response(null, { status: NOT_FOUND });
+  }
+  const response = await fetch(
+    new URL(`/media/${site.id}/${fileName}`, cmsOrigin)
+  );
+  return new Response(response.body, {
+    status: response.status,
+    headers: {
+      "Content-Type": response.headers.get("Content-Type") ?? "image/webp",
+      "Cache-Control": response.headers.get("Cache-Control") ?? "no-cache"
+    }
+  });
+};
+export {
+  GET
+};

package/dist/schema.d.ts

@@ -0,0 +1,68 @@
+import { a as ImageValue, L as LinkValue, b as Field, c as CollectionField, F as Fields } from './content-DKVM1CUQ.js';
+export { d as Content, C as ContentOf, D as DateField, e as FieldKind, f as FieldValue, G as GroupField, I as ImageField, g as LinkField, N as NumberField, T as TextField, V as ValueOf, h as collection, i as date, j as defaultContent, k as defaultValue, l as defineSchema, m as group, n as image, o as link, p as number, t as text } from './content-DKVM1CUQ.js';
+import { F as FieldPath } from './parse-content-DF2dL2FG.js';
+export { C as ContentIssue, P as ParsedContent, c as countCharacters, f as formatFieldPath, p as parseContent } from './parse-content-DF2dL2FG.js';
+
+declare const FIELD_PATH_ATTRIBUTE = "data-cms-path";
+interface FieldMarker {
+    readonly [FIELD_PATH_ATTRIBUTE]: string;
+}
+/**
+ * Every path in content of type C, as a tuple: ["hero"], ["hero", "title"], ["menu", 2],
+ * ["menu", 2, "price"]. Scalars, images and links are leaves: an image is one field, not two.
+ */
+type ContentPath<C> = C extends readonly (infer Record)[] ? [number] | [number, ...ContentPath<Record>] : C extends string | number | null | ImageValue | LinkValue ? never : {
+    [Name in keyof C & string]: [Name] | [Name, ...ContentPath<C[Name]>];
+}[keyof C & string];
+/**
+ * The marker of a site's content type. On its page a site spreads it on the element that shows
+ * a field or a record of a collection: `<h1 {...edit("hero", "title")}>`,
+ * `<li {...edit("menu", index)}>`. A path that is not in the content does not compile.
+ */
+declare function editable<C>(): (...path: ContentPath<C>) => FieldMarker;
+
+/** What a path written on a page points at: a field, or a whole record of a collection. */
+type FieldTarget = {
+    readonly kind: "field";
+    readonly path: FieldPath;
+    readonly field: Field;
+} | {
+    readonly kind: "record";
+    readonly path: FieldPath;
+    readonly collection: CollectionField;
+    /** The place of the record in its collection, the last segment of its path. */
+    readonly index: number;
+};
+/**
+ * Reads a path from a field marker (`menu.2.price`) by the schema: names inside fields and
+ * groups, indexes inside collections. A path the schema does not have gives undefined.
+ */
+declare function resolveFieldPath(schema: Fields, text: string): FieldTarget | undefined;
+
+/** Where a link leads, as the editor offers it. */
+type LinkTarget = {
+    readonly kind: "page";
+    readonly path: string;
+} | {
+    readonly kind: "web";
+    readonly url: string;
+} | {
+    readonly kind: "phone";
+    readonly number: string;
+} | {
+    readonly kind: "email";
+    readonly address: string;
+};
+type LinkKind = LinkTarget["kind"];
+/**
+ * Where the address leads, or undefined for an address a link of a site may not have. The address
+ * is checked exactly as it is stored and rendered: spaces around it make it no address at all.
+ */
+declare function linkTargetOf(href: string): LinkTarget | undefined;
+/**
+ * The address of a link from what a person typed: a phone or an email without `tel:` or
+ * `mailto:`, a site without `https://`.
+ */
+declare function hrefOf(target: LinkTarget): string;
+
+export { CollectionField, type ContentPath, FIELD_PATH_ATTRIBUTE, Field, type FieldMarker, FieldPath, type FieldTarget, Fields, ImageValue, type LinkKind, type LinkTarget, LinkValue, editable, hrefOf, linkTargetOf, resolveFieldPath };

package/dist/schema.js

@@ -0,0 +1,40 @@
+import {
+  FIELD_PATH_ATTRIBUTE,
+  collection,
+  countCharacters,
+  date,
+  defaultContent,
+  defaultValue,
+  defineSchema,
+  editable,
+  formatFieldPath,
+  group,
+  hrefOf,
+  image,
+  link,
+  linkTargetOf,
+  number,
+  parseContent,
+  resolveFieldPath,
+  text
+} from "./chunk-EC42AIQC.js";
+export {
+  FIELD_PATH_ATTRIBUTE,
+  collection,
+  countCharacters,
+  date,
+  defaultContent,
+  defaultValue,
+  defineSchema,
+  editable,
+  formatFieldPath,
+  group,
+  hrefOf,
+  image,
+  link,
+  linkTargetOf,
+  number,
+  parseContent,
+  resolveFieldPath,
+  text
+};

package/dist/site.d.ts

@@ -0,0 +1,25 @@
+import { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import { F as Fields, C as ContentOf } from './content-DKVM1CUQ.js';
+
+interface SeamletSiteDefinition<F extends Fields> {
+    /** The site's address in the CMS: `/sites/<id>`. */
+    readonly id: string;
+    readonly schema: F;
+    /**
+     * The pages of the site by their address (`/`, `/menu`): components that take the site's content
+     * as their `content` prop. The CMS lists the same addresses for its editor.
+     */
+    readonly pages: Readonly<Record<string, AstroComponentFactory>>;
+}
+interface SeamletSite<F extends Fields = Fields> {
+    readonly id: string;
+    readonly schema: F;
+    /** The page at the rest of an address: nothing is the first page, `menu` the page at /menu. */
+    readonly pageAt: (rest: string | undefined) => AstroComponentFactory | undefined;
+    /** What the CMS published: the site's initial content until the first publication. */
+    readonly loadPublishedContent: () => Promise<ContentOf<F>>;
+}
+/** Describes the site for the integration: `src/seamlet.ts` exports it as its default. */
+declare function defineSeamletSite<F extends Fields>(definition: SeamletSiteDefinition<F>): SeamletSite<F>;
+
+export { type SeamletSite, type SeamletSiteDefinition, defineSeamletSite };

package/dist/site.js

@@ -0,0 +1,32 @@
+import {
+  parseContent
+} from "./chunk-EC42AIQC.js";
+
+// src/site.ts
+import { cmsOrigin } from "virtual:seamlet/config";
+var HOME_PAGE_PATH = "/";
+function defineSeamletSite(definition) {
+  const pages = new Map(Object.entries(definition.pages));
+  return {
+    id: definition.id,
+    schema: definition.schema,
+    pageAt: (rest) => pages.get(rest === void 0 ? HOME_PAGE_PATH : `/${rest}`),
+    loadPublishedContent: async () => {
+      const published = await fetchPublished(definition.id);
+      return parseContent(definition.schema, published).content;
+    }
+  };
+}
+async function fetchPublished(siteId) {
+  const url = new URL(`/api/sites/${siteId}/published`, cmsOrigin);
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Loading the published content from ${url.href} failed with status ${String(response.status)}`
+    );
+  }
+  return response.json();
+}
+export {
+  defineSeamletSite
+};

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@seamlet/astro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Connects an Astro site to the Seamlet CMS: the schema of its content, the preview the editor frames, and its published content.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seamlet/sdk.git",
+    "directory": "packages/astro"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "default": "./dist/schema.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "default": "./dist/bridge.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./site": {
+      "types": "./dist/site.d.ts",
+      "default": "./dist/site.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./preview-requests": {
+      "types": "./dist/preview-requests.d.ts",
+      "default": "./dist/preview-requests.js"
+    },
+    "./routes/preview.astro": "./routes/preview.astro",
+    "./routes/media": {
+      "types": "./dist/routes/media.d.ts",
+      "default": "./dist/routes/media.js"
+    }
+  },
+  "files": [
+    "dist",
+    "routes"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "peerDependencies": {
+    "astro": ">=7.3.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://github.com/seamlet/sdk/tree/main/packages/astro#readme",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "cms",
+    "visual-editing",
+    "seamlet"
+  ]
+}

package/routes/preview.astro

@@ -0,0 +1,37 @@
+---
+// The preview the CMS's editor frames: a page of the site with the bridge to the editor.
+// `/preview` is the first page, `/preview/menu` the page at /menu. GET shows the published
+// content; POST shows the content in its JSON body, never saved: the bridge renders the editor's
+// draft this way.
+import { parseContent } from "@seamlet/astro/schema";
+import { readDraft } from "@seamlet/astro/preview-requests";
+import { cmsOrigin } from "virtual:seamlet/config";
+import site from "virtual:seamlet/site";
+
+const NOT_FOUND = 404;
+
+const Page = site.pageAt(Astro.params.page);
+if (Page === undefined) {
+  return new Response(null, { status: NOT_FOUND });
+}
+
+// Only the CMS's editor frames the preview, and nobody indexes or keeps it.
+Astro.response.headers.set(
+  "Content-Security-Policy",
+  `frame-ancestors ${cmsOrigin}`,
+);
+Astro.response.headers.set("X-Robots-Tag", "noindex");
+Astro.response.headers.set("Cache-Control", "no-store");
+
+const reading =
+  Astro.request.method === "POST" ? await readDraft(Astro.request) : undefined;
+if (reading !== undefined && !reading.isRead) {
+  return reading.response;
+}
+const content =
+  reading === undefined
+    ? await site.loadPublishedContent()
+    : parseContent(site.schema, reading.draft).content;
+---
+
+<Page content={content} />