@craftware/crafty-sdk 0.2.2 → 0.3.0

package/skills/crafty-cms/references/visual-editor.md

@@ -0,0 +1,218 @@
+# Preparing a site for the Crafty visual editor
+
+The visual editor lets a non-technical user open their real site inside the Crafty admin, click (or tap) a text or image, edit it in a side panel, watch the change live, and publish. It only works when the frontend is prepared with `@craftware/crafty-sdk` **0.3.0 or later**. This guide is the complete checklist.
+
+## The mandatory question
+
+Whenever you integrate Crafty into a frontend (a new site, new pages or sections, or moving hardcoded content into Crafty), ask the user this exact question once, before you finish:
+
+> **¿Quieres dejar el sitio preparado para el editor visual de Crafty?**
+
+- **Yes** → run the whole "Yes flow" below.
+- **No** → run the "No flow".
+- If the user later asks "habilita el editor visual de Crafty" (or anything equivalent) for an existing site, do not ask again: run the Yes flow.
+
+## No flow
+
+Add nothing: no `attrs()`, no `enableVisualEditing()`, no preview token handling, no headers, no `configure_visual_editor` call. End your final message with this sentence for the user:
+
+> El editor visual de Crafty no quedó activado. Cuando quieras activarlo, pide: «habilita el editor visual de Crafty».
+
+## Yes flow
+
+Do every step. Keep changes minimal and in the site's existing style.
+
+### 1. Decide the render mode
+
+| `render_mode` | How to recognise it | Token strategy (step 4) |
+|---|---|---|
+| `ssr` | Content is fetched on the server for every request: Next.js dynamic routes / Server Components without static caching, Nuxt SSR, Astro `output: "server"`, Remix loaders, Express/Fastify templates. | Read it per request with `previewFromRequest()`. |
+| `hybrid` | HTML is prerendered at build time **and** the browser fetches Crafty again on load (the Vite + prerender + client refresh pattern). | Automatic in the browser. |
+| `static` | Content is baked at build time only; the browser never calls the Crafty API. | Add a browser re-fetch that only runs in preview. |
+| `unknown` | You cannot tell. | Treat it like `hybrid` and tell the user. |
+
+### 2. Upgrade the SDK
+
+```bash
+npm install @craftware/crafty-sdk@^0.3.0
+```
+
+### 3. Mark every editable element
+
+Use `attrs(target, field, { label })` (also available as `crafty.attrs` on the client). `target` is the block or entry the value came from; `field` is the field key or the JSON path of the value.
+
+Rules:
+
+- Mark only content that comes from Crafty. Never mark hardcoded text.
+- Put the attributes on the innermost element whose **entire text** is the field value (`<h1>`, `<p>`, `<span>`, the `<a>` or `<button>` label, `<li>`). Live preview replaces that element's text, so an element that also contains icons or other fields must not be marked; wrap the value in a `<span>` and mark the span.
+- Images from a media `reference` field: mark the `<img>` with the field key (`image`, `photo`). URL fields (`url`) are edited as text: mark the element that shows or uses them (for a link, mark the `<a>`).
+- Values inside `json` fields: use the exact path of the rendered value, e.g. `sections[2].title`, `hero.title_segments[0].text`, `extra.ctaPrimaryLabel`. Array indexes are positions in the stored JSON, which is the order you render; build them from the loop index (`` `sections[${i}].title` ``).
+- Editable types: `string`, `text`, `longText`, `url`, `number`, media `reference`, and string/number values inside `json`. Do not mark booleans, dates, selects, multi-references, or array items that are objects.
+- `label` is a short Spanish name the client understands ("Título principal", "Texto del botón"). Without it the editor shows the field key.
+- Pass blocks and entries as the API returns them. If an entry has fields named `order`, `data` and `type` at once, pass `{ kind: "entry", id: entry.id }` instead.
+
+React / Next.js / Astro (JSX):
+
+```tsx
+import { attrs } from "@craftware/crafty-sdk";
+
+<h1 {...attrs(block, "title", { label: "Título principal" })}>{block.data.title}</h1>
+<img {...attrs(block, "image", { label: "Imagen principal" })} src={imageUrl} alt="" />
+
+{sections.map((section, i) => (
+  <section key={i}>
+    <h2 {...attrs(entry, `sections[${i}].title`, { label: "Título de la sección" })}>{section.title}</h2>
+    <p {...attrs(entry, `sections[${i}].body`, { label: "Texto de la sección" })}>{section.body}</p>
+  </section>
+))}
+```
+
+Vue:
+
+```vue
+<h1 v-bind="attrs(entry, 'hero.title', { label: 'Título principal' })">{{ entry.hero.title }}</h1>
+```
+
+HTML string templates (vanilla TS):
+
+```ts
+import { attrsHtml } from "@craftware/crafty-sdk";
+
+html += `<h1 ${attrsHtml(entry, "extra.title", { label: "Título" })}>${escapeHtml(extra.title)}</h1>`;
+```
+
+### 4. Deliver the preview token
+
+The editor loads the site with `?crafty_preview=<token>`. Requests that carry it as `X-Crafty-Preview` get unpublished drafts and bypass the API cache.
+
+- **hybrid / SPA:** nothing to do. A client created in the browser reads the token from the URL, keeps it in `sessionStorage`, and sends it on every request. Make sure the browser re-fetch really runs on every page load.
+- **ssr:** create the client **per request** with the token, never share a module-level client that received one, and never cache a preview response:
+
+```ts
+import { createCraftyClient, previewFromRequest } from "@craftware/crafty-sdk";
+
+// Express / Node: previewFromRequest(req)   Web Request: previewFromRequest(request)
+// Next.js App Router: previewFromRequest({ query: await searchParams })
+const preview = previewFromRequest(req);
+const crafty = createCraftyClient({ baseUrl: process.env.CRAFTY_URL!, apiKey: process.env.CRAFTY_API_KEY!, preview });
+
+if (preview) {
+  res.setHeader("Cache-Control", "no-store"); // Next.js: call noStore() / use dynamic rendering for this request
+}
+```
+
+  Server-rendered pages should also tell the editor what they show (step 5, `page` / `entries`).
+- **static:** the built HTML has no drafts, so re-fetch in the browser only when previewing and re-render:
+
+```ts
+import { readPreviewToken } from "@craftware/crafty-sdk";
+
+if (readPreviewToken()) {
+  const fresh = await crafty.entries.list("site-pages");
+  renderPage(fresh.data); // the same function the build uses
+}
+```
+
+  If the site cannot re-render in the browser, set `render_mode` to `static` anyway and tell the user that the editor will show changes only after saving and reloading, and the public site only after a deploy.
+
+### 5. Turn on the bridge
+
+Call it once in the browser entry (it keeps watching the DOM, so it can run before or after the first render):
+
+```ts
+import { enableVisualEditing } from "@craftware/crafty-sdk/visual-editing";
+
+enableVisualEditing({
+  onRefresh: () => reloadCraftyContent(), // re-fetch + re-render; omit it to let the editor reload the page
+});
+```
+
+- It does nothing for normal visitors (it needs the admin iframe, a token, and an allowed admin origin), so ship it to production.
+- Even then it stays inert until the backend confirms the token — a response with `X-Crafty-Preview-Status: active`, normally the site's own first Crafty request for that page. **`ssr` sites where the browser never calls the Crafty API itself must pass `client`** (a `CraftyClient`, typically the same one already created for that render mode) so the bridge can confirm the token itself with one lightweight request (`pages.list({ per_page: 1 })`): `enableVisualEditing({ client: crafty })`. `hybrid` and `static` sites already make a browser-side request that carries the header, so `client` is optional for them. If the API answers `invalid`, the bridge stays off and tells the admin instead of activating.
+- If the site fetches Crafty through something other than this SDK's client (so neither path above ever runs), report `X-Crafty-Preview-Status` yourself with `notifyPreviewActive()` / `notifyPreviewInvalid()` from `@craftware/crafty-sdk/visual-editing` (also exports `getPreviewStatus()` and the `PREVIEW_ACTIVE_EVENT` / `PREVIEW_INVALID_EVENT` event names).
+- `onRefresh`: register it when the site can re-fetch Crafty and re-render without a reload (SPAs, hybrid sites). Otherwise omit it.
+- SSR: pass what the server rendered, e.g. `enableVisualEditing({ client: crafty, page: { id: page.id, slug: page.slug }, entries: [{ id: post.id, collection: "blog" }] })`.
+- `adminOrigins`: only when the tenant's admin is not on `https://<tenant>.crafty.do` (custom admin domain, or local development such as `http://<tenant>.crafty.test`). It replaces the default list.
+- No bundler:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@craftware/crafty-sdk@0.3/dist/crafty-visual-editing.global.js"></script>
+<script>CraftyVisualEditing.enableVisualEditing();</script>
+```
+
+  Pin an exact version (`@0.3.0`) with an `integrity="sha384-…" crossorigin="anonymous"` attribute (jsDelivr shows the hash) when the site uses Subresource Integrity.
+
+### 6. Allow the admin to frame the site
+
+The site must accept being framed by the admin. Sites deployed to Crafty Hosting get this header from Crafty; for any other host add it (and remove any `X-Frame-Options: DENY` / `SAMEORIGIN`):
+
+```
+Content-Security-Policy: frame-ancestors 'self' https://<tenant>.crafty.do
+```
+
+- Netlify / Cloudflare Pages (`_headers` in the build output):
+
+```
+/*
+  Content-Security-Policy: frame-ancestors 'self' https://<tenant>.crafty.do
+```
+
+- Vercel (`vercel.json`):
+
+```json
+{ "headers": [{ "source": "/(.*)", "headers": [{ "key": "Content-Security-Policy", "value": "frame-ancestors 'self' https://<tenant>.crafty.do" }] }] }
+```
+
+- Nginx: `add_header Content-Security-Policy "frame-ancestors 'self' https://<tenant>.crafty.do" always;`
+
+If the site already sends a `Content-Security-Policy`, add the `frame-ancestors` directive to it instead of sending a second header.
+
+### 7. Make sure images come from public repositories
+
+Static and hybrid sites keep image URLs in their HTML; private repositories give expiring URLs. Check with `list_media` (each file has `is_public`) or `crafty.mediaCollections.list()`. If images the site shows live in a private repository, tell the user: «Las imágenes del repositorio X son privadas y sus enlaces caducan en sitios estáticos. Márcalo como público en Crafty → Media.» Uploads made from the visual editor go to the public "Editor visual" repository by default.
+
+### 8. Configure Crafty
+
+Call `configure_visual_editor` (scope `crafty:write`) with what you learned:
+
+```json
+{
+  "site_id": 3,
+  "environment": "production",
+  "frontend_url": "https://www.example.com",
+  "routes": {
+    "page_pattern": "/{slug}",
+    "home_slug": "home",
+    "collections": { "blog": "/blog/{slug}" },
+    "fixed": ["/", "/en", "/blog"]
+  },
+  "render_mode": "hybrid"
+}
+```
+
+- `frontend_url`: the public URL of that environment (omit it when it is the site's domain in production or the Crafty Hosting URL).
+- `routes.page_pattern` / `home_slug`: only if the site renders Crafty **pages**; patterns start with `/` and contain `{slug}`.
+- `routes.collections`: collections whose entries have their own URL; patterns contain `{slug}` or `{id}`.
+- `routes.fixed`: every other URL that shows Crafty content (home in other languages, listing pages, single-page sites: just `["/"]`).
+- `render_mode`: from step 1.
+- Repeat with `environment: "development"` (or others) when they have their own URL.
+- Calling it with only `site_id` returns the current settings without changing anything.
+
+### 9. Verify
+
+1. Build and type-check the site.
+2. Run it locally and open a page with `?crafty_preview=test`. In DevTools:
+   - `document.querySelectorAll("[data-crafty-field]").length` is greater than 0 on every page type (home, a page, a collection entry).
+   - Requests to the Crafty API carry `X-Crafty-Preview: test`, and the responses say `X-Crafty-Preview-Status: invalid` (expected: `test` is not a real token; the content stays public).
+   - Nothing is highlighted: outside the admin iframe the bridge stays off.
+3. After deploying, ask the user to open Crafty → the site → **Editar sitio** (`https://<tenant>.crafty.do/sites/<site_id>/visual-editor?path=/`). If hovering highlights texts and a click opens the field, the editor received `crafty:ready`. If it shows «Este sitio aún no tiene edición con clic activada», go through the troubleshooting list.
+
+End with a short summary for the user in Spanish: what was marked, the render mode, and what they must do after publishing (nothing for `ssr`/`hybrid`; a deploy for `static`).
+
+## Troubleshooting
+
+- **The editor shows «Este sitio aún no tiene edición con clic activada»** — the iframe is blocked (browser console: `frame-ancestors` or `X-Frame-Options`), `enableVisualEditing()` is not in the bundle of that page, the SDK is older than 0.3.0, the admin origin is not allowed (custom admin domain → `adminOrigins`), a redirect dropped the query string (trailing-slash or locale redirects must keep `?crafty_preview=`), or the site is `ssr` and never confirmed the token because `client` was not passed to `enableVisualEditing()`.
+- **«Esta URL no mostró la página …»** — `routes` do not match the site's URLs; fix them with `configure_visual_editor`.
+- **Saved drafts do not appear in the editor** — SSR: the client was created once at module level or the response was cached; static: the preview re-fetch is missing.
+- **Typing does not update the text live** — the attributes are on a wrapper that contains more than the value, or the field is rich text (`longText` shows after saving the draft).
+- **Clicking an editable card navigates away** — the element inside the link is not marked; mark it (a marked element inside a link is selected, not followed).