@amplifyup/sdk 0.1.63 → 0.1.65

package/dist/react.js

@@ -413,6 +413,16 @@ function isComposerPreview() {
 
 // src/field-envelope.ts
 var FIELDS_BRAND = Symbol("amplifyup.fields");
+var IDENTIFIER_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "_id",
+  "slug",
+  "key",
+  "_key",
+  "docId",
+  "_type",
+  "type"
+]);
 function isBrandedFields(value) {
   return !!value && typeof value === "object" && FIELDS_BRAND in value;
 }
@@ -430,25 +440,88 @@ function isFieldEnvelope(value) {
   const rec = value;
   return typeof rec.name === "string" && "value" in rec && !("url" in rec);
 }
-function isPortableImageShape(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  return "url" in value;
+function isPageResourceSentinel(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && typeof value.__amplifyupPageResource === "string";
 }
-function isEntryRefItem(value) {
+function isPortableImageShape(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if ("url" in value) return true;
   const rec = value;
-  return typeof rec.id === "string" && rec.id.trim().length > 0 || typeof rec._id === "string" && rec._id.trim().length > 0 || typeof rec.docId === "string" && rec.docId.trim().length > 0;
+  return rec._type === "image" || rec.asset != null;
+}
+function isIdentifierKey(key) {
+  return IDENTIFIER_KEYS.has(key);
 }
-function isRepeaterArray(value) {
+function isRecordList(value) {
   if (!Array.isArray(value) || value.length === 0) return false;
   const sample = value.find((item) => item != null);
   if (sample === void 0) return false;
   if (typeof sample !== "object" || Array.isArray(sample)) return false;
   if (isPortableImageShape(sample)) return false;
-  if (isEntryRefItem(sample)) return false;
   if (sample.$$typeof) return false;
   return true;
 }
+function isFieldRef(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const rec = value;
+  return typeof rec.providerId === "string" && !!rec.providerId && typeof rec.entity === "string" && !!rec.entity && typeof rec.id === "string" && !!rec.id;
+}
+function isListOwner(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const rec = value;
+  return typeof rec.providerId === "string" && !!rec.providerId && typeof rec.entity === "string" && !!rec.entity;
+}
+function isReadOnlyRowField(value) {
+  return isFieldEnvelope(value) && value.readOnly === true && !value.ref;
+}
+function composerStoreKey(name, ref, layoutNodeId) {
+  if (isFieldRef(ref)) {
+    return `record:${ref.providerId}:${ref.entity}:${ref.id}:${name}`;
+  }
+  return layoutNodeId ? `page:${layoutNodeId}:${name}` : name;
+}
+function listOwnerFromConnection(conn) {
+  if (!conn || typeof conn !== "object") return void 0;
+  if (conn.mode === "query") {
+    const providerId = String(conn.spec?.providerId || "").trim();
+    const entity = String(conn.spec?.entity || "").trim();
+    return providerId && entity ? { providerId, entity } : void 0;
+  }
+  if (conn.mode === "item" || conn.mode === "items") {
+    const providerId = String(conn.providerId || "").trim();
+    const entity = String(conn.entity || "").trim();
+    return providerId && entity ? { providerId, entity } : void 0;
+  }
+  return void 0;
+}
+function listOwnerFromSpec(spec) {
+  const providerId = String(spec?.providerId || "").trim();
+  const entity = String(spec?.entity || "").trim();
+  return providerId && entity ? { providerId, entity } : void 0;
+}
+function isEnvelopeSources(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const rec = value;
+  return rec.connections != null || rec.reads != null;
+}
+function normalizeEnvelopeSources(sources) {
+  if (!sources) return {};
+  if (isEnvelopeSources(sources) && !("mode" in sources)) {
+    return sources;
+  }
+  return { connections: sources };
+}
+function listOwnerForField(fieldName, props, sources) {
+  const { connections, reads } = normalizeEnvelopeSources(sources);
+  const resourceName = reads?.[fieldName]?.resource || fieldName;
+  const fromConn = listOwnerFromConnection(connections?.[resourceName]);
+  if (fromConn) return fromConn;
+  const paging = props?.[`${fieldName}Pagination`];
+  if (paging && typeof paging === "object" && !Array.isArray(paging)) {
+    return listOwnerFromSpec(paging.spec);
+  }
+  return void 0;
+}
 function joinPath(prefix, key) {
   return prefix ? `${prefix}.${key}` : key;
 }
@@ -456,61 +529,105 @@ function emptyValue(raw) {
   if (raw === void 0) return null;
   return raw;
 }
-function toFieldEnvelopes(source, prefix = "") {
+function rowId(raw) {
+  const candidates = [raw.id, raw._id, raw.docId, raw.key, raw._key];
+  for (const c of candidates) {
+    if (typeof c === "string" && c.trim()) return c;
+  }
+  return "";
+}
+function withLeaf(envelope, scope) {
+  if (isFieldRef(scope?.ref)) envelope.ref = scope.ref;
+  else if (scope?.readOnly) envelope.readOnly = true;
+  return envelope;
+}
+function toFieldEnvelopes(source, prefix = "", scope) {
+  const ctx = isFieldRef(scope) ? { ref: scope } : scope || {};
   const input = source && typeof source === "object" && !Array.isArray(source) ? source : {};
   if (isBrandedFields(input)) {
     return input;
   }
   const out = {};
   for (const [key, raw] of Object.entries(input)) {
+    if (isIdentifierKey(key) && (typeof raw === "string" || raw == null)) {
+      out[key] = raw ?? "";
+      continue;
+    }
     const path = joinPath(prefix, key);
+    if (isPageResourceSentinel(raw)) {
+      out[key] = withLeaf({ value: raw, name: path }, ctx);
+      continue;
+    }
     if (isFieldEnvelope(raw)) {
       const inner = raw.value;
-      if (isRepeaterArray(inner)) {
+      if (isRecordList(inner)) {
+        const owner = ctx.owners?.(key);
         out[key] = {
-          value: envelopeRepeaterItems(inner, raw.name || path),
+          value: envelopeListRows(inner, owner),
           name: raw.name || path
         };
         continue;
       }
-      out[key] = { value: raw.value ?? null, name: raw.name || path };
+      out[key] = withLeaf(
+        { value: raw.value ?? null, name: raw.name || path },
+        raw.ref ? { ref: raw.ref } : ctx
+      );
       continue;
     }
-    if (isRepeaterArray(raw)) {
-      out[key] = { value: envelopeRepeaterItems(raw, path), name: path };
+    if (isRecordList(raw)) {
+      const owner = ctx.owners?.(key);
+      out[key] = { value: envelopeListRows(raw, owner), name: path };
       continue;
     }
     if (raw && typeof raw === "object" && !Array.isArray(raw) && !isPortableImageShape(raw) && !raw.$$typeof) {
-      out[key] = toFieldEnvelopes(raw, path);
+      out[key] = toFieldEnvelopes(raw, path, ctx);
       continue;
     }
-    out[key] = { value: emptyValue(raw), name: path };
+    out[key] = withLeaf({ value: emptyValue(raw), name: path }, ctx);
   }
   return brandFields(out);
 }
-function envelopeRepeaterItems(items, prefix) {
-  return items.map((item, i) => {
-    const path = joinPath(prefix, String(i));
-    if (isBrandedFields(item)) return item;
-    if (item && typeof item === "object" && !Array.isArray(item)) {
-      return toFieldEnvelopes(item, path);
-    }
-    return toFieldEnvelopes({}, path);
+function envelopeListRows(items, owner) {
+  return items.map((item) => envelopeListRow(item, owner));
+}
+function envelopeListRow(item, owner) {
+  if (isBrandedFields(item) && typeof item.id === "string") {
+    return item;
+  }
+  const raw = item && typeof item === "object" && !Array.isArray(item) ? item : {};
+  const id = rowId(raw);
+  const ref = isListOwner(owner) && id ? { providerId: owner.providerId, entity: owner.entity, id } : void 0;
+  const fields = toFieldEnvelopes(raw, "", {
+    ref,
+    readOnly: !ref
   });
+  const row = fields;
+  if (typeof row.id !== "string") {
+    row.id = id;
+  }
+  return row;
 }
-function attachFieldEnvelopes(props) {
+function attachFieldEnvelopes(props, sources) {
   const raw = props && typeof props === "object" ? { ...props } : {};
   if (isBrandedFields(raw.fields)) return raw;
   const { fields: existing, ...content } = raw;
   const source = existing && typeof existing === "object" && !isFieldEnvelope(existing) ? existing : content;
-  return { ...raw, fields: toFieldEnvelopes(source) };
+  return {
+    ...raw,
+    fields: toFieldEnvelopes(source, "", {
+      owners: (fieldName) => listOwnerForField(fieldName, source, sources)
+    })
+  };
 }
 function walkLayoutNodes(nodes) {
   if (!Array.isArray(nodes)) return;
   for (const node of nodes) {
     if (!node || typeof node !== "object") continue;
     const rec = node;
-    rec.props = attachFieldEnvelopes(rec.props);
+    rec.props = attachFieldEnvelopes(rec.props, {
+      connections: rec.resources,
+      reads: rec.reads
+    });
     for (const slot of rec.slots || []) {
       walkLayoutNodes(slot.children);
     }
@@ -524,31 +641,36 @@ function envelopePageConfig(page) {
 }
 function collectFieldPatches(props) {
   const out = [];
-  const walkRepeater = (items, prefix) => {
-    items.forEach((item, i) => {
-      const itemPath = joinPath(prefix, String(i));
+  const walkRows = (items) => {
+    for (const item of items) {
       if (isBrandedFields(item) || item && typeof item === "object" && !Array.isArray(item) && !isFieldEnvelope(item)) {
-        walk(item, itemPath);
+        walk(item, "");
       }
-    });
+    }
   };
   const walk = (obj, prefix) => {
     for (const [key, raw] of Object.entries(obj)) {
+      if (isIdentifierKey(key)) continue;
       if (key === "fields" && raw && typeof raw === "object" && !Array.isArray(raw) && !isFieldEnvelope(raw)) {
         walk(raw, prefix);
         continue;
       }
       const path = joinPath(prefix, key);
       if (isFieldEnvelope(raw)) {
-        if (isRepeaterArray(raw.value)) {
-          walkRepeater(raw.value, raw.name || path);
+        if (isRecordList(raw.value)) {
+          walkRows(raw.value);
           continue;
         }
-        out.push({ name: raw.name || path, value: raw.value });
+        const patch = {
+          name: raw.name || path,
+          value: raw.value
+        };
+        if (raw.ref) patch.ref = raw.ref;
+        out.push(patch);
         continue;
       }
-      if (isRepeaterArray(raw)) {
-        walkRepeater(raw, path);
+      if (isRecordList(raw)) {
+        walkRows(raw);
         continue;
       }
       if (raw && typeof raw === "object" && !Array.isArray(raw) && !isPortableImageShape(raw) && !raw.$$typeof) {
@@ -563,40 +685,14 @@ function collectFieldPatches(props) {
   }
   return out;
 }
-function unwrapFieldsBag(item) {
-  if (!item || typeof item !== "object" || Array.isArray(item)) return {};
-  const out = {};
-  for (const [key, raw] of Object.entries(item)) {
-    if (isFieldEnvelope(raw)) {
-      out[key] = raw.value;
-      continue;
-    }
-    if (raw && typeof raw === "object" && !Array.isArray(raw) && !isPortableImageShape(raw) && !isEntryRefItem(raw) && !raw.$$typeof) {
-      out[key] = unwrapFieldsBag(raw);
-      continue;
-    }
-    out[key] = raw;
-  }
-  return out;
-}
-function resolveCollectionItems(field, overlay) {
-  const name = typeof field?.name === "string" ? field.name : "";
-  const raw = overlay !== void 0 ? overlay : field?.value;
-  const list = Array.isArray(raw) ? raw : isFieldEnvelope(raw) && Array.isArray(raw.value) ? raw.value : [];
-  if (list.length === 0) return [];
-  if (isRepeaterArray(list) || list.every((item) => isBrandedFields(item))) {
-    return envelopeRepeaterItems(list, name);
-  }
-  return envelopeRepeaterItems(
-    list.map(
-      (item) => item && typeof item === "object" && !Array.isArray(item) ? item : {}
-    ),
-    name
-  );
-}
 function resolveEditableBinding(field, value, name) {
   if (isFieldEnvelope(field)) {
-    return { name: field.name, value: field.value, requiresName: false };
+    return {
+      name: field.name,
+      value: field.value,
+      ref: field.ref,
+      requiresName: false
+    };
   }
   return {
     name: name || "",
@@ -767,7 +863,7 @@ function mergeEventContext(properties, attached) {
   };
 }
 var PAGE_RESOURCE_MARKER = "__amplifyupPageResource";
-function isPageResourceSentinel(value) {
+function isPageResourceSentinel2(value) {
   return !!value && typeof value === "object" && !Array.isArray(value) && typeof value[PAGE_RESOURCE_MARKER] === "string";
 }
 function getByDotPath(source, path) {
@@ -783,7 +879,7 @@ function getByDotPath(source, path) {
   return cur;
 }
 function hydratePageResourceValue(value, fields) {
-  if (!isPageResourceSentinel(value)) return value;
+  if (!isPageResourceSentinel2(value)) return value;
   if (!fields) return null;
   if (value.path) return getByDotPath(fields, value.path) ?? null;
   return fields;
@@ -795,7 +891,7 @@ function hydrateFieldsBag(bag, fields) {
       const env = val;
       out[key] = {
         name: env.name,
-        value: isPageResourceSentinel(env.value) ? hydratePageResourceValue(env.value, fields) : env.value
+        value: isPageResourceSentinel2(env.value) ? hydratePageResourceValue(env.value, fields) : env.value
       };
       continue;
     }
@@ -803,7 +899,7 @@ function hydrateFieldsBag(bag, fields) {
       out[key] = hydrateFieldsBag(val, fields);
       continue;
     }
-    out[key] = isPageResourceSentinel(val) ? hydratePageResourceValue(val, fields) : val;
+    out[key] = isPageResourceSentinel2(val) ? hydratePageResourceValue(val, fields) : val;
   }
   return out;
 }
@@ -816,7 +912,7 @@ function hydratePageResourceProps(props, fields) {
   }
   for (const [key, val] of Object.entries(out)) {
     if (key === "fields") continue;
-    if (isPageResourceSentinel(val)) {
+    if (isPageResourceSentinel2(val)) {
       out[key] = hydratePageResourceValue(val, fields);
     }
   }
@@ -955,7 +1051,10 @@ async function fetchEdgeResolve(options) {
   return envelopeResolvedPayload(body);
 }
 function envelopeResolvedComponent(node) {
-  node.props = attachFieldEnvelopes(node.props);
+  node.props = attachFieldEnvelopes(node.props, {
+    connections: node.resources,
+    reads: node.reads
+  });
   if (!node.children) return;
   for (const kids of Object.values(node.children)) {
     for (const child of kids || []) envelopeResolvedComponent(child);
@@ -1214,7 +1313,7 @@ async function fetchEdgeQuery(options) {
 async function queryContent(options) {
   const target = resolveAmplifyUpTarget({ configTarget: options.target });
   const { edgeUrl } = resolveAmplifyUpUrls(target);
-  return fetchEdgeQuery({
+  const raw = await fetchEdgeQuery({
     edgeUrl,
     trackingId: options.trackingId,
     route: options.route,
@@ -1223,6 +1322,13 @@ async function queryContent(options) {
     fetch: options.fetch,
     signal: options.signal
   });
+  return {
+    ...raw,
+    results: envelopeListRows(
+      raw.results,
+      listOwnerFromSpec(options.spec)
+    )
+  };
 }
 function nextPageSpec(pagination) {
   return { ...pagination.spec, offset: pagination.nextOffset };
@@ -3719,44 +3825,50 @@ var ComposerFieldStore = class {
   }
 };
 var ComposerStoreContext = React2.createContext(null);
-function matchesNode(eventNodeId, layoutNodeId) {
-  if (eventNodeId && layoutNodeId && String(eventNodeId) !== String(layoutNodeId)) {
-    return false;
-  }
-  return true;
+var ComposerNodeContext = React2.createContext(void 0);
+function applyComposerPatch(store, name, value, ref, layoutNodeId) {
+  store.set(composerStoreKey(name, ref, layoutNodeId), value);
 }
 function ComposerProvider({
-  layoutNodeId,
   children
 }) {
+  const existing = React2.useContext(ComposerStoreContext);
   const storeRef = React2.useRef(null);
   if (!storeRef.current) storeRef.current = new ComposerFieldStore();
-  const store = storeRef.current;
+  const store = existing || storeRef.current;
   React2.useEffect(() => {
-    const applyField = (fieldName, value, nodeId) => {
+    if (existing) return;
+    const applyField = (fieldName, value, nodeId, ref) => {
       if (!fieldName || typeof fieldName !== "string") return;
-      if (!matchesNode(nodeId, layoutNodeId)) return;
-      store.set(fieldName, value);
-      if (value && typeof value === "object") {
-        for (const patch of collectFieldPatches(
-          toFieldEnvelopes({ [fieldName]: value })
-        )) {
-          store.set(patch.name, patch.value);
-        }
-      }
+      const fieldRef = isFieldRef(ref) ? ref : void 0;
+      const layoutNodeId = typeof nodeId === "string" && nodeId ? nodeId : void 0;
+      applyComposerPatch(store, fieldName, value, fieldRef, layoutNodeId);
     };
     const applyProps = (nextProps, nodeId) => {
       if (!nextProps || typeof nextProps !== "object" || Array.isArray(nextProps)) {
         return;
       }
-      if (!matchesNode(nodeId, layoutNodeId)) return;
-      for (const patch of collectFieldPatches(nextProps)) {
-        store.set(patch.name, patch.value);
+      const layoutNodeId = typeof nodeId === "string" && nodeId ? nodeId : void 0;
+      for (const patch of collectFieldPatches(
+        nextProps
+      )) {
+        applyComposerPatch(
+          store,
+          patch.name,
+          patch.value,
+          patch.ref,
+          patch.ref ? void 0 : layoutNodeId
+        );
       }
     };
     const onPatch = (event) => {
       const detail = event.detail || {};
-      applyField(detail.fieldName, detail.value, detail.layoutNodeId);
+      applyField(
+        detail.fieldName,
+        detail.value,
+        detail.layoutNodeId,
+        detail.ref
+      );
     };
     const onPropsPatch = (event) => {
       const detail = event.detail || {};
@@ -3768,7 +3880,12 @@ function ComposerProvider({
         return;
       }
       if (event.data?.type !== "AMPLIFYUP_FIELD_PATCH") return;
-      applyField(event.data.fieldName, event.data.value, event.data.layoutNodeId);
+      applyField(
+        event.data.fieldName,
+        event.data.value,
+        event.data.layoutNodeId,
+        event.data.ref
+      );
     };
     window.addEventListener("amplifyup:field-patch", onPatch);
     window.addEventListener("amplifyup:props-patch", onPropsPatch);
@@ -3778,29 +3895,29 @@ function ComposerProvider({
       window.removeEventListener("amplifyup:props-patch", onPropsPatch);
       window.removeEventListener("message", onMessage);
     };
-  }, [layoutNodeId, store]);
+  }, [existing, store]);
+  if (existing) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
   return /* @__PURE__ */ jsxRuntime.jsx(ComposerStoreContext.Provider, { value: store, children });
 }
-function useComposerFieldValue(name, fallback) {
+function useComposerFieldValue(name, fallback, ref) {
   const store = React2.useContext(ComposerStoreContext);
+  const layoutNodeId = React2.useContext(ComposerNodeContext);
+  const key = composerStoreKey(name, ref, layoutNodeId);
   const subscribe = React2.useCallback(
     (onStoreChange) => {
       if (!store || !name) return () => {
       };
-      return store.subscribe(name, onStoreChange);
+      return store.subscribe(key, onStoreChange);
     },
-    [store, name]
+    [store, name, key]
   );
   const getSnapshot = React2.useCallback(() => {
     if (!store || !name) return void 0;
-    return store.get(name);
-  }, [store, name]);
+    return store.get(key);
+  }, [store, name, key]);
   const overlay = React2.useSyncExternalStore(subscribe, getSnapshot, () => void 0);
   return overlay !== void 0 ? overlay : fallback;
 }
-function useComposerStore() {
-  return React2.useContext(ComposerStoreContext);
-}
 function MaybeComposerProvider({
   enabled,
   layoutNodeId,
@@ -3808,7 +3925,7 @@ function MaybeComposerProvider({
 }) {
   const content = React2.useMemo(() => children, [children]);
   if (!enabled) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: content });
-  return /* @__PURE__ */ jsxRuntime.jsx(ComposerProvider, { layoutNodeId, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(ComposerProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(ComposerNodeContext.Provider, { value: layoutNodeId, children }) });
 }
 function nodeRenderProps(node) {
   const settings = node.settings || {};
@@ -4266,7 +4383,7 @@ function AmplifyRendererInner({
   if (layoutTree.length === 0) {
     return /* @__PURE__ */ jsxRuntime.jsx("main", { children: emptyComponent || /* @__PURE__ */ jsxRuntime.jsx("div", { className: "container mx-auto px-4 py-16", children: /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-muted-foreground", children: "No content configured for this page." }) }) });
   }
-  return /* @__PURE__ */ jsxRuntime.jsx("main", { children: composerPreview || isComposerPreview() ? /* @__PURE__ */ jsxRuntime.jsx(
+  return /* @__PURE__ */ jsxRuntime.jsx(ComposerProvider, { children: /* @__PURE__ */ jsxRuntime.jsx("main", { children: composerPreview || isComposerPreview() ? /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
       "data-slot-id": "main",
@@ -4275,7 +4392,7 @@ function AmplifyRendererInner({
       "data-slot-empty": layoutTree.length === 0 ? "true" : void 0,
       children: layoutTree.map((node) => /* @__PURE__ */ jsxRuntime.jsx(React2.Fragment, { children: renderNode(node) }, node.id))
     }
-  ) : layoutTree.map((node) => /* @__PURE__ */ jsxRuntime.jsx(React2.Fragment, { children: renderNode(node) }, node.id)) });
+  ) : layoutTree.map((node) => /* @__PURE__ */ jsxRuntime.jsx(React2.Fragment, { children: renderNode(node) }, node.id)) }) });
 }
 var AmplifyRenderer = React2.memo(AmplifyRendererInner);
 function AddComponentIcon({ size = 28 }) {
@@ -4628,10 +4745,10 @@ function useBoundField(field, value, name, component) {
       `[AmplifyUp SDK] ${component} value={\u2026} requires name="\u2026" for computed values`
     );
   }
-  const fieldValue = useComposerFieldValue(bound.name, bound.value);
-  return { editName: bound.name, fieldValue };
+  const fieldValue = useComposerFieldValue(bound.name, bound.value, bound.ref);
+  return { editName: bound.name, fieldValue, ref: bound.ref };
 }
-function commitComposerField(layoutNodeId, componentId, name, value) {
+function commitComposerField(layoutNodeId, componentId, name, value, ref) {
   if (typeof window === "undefined" || window.parent === window) return;
   window.parent.postMessage(
     {
@@ -4639,7 +4756,8 @@ function commitComposerField(layoutNodeId, componentId, name, value) {
       layoutNodeId,
       componentId,
       fieldName: name,
-      value
+      value,
+      ...ref ? { ref } : {}
     },
     "*"
   );
@@ -4664,6 +4782,7 @@ function requestCanvasRichTextEdit(opts) {
       componentId: opts.componentId,
       fieldName: opts.name,
       value: opts.value,
+      ...opts.fieldRef ? { ref: opts.fieldRef } : {},
       bounds: {
         top: rect.top,
         left: rect.left,
@@ -4688,6 +4807,7 @@ function ComposerInlineField({
   className,
   layoutNodeId,
   componentId,
+  fieldRef,
   rich = false
 }) {
   const [focused, setFocused] = React2.useState(false);
@@ -4716,12 +4836,12 @@ function ComposerInlineField({
     if (storedEmpty && next === "") {
       if (elRef.current) elRef.current.textContent = hint;
       if (typeof value === "string" && EMPTY_FIELD_PLACEHOLDERS.has(value.trim())) {
-        commitComposerField(layoutNodeId, componentId, name, "");
+        commitComposerField(layoutNodeId, componentId, name, "", fieldRef);
       }
       return;
     }
     if (next === text) return;
-    commitComposerField(layoutNodeId, componentId, name, next);
+    commitComposerField(layoutNodeId, componentId, name, next, fieldRef);
   };
   const openRichEditor = (event) => {
     if (!isComposerEditMode() || !elRef.current) return;
@@ -4733,7 +4853,8 @@ function ComposerInlineField({
       layoutNodeId,
       componentId,
       name,
-      value: source
+      value: source,
+      fieldRef
     });
   };
   return /* @__PURE__ */ jsxRuntime.jsx(
@@ -4744,6 +4865,9 @@ function ComposerInlineField({
       "data-amplifyup-field": name,
       "data-amplifyup-field-type": rich ? "richtext" : "text",
       "data-amplifyup-node-id": layoutNodeId || void 0,
+      "data-amplifyup-ref-provider": fieldRef?.providerId || void 0,
+      "data-amplifyup-ref-entity": fieldRef?.entity || void 0,
+      "data-amplifyup-ref-id": fieldRef?.id || void 0,
       "data-amplifyup-empty-hint": showHint ? "true" : void 0,
       contentEditable: !rich,
       suppressContentEditableWarning: true,
@@ -4808,7 +4932,8 @@ function ComposerInlineHtml({
   className,
   Tag = "div",
   layoutNodeId,
-  componentId
+  componentId,
+  fieldRef
 }) {
   const elRef = React2.useRef(null);
   React2.useEffect(() => {
@@ -4825,7 +4950,8 @@ function ComposerInlineHtml({
       layoutNodeId,
       componentId,
       name,
-      value: sourceValue
+      value: sourceValue,
+      fieldRef
     });
   };
   return React2__default.default.createElement(Tag, {
@@ -4834,6 +4960,9 @@ function ComposerInlineHtml({
     "data-amplifyup-field": name,
     "data-amplifyup-field-type": "richtext",
     "data-amplifyup-node-id": layoutNodeId || void 0,
+    "data-amplifyup-ref-provider": fieldRef?.providerId || void 0,
+    "data-amplifyup-ref-entity": fieldRef?.entity || void 0,
+    "data-amplifyup-ref-id": fieldRef?.id || void 0,
     dangerouslySetInnerHTML: { __html: html },
     onMouseDown: (event) => {
       event.stopPropagation();
@@ -4865,6 +4994,40 @@ function formatFieldValue(value) {
   }
   return "";
 }
+var FIELD_SCALAR_HINT = "Field expects a scalar field. Did you mean <Field field={post.title} />?";
+function warnNotScalarField(component, field, fieldValue) {
+  if (process.env.NODE_ENV === "production") return false;
+  if (isBrandedFields(field)) {
+    console.error(`[AmplifyUp SDK] ${component}: ${FIELD_SCALAR_HINT}`);
+    return true;
+  }
+  if (isFieldEnvelope(field) && Array.isArray(field.value)) {
+    console.error(`[AmplifyUp SDK] ${component}: ${FIELD_SCALAR_HINT}`);
+    return true;
+  }
+  if (Array.isArray(fieldValue)) {
+    console.error(`[AmplifyUp SDK] ${component}: ${FIELD_SCALAR_HINT}`);
+    return true;
+  }
+  return false;
+}
+var warnedReadOnlyFields = /* @__PURE__ */ new Set();
+function warnReadOnlyRowField(name) {
+  if (process.env.NODE_ENV === "production") return;
+  const key = name || "(unnamed)";
+  if (warnedReadOnlyFields.has(key)) return;
+  warnedReadOnlyFields.add(key);
+  console.warn(
+    `[AmplifyUp SDK] ${key} has no write target; rendered read-only.`
+  );
+}
+function canComposerBind(field, ref, editName) {
+  if (isReadOnlyRowField(field) || isFieldEnvelope(field) && field.readOnly) {
+    warnReadOnlyRowField(editName || (isFieldEnvelope(field) ? field.name : ""));
+    return false;
+  }
+  return true;
+}
 function warnProjectionProps(component, hasField, hasValue, name) {
   if (process.env.NODE_ENV === "production") return;
   if (!hasField && !hasValue && !name) {
@@ -4882,16 +5045,20 @@ function Field(props) {
   const composerEdit = useComposerEditMode();
   const hasField = isFieldEnvelope(field);
   const hasValue = hasOwnProp(props, "value");
-  const { editName, fieldValue } = useBoundField(field, value, name, "Field");
+  const { editName, fieldValue, ref } = useBoundField(field, value, name, "Field");
   warnProjectionProps("Field", hasField, hasValue, name);
+  if (warnNotScalarField("Field", field, fieldValue)) {
+    return null;
+  }
   if (!hasField && !hasValue && !name) {
     return null;
   }
-  if (Array.isArray(fieldValue)) {
+  if (isBrandedFields(field) || Array.isArray(fieldValue)) {
     return null;
   }
   const empty = isComposerEmptyText(fieldValue);
-  if (composerEdit && editName && context && canInlineEdit(editName, fieldValue)) {
+  const bindComposer = composerEdit && editName && context && canInlineEdit(editName, fieldValue) && canComposerBind(field, ref, editName);
+  if (bindComposer) {
     return /* @__PURE__ */ jsxRuntime.jsx(
       ComposerInlineField,
       {
@@ -4900,6 +5067,7 @@ function Field(props) {
         className,
         layoutNodeId: context.layoutNodeId,
         componentId: context.componentId,
+        fieldRef: ref,
         rich: looksLikeRichCanvasField(editName)
       }
     );
@@ -4909,186 +5077,6 @@ function Field(props) {
   if (!text) return null;
   return /* @__PURE__ */ jsxRuntime.jsx("span", { className, children: text });
 }
-var COMPOSER_EMPTY_COLLECTION_HINT = "Click here to add an item";
-function CollectionChromeButton({
-  label,
-  onClick
-}) {
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    "button",
-    {
-      type: "button",
-      onMouseDown: (event) => event.stopPropagation(),
-      onClick: (event) => {
-        event.preventDefault();
-        event.stopPropagation();
-        onClick();
-      },
-      style: {
-        fontSize: 11,
-        lineHeight: 1.2,
-        padding: "4px 8px",
-        border: "1px solid color-mix(in srgb, currentColor 28%, transparent)",
-        borderRadius: 6,
-        background: "transparent",
-        cursor: "pointer",
-        color: "inherit"
-      },
-      children: label
-    }
-  );
-}
-function Collection({
-  field,
-  children,
-  className
-}) {
-  const context = React2.useContext(ComponentContext);
-  const store = useComposerStore();
-  const composerEdit = useComposerEditMode();
-  const name = isFieldEnvelope(field) ? field.name : "";
-  const overlay = useComposerFieldValue(name, void 0);
-  const items = resolveCollectionItems(field, overlay);
-  const writeItems = (nextPlain) => {
-    if (name && store) {
-      const prefixed = name ? store.keys().filter((key) => key === name || key.startsWith(`${name}.`)) : [];
-      for (const key of prefixed) store.delete(key);
-      store.set(name, nextPlain);
-      for (const patch of collectFieldPatches(
-        toFieldEnvelopes({ [name]: nextPlain })
-      )) {
-        store.set(patch.name, patch.value);
-      }
-    }
-    commitComposerField(
-      context?.layoutNodeId,
-      context?.componentId,
-      name,
-      nextPlain
-    );
-  };
-  const plainItems = () => items.map((item, index) => {
-    const base = unwrapFieldsBag(item);
-    if (!store || !name) return base;
-    const out = { ...base };
-    for (const key of Object.keys(out)) {
-      const overlayValue = store.get(`${name}.${index}.${key}`);
-      if (overlayValue !== void 0) out[key] = overlayValue;
-    }
-    return out;
-  });
-  const addItem = () => writeItems([...plainItems(), {}]);
-  const removeItem = (index) => writeItems(plainItems().filter((_, i) => i !== index));
-  const moveItem = (index, delta) => {
-    const next = plainItems();
-    const target = index + delta;
-    if (target < 0 || target >= next.length) return;
-    const swap = next[index];
-    next[index] = next[target];
-    next[target] = swap;
-    writeItems(next);
-  };
-  if (!composerEdit) {
-    if (items.length === 0) return null;
-    return /* @__PURE__ */ jsxRuntime.jsx("span", { className, style: { display: "contents" }, children: items.map((item, index) => /* @__PURE__ */ jsxRuntime.jsx(React2__default.default.Fragment, { children: children(item, index) }, item && typeof item === "object" ? `${name}.${index}` : index)) });
-  }
-  if (items.length === 0) {
-    return /* @__PURE__ */ jsxRuntime.jsx(
-      "span",
-      {
-        className,
-        "data-amplifyup-collection": name || void 0,
-        "data-amplifyup-collection-empty": "true",
-        "data-amplifyup-node-id": context?.layoutNodeId || void 0,
-        role: "button",
-        tabIndex: 0,
-        onMouseDown: (event) => event.stopPropagation(),
-        onClick: (event) => {
-          event.preventDefault();
-          event.stopPropagation();
-          addItem();
-        },
-        onKeyDown: (event) => {
-          if (event.key === "Enter" || event.key === " ") {
-            event.preventDefault();
-            addItem();
-          }
-        },
-        style: {
-          display: "block",
-          cursor: "pointer",
-          outline: "1px dashed color-mix(in srgb, currentColor 40%, transparent)",
-          outlineOffset: 2,
-          minHeight: "3em",
-          opacity: 0.5
-        },
-        children: /* @__PURE__ */ jsxRuntime.jsx(EmptySlotHint, { label: COMPOSER_EMPTY_COLLECTION_HINT, compact: true })
-      }
-    );
-  }
-  return /* @__PURE__ */ jsxRuntime.jsxs(
-    "span",
-    {
-      className,
-      "data-amplifyup-collection": name || void 0,
-      "data-amplifyup-node-id": context?.layoutNodeId || void 0,
-      style: { display: "flex", flexDirection: "column", gap: 8 },
-      children: [
-        items.map((item, index) => /* @__PURE__ */ jsxRuntime.jsxs(
-          "span",
-          {
-            "data-amplifyup-collection-item": `${name}.${index}`,
-            style: {
-              display: "block",
-              outline: "1px dashed color-mix(in srgb, currentColor 28%, transparent)",
-              outlineOffset: 2,
-              padding: 8
-            },
-            children: [
-              /* @__PURE__ */ jsxRuntime.jsxs(
-                "span",
-                {
-                  style: {
-                    display: "flex",
-                    gap: 6,
-                    justifyContent: "flex-end",
-                    marginBottom: 8
-                  },
-                  children: [
-                    /* @__PURE__ */ jsxRuntime.jsx(
-                      CollectionChromeButton,
-                      {
-                        label: "Move up",
-                        onClick: () => moveItem(index, -1)
-                      }
-                    ),
-                    /* @__PURE__ */ jsxRuntime.jsx(
-                      CollectionChromeButton,
-                      {
-                        label: "Move down",
-                        onClick: () => moveItem(index, 1)
-                      }
-                    ),
-                    /* @__PURE__ */ jsxRuntime.jsx(
-                      CollectionChromeButton,
-                      {
-                        label: "Remove",
-                        onClick: () => removeItem(index)
-                      }
-                    )
-                  ]
-                }
-              ),
-              children(item, index)
-            ]
-          },
-          `${name}.${index}`
-        )),
-        /* @__PURE__ */ jsxRuntime.jsx("span", { children: /* @__PURE__ */ jsxRuntime.jsx(CollectionChromeButton, { label: "Add item", onClick: addItem }) })
-      ]
-    }
-  );
-}
 function markdownToHtml(markdown) {
   try {
     const result = marked.marked.parse(markdown, { async: false });
@@ -5112,7 +5100,7 @@ function RichText(props) {
   const hasField = isFieldEnvelope(field);
   const hasValueProp = hasOwnProp(props, "value") || childrenValue !== void 0;
   const boundValue = hasOwnProp(props, "value") ? value : childrenValue !== void 0 ? childrenValue : value;
-  const { editName, fieldValue } = useBoundField(
+  const { editName, fieldValue, ref } = useBoundField(
     field,
     boundValue,
     name,
@@ -5122,7 +5110,10 @@ function RichText(props) {
     return null;
   }
   warnProjectionProps("RichText", hasField, hasValueProp, name);
-  const canEdit = !!context && canInlineEditRichText(editName, fieldValue);
+  if (warnNotScalarField("RichText", field, fieldValue)) {
+    return null;
+  }
+  const canEdit = !!context && canInlineEditRichText(editName, fieldValue) && canComposerBind(field, ref, editName);
   if (isComposerEmptyText(fieldValue)) {
     if (composerEdit && canEdit) {
       return /* @__PURE__ */ jsxRuntime.jsx(
@@ -5133,6 +5124,7 @@ function RichText(props) {
           className,
           layoutNodeId: context?.layoutNodeId,
           componentId: context?.componentId,
+          fieldRef: ref,
           rich: true
         }
       );
@@ -5164,7 +5156,8 @@ function RichText(props) {
         className,
         Tag,
         layoutNodeId: context?.layoutNodeId,
-        componentId: context?.componentId
+        componentId: context?.componentId,
+        fieldRef: ref
       }
     );
   }
@@ -5180,6 +5173,38 @@ function imageSrc(value) {
   if (isPortableImageValue(value)) return value.url.trim();
   return "";
 }
+function leafText(field) {
+  if (isFieldEnvelope(field)) return field.value;
+  return field;
+}
+function coerceImageField(field, value, name) {
+  if (isFieldEnvelope(field)) return { field, value, name };
+  if (!isBrandedFields(field) || !field || typeof field !== "object") {
+    return { field: void 0, value, name };
+  }
+  const bag = field;
+  const urlField = bag.url;
+  const urlName = isFieldEnvelope(urlField) && typeof urlField.name === "string" ? urlField.name.replace(/\.url$/, "") : "";
+  const editName = urlName || name || "";
+  if (!editName) return { field: void 0, value, name };
+  const ref = isFieldEnvelope(urlField) ? urlField.ref : void 0;
+  const width = leafText(bag.width);
+  const height = leafText(bag.height);
+  return {
+    field: {
+      value: {
+        url: String(leafText(urlField) ?? ""),
+        alt: leafText(bag.alt),
+        ...typeof width === "number" ? { width } : {},
+        ...typeof height === "number" ? { height } : {}
+      },
+      name: editName,
+      ...ref ? { ref } : {}
+    },
+    value,
+    name: editName
+  };
+}
 function Image(props) {
   const {
     field,
@@ -5192,12 +5217,22 @@ function Image(props) {
     ...imgProps
   } = props;
   const context = React2.useContext(ComponentContext);
-  const hasField = isFieldEnvelope(field);
+  const coerced = coerceImageField(field, value, name);
+  const boundField = coerced.field;
+  const hasField = isFieldEnvelope(boundField);
   const hasValue = hasOwnProp(props, "value");
-  const { editName, fieldValue } = useBoundField(field, value, name, "Image");
+  const { editName, fieldValue, ref } = useBoundField(
+    boundField,
+    coerced.value,
+    coerced.name,
+    "Image"
+  );
   const composerEdit = useComposerEditMode();
-  warnProjectionProps("Image", hasField, hasValue, name);
-  if (!hasField && !hasValue && !name) {
+  warnProjectionProps("Image", hasField || isBrandedFields(field), hasValue, coerced.name || name);
+  if (!isBrandedFields(field) && warnNotScalarField("Image", boundField, fieldValue)) {
+    return null;
+  }
+  if (!hasField && !hasValue && !name && !editName) {
     return null;
   }
   const src = imageSrc(fieldValue);
@@ -5205,10 +5240,13 @@ function Image(props) {
   const alt = altProp ?? portable?.alt ?? "";
   const width = widthProp ?? portable?.width;
   const height = heightProp ?? portable?.height;
-  const fieldAttrs = composerEdit && editName ? {
+  const fieldAttrs = composerEdit && editName && canComposerBind(boundField, ref, editName) ? {
     "data-amplifyup-field": editName,
     "data-amplifyup-field-type": "image",
-    "data-amplifyup-node-id": context?.layoutNodeId || void 0
+    "data-amplifyup-node-id": context?.layoutNodeId || void 0,
+    "data-amplifyup-ref-provider": ref?.providerId || void 0,
+    "data-amplifyup-ref-entity": ref?.entity || void 0,
+    "data-amplifyup-ref-id": ref?.id || void 0
   } : null;
   if (composerEdit && !editName && (hasField || hasValue)) {
     console.warn(
@@ -5480,7 +5518,6 @@ function useAmplifyUp() {
 exports.AmplifyPageContent = AmplifyPageContent;
 exports.AmplifyRenderer = AmplifyRenderer;
 exports.AmplifyUpProvider = AmplifyUpProvider;
-exports.Collection = Collection;
 exports.ComponentContextProvider = ComponentContextProvider;
 exports.ComposerProvider = ComposerProvider;
 exports.Field = Field;
@@ -5490,11 +5527,16 @@ exports.QueryContentError = QueryContentError;
 exports.RichText = RichText;
 exports.SelectVariantsError = SelectVariantsError;
 exports.Slot = Slot;
+exports.attachFieldEnvelopes = attachFieldEnvelopes;
+exports.composerStoreKey = composerStoreKey;
+exports.envelopeListRows = envelopeListRows;
 exports.isBrandedFields = isBrandedFields;
 exports.isComposerPreview = isComposerPreview;
 exports.isFieldEnvelope = isFieldEnvelope;
 exports.isPreviewRequest = isPreviewRequest;
+exports.isReadOnlyRowField = isReadOnlyRowField;
 exports.isWorkingContentRequest = isWorkingContentRequest;
+exports.listOwnerFromSpec = listOwnerFromSpec;
 exports.nextPageSpec = nextPageSpec;
 exports.queryContent = queryContent;
 exports.searchSpec = searchSpec;