picked 0.0.101-next.2 → 0.0.101

package/docs/reference/sdk/plugins/shopify.md

@@ -0,0 +1,109 @@
+---
+type: reference
+layout: docs
+---
+
+# Shopify
+
+`@picked/shopify` connects the Picked client to a Shopify storefront. It adds Shopify
+predicates, writes Picked data to the cart, and gives helpers for the Shopify storefront
+APIs.
+
+```ts
+import { createClient } from 'picked'
+import { shopifyPlugin } from '@picked/shopify/plugins/shopify'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [shopifyPlugin()],
+})
+```
+
+The plugin has no options. The helpers read `window.Shopify` and `window.pickedConfig`.
+The Picked Shopify app puts `window.pickedConfig` on the storefront.
+
+## Predicates
+
+The plugin registers these predicates. Each name starts with `shopify-`.
+
+| Predicate | Returns |
+| --- | --- |
+| `shopify-is-homepage` | `true` on `/`. |
+| `shopify-is-product-page` | `true` when `pickedConfig.product` has a handle. |
+| `shopify-get-product-handle` | The handle of `pickedConfig.product`, or `false`. |
+| `shopify-is-collection-page` | `true` when `pickedConfig.collection` has a handle. |
+| `shopify-get-collection-handle` | The handle of `pickedConfig.collection`, or `false`. |
+| `shopify-is-page` | `true` on `/pages/<handle>`. |
+| `shopify-get-page-handle` | The page handle from the path. |
+| `shopify-is-blog-page` | `true` on `/blogs/<handle>`. |
+| `shopify-get-blog-handle` | The blog handle from the path. |
+| `shopify-is-article-page` | `true` on `/blogs/<blog>/<article>`. |
+| `shopify-get-article-handle` | The article handle from the path. |
+| `shopify-is-app-proxy-page` | `true` on `/a/`, `/apps/`, `/community/` and `/tools/` paths. |
+| `shopify-get-app-proxy-handle` | The first path segment after the app proxy prefix. |
+| `shopify-is-account-page` | `true` on `/account/<path>`. |
+| `shopify-is-login-page` | `true` on `/account/login`. |
+| `shopify-is-register-page` | `true` on `/account/register`. |
+| `shopify-is-cart-page` | `true` on `/cart/<path>`. |
+| `shopify-is-checkout-page` | `true` on `/checkout/<path>`. |
+
+See [Predicates](/reference/sdk/predicates) for how a condition reads a predicate.
+
+## Cart attributes
+
+In a browser with `window.Shopify.analytics`, the plugin writes these cart attributes
+through the AJAX API of the Shopify cart:
+
+| Attribute | Value |
+| --- | --- |
+| `picked.id` | The session ID. |
+| `picked.is_user` | `'true'` or `'false'`. |
+| `picked.features.<feature ID>` | The bucket of each resolved feature. |
+
+The plugin writes the attributes again on the `initialize`, `session`, `user_decide`,
+`feature_decide` and `experience_initialize` events. It then reads the cart back after 2
+seconds. If a different app changed an attribute, the plugin writes it again, up to 3
+times.
+
+On the `session` event, the plugin also publishes `picked:session` with `{ id }` through
+`Shopify.analytics.publish`. A Shopify web pixel can subscribe to this event.
+
+## Storefront data
+
+`@picked/shopify/plugins/shopify` also gives readers for `window.pickedConfig`. Each
+returns `undefined` outside a browser.
+
+| Function | Returns |
+| --- | --- |
+| `getPickedConfig()` | The full `window.pickedConfig` object. |
+| `getPickedConfigCustomer()` | The customer that is logged in. |
+| `getPickedConfigProduct()` | The product of the current page. |
+| `getPickedConfigCollection()` | The collection of the current page. |
+| `getPickedConfigExperiments()` | The experiments of the Picked Shopify app. |
+| `getPickedConfigFeatureExperiments()` | Each enabled experiment as a value for the `features` option of `createClient()`. |
+| `getPickedConfigStorefrontApiToken()` | The public Storefront API token. |
+| `getShopify()` | The `window.Shopify` object. |
+
+## Storefront APIs
+
+| Import | Functions |
+| --- | --- |
+| `@picked/shopify/ajax-api` | `getProduct`, `getProductRecommendations`, `getPredictiveSearch`, `getCart`, `addToCart`, `updateCart`, `changeCart`, `clearCart`, `getShippingRates` |
+| `@picked/shopify/json-api` | `getCollection`, `getCollectionProducts` |
+| `@picked/shopify/storefront-api` | `createStorefrontApiClient`, `getStorefrontApiClient`, `cartDiscountCodesUpdate` |
+| `@picked/shopify/picked-app` | `getProductMetadata`, `getCollectionMetadata` |
+| `@picked/shopify/utils` | `getRequest`, `postRequest` |
+
+Each request goes to the storefront origin, below `Shopify.routes.root`. A response that
+is not `ok` throws an `Error`. The message of the error is the status text.
+
+`createStorefrontApiClient()` needs the Storefront API token in `window.pickedConfig`. It
+throws an `Error` when the token is not there.
+
+The helpers of `@picked/shopify/picked-app` read metafields through the
+`/apps/picked` app proxy of the Picked Shopify app.
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [Predicates](/reference/sdk/predicates)

