@pramen/cms-astro 0.0.48 → 0.0.50

package/README.md

@@ -3,12 +3,16 @@
 Consume a [`@pramen/cms`](../cms) backend from an **Astro** site. Self-contained (no
 `@pramen/server` dependency — it speaks the CMS's public HTTP content API).
 
-- **`createCmsClient({ baseUrl })`** — `getPage(slug, locale?)` and `listPublishedPages()`.
+- **`createCmsClient({ baseUrl })`** — `getPage(slug, locale?)`, `listPublishedPages()`, and
+  `getPreview(token)` to redeem a signed preview link (no session needed — the signature is
+  the authorization; the result carries `isPreview: true`).
 - **`cmsLoader({ client })`** — an Astro **content-collection loader**. Wire it into a
   collection and the CMS's published pages become available via `getCollection()` /
   `getEntry()`, rendered to static HTML at build time (re-run the build — a publish webhook —
   to refresh). Works with `output: 'static'`; no SSR required.
 - **`BlockRenderer.astro`** — render a page's blocks with your own `.astro` components.
+- **`RichText.astro`** — render a `richtext` field. The value is a document tree, not an
+  HTML string, so it walks into real elements — nothing on this path uses `set:html`.
 
 ```ts
 // src/content.config.ts
@@ -40,6 +44,17 @@ const components = { rich_text: RichText, image: ImageBlock };
 <BlockRenderer blocks={page.blocks} {components} />
 ```
 
+A block component renders its own fields; a `richtext` one hands the tree to `RichText`:
+
+```astro
+---
+// src/components/blocks/RichText.astro
+import RichText from "@pramen/cms-astro/RichText.astro";
+const { fields } = Astro.props;
+---
+<RichText value={fields.body} />
+```
+
 The `cmsLoader`'s default entry `data` flattens the page's own `fields` to the top level and
 adds `title / slug / locale / seo / regions / blocks` (blocks in document order). Pass
 `transform` to shape it differently, or a Zod `schema` on the collection to validate it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pramen/cms-astro",
-  "version": "0.0.48",
-  "description": "Astro integration for @pramen/cms — a build-time content-collection loader + a BlockRenderer for rendering CMS blocks in .astro pages.",
+  "version": "0.0.50",
+  "description": "Astro integration for @pramen/cms \u2014 a build-time content-collection loader + a BlockRenderer for rendering CMS blocks in .astro pages.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,9 +14,13 @@
   "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
-    "./BlockRenderer.astro": "./src/BlockRenderer.astro"
+    "./BlockRenderer.astro": "./src/BlockRenderer.astro",
+    "./RichText.astro": "./src/RichText.astro",
+    "./RichTextMarks.astro": "./src/RichTextMarks.astro"
   },
-  "files": ["src"],
+  "files": [
+    "src"
+  ],
   "peerDependencies": {
     "astro": ">=4"
   },

package/src/BlockRenderer.astro

