@amplifyup/sdk 0.1.63 → 0.1.64

package/README.md

@@ -97,12 +97,27 @@ fields.hero.image
 
 fields.subheading   // empty on a new page
 // → { value: null, name: 'subheading' }
+
+fields.posts.value[0].title   // a row inside a list
+// → { value: 'Ship faster', name: 'title', ref: { providerId, entity, id } }
 ```
 
 `name` is the field's dot path. It is what lets `<Field>` know which field it is bound to without you telling it. `value` is the content, typed from your schema.
 
 **The shape is identical on the live site, in a draft, and in Composer.** There is no mode where you get a bare string instead of an envelope, and no mode where an empty field is `undefined` instead of `{ value: null, name }`.
 
+### Write targets
+
+One rule explains everything about editing:
+
+> **A field is editable if and only if it carries a write target.** The write target is set by whoever produced the data. Nothing downstream guesses.
+
+- A **page field** (`fields.heading`) has no `ref`. Its write target is the page, and Composer already knows which page you are on.
+- A **list row field** (`post.title`) carries `ref: { providerId, entity, id }` — the record it belongs to. Editing it saves to that record, not to the page.
+- A row field the SDK could not trace back to a producer gets no `ref` and is marked `readOnly: true`. It renders as plain text in Composer: no outline, no click target.
+
+You never set `ref` yourself. You never read it either. It is there so that the same `<Field>` you use for a page heading also works on a row in a list.
+
 ### Two ways to read a field
 
 ```tsx
