@avocadostudio-ai/site-sdk 0.5.1 → 0.7.0

package/dist/lens/register.js

@@ -0,0 +1,148 @@
+/*
+ * The table's other two consumers: the schema an edit is validated against, and
+ * the metadata the property panel draws with.
+ *
+ * Both matter and they answer different questions. Skip the Zod schema and
+ * every AI edit comes back `Unknown block type`. Skip the metadata and every
+ * string gets the same one-line input, because `kind` has no JSON Schema
+ * spelling — a rich-text body is then edited as a headline, and an image field
+ * gets a text box holding a URL.
+ *
+ * Deliberately separate from `createLens`. This writes to a global registry and
+ * `createLens` returns a value; folding a side effect into a constructor makes
+ * an object you cannot build twice, and makes the order of two imports matter.
+ */
+import { registerBlock, declareBlockCatalogue, z } from "@avocadostudio-ai/shared";
+import { suffixNaming } from "./types.js";
+/**
+ * A ProseMirror document, declared so the panel recognises it as one.
+ *
+ * The recogniser keys off `type` being pinned to the literal `"doc"`, which
+ * `z.literal` does survive into JSON Schema as a `const`. `content` is left
+ * unconstrained on purpose: it is somebody else's grammar, and validating it
+ * here would only reject documents the editor round-trips perfectly well.
+ */
+const richTextSchema = () => z.object({
+    type: z.literal("doc"),
+    content: z.array(z.any()).optional()
+});
+function humanise(key) {
+    return key
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/^./, (c) => c.toUpperCase());
+}
+function schemaForField(spec) {
+    switch (spec.kind) {
+        case "richtext":
+            return richTextSchema().optional();
+        case "boolean":
+            return z.boolean().optional();
+        case "number":
+            return z.number().optional();
+        case "enum":
+            // Not `z.enum`: content that predates an option being removed still holds
+            // the old value, and a schema that rejects it makes the block uneditable
+            // in the one surface that can still fix it. The panel offers the declared
+            // options; the merge refuses an undeclared write.
+            return z.string().optional();
+        case "stringList":
+            return z.array(z.string()).optional();
+        case "imageList":
+            return z.array(z.record(z.string(), z.any())).optional();
+        case "list":
+            return z.array(z.record(z.string(), z.any())).optional();
+        default:
+            return z.string().optional();
+    }
+}
+function metaForField(key, spec) {
+    const meta = {
+        kind: spec.kind === "stringList" || spec.kind === "imageList" || spec.kind === "list" ? "text" : spec.kind,
+        label: spec.label ?? humanise(key)
+    };
+    if (spec.internal)
+        meta.internal = true;
+    if (spec.kind === "text" && spec.multiline)
+        meta.multiline = true;
+    if (spec.kind === "text" && spec.inlineEditable !== undefined)
+        meta.inlineEditable = spec.inlineEditable;
+    if (spec.kind === "richtext" && spec.inline)
+        meta.inline = true;
+    if (spec.kind === "enum")
+        meta.options = [...spec.options];
+    if (spec.kind === "image" && spec.imageSpec)
+        meta.imageSpec = spec.imageSpec;
+    return meta;
+}
+/**
+ * Register every type in the table as an Avocado block type.
+ *
+ * Adding a field to a block becomes one line in one file: the schema, the
+ * panel, the projection and the merge all read the same declaration.
+ */
+export function registerFieldTable(table, options) {
+    const naming = options?.primitives?.imageNaming ?? suffixNaming("", "_alt");
+    for (const [type, blockSpec] of Object.entries(table)) {
+        const shape = {};
+        const fields = {};
+        const listFields = {};
+        for (const [key, spec] of Object.entries(blockSpec.fields)) {
+            shape[key] = schemaForField(spec);
+            if (spec.kind === "list" || spec.kind === "imageList") {
+                const itemFields = {};
+                if (spec.kind === "imageList") {
+                    itemFields.image = { kind: "image", label: "Image" };
+                    itemFields.alt = { kind: "imageAlt", label: "Alt text" };
+                }
+                else if ("itemFields" in spec) {
+                    for (const [itemKey, itemSpec] of Object.entries(spec.itemFields)) {
+                        if (itemSpec.kind === "image") {
+                            itemFields[naming.url(itemKey)] = metaForField(itemKey, itemSpec);
+                            itemFields[naming.alt(itemKey)] = { kind: "imageAlt", label: `${itemSpec.label ?? humanise(itemKey)} alt` };
+                            continue;
+                        }
+                        itemFields[itemKey] = metaForField(itemKey, itemSpec);
+                    }
+                }
+                listFields[key] = { label: spec.label ?? humanise(key), itemFields };
+                continue;
+            }
+            if (spec.kind === "image") {
+                // An image is two props, and `key` may not be either of them: a pack
+                // that names them `heroUrl`/`heroAlt` must not also leave a bare `hero`
+                // in the schema, or the panel draws a third control that writes nowhere.
+                delete shape[key];
+                shape[naming.url(key)] = z.string().optional();
+                shape[naming.alt(key)] = z.string().optional();
+                fields[naming.url(key)] = metaForField(key, spec);
+                fields[naming.alt(key)] = { kind: "imageAlt", label: `${spec.label ?? humanise(key)} alt` };
+                continue;
+            }
+            fields[key] = metaForField(key, spec);
+        }
+        const meta = {
+            displayName: blockSpec.displayName,
+            fields,
+            ...(blockSpec.category ? { category: blockSpec.category } : {}),
+            ...(Object.keys(listFields).length > 0 ? { listFields } : {})
+        };
+        registerBlock(type, { schema: z.object(shape), meta });
+    }
+    if (options?.narrowCatalogue !== false) {
+        declareBlockCatalogue(Object.entries(table)
+            .filter(([, spec]) => spec.topLevel !== false)
+            .map(([type]) => type));
+    }
+}
+/**
+ * The types a page body may hold, which is not every type in the table.
+ *
+ * A row type — a card, a button — is declared so the panel can draw it and the
+ * merge can construct it, and must never appear in the block picker.
+ */
+export function topLevelTypes(table) {
+    return Object.entries(table)
+        .filter(([, spec]) => spec.topLevel !== false)
+        .map(([type]) => type);
+}

