@avocadostudio-ai/site-sdk 0.6.0 → 0.7.0

package/dist/lens/sanity.js

@@ -0,0 +1,187 @@
+/*
+ * Sanity's answers to the same six questions.
+ *
+ * This pack exists as much to prove the abstraction as to serve Sanity. A codec
+ * interface derived from one CMS is a description of that CMS wearing a general
+ * name; the two that matter here disagree in every particular — a Storyblok
+ * asset is a flat object with a `filename`, a Sanity image is a reference to an
+ * asset document; Storyblok's rich text is the pivot itself, Sanity's is
+ * Portable Text; Storyblok localises into a suffixed sibling key, Sanity into a
+ * per-locale object under the key. Nothing above this file changes between the
+ * two, which is the claim.
+ */
+import { fromPortableText, toPortableText } from "@avocadostudio-ai/richtext";
+import { changed } from "./scalar-codecs.js";
+import { suffixNaming } from "./types.js";
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (v == null ? "" : String(v));
+/**
+ * A resolved image URL, which is a render of a reference and not the reference.
+ *
+ * This is why only the alt text below is writable. The URL a projection carries
+ * was built by the query that resolved `asset._ref` through the CDN; writing it
+ * back replaces a reference to an asset document with a string, which is
+ * precisely the overwrite a field-level publish diff exists to prevent.
+ */
+export function imageUrl(image) {
+    if (!image)
+        return "";
+    if (typeof image === "string")
+        return image;
+    const img = image;
+    if (typeof img.url === "string")
+        return img.url;
+    const asset = isObj(img.asset) ? img.asset : undefined;
+    return str(asset?.url);
+}
+export function imageAlt(image) {
+    return isObj(image) ? str(image.alt) : "";
+}
+/**
+ * An image whose alt text is editable and whose asset is not.
+ *
+ * The asymmetry is deliberate and it is the honest shape: an editor changing
+ * alt text is editing content, and an editor "changing" the URL is proposing to
+ * repoint a reference at something the CMS has no record of.
+ */
+const imageCodec = (naming) => ({
+    project(key, raw) {
+        return { [naming.url(key)]: imageUrl(raw), [naming.alt(key)]: imageAlt(raw) };
+    },
+    merge(key, props, before) {
+        const altKey = naming.alt(key);
+        if (!(altKey in props))
+            return null;
+        const nextAlt = str(props[altKey]);
+        if (!changed(nextAlt, imageAlt(before)))
+            return null;
+        if (!isObj(before))
+            return null;
+        return { value: { ...before, alt: nextAlt } };
+    }
+});
+const fileCodec = {
+    project(key, raw) {
+        return { [key]: imageUrl(raw) };
+    },
+    merge() {
+        return null;
+    }
+};
+/**
+ * A reference, which is what Sanity stores every internal link as.
+ *
+ * Read as the href the query resolved; never written, for the same reason the
+ * image URL is never written — the stored value is a `_ref` and the href is one
+ * rendering of it, per locale.
+ */
+const referenceCodec = {
+    project(key, raw) {
+        if (typeof raw === "string")
+            return { [key]: raw };
+        const ref = isObj(raw) ? raw : undefined;
+        return { [key]: str(ref?.href ?? ref?.slug ?? "") };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const current = typeof before === "string" ? before : str(isObj(before) ? (before.href ?? before.slug) : "");
+        if (str(props[key]) === current)
+            return null;
+        return {
+            warning: `"${key}" points at a document in the CMS, not at a URL. Its address is derived from ` +
+                `that document — move or rename it in Sanity instead.`
+        };
+    },
+    fieldKind: "reference"
+};
+const richTextCodec = {
+    project(key, raw) {
+        return { [key]: fromPortableText(Array.isArray(raw) ? raw : []) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        /*
+         * Key-preserving on purpose. Portable Text blocks carry a `_key` that
+         * Sanity uses to address them, and a converter that mints fresh keys turns
+         * every edit into a full replacement of the array — which is a patch that
+         * conflicts with every other editor's concurrent patch, rather than one
+         * that merges with it.
+         */
+        const nextBlocks = toPortableText(props[key], { previous: Array.isArray(before) ? before : [] });
+        if (JSON.stringify(nextBlocks) === JSON.stringify(before ?? []))
+            return null;
+        const bothEmpty = nextBlocks.length === 0 && (!Array.isArray(before) || before.length === 0);
+        if (bothEmpty)
+            return null;
+        return { value: nextBlocks };
+    }
+};
+const imageListCodec = () => ({
+    project(key, raw) {
+        return {
+            [key]: (Array.isArray(raw) ? raw : []).map((img) => ({
+                image: imageUrl(img),
+                alt: imageAlt(img),
+                _key: isObj(img) ? img._key : undefined
+            }))
+        };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const items = Array.isArray(props[key]) ? props[key] : [];
+        const sourceItems = (Array.isArray(before) ? before : []);
+        const byKey = new Map(sourceItems.filter(isObj).map((row) => [row._key, row]));
+        const merged = items.map((item, i) => {
+            const src = (item._key !== undefined ? byKey.get(item._key) : undefined) ?? sourceItems[i] ?? {};
+            const alt = str(item.alt);
+            if (!isObj(src) || alt === imageAlt(src))
+                return src;
+            return { ...src, alt };
+        });
+        if (JSON.stringify(merged) === JSON.stringify(sourceItems))
+            return null;
+        return { value: merged };
+    }
+});
+/**
+ * The locale lens for a site whose translatable fields are `{de, fr, en}`.
+ *
+ * One Sanity document becomes one Avocado page *per language*, because an
+ * Avocado prop is one value and this content model has three. `/preise` and
+ * `/fr/prix` are two pages backed by the same document.
+ */
+export function sanityLocale(defaultLang, languages) {
+    return {
+        default: defaultLang,
+        languages,
+        path: (key, lang) => [key, lang]
+    };
+}
+/**
+ * The default naming is the one a tri-lingual Sanity site on Next 15 arrived
+ * at, and it is not a style choice: the asset picker recognises a field as an
+ * image by the `*imageUrl` / `*Image` name pattern, so an image field `hero`
+ * has to project to `heroUrl` for the picker to appear at all.
+ */
+export function sanityPrimitives(options) {
+    const imageNaming = options?.imageNaming ?? suffixNaming("Url", "Alt");
+    return {
+        imageNaming,
+        rowIdKey: "_key",
+        rowTypeKey: "_type",
+        newRowId: () => typeof crypto !== "undefined" && "randomUUID" in crypto
+            ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+            : Math.random().toString(36).slice(2, 14),
+        codecs: {
+            image: imageCodec(imageNaming),
+            file: fileCodec,
+            link: referenceCodec,
+            reference: referenceCodec,
+            richtext: richTextCodec,
+            imageList: imageListCodec()
+        }
+    };
+}

package/dist/lens/scalar-codecs.d.ts

@@ -0,0 +1,26 @@
+import type { CodecContext, FieldCodec } from "./types.ts";
+/**
+ * Unchanged is not written, and empty is not written over absent.
+ *
+ * The second rule is the one that is easy to miss and expensive to discover.
+ * Writing `""` into a slot that had no value for this language looks like a
+ * no-op — the page rendered the fallback before and renders it after — and it
+ * is a real diff in the document, so a publish that touched one field reports
+ * every page as modified.
+ */
+export declare function changed(next: unknown, before: unknown): boolean;
+export declare const textCodec: FieldCodec;
+export declare const numberCodec: FieldCodec;
+export declare const booleanCodec: FieldCodec;
+/**
+ * A closed list, and a value outside it is refused rather than stored.
+ *
+ * The panel offers only the declared options, so an out-of-range value can only
+ * arrive from a planner — and storing one produces a page that renders its
+ * fallback branch with no error anywhere, which is the failure this whole file
+ * exists to stop being silent.
+ */
+export declare const enumCodec: FieldCodec;
+export declare const stringListCodec: FieldCodec;
+export declare const SCALAR_CODECS: Record<string, FieldCodec>;
+export type { CodecContext };

package/dist/lens/scalar-codecs.js

@@ -0,0 +1,92 @@
+/*
+ * The kinds no CMS shapes differently.
+ *
+ * A string is a string in Storyblok, Sanity, Contentful and Strapi; so is a
+ * number, a boolean, an enum value and a heading level. These carry no
+ * per-CMS answer, so a primitive pack that supplied them would be four copies
+ * of the same eight lines — and the eighth line, the one that decides whether a
+ * value counts as changed, is the one it is worst to get subtly different
+ * between two integrations.
+ */
+/**
+ * Unchanged is not written, and empty is not written over absent.
+ *
+ * The second rule is the one that is easy to miss and expensive to discover.
+ * Writing `""` into a slot that had no value for this language looks like a
+ * no-op — the page rendered the fallback before and renders it after — and it
+ * is a real diff in the document, so a publish that touched one field reports
+ * every page as modified.
+ */
+export function changed(next, before) {
+    if (next === before)
+        return false;
+    const nextEmpty = next === "" || next === undefined || next === null;
+    const beforeEmpty = before === "" || before === undefined || before === null;
+    return !(nextEmpty && beforeEmpty);
+}
+function scalar(read, write) {
+    return {
+        project(key, raw) {
+            return { [key]: read(raw) };
+        },
+        merge(key, props, before) {
+            if (!(key in props))
+                return null;
+            const next = write(props[key]);
+            return changed(next, read(before)) ? { value: next } : null;
+        }
+    };
+}
+const asText = (raw) => (raw == null ? "" : String(raw));
+export const textCodec = scalar(asText, asText);
+export const numberCodec = scalar((raw) => (typeof raw === "number" ? raw : Number(raw ?? 0) || 0), (next) => (typeof next === "number" ? next : Number(next ?? 0) || 0));
+export const booleanCodec = scalar((raw) => raw === true, (next) => next === true);
+/**
+ * A closed list, and a value outside it is refused rather than stored.
+ *
+ * The panel offers only the declared options, so an out-of-range value can only
+ * arrive from a planner — and storing one produces a page that renders its
+ * fallback branch with no error anywhere, which is the failure this whole file
+ * exists to stop being silent.
+ */
+export const enumCodec = {
+    project(key, raw) {
+        return { [key]: asText(raw) };
+    },
+    merge(key, props, before, ctx) {
+        if (!(key in props))
+            return null;
+        const next = asText(props[key]);
+        if (!changed(next, asText(before)))
+            return null;
+        const options = ctx.spec.kind === "enum" ? ctx.spec.options : [];
+        if (next !== "" && !options.includes(next)) {
+            return { warning: `"${next}" is not one of ${options.join(", ")}` };
+        }
+        return { value: next };
+    }
+};
+export const stringListCodec = {
+    project(key, raw) {
+        return { [key]: (Array.isArray(raw) ? raw : []).map(asText) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const next = (Array.isArray(props[key]) ? props[key] : []).map(asText);
+        const prev = (Array.isArray(before) ? before : []).map(asText);
+        if (next.length === prev.length && next.every((v, i) => v === prev[i]))
+            return null;
+        if (next.length === 0 && prev.length === 0)
+            return null;
+        return { value: next };
+    }
+};
+export const SCALAR_CODECS = {
+    text: textCodec,
+    number: numberCodec,
+    boolean: booleanCodec,
+    enum: enumCodec,
+    headingLevel: textCodec,
+    stringList: stringListCodec
+};

package/dist/lens/storyblok.d.ts

@@ -0,0 +1,28 @@
+import { changed } from "./scalar-codecs.ts";
+import type { ImageNaming, LocaleLens, Primitives } from "./types.ts";
+export declare function assetUrl(asset: unknown): string;
+export declare function assetAlt(asset: unknown): string;
+export declare function linkHref(link: unknown): string;
+/** A link that points at a story is a reference, whatever it renders as. */
+export declare function isStoryLink(link: unknown): boolean;
+/**
+ * The locale lens for Storyblok's field-level i18n.
+ *
+ * The default language lives in the bare key and every other language in
+ * `<key>__i18n__<lang>` beside it. Supplied rather than left to the integrator
+ * because the conditional is one line and getting it wrong is silent: a lens
+ * that reads `title__i18n__de` finds nothing, falls back to `title`, and looks
+ * correct until somebody edits the German page.
+ */
+export declare function storyblokLocale<L extends string>(defaultLang: L, languages: readonly L[]): LocaleLens<L>;
+/**
+ * Storyblok's answers, ready to hand to `createLens` and `registerFieldTable`.
+ *
+ * The default naming is the one a tri-lingual Storyblok site on Next 16
+ * arrived at: an image field `background_image` projects to
+ * `background_image` and `background_image_alt`.
+ */
+export declare function storyblokPrimitives(options?: {
+    imageNaming?: ImageNaming;
+}): Primitives;
+export { changed };

package/dist/lens/storyblok.js

@@ -0,0 +1,232 @@
+/*
+ * Storyblok's answers to the six questions a lens asks.
+ *
+ * Everything here is a fact about Storyblok rather than about a site: an asset
+ * is `{ fieldtype, filename, alt }`, a link is a multilink whose `linktype`
+ * decides whether its href is editable at all, a child row is a blok carrying
+ * `_uid` and `component`, and rich text is a ProseMirror document — the pivot
+ * itself, which is why the converter is a rename rather than a translation.
+ */
+import { fromStoryblok, toStoryblok, isEmptyRichText } from "@avocadostudio-ai/richtext";
+import { changed } from "./scalar-codecs.js";
+import { suffixNaming } from "./types.js";
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (v == null ? "" : String(v));
+export function assetUrl(asset) {
+    if (!asset)
+        return "";
+    if (typeof asset === "string")
+        return asset;
+    return str(asset.filename);
+}
+export function assetAlt(asset) {
+    if (!isObj(asset))
+        return "";
+    return str(asset.alt);
+}
+export function linkHref(link) {
+    if (!link)
+        return "";
+    if (typeof link === "string")
+        return link;
+    const l = link;
+    return str(l.url || l.cached_url || l.href);
+}
+/** A link that points at a story is a reference, whatever it renders as. */
+export function isStoryLink(link) {
+    return isObj(link) && link.linktype === "story";
+}
+/**
+ * An asset object built from a URL, keeping whatever the source knew.
+ *
+ * The id must not be carried over when the URL did not come from Storyblok's
+ * asset service: there is no asset record behind it, and an id pointing at the
+ * image it replaced is worse than no id at all.
+ */
+function assetFrom(url, alt, before) {
+    const base = isObj(before) ? before : {};
+    return {
+        fieldtype: "asset",
+        ...base,
+        id: url.includes("a.storyblok.com") ? (base.id ?? null) : null,
+        filename: url,
+        ...(alt === undefined ? {} : { alt })
+    };
+}
+const imageCodec = (naming) => ({
+    project(key, raw) {
+        return { [naming.url(key)]: assetUrl(raw), [naming.alt(key)]: assetAlt(raw) };
+    },
+    merge(key, props, before) {
+        const urlKey = naming.url(key);
+        const altKey = naming.alt(key);
+        if (!(urlKey in props) && !(altKey in props))
+            return null;
+        const nextUrl = str(props[urlKey] ?? assetUrl(before));
+        const nextAlt = str(props[altKey] ?? assetAlt(before));
+        if (nextUrl === assetUrl(before) && nextAlt === assetAlt(before))
+            return null;
+        // Rule 2: clearing a field that was never set for this language is a diff
+        // with no visible effect. Clearing one that was set is real.
+        if (!nextUrl)
+            return assetUrl(before) ? { value: null } : null;
+        return { value: assetFrom(nextUrl, nextAlt, before) };
+    }
+});
+const fileCodec = {
+    project(key, raw) {
+        return { [key]: assetUrl(raw) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const nextUrl = str(props[key]);
+        if (nextUrl === assetUrl(before))
+            return null;
+        if (!nextUrl && !assetUrl(before))
+            return null;
+        return { value: nextUrl ? assetFrom(nextUrl, undefined, before) : null };
+    }
+};
+/**
+ * A link, and the one shape of it that cannot be written.
+ *
+ * Storyblok stores a story link as `faq` and serves `/fr/faq` on the French
+ * page and `/faq` on the German one — the same stored value, two different
+ * strings, neither of them what is in the document. Flattening it to an href
+ * therefore cannot round-trip: the projection never equals the source, so every
+ * publish of a page nobody edited wants to rewrite every link on it, and
+ * writing the rendered href back replaces the reference with a hard-coded URL
+ * that stops following renames — the one thing the reference was for.
+ *
+ * External links have no such problem, because the stored value *is* the href.
+ * Those stay editable, which covers the case that actually matters: booking and
+ * shop URLs.
+ */
+const linkCodec = {
+    project(key, raw) {
+        return { [key]: linkHref(raw) };
+    },
+    merge(key, props, before, ctx) {
+        if (!(key in props))
+            return null;
+        const nextHref = str(props[key]);
+        if (nextHref === linkHref(before))
+            return null;
+        if (!nextHref && !linkHref(before))
+            return null;
+        if (isStoryLink(before)) {
+            return {
+                warning: `"${key}" points at a page in the CMS, not at a URL. Its address is derived from ` +
+                    `that page and cannot be edited here — move or rename the page in Storyblok instead.`
+            };
+        }
+        const base = isObj(before) ? before : {};
+        return { value: { fieldtype: "multilink", ...base, linktype: "url", url: nextHref, cached_url: nextHref } };
+    },
+    fieldKind: "link"
+};
+/** A reference is never written from a rendered href. It is read-only here. */
+const referenceCodec = {
+    project(key, raw) {
+        return { [key]: linkHref(raw) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        if (str(props[key]) === linkHref(before))
+            return null;
+        return {
+            warning: `"${key}" is a reference to another document. Its address is derived from that ` +
+                `document and cannot be edited here.`
+        };
+    },
+    fieldKind: "reference"
+};
+const richTextCodec = {
+    project(key, raw) {
+        return { [key]: fromStoryblok(raw) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const nextDoc = toStoryblok(props[key]);
+        if (JSON.stringify(nextDoc) === JSON.stringify(before ?? {}))
+            return null;
+        // Two different spellings of "nothing" are not a change.
+        if (isEmptyRichText(nextDoc) && isEmptyRichText(before))
+            return null;
+        return { value: nextDoc };
+    }
+};
+const imageListCodec = {
+    project(key, raw) {
+        return {
+            [key]: (Array.isArray(raw) ? raw : []).map((a) => ({
+                image: assetUrl(a),
+                alt: assetAlt(a),
+                _uid: isObj(a) && a.id != null ? String(a.id) : undefined
+            }))
+        };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const items = Array.isArray(props[key]) ? props[key] : [];
+        const sourceItems = Array.isArray(before) ? before : [];
+        const merged = items.map((item, i) => {
+            const src = sourceItems[i] ?? {};
+            const url = str(item?.image);
+            const alt = str(item?.alt);
+            if (url === assetUrl(src) && alt === assetAlt(src))
+                return src;
+            return assetFrom(url, alt, src);
+        });
+        if (JSON.stringify(merged) === JSON.stringify(sourceItems))
+            return null;
+        return { value: merged };
+    }
+};
+/**
+ * The locale lens for Storyblok's field-level i18n.
+ *
+ * The default language lives in the bare key and every other language in
+ * `<key>__i18n__<lang>` beside it. Supplied rather than left to the integrator
+ * because the conditional is one line and getting it wrong is silent: a lens
+ * that reads `title__i18n__de` finds nothing, falls back to `title`, and looks
+ * correct until somebody edits the German page.
+ */
+export function storyblokLocale(defaultLang, languages) {
+    return {
+        default: defaultLang,
+        languages,
+        path: (key, lang) => (lang === defaultLang ? [key] : [`${key}__i18n__${lang}`])
+    };
+}
+/**
+ * Storyblok's answers, ready to hand to `createLens` and `registerFieldTable`.
+ *
+ * The default naming is the one a tri-lingual Storyblok site on Next 16
+ * arrived at: an image field `background_image` projects to
+ * `background_image` and `background_image_alt`.
+ */
+export function storyblokPrimitives(options) {
+    const imageNaming = options?.imageNaming ?? suffixNaming("", "_alt");
+    return {
+        imageNaming,
+        rowIdKey: "_uid",
+        rowTypeKey: "component",
+        newRowId: () => typeof crypto !== "undefined" && "randomUUID" in crypto
+            ? crypto.randomUUID()
+            : `uid_${Math.random().toString(36).slice(2, 12)}`,
+        codecs: {
+            image: imageCodec(imageNaming),
+            file: fileCodec,
+            link: linkCodec,
+            reference: referenceCodec,
+            richtext: richTextCodec,
+            imageList: imageListCodec
+        }
+    };
+}
+export { changed };