@avocadostudio-ai/shared 0.2.1 → 0.3.0

package/dist/blocks/_registry.d.ts

@@ -97,10 +97,8 @@ export type BlockRegistration = {
     schema: z.ZodObject<any>;
     meta: BlockMeta;
 };
-/**
- * Register a block type. Can be called at module load time.
- * Re-registering the same type overwrites the previous registration.
- */
+/** Test seam: forget what has already been warned about. */
+export declare function resetListFieldWarnings(): void;
 export declare function registerBlock(type: string, config: BlockRegistration): void;
 /** Get metadata for a registered block type, or undefined. */
 export declare function getBlockMeta(type: string): BlockMeta | undefined;

package/dist/blocks/_registry.js

@@ -23,6 +23,74 @@ const _blockMeta = G.__ase_blockMeta ?? (G.__ase_blockMeta = {});
  * Register a block type. Can be called at module load time.
  * Re-registering the same type overwrites the previous registration.
  */
+/*
+ * `meta.listFields` and the props schema are two halves of one declaration, and
+ * only the schema is load-bearing: the property panel renders rows from the
+ * schema's array, and `listFields` only says how to label them. So a list named
+ * in the meta and missing from the schema produces no rows, no Add control, and
+ * no error — the one outcome that carries no information.
+ *
+ * That is not hypothetical. An integration declared six accordion items, four
+ * contact rows, a price table's tiers and every block's buttons this way, and
+ * the whole run passed: validation succeeded, operations applied, the preview
+ * rendered, the publisher diffed the rows correctly. The only symptom was an
+ * absence in one panel — and it was invisible precisely because the block's
+ * schema carried `.catchall(z.unknown())`, which every CMS integration needs
+ * because our own publish guidance tells it to stash a `__source` snapshot in
+ * block props. The catchall swallowed the undeclared arrays as extras.
+ *
+ * The loop below was already standing on the contradiction: it walks
+ * `listFields` against the schema to derive `required`, finds no array, and
+ * steps over it. This is that step, saying so.
+ *
+ * A warning rather than a throw: `registerBlocks` re-runs on every `/blocks`
+ * request, and a registry that can fail a request is worse than a panel with a
+ * missing list. Deduped for the same reason.
+ */
+/**
+ * Strip the wrappers that make a schema optional, so the shape underneath can be
+ * inspected. `z.array(z.object({…})).optional()` is a `ZodOptional` holding the
+ * array, and reaching for `.element` on the wrapper finds nothing.
+ *
+ * Follows `def.innerType`, which is what `ZodOptional`, `ZodDefault` and
+ * `ZodNullable` carry, and deliberately **not** `.unwrap()`: in Zod 4 an array
+ * has that method too and it returns the array's *element*, so a generic
+ * unwrapper walks `ZodOptional → ZodArray → ZodObject` and lands one step past
+ * the array it was looking for.
+ */
+function unwrapZod(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 5 && current; depth += 1) {
+        const inner = current.def?.innerType ?? current._def?.innerType;
+        if (!inner)
+            return current;
+        current = inner;
+    }
+    return current;
+}
+const warnedListFields = new Set();
+function warnUnbackedListField(type, listKey, present) {
+    const key = `${type}.${listKey}`;
+    if (warnedListFields.has(key))
+        return;
+    warnedListFields.add(key);
+    const because = present
+        ? `the schema's \`${listKey}\` is not an array of objects`
+        : `the schema has no \`${listKey}\``;
+    try {
+        console.warn(`[avocado] ${type}: meta.listFields declares "${listKey}" but ${because}. ` +
+            `The property panel renders list rows from the schema, so this list will show ` +
+            `no rows and no Add control. Declare it alongside the meta, e.g. ` +
+            `${listKey}: z.array(z.object({ … })).optional()`);
+    }
+    catch {
+        // A host with no console is not a reason to fail a registration.
+    }
+}
+/** Test seam: forget what has already been warned about. */
+export function resetListFieldWarnings() {
+    warnedListFields.clear();
+}
 export function registerBlock(type, config) {
     _blockSchemas[type] = config.schema;
     // Auto-derive `required` on each FieldMeta from the Zod schema shape
@@ -40,10 +108,15 @@ export function registerBlock(type, config) {
         if (config.meta.listFields) {
             for (const [listKey, listMeta] of Object.entries(config.meta.listFields)) {
                 const listZod = shape[listKey];
-                // Unwrap ZodArray → element (ZodObject)
-                const elementShape = listZod?.element?.shape;
-                if (!elementShape)
+                // Unwrap ZodOptional / ZodDefault / ZodNullable → ZodArray → element.
+                // Without the outer unwrap, `z.array(...).optional()` — which is how a
+                // list should be declared — looked like no array at all, so every
+                // optional list silently skipped its own `required` derivation.
+                const elementShape = unwrapZod(listZod)?.element?.shape;
+                if (!elementShape) {
+                    warnUnbackedListField(type, listKey, listZod !== undefined);
                     continue;
+                }
                 for (const [itemKey, itemField] of Object.entries(listMeta.itemFields)) {
                     if (itemField.required !== undefined)
                         continue;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.ts";
 export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText, isRichTextDoc, fromMarkdown, toMarkdown, mergeRichTextDoc, NODE, MARK, type InlineToken, type RichTextBlock, type RichTextList, type RichTextListItem, type RichTextDoc, type RichTextNode, type RichTextMark } from "@avocadostudio-ai/richtext";
 export { blockDefinitionSchema, blockManifestSchema, buildBlockManifest, jsonSchemaLikeSchema, validateByJsonSchemaLike, findManifestSchemaIssue, type ManifestSchemaIssue, validateManifestDefaultProps, deriveFieldMetaFromSchema, resolveManifestFieldMeta, isProseMirrorDocSchema, type BlockDefinition, type BlockManifest } from "./block-manifest.ts";
 export { z } from "zod";
-export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
+export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
 export { defaultPropsForType, declaredDefaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.ts";
 export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.ts";
 export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, type AddBlockOp, type MakeAddBlockOptions, type AddItemOp, type MakeAddItemOptions, } from "./ops/builders.ts";

package/dist/index.js

@@ -33,7 +33,7 @@ export {
 // Constants & helpers
 IMAGE_PLACEHOLDER, isImagePlaceholder, 
 // Registry functions
-registerBlock, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
+registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
 // Backwards-compatible exports
 blockSchemas, allowedBlockTypes, 
 // The catalogue a site actually renders — see `declareBlockCatalogue`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,13 +19,23 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/richtext": "0.2.1"
+    "@avocadostudio-ai/richtext": "^0.3.0"
   },
   "devDependencies": {
     "tsx": "^4.21.0",
     "typescript": "^5.7.3"
   },
   "description": "Shared Zod schemas, block registry, and operation types for Avocado Studio",
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "cms",
+    "blocks",
+    "zod",
+    "schema",
+    "page-builder",
+    "visual-editing"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/shared#readme",
   "bugs": {