@@ -130,8 +145,8 @@ export function Card({ fields }: { fields: Fields<{ title: string; link: string;
 
 | Component | Field type | Renders |
 | --- | --- | --- |
-| `<Field>` | `string`, `number` | text node — no wrapper element |
-| `<RichText>` | markdown / rich text | rendered HTML |
+| `<Field>` | `string`, `number` | a `<span>` with the text |
+| `<RichText>` | markdown / rich text | rendered HTML in a `<div>` (change with `as`) |
 | `<Image>` | `ImageValue` | `<img>` |
 
 All three take a `field` prop and read `name` from it. Pass any extra props (`className`, `loading`, etc.) and they go on the rendered element.
@@ -178,7 +193,7 @@ Why no `fallback` prop: a fallback turns "this field was never populated" into "
 
 ### Wrapper elements
 
-`<Field>` renders a text node, not an element, so you supply the tag:
+`<Field>` renders an inline `<span>`, never a heading or paragraph, so you supply the semantic tag around it:
 
 ```tsx
 // ✓
@@ -189,6 +204,19 @@ Why no `fallback` prop: a fallback turns "this field was never populated" into "
 <Field as="h1" field={fields.heading} />
 ```
 
+`<RichText>` is the exception: it owns a block element, and `as` picks which one.
+
+```tsx
+// ✓ — default is <div>
+<RichText field={fields.body} className="prose" />
+
+// ✓ — pick a different block element
+<RichText field={fields.body} as="article" className="prose" />
+
+// ✗ — don't nest a block element inside a paragraph
+<p><RichText field={fields.body} /></p>
+```
+
 If the wrapper should disappear when the field is empty, check `.value`:
 
 ```tsx
@@ -273,16 +301,18 @@ export function Announcement({ fields }: { fields: Fields<{ message: string }> }
 export function Carousel({ fields }) {
   const inComposer = useInComposer();
   return (
-    <Collection field={fields.slides}>
-      {(slide) => <Slide slide={slide} autoplay={!inComposer} />}
-    </Collection>
+    <>
+      {(fields.slides.value ?? []).map((slide) => (
+        <Slide key={slide.id} slide={slide} autoplay={!inComposer} />
+      ))}
+    </>
   );
 }
 ```
 
 Rules of thumb:
 
-- The **field component is the source of truth in Composer.** If a field is visible to authors, it must be rendered through `<Field>` / `<RichText>` / `<Image>` / `<Collection>` in Composer mode, even if the live site reads `.value`.
+- The **field component is the source of truth in Composer.** If a field is visible to authors, it must be rendered through `<Field>` / `<RichText>` / `<Image>` in Composer mode, even if the live site reads `.value`.
 - **Don't fork the whole component.** Branch the one element that differs, not the entire return. Two divergent trees drift and the preview stops matching production.
 - **Empty gating uses `inComposer`.** `if (!x.value) return null` is correct for live and wrong for authors — they can't click what isn't rendered. Add `&& !inComposer`.
 - **Don't use it to hide editable text on live.** If the text is visible on the live site, render it with the field component in both modes. `useInComposer` is for content the live markup genuinely can't expose as a field.
@@ -299,20 +329,13 @@ Rules of thumb:
 
 ## Lists
 
-There are two kinds of list field and they are handled differently. Check your schema to know which you have.
-
-| Shape | Schema | What it holds | In your component | Edited in Composer via |
-| --- | --- | --- | --- | --- |
-| **Reference list** | `array` + `entity` `of` | Linked entries — a query or a curated set of documents | Map `fields.posts.value` — plain rows | Props panel (pick, reorder) |
-| **Repeater** | `array` + `of: 'json'` | Inline-authored items (slides, cards, FAQs) | `<Collection>` + `<Field>` on each item | Canvas (add, remove, reorder, click to edit) |
+Every object array is a list of records. Each row is a fields object plus a plain `id`. Edit `post.title` in the grid and you are editing the post. Which records are in the list, and their order, is edited in the props panel — not on the canvas.
 
-Scalar lists (tags, multi-select) are plain `.value` arrays edited in the props panel — same as reference lists.
-
-### Reference lists
-
-Rows are plain objects, not envelopes. Read them directly:
+Scalar lists (tags, multi-select) stay plain: `fields.tags` is `Field<string[]>`.
 
 ```tsx
+import { Field, Image, RichText } from '@amplifyup/sdk/react';
+
 export function LatestPosts({ fields }: { fields: Fields<{ heading: string; posts: Post[] }> }) {
   const posts = fields.posts.value ?? [];
   return (
@@ -321,8 +344,10 @@ export function LatestPosts({ fields }: { fields: Fields<{ heading: string; post
       <ul>
         {posts.map((post) => (
           <li key={post.id}>
-            <img src={post.mainImage?.url} alt={post.mainImage?.alt ?? ''} />
-            <a href={`/blog/${post.slug}`}>{post.title}</a>
+            <Image field={post.mainImage} />
+            <a href={`/blog/${post.slug}`}>
+              <Field field={post.title} />
+            </a>
           </li>
         ))}
       </ul>
@@ -332,75 +357,60 @@ export function LatestPosts({ fields }: { fields: Fields<{ heading: string; post
 ```
 
 ```tsx
-// ✗ — reference rows aren't editable inline; there's nothing for Field to bind to
-{posts.map((post) => <Field field={post.title} />)}
+// ✗ — Field expects a scalar, not the list or the row
+<Field field={fields.posts} />
+<Field field={post} />
 
-// ✗ — Collection is for repeaters
-<Collection field={fields.posts}>…</Collection>
+// ✓ — edit the record through its fields
+<Field field={post.title} />
+<Image field={post.mainImage} />
 ```
 
-The list itself (which posts, in what order) is edited in the props panel. When the component is selected on the canvas, the component outline is the affordance — you don't need to add one.
-
-### Repeaters
-
-Items **are** enveloped. `fields.slides.value[0].title` is `{ value, name: 'slides.0.title' }`. Render through `<Collection>`:
+Search or load-more rows from `queryContent` are the same shape. Render them with the same components — one renderer for both:
 
 ```tsx
-import { Collection, Field, Image } from '@amplifyup/sdk/react';
-
-export function Slideshow({
-  fields,
-}: {
-  fields: Fields<{ slides: Array<{ title: string; caption: string; image: ImageValue }> }>;
-}) {
-  return (
-    <Collection field={fields.slides}>
-      {(slide, i) => (
-        <figure className="slide" data-index={i}>
-          <Image field={slide.image} />
-          <figcaption>
-            <h2><Field field={slide.title} /></h2>
-            <Field field={slide.caption} className="text-sm" />
-          </figcaption>
-        </figure>
-      )}
-    </Collection>
-  );
-}
+const posts = hits ?? fields.posts.value ?? [];
+return posts.map((post) => (
+  <article key={post.id}>
+    <h2><Field field={post.title} /></h2>
+  </article>
+));
 ```
 
-On the live site `Collection` renders your children and nothing else — no wrapper element. In Composer it adds an empty-state placeholder and add / remove / reorder controls.
+### When a row is editable
 
-Need a wrapping `<ul>`? Put it outside:
+A row is editable when the SDK knows which record it came from. That happens automatically in two cases:
 
-```tsx
-<ul className="faq">
-  <Collection field={fields.questions}>
-    {(q) => (
-      <li>
-        <h3><Field field={q.question} /></h3>
-        <RichText field={q.answer} />
-      </li>
-    )}
-  </Collection>
-</ul>
-```
+| Rows came from | Editable in Composer? |
+| --- | --- |
+| A list prop on your component (curated or query connection) | Yes |
+| `queryContent` using the published spec from `{field}Pagination.spec` | Yes |
+| `queryContent` with a spec you assembled by hand, missing `providerId` or `entity` | No — renders as plain text |
+| Rows you fetched yourself from your CMS and passed in as props | No — renders as plain text |
 
-```tsx
-// ✗ — mapping .value skips the canvas chrome; items won't be addable in Composer
-{fields.slides.value.map((slide) => <Field field={slide.title} />)}
-```
+Read-only rows still render their text on the live site and in Composer. They just aren't clickable, and in development the SDK logs once per field:
 
-### Mixing a list with a runtime query
+```
+[AmplifyUp SDK] title has no write target; rendered read-only.
+```
 
-Search or "load more" results come from `queryContent`, which returns plain rows. Your reference list is also plain rows, so they share a renderer:
+If you see that and expected an editable field, the fix is upstream — use the published spec instead of a hand-built one, or bind the list to a connection in Composer. Do not try to add `ref` yourself.
 
 ```tsx
-const posts = hits ?? fields.posts.value ?? [];
-return <PostGrid posts={posts} />;
-```
+// ✓ — spec comes from the list prop Composer published; rows stay editable
+const hits = await queryContent({
+  trackingId,
+  route: '/insights',
+  spec: searchSpec(postsPagination, 'title', term),
+});
 
-No SDK component is involved on either path.
+// ✗ — hand-built spec with no connection behind it; rows render read-only
+const hits = await queryContent({
+  trackingId,
+  route: '/insights',
+  spec: { providerId: '', entity: '', filter: [], sort: [], limit: 10, offset: 0 },
+});
+```
 
 ---
 
@@ -409,19 +419,29 @@ No SDK component is involved on either path.
 A slot is a region where authors drop other components. Render it with `<Slot>`:
 
 ```tsx
-import { Field, Slot } from '@amplifyup/sdk/react';
+import { Slot } from '@amplifyup/sdk/react';
 
-export function TwoColumn({ fields, slots }) {
+export function TwoColumn() {
   return (
     <div className="grid grid-cols-2">
-      <div><Slot name="left" slots={slots} /></div>
-      <div><Slot name="right" slots={slots} /></div>
+      <div><Slot name="left" /></div>
+      <div><Slot name="right" /></div>
     </div>
   );
 }
 ```
 
-Slots hold components, not fields — nothing in a slot is read through `fields`.
+`<Slot>` takes only `name` and `className`. It reads the slot content from `ComponentContextProvider`, so you never thread a `slots` prop through your component.
+
+```tsx
+// ✗ — Slot has no `slots` prop
+<Slot name="left" slots={slots} />
+
+// ✓
+<Slot name="left" />
+```
+
+Slot names must match the slots declared on the component in AmplifyUp. Slots hold components, not fields — nothing in a slot is read through `fields`.
 
 ---
 
@@ -434,24 +454,47 @@ Slots hold components, not fields — nothing in a slot is read through `fields`
 | `{fields.x.value ?? 'default'}` in your code | expect the SDK to supply default copy |
 | `if (!fields.x.value) return null` to hide a component | wrap `Field` in conditional logic that hides the field in Composer |
 | `<h1><Field … /></h1>` | look for an `as` / `wrapper` prop |
-| `fields.posts.value.map(…)` for reference lists | `<Field>` or `<Collection>` on reference rows |
-| `<Collection>` for repeaters | `fields.slides.value.map(…)` for repeaters |
+| `<Field field={post.title} />` in a list | `<Field field={fields.posts} />` or `<Field field={post} />` |
 | `value` + `name` together for computed output | `value` alone, or `name` alone |
 | `<Image field={fields.cover} />` | `<img src={fields.cover.value.url} />` when it should be editable |
-| `queryContent` rows as plain data | treat query rows as `fields` |
+| `queryContent` rows through `<Field field={post.title} />` | treat query rows as raw CMS objects |
+| `spec: searchSpec(postsPagination, …)` from the published list prop | hand-build a `spec` and expect rows to stay editable |
+| `<Slot name="left" />` | `<Slot name="left" slots={slots} />` |
+| let the producer set `ref` | set, copy, or patch `ref` yourself |
 | `useInComposer()` to expose a field the live markup can't (CSS background, attribute, hidden panel) | fork the whole component's return on `inComposer` |
 | `if (!x.value && !inComposer) return null` | `if (!x.value) return null` — authors can't click what isn't rendered |
 
 ---
 
+## Console messages
+
+In development the SDK tells you exactly what is wrong. Production is silent.
+
+| Message | What it means | Fix |
+| --- | --- | --- |
+| `Field expects a scalar field. Did you mean <Field field={post.title} />?` | You passed a list or a whole row to `Field` / `RichText` / `Image` | Pass one scalar field off the row |
+| `title has no write target; rendered read-only.` | A row field the SDK can't trace to a record | Bind the list to a connection, or query with the published spec |
+| `Field value={…} requires name="…" for computed values` | You passed `value` without `name` | Add `name={fields.x.name}` |
+| `Field needs field={fields.yourProp} (or value + name for computed values)` | No binding at all | Pass `field=` |
+| `Slot "left" used outside ComponentContextProvider` | The component wasn't wrapped when rendered | Wrap it in `renderComponent` |
+
+---
+
 ## Types
 
 ```ts
 import type { Field, Fields, ImageValue } from '@amplifyup/sdk/react';
 
-type Field<T> = { value: T | null; name: string };
+type Field<T> = {
+  value: T;
+  name: string;
+  /** Write target — the record this field saves to. Page fields omit it. */
+  ref?: { providerId: string; entity: string; id: string };
+  /** Row field with no write target — display only in Composer. */
+  readOnly?: true;
+};
 
-type Fields<T> = { [K in keyof T]: /* Field<T[K]>, recursing into objects and repeater arrays */ };
+type Fields<T> = { [K in keyof T]: /* Field<T[K]>, recursing into objects and lists */ };
 ```
 
 Declare the schema shape once on the component and let inference do the rest:
@@ -462,14 +505,14 @@ type HeroFields = Fields<{
   heading: string;
   body: string;          // markdown → use <RichText>
   image: ImageValue;     // → use <Image>
-  ctas: Array<{ label: string; href: string }>;  // repeater
-  related: Post[];       // reference list — rows are plain Post
+  posts: Post[];         // list — each row is Fields<Post> & { id: string }
+  tags: string[];        // scalar list — Field<string[]>
 }>;
 
 export function Hero({ fields }: { fields: HeroFields }) { … }
 ```
 
-`fields.heading.value` is `string | null`. `fields.image.value` is `ImageValue | null`. `fields.ctas.value[0].label` is `Field<string>`. `fields.related.value[0]` is `Post`.
+`fields.heading.value` is `string`. `fields.image.value` is `ImageValue | null`. `fields.posts.value[0]` is `Fields<Post> & { id: string }`. `fields.posts.value[0].title` is `Field<string>` with `ref` pointing at that post.
 
 ---
 
@@ -532,7 +575,9 @@ const hits = await queryContent({
 });
 ```
 
-Only entities published with that route can be queried, and visitors only see published content. Results are plain rows — not `fields` envelopes, not canvas-editable. Also available from `@amplifyup/sdk/server`. See the [runtime queries guide](../../docs/sdk-site-setup.md#8-runtime-content-queries).
+Only entities published with that route can be queried, and visitors only see published content. Also available from `@amplifyup/sdk/server`. See the [runtime queries guide](../../docs/sdk-site-setup.md#8-runtime-content-queries).
+
+**Always start from `postsPagination.spec`.** `nextPageSpec` and `searchSpec` do that for you. The spec identifies the connection, and that is what makes the returned rows editable in Composer — see [when a row is editable](#when-a-row-is-editable). A spec you assemble by hand has no connection behind it, so its rows come back read-only.
 
 ## Track events
 

package/dist/AmplifyRenderer.d.mts

@@ -1,4 +1,40 @@
-import 'react';
-import 'react/jsx-runtime';
-export { A as AmplifyRenderer } from './AmplifyRenderer-TawbUIKZ.mjs';
-import './types-Db_eLrfU.mjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { L as LayoutComponentProps, P as PageConfig } from './types-C32MgOiv.mjs';
+
+interface AmplifyRendererProps {
+    /**
+     * Component renderer function that maps componentId to React component
+     * This is site-specific and must be provided by the developer
+     */
+    renderComponent: (componentId: string, props: LayoutComponentProps, slots?: Record<string, ReactNode>, context?: {
+        layoutNodeId: string;
+    }) => ReactNode;
+    /**
+     * Optional page config for server-side rendering (SSR/SSG)
+     * If provided, the component will use this instead of fetching client-side
+     */
+    pageConfig?: PageConfig;
+    /**
+     * Optional loading component
+     */
+    loadingComponent?: ReactNode;
+    /**
+     * Optional error component
+     */
+    errorComponent?: (error: string) => ReactNode;
+    /**
+     * Optional empty state component (when no content is configured)
+     */
+    emptyComponent?: ReactNode;
+    /**
+     * Force Composer page-slot wrapper (avoids SSR miss when window isn't available yet).
+     * When true, root components stay under [data-slot-source="page"] so hierarchy can climb to Page.
+     */
+    composerPreview?: boolean;
+}
+declare function AmplifyRendererInner({ renderComponent, pageConfig: serverPageConfig, loadingComponent, errorComponent, emptyComponent, composerPreview, }: AmplifyRendererProps): react_jsx_runtime.JSX.Element | null;
+declare const AmplifyRenderer: react.MemoExoticComponent<typeof AmplifyRendererInner>;
+
+export { AmplifyRenderer };

package/dist/AmplifyRenderer.d.ts

@@ -1,4 +1,40 @@
-import 'react';
-import 'react/jsx-runtime';
-export { A as AmplifyRenderer } from './AmplifyRenderer-Bwob7ICJ.js';
-import './types-Db_eLrfU.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { L as LayoutComponentProps, P as PageConfig } from './types-C32MgOiv.js';
+
+interface AmplifyRendererProps {
+    /**
+     * Component renderer function that maps componentId to React component
+     * This is site-specific and must be provided by the developer
+     */
+    renderComponent: (componentId: string, props: LayoutComponentProps, slots?: Record<string, ReactNode>, context?: {
+        layoutNodeId: string;
+    }) => ReactNode;
+    /**
+     * Optional page config for server-side rendering (SSR/SSG)
+     * If provided, the component will use this instead of fetching client-side
+     */
+    pageConfig?: PageConfig;
+    /**
+     * Optional loading component
+     */
+    loadingComponent?: ReactNode;
+    /**
+     * Optional error component
+     */
+    errorComponent?: (error: string) => ReactNode;
+    /**
+     * Optional empty state component (when no content is configured)
+     */
+    emptyComponent?: ReactNode;
+    /**
+     * Force Composer page-slot wrapper (avoids SSR miss when window isn't available yet).
+     * When true, root components stay under [data-slot-source="page"] so hierarchy can climb to Page.
+     */
+    composerPreview?: boolean;
+}
+declare function AmplifyRendererInner({ renderComponent, pageConfig: serverPageConfig, loadingComponent, errorComponent, emptyComponent, composerPreview, }: AmplifyRendererProps): react_jsx_runtime.JSX.Element | null;
+declare const AmplifyRenderer: react.MemoExoticComponent<typeof AmplifyRendererInner>;
+
+export { AmplifyRenderer };