@contentful/experiences-svelte 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.5.1 (2026-08-07)
+
+### 🚀 Features
+
+- expose slot children as an array instead of a single wrapping node ([#122](https://github.com/contentful/experiences/pull/122))
+
 ## 0.5.0 (2026-08-07)
 
 ### 🩹 Fixes

package/README.md

@@ -35,7 +35,7 @@ resolveExperience(payload, config, opts?); // Async; walks payload, runs resolve
 ServerExperienceRenderer; // SSR-safe; active viewport seeded from initialViewportId
 ClientExperienceRenderer; // Subscribes to window.matchMedia via runes
 MissingComponent; // Default fallback for unregistered component types
-NodesRenderer; // Exposed so you can render non-`children` slots manually
+NodesRenderer; // Exposed so you can render non-`children` slots manually (see Slot children)
 useActiveViewport; // Rune-backed reactive object; you'll rarely need it directly
 ```
 
@@ -124,6 +124,37 @@ export const experienceConfig: Config = { components, resolveToken };
 <ServerExperienceRenderer experience={data.experience} config={experienceConfig} />
 ```
 
+### Slot children
+
+A component's default slot children arrive as an **array of Snippets** (`Snippet[]`), one per child — not a single wrapping Snippet. For the common "just render them" case, iterate the array with `{#each}` and `{@render}`; to wrap, reorder, or drop children individually, do it inside that loop.
+
+```svelte
+<!-- Section.svelte -->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  let { children }: { children?: Snippet[] } = $props();
+</script>
+
+<!-- Common case — render them all: -->
+<div>
+  {#each children ?? [] as child}
+    {@render child()}
+  {/each}
+</div>
+
+<!-- Or take control of each child: -->
+<!--
+<div>
+  {#each children ?? [] as child, i}
+    <div class="cell">{@render child()}</div>
+  {/each}
+</div>
+-->
+```
+
+The default slot is injected as the `children` prop. Any **additional named slots** are not auto-injected — reach them from the raw payload via `getContentfulComponent().slots` (a `Record<string, PortableRenderNode[]>`) and render them yourself with `NodesRenderer`.
+
 For the full getting-started walkthrough, the merge-precedence rules, viewport handling, and design rationale, see the [root README](../../README.md) and [`AGENTS.md`](../../AGENTS.md).
 
 ---

package/dist/NodeRenderer.svelte

@@ -23,7 +23,7 @@
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
-    children: Snippet;
+    children: Snippet[];
   }
 
   let { node, config, experience, renderUnknown, children }: NodeRendererProps = $props();

package/dist/NodeRenderer.svelte.d.ts

@@ -7,7 +7,7 @@ interface NodeRendererProps {
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
-    children: Snippet;
+    children: Snippet[];
 }
 declare const NodeRenderer: import("svelte").Component<NodeRendererProps, {}, "">;
 type NodeRenderer = ReturnType<typeof NodeRenderer>;

package/dist/NodeRenderer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodeRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,iBAAiB;IACzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAoEH,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"NodeRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodeRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,iBAAiB;IACzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAoEH,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/NodesRenderer.svelte

@@ -1,22 +1,17 @@
 <!--
  * Recursive renderer over PortableRenderNodes. Customer components receive
  * the merged content / design / resolveData prop bag plus the default
- * `children` slot as a named Snippet:
+ * `children` slot as an ARRAY of Snippets — one zero-arg Snippet per
+ * pre-rendered child node — declared as `children?: Snippet[]`. A component
+ * renders them all with an each-block + @render, or maps/filters/wraps the
+ * children individually. The array mirrors the React adapter's ReactNode[]
+ * slot contract; see the README for the consuming-a-slot example.
  *
- *     <script lang="ts">
- *       import type { Snippet } from 'svelte';
- *       let { text, children }: { text?: string; children?: Snippet } = $props();
- *     </script>
- *     <button>
- *       {text}
- *       {@render children?.()}
- *     </button>
- *
- * Only the `children` slot is rendered automatically — Svelte 5 Snippets are
- * compile-time entities, so the renderer can't synthesize an unbounded set
- * of named Snippet props from runtime payload data. Additional named slots
- * are reachable through `getContentfulComponent().slots` and can be rendered
- * with the exported `<NodesRenderer />` (see README).
+ * Only the default `children` slot is injected as a prop — Svelte 5 Snippets
+ * are compile-time entities, so the renderer can't synthesize an unbounded
+ * set of named Snippet props from runtime payload data. Additional named
+ * slots are reachable through `getContentfulComponent().slots` and can be
+ * rendered with the exported NodesRenderer (see README).
  *
  * The Experience runtime context and the raw Contentful payload are read
  * via `getExperience` / `getContentfulComponent`.
@@ -25,10 +20,11 @@
  * the active viewport is sourced (initial seed vs reactive matchMedia).
 -->
 <script lang="ts">
+  import type { Snippet } from 'svelte';
+
   import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
 
   import NodeRenderer from './NodeRenderer.svelte';
-  import NodesRenderer from './NodesRenderer.svelte';
   import type { RenderUnknown } from './component-props.js';
   import type { Config, RenderContext } from './types.js';
 
@@ -40,12 +36,24 @@
   }
 
   let { nodes, config, experience, renderUnknown }: NodesRendererProps = $props();