package/docs/reference/sdk/plugins/window-object.md

@@ -0,0 +1,25 @@
+---
+type: reference
+layout: docs
+---
+
+# Window Object
+
+A plugin to add the Picked client to the window object
+
+## Setup Plugin
+
+```ts
+import { createClient } from 'picked'
+import { windowObjectPlugin } from '@picked/client/plugins/window-object'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [windowObjectPlugin()],
+})
+```
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [How to install the SDK](/how-to/install-the-sdk)

package/docs/reference/sdk/predicates.md

@@ -0,0 +1,43 @@
+---
+type: reference
+layout: docs
+---
+
+# Predicates
+
+A predicate holds reusable condition logic that reads the current state of your
+application. Each predicate is a pure function. It takes a state snapshot, and that
+snapshot holds the responses, the fields, the browser context, and optional
+arguments.
+
+## Use the state snapshot
+
+Each predicate takes a `StateSnapshot` object with these properties:
+
+```ts
+interface StateSnapshot {
+  client: Picked // The Picked client.
+  responses?: Array<{
+    // Every response from the user.
+    fieldId: string
+    value: FieldValue | undefined
+  }>
+  args?: unknown[]
+  fields?: Field[] // Every registered field.
+  location?: Location // The browser location: URL, pathname, search, and more.
+  document?: Document // The browser document object.
+  sessionStorage?: Storage // The browser sessionStorage API.
+  localStorage?: Storage // The browser localStorage API.
+}
+```
+
+:::warning
+In server-side rendering, and in any environment that is not a browser, `location`,
+`document`, `sessionStorage`, and `localStorage` are `undefined`.
+:::
+
+## Related
+
+- [How to write a predicate](/how-to/write-a-predicate)
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  why predicates exist.

package/docs/reference/sdk/react.md

