@amplifyup/sdk 0.1.62 → 0.1.64

package/README.md

@@ -61,10 +61,10 @@ export default function Page() {
 }
 ```
 
-### 3. Components use Field / Slot
+### 3. Write a component
 
 ```tsx
-import { Field, Slot } from '@amplifyup/sdk/react';
+import { Field } from '@amplifyup/sdk/react';
 import type { Fields } from '@amplifyup/sdk/react';
 
 export function Hero({ fields }: { fields: Fields<{ heading: string }> }) {
@@ -78,13 +78,443 @@ export function Hero({ fields }: { fields: Fields<{ heading: string }> }) {
 }
 ```
 
-AmplifyUp passes `fields` on the component props. Use
-`<Field field={fields.heading} />` to show and edit, or
-`{fields.heading.value}` to render the text. You do not pass `name` unless
-you computed the value yourself. An empty field renders nothing on the live
-site; in Composer it stays clickable. Default copy belongs in your component
-(`{fields.heading.value ?? 'Welcome'}`). Connect content in Composer, then
-**Deploy** so the live site can serve the page.
+Connect content in Composer, then **Deploy** so the live site can serve the page.
+
+That's the whole loop. The rest of this section is the detail.
+
+---
+
+## Working with `fields`
+
+Every component receives a `fields` prop. It is not raw CMS data — every entry is a **field envelope**:
+
+```ts
+fields.heading
+// → { value: 'Welcome to AmplifyUp', name: 'heading' }
+
+fields.hero.image
+// → { value: { url: '…', alt: '…' }, name: '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
+// Editable — use an SDK component
+<Field field={fields.heading} />
+
+// Display only — read .value
+<title>{fields.heading.value}</title>
+```
+
+Use the component when the field should be clickable in Composer. Use `.value` when it shouldn't — meta tags, `aria-label`, an `href`, a condition, anything that isn't visible text.
+
+```tsx
+export function Card({ fields }: { fields: Fields<{ title: string; link: string; image: ImageValue }> }) {
+  return (
+    <a href={fields.link.value ?? '#'} aria-label={fields.title.value ?? undefined}>
+      <Image field={fields.image} />
+      <h3><Field field={fields.title} /></h3>
+    </a>
+  );
+}
+```
+
+### SDK field components
+
+| Component | Field type | Renders |
+| --- | --- | --- |
+| `<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.
+
+```tsx
+<Field field={fields.eyebrow} className="text-xs uppercase" />
+<RichText field={fields.body} className="prose" />
+<Image field={fields.cover} className="rounded-lg" loading="lazy" />
+```
+
+`<Field>` is scalar-only. Passing a list is a type error:
+
+```tsx
+// ✗ Field<string[]> is not assignable to Field<string | number>
+<Field field={fields.tags} />
+```
+
+### Empty fields
+
+An empty field renders **nothing** on the live site and a clickable placeholder in Composer. The SDK never invents default copy.
+
+```tsx
+// A new page, `subheading` not yet filled in:
+
+<Field field={fields.subheading} />
+// live:      (nothing)
+// Composer:  clickable empty placeholder
+```
+
+If you want a default, it's yours to write, and it reads from `.value`:
+
+```tsx
+// ✓ your default, in your code
+<p>{fields.subheading.value ?? 'Built for teams that ship.'}</p>
+
+// ✓ hide the whole component when the key field is empty
+export function Banner({ fields }: { fields: Fields<{ message: string }> }) {
+  if (!fields.message.value) return null;
+  return <div className="banner"><Field field={fields.message} /></div>;
+}
+```
+
+Why no `fallback` prop: a fallback turns "this field was never populated" into "this field says *Welcome*". Nobody notices until a customer does. Empty should look empty.
+
+### Wrapper elements
+
+`<Field>` renders an inline `<span>`, never a heading or paragraph, so you supply the semantic tag around it:
+
+```tsx
+// ✓
+<h1><Field field={fields.heading} /></h1>
+<p className="lead"><Field field={fields.intro} /></p>
+
+// ✗ — Field has no `as` prop; put the element around it
+<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
+{fields.intro.value ? (
+  <p className="lead"><Field field={fields.intro} /></p>
+) : null}
+```
+
+### Computed values
+
+Occasionally what you display isn't a field — it's derived from one. Then you pass `value` and must also pass `name` so Composer knows which field a click edits:
+
+```tsx
+// Show a formatted price but edit the raw number
+<Field
+  value={formatPrice(fields.price.value)}
+  name={fields.price.name}
+/>
+```
+
+`name` is only accepted alongside `value`. This is the one place you write it.
+
+```tsx
+// ✗ — redundant, and a type error
+<Field field={fields.price} name="price" />
+
+// ✗ — value without name has nothing to bind to
+<Field value={formatPrice(fields.price.value)} />
+```
+
+### Rendering differently in Composer
+
+Most components render the same everywhere. Sometimes the live markup can't host an editable field — the text is a CSS background, an SVG `<title>`, a `<meta>` tag, an attribute, or it's behind interaction (a closed accordion, an auto-playing carousel). In Composer you still need something the author can click.
+
+`useInComposer()` tells you which mode you're in:
+
+```tsx
+import { Field, Image, useInComposer } from '@amplifyup/sdk/react';
+
+export function HeroBackground({ fields }: { fields: Fields<{ heading: string; image: ImageValue }> }) {
+  const inComposer = useInComposer();
+
+  return (
+    <section
+      className="hero"
+      style={{ backgroundImage: `url(${fields.image.value?.url ?? ''})` }}
+    >
+      {/* Live: image is a CSS background. Composer: also render it so it's clickable. */}
+      {inComposer ? <Image field={fields.image} className="hidden" /> : null}
+      <h1><Field field={fields.heading} /></h1>
+    </section>
+  );
+}
+```
+
+Other common cases:
+
+```tsx
+// Attribute on the live site, editable in Composer
+const inComposer = useInComposer();
+return (
+  <>
+    <button aria-label={fields.label.value ?? undefined}>
+      <Icon />
+      {inComposer ? <Field field={fields.label} /> : null}
+    </button>
+  </>
+);
+```
+
+```tsx
+// Component that hides itself when empty on live, but stays visible for authors
+export function Announcement({ fields }: { fields: Fields<{ message: string }> }) {
+  const inComposer = useInComposer();
+  if (!fields.message.value && !inComposer) return null;
+  return <div className="announcement"><Field field={fields.message} /></div>;
+}
+```
+
+```tsx
+// Interaction that fights the canvas — turn it off in Composer
+export function Carousel({ fields }) {
+  const inComposer = useInComposer();
+  return (
+    <>
+      {(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>` 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.
+
+```tsx
+// ✗ — heading is visible on live; no reason to fork
+{inComposer ? <Field field={fields.heading} /> : fields.heading.value}
+
+// ✓
+<Field field={fields.heading} />
+```
+
+---
+
+## Lists
+
+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) 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 (
+    <section>
+      <h2><Field field={fields.heading} /></h2>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <Image field={post.mainImage} />
+            <a href={`/blog/${post.slug}`}>
+              <Field field={post.title} />
+            </a>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+```
+
+```tsx
+// ✗ — Field expects a scalar, not the list or the row
+<Field field={fields.posts} />
+<Field field={post} />
+
+// ✓ — edit the record through its fields
+<Field field={post.title} />
+<Image field={post.mainImage} />
+```
+
+Search or load-more rows from `queryContent` are the same shape. Render them with the same components — one renderer for both:
+
+```tsx
+const posts = hits ?? fields.posts.value ?? [];
+return posts.map((post) => (
+  <article key={post.id}>
+    <h2><Field field={post.title} /></h2>
+  </article>
+));
+```
+
+### When a row is editable
+
+A row is editable when the SDK knows which record it came from. That happens automatically in two cases:
+
+| 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 |
+
+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:
+
+```
+[AmplifyUp SDK] title has no write target; rendered read-only.
+```
+
+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
+// ✓ — spec comes from the list prop Composer published; rows stay editable
+const hits = await queryContent({
+  trackingId,
+  route: '/insights',
+  spec: searchSpec(postsPagination, 'title', term),
+});
+
+// ✗ — 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 },
+});
+```
+
+---
+
+## Slots
+
+A slot is a region where authors drop other components. Render it with `<Slot>`:
+
+```tsx
+import { Slot } from '@amplifyup/sdk/react';
+
+export function TwoColumn() {
+  return (
+    <div className="grid grid-cols-2">
+      <div><Slot name="left" /></div>
+      <div><Slot name="right" /></div>
+    </div>
+  );
+}
+```
+
+`<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`.
+
+---
+
+## Do / Don't
+
+| Do | Don't |
+| --- | --- |
+| `<Field field={fields.heading} />` | `<Field field={fields.heading} name="heading" />` |
+| `{fields.heading.value}` for non-visible uses | `{fields.heading}` as a JSX child (it's an object) |
+| `{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 |
+| `<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 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;
+  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 lists */ };
+```
+
+Declare the schema shape once on the component and let inference do the rest:
+
+```ts
+type HeroFields = Fields<{
+  eyebrow: string;
+  heading: string;
+  body: string;          // markdown → use <RichText>
+  image: ImageValue;     // → use <Image>
+  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`. `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.
+
+---
 
 ## Content sources
 
@@ -95,6 +525,8 @@ site; in Composer it stays clickable. Default copy belongs in your component
 | Composer preview | Orchestrator (Control Plane) layout provider | `?preview=true` / Composer iframe |
 | Runtime queries | Edge `/v1/query` | `queryContent` — search, load more, pickers |
 
+Field envelopes are attached once, when the SDK reads the Edge response. Edge's JSON is raw; you never see it that way if you go through `AmplifyPageContent` or `fetchPageConfigServer`. If you call `fetchEdgeResolve` directly you get raw props and must map them yourself — prefer the documented path.
+
 ## Pattern pages (From page)
 
 Components using Composer **From page** require `pageContext` on the provider (or `init`) so the first paint and first page view include fields. Late `setPageContext` is fine for subsequent events, not for rendering those components.
@@ -116,7 +548,7 @@ Components using Composer **From page** require `pageContext` on the provider (o
 
 Pass `pageContext` at provider/init for From-page components. Do not wait until after first paint. Fixed (static) page fields still attach to events when `pageContext` is omitted.
 
-The SDK maps Edge’s resolved tree into `layoutTree` and renders it. Edge already applies personalization and CMS projection — the site does not call CMS or Decision APIs for layout. After paint, the overlay calls `POST /v1/select` (or `selectVariants()`) then `/v1/resolve?variants=` so decisions stay on the edge (`clientPersonalization`).
+The SDK maps Edge's resolved tree into `layoutTree` and renders it. Edge already applies personalization and CMS projection — the site does not call CMS or Decision APIs for layout. After paint, the overlay calls `POST /v1/select` (or `selectVariants()`) then `/v1/resolve?variants=` so decisions stay on the edge (`clientPersonalization`).
 
 ## Runtime queries
 
@@ -143,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` objects — they are 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
 
@@ -167,4 +601,4 @@ React context: `useAmplifyUp()` → `{ pageConfig, loading, error, source, meta
 
 ## License
 
-MIT
+MIT

package/dist/AmplifyRenderer.d.mts

@@ -1,4 +1,40 @@
-import 'react';
-import 'react/jsx-runtime';
-export { A as AmplifyRenderer } from './AmplifyRenderer-W7eqltSj.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-BQ8-H2H4.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 };