+
+  // Curry the parameterized `renderNode` snippet into a zero-arg Snippet bound
+  // to one node. Svelte 5 invokes a snippet as `(anchor, ...argGetters)`, so we
+  // forward the anchor and supply the node through a getter. This is the one
+  // spot that leans on Svelte's snippet calling convention; pinned by the
+  // `children`-array tests in server-renderer.test.ts.
+  function toChildSnippet(node: PortableRenderNode): Snippet {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- programmatic snippet construction; see note above.
+    return ((anchor: unknown) => (renderNode as any)(anchor, () => node)) as Snippet;
+  }
 </script>
 
-{#each nodes as node, index (node.nodeId ?? index)}
-  {#snippet children()}
-    {@const childrenNodes = (node.slots.children ?? []) as PortableRenderNode[]}
-    <NodesRenderer nodes={childrenNodes} {config} {experience} {renderUnknown} />
-  {/snippet}
+{#snippet renderNode(node: PortableRenderNode)}
+  {@const childNodes = (node.slots.children ?? []) as PortableRenderNode[]}
+  {@const children = childNodes.map(toChildSnippet)}
   <NodeRenderer {node} {config} {experience} {renderUnknown} {children} />
+{/snippet}
+
+{#each nodes as node, index (node.nodeId ?? index)}
+  {@render renderNode(node)}
 {/each}

package/dist/NodesRenderer.svelte.d.ts

@@ -1,5 +1,4 @@
 import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
-import NodesRenderer from './NodesRenderer.svelte';
 import type { RenderUnknown } from './component-props.js';
 import type { Config, RenderContext } from './types.js';
 interface NodesRendererProps {

package/dist/NodesRenderer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodesRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodesRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAG3E,OAAO,aAAa,MAAM,wBAAwB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGtD,UAAU,kBAAkB;IAC1B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;CAC9B;AAwBH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"NodesRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodesRenderer.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAG3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGtD,UAAU,kBAAkB;IAC1B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;CAC9B;AAqCH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/server-renderer.test.js

@@ -9,6 +9,7 @@ import HeadingFixture from './test-fixtures/HeadingFixture.svelte';
 import ItemFixture from './test-fixtures/ItemFixture.svelte';
 import PrecedenceFixture from './test-fixtures/PrecedenceFixture.svelte';
 import ExperienceTemplateFixture from './test-fixtures/ExperienceTemplateFixture.svelte';
+import WrappingContainerFixture from './test-fixtures/WrappingContainerFixture.svelte';
 import { captureSink } from './test-fixtures/capture-sink.js';
 import { toCss } from './design-utils.js';
 const VIEWPORTS = [
@@ -313,6 +314,66 @@ describe('ServerExperienceRenderer', () => {
         warn.mockRestore();
     });
 });
+describe('ServerExperienceRenderer — slot children as an array', () => {
+    const childrenPayload = () => ({
+        viewports: VIEWPORTS,
+        nodes: [
+            componentNode('contentful-container', {
+                id: 'c',
+                slots: {
+                    children: [
+                        componentNode('contentful-heading', {
+                            id: 'a',
+                            contentProperties: { text: 'one' },
+                        }),
+                        componentNode('contentful-heading', {
+                            id: 'b',
+                            contentProperties: { text: 'two' },
+                        }),
+                        componentNode('contentful-heading', {
+                            id: 'd',
+                            contentProperties: { text: 'three' },
+                        }),
+                    ],
+                },
+            }),
+        ],
+    });
+    it('passes slot children as a Snippet[] a component can wrap individually', async () => {
+        const cfg = {
+            components: {
+                'contentful-container': WrappingContainerFixture,
+                'contentful-heading': HeadingFixture,
+            },
+        };
+        const plan = await resolveExperience(childrenPayload(), cfg);
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config: cfg },
+        });
+        // The component received a real array of the right length.
+        expect(captureSink[0].props.childrenIsArray).toBe(true);
+        expect(captureSink[0].props.childCount).toBe(3);
+        // Each child got its own wrapper — proves per-child rendering control.
+        const wrappers = container.querySelectorAll('.wrap');
+        expect(wrappers.length).toBe(3);
+        expect(container.querySelector('[data-index="0"]')).not.toBeNull();
+        expect(container.querySelector('[data-index="2"]')).not.toBeNull();
+        expect(container.textContent).toContain('one');
+        expect(container.textContent).toContain('three');
+    });
+    it('renders an empty container when the slot has no children', async () => {
+        const cfg = {
+            components: { 'contentful-container': WrappingContainerFixture },
+        };
+        const plan = await resolveExperience({ viewports: VIEWPORTS, nodes: [componentNode('contentful-container', { id: 'c' })] }, cfg);
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config: cfg },
+        });
+        expect(captureSink[0].props.childCount).toBe(0);
+        expect(container.querySelectorAll('.wrap').length).toBe(0);
+        expect(container.querySelector('[data-container]')).not.toBeNull();
+    });
+});
 describe('ServerExperienceRenderer — bare-component registrations', () => {
     it('accepts a bare Svelte component as a registry entry', async () => {
         const cfg = { components: { item: PrecedenceFixture } };

package/dist/test-fixtures/ContainerFixture.svelte

@@ -3,10 +3,12 @@
 
   import { getDesignValues } from '../get-design-values.js';
 
-  let { children }: { children?: Snippet } = $props();
+  let { children }: { children?: Snippet[] } = $props();
   const design = $derived(getDesignValues());
 </script>
 
 <div data-padding={design.cfPadding as string}>
-  {#if children}{@render children()}{/if}
+  {#each children ?? [] as child}
+    {@render child()}
+  {/each}
 </div>

package/dist/test-fixtures/ContainerFixture.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
-    children?: Snippet;
+    children?: Snippet[];
 };
 declare const ContainerFixture: import("svelte").Component<$$ComponentProps, {}, "">;
 type ContainerFixture = ReturnType<typeof ContainerFixture>;

package/dist/test-fixtures/ContainerFixture.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContainerFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/ContainerFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIrC,KAAK,gBAAgB,GAAI;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgBjD,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"ContainerFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/ContainerFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIrC,KAAK,gBAAgB,GAAI;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AAkBnD,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/test-fixtures/WrappingContainerFixture.svelte

@@ -0,0 +1,27 @@
+<!--
+  Test fixture: proves slot children arrive as an array of Snippets that a
+  component can iterate and wrap individually. Also records the received array
+  length in the capture sink.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  import { getContentfulComponent, getExperience } from '../context.js';
+  import { captureSink } from './capture-sink.js';
+
+  let { children }: { children?: Snippet[] } = $props();
+
+  captureSink.push({
+    props: { childCount: children?.length ?? 0, childrenIsArray: Array.isArray(children) },
+    experience: getExperience(),
+    contentful: getContentfulComponent(),
+  });
+</script>
+
+<div data-container>
+  {#each children ?? [] as child, i}
+    <div class="wrap" data-index={i}>
+      {@render child()}
+    </div>
+  {/each}
+</div>

package/dist/test-fixtures/WrappingContainerFixture.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    children?: Snippet[];
+};
+declare const WrappingContainerFixture: import("svelte").Component<$$ComponentProps, {}, "">;
+type WrappingContainerFixture = ReturnType<typeof WrappingContainerFixture>;
+export default WrappingContainerFixture;
+//# sourceMappingURL=WrappingContainerFixture.svelte.d.ts.map

package/dist/test-fixtures/WrappingContainerFixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WrappingContainerFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/WrappingContainerFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKrC,KAAK,gBAAgB,GAAI;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AA2BnD,QAAA,MAAM,wBAAwB,sDAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-svelte",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Svelte adapter for Contentful Experiences — Server and Client renderers over a PortableRenderPlan",
   "license": "MIT",
   "type": "module",