@avocadostudio-ai/site-sdk 0.6.0 → 0.7.0

package/dist/lens/lens.test.js

@@ -0,0 +1,221 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { createLens } from "./create-lens.js";
+import { storyblokPrimitives, storyblokLocale } from "./storyblok.js";
+import { sanityPrimitives, sanityLocale } from "./sanity.js";
+// ---------------------------------------------------------------------------
+// Storyblok: a suffixed sibling key per language
+// ---------------------------------------------------------------------------
+const TABLE = {
+    hero_section: {
+        displayName: "Hero",
+        topLevel: true,
+        fields: {
+            title: { kind: "text" },
+            background_image: { kind: "image" },
+            cta_link: { kind: "link" },
+            anchor: { kind: "text", localized: false },
+            buttons: { kind: "list", of: ["button"] }
+        }
+    },
+    button: {
+        displayName: "Button",
+        topLevel: false,
+        fields: {
+            label: { kind: "text" },
+            variant: { kind: "enum", options: ["solid", "outline"] }
+        }
+    }
+};
+const sbLocale = storyblokLocale("de", ["de", "fr"]);
+const sb = createLens({ table: TABLE, locale: sbLocale, primitives: storyblokPrimitives() });
+function story() {
+    return {
+        component: "hero_section",
+        _uid: "u_hero",
+        title: "Willkommen",
+        title__i18n__fr: "Bienvenue",
+        background_image: { fieldtype: "asset", id: 9, filename: "https://a.storyblok.com/f/1/a.jpg", alt: "Halle" },
+        cta_link: { fieldtype: "multilink", linktype: "url", url: "https://book.example.com" },
+        anchor: "top",
+        // Declared by nobody. It has to survive every write below.
+        layout_variant: "wide",
+        buttons: [
+            { component: "button", _uid: "u_b1", label: "Buchen", label__i18n__fr: "Réserver", variant: "solid" },
+            { component: "spacer", _uid: "u_x1", height: 24 }
+        ]
+    };
+}
+test("a field the table does not declare is not projected", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    assert.equal("layout_variant" in props, false);
+    assert.equal(props.title, "Willkommen");
+});
+test("an image projects to two props, a URL and its alt", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    assert.equal(props.background_image, "https://a.storyblok.com/f/1/a.jpg");
+    assert.equal(props.background_image_alt, "Halle");
+});
+test("a language reads its own slot, and falls back to the default when absent", () => {
+    assert.equal(sb.project(story(), "hero_section", "fr").title, "Bienvenue");
+    const noFrench = { ...story(), title__i18n__fr: undefined };
+    assert.equal(sb.project(noFrench, "hero_section", "fr").title, "Willkommen");
+});
+/*
+ * The rule the whole file turns on. French has no value for `anchor` — it is
+ * declared `localized: false` — and no value for the image alt, so the
+ * projection carries German strings sitting in a French page. Merging that
+ * projection back must write none of them: each one would become a real,
+ * fabricated French translation, invisible on screen and permanent in the
+ * document.
+ */
+test("a projection merged straight back changes nothing, in either language", () => {
+    for (const lang of ["de", "fr"]) {
+        const result = sb.roundTrip(story(), "hero_section", lang);
+        assert.equal(result.clean, true, `${lang}: ${result.fields.join(", ")}`);
+    }
+});
+test("a real edit is written into the language being edited, and only there", () => {
+    const props = sb.project(story(), "hero_section", "fr");
+    const { doc, changed } = sb.merge(story(), { ...props, title: "Salut" }, "hero_section", "fr");
+    assert.equal(changed, true);
+    assert.equal(doc.title__i18n__fr, "Salut");
+    assert.equal(doc.title, "Willkommen", "the German value must not move");
+});
+test("a field nobody declared survives a write", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const { doc } = sb.merge(story(), { ...props, title: "Neu" }, "hero_section", "de");
+    assert.equal(doc.layout_variant, "wide");
+});
+test("a non-localised field writes to the bare key whatever page is edited", () => {
+    const props = sb.project(story(), "hero_section", "fr");
+    const { doc } = sb.merge(story(), { ...props, anchor: "hero" }, "hero_section", "fr");
+    assert.equal(doc.anchor, "hero");
+    assert.equal("anchor__i18n__fr" in doc, false);
+});
+/*
+ * A story link is a reference rendered per-locale, so its href cannot be
+ * written back — but an external URL is stored as itself and stays editable,
+ * which is the case that matters (booking and shop links).
+ */
+test("an external link is writable and a story link is refused with a reason", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const external = sb.merge(story(), { ...props, cta_link: "https://shop.example.com" }, "hero_section", "de");
+    assert.equal(external.doc.cta_link.url, "https://shop.example.com");
+    assert.equal(external.warnings.length, 0);
+    const withStoryLink = { ...story(), cta_link: { fieldtype: "multilink", linktype: "story", cached_url: "faq" } };
+    const refused = sb.merge(withStoryLink, { ...sb.project(withStoryLink, "hero_section", "de"), cta_link: "/anything" }, "hero_section", "de");
+    assert.equal(refused.changed, false);
+    assert.match(refused.warnings[0].reason, /points at a page in the CMS/);
+});
+test("a child row is matched by its own id, not by position", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const buttons = props.buttons;
+    assert.equal(buttons.length, 1, "an undeclared child type is not projected");
+    assert.equal(buttons[0]._uid, "u_b1");
+    const reordered = { ...props, buttons: [{ ...buttons[0], label: "Jetzt buchen" }] };
+    const { doc } = sb.merge(story(), reordered, "hero_section", "de");
+    const merged = doc.buttons;
+    assert.equal(merged.find((b) => b._uid === "u_b1").label, "Jetzt buchen");
+});
+/*
+ * A list can hold types the table does not describe, and dropping them is how
+ * an integration deletes content it was never asked about.
+ */
+test("a child row of an undeclared type keeps its place through a list edit", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const buttons = props.buttons;
+    const { doc } = sb.merge(story(), { ...props, buttons: [{ ...buttons[0], label: "X" }] }, "hero_section", "de");
+    const merged = doc.buttons;
+    assert.ok(merged.some((b) => b._uid === "u_x1"), "the spacer must survive");
+});
+test("a value outside a closed list is refused rather than stored", () => {
+    const source = { component: "button", _uid: "u_b1", label: "Buchen", variant: "solid" };
+    const result = sb.merge(source, { label: "Buchen", variant: "ghost" }, "button", "de");
+    assert.equal(result.changed, false);
+    assert.match(result.warnings[0].reason, /not one of solid, outline/);
+});
+// ---------------------------------------------------------------------------
+// Sanity: a per-locale object under the key itself
+// ---------------------------------------------------------------------------
+/*
+ * The same table, the same lens, a CMS that disagrees in every particular — a
+ * per-locale object rather than a suffixed key, a reference rather than a flat
+ * asset, `_key` rather than `_uid`. If anything above `Primitives` had turned
+ * out to be Storyblok-shaped, it would show up here.
+ */
+const SANITY_TABLE = {
+    heroSplit: {
+        displayName: "Hero — split",
+        fields: {
+            heading: { kind: "text" },
+            // Sanity localises only what the schema marks translatable, and an image
+            // is not: it is one asset reference for every language, at the bare key
+            // rather than inside a `{de, fr}` container. Declaring that is the
+            // difference between reading the image and reading nothing.
+            hero: { kind: "image", localized: false },
+            // The list *container* is one array for every language; what is
+            // translated are the fields on its rows. Storyblok and Sanity differ here
+            // and the table is where the difference is stated.
+            buttons: {
+                kind: "list",
+                localized: false,
+                itemFields: { label: { kind: "text" }, variant: { kind: "enum", options: ["solid", "outline"] } }
+            }
+        }
+    }
+};
+const sanity = createLens({
+    table: SANITY_TABLE,
+    locale: sanityLocale("de", ["de", "fr"]),
+    primitives: sanityPrimitives()
+});
+function sanityDoc() {
+    return {
+        _type: "heroSplit",
+        _key: "k_hero",
+        heading: { de: "Willkommen", fr: "Bienvenue" },
+        hero: { _type: "image", asset: { _ref: "image-abc", url: "https://cdn.sanity.io/a.jpg" }, alt: "Halle" },
+        buttons: [{ _key: "k_b1", label: { de: "Buchen", fr: "Réserver" }, variant: "solid" }]
+    };
+}
+test("the same lens reads a per-locale object", () => {
+    assert.equal(sanity.project(sanityDoc(), "heroSplit", "de").heading, "Willkommen");
+    assert.equal(sanity.project(sanityDoc(), "heroSplit", "fr").heading, "Bienvenue");
+});
+test("an image names its props the way the asset picker expects", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "de");
+    assert.equal(props.heroUrl, "https://cdn.sanity.io/a.jpg");
+    assert.equal(props.heroAlt, "Halle");
+});
+test("a Sanity projection merged back changes nothing either", () => {
+    for (const lang of ["de", "fr"]) {
+        const result = sanity.roundTrip(sanityDoc(), "heroSplit", lang);
+        assert.equal(result.clean, true, `${lang}: ${result.fields.join(", ")}`);
+    }
+});
+test("an edit lands in its own locale slot and leaves the other alone", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "fr");
+    const { doc } = sanity.merge(sanityDoc(), { ...props, heading: "Salut" }, "heroSplit", "fr");
+    assert.deepEqual(doc.heading, { de: "Willkommen", fr: "Salut" });
+});
+/*
+ * The URL is a render of `asset._ref`, so writing it back would replace a
+ * reference with a string. The alt text is content and stays editable — the
+ * asymmetry is the point.
+ */
+test("an image's alt is writable and its resolved URL is not", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "de");
+    const { doc } = sanity.merge(sanityDoc(), { ...props, heroAlt: "Die Halle", heroUrl: "https://evil.example/x.jpg" }, "heroSplit", "de");
+    const image = doc.hero;
+    assert.equal(image.alt, "Die Halle");
+    assert.deepEqual(image.asset, { _ref: "image-abc", url: "https://cdn.sanity.io/a.jpg" });
+});
+test("an inline-described row merges by _key", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "de");
+    const buttons = props.buttons;
+    assert.equal(buttons[0]._key, "k_b1");
+    const { doc } = sanity.merge(sanityDoc(), { ...props, buttons: [{ ...buttons[0], label: "Jetzt" }] }, "heroSplit", "de");
+    const merged = doc.buttons;
+    assert.deepEqual(merged[0].label, { de: "Jetzt", fr: "Réserver" });
+});

package/dist/lens/register.d.ts

@@ -0,0 +1,34 @@
+import type { FieldTable, Primitives } from "./types.ts";
+export type RegisterOptions = {
+    /**
+     * The CMS pack, read only for its image prop naming.
+     *
+     * Passing the same object `createLens` gets is what makes the panel and the
+     * projection agree about what an image field's two props are called. Held
+     * apart they are two declarations that must match with nothing checking that
+     * they do — and the symptom is an asset picker that never appears.
+     */
+    primitives?: Pick<Primitives, "imageNaming">;
+    /**
+     * `false` to leave Avocado's own built-in block types in the picker.
+     *
+     * The default narrows the catalogue to the table, because a site that cannot
+     * render `FeatureGrid` should not be offered it — an editor who adds one gets
+     * a block that renders as nothing, and the only trace is a warning in a log.
+     */
+    narrowCatalogue?: boolean;
+};
+/**
+ * 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 declare function registerFieldTable(table: FieldTable, options?: RegisterOptions): void;
+/**
+ * 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 declare function topLevelTypes(table: FieldTable): string[];

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;