@blocklify/preview 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @blocklify/preview
 
-Frontend SDK for [Blocklify](https://github.com/): Content API client + live-preview React helpers for your theme.
+Frontend SDK for [Blocklify](https://www.blocklify.app): Content API client, live preview, and starter blocks for a new website.
 
 ## Install
 
@@ -9,13 +9,66 @@ bun add @blocklify/preview
 # or: npm install @blocklify/preview
 ```
 
-Peer dependencies: `react`, `react-dom` (≥18).
+Peer dependencies: `react` and `react-dom` (≥18).
 
-## Live preview (theme blocks)
+## New Next.js site
 
-1. Mount `BlocklifyPreview` on a `/preview` route with your `blockMap`.
-2. In each theme block, accept `BlocklifyBlockProps` and spread `{...BlocklifyEditable}` on the root element.
-3. Read CMS custom fields from `block` (e.g. `block.headline`).
-4. Register that preview URL under Space → Live preview URLs.
+```bash
+bunx create-next-app@latest my-blocklify-site
+cd my-blocklify-site
+bun add @blocklify/preview
+cp -R node_modules/@blocklify/preview/starter/nextjs/app ./app
+cp node_modules/@blocklify/preview/starter/nextjs/.env.example ./.env.local
+```
+
+Fill in `.env.local`:
+
+```bash
+BLOCKLIFY_API_URL=https://localhost:3000
+NEXT_PUBLIC_BLOCKLIFY_API_URL=https://localhost:3000
+BLOCKLIFY_ACCESS_TOKEN=blocklify_…
+```
+
+Run the site on port 3001 and register `http://localhost:3001/preview` under Space → Settings → Live preview URLs.
+
+`app/page.tsx` renders the published `home` entry. `app/preview/page.tsx` is the editor iframe.
+
+## New React (Vite) site
+
+```bash
+bunx create-vite@latest my-blocklify-site --template react-ts
+cd my-blocklify-site
+bun add @blocklify/preview react-router-dom
+cp node_modules/@blocklify/preview/starter/react/src/App.tsx ./src/App.tsx
+cp node_modules/@blocklify/preview/starter/react/src/main.tsx ./src/main.tsx
+mkdir -p src/pages
+cp node_modules/@blocklify/preview/starter/react/src/pages/PreviewPage.tsx ./src/pages/PreviewPage.tsx
+cp node_modules/@blocklify/preview/starter/react/.env.example ./.env
+```
+
+Register `http://localhost:5173/preview` as the live preview URL.
+
+## What the starter renders
+
+Matches a Blocklify starter space:
+
+| Block type | Fields                                                     |
+| ---------- | ---------------------------------------------------------- |
+| `hero`     | `headline`, `subheadline`, `image`, `cta_text`, `cta_link` |
+| `text`     | `content` (HTML)                                           |
+| `image`    | `image`, `caption`, `alt`                                  |
+| `cta`      | `headline`, `subtext`, `button_text`, `button_link`        |
+
+`hero_block`, `text_block`, and `image_block` use the same components.
+
+Asset fields can be an id, a URL, or `{ url }`. Pass the Blocklify origin so ids load from `/api/assets/{id}/file`:
+
+```ts
+import { BlocklifyEntryView, BlocklifyPreview, createStarterBlockMap } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: process.env.BLOCKLIFY_API_URL,
+});
+```
 
-See the in-app guide at `/docs/getting-started#live-preview`.
+Use `blockMap` with `BlocklifyPreview` on `/preview`, and `BlocklifyEntryView` for the public page.

package/dist/index.d.ts

@@ -11,3 +11,4 @@
 export { createBlocklifyClient, type BlocklifyClientConfig, type BlocklifyComponent, type BlocklifyEntry, type BlocklifySiteAsset, type BlocklifySiteSettings, } from "./client.js";
 export { BlocklifyEditable, BlocklifyPreview, BlocklifyPreviewRenderer, BLOCKLIFY_PEER_FOCUS, BLOCKLIFY_PREVIEW_STYLES, BLOCKLIFY_SCROLL_TO_BLOCK, getDataBlokC, PREVIEW_EDITABLE_CSS, useBlocklifyPreview, type BlocklifyBlock, type BlocklifyBlockProps, type BlocklifyPreviewProps, type BlockMap, type DataBlokCPayload, } from "./preview.js";
 export { default } from "./preview.js";
+export { BlocklifyEntryView, blocklifyAssetUrl, createStarterBlockMap, starterBlockMap, type StarterBlockMapOptions, } from "./starter.js";

package/dist/index.js

@@ -11,3 +11,4 @@
 export { createBlocklifyClient, } from "./client.js";
 export { BlocklifyEditable, BlocklifyPreview, BlocklifyPreviewRenderer, BLOCKLIFY_PEER_FOCUS, BLOCKLIFY_PREVIEW_STYLES, BLOCKLIFY_SCROLL_TO_BLOCK, getDataBlokC, PREVIEW_EDITABLE_CSS, useBlocklifyPreview, } from "./preview.js";
 export { default } from "./preview.js";
+export { BlocklifyEntryView, blocklifyAssetUrl, createStarterBlockMap, starterBlockMap, } from "./starter.js";

package/dist/starter.d.ts

@@ -0,0 +1,22 @@
+import type { BlocklifyBlock, BlockMap } from "./preview.js";
+export type StarterBlockMapOptions = {
+    /**
+     * Blocklify origin, no trailing slash.
+     * Used when an asset field is still an id (`/api/assets/{id}/file` is public).
+     */
+    assetBaseUrl?: string;
+};
+/** URL for an asset field: expanded `{ url }`, an absolute/path string, or a bare asset id. */
+export declare function blocklifyAssetUrl(value: unknown, assetBaseUrl?: string): string | null;
+/**
+ * Theme components for a starter Blocklify space: hero, text, image, and cta.
+ * Also registers the `*_block` aliases.
+ */
+export declare function createStarterBlockMap(options?: StarterBlockMapOptions): BlockMap;
+/** Starter map without an asset origin. Expanded `{ url }` fields still render. */
+export declare const starterBlockMap: BlockMap;
+/** Renders an entry body with a block map. Use on the public site, outside the preview iframe. */
+export declare function BlocklifyEntryView({ blocks, blockMap, }: {
+    blocks?: BlocklifyBlock[] | null;
+    blockMap?: BlockMap;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/starter.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+function textOf(block, key) {
+    const value = block[key];
+    return typeof value === "string" ? value : "";
+}
+function absolutize(url, assetBaseUrl) {
+    if (/^https?:\/\//i.test(url) || url.startsWith("data:"))
+        return url;
+    if (url.startsWith("/") && assetBaseUrl) {
+        return `${assetBaseUrl.replace(/\/+$/, "")}${url}`;
+    }
+    return url;
+}
+/** URL for an asset field: expanded `{ url }`, an absolute/path string, or a bare asset id. */
+export function blocklifyAssetUrl(value, assetBaseUrl) {
+    if (value == null || value === "")
+        return null;
+    if (typeof value === "object") {
+        const record = value;
+        if (typeof record.url === "string" && record.url !== "") {
+            return absolutize(record.url, assetBaseUrl);
+        }
+        if (typeof record.id === "string" && record.id !== "") {
+            return blocklifyAssetUrl(record.id, assetBaseUrl);
+        }
+        return null;
+    }
+    if (typeof value !== "string")
+        return null;
+    if (/^https?:\/\//i.test(value) || value.startsWith("/") || value.startsWith("data:")) {
+        return absolutize(value, assetBaseUrl);
+    }
+    if (!assetBaseUrl)
+        return null;
+    return `${assetBaseUrl.replace(/\/+$/, "")}/api/assets/${encodeURIComponent(value)}/file`;
+}
+const sectionStyle = {
+    padding: "4rem 1.5rem",
+    maxWidth: "42rem",
+    margin: "0 auto",
+};
+function HeroBlock({ block, BlocklifyEditable = {}, assetBaseUrl, }) {
+    const headline = textOf(block, "headline");
+    const subheadline = textOf(block, "subheadline");
+    const ctaText = textOf(block, "cta_text");
+    const ctaLink = textOf(block, "cta_link") || "#";
+    const imageSrc = blocklifyAssetUrl(block.image, assetBaseUrl);
+    return (_jsxs("section", { style: { ...sectionStyle, textAlign: "center" }, ...BlocklifyEditable, children: [imageSrc ? (
+            // Themes install this package outside the Blocklify app, so they cannot use its Image component.
+            _jsx("img", { src: imageSrc, alt: textOf(block, "alt") || headline, style: { width: "100%", borderRadius: 12, marginBottom: "1.5rem" } })) : null, headline ? (_jsx("h1", { style: { fontSize: "2.5rem", lineHeight: 1.15, margin: 0 }, children: headline })) : null, subheadline ? (_jsx("p", { style: { marginTop: "1rem", fontSize: "1.125rem", opacity: 0.75 }, children: subheadline })) : null, ctaText ? (_jsx("a", { href: ctaLink, style: {
+                    display: "inline-block",
+                    marginTop: "1.5rem",
+                    padding: "0.75rem 1.5rem",
+                    borderRadius: 999,
+                    background: "#111",
+                    color: "#fff",
+                    textDecoration: "none",
+                    fontSize: "0.875rem",
+                }, children: ctaText })) : null] }));
+}
+function TextBlock({ block, BlocklifyEditable = {} }) {
+    const html = textOf(block, "content") || textOf(block, "text") || textOf(block, "html");
+    return (_jsx("section", { style: sectionStyle, ...BlocklifyEditable, children: html ? (_jsx("div", { dangerouslySetInnerHTML: { __html: html } })) : (_jsx("p", { style: { fontStyle: "italic", opacity: 0.6 }, children: "Empty text block" })) }));
+}
+function ImageBlock({ block, BlocklifyEditable = {}, assetBaseUrl, }) {
+    const src = blocklifyAssetUrl(block.image, assetBaseUrl);
+    const caption = textOf(block, "caption");
+    const alt = textOf(block, "alt") || caption;
+    return (_jsxs("figure", { style: { ...sectionStyle, paddingTop: "1.5rem", paddingBottom: "1.5rem" }, ...BlocklifyEditable, children: [src ? (_jsx("img", { src: src, alt: alt, style: { width: "100%", borderRadius: 12 } })) : (_jsx("div", { style: {
+                    padding: "3rem 1rem",
+                    textAlign: "center",
+                    border: "1px dashed #cbd5e1",
+                    borderRadius: 12,
+                    opacity: 0.7,
+                }, children: "No image selected" })), caption ? (_jsx("figcaption", { style: {
+                    marginTop: "0.5rem",
+                    textAlign: "center",
+                    fontSize: "0.875rem",
+                    opacity: 0.7,
+                }, children: caption })) : null] }));
+}
+function CtaBlock({ block, BlocklifyEditable = {} }) {
+    const headline = textOf(block, "headline");
+    const subtext = textOf(block, "subtext");
+    const buttonText = textOf(block, "button_text");
+    const buttonLink = textOf(block, "button_link") || "#";
+    return (_jsxs("section", { style: { ...sectionStyle, textAlign: "center" }, ...BlocklifyEditable, children: [headline ? _jsx("h2", { style: { fontSize: "1.75rem", margin: 0 }, children: headline }) : null, subtext ? _jsx("p", { style: { marginTop: "0.75rem", opacity: 0.75 }, children: subtext }) : null, buttonText ? (_jsx("a", { href: buttonLink, style: {
+                    display: "inline-block",
+                    marginTop: "1.5rem",
+                    padding: "0.75rem 1.5rem",
+                    borderRadius: 999,
+                    background: "#65a30d",
+                    color: "#fff",
+                    textDecoration: "none",
+                }, children: buttonText })) : null] }));
+}
+function withAssetBase(Component, assetBaseUrl) {
+    function StarterBlock(props) {
+        return _jsx(Component, { ...props, assetBaseUrl: assetBaseUrl });
+    }
+    StarterBlock.displayName = Component.displayName ?? Component.name;
+    return StarterBlock;
+}
+/**
+ * Theme components for a starter Blocklify space: hero, text, image, and cta.
+ * Also registers the `*_block` aliases.
+ */
+export function createStarterBlockMap(options) {
+    const assetBaseUrl = options?.assetBaseUrl;
+    const hero = withAssetBase(HeroBlock, assetBaseUrl);
+    const text = TextBlock;
+    const image = withAssetBase(ImageBlock, assetBaseUrl);
+    const cta = CtaBlock;
+    return {
+        hero,
+        hero_block: hero,
+        text,
+        text_block: text,
+        image,
+        image_block: image,
+        cta,
+    };
+}
+/** Starter map without an asset origin. Expanded `{ url }` fields still render. */
+export const starterBlockMap = createStarterBlockMap();
+function resolveBlock(blockMap, type) {
+    return blockMap[type] ?? (type.endsWith("_block") ? blockMap[type.slice(0, -6)] : undefined);
+}
+/** Renders an entry body with a block map. Use on the public site, outside the preview iframe. */
+export function BlocklifyEntryView({ blocks, blockMap = starterBlockMap, }) {
+    if (!blocks?.length)
+        return null;
+    return (_jsx(_Fragment, { children: blocks.map((block, index) => {
+            const Component = resolveBlock(blockMap, block.type);
+            if (!Component)
+                return null;
+            return (_jsx(Component, { block: block, blockMap: blockMap }, block._uid ?? `${block.type}-${index}`));
+        }) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@blocklify/preview",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "description": "Blocklify frontend SDK: Content API client and live-preview React helpers for theme blocks.",
     "license": "MIT",
     "type": "module",
@@ -19,10 +19,15 @@
         "./preview": {
             "types": "./dist/preview.d.ts",
             "import": "./dist/preview.js"
+        },
+        "./starter": {
+            "types": "./dist/starter.d.ts",
+            "import": "./dist/starter.js"
         }
     },
     "files": [
         "dist",
+        "starter",
         "README.md"
     ],
     "publishConfig": {
@@ -30,8 +35,7 @@
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/BodhiMooij/blocklify.git",
-        "directory": "packages/preview"
+        "url": "git+https://github.com/BodhiMooij/blocklify-preview.git"
     },
     "scripts": {
         "build": "tsc -p tsconfig.json",

package/starter/nextjs/.env.example

@@ -0,0 +1,7 @@
+# Blocklify CMS origin (no trailing slash)
+BLOCKLIFY_API_URL=https://localhost:3000
+# Same origin, exposed to the preview page so asset ids can load in the browser
+NEXT_PUBLIC_BLOCKLIFY_API_URL=https://localhost:3000
+
+# Read token from Admin → Access tokens
+BLOCKLIFY_ACCESS_TOKEN=blocklify_your_token_here

package/starter/nextjs/README.md

@@ -0,0 +1,12 @@
+# Next.js starter files
+
+Copy these into a new App Router app after `bun add @blocklify/preview`.
+
+```bash
+cp -R node_modules/@blocklify/preview/starter/nextjs/app ./app
+cp node_modules/@blocklify/preview/starter/nextjs/.env.example ./.env.local
+```
+
+Then set `BLOCKLIFY_API_URL`, `NEXT_PUBLIC_BLOCKLIFY_API_URL`, and `BLOCKLIFY_ACCESS_TOKEN` in `.env.local`.
+
+Register `http://localhost:3001/preview` under Space → Settings → Live preview URLs, and run this app on port 3001.

package/starter/nextjs/app/page.tsx

@@ -0,0 +1,25 @@
+import {
+    BlocklifyEntryView,
+    createBlocklifyClient,
+    createStarterBlockMap,
+} from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: process.env.BLOCKLIFY_API_URL,
+});
+
+const client = createBlocklifyClient({
+    baseUrl: process.env.BLOCKLIFY_API_URL!,
+    accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
+});
+
+export default async function HomePage() {
+    const entry = await client.getEntry("home");
+    const body = entry?.content.body ?? [];
+
+    return (
+        <main>
+            <BlocklifyEntryView blocks={body} blockMap={blockMap} />
+        </main>
+    );
+}

package/starter/nextjs/app/preview/page.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+import { BlocklifyPreview, createStarterBlockMap } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: process.env.NEXT_PUBLIC_BLOCKLIFY_API_URL,
+});
+
+export default function PreviewPage() {
+    return (
+        <BlocklifyPreview
+            blockMap={blockMap}
+            blocksFieldName="body"
+            emptyMessage="Waiting for content from the Blocklify editor…"
+        />
+    );
+}

package/starter/react/.env.example

@@ -0,0 +1,2 @@
+VITE_BLOCKLIFY_API_URL=https://localhost:3000
+VITE_BLOCKLIFY_ACCESS_TOKEN=blocklify_your_token_here

package/starter/react/README.md

@@ -0,0 +1,13 @@
+# React (Vite) starter files
+
+Copy these into a Vite React app after `bun add @blocklify/preview react-router-dom`.
+
+```bash
+cp node_modules/@blocklify/preview/starter/react/src/App.tsx ./src/App.tsx
+cp node_modules/@blocklify/preview/starter/react/src/main.tsx ./src/main.tsx
+mkdir -p src/pages
+cp node_modules/@blocklify/preview/starter/react/src/pages/PreviewPage.tsx ./src/pages/PreviewPage.tsx
+cp node_modules/@blocklify/preview/starter/react/.env.example ./.env
+```
+
+Register `http://localhost:5173/preview` under Space → Settings → Live preview URLs.

package/starter/react/src/App.tsx

@@ -0,0 +1,36 @@
+import { useEffect, useState } from "react";
+import {
+    BlocklifyEntryView,
+    createBlocklifyClient,
+    createStarterBlockMap,
+} from "@blocklify/preview";
+import type { BlocklifyBlock } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: import.meta.env.VITE_BLOCKLIFY_API_URL,
+});
+
+const client = createBlocklifyClient({
+    baseUrl: import.meta.env.VITE_BLOCKLIFY_API_URL,
+    accessToken: import.meta.env.VITE_BLOCKLIFY_ACCESS_TOKEN,
+});
+
+export default function App() {
+    const [blocks, setBlocks] = useState<BlocklifyBlock[]>([]);
+
+    useEffect(() => {
+        let cancelled = false;
+        client.getEntry("home").then((entry) => {
+            if (!cancelled) setBlocks(entry?.content.body ?? []);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    return (
+        <main>
+            <BlocklifyEntryView blocks={blocks} blockMap={blockMap} />
+        </main>
+    );
+}

package/starter/react/src/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter, Route, Routes } from "react-router-dom";
+import App from "./App";
+import { PreviewPage } from "./pages/PreviewPage";
+
+createRoot(document.getElementById("root")!).render(
+    <StrictMode>
+        <BrowserRouter>
+            <Routes>
+                <Route path="/" element={<App />} />
+                <Route path="/preview" element={<PreviewPage />} />
+            </Routes>
+        </BrowserRouter>
+    </StrictMode>
+);

package/starter/react/src/pages/PreviewPage.tsx

@@ -0,0 +1,15 @@
+import { BlocklifyPreview, createStarterBlockMap } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: import.meta.env.VITE_BLOCKLIFY_API_URL,
+});
+
+export function PreviewPage() {
+    return (
+        <BlocklifyPreview
+            blockMap={blockMap}
+            blocksFieldName="body"
+            emptyMessage="Waiting for content from the Blocklify editor…"
+        />
+    );
+}