Fix new schema areas in existing documents (Astro) (#5434)

* Fix orphan or new-in-the-schema areas in external front-ends
* Save missing empty areas in the DB, refactor nunjucks path

Author: myovchev

.changeset/ripe-terms-happen.md

@@ -0,0 +1,11 @@
+---
+"@apostrophecms/apostrophe-astro": minor
+"apostrophe": minor
+---
+
+Fixed adding or removing an area field from a schema breaking existing documents on an external front such as Astro.
+
+- `AposArea` now renders only schema-backed areas. A missing area no longer throws, and an area orphaned by removing its field from the schema (while its content remains in the document) renders nothing instead of breaking sibling areas in edit mode. Logged-in editors get a diagnostic message in place of an orphaned area; anonymous visitors see nothing.
+- Editable documents sent to an external front now materialize empty area objects for schema area fields added after the document was created, so they can be edited in context.
+- `apos.util.getManagerOf` accepts a `{ log }` option to suppress its error log when probing objects that may not have a manager.
+

packages/apostrophe-astro/components/AposArea.astro

@@ -13,9 +13,13 @@ const {
 
 let attributes = {};
 
-const widgets = area?.items || [];
+// The backend sets `field` only on areas still in the schema; a missing or
+// orphaned area lacks it and renders nothing.
+const isArea = Boolean(area?.field);
 
-const isEdit = area?._edit && Astro.url.searchParams.get("aposEdit");
+const widgets: Record<string, any>[] = area?.items || [];
+
+const isEdit = isArea && area?._edit && Astro.url.searchParams.get("aposEdit");
 const forceWrapper = aposAttributes || aposStyle || aposClassName;
 
 const WidgetComponent = widgetComponent ?? AposWidget;
@@ -43,39 +47,62 @@ if (isEdit) {
   };
 }
 const Wrapper = isEdit || forceWrapper ? "div" : Fragment;
-const widgetOptions = getWidgetOptions(area.options);
+const widgetOptions = getWidgetOptions(area?.options);
 
-function getWidgetOptions(options) {
-  let widgets = options.widgets || {};
+function getWidgetOptions(options: any = {}) {
+  let widgets = { ...(options.widgets || {}) };
 
   if (options.groups) {
     for (const group of Object.keys(options.groups)) {
       widgets = {
         ...widgets,
-        ...options.groups[group].widgets,
+        ...(options.groups[group]?.widgets || {}),
       };
     }
   }
   return widgets;
 }
 ---
 
-<Wrapper {...attributes}>
-  {
-    widgets?.map((item) => {
-      const options = {
-        ...item._options,
-        ...widgetOptions[item.type],
-      };
-      return (
-        <WidgetComponent
-          widget={item}
-          options={options}
-          area={area}
-          canEdit={isEdit}
-          {...props}
-        />
-      );
-    })
-  }
-</Wrapper>
+{
+  isArea ? (
+    <Wrapper {...attributes}>
+      {widgets.map((item) => {
+        const options = {
+          ...item._options,
+          ...widgetOptions[item.type],
+        };
+        return (
+          <WidgetComponent
+            widget={item}
+            options={options}
+            area={area}
+            canEdit={isEdit}
+            {...props}
+          />
+        );
+      })}
+    </Wrapper>
+  ) : (
+    // Orphaned area. Dev-only diagnostic: `import.meta.env.DEV` is replaced
+    // with `false` in production, so this branch is dead-code eliminated.
+    (import.meta as any).env.DEV &&
+    area?.metaType === "area" && (
+      <div
+        data-apos-area-error
+        role="alert"
+        style="margin:1rem 0;padding:0.75rem 1rem;border:2px solid #dc2626;border-radius:4px;background:#fff1f2;color:#991b1b;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:0.85rem;line-height:1.5;"
+      >
+        <strong>ApostropheCMS:</strong> an area passed to{" "}
+        <code>{"<AposArea />"}</code> is not defined in the schema, so it was
+        not rendered. Its field was likely removed from the schema while content
+        remains in the document. Restore the field in the schema, or remove the
+        matching <code>{"<AposArea />"}</code> from this template.
+        <br />
+        <small>
+          area _id: {area._id} — document: {area._docId}
+        </small>
+      </div>
+    )
+  )
+}

packages/apostrophe/modules/@apostrophecms/area/index.js

@@ -285,6 +285,37 @@ module.exports = {
           self.missingWidgetTypes[name] = true;
         }
       },
+      // Build an empty area and attach it to `parent[name]`. When `parent`
+      // is doc-backed (has `_docId`, or is itself a doc) and `areaDotPath`
+      // is provided, also persist the area at that dot-path. The write is
+      // idempotent via `$eq: null`, so concurrent renders won't clobber each
+      // other. Returns the area.
+      //
+      // Used by the `{% area %}` tag and the external front annotator as a
+      // single source of truth for stubbing schema areas that have no value
+      // yet.
+      async addMissingArea(parent, name, areaDotPath) {
+        const area = {
+          metaType: 'area',
+          _id: self.apos.util.generateId(),
+          items: []
+        };
+        parent[name] = area;
+        const docId = parent._docId ??
+          (parent.metaType === 'doc' ? parent._id : null);
+        if (docId && areaDotPath) {
+          await self.apos.doc.db.updateOne(
+            {
+              _id: docId,
+              [areaDotPath]: { $eq: null }
+            },
+            {
+              $set: { [areaDotPath]: self.apos.util.clonePermanent(area) }
+            }
+          );
+        }
+        return area;
+      },
       prepForRender(area, context, fieldName) {
         const manager = self.apos.util.getManagerOf(context);
         const field = manager.schema.find(field => field.name === fieldName);
@@ -451,7 +482,10 @@ module.exports = {
         // Loop over the docs in the array passed in.
         for (const doc of within) {
           if (self.apos.externalFrontKey) {
-            self.apos.template.annotateDocForExternalFront(doc, { scene: req.scene });
+            await self.apos.template.annotateDocForExternalFront(
+              doc,
+              { scene: req.scene }
+            );
           }
 
           const rendered = [];

packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js

@@ -63,15 +63,10 @@ module.exports = function(self) {
         // has a value, for instance the field could be new in the schema.
         // But we need an area _id. Stub it into the db on the fly
         // without race conditions
-        area = {
-          metaType: 'area',
-          _id: self.apos.util.generateId(),
-          items: []
-        };
-        doc[name] = area;
         const docId = doc._docId || ((doc.metaType === 'doc') ? doc._id : null);
+        let areaDotPath;
         if (docId) {
-          let mainDoc = await self.apos.doc.db.findOne({ _id: docId });
+          const mainDoc = await self.apos.doc.db.findOne({ _id: docId });
           if (!mainDoc) {
             throw self.apos.error('notfound');
           }
@@ -83,21 +78,14 @@ module.exports = function(self) {
             // Unlikely thanks to advisory locking
             throw self.apos.error('notfound');
           }
-          const areaDotPath = docDotPath ? `${docDotPath}.${name}` : name;
-          await self.apos.doc.db.updateOne({
-            _id: docId,
-            // Prevent race condition
-            [areaDotPath]: {
-              $eq: null
-            }
-          }, {
-            $set: {
-              [areaDotPath]: self.apos.util.clonePermanent(area)
-            }
-          });
-          mainDoc = await self.apos.doc.db.findOne({ _id: docId });
-          // Prevent race condition
-          area._id = self.apos.util.get(mainDoc, areaDotPath)._id;
+          areaDotPath = docDotPath ? `${docDotPath}.${name}` : name;
+        }
+        area = await self.apos.area.addMissingArea(doc, name, areaDotPath);
+        if (docId) {
+          // Race-safety: re-read the persisted _id in case another request
+          // wrote first (our $eq: null write was a no-op in that case).
+          const refreshed = await self.apos.doc.db.findOne({ _id: docId });
+          area._id = self.apos.util.get(refreshed, areaDotPath)._id;
         }
       }
       const manager = self.apos.util.getManagerOf(doc);

packages/apostrophe/modules/@apostrophecms/template/index.js

@@ -1231,7 +1231,7 @@ module.exports = {
       async annotateDataForExternalFront(req, template, data, moduleName) {
         const docs = self.getDocsForExternalFront(req, template, data, moduleName);
         for (const doc of docs) {
-          self.annotateDocForExternalFront(doc, { scene: req.scene });
+          await self.annotateDocForExternalFront(doc, { scene: req.scene });
         }
         data.aposBodyData = await self.getBodyData(req);
         // Already contains module name too
@@ -1283,12 +1283,27 @@ module.exports = {
         ].filter(doc => !!doc);
       },
 
-      annotateDocForExternalFront(doc, { scene } = {}) {
-        self.apos.doc.walk(doc, (o, k, v) => {
+      async annotateDocForExternalFront(doc, { scene } = {}) {
+        const handled = new WeakSet();
+        const missingAreas = [];
+        self.apos.doc.walk(doc, (o, k, v, __dotPath) => {
+          if (o._edit === true && !handled.has(o)) {
+            handled.add(o);
+            // `__dotPath` is the path to `v` (= o[k]); the container `o` lives
+            // one segment up — '' for the top-level doc.
+            const dot = __dotPath.lastIndexOf('.');
+            const containerDotPath = dot === -1 ? '' : __dotPath.substring(0, dot);
+            for (const field of self.missingSchemaAreas(o)) {
+              missingAreas.push([ o, field, containerDotPath ]);
+            }
+          }
           if (v && v.metaType === 'area') {
             const manager = self.apos.util.getManagerOf(o);
             if (!manager) {
-              self.apos.util.warnDevOnce('noManagerForDocInExternalFront', `No manager for: ${o.metaType} ${o.type || ''}`);
+              self.apos.util.warnDevOnce(
+                'noManagerForDocInExternalFront',
+                `No manager for: ${o.metaType} ${o.type || ''}`
+              );
               return;
             }
             const field = manager.schema.find(f => f.name === k);
@@ -1302,6 +1317,21 @@ module.exports = {
             return self.annotateAreaForExternalFront(field, v, { scene });
           }
         });
+        // Materialize every missing area, after the walk so we never add keys
+        // to an object while it is being traversed.
+        for (const [ o, field, containerDotPath ] of missingAreas) {
+          const areaDotPath = containerDotPath
+            ? `${containerDotPath}.${field.name}`
+            : field.name;
+          const area = await self.apos.area.addMissingArea(
+            o,
+            field.name,
+            areaDotPath
+          );
+          area._edit = true;
+          area._docId = o._docId ?? (o.metaType === 'doc' ? o._id : null);
+          self.annotateAreaForExternalFront(field, area, { scene });
+        }
       },
 
       // Annotate an area for easy rendering by an external front end
@@ -1343,6 +1373,13 @@ module.exports = {
             throw self.apos.error('invalid', 'Missing widget type');
           }
         }
+      },
+
+      // The schema area fields of `object` that have no value yet. Returns an
+      // empty array for anything without a schema manager.
+      missingSchemaAreas(object) {
+        const schema = self.apos.util.getManagerOf(object, { log: false })?.schema ?? [];
+        return schema.filter(field => field.type === 'area' && !object[field.name]);
       }
     };
   }

packages/apostrophe/modules/@apostrophecms/util/index.js

@@ -724,7 +724,7 @@ module.exports = {
       },
       // Given a widget or doc, return the appropriate manager module. If the manager
       // cannot be determined for any reason, undefined is returned.
-      getManagerOf(object) {
+      getManagerOf(object, { log = true } = {}) {
         if (object.metaType === 'doc') {
           return self.apos.doc.getManager(object.type);
         } else if (object.metaType === 'widget') {
@@ -733,10 +733,10 @@ module.exports = {
           return self.apos.schema.getArrayManager(object.scopedArrayName);
         } else if (object.metaType === 'object') {
           return self.apos.schema.getObjectManager(object.scopedObjectName);
-        } else {
+        } else if (log) {
           self.apos.util.error(`Unsupported metaType in getManagerOf: ${object.metaType}`);
-          return undefined;
         }
+        return undefined;
       },
       // fetch the value at the given path from the object or
       // array `o`. `path` supports dot notation like MongoDB, and