package/dist/lens/register.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lens/register.test.js

@@ -0,0 +1,81 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { getBlockMeta, blockSchemas, catalogueBlockTypes } from "@avocadostudio-ai/shared";
+import { registerFieldTable } from "./register.js";
+import { storyblokPrimitives } from "./storyblok.js";
+import { sanityPrimitives } from "./sanity.js";
+const TABLE = {
+    lens_hero: {
+        displayName: "Hero",
+        topLevel: true,
+        category: "content",
+        fields: {
+            title: { kind: "text", multiline: true },
+            body: { kind: "richtext" },
+            background: { kind: "image", label: "Background" },
+            alignment: { kind: "enum", options: ["left", "center"] },
+            uid: { kind: "text", internal: true },
+            cards: { kind: "list", itemFields: { heading: { kind: "text" }, photo: { kind: "image" } } }
+        }
+    },
+    lens_card: { displayName: "Card", topLevel: false, fields: { heading: { kind: "text" } } }
+};
+registerFieldTable(TABLE, { primitives: storyblokPrimitives(), narrowCatalogue: false });
+test("every type in the table becomes a registered block type", () => {
+    assert.ok(blockSchemas.lens_hero, "without a schema every AI edit is Unknown block type");
+    assert.equal(getBlockMeta("lens_hero")?.displayName, "Hero");
+    assert.equal(getBlockMeta("lens_hero")?.category, "content");
+});
+/*
+ * `kind` has no JSON Schema spelling, so a table that produced only a schema
+ * would give a rich-text body the same one-line input as a headline.
+ */
+test("the panel metadata carries what the schema cannot say", () => {
+    const fields = getBlockMeta("lens_hero").fields;
+    assert.equal(fields.title.kind, "text");
+    assert.equal(fields.title.multiline, true);
+    assert.equal(fields.body.kind, "richtext");
+    assert.deepEqual(fields.alignment.options, ["left", "center"]);
+});
+test("an internal prop is declared internal rather than left undeclared", () => {
+    assert.equal(getBlockMeta("lens_hero").fields.uid.internal, true);
+});
+/*
+ * The projection and the panel have to agree about what an image field's two
+ * props are called, and the agreement is `imageNaming` on the pack rather than
+ * two constants in two files.
+ */
+test("an image registers the two props its pack projects", () => {
+    const fields = getBlockMeta("lens_hero").fields;
+    assert.equal(fields.background.kind, "image");
+    assert.equal(fields.background_alt.kind, "imageAlt");
+    assert.ok(blockSchemas.lens_hero.shape.background, "the URL prop must be in the schema");
+    assert.ok(blockSchemas.lens_hero.shape.background_alt, "and so must the alt");
+});
+test("a list becomes a list field, with metadata for its rows", () => {
+    const listFields = getBlockMeta("lens_hero").listFields;
+    assert.equal(listFields.cards.itemFields.heading.kind, "text");
+    assert.equal(listFields.cards.itemFields.photo.kind, "image");
+    assert.equal(listFields.cards.itemFields.photo_alt.kind, "imageAlt");
+    assert.equal("cards" in getBlockMeta("lens_hero").fields, false, "a list is not a scalar field");
+});
+test("the other pack names the same image field differently, and the panel follows", () => {
+    registerFieldTable({ sanity_hero: TABLE.lens_hero }, {
+        primitives: sanityPrimitives(),
+        narrowCatalogue: false
+    });
+    const fields = getBlockMeta("sanity_hero").fields;
+    assert.equal(fields.backgroundUrl.kind, "image");
+    assert.equal(fields.backgroundAlt.kind, "imageAlt");
+    assert.equal("background_alt" in fields, false);
+});
+/*
+ * A site that cannot render `FeatureGrid` should not be offered it: an editor
+ * who adds one gets a block that draws as nothing, with a warning in a log as
+ * the only trace.
+ */
+test("the catalogue narrows to the table's top-level types", () => {
+    registerFieldTable(TABLE);
+    const types = catalogueBlockTypes();
+    assert.deepEqual([...types].sort(), ["lens_hero"]);
+});

package/dist/lens/sanity.d.ts

@@ -0,0 +1,28 @@
+import type { ImageNaming, LocaleLens, Primitives } from "./types.ts";
+/**
+ * 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 declare function imageUrl(image: unknown): string;
+export declare function imageAlt(image: unknown): string;
+/**
+ * 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 declare function sanityLocale<L extends string>(defaultLang: L, languages: readonly L[]): LocaleLens<L>;
+/**
+ * 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 declare function sanityPrimitives(options?: {
+    imageNaming?: ImageNaming;
+}): Primitives;

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 };