@picked/client 0.0.64-next.2 → 0.0.64-next.4

package/dist/docs/sdk/ssr/rendering-and-hydration.md

@@ -0,0 +1,141 @@
+---
+layout: docs
+---
+
+# Rendering & Hydration
+
+Seed a Picked client from the server snapshot, render your slots, and hydrate. React and Svelte below.
+
+## React: PickedProvider
+
+`PickedProvider` supplies a client to descendant components. Its props are a union of two construction modes:
+
+| Props | Mode | Description |
+| --- | --- | --- |
+| `{ options, snapshot? }` | Create | The provider calls `createClient(options)` and hydrates it from the snapshot. |
+| `{ client, snapshot? }` | Adopt | The provider uses an existing client, such as an app-wide global, and optionally seeds it from the snapshot. |
+
+The provider seeds synchronously, so the server render and the client's first paint produce the same markup. In the browser it calls `client.start()` from an effect; `start()` is idempotent, so an already-started client is left untouched.
+
+```tsx
+import { PickedProvider, ExperienceSlot } from '@picked/react'
+
+<PickedProvider options={options} snapshot={snapshot}>
+  <ExperienceSlot name="page" />
+</PickedProvider>
+```
+
+## Svelte: setPickedContext
+
+`setPickedContext` is the Svelte-idiomatic equivalent. Call it once at the top of a component's `<script>`. It takes the same two modes, `{ options, snapshot? }` or `{ client, snapshot? }`, and returns the client.
+
+```svelte
+<script lang="ts">
+  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
+
+  setPickedContext({ options, snapshot })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+## Placing the slot
+
+Drop `<ExperienceSlot name="page" />` where the Page should render. The slot renders every experience that targets it and whose condition is active. See [Slots & Placements](/sdk/ssr/slots-and-placements) for how a slot selects and orders experiences.
+
+## Rendering the page component
+
+The SDK does not map content to components. You own the component a Page renders and register it under the name the Page uses, which is the same name the dashboard Page Layout maps to. The component reads the resolved entry data through the content hook: `useStepContent()` in React and `getStepContent()` in Svelte.
+
+:::code-group
+
+```tsx [React]
+import { useStepContent } from '@picked/react/hooks'
+
+export function CMSPage() {
+  const content = useStepContent()
+  if (!content) {
+    return <p>Loading page content…</p>
+  }
+
+  const title = typeof content.title === 'string' ? content.title : ''
+  return (
+    <article>
+      <h1>{title}</h1>
+    </article>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+</script>
+
+{#if $content}
+  <article>
+    <h1>{typeof $content.title === 'string' ? $content.title : ''}</h1>
+  </article>
+{:else}
+  <p>Loading page content…</p>
+{/if}
+```
+
+:::
+
+`useStepContent()` returns the entry's `data` object directly, or `null` while no content is registered. `getStepContent()` returns a store you read with `$content`.
+
+## Full example
+
+This is the verified page-slot wiring. The page client fetches the project config and renders whichever Page experience targets `.picked-slot-page` and matches the current URL.
+
+:::code-group
+
+```tsx [React]
+import type { CreateClientOptions } from '@picked/client'
+import type { PickedSnapshot } from '@picked/client/server'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
+import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
+import { CMSPage } from './CMSPage'
+
+const options = {
+  projectId: 'sdk-cvly-x',
+  components: { CMSPage: adaptReactComponent(CMSPage) },
+  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+} satisfies CreateClientOptions
+
+export function PageSlot({ snapshot }: { snapshot?: PickedSnapshot }) {
+  return (
+    <PickedProvider options={options} snapshot={snapshot}>
+      <ExperienceSlot name="page" />
+    </PickedProvider>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import type { CreateClientOptions } from '@picked/client'
+  import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+  import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
+  import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
+  import CMSPage from './CMSPage.svelte'
+
+  const options = {
+    projectId: 'sdk-cvly-x',
+    components: { CMSPage: adaptSvelteComponent(CMSPage) },
+    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+  } satisfies CreateClientOptions
+
+  setPickedContext({ options })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+:::
+
+For the end-to-end version with the server snapshot, see [Build a Personalized Page](/guides/build-a-personalized-page). For the snapshot reference, see [Server Snapshot](/sdk/ssr/serialize). For how experiences register, see [SDK Experiences](/sdk/experiences).

package/dist/docs/sdk/ssr/serialize.md

@@ -0,0 +1,86 @@
+---
+layout: docs
+---
+
+# Server Snapshot
+
+`serialize()` evaluates which experiences match a URL and fetches their content on the server, returning a plain-JSON snapshot you pass to the client.
+
+## serialize(client, params)
+
+```ts
+import { createClient } from '@picked/client'
+import { serialize } from '@picked/client/server'
+
+const client = createClient(options)
+
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: '/promo' } },
+})
+```
+
+`serialize()` registers the project config on the client synchronously, evaluates each experience's condition against `attributes.location`, fetches content for the experiences whose steps reference layout content, dedupes the content blobs by id, and returns a `PickedSnapshot`. It expects a per-request client; concurrent calls on a single client are not supported.
+
+```ts
+serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `projectConfig` | `ProjectConfig` | required | The published or preview config to register and select against. |
+| `attributes.location` | `Partial<SerializeLocation>` | none | URL fields injected into the selection context, such as `pathname`. |
+| `getContent` | `SerializeGetContent` | runtime API | A custom content fetcher used in place of the runtime API. |
+| `previewToken` | `string` | none | Forwarded to the content fetch so preview content resolves during preview SSR. |
+| `timeoutMs` | `number` | `10000` | Per-content-fetch timeout. On timeout the blob is skipped and the render proceeds. |
+
+`SerializeLocation` carries the plain URL fields `href`, `pathname`, `search`, `hostname`, `origin`, `protocol`, `port`, `host`, and `hash`. Pass only the ones your conditions read.
+
+## The snapshot
+
+```ts
+interface PickedSnapshot {
+  versionId: string | null
+  projectConfig: ProjectConfig
+  content: ContentBlob[]
+  conditionResults: Record<string, boolean>
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `versionId` | The project version the snapshot was selected against, or `null` when unknown (for example on preview). |
+| `projectConfig` | The config the server selected with. It travels so the client renders against the exact same config. |
+| `content` | The deduped content blobs for the selected experiences. |
+| `conditionResults` | The memoized condition results, keyed by rule hash, so the client reuses the server's selection. |
+
+The snapshot is plain JSON. Serialize it into your HTML response with `JSON.stringify` and read it back on the client.
+
+## Passing the snapshot to the client
+
+Embed the snapshot in your HTML payload, then hand it to the provider (React) or context (Svelte):
+
+```ts
+const html = `
+  <div id="root">${appHtml}</div>
+  <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
+`
+```
+
+On the client, read `window.__PICKED__` and pass it as the `snapshot` prop. See [Rendering & Hydration](/sdk/ssr/rendering-and-hydration).
+
+## Preview rendering
+
+Pass `previewToken` so unpublished content resolves during preview SSR. The server has no access to the request's query string, so the token cannot be recovered any other way:
+
+```ts
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: '/promo' } },
+  previewToken,
+})
+```
+
+Use the same token when you fetch `projectConfig` from the [Delivery API](/delivery-api), so the config and the content come from the same preview surface.

package/dist/docs/sdk/ssr/slots-and-placements.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+---
+
+# Slots & Placements
+
+A slot is a named mount point. `<ExperienceSlot name="page" />` renders every experience that targets that slot and whose condition matches.
+
+## What a slot is
+
+A slot's `name` maps to the `.picked-slot-<name>` selector. `<ExperienceSlot name="page" />` renders every experience whose target selector is `.picked-slot-page` and whose condition is active. The slot reads each experience's active state from the seeded snapshot, so it renders synchronously during server-side rendering and the hydration first paint.
+
+```tsx
+<ExperienceSlot name="page" />
+```
+
+## Targeting an experience to a slot
+
+Set the experience's target selector to `.picked-slot-<name>`. An experience targeting `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The slot name and the selector suffix must match.
+
+## Placement order
+
+When several experiences target the same slot, they render in placement precedence:
+
+```
+replace -> before -> prepend -> append -> after
+```
+
+`replace` wins. If an active experience uses the `replace` placement, it renders alone and replaces every other match in the slot. Otherwise every active experience renders, in placement order.
+
+## Multiple experiences in one slot
+
+The slot collects each experience that targets its selector, drops any whose condition is not active, and sorts the rest by placement. If a `replace` experience is among the active ones, only that experience renders. With no active `replace`, the slot renders all active experiences in `before, prepend, append, after` order.
+
+This lets one Page take over a slot with `replace`, while other slots can stack several experiences by using the non-`replace` placements. Conditions decide which experiences are active; see [Conditions](/conditions).

package/dist/docs/steps.mdx

@@ -31,6 +31,8 @@ The key is a unique identifier used in your application. It's set once and can't
 
 **Layout Name**: The name of the component layout used to render this step. For example, `card`, `modal`, or `fullscreen`.
 
+A step can also carry a **Step Layout**, a reusable CMS schema that backs the step with a Content Entry. See [Page & Step Layouts](/content/layouts).
+
 ## Assign fields
 
 In the flow builder, drag a field from the entity browser onto a step node. The field appears in the step's **Assigned Fields** list in the inspector.

package/dist/{dom-DjfSrkpp.js → dom-BwmTHeT7.js}

@@ -1,4 +1,4 @@
-import { f as e, i as t, u as n } from "./supports-BgjwyijI.js";
+import { f as e, i as t, u as n } from "./supports-CO9bJGNl.js";
 //#region src/utils/dom.ts
 function r(n) {
 	return !e() || !t() ? [] : Array.from(window.document.querySelectorAll(n)).filter((e) => e instanceof HTMLElement);

package/dist/{dom-sqnnO-CT.cjs → dom-CDrHc_j9.cjs}

@@ -1 +1 @@
-const e=require(`./supports-34OzZK5j.cjs`);function t(t){return!e.f()||!e.i()?[]:Array.from(window.document.querySelectorAll(t)).filter(e=>e instanceof HTMLElement)}var n=`open`;function r(t){if(!e.u())throw Error(`Shadow DOM is not supported in this environment`);return t.attachShadow({mode:n})}function i(){return new Promise((t,n)=>{if(!e.i()){n();return}document.readyState===`loading`?document.addEventListener(`readystatechange`,()=>t(),{once:!0}):t()})}function a(e,t){let n=new MutationObserver(r=>{document.contains(e)||(n.disconnect(),t())});n.observe(document.body,{childList:!0,subtree:!0})}var o=`picked-root`,s=`picked-target`,c=`picked-root`;function l(e,n){return[...e,{selector:`${c}[experience-id="${n}"]`,placement:`replace`}].flatMap(e=>{let r=t(e.selector).filter(e=>!f(e,n)&&!p(e,n));return{...e,elements:r}})}function u(e,t,n){return e.flatMap(e=>e.elements.map(r=>h(r,e.placement,t,n)))}function d(e,t){e.classList.add(s),e.classList.add(`${s}-${t}`)}function f(e,t){return t?e.classList.contains(`${s}-${t}`):e.classList.contains(`${s}`)}function p(e,t){return t?e.classList.contains(`${o}-${t}`):e.classList.contains(o)}function m(e,t){let n=document.createElement(`div`);return n.style.display=`block`,n.classList.add(o),n.classList.add(`${o}-${e}`),n.classList.add(`${o}-${t}`),n}function h(e,t,n,r){let i,a=m(n,r);if(e instanceof Document)i=e.body.appendChild(a);else{switch(t){case`replace`:e.replaceWith(a);break;case`before`:e.before(a);break;case`after`:e.after(a);break;case`prepend`:e.prepend(a);break;case`append`:e.append(a);break}i=a}return i}Object.defineProperty(exports,`a`,{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,`i`,{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,`o`,{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,`r`,{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,`s`,{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return u}});
+const e=require("./supports-DBzjGaWD.cjs");function t(t){return!e.f()||!e.i()?[]:Array.from(window.document.querySelectorAll(t)).filter(e=>e instanceof HTMLElement)}var n=`open`;function r(t){if(!e.u())throw Error(`Shadow DOM is not supported in this environment`);return t.attachShadow({mode:n})}function i(){return new Promise((t,n)=>{if(!e.i()){n();return}document.readyState===`loading`?document.addEventListener(`readystatechange`,()=>t(),{once:!0}):t()})}function a(e,t){let n=new MutationObserver(r=>{document.contains(e)||(n.disconnect(),t())});n.observe(document.body,{childList:!0,subtree:!0})}var o=`picked-root`,s=`picked-target`,c=`picked-root`;function l(e,n){return[...e,{selector:`${c}[experience-id="${n}"]`,placement:`replace`}].flatMap(e=>{let r=t(e.selector).filter(e=>!f(e,n)&&!p(e,n));return{...e,elements:r}})}function u(e,t,n){return e.flatMap(e=>e.elements.map(r=>h(r,e.placement,t,n)))}function d(e,t){e.classList.add(s),e.classList.add(`${s}-${t}`)}function f(e,t){return t?e.classList.contains(`${s}-${t}`):e.classList.contains(`${s}`)}function p(e,t){return t?e.classList.contains(`${o}-${t}`):e.classList.contains(o)}function m(e,t){let n=document.createElement(`div`);return n.style.display=`block`,n.classList.add(o),n.classList.add(`${o}-${e}`),n.classList.add(`${o}-${t}`),n}function h(e,t,n,r){let i,a=m(n,r);if(e instanceof Document)i=e.body.appendChild(a);else{switch(t){case`replace`:e.replaceWith(a);break;case`before`:e.before(a);break;case`after`:e.after(a);break;case`prepend`:e.prepend(a);break;case`append`:e.append(a);break}i=a}return i}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return u}});

package/dist/esm/form/index.js

@@ -1,4 +1,4 @@
-import { t as e } from "../../rules-logic-D_CVBuv7.js";
+import { t as e } from "../../rules-logic-HesIUCu6.js";
 import { attach as t, combine as n, createEffect as r, createEvent as i, createStore as a, sample as o, split as s } from "effector";
 //#region src/form/build-responses.ts
 function c(e, t, n) {