@@ -22,7 +22,9 @@ const { blocks, components, region } = Astro.props;
 
 {
   blocks.map((block) => {
-    const Component = components[block.block_type];
+    // hasOwn: a block type slugged `constructor`/`valueOf` would otherwise resolve off
+    // the prototype and crash the render.
+    const Component = Object.hasOwn(components, block.block_type) ? components[block.block_type] : undefined;
     return Component ? (
       <Component fields={block.fields} block={block} region={region} />
     ) : (

package/src/RichText.astro

@@ -0,0 +1,106 @@
+---
+// Render a @pramen/cms `richtext` field. The value is a document TREE, not an HTML
+// string, so this walks it into real elements — there is no `set:html` anywhere on the
+// path, and nothing to sanitize at render time (the write path already dropped every node
+// and mark outside the allow-list).
+//
+//   import RichText from "@pramen/cms-astro/RichText.astro";
+//   <RichText value={block.fields.body} />
+//
+// Recurses into itself for child nodes; text leaves go through RichTextMarks.astro.
+
+import type { RichTextDoc, RichTextNode } from "./index";
+import Self from "./RichText.astro";
+import Marks from "./RichTextMarks.astro";
+
+interface Props {
+  /** A whole document — what a `richtext` field holds. */
+  value?: RichTextDoc | null;
+  /** Child nodes, used when this component recurses into itself. */
+  nodes?: RichTextNode[];
+}
+
+const { value, nodes } = Astro.props;
+const list = nodes ?? value?.content ?? [];
+---
+
+{
+  list.map((node) => {
+    const attrs = node.attrs ?? {};
+    const children = node.content ?? [];
+
+    switch (node.type) {
+      case "text":
+        return <Marks text={node.text ?? ""} marks={node.marks} />;
+      case "paragraph":
+        return (
+          <p>
+            <Self nodes={children} />
+          </p>
+        );
+      case "heading": {
+        // Integer too — `h2.5` is an invalid element name.
+        const level =
+          typeof attrs.level === "number" && Number.isInteger(attrs.level) && attrs.level >= 1 && attrs.level <= 6 ? attrs.level : 2;
+        const Tag = `h${level}`;
+        return (
+          <Tag>
+            <Self nodes={children} />
+          </Tag>
+        );
+      }
+      case "blockquote":
+        return (
+          <blockquote>
+            <Self nodes={children} />
+          </blockquote>
+        );
+      case "codeBlock":
+        return (
+          <pre>
+            <code class={typeof attrs.language === "string" ? `language-${attrs.language}` : undefined}>
+              <Self nodes={children} />
+            </code>
+          </pre>
+        );
+      case "bulletList":
+        return (
+          <ul>
+            <Self nodes={children} />
+          </ul>
+        );
+      case "orderedList":
+        return (
+          <ol start={typeof attrs.start === "number" ? attrs.start : undefined}>
+            <Self nodes={children} />
+          </ol>
+        );
+      case "listItem":
+        return (
+          <li>
+            <Self nodes={children} />
+          </li>
+        );
+      case "taskList":
+        return (
+          <ul data-type="taskList">
+            <Self nodes={children} />
+          </ul>
+        );
+      case "taskItem":
+        return (
+          <li data-type="taskItem" data-checked={attrs.checked === true ? "true" : "false"}>
+            <Self nodes={children} />
+          </li>
+        );
+      case "hardBreak":
+        return <br />;
+      case "horizontalRule":
+        return <hr />;
+      default:
+        // Unreachable through the write path (normalizeRichText drops unknown types), so
+        // rendering the subtree is a rescue for hand-written content, not a policy.
+        return <Self nodes={children} />;
+    }
+  })
+}

package/src/RichTextMarks.astro

@@ -0,0 +1,55 @@
+---
+// Wrap a text leaf in its inline marks, peeling one mark per recursion. Split out of
+// RichText.astro because marks nest arbitrarily (bold inside a link inside a highlight)
+// and a template can't build that chain in one pass.
+//
+// A `link` is the only mark carrying attributes through. `target="_blank"` gets `rel`
+// forced: this component owns the markup, and a bare `_blank` hands the opened page a
+// live `window.opener` handle back to yours.
+
+import { isSafeHref, normalizeHref, type RichTextMark } from "./index";
+import Self from "./RichTextMarks.astro";
+
+interface Props {
+  text: string;
+  marks?: RichTextMark[];
+}
+
+const { text, marks = [] } = Astro.props;
+const [mark, ...rest] = marks;
+
+const MARK_TAGS: Record<string, string> = {
+  bold: "strong",
+  italic: "em",
+  underline: "u",
+  strike: "s",
+  code: "code",
+  highlight: "mark",
+};
+
+const attrs = mark?.attrs ?? {};
+// Astro does not sanitize attribute values, so an unchecked href here would render a
+// working `javascript:` anchor for any document that skipped the write-path normalizer.
+// An unsafe link degrades to its text rather than becoming a live one.
+const href = isSafeHref(attrs.href) ? normalizeHref(String(attrs.href)) : "";
+const isLink = mark?.type === "link" && href !== "";
+const title = typeof attrs.title === "string" ? attrs.title : undefined;
+const target = typeof attrs.target === "string" ? attrs.target : undefined;
+// hasOwn: a plain index would resolve `constructor`/`toString` off the prototype.
+const markType = mark?.type ?? "";
+const Tag = Object.hasOwn(MARK_TAGS, markType) ? MARK_TAGS[markType] : "span";
+---
+
+{
+  !mark ? (
+    text
+  ) : isLink ? (
+    <a href={href} title={title} target={target} rel={target ? "noopener noreferrer" : undefined}>
+      <Self text={text} marks={rest} />
+    </a>
+  ) : (
+    <Tag>
+      <Self text={text} marks={rest} />
+    </Tag>
+  )
+}

package/src/index.ts

@@ -11,6 +11,9 @@
 
 import type { Loader, LoaderContext } from "astro/loaders";
 
+/** Any JSON value — the wire form of everything the CMS stores. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
 /** A resolved media reference (a `"media"` block field, resolved by the CMS). */
 export interface ResolvedMedia {
   id: string;
@@ -21,8 +24,53 @@ export interface ResolvedMedia {
   filename: string | null;
 }
 
+/** A rich-text document — the structured JSON a `richtext` field stores. Mirrors
+ * `RichTextDoc` in @pramen/cms; render it with `RichText.astro`. Never an HTML string:
+ * nothing on this path uses `set:html`. */
+export interface RichTextDoc {
+  type: "doc";
+  content?: RichTextNode[];
+}
+
+/** One node in a {@link RichTextDoc}. */
+export interface RichTextNode {
+  type: string;
+  content?: RichTextNode[];
+  text?: string;
+  marks?: RichTextMark[];
+  attrs?: Record<string, JsonValue>;
+}
+
+/** An inline mark on a text node. */
+export interface RichTextMark {
+  type: string;
+  attrs?: Record<string, JsonValue>;
+}
+
+/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path — a single
+ * leading slash, and the next character neither `/` nor `\` (both resolve off-site while
+ * looking local; the URL parser folds `\` to `/` at path-start).
+ *
+ * A local mirror of `isSafeHref` in @pramen/cms, because this package deliberately has no
+ * dependency on it. `RichText.astro` checks every link with it: the write path normalizes,
+ * but a row written by an app's own mutation, a bootstrap seed or an import script never
+ * passed through that, and this renderer is what puts it on a page. */
+export function isSafeHref(raw: unknown): boolean {
+  return typeof raw === "string" && /^(https?:\/\/|mailto:|tel:|\/(?![/\\])|#)/i.test(normalizeHref(raw));
+}
+
+/** Strip the characters the WHATWG URL parser ignores before parsing (ASCII tab/CR/LF),
+ * then trim. Without this, `/\r\n/evil.example/x` passes a naive prefix test and still
+ * resolves to `https://evil.example/x`. Render THIS form, so what was checked is what
+ * the browser resolves. */
+export function normalizeHref(raw: string): string {
+  return raw.replace(/[\t\n\r]/g, "").trim();
+}
+
 export interface RenderedBlock {
   id: string;
+  /** Optimistic-concurrency token — pass back as `expectedVersion` on a write. */
+  version: number;
   block_id: string;
   block_type: string;
   title: string | null;
@@ -45,8 +93,13 @@ export interface AssembledPage {
     metaTitle: string | null;
     metaDescription: string | null;
     seo?: Record<string, unknown>;
+    /** Optimistic-concurrency token — pass back as `expectedVersion` on a write. */
+    version: number;
   };
   regions: Record<string, RenderedBlock[]>;
+  /** True when this is a live draft fetched through a preview link, not the published
+   * snapshot — render a "viewing a draft" banner off it. */
+  isPreview?: boolean;
 }
 
 export interface PublishedPageRef {
@@ -68,6 +121,9 @@ export interface CmsClientOptions {
 
 export interface CmsClient {
   getPage(slug: string, locale?: string): Promise<AssembledPage | null>;
+  /** Redeem a signed preview link. The token names one page and carries its own expiry,
+   * so this needs no session — pass through whatever arrived in the request's query. */
+  getPreview(token: string): Promise<AssembledPage | null>;
   listPublishedPages(): Promise<PublishedPageRef[]>;
   /** Absolute URL for a relative CMS path (e.g. a media `/media/...` url). */
   resolve(path: string): string;
@@ -78,13 +134,14 @@ export interface CmsClient {
 export function createCmsClient(opts: CmsClientOptions): CmsClient {
   const base = opts.baseUrl.replace(/\/+$/, "");
   const call = async <T>(name: string, input: unknown): Promise<T | null> => {
+    const headers = new Headers({
+      "content-type": "application/json",
+      "x-pramen-tenant": opts.tenant ?? "main",
+    });
+    if (opts.token) headers.set("authorization", `Bearer ${opts.token}`);
     const res = await fetch(`${base}/rpc/${name}`, {
       method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "x-pramen-tenant": opts.tenant ?? "main",
-        ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}),
-      },
+      headers,
       body: JSON.stringify(input ?? {}),
     });
     const body = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: unknown; code?: string };
@@ -97,6 +154,18 @@ export function createCmsClient(opts: CmsClientOptions): CmsClient {
   return {
     baseUrl: base,
     getPage: (slug, locale) => call<AssembledPage>("getPage", { slug, locale }),
+    getPreview: async (token) => {
+      // Not an /rpc call: the preview route is public and pre-auth, and the signature IS
+      // the authorization, so there is no bearer token to send.
+      const res = await fetch(`${base}/cms/preview?token=${encodeURIComponent(token)}`);
+      if (res.ok) return (await res.json().catch(() => null)) as AssembledPage | null;
+      // 403/404 mean "this link is not valid" — an ordinary not-found for the caller.
+      // Anything else (notably 503, "preview is not configured") is an operator problem
+      // and must not masquerade as a missing page.
+      if (res.status === 403 || res.status === 404) return null;
+      const body = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
+      throw new Error(`@pramen/cms-astro: preview failed (HTTP ${res.status}${body.code ? `, ${body.code}` : ""}${body.error ? `: ${body.error}` : ""})`);
+    },
     listPublishedPages: async () => (await call<PublishedPageRef[]>("listPublishedPages", {})) ?? [],
     resolve: (path) => (path.startsWith("http") ? path : `${base}${path}`),
   };