@avocadostudio-ai/shared 0.4.0 → 0.5.1

package/dist/panel-coverage.js

@@ -0,0 +1,395 @@
+/**
+ * Can a human actually edit this site in the property panel?
+ *
+ * `editableCoverage` answers the same question for the *preview*: which fields
+ * carry a marker the overlay can find. This is the panel's half, and it was the
+ * half with no check at all — which is why a real integration shipped a panel
+ * whose list rows read `Item 4`, `Item 5`, whose labels came from somebody
+ * else's block, and whose polymorphic branches were never narrowed. Every one of
+ * those was visible in the data the whole time. Nobody was asking.
+ *
+ * The check needs no browser, no screenshot and no model. It has the manifest
+ * (what the panel will render) and the site's own pages (what the rows really
+ * contain), and every finding below is a disagreement between the two.
+ *
+ * It resolves metadata through `resolveEditorBlockMeta` and rows through
+ * `resolveListItemFields` — the same functions the panel itself uses — so its
+ * findings are the panel's behaviour rather than a model of it. A checker that
+ * approximates the panel reports gaps the panel does not have and misses the
+ * ones it does, and gets switched off within a week.
+ *
+ * Pass `builtinTypes` (the registry the *editor* will run with) to get the
+ * collision findings. Without it, collisions are simply not reported — an
+ * absent input is never evidence.
+ */
+import { resolveEditorBlockMeta, resolveListItemFields } from "./editor-block-meta.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasContent(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "string")
+        return value.trim() !== "";
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+/**
+ * The label the panel puts on a collapsed list row.
+ *
+ * Mirrors `PropertyPanel`'s own derivation exactly, including its fallbacks: the
+ * first text-ish field with a value, else that image's alt text, else the
+ * filename of the first image, else `Item N`. Kept here so the two cannot drift
+ * — the panel imports this.
+ *
+ * "With a value" is load-bearing and was, for a while, only true of the comment.
+ * The code took the first *declared* candidate and read whatever it held, so a
+ * field set listing an empty `title` ahead of a populated `text` labelled the row
+ * `Item 4` with the answer sitting one key further along. Each step below scans
+ * for content instead of stopping at the first key of the right kind.
+ *
+ * Alt text outranks the filename because it is the only one of the two a person
+ * wrote on purpose. A column of `20250904_075546.webp`, `20250904_081233.webp`
+ * tells a reader which row is which no better than `Item 4` did, while the alt
+ * beside it already says "Pool bei Sonnenuntergang". The first version of this
+ * ranked the filename higher and the check then reported the mismatch as a
+ * finding — which told a site its alt text was the better label while the panel
+ * had no way to use it. A finding with no remedy gets switched off.
+ */
+export function deriveRowLabel(fields, item, index, options) {
+    const candidates = Object.keys(fields).filter((k) => k !== options?.discriminator);
+    for (const key of candidates) {
+        if (fields[key].kind !== "text" && fields[key].kind !== "richtext")
+            continue;
+        const text = firstText(item[key]);
+        if (text !== "")
+            return { label: text, source: "text" };
+    }
+    for (const key of candidates) {
+        if (fields[key].kind !== "imageAlt")
+            continue;
+        const alt = firstText(item[key]);
+        if (alt !== "")
+            return { label: alt, source: "alt" };
+    }
+    for (const key of candidates) {
+        if (fields[key].kind !== "image")
+            continue;
+        const src = imageSrcOf(item[key]);
+        if (src === "")
+            continue;
+        const name = src.split("?")[0].split("/").filter(Boolean).pop() ?? src;
+        return { label: name, source: "filename" };
+    }
+    return { label: `Item ${index + 1}`, source: "fallback" };
+}
+/**
+ * The first run of readable text in a value, whatever shape the value is in.
+ *
+ * A `richtext` field is only sometimes a string. Storyblok hands over a
+ * ProseMirror document, Sanity a Portable Text array, Contentful its own node
+ * tree — and `String(…)` of any of them is `"[object Object]"`, which is neither
+ * empty nor a label. This used to call exactly that, so a site whose rows carry
+ * nothing but rich text was told 48 of them could not be labelled, in a message
+ * that names `richtext` among the kinds it accepts. Every one of those rows
+ * opened with a heading.
+ *
+ * `text` covers ProseMirror and Strapi text nodes, `value` covers Contentful's;
+ * `content` and `children` are the two spellings of "the nodes below this one".
+ * `label` and `title` are for the other object a text-ish field turns out to
+ * hold: a row of CTAs, whose value is `[{ label, href }]`. That one used to
+ * stringify to `"[object Object]"`, which is not empty, so the row counted as
+ * labelled and the panel printed it.
+ */
+function firstText(value, depth = 0) {
+    if (depth > 8)
+        return "";
+    if (typeof value === "string")
+        return collapseWhitespace(value);
+    if (typeof value === "number")
+        return String(value);
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const found = firstText(entry, depth + 1);
+            if (found !== "")
+                return found;
+        }
+        return "";
+    }
+    if (!isRecord(value))
+        return "";
+    for (const key of ["text", "value", "label", "title"]) {
+        const direct = value[key];
+        if (typeof direct === "string") {
+            const collapsed = collapseWhitespace(direct);
+            if (collapsed !== "")
+                return collapsed;
+        }
+    }
+    for (const key of ["content", "children"]) {
+        const found = firstText(value[key], depth + 1);
+        if (found !== "")
+            return found;
+    }
+    return "";
+}
+/** An image field holds a URL string, or an asset object that has one inside. */
+function imageSrcOf(value) {
+    if (typeof value === "string")
+        return value.trim();
+    if (!isRecord(value))
+        return "";
+    for (const key of ["url", "src", "filename"]) {
+        const candidate = value[key];
+        if (typeof candidate === "string" && candidate.trim() !== "")
+            return candidate.trim();
+    }
+    return "";
+}
+function collapseWhitespace(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+/** Does the registry's version of this type describe a different block? */
+function collisionDetail(definition, registryMeta) {
+    const schemaProps = isRecord(definition.propsSchema.properties)
+        ? new Set(Object.keys(definition.propsSchema.properties))
+        : new Set();
+    const registryProps = new Set([
+        ...Object.keys(registryMeta.fields),
+        ...Object.keys(registryMeta.listFields ?? {})
+    ]);
+    const onlySite = [...schemaProps].filter((p) => !registryProps.has(p));
+    const onlyRegistry = [...registryProps].filter((p) => !schemaProps.has(p));
+    if (onlySite.length === 0 && onlyRegistry.length === 0)
+        return null;
+    const parts = [];
+    if (onlySite.length > 0)
+        parts.push(`only in yours: ${onlySite.join(", ")}`);
+    if (onlyRegistry.length > 0)
+        parts.push(`only in the built-in: ${onlyRegistry.join(", ")}`);
+    return parts.join("; ");
+}
+export function panelCoverage(manifest, pages, options) {
+    const definitions = new Map(manifest.blocks.map((b) => [b.type, b]));
+    const builtins = options?.builtinTypes;
+    const unknownBlockTypes = new Set();
+    /*
+     * Findings are aggregated by (code, blockType, path). A missing row label is a
+     * property of the component, not of the one row that happened to render first
+     * — and a report with forty rows of the same sentence is a report nobody
+     * finishes reading.
+     */
+    const byKey = new Map();
+    const note = (f) => {
+        const key = `${f.code}\u0000${f.blockType}\u0000${f.path ?? ""}`;
+        const existing = byKey.get(key);
+        if (existing) {
+            existing.count += 1;
+            return;
+        }
+        byKey.set(key, { ...f, count: 1 });
+    };
+    // ── static checks, once per declared type ──────────────────────────────
+    for (const definition of manifest.blocks) {
+        const registryMeta = builtins?.[definition.type];
+        if (registryMeta) {
+            const detail = collisionDetail(definition, registryMeta);
+            if (detail) {
+                note({
+                    code: "colliding_type",
+                    blockType: definition.type,
+                    detail: `the editor also ships a built-in "${definition.type}" with a different shape (${detail}). ` +
+                        `Anything your manifest does not declare explicitly is taken from the built-in.`
+                });
+            }
+        }
+        const meta = resolveEditorBlockMeta(definition, registryMeta);
+        for (const [listKey, listField] of Object.entries(meta.listFields ?? {})) {
+            const hasDiscriminator = Boolean(listField.discriminator);
+            const hasBranches = Object.keys(listField.itemFieldsByType ?? {}).length > 0;
+            if (hasDiscriminator !== hasBranches) {
+                note({
+                    code: "incomplete_polymorphism",
+                    blockType: definition.type,
+                    path: listKey,
+                    detail: hasDiscriminator
+                        ? `declares discriminator "${listField.discriminator}" and no itemFieldsByType, so nothing narrows`
+                        : `declares itemFieldsByType and no discriminator, so no branch is ever selected`
+                });
+            }
+        }
+    }
+    // ── content-driven checks ──────────────────────────────────────────────
+    let rowsExamined = 0;
+    let rowsLabelled = 0;
+    /** Item field keys a branch declared, against keys any row of that branch actually had. */
+    const seenItemKeys = new Map();
+    const declaredItemKeys = new Map();
+    for (const page of pages) {
+        const slug = page.slug ?? "(unknown)";
+        for (const block of page.blocks ?? []) {
+            if (!block?.type)
+                continue;
+            const definition = definitions.get(block.type);
+            if (!definition) {
+                unknownBlockTypes.add(block.type);
+                continue;
+            }
+            const meta = resolveEditorBlockMeta(definition, builtins?.[block.type]);
+            const props = isRecord(block.props) ? block.props : {};
+            const listFields = meta.listFields ?? {};
+            for (const [propKey, value] of Object.entries(props)) {
+                if (!hasContent(value))
+                    continue;
+                // `id` and `_key`-style identity keys are never panel content.
+                if (propKey === "id" || propKey === "_key" || propKey === "_type")
+                    continue;
+                if (propKey in meta.fields || propKey in listFields)
+                    continue;
+                note({
+                    code: "orphan_prop",
+                    blockType: block.type,
+                    path: propKey,
+                    exampleSlug: slug,
+                    detail: `held in content, described by neither fields nor listFields — the panel cannot show or edit it`
+                });
+            }
+            for (const [listKey, listField] of Object.entries(listFields)) {
+                const items = props[listKey];
+                if (!Array.isArray(items))
+                    continue;
+                for (const [index, raw] of items.entries()) {
+                    if (!isRecord(raw))
+                        continue;
+                    rowsExamined += 1;
+                    const { fields, discriminantValue, matchedBranch } = resolveListItemFields(listField, raw);
+                    if (listField.discriminator && discriminantValue !== "" && !matchedBranch) {
+                        note({
+                            code: "unmatched_branch",
+                            blockType: block.type,
+                            path: `${listKey}[].${listField.discriminator}=${discriminantValue}`,
+                            exampleSlug: slug,
+                            detail: `no itemFieldsByType entry for "${discriminantValue}", so this row is edited against ` +
+                                `the union of every branch`
+                        });
+                    }
+                    const { source } = deriveRowLabel(fields, raw, index, {
+                        ...(listField.discriminator ? { discriminator: listField.discriminator } : {})
+                    });
+                    if (source === "fallback") {
+                        note({
+                            code: "unlabelled_row",
+                            blockType: block.type,
+                            path: `${listKey}[]${discriminantValue ? `.${listField.discriminator}=${discriminantValue}` : ""}`,
+                            exampleSlug: slug,
+                            detail: `the panel labels this row "Item N" — no text, rich text, alt text or image field on it ` +
+                                `holds a value, so a person scanning the list cannot tell which row is which`
+                        });
+                    }
+                    else {
+                        rowsLabelled += 1;
+                        if (source === "filename") {
+                            /*
+                             * The row fell through to a filename, which means its alt is
+                             * empty — `deriveRowLabel` would have used it otherwise. So this
+                             * is one finding covering two costs: the panel row is named after
+                             * a camera, and the image ships to readers with no description.
+                             * Both are fixed by the same edit.
+                             */
+                            const altKey = Object.keys(fields).find((k) => fields[k].kind === "imageAlt");
+                            if (altKey && !hasContent(raw[altKey])) {
+                                note({
+                                    code: "filename_row_label",
+                                    blockType: block.type,
+                                    path: `${listKey}[].${altKey}`,
+                                    exampleSlug: slug,
+                                    detail: `labelled by image filename because "${altKey}" is empty — writing the alt text ` +
+                                        `names the row and describes the image to a screen reader in one edit`
+                                });
+                            }
+                        }
+                    }
+                    const branchKey = `${block.type}\u0000${listKey}\u0000${discriminantValue}`;
+                    let declared = declaredItemKeys.get(branchKey);
+                    if (!declared)
+                        declaredItemKeys.set(branchKey, (declared = new Set(Object.keys(fields))));
+                    let seen = seenItemKeys.get(branchKey);
+                    if (!seen)
+                        seenItemKeys.set(branchKey, (seen = new Set()));
+                    for (const [itemKey, itemValue] of Object.entries(raw)) {
+                        if (itemKey === "id" || itemKey === "_key" || itemKey === listField.discriminator)
+                            continue;
+                        if (!hasContent(itemValue))
+                            continue;
+                        seen.add(itemKey);
+                        if (!(itemKey in fields)) {
+                            note({
+                                code: "orphan_prop",
+                                blockType: block.type,
+                                path: `${listKey}[]${discriminantValue ? `.${listField.discriminator}=${discriminantValue}` : ""}.${itemKey}`,
+                                exampleSlug: slug,
+                                detail: `held in content, described by no field on this row's field set`
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    for (const [branchKey, declared] of declaredItemKeys) {
+        const seen = seenItemKeys.get(branchKey) ?? new Set();
+        const [blockType, listKey, discriminantValue] = branchKey.split("\u0000");
+        const never = [...declared].filter((k) => !seen.has(k));
+        if (never.length === 0)
+            continue;
+        note({
+            code: "phantom_field",
+            blockType,
+            path: `${listKey}[]${discriminantValue ? `.${discriminantValue}` : ""}`,
+            detail: `declared for these rows and never present in one: ${never.join(", ")}`
+        });
+    }
+    /*
+     * Most-actionable first. A colliding type explains several of the rows below
+     * it, so reading in this order means fixing one cause rather than six
+     * symptoms.
+     */
+    const order = [
+        "colliding_type",
+        "incomplete_polymorphism",
+        "unmatched_branch",
+        "unlabelled_row",
+        "orphan_prop",
+        "filename_row_label",
+        "phantom_field"
+    ];
+    const findings = [...byKey.values()].sort((a, b) => order.indexOf(a.code) - order.indexOf(b.code) ||
+        a.blockType.localeCompare(b.blockType) ||
+        (a.path ?? "").localeCompare(b.path ?? ""));
+    return { rowsExamined, rowsLabelled, findings, unknownBlockTypes: [...unknownBlockTypes] };
+}
+/** A human-readable report, in the shape `formatEditableCoverage` uses. */
+export function formatPanelCoverage(report) {
+    const pct = report.rowsExamined === 0 ? 100 : Math.round((report.rowsLabelled / report.rowsExamined) * 100);
+    const lines = [`list rows the panel can label: ${report.rowsLabelled}/${report.rowsExamined} (${pct}%)`];
+    if (report.findings.length === 0 && report.unknownBlockTypes.length === 0) {
+        lines.push("no editing-surface findings");
+        return lines.join("\n");
+    }
+    let lastCode = null;
+    for (const finding of report.findings) {
+        if (finding.code !== lastCode) {
+            lines.push("", `${finding.code}:`);
+            lastCode = finding.code;
+        }
+        const where = finding.path ? `${finding.blockType}.${finding.path}` : finding.blockType;
+        const times = finding.count > 1 ? ` ×${finding.count}` : "";
+        const on = finding.exampleSlug ? ` (e.g. ${finding.exampleSlug})` : "";
+        lines.push(`  ${where}${times}${on} — ${finding.detail}`);
+    }
+    if (report.unknownBlockTypes.length > 0) {
+        lines.push("", `block types on a page with no manifest entry: ${report.unknownBlockTypes.join(", ")}`);
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/richtext": "^0.4.0"
+    "@avocadostudio-ai/richtext": "^0.5.1"
   },
   "devDependencies": {
     "tsx": "^4.21.0",