@@ -0,0 +1,61 @@
+---
+type: reference
+layout: docs
+---
+
+# React
+
+`@picked/react` lets the Picked client render React components, and gives hooks and
+components to read the client from React.
+
+| Peer dependency | Version |
+| --- | --- |
+| `react`, `react-dom` | `^18.3.0` or `^19.0.0` |
+| `@picked/client` | The version of your Picked SDK |
+| `effector` | `^23.4.4` |
+
+## Entry points
+
+| Import | Exports |
+| --- | --- |
+| `@picked/react` | `adaptReactComponent`, `isValidAdaptedComponent`, `PickedProvider`, `ExperienceSlot`, `HtmlRender` |
+| `@picked/react/plugins/framework` | `reactFrameworkPlugin` |
+| `@picked/react/hooks` | `usePicked`, `useExperience`, `useStep`, `useStepContent`, `useStepLayoutContent`, `useSetStepContext`, `useFeature`, `useFeatureResult`, `useFeatureEnabled`, `useAction`, `useActionResult`, `useContent`, `useReference`, `useReferences`, `useStoreGlobal`, `useSessionStorage`, `useLocalStorage`, the field hooks, and the context providers |
+| `@picked/react/router` | `StepRouter`, `Step` |
+| `@picked/react/form` | `useForm` |
+| `@picked/react/server` | `renderer`, which renders a React component to HTML on the server |
+
+## Framework plugin
+
+`reactFrameworkPlugin` registers React as a framework of the client. The client then
+renders each React component in a shadow root.
+
+```tsx
+import { createClient } from 'picked'
+import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [reactFrameworkPlugin({ components: {} })],
+})
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `components` | `{ experience?: { component, style? } }` | required | `experience` renders each experience that has no component of its own. |
+| `stylesheets` | `string[]` | none | The URLs of stylesheets to add to each shadow root. |
+| `css` | `string[]` | none | CSS text to add to each shadow root. |
+
+## Components
+
+`adaptReactComponent(component)` makes a React component that the client can render. It
+takes a component, a dynamic import, or a lazy loader. See
+[How to register a component](/how-to/register-a-component).
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk)
+- [Steps](/reference/sdk/steps)
+- [Features](/reference/sdk/features)
+- [Content](/reference/sdk/content)
+- [Rendering and hydration](/reference/sdk/ssr/rendering-and-hydration)

package/docs/reference/sdk/ssr/index.md

@@ -0,0 +1,33 @@
+---
+type: reference
+layout: docs
+---
+
+# Server-Side Rendering
+
+Render a Picked Page on your server so that search engines can read it. Then hydrate
+the page on the client. This page shows the whole shape. The pages after it cover
+each part.
+
+## The server entry point
+
+The server helpers live in a dedicated entry point, so a browser bundle never holds
+them:
+
+```ts
+import { serialize, registerProjectConfig } from '@picked/client/server'
+import type { PickedSnapshot } from '@picked/client/server'
+```
+
+Go to [Server Snapshot](/reference/sdk/ssr/serialize) for the `serialize()` reference. Go to
+[Rendering and Hydration](/reference/sdk/ssr/rendering-and-hydration) to connect React and
+Svelte. Go to [Slots and Placements](/reference/sdk/ssr/slots-and-placements) for how a slot
+chooses an experience. If the SDK is new to you, read
+[Installation](/reference/sdk) first.
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why the snapshot
+  exists.
+- [How to server-render a page](/how-to/server-render-a-page)
+- [Server snapshot](/reference/sdk/ssr/serialize)

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

@@ -0,0 +1,103 @@
+---
+type: reference
+layout: docs
+---
+
+# Rendering and Hydration
+
+Seed a Picked client from the server snapshot, render your slots, and hydrate. This
+page covers React and Svelte.
+
+## React: `PickedProvider`
+
+`PickedProvider` gives a client to each component below it. Its props are a union of
+two modes:
+
+| Props | Mode | Description |
+| --- | --- | --- |
+| `{ options, snapshot? }` | Create | The provider calls `createClient(options)` and hydrates the client from the snapshot. |
+| `{ client, snapshot? }` | Adopt | The provider uses a client that is there already, such as a global one for the whole application. It can also seed that client from the snapshot. |
+
+The provider seeds the client at once, so the server and the first paint on the
+client give the same markup. In the browser the provider calls `client.start()` from
+an effect. `start()` is idempotent, so it changes nothing on a client that already
+started.
+
+```tsx
+import { PickedProvider, ExperienceSlot } from '@picked/react'
+
+<PickedProvider options={options} snapshot={snapshot}>
+  <ExperienceSlot name="page" />
+</PickedProvider>
+```
+
+## Svelte: `setPickedContext`
+
+`setPickedContext` does the same work in the Svelte style. Call it one time at the
+top of the `<script>` block of a component. It takes the same two modes,
+`{ options, snapshot? }` or `{ client, snapshot? }`, and it returns the client.
+
+```svelte
+<script lang="ts">
+  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
+
+  setPickedContext({ options, snapshot })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+## Render the page component
+
+The SDK does not connect content to a component. You own the component that a Page
+renders. Register it under the name that the Page uses. The Page Layout in the dashboard
+points at that same name. The component reads the resolved entry data
+through a 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 `data` object of the entry directly. It returns `null`
+while no content is registered. `getStepContent()` returns a store, and you read it
+with `$content`.
+
+## Related
+
+- [How to server-render a page](/how-to/server-render-a-page) — the full example.
+- [Slots and placements](/reference/sdk/ssr/slots-and-placements)

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

@@ -0,0 +1,80 @@
+---
+type: reference
+layout: docs
+---
+
+# Server Snapshot
+
+`serialize()` finds which experiences match a URL and reads their content on the
+server. It returns a snapshot as plain JSON, and you pass that snapshot to the
+client.
+
+## The `serialize(client, params)` function
+
+```ts
+import { createClient } from 'picked'
+import { serialize } from '@picked/client/server'
+
+const client = createClient(options)
+
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: '/promo' } },
+})
+```
+
+`serialize()` does this. It registers the project configuration on the client at once. It
+evaluates the condition of each experience against `attributes.location`. It reads
+the content for each experience whose steps point at layout content. It removes the
+duplicate content blobs, which it finds by their IDs. It then returns a `PickedSnapshot`.
+
+The content that it reads holds the entries of the steps. It also holds the entries that
+a [reference field](/reference/dashboard/content/models#reference-fields) reaches.
+
+Give `serialize()` one client for each request. It does not support two calls at the
+same time on one client.
+
+```ts
+serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `projectConfig` | `ProjectConfig` | required | The published configuration, or the preview configuration, to register and choose against. |
+| `attributes.location` | `Partial<SerializeLocation>` | none | The URL fields that go into the selection context, such as `pathname`. |
+| `getContent` | `SerializeGetContent` | runtime API | Your own function to read content, in place of the runtime API. |
+| `previewToken` | `string` | none | The SDK sends this with the content request, so that preview content resolves during a preview render. |
+| `timeoutMs` | `number` | `10000` | The limit for each content request. After the limit, the SDK skips that blob and continues. |
+
+`SerializeLocation` carries the URL fields `href`, `pathname`, `search`, `hostname`,
+`origin`, `protocol`, `port`, `host`, and `hash`. Pass only the fields that 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 that the snapshot was chosen against. It is `null` when the version is not known, for example in a preview. |
+| `projectConfig` | The options that the server chose with. They travel to the client, so that the client renders against exactly the same options. |
+| `content` | The content blobs for the chosen experiences, with the duplicates removed. It holds the entries of the steps, and every entry that a reference field reaches. The server render and the first paint in the browser therefore resolve the same pointers. |
+| `conditionResults` | The condition results that the server kept, under a key made from the rule hash. The client then reuses the choice of the server. |
+
+The snapshot is plain JSON. Write it into your HTML response with `JSON.stringify`
+and read it back on the client.
+
+## Related
+
+- [How to server-render a page](/how-to/server-render-a-page)
+- [How to render an unpublished preview](/how-to/render-an-unpublished-preview)
+- [Content](/reference/sdk/content) — how to read a content record in a component.

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

@@ -0,0 +1,113 @@
+---
+type: reference
+layout: docs
+---
+
+# Slots and Placements
+
+A slot is a named mount point. `<ExperienceSlot name="page" />` renders every
+experience that points at that slot and whose condition matches.
+
+## What a slot is
+
+The `name` of a slot points at the `.picked-slot-<name>` selector. So
+`<ExperienceSlot name="page" />` renders every experience with the target selector
+`.picked-slot-page`, when the condition of that experience is active.
+
+The slot reads the active state of each experience from the seeded snapshot. It
+therefore renders at once, both in server-side rendering and at the first paint of
+the hydration.
+
+```tsx
+<ExperienceSlot name="page" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | — | The name of the slot. It points at the `.picked-slot-<name>` selector. |
+| `open` | `'rule' \| 'rendered'` | `'rule'` | What an experience does when its `initializeOpen` is empty. `'rule'` keeps it closed. `'rendered'` opens it. A boolean or a rule in `initializeOpen` has the same result with both values. |
+| `wrap` | `boolean` | `false` | Puts the output of each experience in a wrapper element. See [The wrapper](#the-wrapper). |
+
+The slot reads `open` when it mounts an experience.
+
+## Point an experience at a slot
+
+Set the target selector of the experience to `.picked-slot-<name>`. An experience
+that points at `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The
+name of the slot and the end of the selector must match.
+
+## Placement order
+
+When more than one experience points at the same slot, they render in this placement
+order:
+
+```
+replace -> before -> prepend -> append -> after
+```
+
+`replace` wins. An active experience with the `replace` placement renders alone, and
+it replaces every other match in the slot. In every other case each active experience
+renders, in placement order.
+
+## More than one experience in one slot
+
+The slot collects each experience that points at its selector. It drops each one
+whose condition is not active. It then sorts the rest into placement order. When a `replace`
+experience is among the active ones, only that experience renders. With no active
+`replace`, the slot renders every active experience in the order `before`, `prepend`,
+`append`, `after`.
+
+One Page can therefore take a whole slot with `replace`, while another slot holds
+several experiences that use the other placements. A condition decides which
+experiences are active. See [Conditions](/reference/dashboard/conditions).
+
+## Lifecycle events
+
+The slot sends these events on the event bus of the client for each experience that it
+renders. It sends them only in the browser, and only after the client is ready. The server
+render sends no events.
+
+| Bus event | When it fires | Analytics event |
+| --- | --- | --- |
+| `experience_initialize` | The slot mounts the experience. | `experience_load` |
+| `experience_open` | The experience opens. `open` and `initializeOpen` decide this. | `app_open` |
+| `step_enter` | The flow of an open experience arrives at a step. | `step_enter` |
+| `experience_unmount` | The slot stops rendering the experience. | None |
+
+When the slot stops rendering an experience, the open state of that experience does not
+change. The slot therefore sends no `experience_close`, and the analytics plugin sends no
+`app_close`. After that, the experience sends no events, and its flow stops.
+
+Each time that the slot mounts an experience, the experience starts closed, and `open` and
+`initializeOpen` decide again if it opens. This is also true when the slot mounts the same
+experience again, for example after a React `<Activity>` shows it again.
+
+The flow of an experience continues from its history. When the history of an experience
+already ends at a step, the experience opens at that step and the slot sends no
+`step_enter` for it.
+
+Each analytics event has the page URL at the time that the event fires.
+
+## The wrapper
+
+With `wrap`, the slot puts the output of each experience in one element:
+
+```html
+<div data-picked-experience-id="<experience id>" style="display: contents">
+  <!-- the experience -->
+</div>
+```
+
+The element has no box of its own, so the layout does not change. The element is in the
+document tree, so the selectors `>`, `:first-child`, and `:nth-child()` see it. The
+`data-picked-experience-id` attribute holds the ID of the experience. It is the same on the
+server and in the browser.
+
+Without `wrap`, the slot adds no element.
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why placements
+  have an order.

package/docs/reference/sdk/steps.md

@@ -0,0 +1,86 @@
+---
+type: reference
+layout: docs
+---
+
+# Steps
+
+Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
+`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
+
+## Reach the step context
+
+Inside a `Step` component, or inside any component that a `Step` renders, call
+`getStep()` or `useStep()` to reach the reactive context of the step:
+
+:::code-group
+
+```tsx [React]
+import { useStep, useStoreGlobal } from '@picked/react/hooks'
+
+function ContactForm() {
+  const { step, fields } = useStep()
+  const currentStep = useStoreGlobal(step)
+  const currentFields = useStoreGlobal(fields)
+
+  return (
+    <>
+      <h1>{currentStep.label}</h1>
+
+      {currentFields.map((field) => (
+        <div key={field.id}>
+          <label>{field.label}</label>
+          <input
+            name={field.id}
+            value={field.value ?? ''}
+            onChange={field.onChange}
+            onBlur={field.onBlur}
+          />
+          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
+        </div>
+      ))}
+    </>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStep } from '@picked/svelte/hooks'
+
+  const { step, fields } = getStep()
+</script>
+
+<h1>{$step.label}</h1>
+
+{#each $fields as field}
+  <label>{field.label}</label>
+  <input
+    name={field.id}
+    value={field.value ?? ''}
+    onchange={field.onChange}
+    onblur={field.onBlur}
+  />
+  {#if field.error && field.touched}
+    <p class="error">{field.error.userMessage}</p>
+  {/if}
+{/each}
+```
+
+:::
+
+`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
+properties:
+
+| Property   | Type                                          | Description                                                                    |
+| ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `step`     | `Store<ExperienceStep>`                       | A reactive store that holds the `id` and the `label` of the step                |
+| `fields`   | `Store<FormField[]>`                          | A reactive store of the fields, with their current values, errors, and handlers |
+| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether the router holds this step as the active one                            |
+| `form`     | Object                                        | The handlers for a form submission. See [Forms](#forms).                        |
+
+## Related
+
+- [How to render a step form](/how-to/render-a-step-form)
+- [How to run code on a form submission](/how-to/run-code-on-a-form-submission)
+- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.